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¶

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>`	File containing a list of sounding input files.
`-b <file>`	Base bathymetry filename.
`-e <file>`	Elevation filename (can be specified multiple times).
`-d <file>`	File with distances to the coast corresponding to elevation files (to limit dry elevation areas).
`-o <name>`	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 <float>`	Resolution for decimation in arcsec or mn (default: `90arcsec` = 1/40°).
`-cluster <factor>`	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 <file>`	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=<string>`	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 <float>`	Final finite element (FE) grid resolution in arcsec or mn (default: `1arcsec` = 1/3600°).
`–isobath=true	false`
`-maxsize <float>`	Remove connections between FE nodes larger than this value.
`-maxratio <float>`	Remove connections between FE nodes with a ratio larger than this value. Set to `5.0` to retrieve former behavior.
`-dilatation <float>`	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 <file>`	Lowest Astronomical Tide (LAT) file to convert zero-hydro depths to mean level depths.
`--debug`	Enable verbose output. Default: `0`.
`-deflate <level>`	NetCDF compression level (`0` to `9`). Default: `0` (no compression).

Examples¶

Basic Usage¶

Merge random soundings with a base bathymetry:

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:

mapxyz-unstructured -l soundings_list.txt -b base_bathymetry.nc -o output_root

Including Elevation Data¶

Merge soundings, base bathymetry, and elevation data:

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:

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):

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:

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:

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):

mapxyz-unstructured -grid 2arcsec -b base_bathymetry.nc -o output_root input_soundings.xyz

Enable Cartesian Coordinates¶

Use Cartesian coordinates with a PROJ4 string:

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:

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:

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:

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¶

Input Requirements:

At least one input file (random soundings) is required.
If using -l, the file must contain a list of valid sounding files.

Decimation:

By default, random soundings are decimated by averaging clusters.
Use --no-decimation to disable this behavior (may increase processing time).

Coordinate Systems:

Default: Spherical coordinates (lon/lat).
Cartesian coordinates (--cartesian) are experimental and may be unstable.

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.

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.

Deprecated Options:

--header (not used).
-m (mesh file input, not used).