# 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 ```bash topo-operation [OPTIONS] -b input ``` --- ## Options ### **General Options** | Option | Description | |--------|-------------| | `-h`, `--help` | Display help and exit. | --- ### **Input/Output Options** | Option | Description | |--------|-------------| | `-b ` | Path to the input DTM file. **Required.** | | `-v ` | Variable name to prepend to the standard list of variable names for processing. | | `-o ` | Output file name. Default: `topo-operation.grd`. See also `-f`. | | `-f`, `-oF ` | Output format: `grd`, `grd-float`, or `netcdf`. Default is inferred from the `-o` file extension. | | `--deflate ` | 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**: `` number of nodes to shift. For **pixel cloud DTM**: `` coordinate shift value to apply to all points. | --- ### **Masking and Selection Options** | Option | Description | |--------|-------------| | `-p ` | Selection polygon file. Data outside this polygon will be ignored for `-set` and `-shift` operations. | | `-m ` | Path to a masking polygon file. | | `--masked-only` | Apply operations **only** to masked areas. | | `--persistence ` | Number of iterations for growing unmasked pixels. | | `-zmin ` | Minimum depth to import. | | `-zmax ` | 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 ` | Add the values from the specified file to convert hydrographic levels to mean levels. | | `-subtract`, `-substract ` | Subtract the values from the specified file to convert hydrographic levels to mean levels. | | `-set ` | Set bathymetry values to `0.0` for points within the selection polygon (`-p`) and depth range (`-zmin`, `-zmax`). | | `-shift ` | 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: ```bash 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: ```bash topo-operation -b input.grd --shift-grid "2 1" ``` --- ### **Apply a Mask** Apply a mask to exclude points outside a polygon: ```bash 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: ```bash topo-operation -b input.grd -p selection_polygon.grd -set 0.0 -o modified_output.grd ``` --- ### **Offset Bathymetry** Offset bathymetry by `10.0` units: ```bash topo-operation -b input.grd -shift 10.0 -o shifted_output.grd ``` --- ### **Toggle Depth/Altitude** Invert depth values (convert depth to altitude): ```bash 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: ```bash 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: ```bash topo-operation -b input.grd -subtract reference.nc -o mean_level_output.nc ``` --- ### **Process Pixel Cloud DTM** Process an unstructured pixel cloud DTM: ```bash 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]`: ```bash topo-operation -b input.grd --mask "[-50:100]" -o masked_output.grd ``` --- ### **Apply Persistence** Grow unmasked pixels with 5 iterations of persistence: ```bash topo-operation -b input.grd --persistence 5 -o persistent_output.grd ``` --- ### **Combine Multiple Operations** Combine masking, shifting, and depth range exclusion: ```bash 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:** ```bash 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 1. **Input File:** - The `-b` option is **required** to specify the input DTM file. 2. **Output Format:** - If `-f` is not specified, the output format is inferred from the file extension in `-o`. - Supported formats: `grd`, `grd-float`, `netcdf`. 3. **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. 4. **Depth Range:** - `-zmin` and `-zmax` define the depth range for importing or processing data. - `--exclusion` excludes points within the mask and depth range. 5. **Multiple Operations:** - If both `-add` and `-subtract` are provided, **only the last one** is applied. 6. **Pixel Cloud vs. Gridded DTM:** - Use `--discretisation true` to process **unstructured pixel cloud DTMs**. - For **gridded DTMs**, this option is not required. --- ## See Also - [OpenMP Documentation](https://www.openmp.org/) - [NetCDF Format](https://www.unidata.ucar.edu/software/netcdf/)