topo-merge v3.2.3¶

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

Description¶

topo-merge is a tool designed to merge Digital Terrain Models (MNTs). It combines multiple input bathymetry or topography files into a single output, allowing for flexible customization of the merging process.

Usage¶

topo-merge [OPTIONS] input1 [input2 ...]

Options¶

General Options¶

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

Input/Output Options¶

Option	Description
`-b <path>`	Path to the base bathymetry or a template string in the format: `"file=<path> variable=<name> format=<type> scale=<value> offset=<value>"`.
`-v <name>`	Name of the input bathymetry variable to prepend to the standard list of variable names tested.
`-l <file>`	Path to a file containing a list of input files (overrides command-line input arguments).
`-iF <format>`	Input format (e.g., `NETCDF`, `GRD`, `QUADTREE`). See Formats.
`-o <name>`	Output file name (default: `out.grd`). See also `-oF` and `--replace`.
`-f`, `-oF <format>`	Output format (e.g., `NETCDF`, `GRD`). Default is inferred from the file extension of `-o`.
`--replace`	Replace the base bathymetry with the merged output.

Spatial Selection Options¶

Option	Description
`-p <file>`	Path to a selection polygon file. Data outside this polygon will be ignored. See also `--frame`.
`--frame <frame>`	Selection frame in the format: `[lon_min:lon_max;lat_min:lat_max]`. Data outside this frame will be ignored. See also `-p`.
`--proj=...`	Libproj4 projection parameters. Only effective if `-iF` is specified. May crash on mode 0 and 1 grids.

Data Processing Options¶

Option	Description
`-inv`	Toggle depth/altitude for the final topography (invert sign).
`-positive`	Toggle depth/altitude for the imported topography (invert sign).
`-zmin <value>`	Minimum depth to import (values below this threshold are ignored).
`-zmax <value>`	Maximum depth to import (values above this threshold are ignored).
`-add <file>`	Path to a file to convert hydrographic levels to mean levels by adding its values.
`-subtract`, `-substract <file>`	Path to a file to convert hydrographic levels to mean levels by subtracting its values.
`-tag <integer>`	Replace this tagged value in the base bathymetry with input MNT values.
`--masked-only`	Only import data on masked values in the base bathymetry.
`--persistence <n>`	Number of iterations for growing unmasked pixels.
`-smooth-merge <options>`	Smoothing options in the format: `”zmin= zmax= steepness= target=<lower
`--polar`	Enable special routines for handling polar grids.

Output Customization Options¶

Option	Description
`-deflate <level>`	Compression level for the output file (0 to 9, default: 0).
`-debug`	Enable debug verbose mode.

Formats¶

Supported input/output formats:

QUADTREE
NETCDF
GLOBE
GRD
COMODO
ASCII
ASCII_GIS
ASCII_SLIM
ASCII_GET
ASCII_DTU
GEOTIFF
GDAL_HANDLED

Note: Most formats are inferred from the file extension, except for QUADTREE, which must be explicitly specified.

Examples¶

Basic Merge¶

Merge two input files (input1.grd and input2.grd) into a single output file:

topo-merge -o merged_output.grd input1.grd input2.grd

Merge with Base Bathymetry¶

Merge inputs using a base bathymetry file (base.grd):

topo-merge -b "file=base.grd variable=z format=GRD" -o merged_output.grd input1.grd input2.grd

Merge with Variable Name¶

Specify a custom variable name (elevation) for the input bathymetry:

topo-merge -v elevation -o merged_output.nc input1.nc input2.nc

Merge with Spatial Selection¶

Merge inputs within a specific polygon (polygon.dat) or frame:

# Using a polygon file
topo-merge -p polygon.dat -o merged_output.grd input1.grd input2.grd

# Using a frame (longitude: 0 to 10, latitude: 20 to 30)
topo-merge --frame "[0:10;20:30]" -o merged_output.grd input1.grd input2.grd

Merge with Depth Range¶

Only import depths between -1000 and -100 meters:

topo-merge -zmin -1000 -zmax -100 -o merged_output.grd input1.grd input2.grd

Convert Hydrographic Levels¶

Convert hydrographic levels to mean levels by adding a correction file (correction.grd):

topo-merge -add correction.grd -o merged_output.grd input1.grd input2.grd

Or by subtracting it:

topo-merge -subtract correction.grd -o merged_output.grd input1.grd input2.grd

Merge with Tagged Values¶

Replace a tagged value (-999) in the base bathymetry with input data:

topo-merge -b "file=base.grd variable=z" -tag -999 -o merged_output.grd input1.grd

Merge with Smoothing¶

Apply smoothing during the merge with custom parameters:

topo-merge -smooth-merge "zmin=-1000 zmax=-10 steepness=5 target=lower" -o merged_output.grd input1.grd input2.grd

Merge with Polar Grid Handling¶

Enable special routines for polar grids:

topo-merge --polar -o merged_output.grd input1.grd input2.grd

Replace Base Bathymetry¶

Replace the base bathymetry with the merged output:

topo-merge -b "file=base.grd variable=z" --replace -o merged_output.grd input1.grd input2.grd

Merge with Compression¶

Compress the output file with level 5:

topo-merge -deflate 5 -o merged_output.nc input1.nc input2.nc

Merge from a List File¶

Use a file (file_list.txt) containing a list of input files:

topo-merge -l file_list.txt -o merged_output.grd

Merge with Projection Parameters¶

Specify projection parameters for the input data:

topo-merge --proj="+proj=latlong +datum=WGS84" -iF NETCDF -o merged_output.nc input1.nc

Environment Variables¶

topo-merge 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-merge -o merged_output.grd input1.grd input2.grd

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

Notes¶

Multiple -add or -subtract Options: If multiple -add or -subtract options are provided, only the last one is applied.
Format Inference: Most formats are inferred from the file extension. However, QUADTREE must be explicitly specified using -iF.
Projection Parameters: The --proj option only works if -iF is specified. It may crash on mode 0 and 1 grids.
Debug Mode: Use -debug to enable verbose output for troubleshooting.
Polar Grids: Use --polar to enable special handling for polar grids.