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¶

xyz-format [OPTIONS] file1 [file2 ...]

Options¶

General Options¶

Option	Description
`-h`, `--help`	Show this help and exit.

Input/Output Options¶

Option	Description
`-l <file>`	File containing a list of all files to process.
`-iF <fmt>`	Input format. One of: `XYZ`, `GIS`.
`-oF <fmt>`	Output format. One of: `grd`, `grd-float`, `netcdf`, `xyz`, `gis`.
`-o <name>`	Root name for the output file. Default: `anonymous`.
`-v`, `-varname <name>`	Variable name in the output.

Data Processing Options¶

Option	Description
`--parameter <int>`	Column index in the input files where the variable to convert is located.
`--parameter-name <name>`	Name of the variable in the input files to convert.
`--header <string>`	Header of the input file.
`-p <file>`	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 <float>`	Minimum value to constrain the output.
`-zmax <float>`	Maximum value to constrain the output.
`-scale <float>`	Apply a scale factor to the field data.
`-inv`	Invert the data (equivalent to `-scale -1`).
`-add <file>`	File to convert hydrographic level to mean level by adding its values.
`-substract <file>`	File to convert hydrographic level to mean level by subtracting its values.
`--pbma`	Deprecated. Identical to `-add`.

Masking and Compression Options¶

Option	Description
`-mask <float>`	Mask value to override the input mask. Required when input format is `GEOTIFF`.
`-persistence <int>`	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 <file>`	Deprecated. Bathymetry file to merge with. Use `mapxyz-unstructured` instead.

Examples¶

Basic Conversion¶

Convert a single XYZ file to NetCDF format:

xyz-format -iF XYZ -oF netcdf -o output.nc input.xyz

Merge Multiple Files¶

Merge multiple XYZ files into a single output file:

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:

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:

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

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:

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:

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:

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:

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

xyz-format -iF GIS -oF grd -mask -9999 -o masked_output.grd input.tif

Apply NetCDF Compression¶

Compress the output NetCDF file:

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:

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¶

Input Formats:

Supported input formats: XYZ, GIS.
If -iF is not specified, the tool attempts to infer the format automatically.

Output Formats:

Supported output formats: grd, grd-float, netcdf, xyz, gis.
Use -oF to specify the desired output format.

Data Constraints:

Use -zmin and -zmax to constrain the output values to a specific range.

Masking:

The -mask option is required when the input format is GEOTIFF.
The default mask value is -999999.

Quadtree Processing:

The --quadtree option is useful for large datasets to optimize storage and processing speed.

Deprecated Options:

The -b option is deprecated. Use mapxyz-unstructured for merging sounding files with bathymetry.