進階 · Package v2
製作日夜變化 View。
將無太陽的 360° 全景變成完整的 24 小時場所:隨時間移動的太陽與天空大氣、夜間星空與月亮、隨日光調色的地面,以及日落後平滑混合的全畫幅夜間全景。
需要 Locus 1.4.9 – 1.4.11 或更高版本 · 完整 Package v2選擇實現方式
日夜 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.dayNight | 1.4.11 | 讓即時計算的海岸碎浪或影片區域貼圖隨同一套晝夜混合過渡。 |
為什麼
sky 和 daySky 是規範的必要組成部分。 在目前 Package v2 規範中, panoramaBlend 同時需要 environment.sunPath.daySky 與根層 sky (帶 sky.mask 和 stars 或 moon)。其中 sky.mask 中的白色像素顯示即時算繪的白晝大氣與夜間星空/銀河;黑色像素顯示你混合後的白天與黑夜全景圖像。1 · 準備
準備圖像與遮罩
- 白天全景圖(
panorama.path): 2:1 等距柱狀投影 JPEG 或 PNG(例如8192×4096或12288×6144),採用晴朗白天光照,且畫面中完全 不包含畫出的太陽或太陽眩光. - 無太陽的房間光照圖(
environment.imageBasedLight): 單獨的 2:1 JPEG 或 PNG(建議1024×512),同樣不能包含畫出的太陽。 - 天空遮罩(
sky.mask): 與全景對齊的 2:1 8-bit 灰階 PNG(PNG 色彩類型 0)。將開闊天空塗白(255),地面、樹木與建築塗黑(0),地平線與樹枝邊緣保持乾淨的抗鋸齒過渡。 - 可選太陽圓盤遮罩(
environment.sunPath.disc.skyMask): 2:1 8-bit 灰階 PNG(最大寬度4096),白色區域允許移動的太陽圓盤透過前景邊緣顯示。 - 對齊的夜間全景(
panoramaBlend.path,適用於 1.4.10+): 單獨的 2:1 JPEG 或 PNG,需與 完全相同的像素寬高 設為panorama.path,保持完全一致的地平線、山巒與建築,僅做夜間重打光。 - ASTC GPU sidecar(
gpuTexturesv2,使用以下欄位時必須提供:panoramaBlend): 將兩張圖都轉換為panorama.path和panoramaBlend.path到astc-6x6-srgbKTX1 檔案(.ktx),啟用完整 mipmap 與水平循環環繞。記錄每個檔案的sourceSHA256、尺寸和mipmapLevels。舊版單數gpuTexture會被拒絕,當存在panoramaBlend時,舊版單數欄位將被拒絕。
使用自己繪製的天空,替代 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 · 校準
調整太陽高度關鍵影格與混合閾值
daySky:haze(0...1,預設0.3)提高地平線與太陽附近的氣膠輝光;exposure(0.25...4,預設1)縮放白天穹頂的自適應曝光曲線。panoramaGrade.stops: 2 到 16 個關鍵影格,按嚴格遞增的elevationDegrees(-90...90)與線性 RGBcolor乘數(0...4)。用於在夜間全景接管前,讓繪製地形在日出/日落時變暗並染暖色調。light.stops: 2 到 16 個關鍵影格,驅動房間定向太陽光(color0...16,用於乘以peakIlluminanceLux)與房間/玻璃 IBL 曝光(ambientEV-6...6,預設0)。然後加入"midground": true當 View 同時攜帶需要接收相同定向太陽光的 3Dmidground.path模型,使其也能接收相同的定向太陽光照明。panoramaBlend: 在太陽高度panorama.path大於或等於dayElevationDegrees(預設-1)過渡到panoramaBlend.path小於或等於nightElevationDegrees(預設-12;兩者均需在-18...10與night < day),並乘以線性 RGBnightGrade(0...4).
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 中殘留的太陽圓盤或強眩光。
- 匯入到 Apple Vision Pro 透過 Places → Import → Import a View → Files 並與一個 Room 配對。
- 在 Edit View 中拖動 Sun Position 從清晨、正午、黃金時刻、暮光一直拖到午夜,檢查地平線剪影、房間玻璃反射以及地形到天空邊緣的遮罩過渡。
- 檢查關閉動態/減少動態: 確認畫面能穩定停留在
startHour.
共存規則與限制
- 互斥效果:
daySky,panoramaGrade,light,以及panoramaBlend不能與以下欄位共存:clouds,sky.aurora、根層water,midground.water,midground.flowingWater或舊版影片media. - 1.4.11+ 支援的組合: 即時計算
shore海岸碎浪(locus.view.water.surf.panorama-blend.v1)和media.dayNight影片貼圖(locus.view.media.day-night.v1,為每個影片提供 8-bit RGBlighting和emissionPNG 貼圖)可與以下項目搭配使用:panoramaBlend. - 兩張全景圖的尺寸必須完全一致。 哪怕兩張圖相差 1 個像素,即
panorama.path和panoramaBlend.path將被拒絕。