Repository navigation
Description
Status: approved
Part of #3125.
TL;DR
Goal: TrailView reads the snow of every date from one date-free archive, snow, and a date change reads no snow tile.
Problem: TrailView opens one of 46 band archives for the date. A date in another band opens another archive and reads the snow of the whole view again. #3125 has the rest.
Decision: GroundSource opens the layer snow once, with the other archives, and checks snow_format 1. The ground worker decodes a snow tile to the first and the last band of the run of each pixel. snowState gives snow where the run holds the band of the date. The ruleset value snow_share goes, and the browser tests name the layer snow.
Rejected: see #3125
Systems: trailview, data-registry, device-map-builder
Contracts: none (sub-issue A writes the formats into specs/planner-snow-tiles.md and specs/trailview-tiles.md)
Size: M (3 systems, no contract change of its own, about 300 changed lines)
The formats are in the section "The formats" of #3125. This issue does not copy them.
Facts
- TrailView opens the archive of one band. On the branch of obc data: the prepared source snow (format 1), and planner/snow bakes from it #2937,
GroundSource.open(config, date, stop)inground.tsopenstrailview-snow-NNof the band ofdate(snowBand,snowName,snowSource).pagesopens the archive of another band when the date moves to it (snowDays). A band that does not open opens again on the next load. - The ancestor rule is already in place. On the same branch,
snowBodyreads the nearest ancestor of a missing snow tile, down to zoom 7 (SNOW_COARSE). The epic keeps this rule forsnow. opentakes the date only for the band.TrailView.startinengine.tspassesview.date. No other part ofGroundSourcereads it.- The format check reads only
trailview_format.openedinground.tscomparestrailview_formatwithFORMATS[layer]. Thesnowarchive hassnow_format1. - The worker keeps one byte of a snow tile.
decodeinground-worker.tskeeps the red byte of each pixel (channels: 1).straightPixelsgives the RGBA bytes as the WebP stores them. - Both caches are date-free. The worker keeps decoded tiles by
key, which issnow/z/x/ywith no band.GroundSourcekeeps the tile bodies of each archive up to 16 MiB (BODIES). So a date-free tile serves each date from these caches. - The snow page has four bytes.
groundPagesinground-pages.tswrites the result ofsnowStateinto bytes 0, 1 and 3, and the satellite's snow mark into byte 2.ground.wgslreads bytes 0, 1 and 2 ofsnow_in. sharesalso counts the regions.regionAtingroundPagesusesdate.shares.lengthas the number of regions of the rules. A region code at or above it is the world. So withoutshares, the job needs the number of regions.- The date key holds more than the snow.
GroundPages.setDateinpages.tsmakes the key${quarters}/${weight.toFixed(3)}/${snowIndex}.weightis the weight of the second quarter (mosaicsAtinrules.ts). It changes by about 0.011 per day. snow_shareis set once and read nowhere. Onlyworld.jsonsets it, to 0.5.packRulesinrules.tswrites it into the third value ofSLOT.terrain, which no shader reads. The ruleset schema intools/trailview/rules.pyrefuses an unknown key, so the key leaves the schema andworld.jsontogether.- The browser tests name the 46 bands.
groundLayersinharness.jsmapstrailview-snow-NNtosnow-days/NN.pmtiles.buildPageinlink.mjslists the 46 names. The decode test insmoke.test.jsposts a job withsnowIndexandshares. The TrailView README says that--ground DIRservesDIR/snow-days/<band>.pmtiles.
Plan
builder/web/src/lib/trailview/stream/ground.ts:NAMESgetssnow: 'snow'.FORMATSgives each layer its metadata key and its value:snow_format1 forsnow,trailview_formatfor the others.openedchecks that key.GroundSource.open(config, stop)losesdate. It starts to opensnowwith the other archives. The fieldsnowholds the promise of the onesnowarchive. When it fails to open,snowArchive()drops it, so the next load opens it again, assnowDaysdoes for a band today. A short network failure at the start then does not cost the snow for the whole session. Asnowarchive with anothersnow_formatis left out.- Delete
SNOW_BANDS,BAND_STEPS,snowBand,snowName,snowSourceandsnowDays.snowCreditstays forattribution. pagesreadssnowBody(this.archives.snow, z, x, y), with the ancestor rule of obc data: the prepared source snow (format 1), and planner/snow bakes from it #2937. It putsregionCount: this.rules.regions.lengthinto the job.
builder/web/src/lib/trailview/engine.ts:TrailView.startcallsGroundSource.open(config, stop.signal).builder/web/src/lib/trailview/stream/ground-worker.ts:GroundJobgetsregionCount: number, the number of regions of the rules.decodegives asnowtile withchannels: 2: the red and the green byte of each pixel, the first and the last band of the run.builder/web/src/lib/trailview/stream/ground-pages.ts:snowBandcomes frombuilder/web/src/lib/planner/layers/snow.ts, where Snow C. Planner: 6 classes from snow and snow-levels, and the route features from snow-seasons #3128 adds it besideseasonDay. TrailView already importsseasonDayfrom there, so the band rule has one home.GroundDateis{ weight: number; band: number }, withoutsnowIndexandshares.GroundInputsgetsregionCount: number, the number of regions of the rules.regionAtcompares the region code with it.snowState(snow: Raster, band: number): [Float32Array, Float32Array]gives snow where first ≤ band ≤ last, and data where the first byte is not 255. Bytes 253 and 255 are above band 45, so they give no snow.groundPageslosesregionOfand leaves byte 3 of the snow page at 0. The comments ofGroundPageandsnowStatelink thesnowformat ofspecs/planner-snow-tiles.md.
builder/web/src/lib/trailview/ground/pages.tsGroundPages: the constructor losesshares.setDateputssnowBand(seasonDay(date).index)intotoday.band, and the date key holds the band instead ofsnowIndex. A date change still builds the pages again from the cached tiles, because the key also holds the colour weight, which changes each day. It reads no newsnowtile.loadpasses{ weight, band }.- Delete
snow_share:builder/web/src/lib/trailview/rules/regions.ts: the field of the look.builder/web/src/lib/trailview/ground/rules.tspackRules: the third value ofSLOT.terrainis 0. The comment of the slots losessnow_share.builder/web/src/lib/trailview/ground/ground.ts:NEUTRALlosessnow_share.new GroundPages(...)loses the shares.builder/web/src/lib/trailview/ground/ground.wgsl: the comment ofsnow_insays "snow on the band of the date".data/trailview/regions/world.jsonand thelookschema intools/trailview/rules.py.
- Browser tests and README:
builder/web/tests/browser/trailview/harness.js: the rules fixture losessnow_share.groundLayersmaps the layersnowtosnow.pmtiles, the file thatbox.shwrites.builder/web/tests/browser/trailview/link.mjs:buildPagenamessnow, not the 46 bands.builder/web/tests/browser/trailview/smoke.test.js: the job hasdate: { weight: 0, band: 10 }andregionCount: 3. The decode job also posts a small lossless WebPsnowbody, red the first band and green the last, with a run of bands 5 to 15 in one half and of bands 20 to 30 in the other. The test checks that byte 0 of the snow page is 255 in the first half and 0 in the second, and that byte 1 is 255. So a swap of red and green, or one channel read for two, fails.builder/web/src/lib/trailview/README.md:--ground DIRservesDIR/snow.pmtiles.
- Tests:
stream/ground.test.ts: pages of one tile on two dates in different bands read itssnowtile once. A missing tile reads its ancestor down to zoom 7 (from obc data: the prepared source snow (format 1), and planner/snow bakes from it #2937, withsnow_format1). Asnowarchive withsnow_format2 is left out, and the pages are complete. A release withoutsnowgives complete pages. The test of a band that opens again becomes: asnowarchive that fails to open opens again on the next load.stream/ground-pages.test.ts:snowStateof a run from band 10 to band 20 at the bands 9, 10, 20 and 21; 253 gives data and no snow; 255 gives no data. The test ofgroundPagesuses the newGroundDateandregionCount.ground/rules.test.ts: the fixture losessnow_share.ground/pages.test.ts:new GroundPageswithout the shares.
Files
builder/web/src/lib/trailview/stream/ground.ts: change: opensnowonce, checksnow_format, no bands.builder/web/src/lib/trailview/engine.ts: change:GroundSource.openwithout the date.builder/web/src/lib/trailview/stream/ground-worker.ts: change: two bytes per pixel of asnowtile,regionCountin the job.builder/web/src/lib/trailview/stream/ground-pages.ts: change:GroundDate,regionCount,snowStatefrom the run.builder/web/src/lib/trailview/ground/pages.ts: change: the band in the date key, no shares.builder/web/src/lib/trailview/ground/ground.ts,ground/rules.ts,ground/ground.wgsl(comment),rules/regions.ts: change: nosnow_share.data/trailview/regions/world.json,tools/trailview/rules.py: change: nosnow_share.builder/web/tests/browser/trailview/harness.js,link.mjs,smoke.test.js: change: the layersnow, the new job.builder/web/src/lib/trailview/README.md: change:DIR/snow.pmtiles.builder/web/src/lib/trailview/stream/ground.test.ts,stream/ground-pages.test.ts,ground/rules.test.ts,ground/pages.test.ts: change.
Done when
- From
builder/web:npx vitest run src/lib/trailview,npm run checkandnpm run check:wgslpass. - From
builder/web/tests/browser:npm run test:trailview -- --grep-invert @gpupasses. obc test affected --base origin/developpasses. It selectsweb.builder-vitest,web.trailview-smoke,web.trailview-wgslandpython.trailview.- On a local re-bake (
obc data serve local, thenVITE_PLANNER_CATALOG=URL npm run dev -- --mode trailview), TrailView shows snow in the Alps on 1 March and less snow on 1 July. A date change from 1 March to 1 July, across bands, adds no request for asnowtile. - Depends on obc data: the prepared source snow (format 1), and planner/snow bakes from it #2937 (the ancestor rule
snowBodyand the Facts above are on its branch), on Snow A. Bake: planner/snow writes snow, snow-levels and snow-seasons, and the TrailView snow bake goes #3129, and on Snow C. Planner: 6 classes from snow and snow-levels, and the route features from snow-seasons #3128 forsnowBand. It merges with Snow C. Planner: 6 classes from snow and snow-levels, and the route features from snow-seasons #3128, just before the re-bake of Snow: one date-free snow layer for TrailView and the planner, and small per-year tiles for routes #3125 is published.
Generated by Claude Code
Activity
timohueser commentedon Nov 6, 2026
Deviations of the implementation (branch
claude/snow-b-trailview):NAMESinstream/ground.tsdoes not getsnow. The snow name is a separate constantSNOW. Reason:openopens every entry ofNAMESin one loop, and the constructor puts each intoarchives. The snow has its own path:snowArchive()holds its promise and opens it again after a failure. Asnowentry inNAMESneeds a filter in that loop.snowarchive with anothersnow_formatstays left out for the session. Only an archive that fails to open opens again on the next load. Reason: a wrong format does not change during a session, and a new open on each load costs one header request per ground tile.src/lib/planner/layers/snow.test.tsgets no test ofsnowBand. Reason: Snow C. Planner: 6 classes from snow and snow-levels, and the route features from snow-seasons #3128 owns that file; B adds only the two one-line functions tosnow.ts.Generated by Claude Code
timohueser commentedon Nov 6, 2026
#3172 merged into the integration branch
snow-formats, after an adversarial review (no blocking finding) and green CI. This issue closes whensnow-formatsmerges intodevelopwith the re-bake of #3125. Open steps of Done when: the local re-bake check (snow in the Alps on 1 March, less on 1 July, nosnowrequest on a date change).Generated by Claude Code
timohueser commentedon Nov 6, 2026
Done: #3172 merged into
snow-formats, and #3175 merged it intodevelop(3469850).