Skip to content

Snow C. Planner: 6 classes from snow and snow-levels, and the route features from snow-seasons #3128

Closed

Description

@timohueser

Status: approved
Part of #3125.

TL;DR

Goal: The planner map shows 6 snow classes from the snow and snow-levels archives, and the route strip, the route year chart and the year calendar read at most 25 snow-seasons tiles for a route.
Problem: The planner reads the per-year tiles (18 bytes per pixel) for the map and for the route: about 11 to 13 MB for one screen, and about 140 MB along a 2,000 km route (estimated). See #3125 for the rest.
Decision: The snow layer opens three archives. The map reads one snow tile and one snow-levels tile of the zoom below the map zoom, and colours each pixel by the highest level whose run holds the band of the date while each lower level holds it too. Where one data pixel covers more than one screen pixel (map zoom 13 and above, as a tile of zoom 11 holds the pixels of zoom 12), a level holds the band where its pixels have at least half of the bilinear weight. The route samples read snow-seasons at the finest zoom at which they fall in at most 25 tiles. The strip and the route year chart count the seasons with snow, as today, and colour with the same 6 classes as the map. The year calendar keeps its cells of one season each. The class labels and colours are proposals that the owner approves with the gallery of #3125.
Rejected: see #3125
Systems: route-planning
Contracts: none (sub-issue A writes the formats into specs/planner-snow-tiles.md)
Size: M (1 system, no contract change, about 500 changed lines (estimated), at the limit of S)

The formats of the three archives, the bands, the levels and the reader rules are in "The formats" of #3125. This issue does not repeat them.

Facts

  • The map blends the days of each season. Above the data zoom, paintTile in snow.ts blends the onset and melt-out of the four nearest pixels for each season (blendSeason). steady skips the blend where the four pixels agree. Both read the per-year planes (Planar).
  • The classes have lines at 1/3 and 2/3. shareClass gives FREE, MOSTLY_FREE, MOSTLY_SNOW, SNOW and UNKNOWN. snowClasses gives their swatches from colors. palette in snow-layer.svelte.ts indexes the map colours by class value. The map legend leaves out the first class.
  • obc data: the prepared source snow (format 1), and planner/snow bakes from it #2937 adds the ancestor rule of the per-year tiles. covering in snow.ts reads the nearest ancestor of a missing tile down to MODIS_ZOOM (8). draw reads the tile of zoom min(z, max zoom). sample reads the tiles of the max zoom under all samples with eachTile.
  • The route samples are the vertices of the routed line. PlannerApp.svelte gives sample the RoutingLine of the route (visualRoute). Its coordinates come from calculateLine in routing.ts: one sample for each vertex of the routed legs, with no fixed spacing. profileSamples in profile-data.ts gives the strip one point for each coordinate. A pin on the map samples one coordinate (PlannerApp.svelte, pinSamples).
  • evening.ts does not read snow. nightLow samples only a layer with nights, and the snow layer has none.
  • A layer gets one URL. availableLayers in data-layer.ts creates a layer from one archive name. Archive is 'snow' | 'climate', and PlannerConfig.layers in config.ts is typed by it. registry.ts gives the snow layer the URL of snow.
  • A shared ancestor loads once. openArchive in archive.ts keeps one archive for each URL. decodedTiles keeps each decoded tile by z/x/y in a byte budget, and loads a tile once while it stays cached. eachTile loads 4 tiles at a time.
  • The planner decodes a lossless WebP byte for byte. imagePixels in terrain.ts gives the RGBA pixels without colour conversion.
  • The map tiles are 256 pixels. Raster in raster.ts asks for map tiles of 256 × 256 pixels from the archive's min zoom to max(max zoom, MAX_ZOOM 14).
  • The year calendar colours seasons, not classes. snowChart gives one cell for each season and day step: snow, clear or no data. Only its headline counts the seasons.

Plan

  1. snow.ts, the classes: the class values are 0 none (f = 0), 1 below 1/4, 2 from 1/4 to below 1/2, 3 from 1/2 to below 3/4, 4 from 3/4 to below 1, 5 every year (f = 1), and UNKNOWN 6 for no data. shareClass(snow, known) gives them from c and k. snowClasses(theme) gives 7 swatches. colors keeps today's colours for none, below 1/4, 1/2 to below 3/4 and every year, and gets a colour between the neighbours for 1/4 and for 3/4. Proposed labels, one range each: "No snow in any year", "Snow in fewer than 1 in 4 years", "Snow in 1 in 4 to 1 in 2 years", "Snow in 1 in 2 to 3 in 4 years", "Snow in 3 in 4 years or more, but not every year", "Snow every year". The owner approves the labels and colours with the gallery.
  2. snow.ts, the bands: snowBand(index: number): number is ⌊index ÷ 4⌋, and bandDay(band: number): number is min(4 band + 2, 182). snowMeta checks snow_format 1 instead of step_days.
  3. snow.ts, the runs: a new type Runs { first: Uint8Array; last: Uint8Array } holds the first and the last band of one level for the 512 × 512 pixels of a tile. A new function levelClass(levels: Runs[], i: number, band: number): number gives the class of pixel i: the number of levels, from any up, that hold the band without a gap; UNKNOWN where first of the half level is 255. levels is in the order any, quarter, half, three quarters, every.
  4. snow.ts, paintTile(words, levels: Runs[] | undefined, band, parts, x, y, palette): the map tile is part (x, y) of parts × parts parts of the 512-pixel tile. With parts 1 (map zoom 0), each screen pixel takes the nearest data pixel, so the tile shows at half size. With parts 2, each screen pixel is one data pixel. With more parts, a level holds the band at a screen pixel when the pixels of the four nearest whose run holds it have at least half of the bilinear weight, and the hatch is where pixels with 255 have more than half. Delete blendSeason and steady. A missing tile is no data, as today.
  5. snow.ts, the samples: Every count of the snow on the date uses the band day bandDay(snowBand(index)), as the map does: snowClass(p: Planar, i, band) for the strip, the headline of snowYear (clearOn) and the headline of snowChart. So on 28 February (day step 89, band 22, band day 90) all three count day step 90. snowYear keeps its columns of day steps and colours them with the 6 classes. snowChart keeps its cells of one season each and one day step each: snow, clear or no data. routeSeasons stays.
  6. snow.ts, the route zoom: a new function routeZoom(coordinates: Coordinate[], minZoom: number, maxZoom: number): number gives the finest zoom, at most maxZoom, at which the coordinates fall in at most 25 tiles (ROUTE_TILES); else minZoom. It counts the distinct x/y of worldPixel(coordinate, 2 ** zoom), from maxZoom down. A new function seasonsTile(tile, z, x, y) reads tile z/x/y, and where the archive lacks it and z is 11 or more, the ancestor of zoom 10. It returns { data, zoom }, as covering does. covering stops at zoom 7 instead of MODIS_ZOOM 8, and only snow and snow-levels use it.
  7. snow-layer.svelte.ts, the archives: the constructor takes the three URLs. A Decoding for snow and snow-levels splits the tile body into images (the length of each is 8 + the RIFF size in bytes 4 to 7), decodes each with imagePixels, and keeps red as first and green as last. It throws when the image count is not 1 for snow and 4 for snow-levels, or when an image is not 512 × 512. The Decoding of snow-seasons checks a body of 2 × seasons × 4,096 bytes, with the season count of the snow-seasons metadata, which also gives the Planar of the samples. open opens each archive once. The layer's meta (credit, resolution, first season) comes from snow. The decoded-tile budgets: snow 32 MiB (a tile is 512 KiB decoded), snow-levels 64 MiB (2 MiB a tile), snow-seasons 16 MiB (about 80 KiB a tile for 10 seasons).
  8. snow-layer.svelte.ts, draw: the data zoom d is min(max(z − 1, 0), the max zoom of snow). It reads covering of tile d/⌊x ÷ 2^(z − d)⌋/⌊y ÷ 2^(z − d)⌋ in snow, then the snow-levels tile at the zoom that covering found, so the levels line up with the half level and a missing tile costs no second search. Where snow-levels lacks that tile, the map tile is no data. It calls paintTile with parts 2^(z − zoom of the tile found) and the levels in table order. palette gets 7 colours. The legend leaves out "none", as today.
  9. snow-layer.svelte.ts, sample: it takes routeZoom of line.coordinates with the min and max zoom of snow-seasons, groups the samples by the 64-pixel tile of that zoom with eachTile, and reads each tile with seasonsTile. A sample takes the pixel ⌊worldPixel(coordinate, 64 × 2^zoom)⌋ mod 64 of the tile found, with the zoom of that tile. A pin and a single point read one tile of the max zoom with the same code. strip.values passes snowBand of the date to snowClass.
  10. data-layer.ts: Archive gets 'snow-levels' and 'snow-seasons'. An entry of layerRegistry names a list of archives (archives: Archive[]) and has create(urls: Record<Archive, string>). availableLayers creates a layer only when the config has every archive of its list. registry.ts: the climate entry lists climate, and the snow entry lists snow, snow-levels and snow-seasons. data-layer.test.ts: a release without snow-seasons shows no snow layer.
  11. Tests in snow.test.ts: the class of a pixel from its runs, also when the runs do not nest; a class border above the data zoom (instead of the blend test); routeZoom of a long line at 25 tiles, and one zoom coarser when the line grows past 25 tiles; seasonsTile reads the zoom 10 ancestor of a missing tile; covering stops at zoom 7; the 6 classes of snowClass and snowYear.

Files

  • builder/web/src/lib/planner/layers/snow.ts: change: the 6 classes, the bands, the runs, paintTile, routeZoom, seasonsTile, covering; delete blendSeason and steady.
  • builder/web/src/lib/planner/layers/snow-layer.svelte.ts: change: three archives, their decodings, draw, sample, the palette.
  • builder/web/src/lib/planner/layers/registry.ts: change: the three URLs of the snow layer.
  • builder/web/src/lib/planner/layers/data-layer.ts, builder/web/src/lib/planner/layers/data-layer.test.ts: change: Archive names snow-levels and snow-seasons; a layer lists its archives.
  • builder/web/tests/browser/planner/config.json: change: the URLs of snow-levels and snow-seasons, for the suite web.planner-requests.
  • builder/web/src/lib/planner/layers/snow.test.ts: change: the tests of step 11.

Done when


Generated by Claude Code

Activity

  1. timohueser commented on Nov 6, 2026

    @timohueser
    OwnerAuthor

    The algorithm of levelClass and paintTile

    I write this before the code. The steps of the Plan do not change.

    levelClass(levels, i, band)

    levels holds the 5 runs in the order any, quarter, half, three quarters, every.

    1. When first[i] of the half level is 255, the result is UNKNOWN (6).
    2. Else, start at any and count the levels whose run holds the band: first[i] ≤ band ≤ last[i]. Stop at the first level that does not hold it. The result is the count, 0 to 5.

    The bytes 253 and 255 are more than each band (0 to 45). So the test first ≤ band ≤ last is false for them, and they need no special case.

    Invariants:

    • The result is 0 to 5 or UNKNOWN. Class n means that the n lowest levels hold the band, and level n + 1 does not hold it (or n is 5).
    • When each level has one run, the levels nest, and the class is shareClass(c(b), k) of the exact counts.
    • When the runs do not nest, a higher level that holds the band does not raise the class above a lower level that does not hold it. So the classes stay in order, as "Readers" of Snow: one date-free snow layer for TrailView and the planner, and small per-year tiles for routes #3125 says.

    paintTile(words, levels, band, parts, x, y, palette)

    The map tile is part (x, y) of parts × parts parts of the 512 px data tile. One screen pixel is 2 ÷ parts data pixels. levels undefined (a missing tile) draws the hatch on the full tile, as today.

    1. Axes. For each axis, one time for each tile, I fill three module-level arrays of 256 items: low, high and fraction. The centre of screen pixel s is at the data coordinate u = 512 x ÷ parts + (s + 0.5) × 2 ÷ parts.
      • parts 1 or 2: low = high = min(511, ⌊u⌋), the nearest data pixel, and fraction is 0.
      • parts 4 or more: t = u − 0.5, clamped to 0 to 511. low = ⌊t⌋, high = min(511, low + 1), fraction = t − low. The tile edge repeats its pixels, as today.
    2. Cells. Adjacent screen columns with the same low are one column run. Rows are the same. A row run and a column run make one cell. Each screen pixel of a cell has the same four data pixels n0 to n3.
    3. Masks. For each cell, I make 4-bit masks over n0 to n3: missing, where the half level has 255, and for each level from any up, held, where its run holds the band. I stop at the first level with an empty mask: its weight is 0 at each pixel of the cell, so no higher level can count there.
    4. Full cells. When missing is 15, the cell is the hatch. When missing is 0 and each mask that I kept is 15, the class of each pixel of the cell is the number of kept masks. I fill the cell with one value. With parts 1 or 2, each cell is one screen pixel and has this case (n0 = n1 = n2 = n3).
    5. Mixed cells. For each pixel, the bilinear weights w0 to w3 come from the row and the column fraction. The pixel is the hatch when the weight of missing is more than 0.5. Else its class is the count of levels, from any up, whose held weight is 0.5 or more. The count stops at the first level whose weight is less.
    6. Draw. Class 0 stays clear. The hatch draws where ((px + py) & 7) < 2, as today, so its lines continue across tile edges.

    Invariants:

    • With parts 1 or 2, the class of a screen pixel is levelClass of one data pixel.
    • When the four data pixels of a cell have the same levelClass, each screen pixel of the cell has that class. So a class border moves only between data pixels of different classes, and an area of one class gets no speck of another class.
    • The hatch needs more than half of the weight and a level needs half or more. So between one data pixel and one no-data pixel, the class and the hatch meet at the midpoint, with no gap and no overlap.
    • Each fraction is a multiple of 1 ÷ (2 parts), so the weights are exact in binary floating point and the test at 0.5 has no rounding error.
    • No allocation for each pixel or each cell: the axis arrays and the masks are module-level typed arrays.
    • Cost: for each cell, at most 44 byte reads: 4 for missing, and 2 for each data pixel and level. For each pixel of a mixed cell, at most 6 sums of 4 weights. Above the data zoom, most cells are full cells.

    Generated by Claude Code

  2. timohueser commented on Nov 6, 2026

    @timohueser
    OwnerAuthor

    Deviations from the Plan in the pull request

    • Step 5, a fact: 28 February is day step 90, the same as 1 March. 26 and 27 February are day step 89. The rule does not change: the strip, the headline of snowYear and the headline of snowChart count the band day, bandDay(snowBand(index)). The test uses 26 February (day step 89, band 22, band day 90).
    • Step 7 and 9: the samples carry firstSeason from the snow-seasons metadata. The year calendar labels its rows from the archive that its samples come from, so sample opens only snow-seasons. The map attribution (credit, resolution, first season) still comes from snow.
    • Step 7: the split of a run tile into its images is the pure function runImages in snow.ts. The Decoding in snow-layer.svelte.ts calls it. One small test checks the split by the RIFF size. The WebP decode itself has no unit test: vitest runs in Node, which has no createImageBitmap.
    • Step 4: with 1 or 2 parts, paintTile calls levelClass for each screen pixel directly, without the cells. This is the same result as the algorithm comment above, and it is faster.
    • Step 1: colors is not exported any more. The map palette is made from snowClasses, so the map, the legend and the strip use one list of colours. The class constants are EVERY (5) and UNKNOWN (6); the classes 0 to 4 are numbers.
    • Step 1, for the owner: "a colour between the neighbours" gives #becfda for 1/4 to below 1/2 and #c9d9e9 for 3/4 to below 1 in the light theme. These two are near each other, because today's light ramp goes from blue (1/2 to below 3/4) back to near-white (every year). The dark theme does not have this problem (#4f6679 and #a9bcce). The owner decides with the gallery.

    Generated by Claude Code

  3. timohueser commented on Nov 6, 2026

    @timohueser
    OwnerAuthor

    #3173 merged into the integration branch snow-formats, after an adversarial review (no blocking finding; a brute-force probe matched paintTile on 2.75 M pixels and routeZoom on 2,000 random lines) and green CI. This issue closes when snow-formats merges into develop with the re-bake of #3125. Open steps of Done when: the re-bake measurements (one screen at zoom 10 and 12, a 100 km route) and the owner's approval of the labels and colours with the gallery. Note for the gallery: in the light theme, the colours of 1/4 to 1/2 and of 3/4 to 1 look almost the same.


    Generated by Claude Code

  4. timohueser commented on Nov 6, 2026

    @timohueser
    OwnerAuthor

    Owner decision on the snow gallery: keep sure snow ("every year") pale, as today. The mid classes stay blue. Still open: in the light theme, the colours of 1/4 to 1/2 (#becfda) and of 3/4 to below 1 (#c9d9e9) look almost the same.


    Generated by Claude Code

  5. timohueser commented on Nov 6, 2026

    @timohueser
    OwnerAuthor

    The owner approved the before and after gallery of the Central Switzerland re-bake: the planner map with the 6 classes, the labels and the colours (sure snow pale, the classes of fewer years in blue), and the TrailView views. The near-equal light colours of 1/4 to 1/2 and of 3/4 to below 1 stay as they are.


    Generated by Claude Code

  6. timohueser commented on Nov 6, 2026

    @timohueser
    OwnerAuthor

    Done: #3173 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