# topo-create v3.2.3

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

---

## Description

`topo-create` is a tool designed to **create a new Digital Terrain Model (MNT)**. It allows users to merge multiple input files, specify grid resolutions, and customize output formats.

---

## Usage

```bash
topo-create -o output [OPTIONS]
```

---

## Options

### **General Options**

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

---

### **Grid Specification Options**

| Option | Description |
|--------|-------------|
| `-z <name>` | Preset zone name for grid specification. |
| `-n <file>` | Notebook file for grid specification. |
| `-g <file>` | Path to the grid file. |
| `-m <file>` | Path to the mesh file. |
| `--mapping <frame_resolution>` | Frame and resolution for the grid. Template: `[lon_min:dlon:lon_max;lat_min:dlat:lat_max]`. `dlon` and `dlat` support degrees, minutes, and arcseconds. |
| `--spherical=true` | Use spherical coordinates (default: `true`). |
| `--spherical=false` | Disable spherical coordinates. |

---

### **Input Options**

| Option | Description |
|--------|-------------|
| `-b <file>` | Path to an MNT file to be merged. Multiple calls allowed. |
| `-q <file>` | Path to a quadtree MNT file to be merged. Multiple calls allowed. |
| `-l <file>` | Path to an ASCII file containing all the files to process. Use `-iP` to set the input path. |
| `-iF <format>` | Input format. Supported formats: `grd`, `grd-float`, `nectdf`, `xyz`. |
| `-iP <path>` | Input path to read multiple files (used with `-l`). |
| `-v <name>` | Variable name in input files (must be unique). |
| `-mask <value>` | Mask value to apply. |

---

### **Depth/Altitude Options**

| Option | Description |
|--------|-------------|
| `-inv` | Toggle depth/altitude (invert sign). |
| `-zmin <value>` | Minimum imported depth. |
| `-zmax <value>` | Maximum imported depth. |

---

### **Output Options**

| Option | Description |
|--------|-------------|
| `-o <output>` | Specify the output filename. |
| `-oF <format>` | Output format. Supported formats: `grd`, `grd-float`, `netcdf`, `xyz`. Default is `netcdf` if the output file ends with `.nc`, otherwise `grd`. |
| `-deflate <level>` | Compression level (0 to 9). Default is `0` (no compression). |

---

## Examples

### **Create a New MNT from a Grid File**
```bash
topo-create -g grid_file.nc -o output.grd
```

### **Create a New MNT from a Mesh File**
```bash
topo-create -m mesh_file.nc -o output.nc
```

### **Merge Multiple MNT Files**
```bash
topo-create -b mnt1.grd -b mnt2.grd -o merged_output.grd
```

### **Merge Quadtree MNT Files**
```bash
topo-create -q quadtree1.nc -q quadtree2.nc -o merged_quadtree.nc
```

### **Specify a Custom Grid Resolution**
```bash
topo-create --mapping "[0:0.1:10;0:0.1:10]" -o custom_grid.nc
```

### **Use Spherical Coordinates**
```bash
topo-create --spherical=true -g grid_file.nc -o spherical_output.nc
```

### **Disable Spherical Coordinates**
```bash
topo-create --spherical=false -g grid_file.nc -o cartesian_output.nc
```

### **Process Files from a List**
```bash
topo-create -l file_list.txt -iP /path/to/files/ -o merged_output.nc
```

### **Set Input and Output Formats**
```bash
topo-create -iF xyz -oF netcdf -l file_list.txt -o output.nc
```

### **Invert Depth/Altitude**
```bash
topo-create -inv -g grid_file.nc -o inverted_output.nc
```

### **Apply Depth Limits**
```bash
topo-create -zmin -100 -zmax 100 -g grid_file.nc -o limited_depth.nc
```

### **Apply Mask Value**
```bash
topo-create -mask 9999 -g grid_file.nc -o masked_output.nc
```

### **Enable Compression**
```bash
topo-create -deflate 5 -g grid_file.nc -o compressed_output.nc
```

---

## Environment Variables

`topo-create` does not explicitly rely on environment variables for its core functionality. However, it uses **OpenMP** for parallel processing. You can control the number of threads using:

| Variable | Description |
|----------|-------------|
| `OMP_NUM_THREADS` | Number of threads to use for parallel processing. |

**Example:**
```bash
OMP_NUM_THREADS=4 topo-create -g grid_file.nc -o output.nc
```

---

## Notes

1. **Input Files:**
   - Supported input formats: `grd`, `grd-float`, `netcdf`, `xyz`.
   - If no input format is specified, the tool attempts to infer it from the file extension.

2. **Output Files:**
   - If no output format is specified, the default is `grd` unless the output filename ends with `.nc` (then `netcdf` is used).
   - Compression (`-deflate`) is only applicable for `netcdf` and `grd-float` formats.

3. **Grid and Mesh Files:**
   - Use `-g` for grid files and `-m` for mesh files.
   - The `--mapping` option allows fine-grained control over grid resolution and extent.

4. **Merging Files:**
   - Use `-b` for merging standard MNT files and `-q` for quadtree MNT files.
   - Multiple files can be merged by specifying `-b` or `-q` multiple times.

5. **Depth/Altitude:**
   - Use `-inv` to toggle between depth and altitude.
   - Use `-zmin` and `-zmax` to filter depth values outside the specified range.

6. **Masking:**
   - The `-mask` option allows you to specify a value to use as a mask for missing or invalid data.

---

## See Also

- [NetCDF Format](https://www.unidata.ucar.edu/software/netcdf/)
- [OpenMP Documentation](https://www.openmp.org/)