Repository navigation
Description
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,
paintTileinsnow.tsblends the onset and melt-out of the four nearest pixels for each season (blendSeason).steadyskips the blend where the four pixels agree. Both read the per-year planes (Planar). - The classes have lines at 1/3 and 2/3.
shareClassgivesFREE,MOSTLY_FREE,MOSTLY_SNOW,SNOWandUNKNOWN.snowClassesgives their swatches fromcolors.paletteinsnow-layer.svelte.tsindexes 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.
coveringinsnow.tsreads the nearest ancestor of a missing tile down toMODIS_ZOOM(8).drawreads the tile of zoom min(z, max zoom).samplereads the tiles of the max zoom under all samples witheachTile. - The route samples are the vertices of the routed line.
PlannerApp.sveltegivessampletheRoutingLineof the route (visualRoute). Itscoordinatescome fromcalculateLineinrouting.ts: one sample for each vertex of the routed legs, with no fixed spacing.profileSamplesinprofile-data.tsgives the strip one point for each coordinate. A pin on the map samples one coordinate (PlannerApp.svelte,pinSamples). evening.tsdoes not read snow.nightLowsamples only a layer withnights, and the snow layer has none.- A layer gets one URL.
availableLayersindata-layer.tscreates a layer from one archive name.Archiveis'snow' | 'climate', andPlannerConfig.layersinconfig.tsis typed by it.registry.tsgives the snow layer the URL ofsnow. - A shared ancestor loads once.
openArchiveinarchive.tskeeps one archive for each URL.decodedTileskeeps each decoded tile byz/x/yin a byte budget, and loads a tile once while it stays cached.eachTileloads 4 tiles at a time. - The planner decodes a lossless WebP byte for byte.
imagePixelsinterrain.tsgives the RGBA pixels without colour conversion. - The map tiles are 256 pixels.
Rasterinraster.tsasks for map tiles of 256 × 256 pixels from the archive's min zoom to max(max zoom,MAX_ZOOM14). - The year calendar colours seasons, not classes.
snowChartgives one cell for each season and day step: snow, clear or no data. Only its headline counts the seasons.
Plan
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), andUNKNOWN6 for no data.shareClass(snow, known)gives them from c and k.snowClasses(theme)gives 7 swatches.colorskeeps 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.snow.ts, the bands:snowBand(index: number): numberis ⌊index ÷ 4⌋, andbandDay(band: number): numberis min(4 band + 2, 182).snowMetacheckssnow_format1 instead ofstep_days.snow.ts, the runs: a new typeRuns { first: Uint8Array; last: Uint8Array }holds the first and the last band of one level for the 512 × 512 pixels of a tile. A new functionlevelClass(levels: Runs[], i: number, band: number): numbergives the class of pixel i: the number of levels, fromanyup, that hold the band without a gap;UNKNOWNwherefirstof the half level is 255.levelsis in the order any, quarter, half, three quarters, every.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. DeleteblendSeasonandsteady. A missing tile is no data, as today.snow.ts, the samples: Every count of the snow on the date uses the band daybandDay(snowBand(index)), as the map does:snowClass(p: Planar, i, band)for the strip, the headline ofsnowYear(clearOn) and the headline ofsnowChart. So on 28 February (day step 89, band 22, band day 90) all three count day step 90.snowYearkeeps its columns of day steps and colours them with the 6 classes.snowChartkeeps its cells of one season each and one day step each: snow, clear or no data.routeSeasonsstays.snow.ts, the route zoom: a new functionrouteZoom(coordinates: Coordinate[], minZoom: number, maxZoom: number): numbergives the finest zoom, at mostmaxZoom, at which the coordinates fall in at most 25 tiles (ROUTE_TILES); elseminZoom. It counts the distinctx/yofworldPixel(coordinate, 2 ** zoom), frommaxZoomdown. A new functionseasonsTile(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 }, ascoveringdoes.coveringstops at zoom 7 instead ofMODIS_ZOOM8, and onlysnowandsnow-levelsuse it.snow-layer.svelte.ts, the archives: the constructor takes the three URLs. ADecodingforsnowandsnow-levelssplits the tile body into images (the length of each is 8 + the RIFF size in bytes 4 to 7), decodes each withimagePixels, and keeps red asfirstand green aslast. It throws when the image count is not 1 forsnowand 4 forsnow-levels, or when an image is not 512 × 512. TheDecodingofsnow-seasonschecks a body of 2 × seasons × 4,096 bytes, with the season count of thesnow-seasonsmetadata, which also gives thePlanarof the samples.openopens each archive once. The layer'smeta(credit, resolution, first season) comes fromsnow. The decoded-tile budgets:snow32 MiB (a tile is 512 KiB decoded),snow-levels64 MiB (2 MiB a tile),snow-seasons16 MiB (about 80 KiB a tile for 10 seasons).snow-layer.svelte.ts,draw: the data zoom d is min(max(z − 1, 0), the max zoom ofsnow). It readscoveringof tile d/⌊x ÷ 2^(z − d)⌋/⌊y ÷ 2^(z − d)⌋ insnow, then thesnow-levelstile at the zoom thatcoveringfound, so the levels line up with the half level and a missing tile costs no second search. Wheresnow-levelslacks that tile, the map tile is no data. It callspaintTilewith parts 2^(z − zoom of the tile found) and the levels in table order.palettegets 7 colours. The legend leaves out "none", as today.snow-layer.svelte.ts,sample: it takesrouteZoomofline.coordinateswith the min and max zoom ofsnow-seasons, groups the samples by the 64-pixel tile of that zoom witheachTile, and reads each tile withseasonsTile. 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.valuespassessnowBandof the date tosnowClass.data-layer.ts:Archivegets'snow-levels'and'snow-seasons'. An entry oflayerRegistrynames a list of archives (archives: Archive[]) and hascreate(urls: Record<Archive, string>).availableLayerscreates a layer only when the config has every archive of its list.registry.ts: the climate entry listsclimate, and the snow entry listssnow,snow-levelsandsnow-seasons.data-layer.test.ts: a release withoutsnow-seasonsshows no snow layer.- 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);routeZoomof a long line at 25 tiles, and one zoom coarser when the line grows past 25 tiles;seasonsTilereads the zoom 10 ancestor of a missing tile;coveringstops at zoom 7; the 6 classes ofsnowClassandsnowYear.
Files
builder/web/src/lib/planner/layers/snow.ts: change: the 6 classes, the bands, the runs,paintTile,routeZoom,seasonsTile,covering; deleteblendSeasonandsteady.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:Archivenamessnow-levelsandsnow-seasons; a layer lists its archives.builder/web/tests/browser/planner/config.json: change: the URLs ofsnow-levelsandsnow-seasons, for the suiteweb.planner-requests.builder/web/src/lib/planner/layers/snow.test.ts: change: the tests of step 11.
Done when
cd builder/web && npm test(suiteweb.builder-vitest),npm run checkinbuilder/web, andnpm run test:planner --prefix builder/web/tests/browser(suiteweb.planner-requests) pass.obc test affected --base origin/developpasses.- On a local re-bake of Central Switzerland with sub-issue A: the planner map shows the 6 classes and the hatch at zoom 10 and 12, and a 100 km route reads at most 25
snow-seasonstiles. The pull request records the requests and the bytes of one screen at zoom 10 and 12, and of the 100 km route. - The owner approves the labels and the colours with the gallery of Snow: one date-free snow layer for TrailView and the planner, and small per-year tiles for routes #3125.
- Depends on Snow A. Bake: planner/snow writes snow, snow-levels and snow-seasons, and the TrailView snow bake goes #3129. It merges with Snow B. TrailView: the snow of a date from the run of snow #3127, 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
The algorithm of
levelClassandpaintTileI write this before the code. The steps of the Plan do not change.
levelClass(levels, i, band)levelsholds the 5 runs in the order any, quarter, half, three quarters, every.first[i]of the half level is 255, the result isUNKNOWN(6).anyand 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 ≤ lastis false for them, and they need no special case.Invariants:
UNKNOWN. Class n means that the n lowest levels hold the band, and level n + 1 does not hold it (or n is 5).shareClass(c(b), k)of the exact counts.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.
levelsundefined (a missing tile) draws the hatch on the full tile, as today.low,highandfraction. The centre of screen pixel s is at the data coordinate u = 512 x ÷ parts + (s + 0.5) × 2 ÷ parts.low=high= min(511, ⌊u⌋), the nearest data pixel, andfractionis 0.low= ⌊t⌋,high= min(511,low+ 1),fraction= t −low. The tile edge repeats its pixels, as today.loware 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.missing, where the half level has 255, and for each level fromanyup,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.missingis 15, the cell is the hatch. Whenmissingis 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).fraction. The pixel is the hatch when the weight ofmissingis more than 0.5. Else its class is the count of levels, fromanyup, whoseheldweight is 0.5 or more. The count stops at the first level whose weight is less.Invariants:
levelClassof one data pixel.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.fractionis 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.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
timohueser commentedon Nov 6, 2026
Deviations from the Plan in the pull request
snowYearand the headline ofsnowChartcount the band day,bandDay(snowBand(index)). The test uses 26 February (day step 89, band 22, band day 90).firstSeasonfrom thesnow-seasonsmetadata. The year calendar labels its rows from the archive that its samples come from, sosampleopens onlysnow-seasons. The map attribution (credit, resolution, first season) still comes fromsnow.runImagesinsnow.ts. TheDecodinginsnow-layer.svelte.tscalls 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 nocreateImageBitmap.paintTilecallslevelClassfor each screen pixel directly, without the cells. This is the same result as the algorithm comment above, and it is faster.colorsis not exported any more. The map palette is made fromsnowClasses, so the map, the legend and the strip use one list of colours. The class constants areEVERY(5) andUNKNOWN(6); the classes 0 to 4 are numbers.#becfdafor 1/4 to below 1/2 and#c9d9e9for 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 (#4f6679and#a9bcce). The owner decides with the gallery.Generated by Claude Code
timohueser commentedon Nov 6, 2026
#3173 merged into the integration branch
snow-formats, after an adversarial review (no blocking finding; a brute-force probe matchedpaintTileon 2.75 M pixels androuteZoomon 2,000 random lines) and green CI. This issue closes whensnow-formatsmerges intodevelopwith 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
timohueser commentedon Nov 6, 2026
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
timohueser commentedon Nov 6, 2026
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
timohueser commentedon Nov 6, 2026
Done: #3173 merged into
snow-formats, and #3175 merged it intodevelop(3469850).