forcingkit 0.13.0__tar.gz → 0.14.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 (144) hide show
  1. {forcingkit-0.13.0 → forcingkit-0.14.0}/PKG-INFO +3 -1
  2. {forcingkit-0.13.0 → forcingkit-0.14.0}/docs/source/conf.py +1 -1
  3. {forcingkit-0.13.0 → forcingkit-0.14.0}/docs/source/fetchers.rst +5 -1
  4. {forcingkit-0.13.0 → forcingkit-0.14.0}/docs/source/roadmap.rst +4 -2
  5. {forcingkit-0.13.0 → forcingkit-0.14.0}/pyproject.toml +4 -1
  6. {forcingkit-0.13.0 → forcingkit-0.14.0}/service/forcingkit_serve/main.py +10 -0
  7. {forcingkit-0.13.0 → forcingkit-0.14.0}/src/forcingkit/fetchers/noaa.py +99 -99
  8. {forcingkit-0.13.0 → forcingkit-0.14.0}/static/index.html +5 -1
  9. {forcingkit-0.13.0 → forcingkit-0.14.0}/static/preview3d.js +21 -11
  10. {forcingkit-0.13.0 → forcingkit-0.14.0}/tests/unit/test_noaa_currents.py +28 -39
  11. forcingkit-0.14.0/tests/unit/test_noaa_datum.py +69 -0
  12. {forcingkit-0.13.0 → forcingkit-0.14.0}/uv.lock +19 -1
  13. forcingkit-0.13.0/tests/unit/test_noaa_datum.py +0 -66
  14. {forcingkit-0.13.0 → forcingkit-0.14.0}/.agents/forcingkit.md +0 -0
  15. {forcingkit-0.13.0 → forcingkit-0.14.0}/.claude/CLAUDE.md +0 -0
  16. {forcingkit-0.13.0 → forcingkit-0.14.0}/.env.template +0 -0
  17. {forcingkit-0.13.0 → forcingkit-0.14.0}/.github/copilot-instructions.md +0 -0
  18. {forcingkit-0.13.0 → forcingkit-0.14.0}/.github/workflows/docs.yml +0 -0
  19. {forcingkit-0.13.0 → forcingkit-0.14.0}/.github/workflows/publish-client.yml +0 -0
  20. {forcingkit-0.13.0 → forcingkit-0.14.0}/.github/workflows/publish.yml +0 -0
  21. {forcingkit-0.13.0 → forcingkit-0.14.0}/.github/workflows/tests.yml +0 -0
  22. {forcingkit-0.13.0 → forcingkit-0.14.0}/.gitignore +0 -0
  23. {forcingkit-0.13.0 → forcingkit-0.14.0}/.markdownlint.yaml +0 -0
  24. {forcingkit-0.13.0 → forcingkit-0.14.0}/.pre-commit-config.yaml +0 -0
  25. {forcingkit-0.13.0 → forcingkit-0.14.0}/.python-version +0 -0
  26. {forcingkit-0.13.0 → forcingkit-0.14.0}/AGENTS.md +0 -0
  27. {forcingkit-0.13.0 → forcingkit-0.14.0}/CONTRIBUTING.md +0 -0
  28. {forcingkit-0.13.0 → forcingkit-0.14.0}/Dockerfile +0 -0
  29. {forcingkit-0.13.0 → forcingkit-0.14.0}/LICENSE +0 -0
  30. {forcingkit-0.13.0 → forcingkit-0.14.0}/README.md +0 -0
  31. {forcingkit-0.13.0 → forcingkit-0.14.0}/client/LICENSE +0 -0
  32. {forcingkit-0.13.0 → forcingkit-0.14.0}/client/README.md +0 -0
  33. {forcingkit-0.13.0 → forcingkit-0.14.0}/client/pyproject.toml +0 -0
  34. {forcingkit-0.13.0 → forcingkit-0.14.0}/client/src/forcingkit_client/__init__.py +0 -0
  35. {forcingkit-0.13.0 → forcingkit-0.14.0}/client/src/forcingkit_client/client.py +0 -0
  36. {forcingkit-0.13.0 → forcingkit-0.14.0}/client/src/forcingkit_client/schema.py +0 -0
  37. {forcingkit-0.13.0 → forcingkit-0.14.0}/client/src/forcingkit_client/store.py +0 -0
  38. {forcingkit-0.13.0 → forcingkit-0.14.0}/client/src/forcingkit_client/trajectory.py +0 -0
  39. {forcingkit-0.13.0 → forcingkit-0.14.0}/client/tests/conftest.py +0 -0
  40. {forcingkit-0.13.0 → forcingkit-0.14.0}/client/tests/test_client.py +0 -0
  41. {forcingkit-0.13.0 → forcingkit-0.14.0}/client/tests/test_schema.py +0 -0
  42. {forcingkit-0.13.0 → forcingkit-0.14.0}/client/tests/test_trajectory.py +0 -0
  43. {forcingkit-0.13.0 → forcingkit-0.14.0}/client/uv.lock +0 -0
  44. {forcingkit-0.13.0 → forcingkit-0.14.0}/docker-compose.yml +0 -0
  45. {forcingkit-0.13.0 → forcingkit-0.14.0}/docs/Makefile +0 -0
  46. {forcingkit-0.13.0 → forcingkit-0.14.0}/docs/make.bat +0 -0
  47. {forcingkit-0.13.0 → forcingkit-0.14.0}/docs/requirements-docs.txt +0 -0
  48. {forcingkit-0.13.0 → forcingkit-0.14.0}/docs/source/_extra/CNAME +0 -0
  49. {forcingkit-0.13.0 → forcingkit-0.14.0}/docs/source/_static/custom.css +0 -0
  50. {forcingkit-0.13.0 → forcingkit-0.14.0}/docs/source/_static/forcingkit-noreaster-wind.gif +0 -0
  51. {forcingkit-0.13.0 → forcingkit-0.14.0}/docs/source/atmospheric_forcing.rst +0 -0
  52. {forcingkit-0.13.0 → forcingkit-0.14.0}/docs/source/client.rst +0 -0
  53. {forcingkit-0.13.0 → forcingkit-0.14.0}/docs/source/hycom.rst +0 -0
  54. {forcingkit-0.13.0 → forcingkit-0.14.0}/docs/source/index.rst +0 -0
  55. {forcingkit-0.13.0 → forcingkit-0.14.0}/docs/source/layered_mesh.rst +0 -0
  56. {forcingkit-0.13.0 → forcingkit-0.14.0}/docs/source/mesh_frames.rst +0 -0
  57. {forcingkit-0.13.0 → forcingkit-0.14.0}/docs/source/necofs.rst +0 -0
  58. {forcingkit-0.13.0 → forcingkit-0.14.0}/docs/source/nyofs.rst +0 -0
  59. {forcingkit-0.13.0 → forcingkit-0.14.0}/docs/source/rivers.rst +0 -0
  60. {forcingkit-0.13.0 → forcingkit-0.14.0}/docs/source/sources.rst +0 -0
  61. {forcingkit-0.13.0 → forcingkit-0.14.0}/docs/source/waves.rst +0 -0
  62. {forcingkit-0.13.0 → forcingkit-0.14.0}/main.py +0 -0
  63. {forcingkit-0.13.0 → forcingkit-0.14.0}/service/__init__.py +0 -0
  64. {forcingkit-0.13.0 → forcingkit-0.14.0}/service/forcingkit_serve/__init__.py +0 -0
  65. {forcingkit-0.13.0 → forcingkit-0.14.0}/service/forcingkit_serve/jobs.py +0 -0
  66. {forcingkit-0.13.0 → forcingkit-0.14.0}/service/forcingkit_serve/routers/bathymetry.py +0 -0
  67. {forcingkit-0.13.0 → forcingkit-0.14.0}/service/forcingkit_serve/routers/plotly_api.py +0 -0
  68. {forcingkit-0.13.0 → forcingkit-0.14.0}/service/forcingkit_serve/routers/removed.py +0 -0
  69. {forcingkit-0.13.0 → forcingkit-0.14.0}/service/forcingkit_serve/routers/stores.py +0 -0
  70. {forcingkit-0.13.0 → forcingkit-0.14.0}/service/forcingkit_serve/routers/viewer.py +0 -0
  71. {forcingkit-0.13.0 → forcingkit-0.14.0}/service/forcingkit_serve/stac.py +0 -0
  72. {forcingkit-0.13.0 → forcingkit-0.14.0}/service/run_server.py +0 -0
  73. {forcingkit-0.13.0 → forcingkit-0.14.0}/src/forcingkit/__init__.py +0 -0
  74. {forcingkit-0.13.0 → forcingkit-0.14.0}/src/forcingkit/data/rivers/northeast_us.json +0 -0
  75. {forcingkit-0.13.0 → forcingkit-0.14.0}/src/forcingkit/dispatcher.py +0 -0
  76. {forcingkit-0.13.0 → forcingkit-0.14.0}/src/forcingkit/fetchers/coastwatch.py +0 -0
  77. {forcingkit-0.13.0 → forcingkit-0.14.0}/src/forcingkit/fetchers/dbofs.py +0 -0
  78. {forcingkit-0.13.0 → forcingkit-0.14.0}/src/forcingkit/fetchers/erddap.py +0 -0
  79. {forcingkit-0.13.0 → forcingkit-0.14.0}/src/forcingkit/fetchers/hrrr.py +0 -0
  80. {forcingkit-0.13.0 → forcingkit-0.14.0}/src/forcingkit/fetchers/hrrr_atmosphere.py +0 -0
  81. {forcingkit-0.13.0 → forcingkit-0.14.0}/src/forcingkit/fetchers/hrrr_levels.py +0 -0
  82. {forcingkit-0.13.0 → forcingkit-0.14.0}/src/forcingkit/fetchers/hrrr_points.py +0 -0
  83. {forcingkit-0.13.0 → forcingkit-0.14.0}/src/forcingkit/fetchers/hycom.py +0 -0
  84. {forcingkit-0.13.0 → forcingkit-0.14.0}/src/forcingkit/fetchers/hydrography.py +0 -0
  85. {forcingkit-0.13.0 → forcingkit-0.14.0}/src/forcingkit/fetchers/ndbc.py +0 -0
  86. {forcingkit-0.13.0 → forcingkit-0.14.0}/src/forcingkit/fetchers/necofs.py +0 -0
  87. {forcingkit-0.13.0 → forcingkit-0.14.0}/src/forcingkit/fetchers/nwps.py +0 -0
  88. {forcingkit-0.13.0 → forcingkit-0.14.0}/src/forcingkit/fetchers/nyofs.py +0 -0
  89. {forcingkit-0.13.0 → forcingkit-0.14.0}/src/forcingkit/fetchers/usgs.py +0 -0
  90. {forcingkit-0.13.0 → forcingkit-0.14.0}/src/forcingkit/fetchers/usgs_rivers.py +0 -0
  91. {forcingkit-0.13.0 → forcingkit-0.14.0}/src/forcingkit/layered_mesh.py +0 -0
  92. {forcingkit-0.13.0 → forcingkit-0.14.0}/src/forcingkit/mesh_frames.py +0 -0
  93. {forcingkit-0.13.0 → forcingkit-0.14.0}/src/forcingkit/ramps/currents_lis.csv +0 -0
  94. {forcingkit-0.13.0 → forcingkit-0.14.0}/src/forcingkit/ramps/currents_lis_dark.csv +0 -0
  95. {forcingkit-0.13.0 → forcingkit-0.14.0}/src/forcingkit/ramps/currents_lis_deep.csv +0 -0
  96. {forcingkit-0.13.0 → forcingkit-0.14.0}/src/forcingkit/ramps/currents_lis_haline.csv +0 -0
  97. {forcingkit-0.13.0 → forcingkit-0.14.0}/src/forcingkit/render.py +0 -0
  98. {forcingkit-0.13.0 → forcingkit-0.14.0}/src/forcingkit/settings.py +0 -0
  99. {forcingkit-0.13.0 → forcingkit-0.14.0}/src/forcingkit/zarr_stream.py +0 -0
  100. {forcingkit-0.13.0 → forcingkit-0.14.0}/static/app.js +0 -0
  101. {forcingkit-0.13.0 → forcingkit-0.14.0}/static/favicon.ico +0 -0
  102. {forcingkit-0.13.0 → forcingkit-0.14.0}/static/favicon.svg +0 -0
  103. {forcingkit-0.13.0 → forcingkit-0.14.0}/static/logo.svg +0 -0
  104. {forcingkit-0.13.0 → forcingkit-0.14.0}/static/styles.css +0 -0
  105. {forcingkit-0.13.0 → forcingkit-0.14.0}/tests/__init__.py +0 -0
  106. {forcingkit-0.13.0 → forcingkit-0.14.0}/tests/integration/test_auth.py +0 -0
  107. {forcingkit-0.13.0 → forcingkit-0.14.0}/tests/integration/test_erddap_fetch.py +0 -0
  108. {forcingkit-0.13.0 → forcingkit-0.14.0}/tests/integration/test_mesh_frames_necofs.py +0 -0
  109. {forcingkit-0.13.0 → forcingkit-0.14.0}/tests/integration/test_necofs_volume_live.py +0 -0
  110. {forcingkit-0.13.0 → forcingkit-0.14.0}/tests/integration/test_nwps_nomads.py +0 -0
  111. {forcingkit-0.13.0 → forcingkit-0.14.0}/tests/integration/test_nyofs_obc_fetch.py +0 -0
  112. {forcingkit-0.13.0 → forcingkit-0.14.0}/tests/integration/test_obc_offshore_nj.py +0 -0
  113. {forcingkit-0.13.0 → forcingkit-0.14.0}/tests/integration/test_ofs_archive_paths.py +0 -0
  114. {forcingkit-0.13.0 → forcingkit-0.14.0}/tests/integration/test_s3_roms_fetchers.py +0 -0
  115. {forcingkit-0.13.0 → forcingkit-0.14.0}/tests/scripts/inspect_dem.py +0 -0
  116. {forcingkit-0.13.0 → forcingkit-0.14.0}/tests/scripts/inspect_grib.py +0 -0
  117. {forcingkit-0.13.0 → forcingkit-0.14.0}/tests/scripts/inspect_zarr.py +0 -0
  118. {forcingkit-0.13.0 → forcingkit-0.14.0}/tests/unit/test_coastwatch.py +0 -0
  119. {forcingkit-0.13.0 → forcingkit-0.14.0}/tests/unit/test_dbofs.py +0 -0
  120. {forcingkit-0.13.0 → forcingkit-0.14.0}/tests/unit/test_dispatcher.py +0 -0
  121. {forcingkit-0.13.0 → forcingkit-0.14.0}/tests/unit/test_erddap.py +0 -0
  122. {forcingkit-0.13.0 → forcingkit-0.14.0}/tests/unit/test_hrrr_atm.py +0 -0
  123. {forcingkit-0.13.0 → forcingkit-0.14.0}/tests/unit/test_hrrr_idx.py +0 -0
  124. {forcingkit-0.13.0 → forcingkit-0.14.0}/tests/unit/test_hrrr_levels.py +0 -0
  125. {forcingkit-0.13.0 → forcingkit-0.14.0}/tests/unit/test_hrrr_points.py +0 -0
  126. {forcingkit-0.13.0 → forcingkit-0.14.0}/tests/unit/test_hycom.py +0 -0
  127. {forcingkit-0.13.0 → forcingkit-0.14.0}/tests/unit/test_jobs.py +0 -0
  128. {forcingkit-0.13.0 → forcingkit-0.14.0}/tests/unit/test_layered_mesh.py +0 -0
  129. {forcingkit-0.13.0 → forcingkit-0.14.0}/tests/unit/test_main.py +0 -0
  130. {forcingkit-0.13.0 → forcingkit-0.14.0}/tests/unit/test_mesh_frames.py +0 -0
  131. {forcingkit-0.13.0 → forcingkit-0.14.0}/tests/unit/test_ndbc.py +0 -0
  132. {forcingkit-0.13.0 → forcingkit-0.14.0}/tests/unit/test_necofs_hindcast.py +0 -0
  133. {forcingkit-0.13.0 → forcingkit-0.14.0}/tests/unit/test_necofs_mesh_cache.py +0 -0
  134. {forcingkit-0.13.0 → forcingkit-0.14.0}/tests/unit/test_necofs_parent.py +0 -0
  135. {forcingkit-0.13.0 → forcingkit-0.14.0}/tests/unit/test_necofs_volume.py +0 -0
  136. {forcingkit-0.13.0 → forcingkit-0.14.0}/tests/unit/test_nwps.py +0 -0
  137. {forcingkit-0.13.0 → forcingkit-0.14.0}/tests/unit/test_nyofs.py +0 -0
  138. {forcingkit-0.13.0 → forcingkit-0.14.0}/tests/unit/test_obc_donor_report.py +0 -0
  139. {forcingkit-0.13.0 → forcingkit-0.14.0}/tests/unit/test_obc_pipeline.py +0 -0
  140. {forcingkit-0.13.0 → forcingkit-0.14.0}/tests/unit/test_removed_routes.py +0 -0
  141. {forcingkit-0.13.0 → forcingkit-0.14.0}/tests/unit/test_settings.py +0 -0
  142. {forcingkit-0.13.0 → forcingkit-0.14.0}/tests/unit/test_usgs.py +0 -0
  143. {forcingkit-0.13.0 → forcingkit-0.14.0}/tests/unit/test_usgs_rivers.py +0 -0
  144. {forcingkit-0.13.0 → forcingkit-0.14.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.13.0
3
+ Version: 0.14.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
@@ -225,8 +225,10 @@ Requires-Dist: fastapi>=0.135.1
225
225
  Requires-Dist: h5netcdf>=1.8.1
226
226
  Requires-Dist: h5py>=3.16.0
227
227
  Requires-Dist: httpx>=0.28.1
228
+ Requires-Dist: insitukit<0.3,>=0.2
228
229
  Requires-Dist: jinja2>=3.0.0
229
230
  Requires-Dist: matplotlib>=3.10.9
231
+ Requires-Dist: pandas>=2.2
230
232
  Requires-Dist: pillow>=10.0
231
233
  Requires-Dist: pydantic>=2.12.5
232
234
  Requires-Dist: pydap>=3.5.8
@@ -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.13.0"
12
+ release = "0.14.0"
13
13
 
14
14
  extensions = [
15
15
  "sphinx.ext.autodoc",
@@ -146,7 +146,11 @@ These serve validation rather than forcing:
146
146
 
147
147
  - **CO-OPS** water level (``/api/v1/tide``), from the `NOAA CO-OPS data API
148
148
  <https://api.tidesandcurrents.noaa.gov/api/prod/>`__, with a datum
149
- fallback to MSL where a station has no NAVD88 datum.
149
+ fallback to MSL where a station has no NAVD88 datum. Requests go through
150
+ `insitukit <https://github.com/lhzn-io/insitukit>`__, which keeps them at least 1 s apart,
151
+ splits windows longer than the API's 31-day limit, and retries server errors and throttling;
152
+ ``end_time`` is inclusive, as in the API. Current predictions (``/api/v1/currents``) and the
153
+ current-station list (``/api/v1/currents/stations``) use the same client.
150
154
  - **NDBC** buoy meteorology and ADCP profiles (``/api/v1/ndbc``), from the `NOAA National Data
151
155
  Buoy Center <https://www.ndbc.noaa.gov/>`__.
152
156
  - **UConn ERDDAP** water-column profiles (``/api/v1/telemetry/station`` and ``/bbox``), from the
@@ -123,8 +123,10 @@ Planned work
123
123
  - Modules in ``forcingkit.fetchers`` are named for their source (``necofs``, ``hycom``,
124
124
  ``ndbc``, ``coastwatch``, ``usgs``), and a model-ready delivery for the source and what it
125
125
  delivers (``hrrr_atmosphere``, ``usgs_rivers``). Three predate the convention:
126
- ``noaa.py`` serves CO-OPS water levels and current predictions (``coops.py``),
127
- ``erddap.py`` serves the UConn profile stations (named for the protocol, not the source),
126
+ ``noaa.py`` serves CO-OPS water levels and current predictions (``coops.py``; since
127
+ 0.14.0 a thin layer over ``insitukit.coops``, which may replace it outright),
128
+ ``erddap.py`` serves the UConn profile stations (named for the protocol, not the source;
129
+ a move to ``insitukit.erddap`` waits for its expiring failure cache and parallel reads),
128
130
  and ``hydrography.py`` finds heads of tide from OpenStreetMap (``osm.py`` or similar).
129
131
  Renaming them breaks imports from earlier releases, so it belongs in a release that says
130
132
  so, with the old names kept as deprecated aliases for one release.
@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
4
4
 
5
5
  [project]
6
6
  name = "forcingkit"
7
- version = "0.13.0"
7
+ version = "0.14.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"
@@ -26,6 +26,9 @@ dependencies = [
26
26
  "eccodeslib>=2.46.0",
27
27
  "fastapi>=0.135.1",
28
28
  "httpx>=0.28.1",
29
+ # NOAA CO-OPS water level and current predictions (fetchers/noaa.py).
30
+ "insitukit>=0.2,<0.3",
31
+ "pandas>=2.2",
29
32
  "pydantic>=2.12.5",
30
33
  "jinja2>=3.0.0",
31
34
  "pydap>=3.5.8",
@@ -29,6 +29,16 @@ from forcingkit_serve.routers import ( # noqa: E402
29
29
  stores,
30
30
  )
31
31
  from forcingkit.fetchers.noaa import fetch_noaa_tide_data # noqa: E402
32
+ from importlib.metadata import version as _package_version # noqa: E402
33
+
34
+ import insitukit # noqa: E402
35
+
36
+ # Every CO-OPS request (through insitukit) names this service. Set here, not in the library, so a
37
+ # program that imports forcingkit keeps its own identity.
38
+ insitukit.identify(
39
+ f"forcingkit/{_package_version('forcingkit')} (+https://github.com/lhzn-io/forcingkit)",
40
+ application="forcingkit",
41
+ )
32
42
 
33
43
  # Configure Logging
34
44
  log_dir = Path("logs")
@@ -1,8 +1,18 @@
1
- import os
2
- import logging
3
- import requests
1
+ """NOAA CO-OPS water level and tidal current predictions, through insitukit.
2
+
3
+ insitukit's CO-OPS client paces requests (1 s apart, across threads), splits long windows to the API's
4
+ range limits, retries server errors and throttling, and names the caller (``insitukit.identify``, set by
5
+ the service at start-up). This module keeps forcingkit's call signatures, caching and return shapes.
6
+ """
7
+
4
8
  import json
5
- from datetime import datetime
9
+ import logging
10
+ import os
11
+ from datetime import datetime, timedelta, timezone
12
+
13
+ import pandas as pd
14
+ from insitukit import coops
15
+
6
16
  from forcingkit import settings
7
17
 
8
18
  logger = logging.getLogger(__name__)
@@ -12,6 +22,25 @@ logger = logging.getLogger(__name__)
12
22
  TIDE_DATUMS = ("NAVD", "MSL")
13
23
 
14
24
 
25
+ def _utc(stamp: str) -> datetime:
26
+ """An ISO 8601 time, read as UTC (a trailing Z or an offset is accepted)."""
27
+ ts = datetime.fromisoformat(stamp.replace("Z", "+00:00"))
28
+ return (
29
+ ts.replace(tzinfo=timezone.utc)
30
+ if ts.tzinfo is None
31
+ else ts.astimezone(timezone.utc)
32
+ )
33
+
34
+
35
+ def _through(stamp: str) -> datetime:
36
+ """The exclusive end for an inclusive ``end_time``: CO-OPS's own end_date includes its minute."""
37
+ return _utc(stamp) + timedelta(minutes=1)
38
+
39
+
40
+ def _t(ts: pd.Timestamp) -> str:
41
+ return ts.strftime("%Y-%m-%d %H:%M")
42
+
43
+
15
44
  def fetch_noaa_tide_data(
16
45
  station_id: str,
17
46
  start_time: str,
@@ -23,13 +52,18 @@ def fetch_noaa_tide_data(
23
52
  cache_bust: bool = False,
24
53
  ) -> dict:
25
54
  """
26
- Fetches water level data from NOAA CO-OPS API for a specific station and time window.
27
- Supports caching to avoid redundant API calls.
55
+ Fetches water level data from NOAA CO-OPS for a station over [start_time, end_time] (UTC),
56
+ in metres, on NAVD88 where the station has it and MSL otherwise. Supports caching to avoid
57
+ redundant API calls.
58
+
59
+ Returns the shape of a CO-OPS response: ``{"metadata": {"id", "name", "lat", "lon", "datum"},
60
+ "data": [{"t": "YYYY-MM-DD HH:MM", "v": "0.123"}, ...]}``, with ``lat``, ``lon`` and ``v`` as
61
+ strings (``v`` empty for a missing reading). Raises RuntimeError when the window has no data.
28
62
 
29
63
  Args:
30
64
  station_id: NOAA station ID (e.g., '8516945' for Kings Point)
31
65
  start_time: ISO8601 string (YYYY-MM-DDTHH:MM:SSZ)
32
- end_time: ISO8601 string (YYYY-MM-DDTHH:MM:SSZ)
66
+ end_time: ISO8601 string (YYYY-MM-DDTHH:MM:SSZ), inclusive
33
67
  cache_dir: Local directory for caching JSON responses
34
68
  """
35
69
  os.makedirs(cache_dir, exist_ok=True)
@@ -46,52 +80,41 @@ def fetch_noaa_tide_data(
46
80
  logger.info(
47
81
  f"Fetching NOAA tide data for station {station_id} ({start_time} to {end_time})..."
48
82
  )
49
-
50
- # NOAA API expects yyyyMMdd HH:mm
51
- # Note: We assume the input strings are ISO8601 UTC
52
- s_dt = datetime.fromisoformat(start_time.replace("Z", ""))
53
- e_dt = datetime.fromisoformat(end_time.replace("Z", ""))
54
-
55
- begin_str = s_dt.strftime("%Y%m%d %H:%M")
56
- end_str = e_dt.strftime("%Y%m%d %H:%M")
57
-
58
- url = "https://api.tidesandcurrents.noaa.gov/api/prod/datagetter"
59
- params = {
60
- "begin_date": begin_str,
61
- "end_date": end_str,
62
- "station": station_id,
63
- "product": "water_level",
64
- "units": "metric",
65
- "time_zone": "gmt",
66
- "format": "json",
67
- "application": "forcingkit",
68
- }
83
+ start, end = _utc(start_time), _through(end_time)
69
84
 
70
85
  try:
71
86
  # NAVD88 where the station has it, so stations share a datum; otherwise MSL (New Haven,
72
87
  # 8465705, publishes only tidal datums). The datum used is recorded in the metadata.
73
88
  for datum in TIDE_DATUMS:
74
- response = requests.get(url, params={**params, "datum": datum}, timeout=30)
75
- data = response.json() if response.content else {}
76
- message = (
77
- data.get("error", {}).get("message", "")
78
- if isinstance(data, dict)
79
- else ""
80
- )
81
- if "datum" in message.lower() and datum != TIDE_DATUMS[-1]:
89
+ try:
90
+ df = coops.fetch("water_level", station_id, start, end, datum=datum)
91
+ break
92
+ except coops.DatumUnavailable:
93
+ if datum == TIDE_DATUMS[-1]:
94
+ raise
82
95
  logger.info(
83
96
  f"NOAA station {station_id} has no {datum} datum; trying the next"
84
97
  )
85
- continue
86
- response.raise_for_status()
87
- break
88
-
89
- if "error" in data:
90
- logger.warning(
91
- f"NOAA API returned error: {data['error'].get('message', 'Unknown error')}"
98
+ if df.empty:
99
+ raise RuntimeError(
100
+ f"NOAA API Error: No data was found for {station_id} "
101
+ f"({start_time} to {end_time})"
92
102
  )
93
- raise RuntimeError(f"NOAA API Error: {data['error'].get('message')}")
94
- data.setdefault("metadata", {})["datum"] = datum
103
+ info = coops.metadata(station_id, expand="")
104
+ data = {
105
+ "metadata": {
106
+ "id": station_id,
107
+ "name": info.get("name"),
108
+ "lat": str(info["lat"]),
109
+ "lon": str(info["lng"]),
110
+ "datum": datum,
111
+ },
112
+ "data": [
113
+ # Written as CO-OPS writes it: 3 decimals at most, no trailing zeros.
114
+ {"t": _t(t), "v": "" if pd.isna(v) else str(round(float(v), 3))}
115
+ for t, v in zip(df["time"], df["water_level"])
116
+ ],
117
+ }
95
118
 
96
119
  # Cache the successful response
97
120
  with open(cache_path, "w") as f:
@@ -104,25 +127,19 @@ def fetch_noaa_tide_data(
104
127
  raise e
105
128
 
106
129
 
107
- CURRENTS_URL = "https://api.tidesandcurrents.noaa.gov/api/prod/datagetter"
108
- STATION_URL = (
109
- "https://api.tidesandcurrents.noaa.gov/mdapi/prod/webapi/stations/{station}.json"
110
- )
111
- STATIONS_URL = "https://api.tidesandcurrents.noaa.gov/mdapi/prod/webapi/stations.json"
112
-
113
-
114
130
  def fetch_noaa_current_stations(
115
131
  bbox: list[float],
116
132
  cache_dir: str = os.path.join(settings.cache_dir(), "noaa"),
117
133
  cache_bust: bool = False,
118
- get=requests.get,
134
+ get=None,
119
135
  ) -> list[dict]:
120
136
  """Every harmonic CO-OPS current-prediction station and depth bin inside ``bbox``
121
137
  ([min_lon, min_lat, max_lon, max_lat]).
122
138
 
123
139
  Returns one entry per station-bin: ``{"id", "name", "lat", "lon", "bin", "depth_m"}``.
124
140
  Harmonic stations (type H) give a predicted series; subordinate (S) and weak or variable (W)
125
- entries are left out. The full station list is cached for a day.
141
+ entries are left out. The full station list is cached for a day. ``get`` is ignored (kept for
142
+ callers of earlier releases; requests go through insitukit).
126
143
  """
127
144
  os.makedirs(cache_dir, exist_ok=True)
128
145
  cache_path = os.path.join(cache_dir, "currentpredictions_stations.json")
@@ -133,13 +150,7 @@ def fetch_noaa_current_stations(
133
150
  with open(cache_path) as f:
134
151
  stations = json.load(f)
135
152
  else:
136
- response = get(
137
- STATIONS_URL,
138
- params={"type": "currentpredictions", "units": "metric"},
139
- timeout=60,
140
- )
141
- response.raise_for_status()
142
- stations = response.json().get("stations", [])
153
+ stations = coops.stations("currentpredictions", units="metric")
143
154
  with open(cache_path, "w") as f:
144
155
  json.dump(stations, f)
145
156
 
@@ -172,16 +183,18 @@ def fetch_noaa_current_predictions(
172
183
  interval_minutes: int = 30,
173
184
  cache_dir: str = os.path.join(settings.cache_dir(), "noaa"),
174
185
  cache_bust: bool = False,
175
- get=requests.get,
186
+ get=None,
176
187
  ) -> dict:
177
- """Harmonic current predictions for one CO-OPS station and depth bin.
188
+ """Harmonic current predictions for one CO-OPS station and depth bin over
189
+ [start_time, end_time] (UTC).
178
190
 
179
191
  Returns ``{"metadata": {...}, "data": [{"t": "YYYY-MM-DD HH:MM", "v": m/s}, ...]}``: the
180
192
  predicted velocity along the station's flood-ebb axis, positive on the flood, in m/s, every
181
193
  ``interval_minutes``. The metadata carries the station's position, the bin depth (metres
182
194
  below the surface), and the mean flood and ebb directions (degrees true, toward which the
183
195
  water flows). Only harmonic stations give a series; subordinate stations give slack and
184
- maximum times only and are refused.
196
+ maximum times only and are refused. ``get`` is ignored (kept for callers of earlier
197
+ releases; requests go through insitukit).
185
198
  """
186
199
  os.makedirs(cache_dir, exist_ok=True)
187
200
  key = f"currents_{station_id}_b{bin_number}_{start_time}_{end_time}_{interval_minutes}"
@@ -190,40 +203,26 @@ def fetch_noaa_current_predictions(
190
203
  with open(cache_path) as f:
191
204
  return json.load(f)
192
205
 
193
- s_dt = datetime.fromisoformat(start_time.replace("Z", ""))
194
- e_dt = datetime.fromisoformat(end_time.replace("Z", ""))
195
- params = {
196
- "product": "currents_predictions",
197
- "station": station_id,
198
- "bin": str(bin_number),
199
- "begin_date": s_dt.strftime("%Y%m%d %H:%M"),
200
- "end_date": e_dt.strftime("%Y%m%d %H:%M"),
201
- "interval": str(interval_minutes),
202
- "vel_type": "default",
203
- "units": "metric",
204
- "time_zone": "gmt",
205
- "format": "json",
206
- "application": "lhzn_forcingkit",
207
- }
208
- response = get(CURRENTS_URL, params=params, timeout=30)
209
- response.raise_for_status()
210
- payload = response.json()
211
- if "error" in payload:
212
- raise RuntimeError(f"NOAA API Error: {payload['error'].get('message')}")
213
- rows = payload.get("current_predictions", {}).get("cp", [])
214
- if not rows:
215
- raise RuntimeError(f"No current predictions for {station_id} bin {bin_number}")
216
- if any("Type" in r for r in rows):
217
- raise RuntimeError(
218
- f"{station_id} is a subordinate station (slack and maximum times only); "
219
- "a harmonic station is needed for a time series"
206
+ try:
207
+ df = coops.current_predictions(
208
+ station_id,
209
+ _utc(start_time),
210
+ _through(end_time),
211
+ bin=int(bin_number),
212
+ interval=int(interval_minutes),
213
+ vel_type="default",
220
214
  )
215
+ except coops.CoopsError as exc:
216
+ if "subordinate" in str(exc):
217
+ raise RuntimeError(
218
+ f"{station_id} is a subordinate station (slack and maximum times only); "
219
+ "a harmonic station is needed for a time series"
220
+ ) from exc
221
+ raise RuntimeError(f"NOAA API Error: {exc}") from exc
222
+ if df.empty:
223
+ raise RuntimeError(f"No current predictions for {station_id} bin {bin_number}")
221
224
 
222
- station = get(STATION_URL.format(station=station_id), params={}, timeout=30)
223
- station.raise_for_status()
224
- info = station.json().get("stations", [{}])[0]
225
-
226
- first = rows[0]
225
+ info = coops.metadata(station_id, expand="")
227
226
  data = {
228
227
  "metadata": {
229
228
  "id": station_id,
@@ -231,13 +230,14 @@ def fetch_noaa_current_predictions(
231
230
  "lat": float(info["lat"]),
232
231
  "lon": float(info["lng"]),
233
232
  "bin": int(bin_number),
234
- "depth_m": float(first["Depth"]),
235
- "flood_dir_deg": float(first["meanFloodDir"]),
236
- "ebb_dir_deg": float(first["meanEbbDir"]),
233
+ "depth_m": df.attrs["depth_m"],
234
+ "flood_dir_deg": df.attrs["flood_dir_deg"],
235
+ "ebb_dir_deg": df.attrs["ebb_dir_deg"],
237
236
  "units": "m/s along the flood axis, positive on the flood",
238
237
  },
239
238
  "data": [
240
- {"t": r["Time"], "v": float(r["Velocity_Major"]) / 100.0} for r in rows
239
+ {"t": _t(t), "v": float(v)}
240
+ for t, v in zip(df["time"], df["velocity_major"])
241
241
  ],
242
242
  }
243
243
  with open(cache_path, "w") as f:
@@ -137,7 +137,11 @@
137
137
 
138
138
  <script defer src="app.js"></script>
139
139
  <script type="importmap">
140
- { "imports": { "three": "https://cdn.jsdelivr.net/npm/three@0.170.0/build/three.module.js", "three/addons/": "https://cdn.jsdelivr.net/npm/three@0.170.0/examples/jsm/" } }
140
+ { "imports": {
141
+ "three": "https://cdn.jsdelivr.net/npm/three@0.170.0/build/three.module.js",
142
+ "camera-controls": "https://cdn.jsdelivr.net/npm/camera-controls@3.1.2/dist/camera-controls.module.min.js",
143
+ "vantagekit/three": "https://cdn.jsdelivr.net/gh/lhzn-io/vantagekit@v0.3.2/vantagekit-three.js"
144
+ } }
141
145
  </script>
142
146
  <script type="module" src="preview3d.js"></script>
143
147
  </body>
@@ -1,11 +1,12 @@
1
1
  import * as THREE from 'three';
2
- import { OrbitControls } from 'three/addons/controls/OrbitControls.js';
2
+ import CameraControls from 'camera-controls';
3
+ import { createVantage } from 'vantagekit/three';
3
4
 
4
5
  // - State -
5
6
  let renderer = null;
6
7
  let scene = null;
7
8
  let camera = null;
8
- let controls = null;
9
+ let nav = null; // vantagekit: orbit and fly, keys (while the canvas has focus), gamepad, touch
9
10
  let arrowGroup = null;
10
11
  let animId = null;
11
12
  let legendHost = null;
@@ -137,9 +138,14 @@ function initThree(container) {
137
138
  camera = new THREE.PerspectiveCamera(55, container.clientWidth / container.clientHeight, 0.1, 5000);
138
139
  camera.position.set(0, 150, 250);
139
140
 
140
- controls = new OrbitControls(camera, canvas);
141
- controls.enableDamping = true;
142
- controls.dampingFactor = 0.08;
141
+ // The scene is about 200 units across whatever the dataset's size, so metres per unit is set
142
+ // per dataset (buildVectorField). The keyboard acts only while the canvas has focus, so the
143
+ // page's own keys and scrolling keep working.
144
+ nav = createVantage({
145
+ THREE, CameraControls, camera, dom: canvas,
146
+ metresPerUnit: 1, exaggeration: DEPTH_EXAG * DEPTH_BASE_MULT,
147
+ keys: 'focus', minDistance: 0.5, smoothTime: 0.2,
148
+ });
143
149
 
144
150
  // Lighting: ambient + directional + uplight for subsurface visibility
145
151
  scene.add(new THREE.AmbientLight(0x404060, 0.8));
@@ -155,9 +161,10 @@ function initThree(container) {
155
161
  const grid = new THREE.GridHelper(200, 20, 0x1a2030, 0x1a2030);
156
162
  scene.add(grid);
157
163
 
164
+ const clock = new THREE.Clock();
158
165
  function animate() {
159
166
  animId = requestAnimationFrame(animate);
160
- controls.update();
167
+ nav.update(clock.getDelta());
161
168
  renderer.render(scene, camera);
162
169
  }
163
170
  animate();
@@ -200,6 +207,7 @@ function buildVectorField(data, fitCamera) {
200
207
  const latSpan = Math.max(latMax - latMin, 0.001) * degToM;
201
208
  const maxSpan = Math.max(lonSpan, latSpan);
202
209
  const sceneScale = 200 / maxSpan;
210
+ nav.metresPerUnit = 1 / sceneScale; // movement speeds and readouts in real metres
203
211
 
204
212
  // Compute max magnitude
205
213
  let maxMag = 0;
@@ -282,9 +290,8 @@ function buildVectorField(data, fitCamera) {
282
290
  const center = box.getCenter(new THREE.Vector3());
283
291
  const size = box.getSize(new THREE.Vector3());
284
292
  const dist = Math.max(size.x, size.y, size.z) * 1.2;
285
- controls.target.copy(center);
286
- camera.position.set(center.x + dist * 0.3, center.y + dist * 0.5, center.z + dist * 0.8);
287
- controls.update();
293
+ nav.setLookAt([center.x + dist * 0.3, center.y + dist * 0.5, center.z + dist * 0.8], center);
294
+ nav.saveHome(); // the Home key and pad A return here
288
295
  }
289
296
 
290
297
  // - Public API (called from app.js) -
@@ -295,7 +302,9 @@ window.preview3d = {
295
302
  // Re-init if canvas was destroyed (e.g. by 2D preview's innerHTML wipe)
296
303
  const existing = document.getElementById('preview3dCanvas');
297
304
  if (!renderer || !existing) {
298
- if (renderer) { renderer.dispose(); renderer = null; scene = null; camera = null; controls = null; }
305
+ if (animId) cancelAnimationFrame(animId);
306
+ if (nav) nav.dispose();
307
+ if (renderer) { renderer.dispose(); renderer = null; scene = null; camera = null; nav = null; }
299
308
  initThree(container);
300
309
  }
301
310
  const canvas = document.getElementById('preview3dCanvas');
@@ -333,8 +342,9 @@ window.preview3d = {
333
342
  dispose() {
334
343
  clearArrows();
335
344
  if (animId) cancelAnimationFrame(animId);
345
+ if (nav) nav.dispose();
336
346
  if (renderer) renderer.dispose();
337
- renderer = null; scene = null; camera = null; controls = null;
347
+ renderer = null; scene = null; camera = null; nav = null;
338
348
  this.active = false;
339
349
  }
340
350
  };
@@ -1,39 +1,31 @@
1
1
  """CO-OPS harmonic current predictions: parsing, units, caching, and subordinate stations."""
2
2
 
3
3
  import pytest
4
+ from insitukit import coops
4
5
 
5
6
  from forcingkit.fetchers import noaa
6
7
 
8
+ STATION = {"name": "Stratford Shoal, 2 miles south of", "lat": 41.023, "lng": -73.1048}
7
9
 
8
- class FakeResponse:
9
- def __init__(self, payload):
10
- self._payload = payload
11
10
 
12
- def json(self):
13
- return self._payload
14
-
15
- def raise_for_status(self):
16
- pass
17
-
18
-
19
- STATION = {
20
- "stations": [
21
- {"name": "Stratford Shoal, 2 miles south of", "lat": 41.023, "lng": -73.1048}
22
- ]
23
- }
24
-
25
-
26
- def fake_get(predictions):
11
+ def answer(monkeypatch, predictions=None, listing=None):
12
+ """Answer insitukit's CO-OPS data and metadata calls; return the list of calls made."""
27
13
  calls = []
28
14
 
29
- def get(url, params, timeout):
30
- calls.append(url)
31
- return FakeResponse(predictions if "datagetter" in url else STATION)
15
+ def get(params):
16
+ calls.append(("data", params))
17
+ return predictions
18
+
19
+ def md(path, params=None):
20
+ calls.append(("md", path, params))
21
+ return listing if path == "stations.json" else {"stations": [STATION]}
32
22
 
33
- return get, calls
23
+ monkeypatch.setattr(coops, "_get", get)
24
+ monkeypatch.setattr(coops, "_md", md)
25
+ return calls
34
26
 
35
27
 
36
- def test_harmonic_series_in_metres_per_second(tmp_path):
28
+ def test_harmonic_series_in_metres_per_second(tmp_path, monkeypatch):
37
29
  rows = [
38
30
  {
39
31
  "meanFloodDir": 272,
@@ -52,8 +44,8 @@ def test_harmonic_series_in_metres_per_second(tmp_path):
52
44
  "Velocity_Major": -44.0,
53
45
  },
54
46
  ]
55
- get, calls = fake_get(
56
- {"current_predictions": {"units": "meters, cm/s", "cp": rows}}
47
+ calls = answer(
48
+ monkeypatch, {"current_predictions": {"units": "meters, cm/s", "cp": rows}}
57
49
  )
58
50
  data = noaa.fetch_noaa_current_predictions(
59
51
  "LIS1027",
@@ -61,12 +53,15 @@ def test_harmonic_series_in_metres_per_second(tmp_path):
61
53
  "2026-04-02T00:00:00",
62
54
  "2026-04-02T00:30:00",
63
55
  cache_dir=str(tmp_path),
64
- get=get,
65
56
  )
66
57
  assert data["metadata"]["depth_m"] == 6.7
67
58
  assert data["metadata"]["flood_dir_deg"] == 272.0
68
59
  assert data["metadata"]["lat"] == 41.023
60
+ assert [r["t"] for r in data["data"]] == ["2026-04-02 00:00", "2026-04-02 00:30"]
69
61
  assert [r["v"] for r in data["data"]] == pytest.approx([0.303, -0.44])
62
+ request = calls[0][1]
63
+ assert request["bin"] == 15 and request["interval"] == "30"
64
+ assert request["vel_type"] == "default"
70
65
  # A second call is served from the cache.
71
66
  again = noaa.fetch_noaa_current_predictions(
72
67
  "LIS1027",
@@ -74,13 +69,12 @@ def test_harmonic_series_in_metres_per_second(tmp_path):
74
69
  "2026-04-02T00:00:00",
75
70
  "2026-04-02T00:30:00",
76
71
  cache_dir=str(tmp_path),
77
- get=get,
78
72
  )
79
73
  assert again == data
80
74
  assert len(calls) == 2
81
75
 
82
76
 
83
- def test_subordinate_station_is_refused(tmp_path):
77
+ def test_subordinate_station_is_refused(tmp_path, monkeypatch):
84
78
  rows = [
85
79
  {
86
80
  "Type": "flood",
@@ -92,7 +86,7 @@ def test_subordinate_station_is_refused(tmp_path):
92
86
  "Velocity_Major": 58.3,
93
87
  }
94
88
  ]
95
- get, _ = fake_get({"current_predictions": {"cp": rows}})
89
+ answer(monkeypatch, {"current_predictions": {"cp": rows}})
96
90
  with pytest.raises(RuntimeError, match="subordinate"):
97
91
  noaa.fetch_noaa_current_predictions(
98
92
  "ACT2991",
@@ -100,11 +94,10 @@ def test_subordinate_station_is_refused(tmp_path):
100
94
  "2026-04-02T00:00:00",
101
95
  "2026-04-02T06:00:00",
102
96
  cache_dir=str(tmp_path),
103
- get=get,
104
97
  )
105
98
 
106
99
 
107
- def test_station_listing_keeps_harmonic_bins_in_the_box(tmp_path):
100
+ def test_station_listing_keeps_harmonic_bins_in_the_box(tmp_path, monkeypatch):
108
101
  listing = {
109
102
  "stations": [
110
103
  {
@@ -154,19 +147,15 @@ def test_station_listing_keeps_harmonic_bins_in_the_box(tmp_path):
154
147
  },
155
148
  ]
156
149
  }
157
- calls = []
158
-
159
- def get(url, params, timeout):
160
- calls.append(url)
161
- return FakeResponse(listing)
162
-
150
+ calls = answer(monkeypatch, listing=listing)
163
151
  out = noaa.fetch_noaa_current_stations(
164
- [-73.86, 40.75, -72.84, 41.35], cache_dir=str(tmp_path), get=get
152
+ [-73.86, 40.75, -72.84, 41.35], cache_dir=str(tmp_path)
165
153
  )
166
154
  assert [(e["id"], e["bin"]) for e in out] == [("LIS1027", 1), ("LIS1027", 15)]
167
155
  assert out[1]["depth_m"] == 6.71
156
+ assert calls[0][2] == {"type": "currentpredictions", "units": "metric"}
168
157
  # The listing is cached: a second call does not fetch.
169
158
  noaa.fetch_noaa_current_stations(
170
- [-73.86, 40.75, -72.84, 41.35], cache_dir=str(tmp_path), get=get
159
+ [-73.86, 40.75, -72.84, 41.35], cache_dir=str(tmp_path)
171
160
  )
172
161
  assert len(calls) == 1