Skip to content

Snow B. TrailView: the snow of a date from the run of snow #3127

Closed

Description

@timohueser

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) in ground.ts opens trailview-snow-NN of the band of date (snowBand, snowName, snowSource). pages opens 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, snowBody reads the nearest ancestor of a missing snow tile, down to zoom 7 (SNOW_COARSE). The epic keeps this rule for snow.
  • open takes the date only for the band. TrailView.start in engine.ts passes view.date. No other part of GroundSource reads it.
  • The format check reads only trailview_format. opened in ground.ts compares trailview_format with FORMATS[layer]. The snow archive has snow_format 1.
  • The worker keeps one byte of a snow tile. decode in ground-worker.ts keeps the red byte of each pixel (channels: 1). straightPixels gives the RGBA bytes as the WebP stores them.
  • Both caches are date-free. The worker keeps decoded tiles by key, which is snow/z/x/y with no band. GroundSource keeps 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. groundPages in ground-pages.ts writes the result of snowState into bytes 0, 1 and 3, and the satellite's snow mark into byte 2. ground.wgsl reads bytes 0, 1 and 2 of snow_in.
  • shares also counts the regions. regionAt in groundPages uses date.shares.length as the number of regions of the rules. A region code at or above it is the world. So without shares, the job needs the number of regions.
  • The date key holds more than the snow. GroundPages.setDate in pages.ts makes the key ${quarters}/${weight.toFixed(3)}/${snowIndex}. weight is the weight of the second quarter (mosaicsAt in rules.ts). It changes by about 0.011 per day.
  • snow_share is set once and read nowhere. Only world.json sets it, to 0.5. packRules in rules.ts writes it into the third value of SLOT.terrain, which no shader reads. The ruleset schema in tools/trailview/rules.py refuses an unknown key, so the key leaves the schema and world.json together.
  • The browser tests name the 46 bands. groundLayers in harness.js maps trailview-snow-NN to snow-days/NN.pmtiles. buildPage in link.mjs lists the 46 names. The decode test in smoke.test.js posts a job with snowIndex and shares. The TrailView README says that --ground DIR serves DIR/snow-days/<band>.pmtiles.

Plan

  1. builder/web/src/lib/trailview/stream/ground.ts:
    • NAMES gets snow: 'snow'. FORMATS gives each layer its metadata key and its value: snow_format 1 for snow, trailview_format for the others. opened checks that key.
    • GroundSource.open(config, stop) loses date. It starts to open snow with the other archives. The field snow holds the promise of the one snow archive. When it fails to open, snowArchive() drops it, so the next load opens it again, as snowDays does for a band today. A short network failure at the start then does not cost the snow for the whole session. A snow archive with another snow_format is left out.
    • Delete SNOW_BANDS, BAND_STEPS, snowBand, snowName, snowSource and snowDays. snowCredit stays for attribution.
    • pages reads snowBody(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 puts regionCount: this.rules.regions.length into the job.
  2. builder/web/src/lib/trailview/engine.ts: TrailView.start calls GroundSource.open(config, stop.signal).
  3. builder/web/src/lib/trailview/stream/ground-worker.ts: GroundJob gets regionCount: number, the number of regions of the rules. decode gives a snow tile with channels: 2: the red and the green byte of each pixel, the first and the last band of the run.
  4. builder/web/src/lib/trailview/stream/ground-pages.ts:
    • snowBand comes from builder/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 beside seasonDay. TrailView already imports seasonDay from there, so the band rule has one home.
    • GroundDate is { weight: number; band: number }, without snowIndex and shares.
    • GroundInputs gets regionCount: number, the number of regions of the rules. regionAt compares 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.
    • groundPages loses regionOf and leaves byte 3 of the snow page at 0. The comments of GroundPage and snowState link the snow format of specs/planner-snow-tiles.md.
  5. builder/web/src/lib/trailview/ground/pages.ts GroundPages: the constructor loses shares. setDate puts snowBand(seasonDay(date).index) into today.band, and the date key holds the band instead of snowIndex. 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 new snow tile. load passes { weight, band }.
  6. Delete snow_share:
    • builder/web/src/lib/trailview/rules/regions.ts: the field of the look.
    • builder/web/src/lib/trailview/ground/rules.ts packRules: the third value of SLOT.terrain is 0. The comment of the slots loses snow_share.
    • builder/web/src/lib/trailview/ground/ground.ts: NEUTRAL loses snow_share. new GroundPages(...) loses the shares.
    • builder/web/src/lib/trailview/ground/ground.wgsl: the comment of snow_in says "snow on the band of the date".
    • data/trailview/regions/world.json and the look schema in tools/trailview/rules.py.
  7. Browser tests and README:
    • builder/web/tests/browser/trailview/harness.js: the rules fixture loses snow_share. groundLayers maps the layer snow to snow.pmtiles, the file that box.sh writes.
    • builder/web/tests/browser/trailview/link.mjs: buildPage names snow, not the 46 bands.
    • builder/web/tests/browser/trailview/smoke.test.js: the job has date: { weight: 0, band: 10 } and regionCount: 3. The decode job also posts a small lossless WebP snow body, 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 DIR serves DIR/snow.pmtiles.
  8. Tests:
    • stream/ground.test.ts: pages of one tile on two dates in different bands read its snow tile 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, with snow_format 1). A snow archive with snow_format 2 is left out, and the pages are complete. A release without snow gives complete pages. The test of a band that opens again becomes: a snow archive that fails to open opens again on the next load.
    • stream/ground-pages.test.ts: snowState of 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 of groundPages uses the new GroundDate and regionCount.
    • ground/rules.test.ts: the fixture loses snow_share. ground/pages.test.ts: new GroundPages without the shares.

Files

  • builder/web/src/lib/trailview/stream/ground.ts: change: open snow once, check snow_format, no bands.
  • builder/web/src/lib/trailview/engine.ts: change: GroundSource.open without the date.
  • builder/web/src/lib/trailview/stream/ground-worker.ts: change: two bytes per pixel of a snow tile, regionCount in the job.
  • builder/web/src/lib/trailview/stream/ground-pages.ts: change: GroundDate, regionCount, snowState from 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: no snow_share.
  • data/trailview/regions/world.json, tools/trailview/rules.py: change: no snow_share.
  • builder/web/tests/browser/trailview/harness.js, link.mjs, smoke.test.js: change: the layer snow, 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


Generated by Claude Code

Activity

  1. timohueser commented on Nov 6, 2026

    @timohueser
    OwnerAuthor

    Deviations of the implementation (branch claude/snow-b-trailview):

    • NAMES in stream/ground.ts does not get snow. The snow name is a separate constant SNOW. Reason: open opens every entry of NAMES in one loop, and the constructor puts each into archives. The snow has its own path: snowArchive() holds its promise and opens it again after a failure. A snow entry in NAMES needs a filter in that loop.
    • A snow archive with another snow_format stays 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.ts gets no test of snowBand. 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 to snow.ts.

    Generated by Claude Code

  2. timohueser commented on Nov 6, 2026

    @timohueser
    OwnerAuthor

    #3172 merged into the integration branch snow-formats, after an adversarial review (no blocking finding) and green CI. This issue closes when snow-formats merges into develop with 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, no snow request on a date change).


    Generated by Claude Code

  3. timohueser commented on Nov 6, 2026

    @timohueser
    OwnerAuthor

    Done: #3172 merged into snow-formats, and #3175 merged it into develop (3469850).

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions