# topo-antarctic v3.2.3

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

---

## Description

`topo-antarctic` is a tool designed to **process the bathymetry of Antarctica**. It reads input bathymetry data, applies optional transformations (e.g., inversion, averaging, or projection), and saves the results in the specified output format.

---

## Usage

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

---

## Options

### **Input/Output Options**

| Option | Description |
|--------|-------------|
| `-h`, `--help` | Show help and exit. |
| `-iF <fmt>` | **Input file format**: `comodo`, `timmerman`, or `albmap`. Default: `comodo`. |
| | **`comodo`**: Must contain the `z` variable. |
| | **`timmerman`**: Must contain `bathy` (bathymetry) and `draft` (ice bottom position) variables. |
| | **`albmap`**: Must contain `topg` (bathymetry) and `lsrf` (ice bottom position) variables. |
| `-f`, `-oF <fmt>` | **Output format**: `netcdf`, `grd`, or `grd-float`. Default: `netcdf`. |
| `-o <name>` | Root name for the output file. Default: `out`. |

---

### **Processing Options**

| Option | Description |
|--------|-------------|
| `--proj=...` | **PROJ4 string** to convert Cartesian coordinates to spherical (e.g., `--proj="+proj=stere +lat_0=-90 +lon_0=0 +lat_ts=-71 +x_0=0 +y_0=0 +ellps=WGS84"`). |
| `-inv` | Invert altitude/depth topography (multiply by `-1`). |
| `-average <int>` | Average the depth over a grid of `<int>` nodes around each point. |
| `-deflate <level>` | **NetCDF compression level** (0-9). Default: `0` (no compression). Only applicable for `netcdf`, `grd`, or `grd-float` output formats. |

---

### **Deprecated Options**

> ⚠️ **These options are deprecated and may not work in future versions.**

| Option | Description |
|--------|-------------|
| `-b <file>` | Bathymetry file (deprecated). |
| `-p <file>` | Polygon file to limit the working area (deprecated). |
| `-add <file>` | File to convert hydrographic level to mean level by **adding** its values (deprecated). |
| `-subtract <file>` | File to convert hydrographic level to mean level by **subtracting** its values (deprecated). |
| `-zmax <float>` | Maximum depth constraint for the output (deprecated). |
| `-zmin <float>` | Minimum depth constraint for the output (deprecated). |

---

## Examples

### **Basic Conversion (Comodo to NetCDF)**
Convert a `comodo`-formatted input file to NetCDF:
```bash
topo-antarctic -iF comodo -f netcdf -o antarctica_bathy input.nc
```

---

### **Convert Timmerman Format to GRD**
Convert a `timmerman`-formatted file to GRD format:
```bash
topo-antarctic -iF timmerman -f grd -o timmerman_bathy input_timmerman.nc
```

---

### **Invert Topography**
Invert the altitude/depth values (e.g., convert depths to elevations):
```bash
topo-antarctic -iF comodo -inv -o inverted_bathy input.nc
```

---

### **Smooth Bathymetry with Averaging**
Average the depth over a 3-node grid to smooth the bathymetry:
```bash
topo-antarctic -iF comodo -average 3 -o smoothed_bathy input.nc
```

---

### **Apply PROJ4 Projection**
Convert Cartesian coordinates to spherical using a PROJ4 string (e.g., for Antarctic Stereographic Projection):
```bash
topo-antarctic -iF comodo \
  --proj="+proj=stere +lat_0=-90 +lon_0=0 +lat_ts=-71 +x_0=0 +y_0=0 +ellps=WGS84" \
  -o projected_bathy input.nc
```

---

### **Compress NetCDF Output**
Save the output in NetCDF format with compression level 5:
```bash
topo-antarctic -iF comodo -f netcdf -deflate 5 -o compressed_bathy input.nc
```

---

### **Convert Albmap Format to GRD-Float**
Convert an `albmap`-formatted file to `grd-float` format:
```bash
topo-antarctic -iF albmap -f grd-float -o albmap_bathy input_albmap.nc
```

---

### **Combine Inversion and Projection**
Invert topography and apply a projection in one command:
```bash
topo-antarctic -iF comodo -inv \
  --proj="+proj=stere +lat_0=-90 +lon_0=0 +lat_ts=-71 +x_0=0 +y_0=0 +ellps=WGS84" \
  -o inverted_projected_bathy input.nc
```

---

## Environment Variables

`topo-antarctic` uses **OpenMP** for parallel processing. You can control the number of threads with the following environment variable:

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

**Example:**
```bash
OMP_NUM_THREADS=4 topo-antarctic -iF comodo -o output input.nc
```

---

## Notes

1. **Input File Requirements:**
   - **`comodo`**: Must include the `z` variable for bathymetry.
   - **`timmerman`**: Must include `bathy` (bathymetry) and `draft` (ice bottom position).
   - **`albmap`**: Must include `topg` (bathymetry) and `lsrf` (ice bottom position).

2. **Output Formats:**
   - **`netcdf`**: Standard NetCDF format. Supports compression (`-deflate`).
   - **`grd`**: Binary grid format (integer values).
   - **`grd-float`**: Binary grid format (floating-point values).

3. **Projection:**
   - The `--proj` option requires a valid **PROJ4 string** to define the coordinate transformation.
   - If no projection is specified, the tool assumes the input coordinates are already in the desired format.

4. **Averaging:**
   - The `-average` option smooths the bathymetry by averaging over a grid of `<int>` nodes around each point.
   - Useful for reducing noise in high-resolution datasets.

5. **Inversion:**
   - The `-inv` option multiplies all depth values by `-1`, effectively converting depths to elevations (or vice versa).

6. **Compression:**
   - The `-deflate` option only works with `netcdf`, `grd`, or `grd-float` output formats.
   - Higher compression levels (e.g., `5` or `9`) reduce file size but may increase processing time.

---

## See Also

- [PROJ4 Documentation](https://proj.org/) (for projection strings)
- [NetCDF Format](https://www.unidata.ucar.edu/software/netcdf/) (for output format details)
- [OpenMP](https://www.openmp.org/) (for parallel processing)