# 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

```bash
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:

```bash
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:

```bash
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:

```bash
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:

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

### **Extract Shorelines Using a Frame**

Extract shorelines using a frame string:

```bash
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:

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

### **Swap Land and Ocean Masks**

Swap land and ocean masks:

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

### **Use a Notebook File for Grid Definition**

Define the grid using a notebook file:

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

### **Enable Debug Mode**

Enable debug mode for verbose output:

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

### **Set NetCDF Compression Level**

Set the NetCDF compression level to 4:

```bash
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

1. **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)
2. **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.
3. **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`).
4. **Masking**:
  - Use `--land` to force the mask to land.
  - Use `--swap` to invert land and ocean masks.
5. **Performance**:
  - For large datasets, consider using `--dx` to control grid resolution and balance between accuracy and computation time.

---

## See Also

- [GSHHS (Global Self-consistent, Hierarchical, High-resolution Shoreline Database)](https://www.ngdc.noaa.gov/mgg/shorelines/gshhs.html)
- [PROJ4](https://proj.org/) (for coordinate projection parameters)
- [NetCDF](https://www.unidata.ucar.edu/software/netcdf/) (for output file format)