forcingkit 0.21.0__tar.gz → 0.22.1__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (164) hide show
  1. {forcingkit-0.21.0 → forcingkit-0.22.1}/PKG-INFO +1 -1
  2. forcingkit-0.22.1/docs/source/cache_viewer.rst +146 -0
  3. {forcingkit-0.21.0 → forcingkit-0.22.1}/docs/source/conf.py +1 -1
  4. {forcingkit-0.21.0 → forcingkit-0.22.1}/docs/source/doppio.rst +2 -3
  5. {forcingkit-0.21.0 → forcingkit-0.22.1}/pyproject.toml +1 -1
  6. {forcingkit-0.21.0 → forcingkit-0.22.1}/service/forcingkit_serve/main.py +2 -2
  7. forcingkit-0.22.1/service/forcingkit_serve/routers/view.py +259 -0
  8. {forcingkit-0.21.0 → forcingkit-0.22.1}/service/forcingkit_serve/routers/viewer.py +1 -721
  9. forcingkit-0.22.1/service/forcingkit_serve/view_store.py +1133 -0
  10. forcingkit-0.22.1/static/app.js +282 -0
  11. forcingkit-0.22.1/static/cells_map.js +336 -0
  12. {forcingkit-0.21.0 → forcingkit-0.22.1}/static/coverage.js +52 -2
  13. forcingkit-0.22.1/static/index.html +200 -0
  14. forcingkit-0.22.1/static/preview.js +548 -0
  15. forcingkit-0.22.1/static/scene3d.js +617 -0
  16. {forcingkit-0.21.0 → forcingkit-0.22.1}/static/styles.css +271 -51
  17. forcingkit-0.22.1/static/view_api.js +123 -0
  18. forcingkit-0.22.1/tests/unit/test_view_store.py +328 -0
  19. {forcingkit-0.21.0 → forcingkit-0.22.1}/uv.lock +1 -1
  20. forcingkit-0.21.0/docs/source/cache_viewer.rst +0 -67
  21. forcingkit-0.21.0/service/forcingkit_serve/routers/plotly_api.py +0 -150
  22. forcingkit-0.21.0/static/app.js +0 -649
  23. forcingkit-0.21.0/static/index.html +0 -175
  24. forcingkit-0.21.0/static/preview3d.js +0 -350
  25. {forcingkit-0.21.0 → forcingkit-0.22.1}/.agents/forcingkit.md +0 -0
  26. {forcingkit-0.21.0 → forcingkit-0.22.1}/.claude/CLAUDE.md +0 -0
  27. {forcingkit-0.21.0 → forcingkit-0.22.1}/.env.template +0 -0
  28. {forcingkit-0.21.0 → forcingkit-0.22.1}/.github/copilot-instructions.md +0 -0
  29. {forcingkit-0.21.0 → forcingkit-0.22.1}/.github/workflows/docs.yml +0 -0
  30. {forcingkit-0.21.0 → forcingkit-0.22.1}/.github/workflows/publish-client.yml +0 -0
  31. {forcingkit-0.21.0 → forcingkit-0.22.1}/.github/workflows/publish.yml +0 -0
  32. {forcingkit-0.21.0 → forcingkit-0.22.1}/.github/workflows/tests.yml +0 -0
  33. {forcingkit-0.21.0 → forcingkit-0.22.1}/.gitignore +0 -0
  34. {forcingkit-0.21.0 → forcingkit-0.22.1}/.markdownlint.yaml +0 -0
  35. {forcingkit-0.21.0 → forcingkit-0.22.1}/.pre-commit-config.yaml +0 -0
  36. {forcingkit-0.21.0 → forcingkit-0.22.1}/.python-version +0 -0
  37. {forcingkit-0.21.0 → forcingkit-0.22.1}/AGENTS.md +0 -0
  38. {forcingkit-0.21.0 → forcingkit-0.22.1}/CONTRIBUTING.md +0 -0
  39. {forcingkit-0.21.0 → forcingkit-0.22.1}/Dockerfile +0 -0
  40. {forcingkit-0.21.0 → forcingkit-0.22.1}/LICENSE +0 -0
  41. {forcingkit-0.21.0 → forcingkit-0.22.1}/README.md +0 -0
  42. {forcingkit-0.21.0 → forcingkit-0.22.1}/client/LICENSE +0 -0
  43. {forcingkit-0.21.0 → forcingkit-0.22.1}/client/README.md +0 -0
  44. {forcingkit-0.21.0 → forcingkit-0.22.1}/client/pyproject.toml +0 -0
  45. {forcingkit-0.21.0 → forcingkit-0.22.1}/client/src/forcingkit_client/__init__.py +0 -0
  46. {forcingkit-0.21.0 → forcingkit-0.22.1}/client/src/forcingkit_client/client.py +0 -0
  47. {forcingkit-0.21.0 → forcingkit-0.22.1}/client/src/forcingkit_client/schema.py +0 -0
  48. {forcingkit-0.21.0 → forcingkit-0.22.1}/client/src/forcingkit_client/store.py +0 -0
  49. {forcingkit-0.21.0 → forcingkit-0.22.1}/client/src/forcingkit_client/trajectory.py +0 -0
  50. {forcingkit-0.21.0 → forcingkit-0.22.1}/client/tests/conftest.py +0 -0
  51. {forcingkit-0.21.0 → forcingkit-0.22.1}/client/tests/test_client.py +0 -0
  52. {forcingkit-0.21.0 → forcingkit-0.22.1}/client/tests/test_schema.py +0 -0
  53. {forcingkit-0.21.0 → forcingkit-0.22.1}/client/tests/test_trajectory.py +0 -0
  54. {forcingkit-0.21.0 → forcingkit-0.22.1}/client/uv.lock +0 -0
  55. {forcingkit-0.21.0 → forcingkit-0.22.1}/docker-compose.yml +0 -0
  56. {forcingkit-0.21.0 → forcingkit-0.22.1}/docs/Makefile +0 -0
  57. {forcingkit-0.21.0 → forcingkit-0.22.1}/docs/make.bat +0 -0
  58. {forcingkit-0.21.0 → forcingkit-0.22.1}/docs/requirements-docs.txt +0 -0
  59. {forcingkit-0.21.0 → forcingkit-0.22.1}/docs/source/_extra/CNAME +0 -0
  60. {forcingkit-0.21.0 → forcingkit-0.22.1}/docs/source/_static/forcingkit-noreaster-wind.gif +0 -0
  61. {forcingkit-0.21.0 → forcingkit-0.22.1}/docs/source/atmospheric_forcing.rst +0 -0
  62. {forcingkit-0.21.0 → forcingkit-0.22.1}/docs/source/client.rst +0 -0
  63. {forcingkit-0.21.0 → forcingkit-0.22.1}/docs/source/fetchers.rst +0 -0
  64. {forcingkit-0.21.0 → forcingkit-0.22.1}/docs/source/hycom.rst +0 -0
  65. {forcingkit-0.21.0 → forcingkit-0.22.1}/docs/source/index.rst +0 -0
  66. {forcingkit-0.21.0 → forcingkit-0.22.1}/docs/source/layered_mesh.rst +0 -0
  67. {forcingkit-0.21.0 → forcingkit-0.22.1}/docs/source/mesh_frames.rst +0 -0
  68. {forcingkit-0.21.0 → forcingkit-0.22.1}/docs/source/necofs.rst +0 -0
  69. {forcingkit-0.21.0 → forcingkit-0.22.1}/docs/source/nyofs.rst +0 -0
  70. {forcingkit-0.21.0 → forcingkit-0.22.1}/docs/source/rivers.rst +0 -0
  71. {forcingkit-0.21.0 → forcingkit-0.22.1}/docs/source/roadmap.rst +0 -0
  72. {forcingkit-0.21.0 → forcingkit-0.22.1}/docs/source/shelf_models.rst +0 -0
  73. {forcingkit-0.21.0 → forcingkit-0.22.1}/docs/source/sources.rst +0 -0
  74. {forcingkit-0.21.0 → forcingkit-0.22.1}/docs/source/waves.rst +0 -0
  75. {forcingkit-0.21.0 → forcingkit-0.22.1}/main.py +0 -0
  76. {forcingkit-0.21.0 → forcingkit-0.22.1}/service/__init__.py +0 -0
  77. {forcingkit-0.21.0 → forcingkit-0.22.1}/service/forcingkit_serve/__init__.py +0 -0
  78. {forcingkit-0.21.0 → forcingkit-0.22.1}/service/forcingkit_serve/jobs.py +0 -0
  79. {forcingkit-0.21.0 → forcingkit-0.22.1}/service/forcingkit_serve/routers/bathymetry.py +0 -0
  80. {forcingkit-0.21.0 → forcingkit-0.22.1}/service/forcingkit_serve/routers/removed.py +0 -0
  81. {forcingkit-0.21.0 → forcingkit-0.22.1}/service/forcingkit_serve/routers/stores.py +0 -0
  82. {forcingkit-0.21.0 → forcingkit-0.22.1}/service/forcingkit_serve/stac.py +0 -0
  83. {forcingkit-0.21.0 → forcingkit-0.22.1}/service/run_server.py +0 -0
  84. {forcingkit-0.21.0 → forcingkit-0.22.1}/src/forcingkit/__init__.py +0 -0
  85. {forcingkit-0.21.0 → forcingkit-0.22.1}/src/forcingkit/data/rivers/northeast_us.json +0 -0
  86. {forcingkit-0.21.0 → forcingkit-0.22.1}/src/forcingkit/dispatcher.py +0 -0
  87. {forcingkit-0.21.0 → forcingkit-0.22.1}/src/forcingkit/fetchers/coastwatch.py +0 -0
  88. {forcingkit-0.21.0 → forcingkit-0.22.1}/src/forcingkit/fetchers/dbofs.py +0 -0
  89. {forcingkit-0.21.0 → forcingkit-0.22.1}/src/forcingkit/fetchers/doppio.py +0 -0
  90. {forcingkit-0.21.0 → forcingkit-0.22.1}/src/forcingkit/fetchers/erddap.py +0 -0
  91. {forcingkit-0.21.0 → forcingkit-0.22.1}/src/forcingkit/fetchers/hfradar.py +0 -0
  92. {forcingkit-0.21.0 → forcingkit-0.22.1}/src/forcingkit/fetchers/hrdps.py +0 -0
  93. {forcingkit-0.21.0 → forcingkit-0.22.1}/src/forcingkit/fetchers/hrrr.py +0 -0
  94. {forcingkit-0.21.0 → forcingkit-0.22.1}/src/forcingkit/fetchers/hrrr_atmosphere.py +0 -0
  95. {forcingkit-0.21.0 → forcingkit-0.22.1}/src/forcingkit/fetchers/hrrr_levels.py +0 -0
  96. {forcingkit-0.21.0 → forcingkit-0.22.1}/src/forcingkit/fetchers/hrrr_points.py +0 -0
  97. {forcingkit-0.21.0 → forcingkit-0.22.1}/src/forcingkit/fetchers/hycom.py +0 -0
  98. {forcingkit-0.21.0 → forcingkit-0.22.1}/src/forcingkit/fetchers/hydrography.py +0 -0
  99. {forcingkit-0.21.0 → forcingkit-0.22.1}/src/forcingkit/fetchers/ndbc.py +0 -0
  100. {forcingkit-0.21.0 → forcingkit-0.22.1}/src/forcingkit/fetchers/necofs.py +0 -0
  101. {forcingkit-0.21.0 → forcingkit-0.22.1}/src/forcingkit/fetchers/noaa.py +0 -0
  102. {forcingkit-0.21.0 → forcingkit-0.22.1}/src/forcingkit/fetchers/nwps.py +0 -0
  103. {forcingkit-0.21.0 → forcingkit-0.22.1}/src/forcingkit/fetchers/nyofs.py +0 -0
  104. {forcingkit-0.21.0 → forcingkit-0.22.1}/src/forcingkit/fetchers/usgs.py +0 -0
  105. {forcingkit-0.21.0 → forcingkit-0.22.1}/src/forcingkit/fetchers/usgs_rivers.py +0 -0
  106. {forcingkit-0.21.0 → forcingkit-0.22.1}/src/forcingkit/layered_mesh.py +0 -0
  107. {forcingkit-0.21.0 → forcingkit-0.22.1}/src/forcingkit/mesh_frames.py +0 -0
  108. {forcingkit-0.21.0 → forcingkit-0.22.1}/src/forcingkit/ramps/currents_lis.csv +0 -0
  109. {forcingkit-0.21.0 → forcingkit-0.22.1}/src/forcingkit/ramps/currents_lis_dark.csv +0 -0
  110. {forcingkit-0.21.0 → forcingkit-0.22.1}/src/forcingkit/ramps/currents_lis_deep.csv +0 -0
  111. {forcingkit-0.21.0 → forcingkit-0.22.1}/src/forcingkit/ramps/currents_lis_haline.csv +0 -0
  112. {forcingkit-0.21.0 → forcingkit-0.22.1}/src/forcingkit/render.py +0 -0
  113. {forcingkit-0.21.0 → forcingkit-0.22.1}/src/forcingkit/settings.py +0 -0
  114. {forcingkit-0.21.0 → forcingkit-0.22.1}/src/forcingkit/zarr_stream.py +0 -0
  115. {forcingkit-0.21.0 → forcingkit-0.22.1}/static/favicon.ico +0 -0
  116. {forcingkit-0.21.0 → forcingkit-0.22.1}/static/favicon.svg +0 -0
  117. {forcingkit-0.21.0 → forcingkit-0.22.1}/static/logo.svg +0 -0
  118. {forcingkit-0.21.0 → forcingkit-0.22.1}/tests/__init__.py +0 -0
  119. {forcingkit-0.21.0 → forcingkit-0.22.1}/tests/integration/test_auth.py +0 -0
  120. {forcingkit-0.21.0 → forcingkit-0.22.1}/tests/integration/test_erddap_fetch.py +0 -0
  121. {forcingkit-0.21.0 → forcingkit-0.22.1}/tests/integration/test_mesh_frames_necofs.py +0 -0
  122. {forcingkit-0.21.0 → forcingkit-0.22.1}/tests/integration/test_necofs_volume_live.py +0 -0
  123. {forcingkit-0.21.0 → forcingkit-0.22.1}/tests/integration/test_nwps_nomads.py +0 -0
  124. {forcingkit-0.21.0 → forcingkit-0.22.1}/tests/integration/test_nyofs_obc_fetch.py +0 -0
  125. {forcingkit-0.21.0 → forcingkit-0.22.1}/tests/integration/test_obc_offshore_nj.py +0 -0
  126. {forcingkit-0.21.0 → forcingkit-0.22.1}/tests/integration/test_ofs_archive_paths.py +0 -0
  127. {forcingkit-0.21.0 → forcingkit-0.22.1}/tests/integration/test_s3_roms_fetchers.py +0 -0
  128. {forcingkit-0.21.0 → forcingkit-0.22.1}/tests/scripts/inspect_dem.py +0 -0
  129. {forcingkit-0.21.0 → forcingkit-0.22.1}/tests/scripts/inspect_grib.py +0 -0
  130. {forcingkit-0.21.0 → forcingkit-0.22.1}/tests/scripts/inspect_zarr.py +0 -0
  131. {forcingkit-0.21.0 → forcingkit-0.22.1}/tests/unit/data/doppio_reanalysis_20220811_corner.nc +0 -0
  132. {forcingkit-0.21.0 → forcingkit-0.22.1}/tests/unit/test_cache_inventory.py +0 -0
  133. {forcingkit-0.21.0 → forcingkit-0.22.1}/tests/unit/test_coastwatch.py +0 -0
  134. {forcingkit-0.21.0 → forcingkit-0.22.1}/tests/unit/test_dbofs.py +0 -0
  135. {forcingkit-0.21.0 → forcingkit-0.22.1}/tests/unit/test_dispatcher.py +0 -0
  136. {forcingkit-0.21.0 → forcingkit-0.22.1}/tests/unit/test_doppio.py +0 -0
  137. {forcingkit-0.21.0 → forcingkit-0.22.1}/tests/unit/test_erddap.py +0 -0
  138. {forcingkit-0.21.0 → forcingkit-0.22.1}/tests/unit/test_hfradar.py +0 -0
  139. {forcingkit-0.21.0 → forcingkit-0.22.1}/tests/unit/test_hrdps.py +0 -0
  140. {forcingkit-0.21.0 → forcingkit-0.22.1}/tests/unit/test_hrrr_atm.py +0 -0
  141. {forcingkit-0.21.0 → forcingkit-0.22.1}/tests/unit/test_hrrr_idx.py +0 -0
  142. {forcingkit-0.21.0 → forcingkit-0.22.1}/tests/unit/test_hrrr_levels.py +0 -0
  143. {forcingkit-0.21.0 → forcingkit-0.22.1}/tests/unit/test_hrrr_points.py +0 -0
  144. {forcingkit-0.21.0 → forcingkit-0.22.1}/tests/unit/test_hycom.py +0 -0
  145. {forcingkit-0.21.0 → forcingkit-0.22.1}/tests/unit/test_jobs.py +0 -0
  146. {forcingkit-0.21.0 → forcingkit-0.22.1}/tests/unit/test_layered_mesh.py +0 -0
  147. {forcingkit-0.21.0 → forcingkit-0.22.1}/tests/unit/test_main.py +0 -0
  148. {forcingkit-0.21.0 → forcingkit-0.22.1}/tests/unit/test_mesh_frames.py +0 -0
  149. {forcingkit-0.21.0 → forcingkit-0.22.1}/tests/unit/test_ndbc.py +0 -0
  150. {forcingkit-0.21.0 → forcingkit-0.22.1}/tests/unit/test_necofs_hindcast.py +0 -0
  151. {forcingkit-0.21.0 → forcingkit-0.22.1}/tests/unit/test_necofs_mesh_cache.py +0 -0
  152. {forcingkit-0.21.0 → forcingkit-0.22.1}/tests/unit/test_necofs_parent.py +0 -0
  153. {forcingkit-0.21.0 → forcingkit-0.22.1}/tests/unit/test_necofs_volume.py +0 -0
  154. {forcingkit-0.21.0 → forcingkit-0.22.1}/tests/unit/test_noaa_currents.py +0 -0
  155. {forcingkit-0.21.0 → forcingkit-0.22.1}/tests/unit/test_noaa_datum.py +0 -0
  156. {forcingkit-0.21.0 → forcingkit-0.22.1}/tests/unit/test_nwps.py +0 -0
  157. {forcingkit-0.21.0 → forcingkit-0.22.1}/tests/unit/test_nyofs.py +0 -0
  158. {forcingkit-0.21.0 → forcingkit-0.22.1}/tests/unit/test_obc_donor_report.py +0 -0
  159. {forcingkit-0.21.0 → forcingkit-0.22.1}/tests/unit/test_obc_pipeline.py +0 -0
  160. {forcingkit-0.21.0 → forcingkit-0.22.1}/tests/unit/test_removed_routes.py +0 -0
  161. {forcingkit-0.21.0 → forcingkit-0.22.1}/tests/unit/test_settings.py +0 -0
  162. {forcingkit-0.21.0 → forcingkit-0.22.1}/tests/unit/test_usgs.py +0 -0
  163. {forcingkit-0.21.0 → forcingkit-0.22.1}/tests/unit/test_usgs_rivers.py +0 -0
  164. {forcingkit-0.21.0 → forcingkit-0.22.1}/tests/unit/test_zarr_stream.py +0 -0
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.5
2
2
  Name: forcingkit
3
- Version: 0.21.0
3
+ Version: 0.22.1
4
4
  Summary: Spatiotemporal forcing for computational Earth-system models: selects, regrids and serves model-ready time series with provenance.
5
5
  Project-URL: Documentation, https://forcingkit.docs.lhzn.io
6
6
  Project-URL: Issues, https://github.com/lhzn-io/forcingkit/issues
@@ -0,0 +1,146 @@
1
+ Cache viewer
2
+ ============
3
+
4
+ The service serves a page at ``/ui/`` that lists every store in ``FORCINGKIT_CACHE_DIR``: the
5
+ Zarr stores it built and the raw GRIB and NetCDF files it fetched. The page polls
6
+ ``/api/v1/cache/inventory`` every two seconds, so new stores appear while a request is still
7
+ running.
8
+
9
+ Coverage
10
+ --------
11
+
12
+ The **Coverage** tab answers which stores cover a place and a time:
13
+
14
+ - **Map.** Each store's footprint is drawn as an outline, colored by its source family (NECOFS,
15
+ Doppio, HRRR, HYCOM, HF radar and so on). Hovering an outline names the store, its kind and its
16
+ time span; clicking it selects the store and opens its preview.
17
+ - **Coverage strip.** One row per source family and one column per UTC day. The shade is the
18
+ number of hours of that day covered by the stores in the current map view, so panning or
19
+ zooming the map changes the strip. Clicking a cell filters the list and the map to that day.
20
+
21
+ The filters above the list apply to both: the family chips (click to hide or show a family,
22
+ double-click to show only it), the kind, a date range, and **In map view**, which lists only
23
+ the stores that overlap the map.
24
+
25
+ Preview
26
+ -------
27
+
28
+ The **Preview** tab draws the selected store on its own cells: an unstructured mesh (NECOFS
29
+ FVCOM) by its triangles, a regular or curvilinear grid (HRRR, NWPS, Doppio, the parent-ocean
30
+ stores) by its cells, and a store of sites (river mouths) as one circle per site. It reads every
31
+ store the inventory lists, including those in subfolders.
32
+
33
+ - **Map.** One color per cell over the basemap, one record at a time. Choose the field (a speed
34
+ is derived from each east and north pair), the layer and the record; **Play** steps through the
35
+ records. The readout under the pointer gives the cell's value, the layer's depth, the bed and
36
+ the cell's index in the source.
37
+ - **3D.** The surface cells, see-through and with faint cell edges, over a lit bed tinted from
38
+ shallow to deep: a mesh's own faceted bed where the store holds the depth at its nodes, else
39
+ each cell flat at its own bed with walls between neighbors. Tracers show the current or wind
40
+ below: in a thinned set of columns and up to six levels down each, one segment per cell moves
41
+ along that cell's velocity and wraps inside the cell, colored by depth in the column. Up to
42
+ four level maps draw whole layers at their heights. Navigation is
43
+ `vantagekit <https://github.com/lhzn-io/vantagekit>`__: drag to orbit, keys while the view has
44
+ focus, double-click to turn about a point.
45
+ - **Section.** Click points on the map and double-click (or press Enter) to finish: the panel
46
+ shows the field along the line in every layer, with the bed, and the 3D view hangs it as a
47
+ curtain.
48
+
49
+ The link in the address bar (``#<store>&f=<field>&k=<layer>&t=<record>&v=3d``) reopens the same
50
+ view.
51
+
52
+ The preview draws what the store holds and nothing more:
53
+
54
+ - **No interpolation.** A cell is drawn flat in its own color; a section sample takes its host
55
+ cell's value. Records are held, not blended, during playback.
56
+ - **Fixed scales.** A field's scale is set once per store from the 1st to the 99th percentile of
57
+ its values weighted by cell area (symmetric about zero, at the 99.5th percentile of the
58
+ magnitude, for signed fields), so a color means the same value in every record and layer.
59
+ Water speed uses the packaged ``currents_lis_dark`` ramp at its own speeds (0.02 to 3.1 m/s on
60
+ a log axis), so different stores compare directly.
61
+ - **True heights.** Layers run from the surface down and are labeled with their mean depth:
62
+ fixed levels from the store's vertical coordinate, sigma layers from ``siglay`` and the water
63
+ depth ``h``, atmosphere levels from their heights. Sigma layers in a store without ``h`` are
64
+ labeled by sigma and stacked evenly in 3D, and the legend says so.
65
+ - **Large grids.** A grid with more than 400,000 cells (120,000 in 3D) is shown every *n*-th
66
+ cell in each direction; each drawn cell carries one source cell's value, never an average, and
67
+ the legend says when.
68
+
69
+ Drawing API
70
+ -----------
71
+
72
+ The page draws through ``/api/v1/cache/view/{id}/...``; other tools can use it too. ``detail``
73
+ (``2d`` or ``3d``) picks the cell budget, and element numbering is fixed for a store and detail.
74
+
75
+ .. list-table::
76
+ :header-rows: 1
77
+ :widths: 25 75
78
+
79
+ * - Route
80
+ - Returns
81
+ * - ``manifest``
82
+ - JSON: fields (label, units, scale ``lo`` and ``hi``, ``log``, ticks, and a 256-entry RGBA
83
+ ramp indexed by byte code), layers surface first with mean heights, record times and
84
+ cadence, cell counts, stride and bounding box.
85
+ * - ``mesh``
86
+ - Binary: node longitudes and latitudes (Float64) then triangles (Uint32, three per element).
87
+ * - ``frame?field=&layer=&t=``
88
+ - Binary: one byte per element on the field's scale (0: no value; 1 to 255 from ``lo`` to
89
+ ``hi``), as ``forcingkit.layered_mesh.FieldMeta.encode`` writes it.
90
+ * - ``heights?layer=&t=``, ``bed``
91
+ - Binary Float32 per element: the layer center's height and the bed's (m, positive up).
92
+ ``bed?at=node`` gives the bed per mesh node where the store holds the depth at its nodes.
93
+ * - ``point?lon=&lat=&field=&layer=&t=``
94
+ - JSON: the cell under the point, its value, height, bed and source index.
95
+ * - ``section?pts=lon,lat;...&field=&t=&n=``
96
+ - JSON: values and heights in every layer at ``n`` points along the polyline.
97
+ * - ``tracers?pair=&t=&levels=&limit=``
98
+ - JSON: up to ``limit`` columns thinned evenly (their elements, the same at every level) and
99
+ up to ``levels`` layers from the surface down, each with east and north components and
100
+ heights per column.
101
+
102
+ Inventory fields
103
+ ----------------
104
+
105
+ Besides the display strings, each inventory entry carries structured fields for other tools:
106
+
107
+ .. list-table::
108
+ :header-rows: 1
109
+ :widths: 20 80
110
+
111
+ * - Field
112
+ - Meaning
113
+ * - ``bbox``
114
+ - ``[west, south, east, north]`` in degrees (longitudes in -180 to 180), from the store's
115
+ longitude and latitude coordinates or variables (mesh nodes and river mouths included),
116
+ else from its ``bbox`` or ``requested_bbox`` attribute. ``null`` when neither exists.
117
+ * - ``time_start``, ``time_end``
118
+ - ISO 8601 UTC times of the first and last records, or the target date of a snapshot.
119
+ * - ``family``
120
+ - The source model or provider, read from the store's path and its ``type``, ``source``
121
+ and donor attributes.
122
+ * - ``kind``
123
+ - ``ocean boundary``, ``ocean volume``, ``initial condition``, ``atmosphere``,
124
+ ``atmosphere levels``, ``waves``, ``rivers``, ``surface currents (radar)`` or
125
+ ``raw donor file``.
126
+
127
+ Entries are cached per store and rebuilt only when the store's metadata files change.
128
+
129
+ Basemap
130
+ -------
131
+
132
+ By default the maps use `OpenFreeMap <https://openfreemap.org/>`__ vector tiles
133
+ (OpenStreetMap data), which need no key, cut down to land, water, the shoreline and faint
134
+ rivers: no roads, buildings, place names or boundaries, so the data drawn over it carries the
135
+ 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
136
+ service at it:
137
+
138
+ .. code-block:: bash
139
+
140
+ export FORCINGKIT_BASEMAP_DIR=/path/to/basemaps
141
+ export FORCINGKIT_BASEMAP_ATTRIBUTION="Relief: NOAA, USGS"
142
+
143
+ Every ``<name>.pmtiles`` in the folder is drawn, coarsest first (by deepest zoom), dimmed for the
144
+ dark page; a ``<name>.coast.geojson`` beside it is drawn as a shoreline. The page reads the
145
+ archives in byte ranges from ``/api/v1/cache/basemap/files/<file>``, and
146
+ ``/api/v1/cache/basemap`` lists them.
@@ -9,7 +9,7 @@ sys.path.insert(0, os.path.abspath("../../src"))
9
9
  project = "forcingkit"
10
10
  copyright = "2026, Long Horizon Observatory"
11
11
  author = "Daniel Fry"
12
- release = "0.21.0"
12
+ release = "0.22.1"
13
13
 
14
14
  extensions = [
15
15
  "sphinx.ext.autodoc",
@@ -120,9 +120,8 @@ Limits
120
120
  - **Sea level datum.** ``zeta`` is relative to the model's own mean sea level; the Rutgers
121
121
  metadata names no geodetic datum.
122
122
  - **Cache viewer.** The cache viewer (:doc:`cache_viewer`) lists the stores under
123
- ``doppio/volume/`` and draws their footprints on its coverage map. Its image preview opens
124
- only stores at the top of the cache directory, so it does not yet preview Doppio or NECOFS
125
- volume stores.
123
+ ``doppio/volume/``, draws their footprints on its coverage map and previews them on their
124
+ own curvilinear cells, every layer at its height from ``siglay`` and ``h``.
126
125
 
127
126
  Credit
128
127
  ------
@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
4
4
 
5
5
  [project]
6
6
  name = "forcingkit"
7
- version = "0.21.0"
7
+ version = "0.22.1"
8
8
  description = "Spatiotemporal forcing for computational Earth-system models: selects, regrids and serves model-ready time series with provenance."
9
9
  readme = "README.md"
10
10
  requires-python = ">=3.11"
@@ -24,9 +24,9 @@ from forcingkit_serve.jobs import Job # noqa: E402
24
24
  from forcingkit_serve.routers import ( # noqa: E402
25
25
  viewer,
26
26
  bathymetry,
27
- plotly_api,
28
27
  removed,
29
28
  stores,
29
+ view as view_api,
30
30
  )
31
31
  from forcingkit.fetchers.noaa import fetch_noaa_tide_data # noqa: E402
32
32
  from importlib.metadata import version as _package_version # noqa: E402
@@ -103,7 +103,7 @@ app.add_middleware(
103
103
 
104
104
  app.include_router(viewer.router)
105
105
  app.include_router(bathymetry.router)
106
- app.include_router(plotly_api.router)
106
+ app.include_router(view_api.router)
107
107
  app.include_router(stores.router)
108
108
  # 410 Gone stubs for the routes removed on 2026-10-05; drop at the next release.
109
109
  app.include_router(removed.router)
@@ -0,0 +1,259 @@
1
+ """The cache viewer's drawing API: any cached store on its own cells (see `view_store`).
2
+
3
+ Every route takes the store id from the inventory and `detail` (``2d`` or ``3d``, the cell
4
+ budget for large grids; element numbering is fixed for a store and detail). Binary bodies are
5
+ little-endian.
6
+ """
7
+
8
+ from __future__ import annotations
9
+
10
+ import logging
11
+ import threading
12
+ import time
13
+ from pathlib import Path
14
+ from typing import Any, Callable
15
+
16
+ import numpy as np
17
+ from fastapi import APIRouter, HTTPException, Query
18
+ from fastapi.responses import JSONResponse, Response
19
+ from starlette.concurrency import run_in_threadpool
20
+
21
+ from forcingkit import settings
22
+ from forcingkit_serve import view_store
23
+ from forcingkit_serve.routers.viewer import _crawl_inventory
24
+
25
+ logger = logging.getLogger(__name__)
26
+
27
+ router = APIRouter(prefix="/api/v1/cache/view", tags=["Cache Viewer"])
28
+
29
+ Detail = Query("2d", pattern="^(2d|3d)$", description="Cell budget: 2d or 3d")
30
+ BINARY = "application/octet-stream"
31
+
32
+
33
+ # Crawling the whole cache takes about 0.4 s on a cache of a few hundred stores, far more than
34
+ # drawing a cached record, so the store ids the crawl found are reused for a few seconds.
35
+ # Only ids a crawl listed resolve, and a store whose path is gone is looked up again.
36
+ RESOLVE_TTL_S = 10.0
37
+ _resolved: dict[str, Any] = {"dir": None, "at": 0.0, "stores": {}}
38
+ _resolve_lock = threading.Lock()
39
+
40
+
41
+ def _fresh(cache_dir: str) -> bool:
42
+ return (
43
+ _resolved["dir"] == cache_dir
44
+ and time.monotonic() - _resolved["at"] < RESOLVE_TTL_S
45
+ )
46
+
47
+
48
+ def _locate(dataset_id: str) -> tuple[Path, Any] | None:
49
+ """The store's path and change key (from the inventory), or None."""
50
+ cache_dir = str(settings.cache_dir())
51
+ if _fresh(cache_dir):
52
+ hit = _resolved["stores"].get(dataset_id)
53
+ if hit is not None and hit[0].exists():
54
+ return hit
55
+ with _resolve_lock:
56
+ # Another request may have crawled while this one waited.
57
+ hit = _resolved["stores"].get(dataset_id) if _fresh(cache_dir) else None
58
+ if hit is None or not hit[0].exists():
59
+ items = _crawl_inventory()
60
+ _resolved["stores"] = {
61
+ i.id: (Path(i.path), (i.modified_time, i.size_mb)) for i in items
62
+ }
63
+ _resolved["dir"], _resolved["at"] = cache_dir, time.monotonic()
64
+ return _resolved["stores"].get(dataset_id)
65
+
66
+
67
+ def forget_stores() -> None:
68
+ """Drop the remembered store ids, so the next request crawls the cache."""
69
+ with _resolve_lock:
70
+ _resolved.update(dir=None, at=0.0, stores={})
71
+
72
+
73
+ def _view(dataset_id: str, detail: str) -> view_store.StoreView:
74
+ found = _locate(dataset_id)
75
+ if found is None:
76
+ raise HTTPException(
77
+ status_code=404, detail=f"No store {dataset_id} in the cache."
78
+ )
79
+ path, key = found
80
+ try:
81
+ return view_store.get_view(dataset_id, path, detail, key)
82
+ except ValueError as e:
83
+ raise HTTPException(status_code=422, detail=str(e))
84
+
85
+
86
+ async def _run(fn: Callable[[], Any]) -> Any:
87
+ try:
88
+ return await run_in_threadpool(fn)
89
+ except HTTPException:
90
+ raise
91
+ except KeyError as e:
92
+ raise HTTPException(status_code=404, detail=str(e).strip("'\""))
93
+ except ValueError as e:
94
+ raise HTTPException(status_code=422, detail=str(e))
95
+
96
+
97
+ def _cells_only(view: view_store.StoreView) -> None:
98
+ if view.store == "points":
99
+ raise HTTPException(status_code=422, detail="this store holds sites, not cells")
100
+
101
+
102
+ def _field(view: view_store.StoreView, name: str) -> None:
103
+ if name not in view.fields:
104
+ raise HTTPException(
105
+ status_code=404,
106
+ detail=f"no field {name!r}; fields: {', '.join(view.fields)}",
107
+ )
108
+
109
+
110
+ @router.get("/{dataset_id}/manifest")
111
+ async def manifest(dataset_id: str, detail: str = Detail):
112
+ """Fields (label, units, fixed scale, ticks, 256-entry RGBA ramp by byte code), layers
113
+ surface first with mean heights, record times and cadence, cell counts and stride."""
114
+ return JSONResponse(await _run(lambda: _view(dataset_id, detail).manifest()))
115
+
116
+
117
+ @router.get("/{dataset_id}/mesh")
118
+ async def mesh(dataset_id: str, detail: str = Detail):
119
+ """Node longitudes, node latitudes (Float64 each) and triangles (Uint32, three per
120
+ element). Sizes are in the manifest (n_node, n_elem)."""
121
+
122
+ def body():
123
+ view = _view(dataset_id, detail)
124
+ _cells_only(view)
125
+ return view.mesh_bytes()
126
+
127
+ return Response(await _run(body), media_type=BINARY)
128
+
129
+
130
+ @router.get("/{dataset_id}/frame")
131
+ async def frame(
132
+ dataset_id: str,
133
+ field: str = Query(..., description="Field name from the manifest"),
134
+ layer: int = Query(0, ge=0, description="Layer, 0 at the surface"),
135
+ t: int = Query(0, ge=0, description="Record index"),
136
+ detail: str = Detail,
137
+ ):
138
+ """One byte per element on the field's fixed scale (0: no value): for sites, one per site."""
139
+
140
+ def body():
141
+ view = _view(dataset_id, detail)
142
+ _field(view, field)
143
+ return view.codes(field, t, layer)
144
+
145
+ return Response(await _run(body), media_type=BINARY)
146
+
147
+
148
+ @router.get("/{dataset_id}/heights")
149
+ async def heights(
150
+ dataset_id: str,
151
+ layer: int = Query(0, ge=0),
152
+ t: int = Query(0, ge=0),
153
+ detail: str = Detail,
154
+ ):
155
+ """Float32 per element: the layer center's height (m, positive up); 404 when the store
156
+ holds no heights."""
157
+
158
+ def body():
159
+ view = _view(dataset_id, detail)
160
+ _cells_only(view)
161
+ z = view.heights(t, layer)
162
+ if z is None:
163
+ raise HTTPException(
164
+ status_code=404, detail="this store holds no layer heights"
165
+ )
166
+ return np.asarray(z, "<f4").tobytes()
167
+
168
+ return Response(await _run(body), media_type=BINARY)
169
+
170
+
171
+ @router.get("/{dataset_id}/bed")
172
+ async def bed(
173
+ dataset_id: str,
174
+ at: str = Query("element", pattern="^(element|node)$"),
175
+ detail: str = Detail,
176
+ ):
177
+ """Float32 per element (or, with at=node, per mesh node, where the store holds the depth at
178
+ its nodes): the bed's height (m, positive up), or the ground's for an atmosphere; 404 when
179
+ the store holds none."""
180
+
181
+ def body():
182
+ view = _view(dataset_id, detail)
183
+ _cells_only(view)
184
+ b = view.bed_nodes() if at == "node" else view.bed()
185
+ if b is None:
186
+ raise HTTPException(status_code=404, detail="this store holds no bed")
187
+ return np.asarray(b, "<f4").tobytes()
188
+
189
+ return Response(await _run(body), media_type=BINARY)
190
+
191
+
192
+ @router.get("/{dataset_id}/point")
193
+ async def point(
194
+ dataset_id: str,
195
+ lon: float = Query(..., ge=-180, le=180),
196
+ lat: float = Query(..., ge=-90, le=90),
197
+ field: str = Query(...),
198
+ layer: int = Query(0, ge=0),
199
+ t: int = Query(0, ge=0),
200
+ detail: str = Detail,
201
+ ):
202
+ """The cell under a point: value, layer height, bed, source cell index, record time (for a
203
+ store of sites, the nearest site)."""
204
+
205
+ def body():
206
+ view = _view(dataset_id, detail)
207
+ _field(view, field)
208
+ return view.point(lon, lat, field, t, layer)
209
+
210
+ return JSONResponse(await _run(body))
211
+
212
+
213
+ @router.get("/{dataset_id}/section")
214
+ async def section(
215
+ dataset_id: str,
216
+ pts: str = Query(..., description="lon,lat;lon,lat;... (two or more points)"),
217
+ field: str = Query(...),
218
+ t: int = Query(0, ge=0),
219
+ n: int = Query(200, ge=2, le=1000),
220
+ detail: str = Detail,
221
+ ):
222
+ """Values in every layer at n points along a polyline, each from its host cell."""
223
+
224
+ def body():
225
+ try:
226
+ points = [[float(x) for x in p.split(",")] for p in pts.split(";") if p]
227
+ except ValueError:
228
+ raise HTTPException(
229
+ status_code=422, detail="pts must be lon,lat;lon,lat;..."
230
+ )
231
+ if len(points) > 50:
232
+ raise HTTPException(status_code=422, detail="at most 50 points")
233
+ view = _view(dataset_id, detail)
234
+ _cells_only(view)
235
+ _field(view, field)
236
+ return view.section(points, field, t, n)
237
+
238
+ return JSONResponse(await _run(body))
239
+
240
+
241
+ @router.get("/{dataset_id}/tracers")
242
+ async def tracers(
243
+ dataset_id: str,
244
+ pair: str = Query(..., description="speed or wind_speed"),
245
+ t: int = Query(0, ge=0),
246
+ levels: int = Query(6, ge=1, le=12),
247
+ limit: int = Query(3000, ge=10, le=20000),
248
+ detail: str = Detail,
249
+ ):
250
+ """East and north components for tracers kept inside their own cells: up to `limit`
251
+ columns (thinned evenly, the same at every level), each column's element, and up to
252
+ `levels` layers from the surface down with their heights."""
253
+
254
+ def body():
255
+ view = _view(dataset_id, detail)
256
+ _cells_only(view)
257
+ return view.tracers(pair, t, levels, limit)
258
+
259
+ return JSONResponse(await _run(body))