# shorelines-converter v3.2.3 **Mercurial revision 5803:7164e00e8f3d | 2026-08-18** --- ## Description `shorelines-converter` is a tool designed to **convert between different coastline formats**. It supports a wide range of input and output formats, allowing users to transform coastline data into the desired format for their applications. --- ## Usage ```bash shorelines-converter [OPTIONS] ``` --- ## Options | Option | Description | | ------------------------ | ---------------------------------------------------------------------------------------------------------------------------- | | `-h`, `--help` | Display this help message and exit. | | `-i ` | Path to the **input file**. | | `-o ` | Path to the **output file**. If not specified, the output filename is derived from the input filename and the output format. | | `-iF ` | **Input format** (e.g., `SCAN`, `SHP`, `NETCDF`). If not specified, the format is inferred from the input file extension. | | `-oF ` | **Output format** (e.g., `SCAN`, `SHP`, `NETCDF`). If not specified, the format is inferred from the output file extension. | | `-d ` | **Decimation factor** (default: `1`, no decimation). Reduces the number of points in the coastline data. | | `-l ` | **Minimum length** (default: `0`, no decimation). Removes small line segments below this length. | | `--proj=` | **Projection parameters** (e.g., `+proj=longlat +datum=WGS84`). If not specified, no projection is applied. | | `-r ` | **Root name** for output files (used in specific cases like SWOT processing). | | `--frame ` | **Frame string** to define a spatial subset (e.g., `xmin:xmax:ymin:ymax`). | | `--grid ` | **Grid file** for additional spatial reference. | | `--swot-cut ` | **SWOT-specific processing** (e.g., for demangling SWOT ground tracks). | | `--depth ` | **Depth value** to assign to the coastline data (for XYZ output). | --- ## File Formats The following coastline formats are supported: | ID | Format | | --- | ---------- | | 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 Conversion** Convert a coastline file from `SCAN` to `SHP` format: ```bash shorelines-converter -i input.scan -oF SHP -o output.shp ``` ### **Convert with Decimation** Reduce the number of points in the coastline data by a factor of 10: ```bash shorelines-converter -i input.scan -o output.scan -d 10 ``` ### **Convert with Minimum Length Filter** Remove line segments shorter than 1000 meters: ```bash shorelines-converter -i input.scan -o output.scan -l 1000 ``` ### **Convert with Projection** Apply a projection (e.g., `+proj=longlat +datum=WGS84`) to the coastline data: ```bash shorelines-converter -i input.scan -o output.shp --proj="+proj=longlat +datum=WGS84" ``` ### **Convert to XYZ Format with Depth** Convert coastline data to XYZ format with a depth of -2.0: ```bash shorelines-converter -i input.scan -o output.xyz --depth -2.0 ``` ### **Convert with Spatial Subset** Convert a coastline file and limit the output to a specific frame (e.g., `xmin:xmax:ymin:ymax`): ```bash shorelines-converter -i input.scan -o output.shp --frame "-10:10:-20:20" ``` ### **SWOT-Specific Processing** Process SWOT ground tracks and save in SHP format: ```bash shorelines-converter -i swot_tracks.scan -oF SHP --swot-cut "options" -r swot_output ``` ### **Convert with Explicit Input and Output Formats** Specify both input and output formats explicitly: ```bash shorelines-converter -i input.bin -iF BIN -o output.shp -oF SHP ``` --- ## Environment Variables `shorelines-converter` uses **OpenMP** for parallel processing. The following environment variables can be used to control parallelization: | Variable | Description | | ----------------- | ------------------------------------------------- | | `OMP_NUM_THREADS` | Number of threads to use for parallel processing. | | `OMP_SCHEDULE` | Runtime schedule type and chunk size. | | `OMP_DYNAMIC` | Enable/disable dynamic thread adjustment. | | `OMP_NESTED` | Enable/disable nested parallelism. | **Example:** ```bash OMP_NUM_THREADS=4 shorelines-converter -i input.scan -o output.shp ``` --- ## Notes 1. **Input/Output Formats:** - If the input or output format is not specified, the tool attempts to infer it from the file extension. - Use `-iF` and `-oF` to explicitly define the formats if the extensions are non-standard or ambiguous. 2. **Decimation:** - The `-d` option reduces the number of points in the coastline data by the specified factor. - The `-l` option removes line segments shorter than the specified length (in meters). 3. **Projection:** - The `--proj` option allows you to specify projection parameters in **PROJ.4** format. - If no projection is specified, the data is treated as unprojected (latitude/longitude). 4. **SWOT Processing:** - The `--swot-cut` option is designed for processing SWOT mission data (e.g., ground tracks). - Use the `-r` option to specify a root name for output files in SWOT processing. 5. **Depth Assignment:** - The `--depth` option assigns a constant depth value to all points in the coastline data (useful for XYZ output). 6. **Frame Selection:** - The `--frame` option allows you to define a spatial subset of the data (e.g., `xmin:xmax:ymin:ymax`). --- ## See Also - [PROJ.4 Documentation](https://proj.org/) (for projection parameters) - [GSHHS (Global Self-consistent, Hierarchical, High-resolution Shoreline Database)](https://www.ngdc.noaa.gov/mgg/shorelines/gshhs.html) - [Shapefile (SHP) Format](https://www.esri.com/library/whitepapers/pdfs/shapefile.pdf) - [NetCDF Format](https://www.unidata.ucar.edu/software/netcdf/)