選擇實現方式

日夜 View 基於 environment.sunPath 的完整 Package v2 歸檔(扁平相容 view.json ZIP 不支援這些欄位)。下方設定基於 白丘晨光(Chalk Dune Dawn) (destination.chalk-dune-dawn 1.4.0),這是一個 12K 白色石膏沙丘 View,結合了全畫幅日夜雙全景圖、程式化晴空、星空與銀河,以及隨太陽受光的 3D 中景沙丘。

下載研究 Chalk Dune Dawn 範例。 下載 destination.chalk-dune-dawn-1.4.0.locusplace (123.9 MB ZIP,依 Locus 範例授權提供;也已收錄於 place-examples.json)。需要 Locus 1.4.10 / 1.5.0 或更新版本,並在 Locus 1.5.0 上架 App Store 後加入公開 Gallery。
方案最低 App 版本需要準備的內容
程式化大氣 + 地形調光 (daySky, panoramaGrade, light)1.4.9一張無太陽的白天全景圖、一張 sky.mask 用於區分天空與前景,外加按太陽高度給繪製地面調色並驅動房間太陽光線的關鍵影格。
全畫幅白天/黑夜雙全景 (+ panoramaBlend)1.4.10增加一張對齊的全畫幅夜間全景圖以及 astc-6x6-srgb KTX1 gpuTextures v2 sidecar,讓山體、雪面或遠岸在夜間真正轉為夜景光照。
配合即時計算的 shore 或 media.dayNight1.4.11讓即時計算的海岸碎浪或影片區域貼圖隨同一套晝夜混合過渡。
為什麼 sky 和 daySky 是規範的必要組成部分。 在目前 Package v2 規範中, panoramaBlend 同時需要 environment.sunPath.daySky 與根層 sky (帶 sky.mask 和 stars 或 moon)。其中 sky.mask 中的白色像素顯示即時算繪的白晝大氣與夜間星空/銀河;黑色像素顯示你混合後的白天與黑夜全景圖像。

1 · 準備

準備圖像與遮罩

使用自己繪製的天空,替代 Locus 的程式化天空。 將 sky.mask 塗成全黑(0),同時保留根層級的 sky 和 daySky 依規定聲明完整。由於黑色在 sky.mask 中表示全景圖完全不透明,Locus 會隱藏程式化算繪的藍天、星空和月亮,同時完整保留 24 小時時鐘、Edit View 太陽位置拖動、 panoramaBlend 過渡、 panoramaGrade、以及 Room/中景的動態光照變化。省略 environment.sunPath.disc (或把全黑遮罩傳給 disc.skyMask)即可同時隱藏太陽圓盤與眩光;如果仍希望在你繪製的天空上顯示移動的太陽圓盤,則單獨提供一張天空部分為白色的 disc.skyMask 。

2 · 清單

編寫 destination.json 與版權聲明

設定 minimumAppVersion 在 locusplace.json 到 "1.4.9" (不帶 panoramaBlend), "1.4.10" (帶 panoramaBlend),或 "1.4.11" (配對 panoramaBlend 與 shore 或 media.dayNight).

在 destination.json,每個 sunPath View 都必須設定 "sunFreeSky": true 並包含一個 "sun-free-sky" 元件於 provenanceDetail:

{
  "formatVersion": 2,
  "id": "destination.chalk-dune-dawn",
  "title": "Chalk Dune Dawn",
  "panorama": {
    "path": "panorama.jpg",
    "projection": "equirectangular",
    "width": 12288,
    "height": 6144,
    "initialYawDegrees": -50
  },
  "thumbnail": "thumbnail.jpg",
  "provenance": "provenance.json",
  "provenanceDetail": {
    "formatVersion": 1,
    "components": [
      {
        "component": "picture",
        "aiGenerated": true,
        "providers": ["Google Gemini", "OpenAI"],
        "credit": "Locus",
        "notes": "Procedural terrain with silhouette-locked horizon detail and night relighting."
      },
      {
        "component": "sun-free-sky",
        "aiGenerated": false,
        "notes": "Azimuth-symmetric clear sky and IBL with no painted sun disc or glare."
      }
    ]
  },
  "sky": {
    "mask": "sky-mask.png",
    "stars": {
      "twilight": {"strength": 0},
      "milkyWay": {"style": "realistic"}
    }
  },
  "midground": {
    "path": "midground.usdz",
    "terrainEntities": ["Terrain_Dunes", "Terrain_Pan"]
  },
  "gpuTextures": [
    {
      "source": "panorama.jpg",
      "path": "panorama.ktx",
      "format": "astc-6x6-srgb",
      "width": 12288,
      "height": 6144,
      "mipmapLevels": 14,
      "sourceSHA256": "e938e8f8c88f868ed39ec39a3c67c60da2e11281b09f59d79a0953cf8e91154d"
    },
    {
      "source": "panorama-night.jpg",
      "path": "panorama-night.ktx",
      "format": "astc-6x6-srgb",
      "width": 12288,
      "height": 6144,
      "mipmapLevels": 14,
      "sourceSHA256": "efc8fda539be7d867b2181cb8a891f61316ba84d9120d31c62bbad5f96a95e57"
    }
  ],
  "environment": {
    "imageBasedLight": "lighting-ibl.jpg",
    "sunPath": {
      "sunFreeSky": true,
      "startHour": 6.35,
      "dayDurationSeconds": 7200,
      "maxElevationDegrees": 55,
      "peakIlluminanceLux": 2900,
      "nightIlluminanceLux": 0,
      "disc": {
        "skyMask": "sun-sky-mask.png",
        "angularSizeDegrees": 0.53,
        "intensity": 1
      },
      "daySky": {"haze": 0.3, "exposure": 1},
      "panoramaGrade": {
        "stops": [
          {"elevationDegrees": -18, "color": [0.015, 0.014, 0.011]},
          {"elevationDegrees": 0,   "color": [0.245, 0.198, 0.145]},
          {"elevationDegrees": 14,  "color": [0.785, 0.588, 0.36]},
          {"elevationDegrees": 55,  "color": [1.225, 1.108, 0.932]}
        ]
      },
      "light": {
        "stops": [
          {"elevationDegrees": -18, "color": [0, 0, 0],        "ambientEV": -2.75},
          {"elevationDegrees": 0,   "color": [1.25, 0.6, 0.18], "ambientEV": 0.2},
          {"elevationDegrees": 14,  "color": [1.38, 0.97, 0.56], "ambientEV": 0.16},
          {"elevationDegrees": 55,  "color": [0.96, 0.92, 0.85], "ambientEV": -0.35}
        ],
        "midground": true
      },
      "panoramaBlend": {
        "path": "panorama-night.jpg",
        "dayElevationDegrees": -1,
        "nightElevationDegrees": -12,
        "nightGrade": [1, 1, 1]
      }
    }
  }
}

3 · 校準

調整太陽高度關鍵影格與混合閾值

4 · 驗證

打包、校驗並檢查不同時間段效果

python3 tools/pack_locusplace.py --current-app-version 1.4.11 \
  /absolute/path/to/MyDayNightView /absolute/path/to/MyDayNightView.locusplace

python3 tools/validate_locusplace.py --current-app-version 1.4.11 \
  /absolute/path/to/MyDayNightView.locusplace

校驗器會檢查每一項清單約束,驗證兩個 gpuTextures v2 的 KTX1 檔頭與 SHA-256 摘要,並執行 sun_free_sky_check 偵測白天全景或 IBL 中殘留的太陽圓盤或強眩光。

  1. 匯入到 Apple Vision Pro 透過 Places → Import → Import a View → Files 並與一個 Room 配對。
  2. 在 Edit View 中拖動 Sun Position 從清晨、正午、黃金時刻、暮光一直拖到午夜,檢查地平線剪影、房間玻璃反射以及地形到天空邊緣的遮罩過渡。
  3. 檢查關閉動態/減少動態: 確認畫面能穩定停留在 startHour.

共存規則與限制