Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

seastamp

seastamp is a small, fast command-line tool that stamps a table of points with sea attributes. Give it a file with longitude and latitude columns and it appends any of: distance to the nearest coast, bathymetric depth, the sea or ocean name, the nearest country and municipality, or the nearest location in a second table you supply.

It is written in Rust, uses no PROJ or GDAL (the geometry is hand-rolled and pure Rust), and reads and writes Parquet, CSV, TSV, and the gzip variants csv.gz and tsv.gz.

What you can do

CommandPurpose
coastDistance to the nearest shoreline (GSHHG).
depthBathymetric depth at the point (GEBCO grid).
seaSea or ocean name at the point (IHO Sea Areas).
placeNearest country and municipality (Natural Earth + GISCO).
nearestNearest location in a second table you supply, with its distance.
regionsList sea and ocean bounding boxes, to find a region for the commands above.
completionsPrint a shell completion script, so Tab fills in commands, flags, and region names.
reportSummarise a stamped file as a report table, or turn the table into a summary page.

How it works

The five stamping commands follow the same pipeline: read the input, reduce it to unique locations with rounded coordinates (3 decimals by default), stamp those unique locations in parallel, then join the results back onto every input row. A file with millions of rows but few distinct positions is therefore cheap to stamp, because only the distinct positions are ever looked up. Three commands stand outside that pipeline: regions only lists boxes, completions only prints a shell script, and report summarises files the others have already stamped.

Quick example

# Distance to the nearest coast, in kilometers
seastamp coast cores.parquet \
  --data ./data/gshhg/gshhg-shp-2.3.7/GSHHS_shp/f

# Nearest fish farm to each measurement
seastamp nearest cores.parquet --to farms.parquet --name-field farm_name

To see what the full pipeline produces, browse the live example report site, built with the helper scripts.

New here? Start with Installation, skim the Commands, then see the reference datasets each command needs.