# shorelines-doctor v3.2.3

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

---

## Description

`shorelines-doctor` is a tool designed to **evaluate the validity of shorelines**, **correct common defects**, and **process shoreline data**. It ensures that shoreline polygons are clean, consistent, and ready for further analysis or visualization.

---

## Usage

```bash
shorelines-doctor [OPTIONS] -s <input>
```

---

## Options

### **Input/Output Options**

| Option | Description |
|--------|-------------|
| `-h`, `--help` | Show this help and exit. |
| `-s <file>` | Path to the input shoreline file. See [File Formats](#file-formats1). **Required.** |
| `-iF <fmt>` | Input file format. If not specified, the format is inferred from the file extension. |
| `-oF <fmt>` | Output file format. If not specified, the format is inferred from the file extension. |
| `-r <name>` | Root name for output files at each processing step. Default: `anonymous`. |
| `-o <file>` | Output file path. Default: `<rootname>-doctored.plg`. |

---

### **Processing Options**

| Option | Description |
|--------|-------------|
| `--check=<type>` | Apply specific checks to the shoreline polygon. **Multiple calls are allowed** (each produces a distinct output file). |
| `--connections` | If `--check=overlapped` is used, split polygons at connections. |
| `--decimate-aligned <float>` | Angle threshold (in degrees) to decimate nodes with larger angles. |
| `--decimate-resolution <float>` | Resolution threshold (in units of the input coordinates) to decimate nodes with smaller distances. |
| `--debug` | Enable debug mode to save intermediate files for inspection. |

**Supported `--check` Types:**
- `dismangle`: Extract shorelines from concatenated positions arrays.
- `duplicated`: Remove duplicated polygons.
- `auto-reverse`: Fix polygons that were automatically reversed.
- `overlapped`: Fix overlapped polygons.

---

### **Deprecated Options**

> ⚠️ **Note:** The following options are **deprecated** and should no longer be used:
> - `--frame`: Frame string to limit the working area.
> - `-p`: Polygon file to limit the working area.
> - `-z`: Pre-zone name to limit the working area.

---

(file-formats1)=
## File Formats

The following file formats are supported for input and output:

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

---

## Examples

### **Basic Usage**
Process a shoreline file and save the output with the default name:
```bash
shorelines-doctor -s input.shp
```

### **Specify Input and Output Formats**
Process a shoreline file in **SHP** format and save the output in **KML** format:
```bash
shorelines-doctor -s input.shp -iF SHP -oF KML -o output.kml
```

### **Check for Duplicated Polygons**
Process a shoreline file and check for duplicated polygons:
```bash
shorelines-doctor -s input.shp --check=duplicated -r my_shoreline
```

### **Fix Overlapped Polygons**
Process a shoreline file and fix overlapped polygons:
```bash
shorelines-doctor -s input.shp --check=overlapped --connections -r my_shoreline
```

### **Extract Shorelines from Concatenated Arrays**
Process a shoreline file and extract shorelines from concatenated positions arrays:
```bash
shorelines-doctor -s input.shp --check=dismangle -r my_shoreline
```

### **Fix Auto-Reversed Polygons**
Process a shoreline file and fix polygons that were automatically reversed:
```bash
shorelines-doctor -s input.shp --check=auto-reverse -r my_shoreline
```

### **Decimate Nodes by Angle**
Process a shoreline file and decimate nodes with angles larger than 5 degrees:
```bash
shorelines-doctor -s input.shp --decimate-aligned 5.0 -r my_shoreline
```

### **Decimate Nodes by Resolution**
Process a shoreline file and decimate nodes with distances smaller than 0.1 units:
```bash
shorelines-doctor -s input.shp --decimate-resolution 0.1 -r my_shoreline
```

### **Debug Mode**
Process a shoreline file in debug mode to save intermediate files:
```bash
shorelines-doctor -s input.shp --debug -r my_shoreline
```

### **Multiple Checks**
Process a shoreline file with multiple checks (each produces a distinct output file):
```bash
shorelines-doctor -s input.shp \
  --check=duplicated \
  --check=auto-reverse \
  --check=overlapped \
  --connections \
  -r my_shoreline
```

---

## Environment Variables

`shorelines-doctor` does not rely on specific environment variables for its core functionality. However, if the tool is used in a script or workflow, standard environment variables (e.g., `PATH`) may apply.

---

## See Also

- [GSHHS (Global Self-consistent, Hierarchical, High-resolution Shoreline Database)](https://www.ngdc.noaa.gov/mgg/shorelines/)
- [Shapefile (SHP) Format](https://www.esri.com/library/whitepapers/pdfs/shapefile.pdf)
- [KML (Keyhole Markup Language)](https://developers.google.com/kml/documentation)