photo-sky
Skill4 starsChanged 19 days agoMITView on GitHub
Use when a scene needs a photographic sky that follows a day/night clock and the weather, built from equirectangular sky photos on a camera-following dome (the ATS/ETS2 approach) with TSL on WebGPU. Covers sun-elevation bands, per-day variants, overcast/storm/whiteout and night pools, the photo's sun tracking the clock, crossfades without double-exposed clouds, the ACES inverse, and converting sky photos into dome textures.
In this repository28 other files it gives its agents.
- character-cameraSkill
- character-inputSkill
- character-kitSkill
- character-modelSkill
- character-walkingSkill
- engineered-environmentsSkill
- megacitySkill
- station-maglevSkill
- greenhouseSkill
- pipesSkill
- procedural-geometrySkill
- signageSkill
- indirect-lightingSkill
- lightingSkill
- glassSkill
- interior-mappingSkill
- material-compositionSkill
- metalSkill
- paintSkill
- rustSkill
- tsl-materialsSkill
- waterSkill
- threejs-directorSkill
- card-grassSkill
- far-shadeSkill
- ocean-waterSkill
- snow-weatherSkill
- jolt-drivingSkill
The file
We split this skill into the rules it gives an agent
5 rules. About 0 are common, 3 are distinctive, and 2 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈3
Distinctive · estimate
This author's own choices. Worth a look.
2
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 23
when realistic clouds matter more than clouds that move
- Distinctive: line 24
when the sky is also the environment map (PMREM) for the scene
- Distinctive: line 26
Do not use it when clouds must drift or react, when the camera flies through clouds, or for planets and space.
- Very specific: line 100
Keep camera.far above the dome radius (1700 needs a far plane of 1800 or more).
- Very specific: line 129
Never assign a new texture to
scene.environment: after boot: it rebuilds every lit material, roughly 300 ms.
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Photo Sky
Target: Three.js 0.187.0, three/webgpu and TSL node materials from three/tsl; WebGPU only, no WebGL fallback, no GLSL strings.
Companion files in this folder:
scripts/photo-sky.tsl.js: the sky. Copy it into the project; it imports only fromthree/webgpuandthree/tsl.scripts/convert-sky.mjs+scripts/convert-sky.html: turn 2:1 sky photos into dome textures and measure each photo's sun. Node 22+ and Chrome, no packages.
What it is
A back-faced sphere around the camera with one texture slot per sky photo. Every frame, update() turns the sun direction, the weather and the night into one weight per slot. The shader blends the weighted photos with a cloud-aware crossfade, inverts three's ACES tone map (so the renderer's ACES gives the photo back unchanged), and then runs a grade: horizon haze, a night or overcast wash, and a storm fold toward the fog colour. The dome turns so each photo's sun column follows the clock's azimuth. A per-slot elevation warp moves each photo's sun row toward the clock's elevation. The clipped sun comes back as HDR (about 8), so a PMREM baked from the dome lights the scene from the right direction.
A photo sky costs a fraction of a procedural sky: one to three texture fetches per pixel and no ray march. A procedural dome with a cloud march measured 2.3 to 5 ms; this one is well under 1 ms. Its limits: clouds do not move, and you can only show the light conditions you have photos of.
When to use it
- driving, flying or walking scenes with a day/night clock where the sky should look photographed
- when realistic clouds matter more than clouds that move
- when the sky is also the environment map (PMREM) for the scene
Do not use it when clouds must drift or react, when the camera flies through clouds, or for planets and space. Use a procedural sky for those.
API
import { createPhotoSky, PHOTO_SKY_DEFAULTS, PHOTO_SKY_KNOBS, EXAMPLE_SLOTS, acesInverse, dayHash } from './photo-sky.tsl.js';
const sky = createPhotoSky(options);
// -> { mesh, material, textures, uniforms, slots, knobs, load, setSlotImage, update, bakeGate, needsRebake, bake, state }Options (PHOTO_SKY_DEFAULTS):
slots(EXAMPLE_SLOTS): one row per texture slot,{ file, sunElev, sunClear, exp }.sunElevis the photo's sun elevation in degrees from the conversion log, ornullfor no sun.sunClear(0..1) is how visible the disc is; it feedsskyClear, which gates a lens flare.expis an exposure trim.slotCount(0): number of texture slots. 0 roundsslots.lengthup to a multiple of 4. Spare slots hold 1x1 placeholders and are ready for new pools.bands([[-6, 2], [2.5, 0], [12, 8], [37, 1]]):[elevationDeg, slot]pairs. A slot shows while the sun is above its elevation and below the next band's. Belowbands[0]the night slot shows. Bands depend only on elevation, so they are symmetric about noon: sunrise shows the band-0 photo too, which works because dawn and dusk light look the same.roles({ night: 3, aurora: 4, overcast: 5, whiteout: 6, storm: 7, nightOvercast: 9 }): which slot plays each role. Omit a role or set it to -1 for none. A missing weather slot falls back to whichever weather slot exists, and a missingnightOvercastfalls back tonight.pools({}): per-day variants,{ slot: [row, row, ...] }. Each game day pickspool[dayHash(day, 31 + slot) % n].basePath(''),loadImage(ImageLoader +decode()): where files come from and how they are loaded.radius(1700),segments([48, 24]),anisotropy(8),placeholder('#8fa3b8').hazeColor(0xd7dee6): the default grade's target colour. Copyscene.fog.colorintosky.uniforms.hazeColor.valueevery frame.grade(null):(lin, ctx) => vec3replaces the default grade (see below).knobs({}): overrides forPHOTO_SKY_KNOBS.
Knobs (sky.knobs, read on every update(), safe to change live):
fadeDeg4: half-width of a band crossfade, in degrees of sun elevation. It is capped at 45% of the narrower neighbouring band, so short bands (dawn and dusk are 8 to 10 deg) still reach full weight.fadeSharp4: the cloud-aware blend. 0 is a plain dissolve; 8 is harder.warp1,warpMax2.2,warpTop80: the elevation warp (see below).storm0.85,overFold0.1,nightFold0.3: the storm fold toward the haze colour, and how much of it remains by day and at night once a weather photo carries the deck.nightHaze0.15,stormHaze0.1,hazeEase0.8/s: the whole-dome wash. A full wash erases the night photo.weatherFade120 s,auroraFade60 s,rainPick0.3,brightPick0.3: the weather and aurora crossfades.exposureRef0.86: the clear-dayrenderer.toneMappingExposurethe photos are matched to.horizonBand0.22,horizonHaze0.95: belowdir.y0.22 the horizon converges to the haze colour, so fogged terrain never stands out as a silhouette against the sky.pin-1: a slot index from 0 up shows that one photo alone, for inspection.rebakeSunY0.06,rebakeWeight0.25,rebakeEvery1.5 s: the PMREM re-bake rule.
Per frame:
const { skyClear, weights } = sky.update({
dt, sunDir, // seconds; normalised direction TO the sun (y up)
overcast, rain, bright,// 0..1 eased weather scalars (see Integration)
aurora, // 0..1 target; the caller decides when an aurora night happens
day, // integer game day: drives the per-day variant picks
dayFrac | azimuth, // optional: azimuth = dayFrac x 2pi or radians; default atan2(sunDir.z, sunDir.x)
nightShare, // optional override of the night weight (default: 1 - band 0's ramp)
exposure, // optional live renderer.toneMappingExposure (default knobs.exposureRef)
camera, // optional: copies its position into the dome
});Other members: load(day) loads every slot with the day's pool picks; await it before the first bake. setSlotImage(i, img, row?) swaps a slot's image in place. bakeGate(on) switches bake mode. needsRebake() reports whether the environment needs a re-bake. bake(pmrem, { renderTarget, sigma 0.04, near, far, size }) renders the dome alone into a PMREM. uniforms.imgSunDir is where the photo actually draws its sun; aim a flare or glare at it.
How it works
Display-space blend, then an exact ACES inverse. The photos are tone-mapped JPGs: display-referred, with the sun clipped at 1. Sampling them as sRGB textures gives display-linear values. The shader blends in that space, then solves three's RRTAndODTFit quadratic for its positive root, with both ACES matrices inverted on the CPU. The input is clamped to 0.985 first, so a clipped sun returns as about 8 and the PMREM gets a real sun. The result is multiplied by 0.6 / exposure, because three's ACES scales by exposure / 0.6 before the curve. The renderer must use THREE.ACESFilmicToneMapping; any other curve shifts every colour.
Rotation. The converter puts each photo's sun at column 0.5. The shader samples u = fract(atan(z, x) / 2pi + 0.5 + rotU) with rotU = -azimuth / 2pi, so column 0.5 sits on the sun azimuth and column 0 sits on its antipode. That is why night photos are rotated so their moon sits at column 0: a moon light that rides the sun's antipode then matches the moon in the photo.
Elevation warp. For each slot, warpV is piecewise linear in elevation and keeps the horizon (0) and the zenith (90 deg) fixed. It moves the photo's sun row eI to a target eT. eT is the clock's elevation, clamped to [eI / warpMax, min(warpTop, eI x warpMax)] so the clouds never stretch more than 2.2x. Each band boundary sits where the warped suns of the two photos meet. With the example photos: dusk 1.0 x 2.2 meets dawn 5.6 / 2.2 at 2.5 deg, dawn 5.6 x 2.2 meets mid 25.8 / 2.2 at 12 deg, and mid 25.8 x 2.2 is above 37, which is above day 52.8 / 2.2. So one sun climbs continuously through every crossfade.
Seam-free mips. At the atan wrap, fract jumps by 1 between neighbouring pixels. Automatic derivatives see that jump and pick the smallest mip, which draws a one-pixel seam line. The shader computes the azimuth derivative analytically, (x dz - z dx) / (x^2 + z^2) / 2pi, takes dFdx/dFdy of the warped v, and samples with .grad(gx, gy).
Cloud-aware crossfade. A linear dissolve of two cloud photos shows every cloud half-transparent mid-fade, like a double exposure. Each slot's weight is multiplied by exp(fadeSharp x cloudiness), where cloudiness is luminance x (1 - saturation), and the weights are renormalised. Wherever either photo has a cloud, that photo wins and the cloud stays opaque, while clear sky still dissolves.
Weights. For band k, ab[k] is a ramp of the sun elevation around bands[k][0], and the band's weight is ab[k] - ab[k+1]. The night weight is 1 - ab[0]. Weather: overK eases toward overcast over weatherFade and moves the day share onto one weather photo. The pick is an eased one-hot: rain above 0.3 picks the storm photo, bright above 0.3 the whiteout, otherwise overcast. Because the pick eases too, a change of weather type is also a crossfade. The weather photos are day-lit, so they take only the day share; the night share under weather goes to the nightOvercast slot. aurora splits the clear night share between the night and aurora photos. Slots with zero weight skip their fetch.
Per-day variants. A pooled slot's image is swapped in place, into the same Texture, only while both its weight and its band weight are 0. The day photo therefore changes at night and the dusk photo by day, and nothing pops. Each band costs one 4096x1024 upload per day.
Grade and gate. The default grade mixes toward hazeColor by max(haze, horizonBand x 0.95), then applies the storm fold, then uses the haze colour below the horizon. ctx gives a custom grade { dir, gate, haze, hazeColor, horizonBand, storm, imgSunDir, defaultGrade }. Wrap ctx.defaultGrade(lin) to add a tint, for example an event colour multiplied by ctx.gate. Anything with HDR, a tint or weather must be multiplied by gate. bakeGate(true) sets the gate to 0, which caps the sky at bakeCap and drops the wash and the fold, so the PMREM holds only the plain photo blend and re-bakes never make the lighting jump.
Integration
renderer.toneMapping = THREE.ACESFilmicToneMapping. Set the basetoneMappingExposureand use the same value asknobs.exposureRef.- Convert the photos (below) and fill the
slotstable fromsky-stats.json. Setbandsfrom the measuredsunElevvalues using the warp rule above. const sky = createPhotoSky({ slots, pools, basePath: 'assets/sky/' }); scene.add(sky.mesh); await sky.load(day);- Keep
camera.farabove the dome radius (1700 needs a far plane of 1800 or more). Setsky.mesh.layersif mirrors or reflection passes should see the sky. - Each frame, before rendering:
sky.update({ dt, sunDir, overcast, rain, bright, day, camera }), then copyscene.fog.colorintosky.uniforms.hazeColor.value. Easeovercastfirst, about 30 s toward the target; the photo swap eases again overweatherFade. - PMREM: on the first bake
rt = sky.bake(pmrem)andscene.environment = rt.textureonce. After that, callif (sky.needsRebake() && scene.environmentIntensity > 0.01) sky.bake(pmrem, { renderTarget: rt }). Always bake into the same render target. - Lens flare: multiply its strength by
skyClearand aim it atuniforms.imgSunDir, where the photo draws its sun. - Light colour does not come from the photos. Drive the sun light's tint from elevation, for example
(1, 0.55 + 0.42k, 0.28 + 0.64k)withk = smoothstep(sunY, 0, 0.35), lerped toward white byovercast x 0.5. Pull the fog toward an amber colour at dawn and dusk so the haze matches the photos.
Converting photos
node convert-sky.mjs list.json out/ reads [{ name, src, night, moon, sunCol, sunRow, shiftPx }], where src is relative to the list file. Add --width 4096 --quality 0.9, --chrome <path>, or --keep to view the result in a browser and download by hand. Per photo it:
- takes the top half of the 2:1 tone-mapped image, so 4096x2048 becomes 4096x1024. The dome never shows below the horizon.
- finds the sun: the circular-mean centroid of clipped-white pixels (every channel at least 250, more than 8 pixels). A veiled sun with no clipped disc falls back to the brightest 33x33 box, which can be off by about 10 deg; pass
sunCol/sunRowwhen it is wrong. - rotates the image so the sun sits at column 0.5. For a night photo with
moon: true, it rotates the brightest box (the moon) onto column 0. - copies row 1015 over rows 1016 to 1023, which removes the anti-aliased ground edge.
- encodes WebP at 0.9 and logs
sunElevDeg = 90 - (row + 0.5) x 180 / 2048, which is90 - (row + 0.5) x 90 / Hon the cropped image. That value goes in the slot'ssunElev.
HDR sources (Poly Haven .hdr) must be tone-mapped to a display PNG first. The example used Reinhard plus sRGB, with the exposure chosen so the sky half's mean display luminance is about 0.3. Low-contrast decks also got a contrast boost of 1.7 around that mean.
Example sources, all CC0. The measured elevations are examples only; measure your own. ambientCG: MorningSkyHDRI007B (dawn, 5.6 deg), DaySkyHDRI040B (day, 52.8), EveningSkyHDRI046B (dusk, 1.0), DaySkyHDRI069B (mid, 25.8), DaySkyHDRI058B / 027B / 001B / 055B (day variants, 44.8 / 54.0 / 57.5 / 41.2), MorningSkyHDRI011B / 014B and EveningSkyHDRI030B / 032B (dawn variants, 3.5 / 4.9 / 7.9 / 6.2), EveningSkyHDRI044B / 041B (dusk variants, 1.4 / 2.1), EveningSkyHDRI039B (textured overcast), DaySkyHDRI068B (whiteout), DaySkyHDRI061B (storm deck), NightSkyHDRI015 (stars and Milky Way), NightSkyHDRI007 / 004 (aurora; 004 has a moon), NightSkyHDRI016B (misty night). Poly Haven: kloppenheim_07_puresky (moonlit overcast night, exposure trim 0.55). Download pattern: https://dl.polyhaven.org/file/ph-assets/HDRIs/hdr/4k/<id>_4k.hdr. ambientCG has no cloudy night skies; Poly Haven does.
Pitfalls
- WGSL branch scoping. A TSL node first used inside an
Ifis declared in that branch. Every later slot then samples an unassigneduand draws concentric rings. Declare everything shared across slots (u, its derivatives,e) with.toVar()before the firstIf. TakedFdx/dFdyoutside theIftoo, because derivatives need uniform control flow. - Two suns. Photos whose suns sit at very different elevations, crossfaded at one boundary, show two suns. Add a mid-elevation photo and place the boundaries where the warped suns meet.
warpMaxabove about 2.5 visibly stretches the clouds. - Featureless overcast reads as fog, not sky. Pick a textured deck with no blue gaps, and keep
stormHazeandoverFoldlow (0.1): the photo carries the deck, and the wash is only a veil. - Starry sky in the rain. Day-lit overcast photos cannot take the night share. Use a separate night-overcast slot, and trim its
exp(0.4 to 0.55) so it sits darker than the mid-grey rain fog.nightFold0.3 makes the horizon meet that fog. - A drawn moon disc on top of a moonlit photo gives two moons. Rotate the photo so its moon is on the antipode column, and draw no disc.
- Exposure trims per slot. Match brightness between pool variants with
exp: scale by the ratio of mean luminances, for example 0.55 x 77/103 = 0.42. - Per-frame arrays. The weight arrays are allocated once and
.fill(0)every frame. Code that adds to them with+=without clearing them first accumulates forever. - Never assign a new texture to
scene.environmentafter boot: it rebuilds every lit material, roughly 300 ms. Bake into the same render target. - The bake position.
bake()passesmesh.positiontofromScene. A cube camera at the origin with the dome kilometres away renders outside the dome. - Depth. Depth-testing the dome slices distant terrain. Keep
depthTestanddepthWriteoff andrenderOrderat -1. - Texture slots. WGSL allows 16 sampled textures per stage. 12 slots is a comfortable ceiling; past 16, merge roles.
Tuning by eye
Pin a slot (knobs.pin = i) to judge one photo alone, then set it back to -1.
| Symptom | Change |
| clouds look transparent mid-fade | raise fadeSharp (4 to 6) |
| a crossfade looks like a hard switch | lower fadeSharp, or raise fadeDeg |
| two suns during a band fade | move the boundary to where the warped suns meet; check that photo's sunElev |
| clouds stretched near the sun | lower warpMax (2.2 to 1.8) and add a photo between the two bands |
| sky too bright or dark against the world | per-slot exp, not the renderer exposure |
| the horizon shows a line against fogged terrain | raise horizonHaze or horizonBand; copy the fog colour into hazeColor every frame |
| under weather the deck is hidden by grey | lower stormHaze and overFold |
| the night deck is paler than the rain fog | lower the night-overcast exp, raise nightFold |
| lighting jumps when weather arrives | the bake picked up the fold: check bakeGate; lower rebakeWeight |
| a faint glow beside the sun at dawn | the photo's sun column came from the brightest box; give sunCol by hand |
Performance
- Each pixel samples only the slots whose weight is above 0: one fetch for most of the day, two during a crossfade, up to three when weather or aurora overlaps a band fade. Every slot still costs a uniform branch and its derivative maths.
- A 4096x1024 WebP is about 45 to 380 KB on disk. In VRAM it is about 22 MB with mips, so 12 slots take about 270 MB. If that is too much, drop to 2048 wide: the sun disc softens, the clouds hold up.
- A re-bake (6 faces plus mips) is throttled to one per
rebakeEveryseconds; a crossfade costs 2 to 3 bakes. Skip bakes at night when environment intensity is 0. - The dome needs no shadow, no fog and no depth. 48x24 segments are enough because the direction is computed per pixel.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

