# topo-fuse v3.2.3

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

---

## Description

`topo-fuse` merges **Digital Terrain Models (MNTs)** into a **quadtree file** for enhanced performance and storage efficiency. It is designed to combine multiple bathymetry or topography datasets into a single, optimized structure.

---

## Usage

```bash
topo-fuse [OPTIONS] input
```

---

## Options

### **General Options**

| Option | Description |
|--------|-------------|
| `-h`, `--help` | Display help and exit. |
| `-debug` | Enable debug verbose mode. |

---

### **Input/Output Options**

| Option | Description |
|--------|-------------|
| `input` | Input file (required). |
| `-b <file>` | Base bathymetry file to merge with. |
| `-l <file>` | ASCII file containing a list of input files (overrides the `input` argument). |
| `-iF <format>` | Input format: `grd`, `grd-float`, `netcdf`, or `xyz`. Default: `grd`. |
| `--proj=<params>` | [Libproj4](https://proj.org/) projection parameters. Only effective if `-iF` is specified. **Warning:** May crash on mode 0 and 1 grids. |
| `-o <file>` | Output filename (NetCDF quadtree format). |

---

### **Deprecated Options**

> **Note:** These options are **no longer recommended** and may be removed in future versions.

| Option | Description |
|--------|-------------|
| `-oF <format>`, `-f <format>` | Output format: `grd`, `grd-float`, `netcdf`, or `xyz`. Default: `grd`. |
| `-p <file>` | Selection polygon file. |
| `-inv` | Toggle depth/altitude on the **final** topography. |
| `-positive` | Toggle depth/altitude on the **imported** topography. |
| `-zmin <value>` | Minimum imported depth. |
| `-zmax <value>` | Maximum imported depth. |
| `-add <file>` | Path to a file to convert hydrographic level to mean level by **adding** its values. |
| `-subtract`, `-substract <file>` | Path to a file to convert hydrographic level to mean level by **subtracting** its values. |
| `-persistence` | **Unused.** |
| `-tag` | **Unused.** |
| `--masked-only` | Only import data on masked areas. |

---

## Examples

### **Basic Usage**
Merge a single input file into a quadtree:
```bash
topo-fuse input.grd -o output.nc
```

### **Merge with a Base Bathymetry**
Combine an input file with a base bathymetry:
```bash
topo-fuse input.grd -b base_bathymetry.grd -o output.nc
```

### **Use a List of Input Files**
Merge multiple files listed in `files.txt`:
```bash
topo-fuse -l files.txt -o output.nc
```

### **Specify Input Format**
Merge a NetCDF input file:
```bash
topo-fuse input.nc -iF netcdf -o output.nc
```

### **Apply Projection Parameters**
Merge with a custom projection (e.g., UTM zone 33N):
```bash
topo-fuse input.grd --proj="+proj=utm +zone=33 +ellps=GRS80 +units=m" -o output.nc
```

### **Debug Mode**
Enable debug verbose mode for troubleshooting:
```bash
topo-fuse input.grd -debug -o output.nc
```

### **Only Import Masked Areas**
Import data only where the mask is applied:
```bash
topo-fuse input.grd --masked-only -o output.nc
```

---

## Environment Variables

`topo-fuse` 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-fuse input.grd -o output.nc
```

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

---

## Notes

1. **Input Files:**
   - Supported formats: `grd`, `grd-float`, `netcdf`, `xyz`.
   - The `-iF` option is required for non-default formats.

2. **Output:**
   - Default output format: **NetCDF quadtree** (`-o` option).
   - Deprecated output formats (`-oF`, `-f`) are not recommended.

3. **Projection:**
   - Use `--proj=` to specify custom projection parameters (requires `-iF`).
   - **Warning:** Projections may not work with mode 0 and 1 grids.

4. **Performance:**
   - For large datasets, use `-debug` to monitor progress and identify bottlenecks.
   - Adjust `OMP_NUM_THREADS` based on available CPU resources.

5. **Masking:**
   - Use `--masked-only` to import data only where the mask is applied.

6. **Depth/Altitude:**
   - Use `-inv` or `-positive` to toggle depth/altitude values (deprecated).

---

## See Also

- [Libproj4 Documentation](https://proj.org/) (for projection parameters)
- [NetCDF Format](https://www.unidata.ucar.edu/software/netcdf/) (for input/output formats)
- [OpenMP Documentation](https://www.openmp.org/) (for parallelization)