Cache viewer¶
The service serves a page at /ui/ that lists every store in FORCINGKIT_CACHE_DIR: the
Zarr stores it built and the raw GRIB and NetCDF files it fetched. The page polls
/api/v1/cache/inventory every five seconds while it is visible, so new stores appear while a
request is still running. The response carries an ETag, and a poll that sends it back in
If-None-Match gets 304 with no body when nothing changed.
Coverage¶
The Coverage tab answers which stores cover a place and a time:
Map. Each store’s footprint is drawn as an outline, colored by its source family (NECOFS, Doppio, HRRR, HYCOM, HF radar and so on). Hovering an outline names the store, its kind and its time span; clicking it selects the store and opens its preview.
Coverage strip. One row per source family and one column per UTC day. The shade is the number of hours of that day covered by the stores in the current map view, so panning or zooming the map changes the strip. Clicking a cell filters the list and the map to that day.
The filters above the list apply to both: the family chips (click to hide or show a family, double-click to show only it), the kind, a date range, and In map view, which lists only the stores that overlap the map.
Preview¶
The Preview tab draws the selected store on its own cells: an unstructured mesh (NECOFS FVCOM) by its triangles, a regular or curvilinear grid (HRRR, NWPS, Doppio, the parent-ocean stores) by its cells, and a store of sites (river mouths) as one circle per site. It reads every store the inventory lists, including those in subfolders.
Map. One color per cell over the basemap, one record at a time. Choose the field (a speed is derived from each east and north pair), the layer and the record; Play steps through the records. The readout under the pointer gives the cell’s value, the layer’s depth, the bed and the cell’s index in the source.
3D. The surface cells, see-through and with faint cell edges, over a lit bed tinted from shallow to deep: a mesh’s own faceted bed where the store holds the depth at its nodes, else each cell flat at its own bed with walls between neighbors. Tracers show the current or wind below: in a thinned set of columns and up to six levels down each, one segment per cell moves along that cell’s velocity and wraps inside the cell, colored by depth in the column. Up to four level maps draw whole layers at their heights. Navigation is vantagekit: drag to orbit, keys while the view has focus, double-click to turn about a point.
Section. Click points on the map and double-click (or press Enter) to finish: the panel shows the field along the line in every layer, with the bed, and the 3D view hangs it as a curtain.
The link in the address bar (#<store>&f=<field>&k=<layer>&t=<record>&v=3d) reopens the same
view.
The preview draws what the store holds and nothing more:
No interpolation. A cell is drawn flat in its own color; a section sample takes its host cell’s value. Records are held, not blended, during playback.
Fixed scales. A field’s scale is set once per store from the 1st to the 99th percentile of its values weighted by cell area (symmetric about zero, at the 99.5th percentile of the magnitude, for signed fields), so a color means the same value in every record and layer. Water speed uses the packaged
currents_tempo_darkramp at its own speeds (0.02 to 3.1 m/s on a log axis), so different stores compare directly. Temperature is drawn on cmocean “thermal” and salinity on “haline”, the maps oceanographers know for them.True heights. Layers run from the surface down and are labeled with their mean depth: fixed levels from the store’s vertical coordinate, sigma layers from
siglayand the water depthh, atmosphere levels from their heights. Sigma layers in a store withouthare labeled by sigma and stacked evenly in 3D, and the legend says so.Large grids. A grid with more than 400,000 cells (120,000 in 3D) is shown every n-th cell in each direction; each drawn cell carries one source cell’s value, never an average, and the legend says when.
Drawing API¶
The page draws through /api/v1/cache/view/{id}/...; other tools can use it too. detail
(2d or 3d) picks the cell budget, and element numbering is fixed for a store and detail.
Route |
Returns |
|---|---|
|
JSON: fields (label, units, scale |
|
Binary: node longitudes and latitudes (Float64) then triangles (Uint32, three per element). |
|
Binary: one byte per element on the field’s scale (0: no value; 1 to 255 from |
|
Binary Float32 per element: the layer center’s height and the bed’s (m, positive up).
|
|
JSON: the cell under the point, its value, height, bed and source index. |
|
JSON: values and heights in every layer at |
|
JSON: up to |
Inventory fields¶
Besides the display strings, each inventory entry carries structured fields for other tools:
Field |
Meaning |
|---|---|
|
|
|
ISO 8601 UTC times of the first and last records, or the target date of a snapshot. |
|
The source model or provider, read from the store’s path and its |
|
|
Entries are cached per store and rebuilt only when the store’s metadata files change.
Basemap¶
By default the maps use OpenFreeMap vector tiles (OpenStreetMap data), which need no key, cut down to land, water, the shoreline and faint rivers: no roads, buildings, place names or boundaries, so the data drawn over it carries the map. The credit sits behind the (i) button in the map’s corner. To draw your own relief instead, put PMTiles archives of raster tiles (WebP or PNG, 256 px) in a folder and point the service at it:
export FORCINGKIT_BASEMAP_DIR=/path/to/basemaps
export FORCINGKIT_BASEMAP_ATTRIBUTION="Relief: NOAA, USGS"
Every <name>.pmtiles in the folder is drawn, coarsest first (by deepest zoom), dimmed for the
dark page; a <name>.coast.geojson beside it is drawn as a shoreline. The page reads the
archives in byte ranges from /api/v1/cache/basemap/files/<file>, and
/api/v1/cache/basemap lists them.