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.

Installation

Prebuilt binary

The quickest option: every release attaches prebuilt archives for Linux and macOS (x86_64 and arm64) to its GitHub release. They bundle HDF5 and netCDF, so they need no system libraries at all: download the archive for your platform, unpack it, and run the seastamp binary inside. The helper scripts ship in the archive alongside it.

The Linux binaries are linked against glibc 2.17, so they run on any distribution with glibc 2.17 or newer: RHEL / CentOS 7, Rocky Linux 8, Ubuntu 18.04, Debian 9, and everything more recent.

From crates.io

cargo install seastamp

This compiles from source, so the depth command needs the HDF5 / NetCDF development headers (see System dependencies).

Build from source

seastamp is a Rust project, so a recent stable toolchain is all you need:

git clone https://github.com/AIQC-Hub/seastamp
cd seastamp
cargo build --release
# binary at target/release/seastamp

To build a self-contained binary that vendors HDF5 and netCDF (as the release archives do, needing no system libraries), add --features static-netcdf. This compiles the C libraries from source, so it needs cmake and takes longer.

System dependencies

Only the depth command needs anything beyond the Rust toolchain: it reads GEBCO NetCDF and links the HDF5 / NetCDF C libraries, so a source or cargo install build needs their development headers (the same system dependency as ctddump):

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

# macOS
brew install hdf5

The other four commands (coast, sea, place, nearest) use only pure-Rust geometry and have no system dependencies. The prebuilt binary and a --features static-netcdf build vendor the C libraries, so neither needs these.

Shell completion

Optional, and worth the minute it takes: seastamp completions <shell> prints a completion script, after which Tab fills in commands, flags, their enumerated values, and all 109 names --region accepts.

# bash
mkdir -p ~/.local/share/bash-completion/completions
seastamp completions bash > ~/.local/share/bash-completion/completions/seastamp

# zsh (with ~/.zfunc on $fpath)
mkdir -p ~/.zfunc
seastamp completions zsh > ~/.zfunc/_seastamp

# fish
seastamp completions fish > ~/.config/fish/completions/seastamp.fish

Start a new shell afterwards, and regenerate the script when you upgrade seastamp: it is a snapshot of one version’s CLI. elvish and powershell are supported too. See completions for the details, including how to make bash list candidates on the first Tab.

Reference data

The datasets each command stamps from (shorelines, bathymetry, sea polygons, country and municipality boundaries) are large and are not bundled. Download the ones you need with the helper script, described under Reference datasets.

Check it works

seastamp --help
seastamp coast --help

Every command is self-documenting through --help at each level.

coast

Distance to the nearest shoreline, from GSHHG shoreline polygons.

seastamp coast <INPUT> --data <GSHHG> [OPTIONS]

Appends one column, dist_to_coast (rename with --column), holding the distance from each point to the nearest coastline in kilometers (default) or meters (--unit m).

How it works

The GSHHG L1 (land / ocean) boundary segments are cropped to the region box plus a 5 degree margin, projected through the region’s Lambert Azimuthal Equal-Area (LAEA) projection into meters, and indexed in an R-tree. Each point is projected the same way and takes the planar distance to the nearest segment. Segments are dropped, never clipped, so cropping cannot invent artificial shoreline; a point whose true nearest coast lies beyond the region-plus-margin box gets an over-estimate, so widen the region for such cases.

Because the distance is planar, it is accurate near the projection center and degrades away from it. For points spread too widely for any one center, pass --partition and each area is measured in its own projection.

Options

Beyond the shared options and the region options:

OptionDefaultMeaning
--data <PATH>requiredGSHHG shapefile directory (resolution f recommended) or a GSHHS_*_L1.shp file
--unit <km|m>kmDistance unit for the output column
--column <NAME>dist_to_coastOutput column name

Example

seastamp coast cores.parquet \
  --data ./data/gshhg/gshhg-shp-2.3.7/GSHHS_shp/f \
  --unit km -o cores.coast.parquet

See Reference datasets for how to obtain GSHHG.

depth

Bathymetric depth at each point, from a GEBCO gridded NetCDF file.

seastamp depth <INPUT> --data <GEBCO.nc> [OPTIONS]

Appends one column, bathymetry (rename with --column), holding the GEBCO elevation at each point in meters, and a second boolean on_land column with --on-land.

How it works

GEBCO is a regular lon/lat grid, so no nearest-neighbor search is needed. The lat and lon axes are read once to learn each axis origin and spacing, then every point maps straight to its nearest grid cell by arithmetic and reads the single elevation cell. Longitudes are normalized to [-180, 180), and points off the grid yield a null.

Unlike the other commands, depth looks up its points on a single thread, so --threads does not change how the grid is read. HDF5, which the NetCDF reader sits on, is often built without thread safety, and such a build cannot be entered from more than one thread even when the calls are locked so they never overlap. Nothing is lost by it: the reads were funnelled through one lock in any case, so they never ran concurrently.

GEBCO elevation is negative below sea level. By default the value is reported as stored (negative under water); --positive flips the sign so depth reads positive under water and land reads negative.

This command needs no region: a grid lookup is global by construction.

Options

Beyond the shared options:

OptionDefaultMeaning
--data <FILE>requiredGEBCO bathymetry NetCDF file
--positiveoffReport depth as positive below sea level
--column <NAME>bathymetryOutput column name

Example

# Reading and writing gzipped CSV
seastamp depth cores.csv.gz \
  --data ./data/gebco/GEBCO_2024_sub_ice_topo.nc \
  --positive -o cores.depth.csv.gz

The depth command links the HDF5 / NetCDF C libraries; see Installation. See Reference datasets for how to obtain the GEBCO grid.

sea

Sea or ocean name at each point, from the IHO Sea Areas polygons.

seastamp sea <INPUT> --data <IHO> [OPTIONS]

Appends one column, sea_name (rename with --column), holding the name of the sea or ocean the point falls in.

How it works

The IHO Sea Areas features (Marine Regions GeoJSON or shapefile) are cropped whole to the region box plus a margin, and their bounding boxes are indexed in an R-tree. Each point is resolved by an even-odd point-in-polygon test over the candidate features, with a nearest-boundary fallback for points that fall just inland (for example inside a fjord not covered by a sea polygon).

--name-field selects which feature property holds the name (default NAME); the command errors clearly if that field is absent.

Containment is an exact lon/lat test, so no projection is involved and most results are unaffected by which region you pick. Only the nearest-boundary fallback is planar. For points spread too widely for one projection center, pass --partition, which also crops the polygons per area rather than keeping one global set.

Options

Beyond the shared options and the region options:

OptionDefaultMeaning
--data <PATH>requiredIHO Sea Areas polygons (GeoJSON or shapefile)
--name-field <NAME>NAMEProperty / attribute field holding the sea name
--column <NAME>sea_nameOutput column name

Example

seastamp sea cores.parquet --region norway \
  --data ./data/iho/iho_sea_areas.geojson

See Reference datasets for how to obtain the IHO Sea Areas.

place

Nearest country and municipality, from Natural Earth countries and, optionally, Eurostat GISCO LAU municipalities.

seastamp place <INPUT> --countries <NE> [--municipalities <GISCO>] [OPTIONS]

Appends three columns, or four when --municipalities is given:

ColumnMeaning
countryCountry name
country_codeISO alpha-3 code (the Natural Earth -99 placeholder becomes null)
municipalityMunicipality name (empty unless --municipalities is given)
municipality_distDistance to that municipality, 0 when the point is inside it. Only with --municipalities

How it works

Both the country and the municipality lookups resolve a point by containment first (an even-odd point-in-polygon test over R-tree candidates) and fall back to the nearest boundary otherwise, so an offshore point still gets the closest land unit. Attribute fields are auto-detected from candidate name lists, so minor schema drift between dataset versions needs no flags.

--municipalities is optional: without it the municipality column is left empty, no municipality_dist column is added, and a note says so.

Bounding the municipality match

The municipality fallback is unbounded, and GISCO LAU covers Europe only, so a site outside that coverage still resolves to whatever municipality is nearest, however far away. A point a few hundred km offshore picks up a coastal municipality that it is in no sense part of.

municipality_dist makes that visible: 0 means the point really is inside the polygon, and a large value means the fallback reached a long way. --max-municipality-dist turns it into a filter, discarding matches beyond the limit. The name and the distance are cleared together, so a row never carries one without the other. Both are read in --unit, kilometres by default.

country needs none of this, since Natural Earth is global.

Both lookups fall back to the nearest boundary in a plane, and municipality_dist is measured there too, so a projection that does not suit your points can return the wrong place entirely rather than a slightly wrong number. On 540 globally spread points, a single projection assigned a different nearest country to 91 of them than --partition did, and spot checks went to --partition every time.

Options

Beyond the shared options and the region options:

OptionDefaultMeaning
--countries <PATH>requiredNatural Earth countries shapefile
--municipalities <PATH>noneGISCO LAU municipalities shapefile
--max-municipality-dist <N>noneDiscard a municipality match further than this, in --unit
--unit km|mkmUnit for municipality_dist and the cutoff

Example

seastamp place cores.parquet \
  --countries ./data/naturalearth/ne_10m_admin_0_countries.shp \
  --municipalities ./data/gisco/lau.shp \
  --max-municipality-dist 50

See Reference datasets for how to obtain Natural Earth and GISCO.

nearest

Nearest location in a second table you supply, with the distance to it.

seastamp nearest <INPUT> --to <REFERENCE> [OPTIONS]

Unlike the other commands, the reference data is not a bundled dataset but a second table you pass with --to: any set of named locations (fish farms, ports, stations). For every input point it appends the name of the nearest reference location and the great-circle distance to it.

Appends two columns:

ColumnMeaning
nearest_nameName of the nearest reference location (rename with --name-column)
nearest_distDistance to it, in km (default) or m (rename with --dist-column)

How it works

Every reference point is mapped to a unit-sphere (x, y, z) vector and indexed in a 3D R-tree. Each input point is projected the same way and takes the R-tree’s nearest neighbor. Euclidean chord distance on the unit sphere grows monotonically with the great-circle distance, so the nearest by chord is the nearest on the globe; the chord is then converted back to meters.

The unit sphere is used instead of the region LAEA on purpose: the two sets can be anywhere and arbitrarily far apart, and a single planar projection distorts distances away from its center. The sphere is exact everywhere, so this command takes no region box or projection center. Reference rows with a missing coordinate are skipped; an empty reference set leaves every output null.

Options

Beyond the shared options:

OptionDefaultMeaning
--to <FILE>requiredReference table: the second set of locations
--to-format <FMT>inferredFormat of the reference table
--to-lon-col <NAME>longitudeLongitude column in the reference table
--to-lat-col <NAME>latitudeLatitude column in the reference table
--name-field <NAME>nameColumn in the reference table holding each location’s name
--unit <km|m>kmDistance unit for the output distance column
--name-column <NAME>nearest_nameOutput column for the nearest name
--dist-column <NAME>nearest_distOutput column for the distance

Example

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

The name column is cast to text, so numeric ids work as names too.

regions

List sea and ocean bounding boxes: every name --region accepts, or one box per named area in an IHO Sea Areas file.

seastamp regions [OPTIONS]

This is the one command that takes no input table. It stamps nothing: it answers “which seas exist, and where are they”, so you can find a region for your data. The presets are mostly European; the 101 IHO Sea Areas names that sit behind them cover the world.

The two listings

Without --data, every name --region accepts is listed: the seven presets, then the 101 IHO Sea Areas v3 areas baked into the binary. No data file needed.

seastamp regions
name                  min_lon   max_lon   min_lat   max_lat  source  antimeridian
global                -180.00    180.00    -90.00     90.00  preset
baltic                   8.00     31.00     53.00     66.00  preset
...
Arctic Ocean          -180.00    180.00     71.39     90.00  iho
Baltic Sea               9.52     23.51     52.65     59.94  iho
Bering Sea             161.82   -156.23     51.35     66.56  iho     yes
Coral Sea              141.02    169.87    -30.00     -6.79  iho
North Sea               -4.45     12.01     51.00     61.02  iho
Southern Ocean        -180.00    180.00    -85.56    -60.00  iho

Any of those names goes straight into --region:

seastamp coast cores.parquet --data ./data/gshhg/... --region "Coral Sea"

With --data, the boxes are re-derived from an IHO Sea Areas file instead of read from the baked-in table. That is what you want for a newer IHO release, or for any other named polygon layer:

seastamp regions --data ./data/iho/World_Seas_IHO_v3.shp

scripts/gen_iho_areas.py turns that output back into the baked-in table; see its header for the refresh procedure.

Saving the list

--output writes the same table in any supported format, so it can be joined or scripted against:

seastamp regions -o regions.parquet
seastamp regions --data ./data/iho/World_Seas_IHO_v3.shp -o seas.parquet

Add --quiet to write the file without printing.

Options

OptionDefaultMeaning
--data <PATH>noneIHO Sea Areas polygons (GeoJSON or shapefile). Omit to list the built-in names
--name-field <NAME>NAMEProperty or attribute holding the area name
--name <TEXT>noneKeep only areas whose name contains this text (case-insensitive)
-o, --output <FILE>noneAlso write the list to a file
--out-format <FMT>inferred, else parquetparquet, csv, tsv, csv.gz, tsv.gz
-q, --quietoffDo not print the table, only write it

Output columns

ColumnMeaning
nameThe area name, one row per name
min_lon, max_lonLongitude bounds in degrees
min_lat, max_latLatitude bounds in degrees
crosses_antimeridianTrue when the box runs east past 180 and continues from -180
sourcepreset, iho (the baked-in table), or data (derived from --data)

How the box is computed

Latitude is the plain minimum and maximum of the vertices. Longitude is not. Marine Regions splits its polygons at the antimeridian, so a Pacific area has vertices at both -180 and 180, and taking the minimum and maximum of those would report the whole globe for it. Instead seastamp finds the widest arc of longitude the area’s edges leave uncovered, and reports everything else: the smallest arc that actually contains the area.

The extent is built from edges rather than vertices, so a long edge with no intermediate vertex does not read as a gap. An area covering every longitude (the Arctic and Southern Oceans) reports the full -180 to 180 range, while one that merely reaches the line without crossing it (the East Siberian Sea, which ends at exactly 180.00) is left unflagged.

Reading the full IHO v3 shapefile takes about half a minute, nearly all of it parsing the 149 MB of geometry. Use --output if you want the list to hand.

Caveats

A crossing box cannot be used as-is. When crosses_antimeridian is true, min_lon is greater than max_lon, and seastamp rejects such a region (see Coverage and limits). In IHO v3 this is four areas: the Bering Sea, the Chukchi Sea, and the North and South Pacific Oceans. --region auto handles data in those areas correctly; naming them does not.

An IHO area is not the colloquial sea. IHO follows the S-23 limits, which split water bodies more finely than everyday usage. The Baltic Sea box stops at 23.5 E and 59.9 N because the Gulf of Bothnia, the Gulf of Finland, and the Gulf of Riga are three separate areas; the built-in baltic preset covers all four. Check the neighboring names before taking one area’s box as your region, or the crop will cut off part of your study area.

A big sea makes a poor region for coast. The region is also where planar distances are measured from, so a box spanning an ocean puts its own edges tens of percent out: --region "Indian Ocean" is about 5% off at the Arabian Sea edge, and --region "Southern Ocean" about 7%. The default --region auto does not have this problem, because it centers on the data rather than on the sea. This does not affect sea, depth, nearest, or place’s country.

The box is a rectangle, not the sea. It is the extent of the polygons, so it includes land and neighboring water. As a crop box that is exactly what is wanted; as a description of the sea it is coarse.

See also

  • Regions for what a region does and its precedence
  • Coverage and limits for where distances stay accurate
  • sea for stamping points with the name of the sea they fall in
  • scripts/gen_iho_areas.py for regenerating the baked-in table

completions

Print a shell completion script, so Tab fills in subcommands, flags, and the names --region accepts.

seastamp completions <SHELL>

Like regions, this command takes no input table and stamps nothing. It writes a script to stdout and exits. The script is generated from the same clap command tree the parser uses, so it cannot drift out of step with the real CLI.

Supported shells: bash, zsh, fish, elvish, powershell.

Installing it

Write the script where your shell looks at startup, then start a new shell.

bash

mkdir -p ~/.local/share/bash-completion/completions
seastamp completions bash > ~/.local/share/bash-completion/completions/seastamp

That path is read automatically if the bash-completion package is installed. Without it, put the script anywhere and source it from ~/.bashrc:

seastamp completions bash > ~/.seastamp-completion.bash
echo 'source ~/.seastamp-completion.bash' >> ~/.bashrc

zsh

mkdir -p ~/.zfunc
seastamp completions zsh > ~/.zfunc/_seastamp

~/.zfunc has to be on $fpath before compinit runs, so ~/.zshrc needs:

fpath=(~/.zfunc $fpath)
autoload -Uz compinit && compinit

fish

seastamp completions fish > ~/.config/fish/completions/seastamp.fish

PowerShell

seastamp completions powershell | Out-String | Invoke-Expression

Append that line to your profile ($PROFILE) to make it stick.

What completes

seastamp <TAB>                    coast  depth  sea  place  nearest  regions  completions
                                  (and the top-level flags, -h -V --help --version)
seastamp co<TAB>                  coast  completions
seastamp coast --<TAB>            every flag on coast, including the shared ones
seastamp coast --in-format <TAB>  auto  parquet  csv  tsv  csv.gz  tsv.gz
seastamp coast --region med<TAB>  mediterranean
seastamp completions <TAB>        bash  elvish  fish  powershell  zsh

Enumerated values (--in-format, --out-format, --unit) complete from the same list the parser accepts. Path options complete as files, and coast --data as a directory, since GSHHG is a directory of shapefiles.

--region completes from all 109 accepted names: auto, the seven presets, and the 101 IHO Sea Areas. They are offered to the shell but kept out of --help, where 109 values would bury every other flag. Run seastamp regions to see them with their boxes.

One Tab or two, in bash

By default bash completes on the first Tab only when exactly one candidate matches, and needs a second Tab to list an ambiguous set. To get the list on the first Tab, add this to ~/.inputrc:

set show-all-if-ambiguous on

zsh and fish already list on the first Tab.

Caveats

A region name with a space stops at its first word, in bash and zsh. Both shells receive candidates as one space-separated list, so --region Bar<TAB> completes to Barentsz, not Barentsz Sea. This is a limitation of the generated scripts, not of seastamp. It is not silent: running the truncated name reports the full one back at you.

$ seastamp coast cores.parquet --region Barentsz
Error: unknown region 'Barentsz'. Did you mean: Barentsz Sea?

Finish the name by hand, and quote it, as --region "Barentsz Sea". fish completes multi-word names whole.

The script is a snapshot of one version. It is generated when you run the command, not read from the binary at completion time, so a script written by an older seastamp will offer that version’s flags. Regenerate after upgrading.

Options

OptionDefaultMeaning
<SHELL>requiredbash, zsh, fish, elvish, or powershell

See also

  • Installation for getting the binary in the first place
  • regions for the names --region completes to
  • Regions for what a region does

report

Summarise files the stamping commands have written, as a report table (report stats), or turn such a table into a Markdown or HTML summary page (report summary).

seastamp report stats   [options] <stamped file> [dest]
seastamp report summary [--report-dir report] [--format md|html]
                        [--title TEXT] [--note TEXT]... [--top N] [-o dest] <stem>

Neither command stamps anything. stats reads a stamped file, and summary reads only the small table stats wrote, so a summary page can be rebuilt with a new title or notes in an instant. The report is written to dest (or -o), or to stdout when it is omitted.

report stats

Finds the columns the stamping commands added, by their default names, and reports on each one:

ColumnWritten byReported as
dist_to_coastcoastdistance
bathymetrydepthdepth
on_landdepth --on-landflag
sea_nameseatext
country, municipalityplacetext
municipality_distplace --municipalitiesdistance
nearest_namenearesttext
nearest_distnearestdistance

country_code is left out, since it restates country. A column renamed at stamping time (--column, --name-column, --dist-column) is not found.

From a Parquet file only these columns and the coordinates are read, so memory use is about their size (some 2 GB for 30 million rows with four stamped columns), well below what stamping the same file takes.

Rows and locations

Each stamping command rounds longitude and latitude (3 decimals by default), looks every unique location up once, and copies the result to all the rows there. The report counts the same way, so it gives every count twice:

  • rows: what the file carries;
  • locations: unique rounded positions, the lookups that were made.

Minimum, maximum, and mean are taken over locations, so a cast with hundreds of rows weighs no more than a single surface sample. Rows without a usable longitude and latitude get no stamped value; they are counted once, as (no position), and left out of everything else. Pass --decimals if the file was stamped with a different rounding.

The table

The report is one long table, so the same layout serves the whole file and a --by breakdown:

ColumnMeaning
columnthe stamped column, or (all) for the file totals
kindtotal, distance, depth, text, or flag
itemwhat the row counts (below)
unitkm or m for distances, m for depth
rows, locationsthe two counts
min, max, meanover locations, on the (value) row only

The items for each kind:

KindItems
total(located): rows with a position and their locations; (no position)
distance(value), (null), then one per distance band
depth(value), (null), land, then one per band of depth below sea level
textone per value, most locations first, then (null)
flagtrue, false, (null)

Every item is written even when its counts are zero, so a missing row never has to be read as zero.

Bands

Distances are banded at 1, 5, 20, and 100 km (< 1, 1-5, 5-20, 20-100, >= 100), and depth below sea level at 10, 50, 200, and 1000 m. Each band includes its lower edge and excludes its upper one. A depth location whose elevation is at or above sea level is land, the same test depth --on-land uses.

  • --dist-bands 1,5,20,100 sets the distance edges, in km whatever unit the column is in (a column in metres has them scaled to 1000, 5000, …).
  • --depth-bands 10,50,200,1000 sets the depth edges, in m.

Telling it how the file was stamped

A stamped file does not record its units or the depth sign convention, so give them with the same flags scripts/stamp.sh uses:

FlagDefaultWhen to pass it
--coast-unit km|mkmcoast --unit m
--place-unit km|mkmplace --unit m
--nearest-unit km|mkmnearest --unit m
--depth-positiveoffdepth --positive

Without --depth-positive a depth value is read as GEBCO elevation, negative under water, which is what depth writes by default.

Other options

  • -f, --format tsv|text|json: TSV (default), an aligned text table, or a JSON array of objects (empty cells become null).
  • --by COL: one block of rows per distinct value of COL (for example platform_code), under a leading column of that name. A position shared by two groups is a location of each.
  • --lon-col, --lat-col, --in-format: as for the stamping commands.
  • -t, --threads: worker threads for reading the file.
# Whole-file report, as TSV
seastamp report stats cores.stamped.parquet report/stamp/cores.tsv

# Per-platform, readable on screen
seastamp report stats --by platform_code -f text cores.stamped.parquet

# Stamped with --unit m and --positive
seastamp report stats --coast-unit m --depth-positive cores.stamped.parquet

report summary

Builds a single page for one file stem from <report-dir>/stamp/<stem>.tsv, the path stamp_data.sh writes its reports to. The page has an Overview of rows and locations, then a section per module the file was stamped with, in the order the modules run:

SectionTables
Distance to coaststatistics, distance bands
Depthstatistics, depth bands with land first, the land flag when present
Sea arealocations and rows per sea area
Placeper country, per municipality, distance to municipality
Nearest locationper reference location, distance to it

A module the file was not stamped with has no section. Percentages are of the located rows and locations. A name table lists the --top values (default 20) with the most locations and sums the rest in one row.

The page needs a whole-file report, so a TSV written with --by is refused.

Title and notes

The section prose is generic, the same for every file. Anything specific to a file goes in:

  • --title TEXT: replaces the default Summary: <stem> heading.
  • --note TEXT: a note under the title; repeat for several.

Both are plain text and are escaped in HTML output. In the pipeline they are supplied per stem by summary_data.sh, which is the place to edit what a page says about a given product.

# Markdown page, to stdout
seastamp report summary cores

# HTML page with a title and a note
seastamp report summary nrt_bo_bo --format html \
  --title "Baltic Sea: Near Real Time, regional product (BO)" \
  --note "Stamped against GSHHG f and GEBCO 2024." \
  -o summary/nrt_bo_bo.html

The Markdown pages are what summary_site.sh builds a web site from.

Coverage and limits

What works anywhere in the world, what needs configuring first, and what does not work yet. Read this before running seastamp on data outside northern Europe.

What works where

CommandOutside EuropeWhy
depthWorks anywhereGEBCO is a global grid read by arithmetic, with no projection involved.
nearestWorks anywhereGreat-circle distance on the unit sphere, exact globally, and it takes no region or projection center.
seaWorks anywhereIHO Sea Areas is global, and a point inside a sea polygon is resolved by an exact lon/lat containment test. Only the fallback for points inside no polygon is projected.
place, countryWorks anywhereNatural Earth is global, containment first.
place, municipalityEurope onlyGISCO LAU has no coverage elsewhere.
coastWorks anywhereThe distance is measured in a projection centered on the region, and the default region centers itself on your data.

The region centers itself

coast and place’s municipality_dist measure distance in a plane centered on the region (see Technical notes). That is accurate near the center and degrades away from it.

Since 0.12.0 the default region is auto, which derives the box and the center from your own points, so this mostly takes care of itself. Real measurements from a three-point survey off Bergen:

Regiondist_to_coast
auto (default)40.97, 0.400, 69.41 km
global (the old default)44.09, 0.423, 77.65 km

The old default was about 8% out there, and far worse further from (0, 0). See Regions for what auto does and when it gives up.

The rest of this section is about the case auto cannot fix, and about what happens if you pin a region that does not match your data. How far off a 10 km distance is, against a center at (0, 0):

Data locationDistance from (0, 0)Error
Canary Islands3 550 km-1.7%
North Sea6 233 km-11.6%
Baltic6 767 km-9.1%
Gulf of Maine8 239 km+22.6%
Bering Sea13 563 km-50.8%
New Zealand15 341 km-61.4%

Note that this was never about being outside Europe. A North Sea run under the old default was already about 12% out. Centering the projection on the data removes essentially all of it, which is what auto now does by default.

Use a preset or an IHO sea name when you want the region pinned and reproducible rather than derived:

seastamp coast cores.parquet --data ./data/gshhg/... --region norway

Anywhere else, any of the 101 IHO sea names works as a region, no data file needed. seastamp regions lists them:

seastamp coast cores.parquet --data ./data/gshhg/... --region "Tasman Sea"

Or give the box and the center directly:

# a run off New Zealand
seastamp coast cores.parquet --data ./data/gshhg/... \
  --min-lon 160 --max-lon 180 --min-lat -50 --max-lat -30 \
  --proj-lon0 170 --proj-lat0 -40

For a named region the center defaults to the middle of the box, so setting a sensible box is usually enough on its own.

seastamp warns when the input sits far enough from the center to matter:

[seastamp] warning: the farthest input point is 15127 km from the projection
center (0.0, 0.0), where planar distances are off by roughly 63%.
[seastamp] warning: pass --region, or --proj-lon0 / --proj-lat0, centered on your
data, or --partition to measure each area in its own projection.

A large region is not free either. A box spanning a whole ocean puts its own edges thousands of km from its center, so the warning can fire on a region that is genuinely as tight as the data allows.

When the data really is spread too wide for any one center, use --partition, and see auto or partition for which to pick when. It splits the run into sub-regions, each measured in its own projection, and keeps splitting until every point is within 2% of its own partition’s center, and widens any partition whose answer reached past the data it held. On a globally spread grid that cut coast’s mean error from 30.5% to 0.5%, and on two distant survey clusters from 8.6% to 0.2%. It also stopped place assigning the wrong country to 91 of 540 globally spread points. It is available on coast, sea, and place; depth and nearest have no projection to fix.

auto or partition compares the two side by side.

The antimeridian: distances now work, cropping still does not

A region box is a plain lon/lat rectangle compared without wrapping, so one crossing 180 degrees cannot be expressed. The projection has no such problem: a LAEA about a correct center is seamless.

--region auto separates the two. Points either side of the dateline get a correct center and a crop box that keeps every longitude, so distances are right and only cropping is loose. Measured on three points around Fiji:

Regiondist_to_coast
auto (default)7.31, 13.03, 50.84 km
global (the old default)1.23, 5.41, 8.23 km

The old default was wrong by up to a factor of six there. Nothing but the projection center changed.

An explicit crossing box is still rejected:

Error: region min-lon (170) is greater than max-lon (-170). A region crossing
the antimeridian is not supported; split the run into an eastern and a western
box, or use --region auto, which keeps the projection centered correctly and
only widens the crop

So are the four IHO sea names whose extent crosses the line: the Bering Sea, the Chukchi Sea, and the North and South Pacific Oceans. seastamp regions flags them with crosses_antimeridian true, so you know before the run.

Cropping is the part that still suffers, for a region you pin by hand: a (170, 180) region drops reference features lying just across the line, so a coastline a few km east of 180 is invisible to a run bounded at 180. auto avoids that by keeping every longitude when the data wraps, at the cost of a larger reference set to index.

--partition handles it even when the data does not wrap. A group of points sitting on one side of the line has a crop clamped there, and no amount of widening can reach the coast on the other side, so such a partition switches to every longitude and keeps only its latitude band. The same happens at a pole, where the way north comes back down the opposite meridian. That matters most in polar work, where the nearest land is often across the line or over the top: a point at (-179, 86) used to report 1595.58 km against a true 958.68 km. If a partition still cannot reach far enough, the run now says so rather than presenting an over-estimate as a measurement:

[seastamp] warning: 1 partition(s) still reached past their reference data after
widening to the 40 degree limit. Those distances are over-estimates: the nearest
feature may lie outside the data that was searched.

Municipalities are Europe only

place --municipalities uses Eurostat GISCO LAU, which covers the EU, EFTA, and candidate countries. The lookup is a nearest match, so a site outside that coverage is still assigned the nearest European municipality, thousands of km away, and nothing in the name says so. Two ways to handle it:

  • Leave --municipalities off entirely outside Europe. country still works, since Natural Earth is global.
  • Or keep it and pass --max-municipality-dist, which clears the name beyond a limit. The municipality_dist column shows how far each match reached, and is 0 for a point genuinely inside a municipality.

If no LAU polygon survives cropping, seastamp says so rather than filling the column with distant matches.

Accuracy ceiling

All geometry is spherical, so nothing here is ellipsoidal-accurate. Expect agreement with an ellipsoidal calculation at the level of a few parts in a thousand, which is far below the resolution of the shoreline and boundary data being measured against. Sub-meter work would mean replacing the spherical LAEA with an ellipsoidal one.

depth samples the nearest GEBCO cell with no interpolation, so its resolution is the grid’s, about 450 m at the equator for the 15 arc-second product.

Regions

The coast, sea, and place commands crop their reference data to a region box (plus a margin) and, for distance work, project through a Lambert Azimuthal Equal-Area (LAEA) projection centered on that region. The depth command needs no region (a grid lookup is global), and nearest computes exact great-circle distances on the unit sphere, so it needs no region either.

The region is not just a cropping filter: it sets where distances are measured from, so the wrong region silently returns wrong distances rather than an error. Coverage and limits gives the size of that error and how to pick a region, and is worth reading before running on data outside northern Europe.

auto, the default

With no --region at all, or with --region auto, seastamp derives the region from your own points once it has read them:

[seastamp] --region auto: box (-1.30, 9.90, 55.10, 65.90), projection centered on (4.23, 60.47)

The center is the mean direction of the points computed in three dimensions, not an average of their degrees. That matters in two places no rectangle can reach:

  • Around a pole. A ring of stations at 75N spanning every longitude averages to the pole itself, which is the correct center. The arctic preset’s box center is forced down to 75N, four times worse.
  • Across the antimeridian. The projection has no seam, so a survey either side of 180 is centered correctly. Only the crop box has a seam, and auto widens that to every longitude rather than distorting the center. Cropping gets looser; distances stay right.

The box is the points’ own extent padded by 5 degrees, on top of which each command adds its usual 5 degree margin. The reference data kept therefore reaches about 10 degrees, roughly 1100 km, beyond the outermost point, which is deliberately generous: an offshore point’s nearest coast can be hundreds of km away, and cropping to the points alone would cut the coastline out and overstate the distance.

Explicit bounds still win. --region auto --min-lon 0 derives everything except the western bound.

When auto cannot help

One projection cannot serve points spread over the whole globe, and auto says so rather than returning a plausible wrong number:

[seastamp] warning: the points are spread over too much of the globe for any one
projection to serve them (clustering 0.10 of a possible 1.00).
[seastamp] warning: --region auto cannot help here. Pass --partition to measure
each area in its own projection.

The clustering figure is the length of the mean direction vector: 1.00 when every point sits in one place, near 0 when they are spread evenly over the globe. A polar ring scores 0.97 despite spanning every longitude, because those points really do share a direction.

–partition, for data one projection cannot serve

--partition is the answer to that warning. It splits the input into sub-regions, gives each its own crop box and its own projection center, and joins the results back together, so a globally spread table comes out as accurate as running each area separately would have been.

Deciding between the two? auto or partition compares them side by side on measured datasets and says which to use for what.

seastamp coast global-stations.parquet --data ./data/gshhg/... --partition
[seastamp] --partition: 33 partitions over 144 unique locations, worst distortion 1.99%
[seastamp] 144 rows, 144 unique locations -> global-stations.coast.parquet

The split is driven by accuracy, not by a cell size or a count. There is no number to choose. seastamp keeps halving a group while any of its points would be more than 2% out, and stops as soon as none are, so the partition count is whatever the data needs. That last figure bounds the projection error: no distance is scaled by more than that much by the map projection it was measured in. Cropping is a separate error, handled separately: a partition whose answer reached past the data it held is rebuilt with a wider crop and re-run. See auto or partition.

Data that already fits one projection is left as one piece and comes out identical to an ordinary --region auto run, so the flag is safe to leave on:

[seastamp] --partition: 1 partition over 10 unique locations, worst distortion 0.98%

What it is worth, in one line

Where the points fall into a few distant clusters, --partition wins outright: one measured pair of survey areas went from 8.60% mean error to 0.15%. On a grid spread evenly over the globe it went from 30.54% to 0.54%. Below about 5000 km of span it produces a single partition and is identical to auto. auto or partition has the full measurements.

Limits

  • coast, sea, and place take it. depth reads a grid and nearest works on the sphere, so neither has a projection to improve and neither takes the flag at all.
  • It takes no region or bounds of its own. --partition derives every box and center from your points, so combining it with --region, --min-lon and friends, or --proj-lon0 is an error rather than a precedence question.
  • Results are no longer perfectly smooth across a partition boundary. Two nearby points measured in different projections can disagree slightly, bounded by twice the reported distortion. It shows up only if you difference neighboring values; each value on its own is more accurate than it would have been without the flag.

Presets

Pick a region with --region <NAME>:

PresetBox (min_lon, max_lon, min_lat, max_lat)
global-180, 180, -90, 90
baltic8, 31, 53, 66
norway-10, 45, 55, 85
arctic-180, 180, 60, 90
atlantic-83, 20, -60, 70
europe-25, 45, 34, 72
mediterranean-6, 37, 30, 46

global is no longer the default; auto is. Pass --region global to get the old whole-globe behavior back.

IHO sea names

--region also takes any of the 101 IHO Sea Areas v3 names, baked into the binary so no data file is needed:

seastamp coast cores.parquet --data ./data/gshhg/... --region "Barentsz Sea"

seastamp regions lists presets and IHO names together, with a source column saying which is which. Two things to know:

  • An IHO area is not the colloquial sea. S-23 splits the Gulfs of Bothnia, Finland, and Riga out of the Baltic, so --region "Baltic Sea" crops far more tightly than the baltic preset. Check the neighboring names first.
  • Four areas cannot be used by name: the Bering Sea, the Chukchi Sea, and the North and South Pacific Oceans all cross the antimeridian, so their box cannot be expressed. seastamp refuses them and points at --region auto.

An unknown name is an error, not a silent fall back to the whole globe, and it suggests the near misses:

Error: unknown region 'Barent Sea'. Did you mean: Barentsz Sea?

With completions installed, Tab offers these names directly, which saves looking them up. In bash and zsh a name containing a space completes only to its first word, so --region Bar<TAB> stops at Barentsz; running that reports the full name back at you, as above.

Explicit box and projection center

Any preset value can be overridden with explicit bounds:

seastamp coast cores.parquet --data ./data/gshhg/... \
  --min-lon 8 --max-lon 31 --min-lat 53 --max-lat 66

Where the LAEA projection is centered depends on how the region was chosen. A named region centers on its box center. Under auto the center comes from the points themselves, which is better whenever the data sits off to one side of its box. Either way, --proj-lon0 / --proj-lat0 override it.

Note that giving bounds without a --region name leaves you in auto mode, so the box is yours and the center is still derived from the data. Pass --region global (or any name) if you want the old box-center behavior.

Precedence

For the region box and projection center, later sources win:

auto / preset / built-in default  <  config file  <  CLI flag

So a --region name sets the box, a config file can override individual bounds, and a CLI --min-lon (etc.) overrides both. Auto sits at the bottom: it fills in whatever nothing else specified.

Choosing a region

Cropping keeps the reference data small and the lookups fast, but a point whose true nearest feature lies outside the region-plus-margin box can be wrong (for coast, an over-estimate). auto pads generously for exactly this reason. If you are pinning a region by hand and in doubt, widen the box; the unique-location pipeline keeps even a global run affordable.

auto or partition

coast, sea, and place measure in a flat map projection, and a projection is only accurate near the point it is centered on. There are two ways to handle that:

  • --region auto (the default) picks one projection centered on all your points.
  • --partition splits the points into groups and gives each group its own.

This page is about choosing between them, and about how accurate the result actually is in each case.

The short answer

Your dataUseWhy
Spans less than about 5000 kmauto--partition produces a single partition, so the two give the same answer to within centimetres.
Falls into a few distant clusters, however far apart--partitionThis is the case it wins outright. Measured below: 8.6% mean error becomes 0.15%.
Is spread continuously across an ocean or the globe--partitionIt cuts the average error from tens of percent to well under one.

If you are not sure, run the default and read what seastamp prints. If it does not warn, auto was fine and --partition would have changed nothing.

[seastamp] warning: the farthest input point is 15127 km from the projection
center (0.0, 0.0), where planar distances are off by roughly 63%.

What the numbers actually are

Six point sets, each run both ways against GSHHG f. Every point is compared against a reference run of that point alone, with the whole globe indexed and the projection centered on itself, so the reference carries neither projection distortion nor cropping loss. These are full populations, not samples.

DatasetSpanPartitionsauto meanauto worst--partition mean--partition worst
North Sea survey322 km1--identical to autowithin 1 mm
Norwegian shelf1 314 km1--identical to autowithin 2 cm
Nordic seas3 055 km1--identical to autowithin 2 cm
North Atlantic4 806 km1--identical to autowithin 22 cm
Two clusters, Atlantic and Pacific14 298 km28.60%16.91%0.15%0.45%
Global grid19 999 km3430.54%974.72%0.54%2.23%

Three things to take from this.

Below about 5000 km the two are the same thing. The partitioner found nothing worth splitting and built one partition covering everything, which is what auto already does. The tiny differences are floating-point noise, not method. Passing --partition to regional data costs nothing and changes nothing.

Clustered data is where partitioning wins outright. Two survey areas on opposite sides of the world went from 8.60% mean error to 0.15%, with no point worse than 0.45%. Nothing was lost and everything improved.

A single projection degrades further than most people expect. On the global grid auto’s mean error was 30.54%, and its worst point came out nearly ten times its true distance. That is not a rounding problem, it is a different number. Partitioning brought the same grid to 0.54% mean and 2.23% worst.

Two errors, and how each is handled

A partitioned run has two independent ways of being wrong, and it is worth knowing which is which.

Projection error, bounded by splitting

A flat projection scales distances more and more the further you go from its center. seastamp splits until every point is within 2% of its own partition’s center, so this error is bounded by construction, and every run reports what it achieved:

[seastamp] --partition: 33 partitions over 144 unique locations, worst distortion 1.99%

Cropping error, bounded by widening

Every region only indexes reference data inside its own box plus a margin. A point whose true nearest coastline lies beyond that would get the nearest one that is inside, which is always an over-estimate.

Partitions crop tightly, which is what makes them cheap, and tight crops suit points near a coast but not points in open water, whose nearest shoreline can be two thousand km away. So seastamp checks: if a partition’s answer reached further than the data that partition was given, the answer is not final. Those partitions are rebuilt with a crop widened by exactly as much as their own answers asked for, and re-run.

[seastamp] --partition: 31 partition rebuild(s) with a wider crop, where an
answer reached past the data the first crop held.

Only the partitions that need it pay for it. A run whose crops were already sufficient reports no rebuilds and costs nothing extra, and clustered data typically needs one or none.

The reported “worst distortion” describes the projection only. It is not a bound on the total error of the output, and the widening pass above is what handles the other half.

The limit of it

Widening stops at 40 degrees, about 4400 km of reference data around a partition, which is further than any real nearest-coast distance. Going all the way to a global crop for each partition would cost a full-world index apiece and undo the memory saving partitioning exists for.

A point can still come back null if its reference dataset genuinely holds nothing in range. The usual cause is not the crop but the data: GSHHG’s L1 shoreline stops at 69S and holds no Antarctic coastline (Antarctica is in L5 and L6, which coast does not read), so points deep in the Southern Ocean have no nearby L1 land to find. seastamp says so rather than leaving you to notice:

[seastamp] warning: 2 location(s) had no reference feature within reach even
after widening the crop, so their columns are null. A dataset that does not
cover the area is the usual cause: GSHHG's L1 shoreline, for one, stops at 69S
and holds no Antarctic coast.

What it costs

Each partition crops its own copy of the reference data, so partitioning usually does more work. On the global grid above:

RunTimePeak memory
auto7.1 s0.97 GB
--partition28.7 s1.43 GB

Roughly half of that is the widening pass rebuilding the 31 partitions whose first crop turned out too tight.

But clustered data is cheaper partitioned, not dearer. Tight boxes index far less than one box stretched across the gap between the clusters:

Two clusters, Atlantic and PacificTimePeak memory
auto1.8 s262 MB
--partition1.8 s90 MB

One box spanning both oceans has to hold the Americas in between, which no point in the input is anywhere near.

When the partitions will not fit in memory together, seastamp reads the reference file again rather than growing, and says how often it had to:

[seastamp] --partition: reference data read 7 times.

Which commands it affects

CommandDoes --partition help?
coastYes, most. dist_to_coast is planar throughout.
placeYes, and categorically. A distorted projection does not return a slightly wrong distance, it names the wrong place. On 540 globally spread points the two runs named a different nearest country for 91 of them, and every spot check went to --partition.
seaBarely. Which sea a point is in is decided by an exact lon/lat containment test that no projection touches. Only the fallback for points inside no polygon changes.
depthNo. It reads a global grid by arithmetic and takes no region at all.
nearestNo. It works in exact great-circle distance on the sphere and takes no region at all.

depth and nearest reject the flag rather than accepting and ignoring it.

What does not change

  • Reproducibility. Partitioning is deterministic: the same table always gives the same partitions, and two runs give byte-identical output. There is no random seed and no iteration count.
  • Output shape. The same columns and rows in the same order. Rows with no usable coordinate stay null in place.
  • Everything auto is good at. Partitions derive their centers the same way, so stations ringing a pole still center on the pole, and points either side of the antimeridian still center near 180.

Constraints

--partition derives every box and center from your points, so it cannot be combined with --region, with --min-lon and friends, or with --proj-lon0 / --proj-lat0. seastamp rejects the combination rather than silently picking one:

error: the argument '--partition' cannot be used with '--region <REGION>'

For a pinned, reproducible region instead of a derived one, use the presets and IHO sea names.

Output columns

Each stamping command appends its columns to a copy of the input and writes the result; the input columns are preserved and their order is kept. (regions is not one of these: it has no input table and emits its own, documented on its own page.)

CommandAppended columnsType
coastdist_to_coastfloat (km or m)
depthbathymetry, plus on_land with --on-landfloat (m), bool
seasea_nametext
placecountry, country_code, municipality, plus municipality_dist when --municipalities is giventext, text, text, float (km or m)
nearestnearest_name, nearest_disttext, float (km or m)

The single-column commands rename their output with --column; nearest renames with --name-column / --dist-column.

Null values

A row gets null (or NaN for float columns) output when:

  • its longitude or latitude is null or NaN, or
  • the lookup finds nothing (for example a depth point off the GEBCO grid, or a nearest run against an empty reference set), or
  • place discards a municipality match for exceeding --max-municipality-dist, which clears municipality and municipality_dist together.

depth is deliberately not one of these cases for a point on land: GEBCO gives a real elevation there, positive above sea level, and it is reported rather than nulled. --on-land flags such points in a boolean column, which is null itself where there is no reading at all.

Clashing columns

If an output column name already exists in the input, the run fails before any stamping, naming the clashing column(s). Pass --overwrite to replace such a column in place instead: it keeps its position but takes the output value and dtype.

Output format

By default the output file is written beside the input as <stem>.<command>.<input format>, so the output format follows the input’s (a points.csv.gz input stamps to points.coast.csv.gz). Override the path with --output or the format with --out-format. An input with an unrecognized extension defaults to Parquet.

Configuration

Shared options

Every command accepts the same input, output, and pipeline options:

OptionDefaultMeaning
-o, --output <FILE><stem>.<command>.<input format>Output file (beside the input)
--in-format <FMT>inferred, else parquetparquet, csv, tsv, csv.gz, tsv.gz, auto
--out-format <FMT>inferred, else parquetsame set
--overwriteoffReplace clashing output columns instead of failing
--lon-col <NAME>longitudeLongitude column
--lat-col <NAME>latitudeLatitude column
--decimals <N>3Rounding applied before de-duplicating
-t, --threads <N>all coresWorker threads. depth always looks up its grid on one thread, see depth
-c, --config <TOML>noneConfig file (CLI flags override it)

The coast, sea, and place commands also take the region options.

Formats

Input and output can be Parquet (default), CSV, TSV, and the gzip variants csv.gz and tsv.gz. The format is inferred from the file extension; an unrecognized extension falls back to Parquet. Gzip is handled directly (not via a Polars feature), so it behaves the same across Polars versions.

Config file

A TOML config file supplies the region box and projection center, sitting between the built-in default and the CLI flags (see precedence). Every field is optional:

# region.toml
region    = "baltic"   # a named preset
min_lon   = 8.0        # or explicit bounds, overriding the preset
max_lon   = 31.0
min_lat   = 53.0
max_lat   = 66.0
proj_lon0 = 19.5       # LAEA projection center (default: region center)
proj_lat0 = 59.5
seastamp coast cores.parquet --data ./data/gshhg/... -c region.toml

Rounding and de-duplication

Coordinates are rounded to --decimals places (3 by default) before the input is reduced to unique locations. Only the unique locations are looked up, then the results are joined back onto every row. Raising --decimals distinguishes closer points at the cost of more unique lookups; lowering it collapses more rows together.

Technical notes

The shared pipeline

Every command implements one small trait (declare the output columns, compute their values for one location) and shares the rest: extract longitude and latitude (cast to float, nulls to NaN), round and de-duplicate into unique locations with integer-scaled keys (so the join never compares floats), stamp the unique set in parallel with rayon, expand the results back to one value per input row, append the columns, and write. A NaN coordinate gets no key and therefore null output.

Geometry: no PROJ, no GDAL

All geometry is hand-rolled in pure Rust, so downstream projects need no extra system libraries. Two projections do the work:

  • A spherical LAEA (Lambert Azimuthal Equal-Area) centered on the region, used for planar distances by coast (and for the nearest-boundary fallbacks in sea and place). Planar distance in that projection is accurate for the regional-scale nearest-feature query. A single sphere (authalic radius) is used rather than the GRS80 ellipsoid; the error is well under coastline resolution for regional work. Sub-meter accuracy, if ever needed, means an ellipsoidal LAEA.
  • The unit sphere, used by nearest. Reference points become (x, y, z) vectors on the unit sphere; nearest-by-chord equals nearest-by-great-circle, and the squared chord converts back to an exact great-circle distance in meters. This is why nearest needs no projection center and has none of a planar projection’s distortion far from a center.

The haversine_m great-circle distance is used for reference and to refine index candidates.

How distances are calculated

Three commands report a distance, and they do not all compute it the same way. Which method a command uses decides how far from the projection center its numbers stay trustworthy.

ColumnCommandMethodAccurate
dist_to_coastcoastPlanar, in the region LAEARegionally, near the projection center
municipality_distplacePlanar, in the region LAEARegionally, near the projection center
nearest_distnearestGreat circle, on the unit sphereEverywhere on the globe

All three compute in meters and divide by 1000 for the km default; --unit m reports meters unchanged.

Planar, in the region LAEA

coast and place project the query point and the reference geometry into the region’s LAEA plane and take an ordinary Euclidean distance there:

  1. Project the point to (x, y) meters with the spherical LAEA centered on --proj-lon0 / --proj-lat0 (a --region preset sets these).
  2. Ask the R-tree of projected segments for the nearest one.
  3. Take the point-to-segment distance, which is a straight line in that plane.

For coast the segments are the shoreline; for place they are municipality boundaries, and the distance is 0 when the point falls inside the polygon rather than beside it.

Because the projection is centered on the region, the distortion is small near that center and grows with distance from it. Planar distance tracks the true great-circle distance to well under 1% for points a few tens of km apart in the middle of a region, which is the case these commands are built for. Set the region to match your data, since points far outside it get progressively worse numbers rather than an error.

The projection is spherical, using the authalic radius 6371007.181 m, and the formulas are the spherical LAEA case from Snyder, Map Projections: A Working Manual (USGS Professional Paper 1395).

Great circle, on the unit sphere

nearest deliberately does not use the projection, because the two tables it compares can be anywhere and need not share a region. Instead:

  1. Map every reference point to an (x, y, z) vector on the unit sphere, and index those in a 3D R-tree.
  2. Ask for the nearest by Euclidean chord distance. The chord grows monotonically with the central angle, so the nearest by chord is exactly the nearest by great-circle distance.
  3. Convert the squared chord back to meters with d = 2R asin(chord / 2), using the mean radius 6371008.8 m.

The result is exact anywhere on the globe, so nearest takes no region or projection center at all. It agrees with haversine_m to within 1e-9 relative even across a third of the Earth.

Limits

What this means in practice, and how to pick a region, is in Coverage and limits.

Every distance here is spherical, so none of it is ellipsoidal-accurate. Expect agreement with an ellipsoidal calculation at the level of a few parts in a thousand, which is far below the resolution of the shoreline and boundary data being measured against. Sub-meter work means replacing the spherical LAEA with an ellipsoidal one.

Spatial indexes

Nearest-feature and point-in-polygon queries use rstar R-trees:

  • coast indexes projected shoreline segments; a query takes the nearest segment’s planar distance.
  • sea and place index feature bounding boxes for the containment test and boundary segments for the nearest fallback.
  • nearest indexes reference points in 3D on the unit sphere.

Cropping keeps whole features: a feature is dropped if its bounding box misses the region-plus-margin box, but it is never clipped, so containment stays exact and cropping cannot invent geometry.

Memory and streaming

The input is read whole into memory because the join back touches every row; the set stamped is only the unique locations, which stays small. For very large inputs a streamed two-pass version (collect unique locations, then append columns chunk by chunk) is the natural next step, noted in the source.

Threading and HDF5

Stamping normally spreads the unique locations across rayon workers. depth is the exception and runs them on one thread, because it reads through HDF5, which is frequently built serial. A serial build is not merely unsafe for overlapping calls: it cannot be entered from several threads at all, even under a lock that makes the calls strictly sequential. Spreading the reads across workers therefore crashed, as a segfault in release builds and an error-stack assertion in debug ones. A Stamper declares this with parallel() -> false.

This only bites where HDF5 lacks thread safety, which is why it showed up in the prebuilt release binaries (they vendor the C libraries through static-netcdf, which leaves thread safety off) and not against a distribution libhdf5-dev built thread-safe. To exercise that configuration:

cargo test --features static-netcdf --test depth

For the same reason all the depth cases live in a single #[test]: the harness runs each test on its own thread, which is enough to trip a serial HDF5.

Parquet writes

Parquet is written single-threaded (set_parallel(false)), matching ctddump: the parallel column encoder in the pinned Polars version leaks memory per call, and the single-thread path is safe and deterministic.

Reference datasets

The datasets each command stamps from are large and are not bundled or shipped. Each command takes its data path by flag (--data, or --countries / --municipalities for place). The nearest command is the exception: its reference data is a table you supply with --to, not a downloaded dataset.

Download helper

scripts/download_data.sh fetches and unpacks any of the five sources into ./data/, one sub-directory per source, matching the example paths in the command pages:

# 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-org "Your Institute" --mr-email you@example.org \
  --mr-country Norway download iho

Selected datasets download in parallel. Existing archives are kept (--force re-downloads), and the multi-GB GEBCO grid resumes an interrupted download. Run scripts/download_data.sh --help for all options.

Caveats baked into the script:

  • The GEBCO grid is multi-GB; the download resumes if interrupted.

  • The GISCO LAU bundle nests one zip per projection; only the EPSG 4326 (lon/lat) layer is unpacked, since the commands expect lon/lat.

  • The Marine Regions (IHO) download submits the site’s statistics form on your behalf, so every field the form marks required has to be supplied: --mr-name, --mr-org, --mr-email, and --mr-country, plus --mr-category and --mr-purpose, which default to academia and Research. Those two are dropdowns on the form and accept only fixed values, so the script checks them before downloading anything and lists the valid ones if you miss:

    OptionAccepted values
    --mr-categoryacademia, industry, government, civil society
    --mr-purposeConservation, Data exploration & testing, Education & workshops, Fisheries, Policy & Marine Spatial Planning, Mapping & visualisation, Maritime transport & cruise planning, Industry & offshore activities, Research, GIS Analysis, Personal information, Other

    Anything missing or invalid is prompted for at the terminal, with the two dropdowns offered as numbered menus, so you can also just run scripts/download_data.sh download iho and answer the questions. Prompting needs a terminal to ask at, so under -y/--yes or in a non-interactive shell (CI, a pipeline) a missing field stays a hard error rather than hanging.

    --mr-country is free text but has to match the form’s spelling of the country in English. Because these details go to a third party and the download accepts the dataset licence (CC BY-NC-SA 4.0, non-commercial and share-alike), the script prints exactly what it will submit and waits for confirmation before starting. It also verifies the response is a zip and fails loudly if the form rejects the request.

Sources

DatasetUsed bySource
GSHHG shorelines (ESRI shapefiles, resolution f)coasthttps://www.soest.hawaii.edu/pwessel/gshhg/
GEBCO bathymetry (gridded NetCDF)depthhttps://www.gebco.net/
IHO Sea Areas v3 (GeoJSON or shapefile)seahttps://www.marineregions.org/
Natural Earth countriesplacehttps://www.naturalearthdata.com/
Eurostat GISCO LAU (municipalities)placehttps://ec.europa.eu/eurostat/web/gisco

Helper scripts

The scripts/ directory holds bash helpers that sit alongside the CLI: one to fetch the reference datasets, one to run several modules over an input in a single pass, one to do that for every product of a ctddump pipeline at once and report on each, and two that turn those reports into summary pages and a static web site. None is required to use seastamp, but together they cover the “get the data, stamp, then report” workflow end to end.

All follow the same conventions:

  • The header comment doubles as --help, so scripts/<name> --help prints the full interface.
  • Steps are traced to stderr as they run (a timestamped RUN: line per command), so a long run shows what it is doing.
  • They run under set -euo pipefail and stop at the first error.

download_data.sh

Downloads and unpacks the reference datasets into a local data/ tree, one sub-directory per source, matching the paths the command pages use. Selected datasets download in parallel, existing archives are kept unless --force is given, and the multi-GB GEBCO grid resumes an interrupted download.

scripts/download_data.sh download gshhg gebco countries lau

See Reference datasets for the full list of sources, the Marine Regions (IHO) form details, and the caveats.

stamp.sh

Runs several modules over one input in sequence and writes a single output file carrying every selected module’s new columns. A module runs when you give its data source, each step chains onto the previous one’s output, and the intermediate files are removed when the script ends.

scripts/stamp.sh cores.parquet cores.stamped.parquet \
  --coast ./data/gshhg/gshhg-shp-2.3.7/GSHHS_shp/f \
  --depth ./data/gebco/GEBCO_2024_sub_ice_topo.nc \
  --nearest farms.parquet --nearest-name-field farm_name

See Stamp with several modules for the module flags, the per-module and common options, and how the intermediate files are handled.

stamp_data.sh

Runs stamp.sh over every data product that ctddump’s pipeline produces for the Arctic, Baltic, and Mediterranean seas, one worker per product, all in parallel, then summarises each stamped file with report stats. The inputs are the de-duplicated files dedup_data.sh writes, one per stem (nrt_ar_ar, nrt_ar_gl, cora_ar, and the same for bo and mo). Each <in>/<stem>.parquet is stamped to <out>/<stem>.parquet, and its report is written to <report>/stamp/<stem>.tsv (-r, --report, default report).

scripts/stamp_data.sh -i ../ctddump/output/dedup/dedup -o output/stamp \
  --coast ./data/gshhg/gshhg-shp-2.3.7/GSHHS_shp/f --partition \
  --depth ./data/gebco/GEBCO_2024_sub_ice_topo.nc
  • A leading command picks the steps, as in ctddump’s scripts: stamp, report, or all (the default, stamp then report). report alone re-reads outputs that already exist, so it needs no module flags.
  • The module flags and their options are the ones stamp.sh takes, forwarded unchanged. They are checked once, before any worker starts, so a bad combination fails the run up front rather than once per product.
  • Name regions (arctic, baltic, mediterranean) to stamp only those; the default is all three.
  • A product whose input is missing is skipped with a note, so a product that is not published yet (the Baltic GL) does not fail the run.
  • -t, --threads sets the threads of each seastamp call (default 2), so the total is that times the number of products running at once.
  • Each worker is a separate seastamp process with its own copy of the reference data, so memory use grows with the number of workers. --by-region runs one worker per region and --sequential one product at a time. Stamping depth for several products at once is safe: the one-thread limit on the grid lookup applies within a process, not across processes.
  • The report reads the units and the depth sign from the same flags the stamp step takes (--coast-unit, --place-unit, --nearest-unit, --depth-positive), so a report run on its own needs them repeated. --dist-bands and --depth-bands set the report’s band edges.
  • -f, --format picks the output format (parquet, csv, tsv, csv.gz, tsv.gz), -n, --dry-run prints the commands, and -y, --yes skips the confirmation prompt.

Run scripts/stamp_data.sh --help for the full interface.

summary_data.sh

Builds one report summary page per product from the reports stamp_data.sh wrote: <report>/stamp/<stem>.tsv to summary/<stem>.md (-d, --dest), Markdown by default and HTML with -f html. A product with no report is skipped.

scripts/summary_data.sh -y                  # every region
scripts/summary_data.sh -y -f html baltic   # HTML pages, Baltic only

Each page gets a title and notes per product, defined in the script’s “Page text” section, which is the place to edit what a page says about a product. The titles match ctddump’s summary pages for the same products. --top sets how many names a sea-area or country table lists before summing the rest.

summary_site.sh

Renders the Markdown pages into a static web site with mdBook, the same way ctddump’s script of the same name does: one part per region, a chapter per product, read from summary/ (-s, --src) and written to site/ (-d, --dest). Open site/index.html in a browser, or publish the directory as is: it carries a .nojekyll, a LICENSE, a CITATION.cff, and a README.md, so it can be pushed straight to a GitHub Pages repository.

scripts/summary_site.sh -y                          # site/ from summary/
scripts/summary_site.sh -y -t "Arctic stamping" arctic
scripts/summary_site.sh -y --citation my-CITATION.cff   # your own site's citation

-t, --title sets the book title, and -c, --config swaps in your own book.toml. Each chapter is named after its page’s title, so titles live in summary_data.sh alone.

OptionDefaultDescription
-l, --license FILEthe LICENSE one level above the scriptLICENSE copied into the built site. Pass --license "" to skip it.
--citation FILEthe site-CITATION.cff beside the scriptCITATION.cff copied into the built site. If it has a top-level doi:, the site README also gets a DOI badge and a Citation section. Pass --citation "" to skip it.

mdBook empties the site directory before every build, so anything added to it by hand, such as a CITATION.cff or an edited README, is gone after the next run. The site’s citation therefore lives in this repository, as scripts/site-CITATION.cff, and every build copies it in as CITATION.cff and regenerates the README’s DOI badge from its doi:. It describes the published example site (seastamp-report-example, and once it is archived on Zenodo, that site’s DOI), and lists seastamp, its reference datasets, ctddump, and the Copernicus Marine products as references, so edit it there when the site’s metadata changes. If you publish a site of your own, pass your own file with --citation FILE, or --citation "" to leave it out. If the default file is missing (for example, only the script was copied), it is skipped without a message; a missing --citation path is an error.

The whole chain, after ctddump has run:

scripts/stamp_data.sh -y -i ../ctddump/output/dedup/dedup \
  --coast ./data/gshhg/gshhg-shp-2.3.7/GSHHS_shp/f --partition \
  --depth ./data/gebco/GEBCO_2024_sub_ice_topo.nc
scripts/summary_data.sh -y
scripts/summary_site.sh -y

The old name enrich.sh

stamp.sh was called enrich.sh up to 0.15.0. That name still works: it is a wrapper that forwards every argument to stamp.sh and prints a notice to stderr. It will be removed in a later release, so move to stamp.sh when convenient.

Requirements

download_data.sh needs curl and unzip on PATH. stamp.sh, stamp_data.sh, and summary_data.sh need a built seastamp binary: they use $SEASTAMP_BIN if set, else the one on PATH, else a ./target/release or ./target/debug build in the repository (pass --bin to point elsewhere). stamp_data.sh calls the stamp.sh next to it, so keep the two in the same directory. summary_site.sh needs mdbook on PATH (cargo install mdbook).

Stamp with several modules

scripts/stamp.sh runs several modules over one input in sequence, so the result is a single file carrying the new columns of every module you selected. Each module is chained onto the previous one’s output, its columns accumulating, and the in-between files are written to a temporary directory that is removed when the script ends. Only the final output file remains.

scripts/stamp.sh [options] <input> <output>

Selecting modules

A module runs only when you give its data source, so the flags pick both the modules and their inputs. At least one module must be selected.

FlagModuleData source
--coast PATHcoastGSHHG shapefile dir or GSHHS_*_L1.shp
--depth FILEdepthGEBCO bathymetry NetCDF
--sea PATHseaIHO Sea Areas GeoJSON or shapefile
--countries FILEplaceNatural Earth countries shapefile
--nearest FILEnearestreference table of named locations

The modules run in a fixed order (coast, depth, sea, place, nearest); the order does not matter, since each adds distinct columns.

Per-module options

OptionApplies toMeaning
--municipalities FILEplaceGISCO LAU municipalities (optional)
--coast-unit km|mcoastDistance unit (default km)
--depth-positivedepthReport depth positive below sea level
--depth-on-landdepthAdd an on_land boolean column
--max-municipality-dist NplaceDrop a municipality match further than N away
--place-unit km|mplaceUnit for municipality_dist and its cutoff (default km)
--sea-name-field STRseaFeature field with the sea name (default NAME)
--nearest-name-field STRnearestReference name column (default name)
--nearest-unit km|mnearestDistance unit (default km)

Common and other options

--region, --partition, --lon-col, --lat-col, --decimals, and --threads are passed to every module that accepts them (--region and --partition only to coast, sea, and place). --threads reaches depth too, but not its grid lookup, which always runs on one thread. --in-format describes the original input. Other options:

OptionMeaning
--bin PATHseastamp binary (default: $SEASTAMP_BIN, else the one on PATH, else ./target/release or ./target/debug)
-k, --keepKeep the intermediate files (default: remove them)
-n, --dry-runPrint the commands without running them

--partition and --region are exclusive, here as in seastamp itself: a partitioned run derives a box and a projection center for each piece of the input, so there is no single region to set. Passing both is an error before any module runs.

Each step chains onto the previous one’s output, which carries the same points, so every partitioned module in a chain splits the input the same way and reports the same partition count. See auto or partition for when the flag is worth using.

Example

scripts/stamp.sh cores.parquet cores.stamped.parquet \
  --coast ./data/gshhg/gshhg-shp-2.3.7/GSHHS_shp/f \
  --depth ./data/gebco/GEBCO_2024_sub_ice_topo.nc \
  --nearest farms.parquet --nearest-name-field farm_name

This writes one file, cores.stamped.parquet, with the original columns plus dist_to_coast, bathymetry, nearest_name, and nearest_dist. The intermediate coast-only and coast+depth files are removed on exit.

The intermediate files are Parquet (lossless); the final file’s format follows its extension, so cores.stamped.csv.gz would be written as gzipped CSV.