shorelines-distance v3.2.3¶

Mercurial revision 5786:5c8b45563631 | 2026-08-04

Description¶

shorelines-distance computes a map of distances to the nearest coast based on a custom mesh and an input shoreline. It can also pre-merge a shoreline/coastline file with an existing dataset using the -s option.

The grid can be defined using the following options:

--dx: Grid resolution in meters.
--grid: Grid definition template.
--mapping: Mapping template.
--notebook: Notebook file to define the grid.

Usage¶

shorelines-distance [OPTIONS] input_shoreline

Options¶

General Options¶

Option	Description
`-h`, `--help`	Show help and exit.
`-s <file>`	Base shoreline file to merge with. Default: `/home/data/shorelines/gshhs-2.0/gshhs_f.cst`.
`-r <name>`	Rootname for output files. Default: `anonymous`.
`-o <file>`	Output file. Default: `rootname-landmask.nc`.

Grid Definition Options¶

Option	Description
`--dx <resolution>`	Grid resolution in meters to compute distances to the nearest coastline.
`--grid <template>`	Grid definition template: `"gridfile=.. maskfile=.. tag=.. target=.."`.
`--mapping <template>`	Mapping template: `[lonmin:dlon:lonmax;latmin:dlat:latmax]`. `dlon` and `dlat` can use `deg`, `mn`, or `arcsec` units.
`--notebook <file>`	Notebook file to define the grid.
`--polar`	Enable specific routines to handle polar grids.

Extraction Options¶

Option	Description
`--extract`	Extract shorelines from the given dataset.
`-p <file>`	Polygon file to define the extraction area.
`--frame <string>`	Frame string to define the extraction area: `[lonmin:lonmax;latmin:latmax]`.

Mask Options¶

Option	Description
`--land`	Force mask to land.
`--swap`	Swap land and ocean masks.

Miscellaneous Options¶

Option	Description
`--debug`	Enable debug verbose mode.
`-deflate <level>`	NetCDF compression level. Default: `0`.
`-z <zone>`, `--zone <zone>`	Pre-set zone for grid or extraction.

Deprecated Options¶

Option	Description
`-d <factor>`	Decimation factor. Default: `1` (no decimation).
`--proj=...`	PROJ4 parameters to convert Cartesian to spherical coordinates. Default: no projection.

Examples¶

Basic Usage¶

Compute distances to the nearest coast with a grid resolution of 100 meters:

shorelines-distance -dx 100 -r 100m-grid shoreline_file.cst

Merge with a Base Shoreline¶

Merge shoreline_file.cst with a base shoreline file and compute distances:

shorelines-distance -s /path/to/base_shoreline.cst -dx 100 -r merged-grid shoreline_file.cst

Define Grid Using Mapping Template¶

Define the grid using a mapping template:

shorelines-distance --mapping "[0:1:10;0:1:10]" -r custom-grid shoreline_file.cst

Extract Shorelines from a Dataset¶

Extract shorelines from a dataset using a polygon file:

shorelines-distance --extract -p polygon_file.shp -r extracted-shore shoreline_file.cst

Extract Shorelines Using a Frame¶

Extract shorelines using a frame string:

shorelines-distance --extract --frame "[0:10;0:10]" -r frame-extracted shoreline_file.cst

Force Land Mask¶

Force the mask to land and save the output:

shorelines-distance --land -o landmask.nc shoreline_file.cst

Swap Land and Ocean Masks¶

Swap land and ocean masks:

shorelines-distance --swap -o swapped-mask.nc shoreline_file.cst

Use a Notebook File for Grid Definition¶

Define the grid using a notebook file:

shorelines-distance --notebook grid_notebook.ipynb -r notebook-grid shoreline_file.cst

Enable Debug Mode¶

Enable debug mode for verbose output:

shorelines-distance --debug -dx 100 -r debug-grid shoreline_file.cst

Set NetCDF Compression Level¶

Set the NetCDF compression level to 4:

shorelines-distance -deflate 4 -dx 100 -r compressed-grid shoreline_file.cst

Environment Variables¶

This tool does not rely on specific environment variables. However, ensure that:

Input files (shorelines, grids, etc.) are accessible.
Output directories have write permissions.

Notes¶

Input Shoreline Formats:
Supported formats include:

BIN (0)
SCAN (2)
GSHHS (3)
XISO (6)
BOUNDARIES (7)
SHP (8)
NETCDF (9)
XY (10)
MAPINFO (11)
HISTOLITT (12)
POCFORMULA (15)
NEI (16)
BEL (18)
KML (13)

Grid Handling:

If no grid definition is provided, the tool will attempt to generate one based on the input shoreline.
For polar grids, use --polar to enable specific routines.

Extraction:

The --extract option requires either a polygon file (-p) or a frame string (--frame).
Extracted shorelines are saved in the specified input file (default: rootname-extraction.shp).

Masking:

Use --land to force the mask to land.
Use --swap to invert land and ocean masks.

Performance:

For large datasets, consider using --dx to control grid resolution and balance between accuracy and computation time.