Advanced · Package v2
Make a day-and-night View.
Turn a sun-free 360° panorama into a full 24-hour Place: moving sunlight and sky atmosphere, stars and the Moon at night, graded terrain, and an optional full-frame night panorama that blends in after sunset.
Needs Locus 1.4.9 – 1.4.11 or later · Complete Package v2Choose your approach
Day-and-night Views build on environment.sunPath inside a complete Package v2 archive (the flat compatibility view.json ZIP does not support these fields). The manifest below follows Chalk Dune Dawn (destination.chalk-dune-dawn 1.4.0), a 12K gypsum-dunes View pairing full-frame day and night panoramas, procedural clear sky, stars/Milky Way, and sun-lit 3D midground dunes.
destination.chalk-dune-dawn-1.4.0.locusplace (123.9 MB ZIP under the Locus Example License; also listed in place-examples.json). Needs Locus 1.4.10 / 1.5.0 or later and joins the public Gallery once Locus 1.5.0 is live on the App Store.| Approach | Minimum App | What you author |
|---|---|---|
Atmosphere + graded land (daySky, panoramaGrade, light) | 1.4.9 | One sun-free daytime panorama, a sky.mask separating sky from foreground, plus elevation stops that tint the painted land and drive Room sunlight. |
Full-frame day/night panorama pair (+ panoramaBlend) | 1.4.10 | Adds an aligned full-frame night panorama and astc-6x6-srgb KTX1 gpuTextures v2 sidecars for both panoramas so mountains, snow, or distant shorelines shift to real night lighting. |
With computed shore or media.dayNight | 1.4.11 | Lets a computed surf beach or video region maps follow the same day/night blend. |
sky and daySky are part of the contract. In the current Package v2 specification, panoramaBlend requires both environment.sunPath.daySky and root sky (with sky.mask and stars or moon). White pixels in sky.mask show the rendered day atmosphere and night stars/Milky Way; black pixels show your blended day and night panorama images.1 · Prepare
Prepare the images and masks
- Daytime panorama (
panorama.path): A 2:1 equirectangular JPEG or PNG (for example8192×4096or12288×6144), lit for clear daylight and completely free of a painted sun or sun glare. - Sun-free Room lighting image (
environment.imageBasedLight): A separate 2:1 JPEG or PNG (1024×512recommended), also free of a painted sun. - Sky mask (
sky.mask): A 2:1 8-bit grayscale PNG (PNG colour type 0) aligned to the panorama. Paint the open sky white (255) and land, trees, and buildings black (0), with clean anti-aliased edges along horizons and branches. - Optional sun-disc mask (
environment.sunPath.disc.skyMask): A 2:1 8-bit grayscale PNG (max width4096) where white admits the moving solar disc behind foreground edges. - Aligned night panorama (
panoramaBlend.path, for 1.4.10+): A separate 2:1 JPEG or PNG with the exact same pixel width and height aspanorama.path, keeping the identical horizon, mountains, and structures under night relighting. - ASTC GPU sidecars (
gpuTexturesv2, required forpanoramaBlend): Convert bothpanorama.pathandpanoramaBlend.pathtoastc-6x6-srgbKTX1 files (.ktx) with full mipmaps and repeating horizontal wrap. Record each file’ssourceSHA256, dimensions, andmipmapLevels. Legacy singulargpuTextureis rejected whenpanoramaBlendis present.
sky.mask completely black (0) while keeping root sky and daySky declared as required. Because black in sky.mask keeps your panoramas opaque, Locus hides the rendered blue sky, stars, and Moon while preserving the 24-hour clock, Edit View Sun Position scrubbing, panoramaBlend transitions, panoramaGrade, and dynamic Room/midground lighting. Omit environment.sunPath.disc (or pass the all-black mask to disc.skyMask) to hide the solar disc and glare as well, or supply a separate white-sky disc.skyMask if you still want the moving sun disc.2 · Manifest
Write destination.json and provenance
Set minimumAppVersion in locusplace.json to "1.4.9" (without panoramaBlend), "1.4.10" (with panoramaBlend), or "1.4.11" (when pairing panoramaBlend with shore or media.dayNight).
In destination.json, every sunPath View must set "sunFreeSky": true and include a "sun-free-sky" component in 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 · Calibrate
Tune elevation stops and blend thresholds
daySky:haze(0...1, default0.3) raises aerosol glow near the horizon and sun;exposure(0.25...4, default1) scales the day-sky adaptation curve.panoramaGrade.stops: 2 to 16 stops with strictly increasingelevationDegrees(-90...90) and linear RGBcolormultipliers (0...4). Use it to dim and warm painted terrain at sunrise/sunset before the night panorama takes over.light.stops: 2 to 16 stops driving the Room’s directional sun (color0...16multiplyingpeakIlluminanceLux) and Room/glass IBL exposure (ambientEV-6...6, default0). Add"midground": truewhen the View also carries a 3Dmidground.pathmodel that should receive the same directional sunlight.panoramaBlend: Cross-fades smoothly frompanorama.pathat or abovedayElevationDegrees(default-1) topanoramaBlend.pathat or belownightElevationDegrees(default-12; both in-18...10withnight < day), tinted by linear RGBnightGrade(0...4).
4 · Verify
Pack, validate, and inspect across hours
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.locusplaceThe validator checks every manifest constraint, verifies both gpuTextures v2 KTX1 headers and SHA-256 digests, and runs sun_free_sky_check to catch bright solar discs left in the day panorama or IBL.
- Import on Apple Vision Pro via Places → Import → Import a View → Files and pair the View with a Room.
- Scrub Sun Position in Edit View through morning, noon, golden hour, twilight, and midnight to check horizon silhouettes, Room glass reflections, and painted-to-sky edge masks.
- Check Motion Off / Reduce Motion: confirm the View freezes cleanly at
startHour.
Coexistence rules and limits
- Excluded effects:
daySky,panoramaGrade,light, andpanoramaBlendcannot coexist withclouds,sky.aurora, rootwater,midground.water,midground.flowingWater, or legacy videomedia. - Allowed pairings in 1.4.11+: Computed
shoresurf (locus.view.water.surf.panorama-blend.v1) andmedia.dayNightvideo maps (locus.view.media.day-night.v1, providing per-video 8-bit RGBlightingandemissionPNGs) are supported alongsidepanoramaBlend. - Both panoramas must match dimensions exactly. Even a one-pixel difference between
panorama.pathandpanoramaBlend.pathis rejected.