topo-operation v3.2.3¶

Mercurial revision 5786:5c8b45563631 | 2026-08-04

Description¶

topo-operation is a tool for performing operations on gridded or pixel cloud Digital Terrain Models (DTM). It allows users to modify, analyze, and process bathymetry or topography data with various options for shifting, masking, setting values, and applying transformations.

Usage¶

topo-operation [OPTIONS] -b input

Options¶

General Options¶

Option	Description
`-h`, `--help`	Display help and exit.

Input/Output Options¶

Option	Description
`-b <file>`	Path to the input DTM file. Required.
`-v <name>`	Variable name to prepend to the standard list of variable names for processing.
`-o <name>`	Output file name. Default: `topo-operation.grd`. See also `-f`.
`-f`, `-oF <format>`	Output format: `grd`, `grd-float`, or `netcdf`. Default is inferred from the `-o` file extension.
`--deflate <level>`	Compression level for NetCDF output (0 to 9). Default: `0` (no compression).

Processing Options¶

Option	Description
`--discretisation true`	Process pixel cloud DTM (unstructured data). Otherwise, treat input as a structured grid.
`--shift-grid`, `--shift-coordinates <"i_shift j_shift">`	Shift the grid or coordinates. For gridded DTM: `<int>` number of nodes to shift. For pixel cloud DTM: `<float>` coordinate shift value to apply to all points.

Masking and Selection Options¶

Option	Description
`-p <file>`	Selection polygon file. Data outside this polygon will be ignored for `-set` and `-shift` operations.
`-m <file>`	Path to a masking polygon file.
`--masked-only`	Apply operations only to masked areas.
`--persistence <n>`	Number of iterations for growing unmasked pixels.
`-zmin <value>`	Minimum depth to import.
`-zmax <value>`	Maximum depth to import.
`--exclusion`	Exclude all points selected by the mask and depth range in the imported DTM.
`--mask <[min:max]>`	Mask output values outside the specified range `[min:max]`.

Data Transformation Options¶

Option	Description
`-inv`	Toggle depth/altitude in the final topography (multiply by `-1`).
`-add <file>`	Add the values from the specified file to convert hydrographic levels to mean levels.
`-subtract`, `-substract <file>`	Subtract the values from the specified file to convert hydrographic levels to mean levels.
`-set <value>`	Set bathymetry values to `0.0` for points within the selection polygon (`-p`) and depth range (`-zmin`, `-zmax`).
`-shift <value>`	Offset bathymetry by the specified value.

Note: If multiple -add or -subtract options are provided, only the last one is applied.

Options to Be Implemented¶

Option	Description
`-formula`	Set custom operations on the DTM (not yet implemented).
`-m`	Masking option for pixel clouds (not yet implemented).

Examples¶

Basic Usage¶

Process a DTM file and save the output in NetCDF format:

topo-operation -b input.grd -o output.nc -f netcdf

Shift Grid Coordinates¶

Shift the grid by 2 nodes in the i-direction and 1 node in the j-direction:

topo-operation -b input.grd --shift-grid "2 1"

Apply a Mask¶

Apply a mask to exclude points outside a polygon:

topo-operation -b input.grd -m mask_polygon.grd -o masked_output.grd

Set Depth Values¶

Set bathymetry values to 0.0 within a selection polygon:

topo-operation -b input.grd -p selection_polygon.grd -set 0.0 -o modified_output.grd

Offset Bathymetry¶

Offset bathymetry by 10.0 units:

topo-operation -b input.grd -shift 10.0 -o shifted_output.grd

Toggle Depth/Altitude¶

Invert depth values (convert depth to altitude):

topo-operation -b input.grd -inv -o inverted_output.grd

Add a File to Convert Hydrographic Levels¶

Add values from a reference file to convert hydrographic levels to mean levels:

topo-operation -b input.grd -add reference.nc -o mean_level_output.nc

Subtract a File to Convert Hydrographic Levels¶

Subtract values from a reference file to convert hydrographic levels to mean levels:

topo-operation -b input.grd -subtract reference.nc -o mean_level_output.nc

Process Pixel Cloud DTM¶

Process an unstructured pixel cloud DTM:

topo-operation -b input_cloud.nc --discretisation true -o cloud_output.nc

Mask Output by Depth Range¶

Mask output values outside the range [-50:100]:

topo-operation -b input.grd --mask "[-50:100]" -o masked_output.grd

Apply Persistence¶

Grow unmasked pixels with 5 iterations of persistence:

topo-operation -b input.grd --persistence 5 -o persistent_output.grd

Combine Multiple Operations¶

Combine masking, shifting, and depth range exclusion:

topo-operation -b input.grd \
  -m mask_polygon.grd \
  --shift-grid "1 1" \
  -zmin -100 -zmax 50 \
  --exclusion \
  -o final_output.grd

Environment Variables¶

topo-operation uses OpenMP (version 201511) for parallelization. Key environment variables:

Variable	Description
`OMP_NUM_THREADS`	Number of threads to use.
`OMP_SCHEDULE`	Runtime schedule type and chunk size.
`OMP_DYNAMIC`	Enable/disable dynamic thread adjustment.
`OMP_NESTED`	Enable/disable nested parallelism.

Example:

OMP_NUM_THREADS=6 topo-operation -b input.grd -o output.grd

Note: If running on a machine with high CPU load, limit threads to the number of free CPUs to avoid performance degradation.

Notes¶

Input File:
- The -b option is required to specify the input DTM file.
Output Format:
- If -f is not specified, the output format is inferred from the file extension in -o.
- Supported formats: grd, grd-float, netcdf.
Masking and Selection:
- The -p option defines a polygon for selecting areas where operations like -set and -shift are applied.
- The -m option applies a mask to exclude or include specific areas.
Depth Range:
- -zmin and -zmax define the depth range for importing or processing data.
- --exclusion excludes points within the mask and depth range.
Multiple Operations:
- If both -add and -subtract are provided, only the last one is applied.
Pixel Cloud vs. Gridded DTM:
- Use --discretisation true to process unstructured pixel cloud DTMs.
- For gridded DTMs, this option is not required.