# topo-assembly v3.2.3

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

---

## Description

`topo-assembly` assembles tiles of data (e.g., SRTM) into a single output. It creates:
- A **`.nc` (NetCDF)** file.
- A **`.grd` (GRD format)** file (optional).

The tiling description is provided in an **input file** that defines the arrangement of the tiles. See [Tiling Description Format](#tiling-description-format).

---

## Usage

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

---

## Options

### **General Options**

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

---

### **Input Options**

| Option | Description |
|--------|-------------|
| `--litto3D <file>` | Path to an **IGN.asc** file to assemble with topography. **Multiple calls allowed.** |
| `--litto3D-list <file>` | Path to an ASCII file containing a list of **IGN.asc** files to assemble. |
| `-mask <value>` | Specify the **masked value** (default: `+INFINITY`). |
| `--allow-missing` | Continue assembly even if some tiles are missing in the frame. |

---

### **Projection and Grid Options**

| Option | Description |
|--------|-------------|
| `--cartesian <grid>` | Cartesian grid settings in the format `[xmin:dx:xmax;ymin:dy:ymax]`. Useful for handling poorly geo-referenced rasters. |
| `--proj=<proj4_string>` | **PROJ4** option string to convert Cartesian coordinates to spherical. |

---

### **Output Options**

| Option | Description |
|--------|-------------|
| `-o <rootname>` | Root name for output files (default: `assembly`). |
| `-grd` | Also save topography in **GRD format** (in addition to NetCDF). |
| `-deflate <level>` | Compression level for output files (0 to 9). Default: `0` (no compression). |
| `-short` | Enable reading of **short integer format** for input data. |
| `-shrinked` | Shrink the topography to the **minimum frame** defined by the topography. |

---

(tiling-description-format)=
## Tiling Description Format

The input file must follow this format:

1. **First line**: Contains the **X (#columns)** and **Y (#rows)** size of the output, in number of tiles.
   Example: `3 2`

2. **Subsequent lines**: Each line describes a tile with:
   - **X (column index)** and **Y (row index)** of the tile position (origin is bottom/left).
   - **File name** of the tile.
   - **Variable name** of the data in the file.

**Example:**
```
3 2
0 0 n03_e008_3arc_v1.nc Band1
1 0 n03_e009_3arc_v1.nc Band1
2 0 n03_e010_3arc_v1.nc Band1
0 1 n04_e008_3arc_v1.nc Band1
1 1 n04_e009_3arc_v1.nc Band1
2 1 n04_e010_3arc_v1.nc Band1
```

---

## Examples

### **Basic Assembly**
Assemble tiles described in `tiling.txt`:
```bash
topo-assembly tiling.txt
```

### **Custom Output Name**
Assemble tiles and save outputs with a custom root name:
```bash
topo-assembly -o my_output tiling.txt
```

### **Enable GRD Output**
Assemble tiles and save in both **NetCDF** and **GRD** formats:
```bash
topo-assembly -grd tiling.txt
```

### **Compress Output**
Assemble tiles with compression level `5`:
```bash
topo-assembly -deflate 5 tiling.txt
```

### **Use Short Integer Format**
Assemble tiles with short integer input data:
```bash
topo-assembly -short tiling.txt
```

### **Shrink to Minimum Frame**
Shrink the output to the minimum frame defined by the topography:
```bash
topo-assembly -shrinked tiling.txt
```

### **Allow Missing Tiles**
Continue assembly even if some tiles are missing:
```bash
topo-assembly --allow-missing tiling.txt
```

### **Cartesian Grid**
Assemble tiles with a Cartesian grid:
```bash
topo-assembly --cartesian "[0:1:100;0:1:100]" tiling.txt
```

### **PROJ4 Projection**
Convert Cartesian coordinates to spherical using a PROJ4 string:
```bash
topo-assembly --proj="+proj=utm +zone=10 +ellps=WGS84" tiling.txt
```

### **LITTO3D Assembly**
Assemble LITTO3D files (IGN.asc format):
```bash
topo-assembly --litto3D LITTO3D_FRA_0374_6414_MNT5_20250531_LAMB93_RGF93_IGN69.asc tiling.txt
```

Assemble multiple LITTO3D files:
```bash
topo-assembly \
  --litto3D file1.asc \
  --litto3D file2.asc \
  tiling.txt
```

Assemble LITTO3D files from a list:
```bash
topo-assembly --litto3D-list litto3d_files.txt tiling.txt
```

### **Combined Options**
Assemble tiles with compression, GRD output, and a custom root name:
```bash
topo-assembly -o my_topography -grd -deflate 4 tiling.txt
```

---

## Environment Variables

`topo-assembly` does not rely on specific environment variables. However, if **PROJ4** is used, ensure the `proj` library is correctly installed and configured on your system.

---

## Notes

1. **Input Files**:
   - The input file must follow the [Tiling Description Format](#tiling-description-format).
   - Supported input formats include **NetCDF** and **IGN.asc** (for LITTO3D).

2. **Output Files**:
   - By default, outputs are named `assembly.nc` and `assembly.grd` (if `-grd` is used).
   - Use `-o` to specify a custom root name.

3. **Mask Handling**:
   - Use `-mask` to define a custom masked value (default: `+INFINITY`).
   - Masked values are excluded from the assembly process.

4. **Performance**:
   - For large datasets, consider using `-deflate` to reduce file size.
   - The `-shrinked` option can reduce memory usage by limiting the output to the minimum frame.

5. **Debugging**:
   - Use `--debug` to enable verbose output for troubleshooting.

---

## See Also

- [PROJ4 Documentation](https://proj.org/) (for projection options)
- [NetCDF Format](https://www.unidata.ucar.edu/software/netcdf/)
- [GRD Format](https://www.generic-mapping-tools.org/)