geoenrich 0.7.0

Enrich longitude/latitude points with coast distance, bathymetric depth, sea name, and nearest country/municipality
docs.rs failed to build geoenrich-0.7.0
Please check the build logs for more information.
See Builds for ideas on how to fix a failed build, or Metadata for how to configure docs.rs builds.
If you believe this is docs.rs' fault, open an issue.
Visit the last successful build: geoenrich-0.8.0

geoenrich

Latest release

geoenrich is a Rust command-line tool that adds geospatial attributes to a table of points. Give it a file with longitude and latitude columns and it appends any of:

  • coast: distance to the nearest shoreline (GSHHG).
  • depth: bathymetric depth at the point (GEBCO).
  • sea: the sea or ocean name at the point (IHO Sea Areas).
  • place: the nearest country and municipality (Natural Earth + GISCO).
  • nearest: the nearest location in a second table you supply, and the distance to it (any two sets, for example measurements and fish farms).

It reads and writes Parquet (default), CSV, TSV, and the gzip variants csv.gz and tsv.gz. Each command reduces the input to unique rounded locations, processes those in parallel, and joins the results back onto every row, so a file with millions of rows but few distinct positions is cheap to enrich.

Status: all five modules are implemented and tested: coast (nearest GSHHG shoreline by projected R-tree lookup), depth (GEBCO grid lookup), sea (IHO point in polygon with a nearest fallback), place (nearest Natural Earth country and GISCO LAU municipality), and nearest (nearest point of a caller-supplied table by unit-sphere R-tree). See CLAUDE.md for the algorithm and caveats per module.

Install

cargo build --release
# binary at target/release/geoenrich

The depth command reads GEBCO NetCDF and links the HDF5 / NetCDF C libraries, so you need the dev headers (as with ctddump):

# Ubuntu / Debian
sudo apt-get install libhdf5-dev libnetcdf-dev
# macOS
brew install hdf5

Usage

geoenrich <command> <input> [options]

Every command shares these options:

Option Default Meaning
-o, --output <FILE> <stem>.<command>.<input format> Output file
--in-format <FMT> inferred, else parquet parquet, csv, tsv, csv.gz, tsv.gz, auto
--out-format <FMT> inferred, else parquet same set
--overwrite off Replace clashing output columns instead of failing
--lon-col <NAME> longitude Longitude column
--lat-col <NAME> latitude Latitude column
--decimals <N> 3 Rounding applied before de-duplicating
-t, --threads <N> all cores Worker threads
-c, --config <TOML> none Config file (CLI flags override it)

The coast, sea, and place commands also take region options: a --region preset (global, baltic, norway, arctic, atlantic, europe, mediterranean) or explicit --min-lon/--max-lon/--min-lat/--max-lat, plus --proj-lon0/--proj-lat0 for the distance projection center. The default region is the whole globe.

The nearest command instead takes a second table (--to), the set of named locations to measure the distance to. Its coordinate columns default to longitude/latitude (--to-lon-col/--to-lat-col) and the name column to name (--name-field). Distances are great-circle (exact anywhere on the globe, so this command has no region or projection center), in kilometers by default or meters with --unit m.

Examples

# Distance to coast, GSHHG resolution 'f', result in kilometers
geoenrich coast cores.parquet \
  --data ./data/gshhg/gshhg-shp-2.3.7/GSHHS_shp/f \
  --unit km -o cores.coast.parquet

# Bathymetric depth from a GEBCO grid, reading and writing gzipped CSV
geoenrich depth cores.csv.gz --data ./data/gebco/GEBCO_2024_sub_ice.nc \
  -o cores.depth.csv.gz

# Sea name, cropping the reference data to the Norway region
geoenrich sea cores.parquet --region norway \
  --data ./data/iho/iho_sea_areas.geojson

# Nearest country and municipality
geoenrich place cores.parquet \
  --countries ./data/naturalearth/ne_10m_admin_0_countries.shp \
  --municipalities ./data/gisco/lau.shp

# Nearest fish farm to each measurement, distance in km
geoenrich nearest cores.parquet --to farms.parquet \
  --name-field farm_name -o cores.nearest.parquet

Run geoenrich <command> --help for the full interface.

To run several modules over one input and get a single file with all their new columns, use scripts/enrich.sh, which chains the selected modules and removes the intermediate files:

scripts/enrich.sh cores.parquet cores.enriched.parquet \
  --coast ./data/gshhg/gshhg-shp-2.3.7/GSHHS_shp/f \
  --depth ./data/gebco/GEBCO_2024_sub_ice.nc \
  --nearest farms.parquet --nearest-name-field farm_name

Run scripts/enrich.sh --help for all options.

Output columns

Command Appended columns
coast dist_to_coast (rename with --column)
depth bathymetry (rename with --column)
sea sea_name (rename with --column)
place country, country_code, municipality
nearest nearest_name, nearest_dist (rename with --name-column / --dist-column)

Data

The reference datasets are downloaded separately (they are large and not bundled). scripts/download_data.sh fetches and unpacks any of them into ./data/, one sub-directory per source, matching the example paths above:

# GSHHG, GEBCO, Natural Earth, and GISCO need no details
scripts/download_data.sh download gshhg gebco countries lau

# the Marine Regions (IHO) download sits behind a short form
scripts/download_data.sh --mr-name "Your Name" --mr-email you@example.org \
  --mr-country Norway download iho

Run scripts/download_data.sh --help for all options. Sources:

License

MIT.