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

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.