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
| Command | Purpose |
|---|---|
coast | Distance to the nearest shoreline (GSHHG). |
depth | Bathymetric depth at the point (GEBCO grid). |
sea | Sea or ocean name at the point (IHO Sea Areas). |
place | Nearest country and municipality (Natural Earth + GISCO). |
nearest | Nearest location in a second table you supply, with its distance. |
regions | List sea and ocean bounding boxes, to find a region for the commands above. |
completions | Print a shell completion script, so Tab fills in commands, flags, and region names. |
report | Summarise 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:
| Option | Default | Meaning |
|---|---|---|
--data <PATH> | required | GSHHG shapefile directory (resolution f recommended) or a GSHHS_*_L1.shp file |
--unit <km|m> | km | Distance unit for the output column |
--column <NAME> | dist_to_coast | Output 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:
| Option | Default | Meaning |
|---|---|---|
--data <FILE> | required | GEBCO bathymetry NetCDF file |
--positive | off | Report depth as positive below sea level |
--column <NAME> | bathymetry | Output 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:
| Option | Default | Meaning |
|---|---|---|
--data <PATH> | required | IHO Sea Areas polygons (GeoJSON or shapefile) |
--name-field <NAME> | NAME | Property / attribute field holding the sea name |
--column <NAME> | sea_name | Output 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:
| Column | Meaning |
|---|---|
country | Country name |
country_code | ISO alpha-3 code (the Natural Earth -99 placeholder becomes null) |
municipality | Municipality name (empty unless --municipalities is given) |
municipality_dist | Distance 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:
| Option | Default | Meaning |
|---|---|---|
--countries <PATH> | required | Natural Earth countries shapefile |
--municipalities <PATH> | none | GISCO LAU municipalities shapefile |
--max-municipality-dist <N> | none | Discard a municipality match further than this, in --unit |
--unit km|m | km | Unit 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:
| Column | Meaning |
|---|---|
nearest_name | Name of the nearest reference location (rename with --name-column) |
nearest_dist | Distance 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:
| Option | Default | Meaning |
|---|---|---|
--to <FILE> | required | Reference table: the second set of locations |
--to-format <FMT> | inferred | Format of the reference table |
--to-lon-col <NAME> | longitude | Longitude column in the reference table |
--to-lat-col <NAME> | latitude | Latitude column in the reference table |
--name-field <NAME> | name | Column in the reference table holding each location’s name |
--unit <km|m> | km | Distance unit for the output distance column |
--name-column <NAME> | nearest_name | Output column for the nearest name |
--dist-column <NAME> | nearest_dist | Output 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
| Option | Default | Meaning |
|---|---|---|
--data <PATH> | none | IHO Sea Areas polygons (GeoJSON or shapefile). Omit to list the built-in names |
--name-field <NAME> | NAME | Property or attribute holding the area name |
--name <TEXT> | none | Keep only areas whose name contains this text (case-insensitive) |
-o, --output <FILE> | none | Also write the list to a file |
--out-format <FMT> | inferred, else parquet | parquet, csv, tsv, csv.gz, tsv.gz |
-q, --quiet | off | Do not print the table, only write it |
Output columns
| Column | Meaning |
|---|---|
name | The area name, one row per name |
min_lon, max_lon | Longitude bounds in degrees |
min_lat, max_lat | Latitude bounds in degrees |
crosses_antimeridian | True when the box runs east past 180 and continues from -180 |
source | preset, 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.pyfor 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
| Option | Default | Meaning |
|---|---|---|
<SHELL> | required | bash, zsh, fish, elvish, or powershell |
See also
- Installation for getting the binary in the first place
- regions for the names
--regioncompletes 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:
| Column | Written by | Reported as |
|---|---|---|
dist_to_coast | coast | distance |
bathymetry | depth | depth |
on_land | depth --on-land | flag |
sea_name | sea | text |
country, municipality | place | text |
municipality_dist | place --municipalities | distance |
nearest_name | nearest | text |
nearest_dist | nearest | distance |
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:
| Column | Meaning |
|---|---|
column | the stamped column, or (all) for the file totals |
kind | total, distance, depth, text, or flag |
item | what the row counts (below) |
unit | km or m for distances, m for depth |
rows, locations | the two counts |
min, max, mean | over locations, on the (value) row only |
The items for each kind:
| Kind | Items |
|---|---|
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 |
text | one per value, most locations first, then (null) |
flag | true, 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,100sets 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,1000sets 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:
| Flag | Default | When to pass it |
|---|---|---|
--coast-unit km|m | km | coast --unit m |
--place-unit km|m | km | place --unit m |
--nearest-unit km|m | km | nearest --unit m |
--depth-positive | off | depth --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 becomenull).--by COL: one block of rows per distinct value ofCOL(for exampleplatform_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:
| Section | Tables |
|---|---|
| Distance to coast | statistics, distance bands |
| Depth | statistics, depth bands with land first, the land flag when present |
| Sea area | locations and rows per sea area |
| Place | per country, per municipality, distance to municipality |
| Nearest location | per 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 defaultSummary: <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
| Command | Outside Europe | Why |
|---|---|---|
depth | Works anywhere | GEBCO is a global grid read by arithmetic, with no projection involved. |
nearest | Works anywhere | Great-circle distance on the unit sphere, exact globally, and it takes no region or projection center. |
sea | Works anywhere | IHO 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, country | Works anywhere | Natural Earth is global, containment first. |
place, municipality | Europe only | GISCO LAU has no coverage elsewhere. |
coast | Works anywhere | The 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:
| Region | dist_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 location | Distance from (0, 0) | Error |
|---|---|---|
| Canary Islands | 3 550 km | -1.7% |
| North Sea | 6 233 km | -11.6% |
| Baltic | 6 767 km | -9.1% |
| Gulf of Maine | 8 239 km | +22.6% |
| Bering Sea | 13 563 km | -50.8% |
| New Zealand | 15 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:
| Region | dist_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
--municipalitiesoff entirely outside Europe.countrystill works, since Natural Earth is global. - Or keep it and pass
--max-municipality-dist, which clears the name beyond a limit. Themunicipality_distcolumn shows how far each match reached, and is0for 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
arcticpreset’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
autowidens 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, andplacetake it.depthreads a grid andnearestworks 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.
--partitionderives every box and center from your points, so combining it with--region,--min-lonand friends, or--proj-lon0is 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>:
| Preset | Box (min_lon, max_lon, min_lat, max_lat) |
|---|---|
global | -180, 180, -90, 90 |
baltic | 8, 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 thebalticpreset. 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.--partitionsplits 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 data | Use | Why |
|---|---|---|
| Spans less than about 5000 km | auto | --partition produces a single partition, so the two give the same answer to within centimetres. |
| Falls into a few distant clusters, however far apart | --partition | This is the case it wins outright. Measured below: 8.6% mean error becomes 0.15%. |
| Is spread continuously across an ocean or the globe | --partition | It 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.
| Dataset | Span | Partitions | auto mean | auto worst | --partition mean | --partition worst |
|---|---|---|---|---|---|---|
| North Sea survey | 322 km | 1 | - | - | identical to auto | within 1 mm |
| Norwegian shelf | 1 314 km | 1 | - | - | identical to auto | within 2 cm |
| Nordic seas | 3 055 km | 1 | - | - | identical to auto | within 2 cm |
| North Atlantic | 4 806 km | 1 | - | - | identical to auto | within 22 cm |
| Two clusters, Atlantic and Pacific | 14 298 km | 2 | 8.60% | 16.91% | 0.15% | 0.45% |
| Global grid | 19 999 km | 34 | 30.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:
| Run | Time | Peak memory |
|---|---|---|
auto | 7.1 s | 0.97 GB |
--partition | 28.7 s | 1.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 Pacific | Time | Peak memory |
|---|---|---|
auto | 1.8 s | 262 MB |
--partition | 1.8 s | 90 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
| Command | Does --partition help? |
|---|---|
coast | Yes, most. dist_to_coast is planar throughout. |
place | Yes, 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. |
sea | Barely. 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. |
depth | No. It reads a global grid by arithmetic and takes no region at all. |
nearest | No. 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
autois 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.)
| Command | Appended columns | Type |
|---|---|---|
coast | dist_to_coast | float (km or m) |
depth | bathymetry, plus on_land with --on-land | float (m), bool |
sea | sea_name | text |
place | country, country_code, municipality, plus municipality_dist when --municipalities is given | text, text, text, float (km or m) |
nearest | nearest_name, nearest_dist | text, 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
longitudeorlatitudeis null or NaN, or - the lookup finds nothing (for example a
depthpoint off the GEBCO grid, or anearestrun against an empty reference set), or placediscards a municipality match for exceeding--max-municipality-dist, which clearsmunicipalityandmunicipality_disttogether.
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:
| Option | Default | Meaning |
|---|---|---|
-o, --output <FILE> | <stem>.<command>.<input format> | Output file (beside the input) |
--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. depth always looks up its grid on one thread, see depth |
-c, --config <TOML> | none | Config 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 inseaandplace). 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 whynearestneeds 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.
| Column | Command | Method | Accurate |
|---|---|---|---|
dist_to_coast | coast | Planar, in the region LAEA | Regionally, near the projection center |
municipality_dist | place | Planar, in the region LAEA | Regionally, near the projection center |
nearest_dist | nearest | Great circle, on the unit sphere | Everywhere 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:
- Project the point to
(x, y)meters with the spherical LAEA centered on--proj-lon0/--proj-lat0(a--regionpreset sets these). - Ask the R-tree of projected segments for the nearest one.
- 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:
- Map every reference point to an
(x, y, z)vector on the unit sphere, and index those in a 3D R-tree. - 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.
- Convert the squared chord back to meters with
d = 2R asin(chord / 2), using the mean radius6371008.8m.
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:
coastindexes projected shoreline segments; a query takes the nearest segment’s planar distance.seaandplaceindex feature bounding boxes for the containment test and boundary segments for the nearest fallback.nearestindexes 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-categoryand--mr-purpose, which default toacademiaandResearch. 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:Option Accepted 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,OtherAnything 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 ihoand answer the questions. Prompting needs a terminal to ask at, so under-y/--yesor in a non-interactive shell (CI, a pipeline) a missing field stays a hard error rather than hanging.--mr-countryis 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
| Dataset | Used by | Source |
|---|---|---|
GSHHG shorelines (ESRI shapefiles, resolution f) | coast | https://www.soest.hawaii.edu/pwessel/gshhg/ |
| GEBCO bathymetry (gridded NetCDF) | depth | https://www.gebco.net/ |
| IHO Sea Areas v3 (GeoJSON or shapefile) | sea | https://www.marineregions.org/ |
| Natural Earth countries | place | https://www.naturalearthdata.com/ |
| Eurostat GISCO LAU (municipalities) | place | https://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, soscripts/<name> --helpprints 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 pipefailand 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, orall(the default, stamp then report).reportalone re-reads outputs that already exist, so it needs no module flags. - The module flags and their options are the ones
stamp.shtakes, 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, --threadssets 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-regionruns one worker per region and--sequentialone product at a time. Stampingdepthfor 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 areportrun on its own needs them repeated.--dist-bandsand--depth-bandsset the report’s band edges. -f, --formatpicks the output format (parquet,csv,tsv,csv.gz,tsv.gz),-n, --dry-runprints the commands, and-y, --yesskips 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.
| Option | Default | Description |
|---|---|---|
-l, --license FILE | the LICENSE one level above the script | LICENSE copied into the built site. Pass --license "" to skip it. |
--citation FILE | the site-CITATION.cff beside the script | CITATION.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.
| Flag | Module | Data source |
|---|---|---|
--coast PATH | coast | GSHHG shapefile dir or GSHHS_*_L1.shp |
--depth FILE | depth | GEBCO bathymetry NetCDF |
--sea PATH | sea | IHO Sea Areas GeoJSON or shapefile |
--countries FILE | place | Natural Earth countries shapefile |
--nearest FILE | nearest | reference 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
| Option | Applies to | Meaning |
|---|---|---|
--municipalities FILE | place | GISCO LAU municipalities (optional) |
--coast-unit km|m | coast | Distance unit (default km) |
--depth-positive | depth | Report depth positive below sea level |
--depth-on-land | depth | Add an on_land boolean column |
--max-municipality-dist N | place | Drop a municipality match further than N away |
--place-unit km|m | place | Unit for municipality_dist and its cutoff (default km) |
--sea-name-field STR | sea | Feature field with the sea name (default NAME) |
--nearest-name-field STR | nearest | Reference name column (default name) |
--nearest-unit km|m | nearest | Distance 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:
| Option | Meaning |
|---|---|
--bin PATH | seastamp binary (default: $SEASTAMP_BIN, else the one on PATH, else ./target/release or ./target/debug) |
-k, --keep | Keep the intermediate files (default: remove them) |
-n, --dry-run | Print 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.