# mapxyz-unstructured v3.2.3 **Mercurial revision 5770:c90c3015e72d | 2026-05-22** --- ## Description `mapxyz-unstructured` merges **structured and random sounding bathymetric data** to create a unified bathymetry. It: - Generates a bathymetry from random sounding input files. - Pads the result with a **base bathymetry file** and **elevation files** (if provided). - By default, **decimates random soundings** by averaging clusters to optimize performance. --- ## Usage ```bash mapxyz-unstructured [OPTIONS] input ``` - `input`: Input file(s) containing random soundings or a list of files (using `-l`). --- ## Options ### **Input/Output Options** | Option | Description | | -------------- | ------------------------------------------------------------------------------------------------- | | `-h`, `--help` | Show help and exit. | | `-l ` | File containing a list of sounding input files. | | `-b ` | Base bathymetry filename. | | `-e ` | Elevation filename (can be specified multiple times). | | `-d ` | File with distances to the coast corresponding to elevation files (to limit dry elevation areas). | | `-o ` | Root name for output files (default: `mapxyz-unstructured`). | --- ### **Data Processing Controls** Controls for merging different sources (soundings, base bathymetry, elevation). **Prefixes:** - `s_` for random soundings. - `b_` for base bathymetry. - `e_` for elevation. | Option | Description | Default | | ---------------------------------------------- | ----------------------------------------------- | --------------------------------------------- | | `-s_offset`, `-b_offset`, `-e_offset` | Offset for depth/altitude conversion. | `0.` | | `-s_incr`, `-b_incr`, `-e_incr` | Point incrementation. | `1` | | `-s_range`, `-b_range`, `-e_range` | Range for data filtering. | `0` | | `-s_threshold`, `-b_threshold`, `-e_threshold` | Threshold for data filtering. | `0.` (soundings/bathymetry), `1.` (elevation) | | `-s_poly`, `-b_poly`, `-e_poly` | Polygon file to limit the area for each source. | None | --- ### **Decimation Options** | Option | Description | | ---------------------------------------------- | ------------------------------------------------------------------------------------------------- | | `--no-decimation` | Keep all random soundings (disable decimation). | | `-resolution ` | Resolution for decimation in **arcsec** or **mn** (default: `90arcsec` = 1/40°). | | `-cluster ` | Factor to group soundings (`resolution * factor`). Default: `20`. | | `--check-duplicate` | Remove soundings that are too close (< 0.001 km). | | `--frame "[lon_min:lon_max; lat_min:lat_max]"` | Frame to limit soundings. **Warning:** If defined, used **before** polygon filtering (`-s_poly`). | | `--decimate-only` | Process only random soundings on base bathymetry (no elevation files). | | `--filter` | If `--decimate-only`, only consider soundings close to valid DTM nodes. | | `-trusted ` | If `--decimate-only`, trusted DTM filename for filtering. | | `--paranoiac` | If `--decimate-only`, test the soundings database after filtering. | | `--autoscale` | If `--decimate-only`, infer bathymetry sign and force negative mode. | --- ### **Coordinate System Options** | Option | Description | | ----------------- | ------------------------------------------------------------------------ | | `--cartesian` | Activate Cartesian coordinates for soundings. **Note:** May be unstable. | | `--proj=` | PROJ4 option string to convert Cartesian coordinates to spherical. | --- ### **Grid and Mesh Options** | Option | Description | | ------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------ | | `-limits "file= offset="` | Polygon file and offset depth at the boundary. Builds the regular grid with the lon-lat range of the polygon. | | `--mapping "[lon_min:lon_max; lat_min:lat_max]"` | Frame to set the regular grid. | | `-grid ` | Final finite element (FE) grid resolution in **arcsec** or **mn** (default: `1arcsec` = 1/3600°). | | `--isobath=true|false` | Reprocess FE distribution to better match isobaths. Default: `true`. | | `-maxsize ` | Remove connections between FE nodes larger than this value. | | `-maxratio ` | Remove connections between FE nodes with a ratio larger than this value. Set to `5.0` to retrieve former behavior. | | `-dilatation ` | Coefficient to extend lon-lat ranges for edge handling. Default: `0.05`. | | `--mesh` | Save the NEI mesh file of the FE grid. | --- ### **Miscellaneous Options** | Option | Description | | ------------------ | -------------------------------------------------------------------------------------- | | `--pbma ` | Lowest Astronomical Tide (LAT) file to convert zero-hydro depths to mean level depths. | | `--debug` | Enable verbose output. Default: `0`. | | `-deflate ` | NetCDF compression level (`0` to `9`). Default: `0` (no compression). | --- ## Examples ### **Basic Usage** Merge random soundings with a base bathymetry: ```bash mapxyz-unstructured -b base_bathymetry.nc -o output_root input_soundings.xyz ``` ### **Using a List of Sounding Files** Process multiple sounding files from a list: ```bash mapxyz-unstructured -l soundings_list.txt -b base_bathymetry.nc -o output_root ``` ### **Including Elevation Data** Merge soundings, base bathymetry, and elevation data: ```bash mapxyz-unstructured -b base_bathymetry.nc -e elevation1.nc -e elevation2.nc -o output_root input_soundings.xyz ``` ### **Disable Decimation** Keep all random soundings without decimation: ```bash mapxyz-unstructured --no-decimation -b base_bathymetry.nc -o output_root input_soundings.xyz ``` ### **Custom Decimation Resolution** Set a custom decimation resolution (e.g., `30arcsec`): ```bash mapxyz-unstructured -resolution 30arcsec -b base_bathymetry.nc -o output_root input_soundings.xyz ``` ### **Decimate Only with Filtering** Process only random soundings on base bathymetry with filtering: ```bash mapxyz-unstructured --decimate-only --filter -trusted trusted_dtm.nc -b base_bathymetry.nc -o output_root input_soundings.xyz ``` ### **Limit Soundings to a Frame** Restrict soundings to a specific geographic frame: ```bash mapxyz-unstructured --frame "[2:5; 45:50]" -b base_bathymetry.nc -o output_root input_soundings.xyz ``` ### **Custom Grid Resolution** Set a custom FE grid resolution (e.g., `2arcsec`): ```bash mapxyz-unstructured -grid 2arcsec -b base_bathymetry.nc -o output_root input_soundings.xyz ``` ### **Enable Cartesian Coordinates** Use Cartesian coordinates with a PROJ4 string: ```bash mapxyz-unstructured --cartesian --proj="+proj=utm +zone=10 +ellps=WGS84" -b base_bathymetry.nc -o output_root input_soundings.xyz ``` ### **Save Mesh File** Generate and save the NEI mesh file: ```bash mapxyz-unstructured --mesh -b base_bathymetry.nc -o output_root input_soundings.xyz ``` ### **Use Polygon to Limit Area** Limit soundings and bathymetry to a polygon-defined area: ```bash mapxyz-unstructured -s_poly coast_polygon.shp -b_poly bathy_polygon.shp -b base_bathymetry.nc -o output_root input_soundings.xyz ``` ### **Adjust Depth Offsets** Apply offsets to soundings and bathymetry: ```bash mapxyz-unstructured -s_offset 10.0 -b_offset -5.0 -b base_bathymetry.nc -o output_root input_soundings.xyz ``` --- ## Environment Variables `mapxyz-unstructured` does not rely on specific environment variables. However, ensure your system has: - **PROJ4** (if using `--proj` for coordinate transformations). - **NetCDF libraries** (for reading/writing NetCDF files). --- ## Notes 1. **Input Requirements:** - At least **one input file** (random soundings) is required. - If using `-l`, the file must contain a list of valid sounding files. 2. **Decimation:** - By default, random soundings are decimated by averaging clusters. - Use `--no-decimation` to disable this behavior (may increase processing time). 3. **Coordinate Systems:** - Default: **Spherical coordinates** (lon/lat). - Cartesian coordinates (`--cartesian`) are experimental and may be unstable. 4. **Performance:** - For large datasets, consider adjusting `-resolution` and `-cluster` to balance accuracy and performance. - Use `-deflate` to compress NetCDF output files and save disk space. 5. **Output Files:** - Output files are named using the `-o` root name (default: `mapxyz-unstructured`). - If `--mesh` is enabled, a NEI mesh file is generated alongside the bathymetry. 6. **Deprecated Options:** - `--header` (not used). - `-m` (mesh file input, not used). --- ## See Also - [PROJ4 Documentation](https://proj.org/) (for coordinate transformations) - [NetCDF Documentation](https://www.unidata.ucar.edu/software/netcdf/) (for file formats)