选择实现方式

日夜 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.

共存规则与限制