forcingkit 0.22.1__tar.gz → 0.23.0__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 (161) hide show
  1. {forcingkit-0.22.1 → forcingkit-0.23.0}/PKG-INFO +1 -1
  2. {forcingkit-0.22.1 → forcingkit-0.23.0}/docs/source/cache_viewer.rst +6 -4
  3. {forcingkit-0.22.1 → forcingkit-0.23.0}/docs/source/conf.py +1 -1
  4. {forcingkit-0.22.1 → forcingkit-0.23.0}/docs/source/mesh_frames.rst +9 -2
  5. {forcingkit-0.22.1 → forcingkit-0.23.0}/pyproject.toml +1 -1
  6. {forcingkit-0.22.1 → forcingkit-0.23.0}/service/forcingkit_serve/routers/viewer.py +44 -8
  7. {forcingkit-0.22.1 → forcingkit-0.23.0}/service/forcingkit_serve/view_store.py +18 -8
  8. forcingkit-0.23.0/src/forcingkit/ramps/currents_tempo.csv +69 -0
  9. forcingkit-0.23.0/src/forcingkit/ramps/currents_tempo_dark.csv +69 -0
  10. {forcingkit-0.22.1 → forcingkit-0.23.0}/src/forcingkit/render.py +25 -0
  11. {forcingkit-0.22.1 → forcingkit-0.23.0}/static/app.js +34 -13
  12. {forcingkit-0.22.1 → forcingkit-0.23.0}/tests/unit/test_cache_inventory.py +35 -0
  13. {forcingkit-0.22.1 → forcingkit-0.23.0}/tests/unit/test_mesh_frames.py +37 -1
  14. {forcingkit-0.22.1 → forcingkit-0.23.0}/tests/unit/test_view_store.py +3 -0
  15. {forcingkit-0.22.1 → forcingkit-0.23.0}/uv.lock +1 -1
  16. {forcingkit-0.22.1 → forcingkit-0.23.0}/.agents/forcingkit.md +0 -0
  17. {forcingkit-0.22.1 → forcingkit-0.23.0}/.claude/CLAUDE.md +0 -0
  18. {forcingkit-0.22.1 → forcingkit-0.23.0}/.env.template +0 -0
  19. {forcingkit-0.22.1 → forcingkit-0.23.0}/.github/copilot-instructions.md +0 -0
  20. {forcingkit-0.22.1 → forcingkit-0.23.0}/.github/workflows/docs.yml +0 -0
  21. {forcingkit-0.22.1 → forcingkit-0.23.0}/.github/workflows/publish-client.yml +0 -0
  22. {forcingkit-0.22.1 → forcingkit-0.23.0}/.github/workflows/publish.yml +0 -0
  23. {forcingkit-0.22.1 → forcingkit-0.23.0}/.github/workflows/tests.yml +0 -0
  24. {forcingkit-0.22.1 → forcingkit-0.23.0}/.gitignore +0 -0
  25. {forcingkit-0.22.1 → forcingkit-0.23.0}/.markdownlint.yaml +0 -0
  26. {forcingkit-0.22.1 → forcingkit-0.23.0}/.pre-commit-config.yaml +0 -0
  27. {forcingkit-0.22.1 → forcingkit-0.23.0}/.python-version +0 -0
  28. {forcingkit-0.22.1 → forcingkit-0.23.0}/AGENTS.md +0 -0
  29. {forcingkit-0.22.1 → forcingkit-0.23.0}/CONTRIBUTING.md +0 -0
  30. {forcingkit-0.22.1 → forcingkit-0.23.0}/Dockerfile +0 -0
  31. {forcingkit-0.22.1 → forcingkit-0.23.0}/LICENSE +0 -0
  32. {forcingkit-0.22.1 → forcingkit-0.23.0}/README.md +0 -0
  33. {forcingkit-0.22.1 → forcingkit-0.23.0}/client/LICENSE +0 -0
  34. {forcingkit-0.22.1 → forcingkit-0.23.0}/client/README.md +0 -0
  35. {forcingkit-0.22.1 → forcingkit-0.23.0}/client/pyproject.toml +0 -0
  36. {forcingkit-0.22.1 → forcingkit-0.23.0}/client/src/forcingkit_client/__init__.py +0 -0
  37. {forcingkit-0.22.1 → forcingkit-0.23.0}/client/src/forcingkit_client/client.py +0 -0
  38. {forcingkit-0.22.1 → forcingkit-0.23.0}/client/src/forcingkit_client/schema.py +0 -0
  39. {forcingkit-0.22.1 → forcingkit-0.23.0}/client/src/forcingkit_client/store.py +0 -0
  40. {forcingkit-0.22.1 → forcingkit-0.23.0}/client/src/forcingkit_client/trajectory.py +0 -0
  41. {forcingkit-0.22.1 → forcingkit-0.23.0}/client/tests/conftest.py +0 -0
  42. {forcingkit-0.22.1 → forcingkit-0.23.0}/client/tests/test_client.py +0 -0
  43. {forcingkit-0.22.1 → forcingkit-0.23.0}/client/tests/test_schema.py +0 -0
  44. {forcingkit-0.22.1 → forcingkit-0.23.0}/client/tests/test_trajectory.py +0 -0
  45. {forcingkit-0.22.1 → forcingkit-0.23.0}/client/uv.lock +0 -0
  46. {forcingkit-0.22.1 → forcingkit-0.23.0}/docker-compose.yml +0 -0
  47. {forcingkit-0.22.1 → forcingkit-0.23.0}/docs/Makefile +0 -0
  48. {forcingkit-0.22.1 → forcingkit-0.23.0}/docs/make.bat +0 -0
  49. {forcingkit-0.22.1 → forcingkit-0.23.0}/docs/requirements-docs.txt +0 -0
  50. {forcingkit-0.22.1 → forcingkit-0.23.0}/docs/source/_extra/CNAME +0 -0
  51. {forcingkit-0.22.1 → forcingkit-0.23.0}/docs/source/_static/forcingkit-noreaster-wind.gif +0 -0
  52. {forcingkit-0.22.1 → forcingkit-0.23.0}/docs/source/atmospheric_forcing.rst +0 -0
  53. {forcingkit-0.22.1 → forcingkit-0.23.0}/docs/source/client.rst +0 -0
  54. {forcingkit-0.22.1 → forcingkit-0.23.0}/docs/source/doppio.rst +0 -0
  55. {forcingkit-0.22.1 → forcingkit-0.23.0}/docs/source/fetchers.rst +0 -0
  56. {forcingkit-0.22.1 → forcingkit-0.23.0}/docs/source/hycom.rst +0 -0
  57. {forcingkit-0.22.1 → forcingkit-0.23.0}/docs/source/index.rst +0 -0
  58. {forcingkit-0.22.1 → forcingkit-0.23.0}/docs/source/layered_mesh.rst +0 -0
  59. {forcingkit-0.22.1 → forcingkit-0.23.0}/docs/source/necofs.rst +0 -0
  60. {forcingkit-0.22.1 → forcingkit-0.23.0}/docs/source/nyofs.rst +0 -0
  61. {forcingkit-0.22.1 → forcingkit-0.23.0}/docs/source/rivers.rst +0 -0
  62. {forcingkit-0.22.1 → forcingkit-0.23.0}/docs/source/roadmap.rst +0 -0
  63. {forcingkit-0.22.1 → forcingkit-0.23.0}/docs/source/shelf_models.rst +0 -0
  64. {forcingkit-0.22.1 → forcingkit-0.23.0}/docs/source/sources.rst +0 -0
  65. {forcingkit-0.22.1 → forcingkit-0.23.0}/docs/source/waves.rst +0 -0
  66. {forcingkit-0.22.1 → forcingkit-0.23.0}/main.py +0 -0
  67. {forcingkit-0.22.1 → forcingkit-0.23.0}/service/__init__.py +0 -0
  68. {forcingkit-0.22.1 → forcingkit-0.23.0}/service/forcingkit_serve/__init__.py +0 -0
  69. {forcingkit-0.22.1 → forcingkit-0.23.0}/service/forcingkit_serve/jobs.py +0 -0
  70. {forcingkit-0.22.1 → forcingkit-0.23.0}/service/forcingkit_serve/main.py +0 -0
  71. {forcingkit-0.22.1 → forcingkit-0.23.0}/service/forcingkit_serve/routers/bathymetry.py +0 -0
  72. {forcingkit-0.22.1 → forcingkit-0.23.0}/service/forcingkit_serve/routers/removed.py +0 -0
  73. {forcingkit-0.22.1 → forcingkit-0.23.0}/service/forcingkit_serve/routers/stores.py +0 -0
  74. {forcingkit-0.22.1 → forcingkit-0.23.0}/service/forcingkit_serve/routers/view.py +0 -0
  75. {forcingkit-0.22.1 → forcingkit-0.23.0}/service/forcingkit_serve/stac.py +0 -0
  76. {forcingkit-0.22.1 → forcingkit-0.23.0}/service/run_server.py +0 -0
  77. {forcingkit-0.22.1 → forcingkit-0.23.0}/src/forcingkit/__init__.py +0 -0
  78. {forcingkit-0.22.1 → forcingkit-0.23.0}/src/forcingkit/data/rivers/northeast_us.json +0 -0
  79. {forcingkit-0.22.1 → forcingkit-0.23.0}/src/forcingkit/dispatcher.py +0 -0
  80. {forcingkit-0.22.1 → forcingkit-0.23.0}/src/forcingkit/fetchers/coastwatch.py +0 -0
  81. {forcingkit-0.22.1 → forcingkit-0.23.0}/src/forcingkit/fetchers/dbofs.py +0 -0
  82. {forcingkit-0.22.1 → forcingkit-0.23.0}/src/forcingkit/fetchers/doppio.py +0 -0
  83. {forcingkit-0.22.1 → forcingkit-0.23.0}/src/forcingkit/fetchers/erddap.py +0 -0
  84. {forcingkit-0.22.1 → forcingkit-0.23.0}/src/forcingkit/fetchers/hfradar.py +0 -0
  85. {forcingkit-0.22.1 → forcingkit-0.23.0}/src/forcingkit/fetchers/hrdps.py +0 -0
  86. {forcingkit-0.22.1 → forcingkit-0.23.0}/src/forcingkit/fetchers/hrrr.py +0 -0
  87. {forcingkit-0.22.1 → forcingkit-0.23.0}/src/forcingkit/fetchers/hrrr_atmosphere.py +0 -0
  88. {forcingkit-0.22.1 → forcingkit-0.23.0}/src/forcingkit/fetchers/hrrr_levels.py +0 -0
  89. {forcingkit-0.22.1 → forcingkit-0.23.0}/src/forcingkit/fetchers/hrrr_points.py +0 -0
  90. {forcingkit-0.22.1 → forcingkit-0.23.0}/src/forcingkit/fetchers/hycom.py +0 -0
  91. {forcingkit-0.22.1 → forcingkit-0.23.0}/src/forcingkit/fetchers/hydrography.py +0 -0
  92. {forcingkit-0.22.1 → forcingkit-0.23.0}/src/forcingkit/fetchers/ndbc.py +0 -0
  93. {forcingkit-0.22.1 → forcingkit-0.23.0}/src/forcingkit/fetchers/necofs.py +0 -0
  94. {forcingkit-0.22.1 → forcingkit-0.23.0}/src/forcingkit/fetchers/noaa.py +0 -0
  95. {forcingkit-0.22.1 → forcingkit-0.23.0}/src/forcingkit/fetchers/nwps.py +0 -0
  96. {forcingkit-0.22.1 → forcingkit-0.23.0}/src/forcingkit/fetchers/nyofs.py +0 -0
  97. {forcingkit-0.22.1 → forcingkit-0.23.0}/src/forcingkit/fetchers/usgs.py +0 -0
  98. {forcingkit-0.22.1 → forcingkit-0.23.0}/src/forcingkit/fetchers/usgs_rivers.py +0 -0
  99. {forcingkit-0.22.1 → forcingkit-0.23.0}/src/forcingkit/layered_mesh.py +0 -0
  100. {forcingkit-0.22.1 → forcingkit-0.23.0}/src/forcingkit/mesh_frames.py +0 -0
  101. {forcingkit-0.22.1 → forcingkit-0.23.0}/src/forcingkit/ramps/currents_lis.csv +0 -0
  102. {forcingkit-0.22.1 → forcingkit-0.23.0}/src/forcingkit/ramps/currents_lis_dark.csv +0 -0
  103. {forcingkit-0.22.1 → forcingkit-0.23.0}/src/forcingkit/ramps/currents_lis_deep.csv +0 -0
  104. {forcingkit-0.22.1 → forcingkit-0.23.0}/src/forcingkit/ramps/currents_lis_haline.csv +0 -0
  105. {forcingkit-0.22.1 → forcingkit-0.23.0}/src/forcingkit/settings.py +0 -0
  106. {forcingkit-0.22.1 → forcingkit-0.23.0}/src/forcingkit/zarr_stream.py +0 -0
  107. {forcingkit-0.22.1 → forcingkit-0.23.0}/static/cells_map.js +0 -0
  108. {forcingkit-0.22.1 → forcingkit-0.23.0}/static/coverage.js +0 -0
  109. {forcingkit-0.22.1 → forcingkit-0.23.0}/static/favicon.ico +0 -0
  110. {forcingkit-0.22.1 → forcingkit-0.23.0}/static/favicon.svg +0 -0
  111. {forcingkit-0.22.1 → forcingkit-0.23.0}/static/index.html +0 -0
  112. {forcingkit-0.22.1 → forcingkit-0.23.0}/static/logo.svg +0 -0
  113. {forcingkit-0.22.1 → forcingkit-0.23.0}/static/preview.js +0 -0
  114. {forcingkit-0.22.1 → forcingkit-0.23.0}/static/scene3d.js +0 -0
  115. {forcingkit-0.22.1 → forcingkit-0.23.0}/static/styles.css +0 -0
  116. {forcingkit-0.22.1 → forcingkit-0.23.0}/static/view_api.js +0 -0
  117. {forcingkit-0.22.1 → forcingkit-0.23.0}/tests/__init__.py +0 -0
  118. {forcingkit-0.22.1 → forcingkit-0.23.0}/tests/integration/test_auth.py +0 -0
  119. {forcingkit-0.22.1 → forcingkit-0.23.0}/tests/integration/test_erddap_fetch.py +0 -0
  120. {forcingkit-0.22.1 → forcingkit-0.23.0}/tests/integration/test_mesh_frames_necofs.py +0 -0
  121. {forcingkit-0.22.1 → forcingkit-0.23.0}/tests/integration/test_necofs_volume_live.py +0 -0
  122. {forcingkit-0.22.1 → forcingkit-0.23.0}/tests/integration/test_nwps_nomads.py +0 -0
  123. {forcingkit-0.22.1 → forcingkit-0.23.0}/tests/integration/test_nyofs_obc_fetch.py +0 -0
  124. {forcingkit-0.22.1 → forcingkit-0.23.0}/tests/integration/test_obc_offshore_nj.py +0 -0
  125. {forcingkit-0.22.1 → forcingkit-0.23.0}/tests/integration/test_ofs_archive_paths.py +0 -0
  126. {forcingkit-0.22.1 → forcingkit-0.23.0}/tests/integration/test_s3_roms_fetchers.py +0 -0
  127. {forcingkit-0.22.1 → forcingkit-0.23.0}/tests/scripts/inspect_dem.py +0 -0
  128. {forcingkit-0.22.1 → forcingkit-0.23.0}/tests/scripts/inspect_grib.py +0 -0
  129. {forcingkit-0.22.1 → forcingkit-0.23.0}/tests/scripts/inspect_zarr.py +0 -0
  130. {forcingkit-0.22.1 → forcingkit-0.23.0}/tests/unit/data/doppio_reanalysis_20220811_corner.nc +0 -0
  131. {forcingkit-0.22.1 → forcingkit-0.23.0}/tests/unit/test_coastwatch.py +0 -0
  132. {forcingkit-0.22.1 → forcingkit-0.23.0}/tests/unit/test_dbofs.py +0 -0
  133. {forcingkit-0.22.1 → forcingkit-0.23.0}/tests/unit/test_dispatcher.py +0 -0
  134. {forcingkit-0.22.1 → forcingkit-0.23.0}/tests/unit/test_doppio.py +0 -0
  135. {forcingkit-0.22.1 → forcingkit-0.23.0}/tests/unit/test_erddap.py +0 -0
  136. {forcingkit-0.22.1 → forcingkit-0.23.0}/tests/unit/test_hfradar.py +0 -0
  137. {forcingkit-0.22.1 → forcingkit-0.23.0}/tests/unit/test_hrdps.py +0 -0
  138. {forcingkit-0.22.1 → forcingkit-0.23.0}/tests/unit/test_hrrr_atm.py +0 -0
  139. {forcingkit-0.22.1 → forcingkit-0.23.0}/tests/unit/test_hrrr_idx.py +0 -0
  140. {forcingkit-0.22.1 → forcingkit-0.23.0}/tests/unit/test_hrrr_levels.py +0 -0
  141. {forcingkit-0.22.1 → forcingkit-0.23.0}/tests/unit/test_hrrr_points.py +0 -0
  142. {forcingkit-0.22.1 → forcingkit-0.23.0}/tests/unit/test_hycom.py +0 -0
  143. {forcingkit-0.22.1 → forcingkit-0.23.0}/tests/unit/test_jobs.py +0 -0
  144. {forcingkit-0.22.1 → forcingkit-0.23.0}/tests/unit/test_layered_mesh.py +0 -0
  145. {forcingkit-0.22.1 → forcingkit-0.23.0}/tests/unit/test_main.py +0 -0
  146. {forcingkit-0.22.1 → forcingkit-0.23.0}/tests/unit/test_ndbc.py +0 -0
  147. {forcingkit-0.22.1 → forcingkit-0.23.0}/tests/unit/test_necofs_hindcast.py +0 -0
  148. {forcingkit-0.22.1 → forcingkit-0.23.0}/tests/unit/test_necofs_mesh_cache.py +0 -0
  149. {forcingkit-0.22.1 → forcingkit-0.23.0}/tests/unit/test_necofs_parent.py +0 -0
  150. {forcingkit-0.22.1 → forcingkit-0.23.0}/tests/unit/test_necofs_volume.py +0 -0
  151. {forcingkit-0.22.1 → forcingkit-0.23.0}/tests/unit/test_noaa_currents.py +0 -0
  152. {forcingkit-0.22.1 → forcingkit-0.23.0}/tests/unit/test_noaa_datum.py +0 -0
  153. {forcingkit-0.22.1 → forcingkit-0.23.0}/tests/unit/test_nwps.py +0 -0
  154. {forcingkit-0.22.1 → forcingkit-0.23.0}/tests/unit/test_nyofs.py +0 -0
  155. {forcingkit-0.22.1 → forcingkit-0.23.0}/tests/unit/test_obc_donor_report.py +0 -0
  156. {forcingkit-0.22.1 → forcingkit-0.23.0}/tests/unit/test_obc_pipeline.py +0 -0
  157. {forcingkit-0.22.1 → forcingkit-0.23.0}/tests/unit/test_removed_routes.py +0 -0
  158. {forcingkit-0.22.1 → forcingkit-0.23.0}/tests/unit/test_settings.py +0 -0
  159. {forcingkit-0.22.1 → forcingkit-0.23.0}/tests/unit/test_usgs.py +0 -0
  160. {forcingkit-0.22.1 → forcingkit-0.23.0}/tests/unit/test_usgs_rivers.py +0 -0
  161. {forcingkit-0.22.1 → forcingkit-0.23.0}/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.22.1
3
+ Version: 0.23.0
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
@@ -3,8 +3,9 @@ Cache viewer
3
3
 
4
4
  The service serves a page at ``/ui/`` that lists every store in ``FORCINGKIT_CACHE_DIR``: the
5
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.
6
+ ``/api/v1/cache/inventory`` every five seconds while it is visible, so new stores appear while a
7
+ request is still running. The response carries an ETag, and a poll that sends it back in
8
+ ``If-None-Match`` gets 304 with no body when nothing changed.
8
9
 
9
10
  Coverage
10
11
  --------
@@ -56,8 +57,9 @@ The preview draws what the store holds and nothing more:
56
57
  - **Fixed scales.** A field's scale is set once per store from the 1st to the 99th percentile of
57
58
  its values weighted by cell area (symmetric about zero, at the 99.5th percentile of the
58
59
  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.
60
+ Water speed uses the packaged ``currents_tempo_dark`` ramp at its own speeds (0.02 to 3.1 m/s on
61
+ a log axis), so different stores compare directly. Temperature is drawn on cmocean "thermal" and
62
+ salinity on "haline", the maps oceanographers know for them.
61
63
  - **True heights.** Layers run from the surface down and are labeled with their mean depth:
62
64
  fixed levels from the store's vertical coordinate, sigma layers from ``siglay`` and the water
63
65
  depth ``h``, atmosphere levels from their heights. Sigma layers in a store without ``h`` are
@@ -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.22.1"
12
+ release = "0.23.0"
13
13
 
14
14
  extensions = [
15
15
  "sphinx.ext.autodoc",
@@ -38,7 +38,8 @@ Colour
38
38
 
39
39
  - ``default_color``: viridis, linear over 0 to 1.5 m/s;
40
40
  - ``named_color(name, vmin, vmax, log=False, floor=None)``: a built-in ramp (``viridis``,
41
- ``greys``) over a chosen range;
41
+ ``greys``, and cmocean's ``thermal`` for temperature and ``haline`` for salinity) over a chosen
42
+ range;
42
43
  - ``lut_color(rows, log=False, floor=None)``: a lookup table of ``(value, r, g, b[, a])`` rows.
43
44
  Values below the first row, or below ``floor``, take the first colour; between rows each channel
44
45
  is interpolated linearly in the value, or in log(value) when ``log`` is true; values above the
@@ -56,7 +57,13 @@ Colour
56
57
  teal and navy to deep purple) and "haline" (dark backgrounds: indigo through blue and green to
57
58
  pale yellow). They separate speeds more strongly than the single-hue pair, but they are not
58
59
  mirror images: purple is fast in one and slow in the other. Use them for a field shown alone
59
- with its legend, not beside other colour-mapped layers.
60
+ with its legend, not beside other colour-mapped layers. Haline is cmocean's salinity map, so a
61
+ reader may take it for salinity;
62
+ - ``packaged_color("currents_tempo")`` and ``packaged_color("currents_tempo_dark")``: after cmocean
63
+ "tempo" on the same speeds, near white at slack through teal-green to deep teal on a light
64
+ basemap, and the reverse on a dark one, so the pair swaps by theme alone. This is the currents
65
+ ramp the Long Horizon Observatory's sites and viewers share; temperature takes cmocean
66
+ "thermal" and salinity "haline".
60
67
 
61
68
  Python
62
69
  ------
@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
4
4
 
5
5
  [project]
6
6
  name = "forcingkit"
7
- version = "0.22.1"
7
+ version = "0.23.0"
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"
@@ -1,5 +1,9 @@
1
+ import hashlib
2
+ import json
3
+ import os
1
4
  from pathlib import Path
2
- from fastapi import APIRouter, HTTPException, Response as FastAPIResponse
5
+ from fastapi import APIRouter, HTTPException, Request, Response as FastAPIResponse
6
+ from fastapi.encoders import jsonable_encoder
3
7
  from pydantic import BaseModel
4
8
  from typing import List
5
9
  import logging
@@ -386,12 +390,43 @@ def _zarr_key(path: Path) -> tuple:
386
390
 
387
391
 
388
392
  @router.get("/inventory", response_model=List[CacheItem])
389
- async def get_cache_inventory(response: FastAPIResponse):
390
- """Crawls the local data cache and returns an inventory of all processed forcing datasets."""
393
+ async def get_cache_inventory(request: Request):
394
+ """Crawls the local data cache and returns an inventory of all processed forcing datasets.
395
+
396
+ The response carries an ETag; a request whose ``If-None-Match`` matches gets 304 and no
397
+ body, so a page polling for changes downloads the list only when it changed."""
391
398
  from starlette.concurrency import run_in_threadpool
392
399
 
393
- response.headers["Cache-Control"] = "no-store"
394
- return await run_in_threadpool(_crawl_inventory)
400
+ items = await run_in_threadpool(_crawl_inventory)
401
+ body = json.dumps(
402
+ jsonable_encoder(items), separators=(",", ":"), ensure_ascii=False
403
+ ).encode()
404
+ etag = '"' + hashlib.sha256(body).hexdigest()[:32] + '"'
405
+ headers = {"Cache-Control": "no-cache", "ETag": etag}
406
+ if request.headers.get("if-none-match") == etag:
407
+ return FastAPIResponse(status_code=304, headers=headers)
408
+ return FastAPIResponse(body, media_type="application/json", headers=headers)
409
+
410
+
411
+ def _cache_entries(cache_dir: Path) -> tuple[list[Path], dict[str, list[Path]]]:
412
+ """The cache's Zarr store directories and its raw donor files (by suffix), in one walk
413
+ that does not descend into a store: a store holds thousands of chunk files, and listing
414
+ them on every poll was most of the crawl's time."""
415
+ zarr_dirs: list[Path] = []
416
+ files: dict[str, list[Path]] = {".grib": [], ".grib2": [], ".nc": []}
417
+ for root, dirs, names in os.walk(cache_dir):
418
+ keep = []
419
+ for d in sorted(dirs):
420
+ if d.endswith(".zarr"):
421
+ zarr_dirs.append(Path(root) / d)
422
+ else:
423
+ keep.append(d)
424
+ dirs[:] = keep
425
+ for n in sorted(names):
426
+ suffix = os.path.splitext(n)[1]
427
+ if suffix in files:
428
+ files[suffix].append(Path(root) / n)
429
+ return zarr_dirs, files
395
430
 
396
431
 
397
432
  def _crawl_inventory() -> list[CacheItem]:
@@ -400,10 +435,11 @@ def _crawl_inventory() -> list[CacheItem]:
400
435
  return []
401
436
 
402
437
  inventory = []
438
+ zarr_dirs, donor_files = _cache_entries(cache_dir)
403
439
 
404
440
  # 1. Find Zarr datasets (directories)
405
441
  seen: set[str] = set()
406
- for zarr_path in cache_dir.rglob("*.zarr"):
442
+ for zarr_path in zarr_dirs:
407
443
  if zarr_path.is_dir():
408
444
  seen.add(str(zarr_path))
409
445
  try:
@@ -431,8 +467,8 @@ def _crawl_inventory() -> list[CacheItem]:
431
467
  _INVENTORY_CACHE[str(zarr_path)] = (ckey, inventory[-1])
432
468
 
433
469
  # 2. Find GRIB/NC datasets (files)
434
- for ext_glob in ["*.grib", "*.grib2", "*.nc"]:
435
- for file_path in cache_dir.rglob(ext_glob):
470
+ for suffix in (".grib", ".grib2", ".nc"):
471
+ for file_path in donor_files.get(suffix, []):
436
472
  if file_path.is_file():
437
473
  seen.add(str(file_path))
438
474
  st = file_path.stat()
@@ -39,7 +39,7 @@ from forcingkit.layered_mesh import (
39
39
  to_local,
40
40
  weighted_percentile,
41
41
  )
42
- from forcingkit.render import PACKAGED_RAMPS, lut_color, packaged_ramp_rows
42
+ from forcingkit.render import PACKAGED_RAMPS, RAMPS, lut_color, packaged_ramp_rows
43
43
 
44
44
  logger = logging.getLogger(__name__)
45
45
 
@@ -52,7 +52,7 @@ SCALE_LAYERS = 8
52
52
  VOLUME_CACHE_BYTES = 256 * 2**20
53
53
  # Water speed is drawn on the packaged currents ramp at its own speeds, so maps of different
54
54
  # stores compare directly.
55
- WATER_SPEED_RAMP = "currents_lis_dark"
55
+ WATER_SPEED_RAMP = "currents_tempo_dark"
56
56
 
57
57
  _TIME_DIMS = ("time", "ocean_time", "valid_time")
58
58
  _VERTICAL_DIMS = ("z", "depth", "level", "s_rho", "siglay", "sigma", "lev")
@@ -141,13 +141,14 @@ _UNITS = {
141
141
  "m3 s-1": "m³/s",
142
142
  }
143
143
  _SYMMETRIC = {"u", "v", "w", "ww", "water_u", "water_v", "u10", "v10", "zeta"}
144
+ # cmocean's maps for temperature and salinity (forcingkit.render.RAMPS), as the community reads them.
144
145
  _RAMPS = {
145
- "temp": "plasma",
146
- "temperature": "plasma",
147
- "t2m": "plasma",
148
- "t": "plasma",
149
- "salt": "cividis",
150
- "salinity": "cividis",
146
+ "temp": "thermal",
147
+ "temperature": "thermal",
148
+ "t2m": "thermal",
149
+ "t": "thermal",
150
+ "salt": "haline",
151
+ "salinity": "haline",
151
152
  "h": "cividis",
152
153
  }
153
154
 
@@ -219,6 +220,15 @@ def _ramp_rgba(meta: FieldMeta, ramp: str) -> bytes:
219
220
  if ramp in PACKAGED_RAMPS:
220
221
  color = lut_color(packaged_ramp_rows(ramp), **PACKAGED_RAMPS[ramp])
221
222
  rgba[1:] = color(meta.decode(codes[1:]))
223
+ elif ramp in RAMPS:
224
+ knots = np.array(RAMPS[ramp], dtype=float)
225
+ f = (codes[1:] - 1) / 254.0
226
+ rgba[1:, :3] = np.rint(
227
+ np.stack(
228
+ [np.interp(f, knots[:, 0], knots[:, k]) for k in (1, 2, 3)], axis=1
229
+ )
230
+ ).astype(np.uint8)
231
+ rgba[1:, 3] = 255
222
232
  else:
223
233
  from matplotlib import colormaps
224
234
 
@@ -0,0 +1,69 @@
1
+ # Currents speed ramp after cmocean "tempo" (Thyng et al. 2016; cmocean is MIT licensed), for a light
2
+ # basemap: speed_m_s,r,g,b (sRGB), on the same speeds as currents_lis. Interpolate in log(speed); speeds below
3
+ # the first row take its colour (floor 0.02 m/s) and speeds above the last row (3.1 m/s) clamp to it.
4
+ # Near white at slack through sage and teal to navy, lightness falling with speed. Colormap
5
+ # position is piecewise linear in log(speed): 0.02 -> 0, 0.494 -> 0.29, 2.418 -> 0.80, 3.097 -> 1.0.
6
+ # Knots from 2026 NOAA CO-OPS current predictions (MAX_SLACK), Long Island Sound and Block Island
7
+ # Sound: regional median daily maximum 0.494 m/s; ACT2611 Little Gull Island median daily maximum
8
+ # 2.418 m/s, 95th percentile 2.964 m/s, annual maximum 3.097 m/s.
9
+ speed_m_s,r,g,b
10
+ 0.0200,255,246,244
11
+ 0.0221,252,244,241
12
+ 0.0244,249,242,238
13
+ 0.0270,247,240,235
14
+ 0.0299,242,237,231
15
+ 0.0330,240,235,228
16
+ 0.0365,237,234,225
17
+ 0.0403,233,231,221
18
+ 0.0446,230,229,218
19
+ 0.0493,227,227,215
20
+ 0.0545,223,225,211
21
+ 0.0602,220,223,208
22
+ 0.0666,217,221,205
23
+ 0.0736,213,219,201
24
+ 0.0813,210,217,199
25
+ 0.0899,207,216,196
26
+ 0.0994,203,213,192
27
+ 0.1099,200,212,190
28
+ 0.1215,197,210,187
29
+ 0.1343,192,208,183
30
+ 0.1484,189,206,181
31
+ 0.1641,186,205,179
32
+ 0.1813,182,203,175
33
+ 0.2005,179,201,173
34
+ 0.2216,176,200,171
35
+ 0.2449,172,198,169
36
+ 0.2708,168,196,165
37
+ 0.2993,164,195,163
38
+ 0.3309,161,193,161
39
+ 0.3657,156,191,159
40
+ 0.4043,153,190,157
41
+ 0.4469,150,188,155
42
+ 0.4940,145,186,152
43
+ 0.5348,134,182,147
44
+ 0.5790,122,177,142
45
+ 0.6269,111,173,139
46
+ 0.6787,97,169,135
47
+ 0.7348,86,164,133
48
+ 0.7955,71,159,130
49
+ 0.8613,59,155,129
50
+ 0.9324,46,149,128
51
+ 1.0095,36,144,127
52
+ 1.0929,26,138,125
53
+ 1.1833,19,132,123
54
+ 1.2810,17,126,122
55
+ 1.3869,17,119,119
56
+ 1.5015,19,114,117
57
+ 1.6256,22,107,114
58
+ 1.7600,24,101,111
59
+ 1.9054,26,95,107
60
+ 2.0629,27,89,104
61
+ 2.2334,28,83,100
62
+ 2.4180,28,77,97
63
+ 2.5198,28,69,91
64
+ 2.6259,27,62,87
65
+ 2.7365,26,54,81
66
+ 2.8518,25,46,77
67
+ 2.9719,23,37,72
68
+ 3.0970,21,29,68
69
+ 3.1000,21,29,68
@@ -0,0 +1,69 @@
1
+ # Currents speed ramp after cmocean "tempo", reversed, for a dark basemap (Thyng et al. 2016; cmocean is MIT
2
+ # licensed): speed_m_s,r,g,b (sRGB), on the same speeds as currents_tempo, so the two swap by theme alone.
3
+ # Interpolate in log(speed); speeds below the first row take its colour (floor 0.02 m/s) and speeds above the
4
+ # last row (3.1 m/s) clamp to it. Navy at slack through teal and sage to near white, lightness rising with
5
+ # speed. Colormap position is 1 minus currents_tempo's, piecewise linear in log(speed) through the same knots.
6
+ # Knots from 2026 NOAA CO-OPS current predictions (MAX_SLACK), Long Island Sound and Block Island
7
+ # Sound: regional median daily maximum 0.494 m/s; ACT2611 Little Gull Island median daily maximum
8
+ # 2.418 m/s, 95th percentile 2.964 m/s, annual maximum 3.097 m/s.
9
+ speed_m_s,r,g,b
10
+ 0.0200,21,29,68
11
+ 0.0221,21,31,69
12
+ 0.0244,22,33,70
13
+ 0.0270,22,35,71
14
+ 0.0299,23,38,72
15
+ 0.0330,23,40,74
16
+ 0.0365,24,42,75
17
+ 0.0403,24,45,76
18
+ 0.0446,25,47,77
19
+ 0.0493,25,49,79
20
+ 0.0545,26,52,80
21
+ 0.0602,26,54,81
22
+ 0.0666,26,55,83
23
+ 0.0736,27,58,84
24
+ 0.0813,27,60,86
25
+ 0.0899,27,62,87
26
+ 0.0994,28,65,88
27
+ 0.1099,28,66,90
28
+ 0.1215,28,68,91
29
+ 0.1343,28,71,93
30
+ 0.1484,28,73,94
31
+ 0.1641,28,75,95
32
+ 0.1813,28,77,97
33
+ 0.2005,28,79,98
34
+ 0.2216,28,81,99
35
+ 0.2449,28,83,100
36
+ 0.2708,27,86,102
37
+ 0.2993,27,88,103
38
+ 0.3309,27,89,104
39
+ 0.3657,26,92,106
40
+ 0.4043,26,94,107
41
+ 0.4469,25,96,108
42
+ 0.4940,25,99,109
43
+ 0.5348,23,104,112
44
+ 0.5790,20,111,115
45
+ 0.6269,18,117,118
46
+ 0.6787,17,123,121
47
+ 0.7348,18,129,123
48
+ 0.7955,22,135,124
49
+ 0.8613,30,141,126
50
+ 0.9324,41,147,127
51
+ 1.0095,52,152,128
52
+ 1.0929,65,157,130
53
+ 1.1833,80,162,132
54
+ 1.2810,91,166,134
55
+ 1.3869,105,171,137
56
+ 1.5015,116,175,141
57
+ 1.6256,129,180,145
58
+ 1.7600,139,184,150
59
+ 1.9054,151,189,156
60
+ 2.0629,161,193,161
61
+ 2.2334,172,198,169
62
+ 2.4180,182,203,175
63
+ 2.5198,195,209,186
64
+ 2.6259,207,216,196
65
+ 2.7365,220,223,208
66
+ 2.8518,231,230,219
67
+ 2.9719,244,238,232
68
+ 3.0970,255,246,244
69
+ 3.1000,255,246,244
@@ -47,6 +47,26 @@ RAMPS: dict[str, list[tuple[float, int, int, int]]] = {
47
47
  (1.00, 253, 231, 37),
48
48
  ],
49
49
  "greys": [(0.0, 240, 240, 240), (1.0, 30, 30, 30)],
50
+ # Seven samples each of cmocean "thermal" (temperature) and "haline" (salinity), Thyng et al. 2016
51
+ # (cmocean is MIT licensed): the community's maps for those variables, low to high.
52
+ "thermal": [
53
+ (0 / 6, 4, 35, 51),
54
+ (1 / 6, 44, 51, 149),
55
+ (2 / 6, 116, 73, 146),
56
+ (3 / 6, 177, 95, 130),
57
+ (4 / 6, 235, 118, 85),
58
+ (5 / 6, 251, 180, 61),
59
+ (6 / 6, 232, 250, 91),
60
+ ],
61
+ "haline": [
62
+ (0 / 6, 42, 24, 108),
63
+ (1 / 6, 20, 67, 156),
64
+ (2 / 6, 32, 110, 139),
65
+ (3 / 6, 60, 147, 135),
66
+ (4 / 6, 90, 185, 120),
67
+ (5 / 6, 170, 216, 92),
68
+ (6 / 6, 253, 239, 154),
69
+ ],
50
70
  }
51
71
  DEFAULT_RAMP = "viridis"
52
72
  DEFAULT_VMAX = 1.5 # m/s
@@ -150,6 +170,11 @@ PACKAGED_RAMPS: dict[str, dict] = {
150
170
  # falling) and "haline" (dark; rising), for a field shown alone with its legend.
151
171
  "currents_lis_deep": {"log": True, "floor": 0.02},
152
172
  "currents_lis_haline": {"log": True, "floor": 0.02},
173
+ # After cmocean "tempo" on the same speeds: near white through sage and teal to navy (light
174
+ # basemaps, lightness falling) and its reverse (dark basemaps, rising), so the pair swaps by theme.
175
+ # The currents ramp shared by the Long Horizon Observatory's products; "haline" stays salinity.
176
+ "currents_tempo": {"log": True, "floor": 0.02},
177
+ "currents_tempo_dark": {"log": True, "floor": 0.02},
153
178
  }
154
179
 
155
180
 
@@ -89,8 +89,13 @@ document.addEventListener("DOMContentLoaded", () => {
89
89
  }
90
90
 
91
91
  // - Initial load, deep link and polling -
92
+ // The list is polled for new stores: every POLL_MS after the previous poll returns, not while
93
+ // the tab is hidden, and with the last ETag, so an unchanged list costs no download.
94
+ const POLL_MS = 5000;
92
95
  let inventoryFingerprint = "";
96
+ let inventoryEtag = null;
93
97
  let pollPaused = false;
98
+ let pollTimer = null;
94
99
  const fingerprint = (items) => items.map(i => `${i.id}:${i.modified_time}:${i.size_mb}`).join("|");
95
100
 
96
101
  fetchInventory().then(() => {
@@ -98,23 +103,38 @@ document.addEventListener("DOMContentLoaded", () => {
98
103
  const { id, want } = window.fkPreview.parseHash(window.location.hash);
99
104
  if (id && currentInventory.some(item => item.id === id)) selectById(id, want);
100
105
  }
101
- setInterval(pollInventory, 2000);
106
+ schedulePoll();
107
+ });
108
+
109
+ function schedulePoll(ms = POLL_MS) {
110
+ clearTimeout(pollTimer);
111
+ pollTimer = setTimeout(pollInventory, ms);
112
+ }
113
+
114
+ document.addEventListener("visibilitychange", () => {
115
+ if (!document.hidden) schedulePoll(0);
102
116
  });
103
117
 
104
118
  async function pollInventory() {
105
- if (pollPaused) return;
106
- try {
107
- const resp = await fetch("/api/v1/cache/inventory", { cache: "no-store" });
108
- if (!resp.ok) return;
109
- const items = await resp.json();
110
- const fp = fingerprint(items);
111
- if (fp === inventoryFingerprint) return;
112
- inventoryFingerprint = fp;
113
- currentInventory = items;
114
- renderInventory(items);
115
- } catch (_) {
116
- // A missed poll is retried two seconds later.
119
+ if (document.hidden) return; // resumed by visibilitychange
120
+ if (!pollPaused) {
121
+ try {
122
+ const headers = inventoryEtag ? { "If-None-Match": inventoryEtag } : {};
123
+ const resp = await fetch("/api/v1/cache/inventory", { cache: "no-store", headers });
124
+ if (resp.ok) {
125
+ inventoryEtag = resp.headers.get("ETag");
126
+ const items = await resp.json();
127
+ const fp = fingerprint(items);
128
+ if (fp !== inventoryFingerprint) {
129
+ inventoryFingerprint = fp;
130
+ currentInventory = items;
131
+ renderInventory(items);
132
+ }
133
+ }
134
+ // 304: unchanged. Other errors: a missed poll is retried at the next one.
135
+ } catch (_) { /* retried at the next poll */ }
117
136
  }
137
+ schedulePoll();
118
138
  }
119
139
 
120
140
  if (purgeBtn) {
@@ -189,6 +209,7 @@ document.addEventListener("DOMContentLoaded", () => {
189
209
  try {
190
210
  const resp = await fetch("/api/v1/cache/inventory", { cache: "no-store" });
191
211
  if (!resp.ok) throw new Error(`HTTP Error: ${resp.status}`);
212
+ inventoryEtag = resp.headers.get("ETag");
192
213
  currentInventory = await resp.json();
193
214
  inventoryFingerprint = fingerprint(currentInventory);
194
215
  renderInventory(currentInventory);
@@ -88,3 +88,38 @@ async def test_inventory_route_returns_the_structured_fields(tmp_path, monkeypat
88
88
  assert item["bbox"] == [-69.9, 39.7, -69.75, 39.82]
89
89
  assert item["time_end"] == "2022-08-11T02:00:00Z"
90
90
  assert (item["family"], item["kind"]) == ("Doppio", "ocean volume")
91
+
92
+
93
+ @pytest.mark.asyncio
94
+ async def test_inventory_etag_answers_304_until_the_cache_changes(
95
+ tmp_path, monkeypatch
96
+ ):
97
+ """A poll that sends back the ETag downloads nothing while the list is unchanged, and the
98
+ full list again once a store appears (here in a subfolder)."""
99
+ monkeypatch.setenv("FORCINGKIT_CACHE_DIR", str(tmp_path))
100
+
101
+ def store(path: Path) -> None:
102
+ xr.Dataset({"temp": (("time",), np.zeros(3))}, coords={"time": TIMES}).to_zarr(
103
+ path
104
+ )
105
+
106
+ store(tmp_path / "obc_000000000001.zarr")
107
+ from forcingkit_serve.main import app
108
+
109
+ async with AsyncClient(
110
+ transport=ASGITransport(app=app), base_url="http://test"
111
+ ) as ac:
112
+ first = await ac.get("/api/v1/cache/inventory")
113
+ etag = first.headers["etag"]
114
+ assert [i["id"] for i in first.json()] == ["obc_000000000001"]
115
+ same = await ac.get("/api/v1/cache/inventory", headers={"If-None-Match": etag})
116
+ assert same.status_code == 304 and same.content == b""
117
+ store(tmp_path / "sub" / "obc_000000000002.zarr")
118
+ changed = await ac.get(
119
+ "/api/v1/cache/inventory", headers={"If-None-Match": etag}
120
+ )
121
+ assert changed.status_code == 200 and changed.headers["etag"] != etag
122
+ assert sorted(i["id"] for i in changed.json()) == [
123
+ "obc_000000000001",
124
+ "obc_000000000002",
125
+ ]
@@ -386,9 +386,45 @@ def test_multi_hue_currents_ramps_share_the_axis(name, falling):
386
386
  assert not np.any((chroma > 10) & ((hue < 80) | (hue > 340))), hue
387
387
 
388
388
 
389
+ @pytest.mark.parametrize(
390
+ ("name", "falling"), [("currents_tempo", True), ("currents_tempo_dark", False)]
391
+ )
392
+ def test_tempo_currents_ramps_share_the_axis_and_swap_by_theme(name, falling):
393
+ light = np.array(render.packaged_ramp_rows("currents_lis"))
394
+ rows = np.array(render.packaged_ramp_rows(name))
395
+ np.testing.assert_array_equal(rows[:, 0], light[:, 0])
396
+ L = _lightness(rows[:, 1:])
397
+ assert np.all(np.diff(L) <= 0) if falling else np.all(np.diff(L) >= 0), (
398
+ "lightness must be monotone"
399
+ )
400
+ # Slack recedes into the basemap and fast water stands out on either: near white or near the dark ground.
401
+ assert (L[0] > 95 and L[-1] < 15) if falling else (L[0] < 15 and L[-1] > 95)
402
+ lab = _lab(rows[:, 1:])
403
+ hue = np.degrees(np.arctan2(lab[:, 2], lab[:, 1])) % 360
404
+ chroma = np.hypot(lab[:, 1], lab[:, 2])
405
+ assert not np.any((chroma > 10) & ((hue < 80) | (hue > 340))), hue
406
+
407
+
408
+ def test_tempo_pair_mirrors():
409
+ light = np.array(render.packaged_ramp_rows("currents_tempo"))
410
+ dark = np.array(render.packaged_ramp_rows("currents_tempo_dark"))
411
+ np.testing.assert_array_equal(dark[:, 0], light[:, 0])
412
+ np.testing.assert_array_equal(
413
+ dark[0, 1:], light[-1, 1:]
414
+ ) # the dark ramp's slack is the light ramp's fastest
415
+ np.testing.assert_array_equal(dark[-1, 1:], light[0, 1:])
416
+
417
+
389
418
  @pytest.mark.parametrize(
390
419
  "name",
391
- ["currents_lis", "currents_lis_dark", "currents_lis_deep", "currents_lis_haline"],
420
+ [
421
+ "currents_lis",
422
+ "currents_lis_dark",
423
+ "currents_lis_deep",
424
+ "currents_lis_haline",
425
+ "currents_tempo",
426
+ "currents_tempo_dark",
427
+ ],
392
428
  )
393
429
  def test_currents_ramp_floor_log_axis_and_clamp(name):
394
430
  rows = render.packaged_ramp_rows(name)
@@ -207,6 +207,9 @@ def test_ramp_has_transparent_no_value_and_one_entry_per_code(tmp_path):
207
207
  temp = next(f for f in view.manifest()["fields"] if f["name"] == "temp")
208
208
  rgba = np.frombuffer(base64.b64decode(temp["ramp_rgba"]), np.uint8).reshape(256, 4)
209
209
  assert rgba[0, 3] == 0 and np.all(rgba[1:, 3] == 255)
210
+ # Temperature on cmocean thermal: its first and last knots at the ends of the codes.
211
+ assert tuple(rgba[1, :3]) == (4, 35, 51) and tuple(rgba[255, :3]) == (232, 250, 91)
212
+ assert temp["ramp"] == "thermal"
210
213
 
211
214
 
212
215
  @pytest.mark.asyncio
@@ -1000,7 +1000,7 @@ wheels = [
1000
1000
 
1001
1001
  [[package]]
1002
1002
  name = "forcingkit"
1003
- version = "0.22.1"
1003
+ version = "0.23.0"
1004
1004
  source = { editable = "." }
1005
1005
  dependencies = [
1006
1006
  { name = "bottleneck" },
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes