进阶 · 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将被拒绝。