# xyz-format v3.2.3 **Mercurial revision 5786:5c8b45563631 | 2026-08-04** --- ## Description `xyz-format` is a tool designed to **convert** XYZ sounding/elevation files or **merge** multiple files into a single output file with a chosen format. It supports various input and output formats, allowing for flexible data processing and transformation. --- ## Usage ```bash xyz-format [OPTIONS] file1 [file2 ...] ``` --- ## Options ### **General Options** | Option | Description | | -------------- | ------------------------ | | `-h`, `--help` | Show this help and exit. | --- ### **Input/Output Options** | Option | Description | | ----------------------- | ------------------------------------------------------------------ | | `-l ` | File containing a list of all files to process. | | `-iF ` | Input format. One of: `XYZ`, `GIS`. | | `-oF ` | Output format. One of: `grd`, `grd-float`, `netcdf`, `xyz`, `gis`. | | `-o ` | Root name for the output file. Default: `anonymous`. | | `-v`, `-varname ` | Variable name in the output. | --- ### **Data Processing Options** | Option | Description | | ------------------------- | ------------------------------------------------------------------------- | | `--parameter ` | Column index in the input files where the variable to convert is located. | | `--parameter-name ` | Name of the variable in the input files to convert. | | `--header ` | Header of the input file. | | `-p ` | Polygon file to limit the processing area. | | `--quadtree` | Process data as a quadtree to speed up processing and limit storage. | | `-flip` | Flip data north-south. | --- ### **Data Transformation Options** | Option | Description | | ------------------- | ------------------------------------------------------------------------------- | | `-zmin ` | Minimum value to constrain the output. | | `-zmax ` | Maximum value to constrain the output. | | `-scale ` | Apply a scale factor to the field data. | | `-inv` | Invert the data (equivalent to `-scale -1`). | | `-add ` | File to convert hydrographic level to mean level by **adding** its values. | | `-substract ` | File to convert hydrographic level to mean level by **subtracting** its values. | | `--pbma` | **Deprecated.** Identical to `-add`. | --- ### **Masking and Compression Options** | Option | Description | | -------------------- | -------------------------------------------------------------------------------------------------------- | | `-mask ` | Mask value to override the input mask. Required when input format is `GEOTIFF`. | | `-persistence ` | Number of pixels for value expansion to unmasked areas. Default: `5`. | | `-deflate` | NetCDF compression level. Default: none. Only useful for `grd`, `grd-float`, or `netcdf` output formats. | --- ### **Deprecated Options** | Option | Description | | ----------- | --------------------------------------------------------------------------------- | | `-b ` | **Deprecated.** Bathymetry file to merge with. Use `mapxyz-unstructured` instead. | --- ## Examples ### **Basic Conversion** Convert a single XYZ file to NetCDF format: ```bash xyz-format -iF XYZ -oF netcdf -o output.nc input.xyz ``` ### **Merge Multiple Files** Merge multiple XYZ files into a single output file: ```bash xyz-format -l file_list.txt -oF grd -o merged_output.grd ``` ### **Convert with Custom Variable Name** Convert a file and specify the output variable name: ```bash xyz-format -iF XYZ -oF netcdf -v elevation -o elevation.nc input.xyz ``` ### **Apply Scaling** Apply a scaling factor of `2.0` to the data: ```bash xyz-format -iF XYZ -oF xyz -scale 2.0 -o scaled_output.xyz input.xyz ``` ### **Invert Data** Invert the data values (equivalent to scaling by `-1`): ```bash xyz-format -iF XYZ -oF xyz -inv -o inverted_output.xyz input.xyz ``` ### **Add Hydrographic Correction** Convert hydrographic levels to mean levels by adding a correction file: ```bash xyz-format -iF XYZ -oF netcdf -add correction_file.xyz -o corrected_output.nc input.xyz ``` ### **Subtract Hydrographic Correction** Convert hydrographic levels to mean levels by subtracting a correction file: ```bash xyz-format -iF XYZ -oF netcdf -substract correction_file.xyz -o corrected_output.nc input.xyz ``` ### **Limit Processing Area with Polygon** Process only the data within a specified polygon: ```bash xyz-format -iF XYZ -oF xyz -p polygon.txt -o clipped_output.xyz input.xyz ``` ### **Use Quadtree Processing** Process data as a quadtree for efficient storage and faster processing: ```bash xyz-format -iF XYZ -oF netcdf --quadtree -o quadtree_output.nc input.xyz ``` ### **Set Custom Mask Value** Override the input mask with a custom value (e.g., for GEOTIFF input): ```bash xyz-format -iF GIS -oF grd -mask -9999 -o masked_output.grd input.tif ``` ### **Apply NetCDF Compression** Compress the output NetCDF file: ```bash xyz-format -iF XYZ -oF netcdf -deflate 4 -o compressed_output.nc input.xyz ``` ### **Use Parameter Name for Conversion** Specify the name of the variable in the input file to convert: ```bash xyz-format -iF XYZ -oF netcdf --parameter-name "depth" -o output.nc input.xyz ``` --- ## Environment Variables `xyz-format` does not rely on specific environment variables for its core functionality. However, if used in conjunction with other tools or scripts, ensure that: - File paths are correctly set. - Permissions are properly configured for input/output directories. --- ## Notes 1. **Input Formats:** - Supported input formats: `XYZ`, `GIS`. - If `-iF` is not specified, the tool attempts to infer the format automatically. 2. **Output Formats:** - Supported output formats: `grd`, `grd-float`, `netcdf`, `xyz`, `gis`. - Use `-oF` to specify the desired output format. 3. **Data Constraints:** - Use `-zmin` and `-zmax` to constrain the output values to a specific range. 4. **Masking:** - The `-mask` option is **required** when the input format is `GEOTIFF`. - The default mask value is `-999999`. 5. **Quadtree Processing:** - The `--quadtree` option is useful for **large datasets** to optimize storage and processing speed. 6. **Deprecated Options:** - The `-b` option is deprecated. Use `mapxyz-unstructured` for merging sounding files with bathymetry. --- ## See Also - [`mapxyz-unstructured`](https://www.comodo-ocean.fr/): An alternative tool for merging sounding files with a given bathymetry.