nav-qa-processing

A Python port of R2R's NavManager, built in the same style as sbe-qa-processing. From a research vessel's raw GNSS files and a small cruise config, it produces:

• QA statistics and checks: completeness, gaps, records out of sequence, bad quality indicators, unreasonable speeds and accelerations, and the satellite, HDOP, altitude, speed and acceleration ranges.
• a PDF report, every figure as an SVG, and a Jupyter notebook that re-runs the assessment.
• by default, the standard R2R GeoCSV 2.0 navigation products (--no-products leaves them out):
  • bestres (<CRUISE>_bestres.geoCSV): every fix, with bad fixes flagged (#), and speed and course over ground;
  • 1min (<CRUISE>_1min.geoCSV): the good fix nearest each whole minute;
  • control (<CRUISE>_control.geoCSV): Douglas–Peucker control points of 1min.
• optionally with the R2R commands, an R2R QA 2.0 XML report with R2R's six tests, ratings and bounds.

It runs from the command line and can be integrated with OpenVDM to run as a post-transfer hook and end-of-cruise task.

docs/examples contain example products from a real cruise (SP2613): the PDF report, with and without R2R's certificate, products, a figure and the R2R QA 2.0 XML.

Requires Python 3.11+, uv and git. INSTALL.md has the commands for macOS, Debian and Ubuntu, RHEL, AlmaLinux and Rocky Linux, and Windows, the install for the OpenVDM hook, the map data, and installing for a ship without internet. In short:

git clone https://github.com/OceanDataTools/nav-qa-processing.git
cd nav-qa-processing
uv sync
uv run pytest

uv run nav-qa-processing formats                        # the raw formats it knows
uv run nav-qa-processing run path/to/fileset -f nav29 -o output/MYCRUISE
uv run nav-qa-processing run path/to/fileset -c my_config.toml -o output/MYCRUISE

Without -c, the products are named after the fileset directory, every fix in it is read, and the expected-area check is n/a. A config TOML sets the cruise's ID, dates and area, the GNSS files and their format, and the thresholds; every field is optional.

COOKBOOK.md walks through whole workflows with real output: a directory of a ship's raw nav files (finding the format, a config TOML, several sensors, the notebook, Python), and an R2R fileset (downloading it, its cruise TOML, R2R's assessment, comparing with R2R's products).

nav-qa-processing --help lists the commands, and nav-qa-processing COMMAND --help (or nav-qa-processing r2r COMMAND --help) documents each one. The core commands are formats, run and fetch-map-data; the R2R commands are a group under r2r; the OpenVDM commands are openvdm, config-from-openvdm and site-config.

Every command follows these conventions:

• -o/--output is a directory; only site-config writes a single file. Commands that make a cruise TOML write <OUTPUT_DIR>/<CRUISE_ID>_<FILESET_ID>.toml (default configs/), or to stdout with -o -.
• Existing outputs aren't overwritten without --force. A command checks before it does any work or asks R2R anything.
• Fileset IDs are integers.
• A command exits 0 on success and 1 when it refuses (e.g. existing outputs) or fails with an expected error (a server that can't be reached, R2R not having what was asked for, a config that can't run the QA, a bad theme), with a one-line message on stderr, e.g. nav-qa-processing: couldn't reach R2R (service.rvdata.us): ... Check the network connection and try again.
• -v/--verbose, before or after the command, logs more: -v is INFO and -vv is DEBUG (default WARNING). -vv also prints the traceback of an expected error.

nav-qa-processing formats [ID]

Without ID, lists R2R's raw navigation format IDs (nav01 … nav33, uhdas, siomet, metoc_nav), whether this version can read each one, and the NMEA sentences it knows. With ID, describes that format (layout, sentences, vessels, R2R format IDs, examples) or sentence. IDs have two digits, so they sort in order: nav02, not NavManager's nav2. NavManager's spelling is still accepted wherever a format ID is given (-f, [nav] format, formats ID).

nav-qa-processing run [-c CONFIG_TOML] [-f FORMAT_ID] [--nav NAME] [-o OUTPUT_DIR] [--force]
                      [--theme THEME_TOML] [--execute-notebook] [--no-products] FILESET_DIR

Reads the fileset's primary GNSS feed, flags bad fixes, computes the QA statistics and checks, and writes the three products, the figures and the PDF report.

It writes <CRUISE>_bestres.geoCSV, <CRUISE>_1min.geoCSV and <CRUISE>_control.geoCSV, and the figures as SVGs in <CRUISE>_plots/, where <CRUISE> is the config's [cruise] id, or the fileset directory's name. With several position sensors, every output of a feed other than the primary also carries the feed's name, e.g. <CRUISE>_seapath_bestres.geoCSV:

Long cruises are reduced for drawing (a simplified track line, min/max bands per time bin, at most 3,000 markers per flag); counts in the legends are the full ones.

It also writes <CRUISE>_qa_report.pdf, which embeds the SVGs as vector drawings. Its sections follow one another without page breaks; a section starts a new page only when it doesn't fit on the current one:

Integrations put their pages after the title block: r2r run adds R2R's certificate, with R2R's ranges over every record before QC.

And it writes <CRUISE>_qa.ipynb, a notebook that re-runs the assessment step by step: the config (the config file, or the run's config written into it as TOML), run_qa, the checks, statistics, QC flags and errors, every figure, the products, and writing the reports again (all but the notebook itself). Edit its paths or the config's [thresholds] and re-run it to change the assessment; see Opening the notebook. It prints a summary: the fixes read, QC's flags, the products' sizes, and every check with its status.

nav-qa-processing fetch-map-data

Downloads the Natural Earth layers the trackline map uses (1:10m land, lakes and coastlines, and the 1:110m world for the inset, about 27 MB) into cartopy's data directory, so the map has coastlines offline, e.g. at sea. Without them, the map is drawn without coastlines and says so, and the "Over water" check, which uses the same land and lakes, is n/a. Setting the environment variable NAV_QA_NO_MAP_DATA has the same effect without touching the network; the tests set it, so they never download map data (tests marked map_data use it when it's already here). It takes no arguments.

The notebook imports this package, so it has to run on the project's Python (.venv), not on the Python of whichever Jupyter opens it. A Jupyter installed with Homebrew, Anaconda or pip starts its own Python by default, which doesn't have this project's packages, so the first cell fails with ModuleNotFoundError: No module named 'nav_qa_processing'. Either:

Run JupyterLab from the project. Nothing to set up, and nothing is added to .venv or uv.lock:

uv run --with jupyterlab jupyter lab output/SP2613/SP2613_qa.ipynb

Or use the Jupyter you already have. Register the project's Python as a kernel, once per checkout:

uv run python -m ipykernel install --user --name nav-qa-processing --display-name "Python (nav-qa-processing)"

Then, in each notebook, choose Kernel → Change Kernel… → Python (nav-qa-processing). The generated notebooks ask for the default python3 kernel, so do this for each new one. It needs ipykernel from the dev group; if you move the checkout or delete .venv, register it again; jupyter kernelspec uninstall nav-qa-processing removes it.

The notebook's paths to the fileset, the config, the theme and the output directory are absolute, so it doesn't matter where Jupyter starts. --execute-notebook runs the notebook with the project's Python and needs neither setup. It runs every cell but the last, which would rewrite the reports just written; run that one yourself to write them again.

A config TOML describes the cruise, the GNSS feed and the thresholds. Every table and key is optional, but a key that isn't one of them is an error, which says where a misplaced or misspelled key belongs (cruise_id (top level): did you mean [cruise] id?), as is a value where a table belongs or a table where a value does ([cruise] extent must be a table). The keys of an R2R cruise TOML are accepted too. configs/config.example.toml shows every key, commented where it's optional or at its default. An example:

[cruise]
id = "SP2613"                     # the products' file name prefix and GeoCSV cruise_id
name = "MPL Internship Program Day at Sea"
pi = "Pereira, Filipe"
vessel_name = "Robert Gordon Sproul"
depart_date = 2026-07-09          # TOML dates, not strings
arrive_date = 2026-07-09
doi = "doi:10.7284/911454"        # GeoCSV source_event

[cruise.extent]                   # expected area [decimal degrees, east and north positive]
westernmost = -117.38
easternmost = -117.22
southernmost = 32.59
northernmost = 32.71

[fileset]
doi = "doi:10.7284/169851"        # GeoCSV source_dataset
manifest = "MD5_Summary.txt"      # checksums for a plain directory; relative to this file

[nav]                             # the primary GNSS feed
format = "nav29"
files = "data/*bx992*.txt"        # glob within the fileset

[nav.device]                      # the receiver or INS, for the reports; every key optional
make = "Trimble"
model = "BX992"
location = "main mast"

[provenance]
contact_institution = "Scripps Institution of Oceanography"
contact_email = "ship-tech@example.org"

[geocsv]
attribution = "Scripps Institution of Oceanography"

[thresholds]                      # defaults below
max_accel = 1.0

[thresholds], with their defaults:

The QC rules are described in src/nav_qa_processing/qc.py.

Parsing rules:

• An unknown key, in any table, is an error that says where a misplaced key or table belongs, or the closest key to a misspelled one ([thresholds] max_gpa: did you mean max_gap?). So is a value of the wrong shape: a value where a table belongs, or a table where a value does.
• The keys of an R2R cruise TOML are accepted, so it works as a config too, as is the site TOML's [openvdm] output_extra_directory.
• [fileset] manifest and theme fonts and logo are relative to the TOML file; [nav] files to the fileset.

The PDF, its figures and the notebook can take a house style: page size and margins, fonts, text sizes, colors, a logo and the footer. Pass a theme file with --theme (run and r2r run), or set a [theme] table in the config, which applies over the file's settings. configs/theme.example.toml shows every setting:

uv run nav-qa-processing run path/to/fileset -c my_config.toml --theme configs/theme.example.toml

[theme]                     # in a config TOML
page_size = "A4"
logo = "logo.png"           # relative to the TOML file
organization = "Example Oceanographic Institution"
palette = "colorblind"      # Okabe-Ito colors, distinct with common color vision deficiencies

[theme.colors]
water = "#e6f0f7"

A bad setting (an unknown key, a color that isn't #rrggbb, a missing font or logo) stops the run before it reads anything, with a one-line message. QC flags are drawn in the palette's distinct colors (matplotlib's tab10, or Okabe–Ito with colorblind). Fonts must be TrueType (.ttf). The notebook re-creates the same theme, so figures re-run there match the PDF.

The r2r commands add R2R's six navigation tests, its rating and the R2R QA 2.0 XML, and write the products with R2R's GeoCSV source values. They take a cruise TOML with R2R's IDs, which comes from R2R's catalog:

uv run nav-qa-processing r2r fetch-fileset SP2613 169851        # into data/SP2613_169851_gnss/
uv run nav-qa-processing r2r config-from-catalog SP2613 169851  # configs/SP2613_169851.toml
uv run nav-qa-processing r2r run configs/SP2613_169851.toml data/SP2613_169851_gnss -o output/SP2613

r2r run writes, by R2R's names:

run -c takes the same cruise TOML and ignores the R2R fields.

nav-qa-processing r2r run [-o OUTPUT_DIR] [--force] [--theme THEME_TOML] [--execute-notebook]
                          [--no-products] [--r2rnav] CRUISE_TOML FILESET_DIR

Runs the QA as run does, then R2R's six tests, and writes the products, figures, PDF with R2R's certificate, notebook and QA 2.0 XML.

It prints the R2R rating and each test's rating and result, then the core summary.

nav-qa-processing r2r config-from-catalog [-o OUTPUT_DIR] [--force] [--no-qa-report]
                                          CRUISE_ID FILESET_ID

Writes an R2R cruise TOML from R2R's catalog: the cruise's name, chief scientist, vessel, operator and scheduler, dates, ports, DOIs and navigation bounding box, and the GNSS receiver, R2R format and nav format. It checks that FILESET_ID is one of the cruise's navigation filesets (GNSS, or an INS such as Falkor (too)'s POS/MV), and lists them if it isn't. R2R's API has no port coordinates, country or state, format alias or catalog dates; those come from R2R's QA report for the fileset, when it has one with fileset info (R2R's reports from 2024 and earlier don't).

It warns when this version has no reader for the fileset's R2R format; set [nav] format by hand then.

nav-qa-processing r2r config-from-qa [-o OUTPUT_DIR] [--force] R2R_QA_XML

Writes an R2R cruise TOML from the provenance and fileset info of one of R2R's QA 2.0 reports. Use it to check this tool's results against R2R's.

nav-qa-processing r2r fetch-fileset [-o OUTPUT_DIR] [--force] CRUISE_ID FILESET_ID

Downloads a released R2R GNSS fileset (a BagIt bag) into <OUTPUT_DIR>/<CRUISE_ID>_<FILESET_ID>_gnss/, with R2R's QA report beside it as r2r_qa.2.0.xml and R2R's r2rnav product bag (the three .geoCSV files) in products/. When R2R answers with an HTTP error (e.g. 503 while its service is down), the command says which download failed in one line and exits 1. If the raw files arrived but the QA report or products didn't, it says so: run it again with --force to fetch them.

An R2R cruise TOML is a config TOML with R2R's catalog details added. It must have [cruise] id, depart_date and arrive_date. The r2r config-from-* commands write it; this is tests/configs/SP2613_169851.toml:

[cruise]
id = "SP2613"
name = "MPL Internship Program Day at Sea"
pi = "Pereira, Filipe"
vessel_id = "32QU"                     # R2R's vessel ID: the ICES ship code
vessel_name = "Robert Gordon Sproul"
operator_id = "edu.ucsd.sio"           # R2R organization IDs
scheduler_id = "org.unols"
date_issued = "2026-07-22"             # R2R's catalog dates, as R2R writes them
date_modified = "2026-07-31T04:28:14Z"
depart_date = 2026-07-09               # required
arrive_date = 2026-07-09               # required
doi = "doi:10.7284/911454"

[cruise.extent]
westernmost = -117.3773103608
easternmost = -117.2262308092
southernmost = 32.5997440998
northernmost = 32.7053695673

[cruise.depart_port]                   # and [cruise.arrive_port]
name = "San Diego"
port_id = "100055"                     # R2R port ID
country_id = "us"
state_id = "ca"
longitude = -117.175
latitude = 32.71667

[cruise.arrive_port]
name = "San Diego"
port_id = "100055"
country_id = "us"
state_id = "ca"
longitude = -117.175
latitude = 32.71667

[fileset]
id = "169851"                          # R2R's raw GNSS fileset ID
doi = "doi:10.7284/169851"
date_created = "2026-07-22"
format_id = "100150"                   # R2R's format ID, and its alias
format_alias = "starc_raw"

[fileset.device]                       # the GNSS receiver, as R2R catalogs it
id = "101253"
make_id = "com.trimble"
model_id = "100542"
model_name = "BX992"

[nav]
format = "nav29"

[nav.device]                           # the receiver for the reports: R2R's device, written out
make = "com.trimble"                   # so `run -c` reports it too
model = "BX992"

[provenance]
distro_type = "post-cruise"
contact_institution = "Rolling Deck to Repository (R2R)"
contact_institution_id = "us.rvdata"
contact_email = "info@rvdata.us"

[geocsv]
attribution = "Rolling Deck to Repository (R2R) Program; http://www.rvdata.us/"

The keys it adds to a config TOML, all written to the XML:

R2R's six tests, written to the XML with R2R's names and bounds:

The overall rating is G if every test is G, R if any is R, else Y. Each result is rated as written in the report. How the statistics are computed, and where that differs from NavManager, is in src/nav_qa_processing/stats.py, src/nav_qa_processing/integrations/r2r/rules.py and docs/navmanager-differences.md.

The tests compare this tool with released R2R filesets: their pre-QC records, products, QA statistics and QA 2.0 reports. Where the ratings differ, the cause is in docs/navmanager-differences.md. SP2613, SP2503, BH19-30 and RC0014 are committed in tests/data/ and unpacked into data/ by the tests, so CI downloads nothing; fetch the others with r2r fetch-fileset (into data/). The tests that need one skip without it and name the command.

On the same filesets and machine, this tool takes 1.7 to 2.5 times less time than NavManager and 2.8 to 11 times more memory: NavManager streams through fixed buffers, and this tool holds the whole cruise, about 190 bytes a fix. A 20-day cruise at 2 Hz (3.5 M fixes) takes NavManager 8.9 minutes in 279 MB, and this tool 3.6 minutes in 786 MB. The measurements, why, and how to repeat them are in docs/performance.md.

On a ship running OpenVDM, the QA runs from OpenVDM's hooks through the cruise:

• During the cruise, after each transfer of the collection system that logs the GNSS (postCollectionSystemTransfer), at most every --min-interval: a failing receiver or a missing feed shows while there's time to fix it.
• When the cruise is finalized (preFinalizeCurrentCruise): the final reports, on the whole cruise. OpenVDM waits for them, so they're in the finalized cruise.
• Afterwards, by hand: any earlier cruise, from the cruise_config.json in its directory (A past cruise).

Each run writes the core products and reports (GeoCSV, SVG plots, PDF, notebook), not R2R's, into an OpenVDM extra directory. Setting it up (the install, the extra directory, the ship's site TOML and the hooks in openvdm.yaml) is in INSTALL.md.

• The cruise, from OpenVDM's API (api/warehouse/getCruiseConfig): its ID, name, PI, location, dates and extent, the warehouse directory, the transfer's destination, the extra directories and the MD5 summary. For a past cruise, from its cruise_config.json instead. The current cruise comes from the API rather than its cruise_config.json for two reasons: the hook sets the cruise extent through the API, after asking it which cruise is current, and OpenVDM rewrites the file only at setup, when the cruise is edited, on an export and at finalize, so an extra directory or transfer added mid-cruise isn't in it yet.
• The vessel's name and contact, from the site TOML, or where it leaves them blank, from openvdm.yaml's vessel block (OpenVDM 2.17). For a past cruise, from its cruise_config.json, the vessel it was on.
• The GNSS feed: OpenVDM doesn't know which of a collection system's files are the GNSS feed, or their format, so the ship's site TOML says ([nav] format and files). A ship logging several position sensors lists each as a [[nav]] table.

• Assesses each feed of the transfer: the site TOML's [nav], or each [[nav]] whose transfer is this one or has none, the primary first. A non-primary feed's outputs carry its name (<CRUISE>_seapath_…).
• Skips a transfer without new or updated files matching a feed's files (--changed-files), and with --min-interval a feed whose reports are newer than that.
• Reads the cruise's nav files from the transfer's directory, within the cruise's dates (an open-ended cruise ends today, UTC), and checks their checksums against OpenVDM's MD5 summary. Files changed after the summary was written count as pending, not failures.
• Writes into the extra directory, replacing earlier ones: the GeoCSV products, the plots, the PDF, the notebook, and <CRUISE>_config.toml, a snapshot of what OpenVDM and the site TOML supplied, which the notebook re-runs from. Run as root, it gives them to the warehouse user.
• Adds those files to the cruise's MD5 summary, with OpenVDM's utils/update_md5_summary.py (OpenVDM 2.16.1 or later).
• Sets OpenVDM's cruise extent (cruiseExtent, OpenVDM 2.17) to the box around the primary feed's fixes that pass QC, so a jump to 0, 0 never stretches it. Its "Within the expected area" check is then n/a, and other feeds are checked against the primary's track. With --no-set-extent, without a workerApiKey, for a past cruise or before OpenVDM 2.17, it checks the fixes against OpenVDM's extent instead, else the site TOML's [extent]. INSTALL.md covers the setup it needs.
• Fails in one line, which OpenVDM shows as the hook's message. One feed's failure doesn't stop the others. Updating the MD5 summary or the extent can fail without failing the hook: it logs a warning.

OpenVDM logs the hook's output in /var/log/openvdm/post_hooks.log. To see it directly, run the hook's command by hand, as root, without --changed-files or --min-interval (INSTALL.md step 5). Each run prints the cruise and feed it found, what it assumed (note: lines), the QA summary and the files it wrote.

nav-qa-processing openvdm [--openvdm-config OPENVDM_YAML] [--cruise-config CRUISE_CONFIG_JSON]
                          [--site-config SITE_TOML] [--no-set-extent]
                          [--changed-files FILES] [--theme THEME_TOML]
                          [--execute-notebook] [--no-products] [--min-interval DURATION]
                          TRANSFER

The hook: assesses the collection system transfer's nav files for OpenVDM's current cruise, or with --cruise-config any cruise, as above. Installed openvdm.yaml files call it, so its arguments keep their names; they're named as in sbe-qa-processing's hook.

nav-qa-processing config-from-openvdm [--openvdm-config OPENVDM_YAML]
                                      [--cruise-config CRUISE_CONFIG_JSON]
                                      [--site-config SITE_TOML] [--no-set-extent]
                                      [-o OUTPUT_DIR] [--force] TRANSFER

Builds the config TOML the hook would use, from OpenVDM's current cruise (or with --cruise-config any cruise) and the site TOML, without running the QA, and reports what's missing or assumed. TRANSFER, --openvdm-config, --cruise-config, --site-config and --no-set-extent are as for openvdm: when the hook would set the cruise extent, the config has no expected area. To review it, or run the QA by hand:

uv run nav-qa-processing config-from-openvdm OpenRVDAS --site-config configs/site.toml  # configs/<CRUISE>.toml
uv run nav-qa-processing run /path/to/cruise/OpenRVDAS -c configs/<CRUISE>.toml -o output/<CRUISE>

OpenVDM's API knows only the current cruise, but OpenVDM writes each cruise's config into its directory as cruise_config.json (its default name, set by CRUISE_CONFIG_FN in OpenVDM's www/app/Core/Config.php): its ID, name, PI, location, dates and extent, the transfers' and extra directories' destinations, the MD5 summary's name, and the vessel it was on. Give it with --cruise-config, and the hook or config-from-openvdm take the cruise from it instead of the API, with the site TOML as for the current cruise:

# Rebuild a past cruise's reports in its NAV_QA extra directory, as the hook would have
sudo /opt/nav-qa-processing/.venv/bin/nav-qa-processing openvdm OpenRVDAS \
    --cruise-config /data/CruiseData/SP2613/cruise_config.json \
    --site-config /opt/nav-qa-processing/configs/site.toml

# Or keep it as a config TOML, and run the QA anywhere
nav-qa-processing config-from-openvdm OpenRVDAS --site-config configs/site.toml \
    --cruise-config /data/CruiseData/SP2613/cruise_config.json -o configs   # configs/SP2613.toml
nav-qa-processing run /data/CruiseData/SP2613/OpenRVDAS -c configs/SP2613.toml -o output/SP2613

• The cruise's directory is the JSON's, wherever the cruise now is: an archived or copied cruise works, as long as its directory keeps the cruise's ID as its name, as OpenVDM names it.
• OpenVDM's cruise extent isn't set: it's the current cruise's. The fixes are checked against the JSON's extent.
• The reports go into the cruise's MD5 summary where OpenVDM is installed and still has the cruise in its warehouse: they're given to OpenVDM by their full paths, so it refuses files outside its directory for the cruise. Otherwise, or without OpenVDM, the hook warns that the reports aren't in the summary and still succeeds.
• The reports belong to the owner of the cruise's directory, run as root.
• A cruise the hook ran on also has <CRUISE>_config.toml beside its reports, the config as of that run, which run -c takes as it is.

nav-qa-processing site-config [-o SITE_TOML] [--openvdm-config OPENVDM_YAML] [--force]

Writes the site TOML by prompting, on stderr, for each field OpenVDM doesn't store: the vessel name and report contact (their defaults the site TOML's, else those in openvdm.yaml's vessel block), the GNSS feed's format (one with a reader; the prompt lists them), files glob, device (make, model, serial number, location) and transfer, any the vessel's top speed in m s-1 ([thresholds] max_speed, default 8.7), other position sensors (a name each, then the same; - drops one), the GeoCSV attribution, the extra directory and an expected cruise area. Enter keeps the [default] and - clears it. It works offline. Over an existing file (with --force) its values are the defaults, and at the end of input every remaining field keeps its default, so with no input the file is written back unchanged. The other [thresholds] and [theme] are kept as they are.

The per-ship settings OpenVDM doesn't store. Only [nav] format is required; configs/site.example.toml shows every key. Any other key is an error, as in a config TOML.

A site TOML describes the ship, so it has a [vessel] table and no [cruise]: the hook gets each cruise's ID, name, chief scientist, location and dates from OpenVDM, and writes them with the site's settings into a config TOML for the cruise, <CRUISE>_config.toml, where the vessel's name is [cruise] vessel_name. A [cruise] table here, or a [vessel] one in a config TOML, is an error that says so.

uv run pytest -n auto --dist loadgroup          # all tests, on every core
uv run pytest tests/test_cli.py::test_version   # one test
uv run ruff check . && uv run ruff format --check .

CI (.github/workflows/ci.yml) runs Ruff and the tests on Linux (Python 3.11 to 3.15, and 3.11.3, before tarfile's "data" filter, like Debian 12's 3.11.2), macOS and Windows on every pull request and push to main. It downloads nothing: the tests unpack the reference filesets committed in tests/data/ and draw on Natural Earth clipped to their areas. The tests never download map data either; with fetch-map-data run, the tests marked map_data use the full layers.

tests/test_openvdm_contract.py checks the OpenVDM hook against OpenVDM's own code rather than stand-ins: how OpenVDM runs the hook commands INSTALL.md documents, its update_md5_summary.py, and the cruise config file it writes. It needs a checkout of OpenVDM's 2.17 branch with a venv of its requirements, at OPENVDM_SOURCE (default ../openvdm), and skips without one; CI's "OpenVDM contract" job clones it:

git clone --branch 2.17 https://github.com/OceanDataTools/openvdm.git ../openvdm
uv venv --python 3.12 ../openvdm/venv && VIRTUAL_ENV=../openvdm/venv uv pip install -r ../openvdm/requirements.txt
uv run pytest tests/test_openvdm_contract.py

MIT