# 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

```bash
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](#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=<value> zmax=<value> steepness=<value> target=<lower|upper>"`. |
| `--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)=
## 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:
```bash
topo-merge -o merged_output.grd input1.grd input2.grd
```

### **Merge with Base Bathymetry**
Merge inputs using a base bathymetry file (`base.grd`):
```bash
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:
```bash
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**:
```bash
# 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:
```bash
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`):
```bash
topo-merge -add correction.grd -o merged_output.grd input1.grd input2.grd
```

Or by **subtracting** it:
```bash
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:
```bash
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:
```bash
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:
```bash
topo-merge --polar -o merged_output.grd input1.grd input2.grd
```

### **Replace Base Bathymetry**
Replace the base bathymetry with the merged output:
```bash
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`:
```bash
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:
```bash
topo-merge -l file_list.txt -o merged_output.grd
```

### **Merge with Projection Parameters**
Specify projection parameters for the input data:
```bash
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:**
```bash
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

1. **Multiple `-add` or `-subtract` Options:**
   If multiple `-add` or `-subtract` options are provided, **only the last one** is applied.

2. **Format Inference:**
   Most formats are inferred from the file extension. However, `QUADTREE` must be explicitly specified using `-iF`.

3. **Projection Parameters:**
   The `--proj` option only works if `-iF` is specified. It may crash on mode 0 and 1 grids.

4. **Debug Mode:**
   Use `-debug` to enable verbose output for troubleshooting.

5. **Polar Grids:**
   Use `--polar` to enable special handling for polar grids.

---

## See Also

- [Libproj4 Documentation](https://proj.org/) (for projection parameters)
- [OpenMP API](https://www.openmp.org/) (for parallelization options)