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¶

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:

topo-antarctic -iF comodo -f netcdf -o antarctica_bathy input.nc

Convert Timmerman Format to GRD¶

Convert a timmerman-formatted file to GRD format:

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):

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:

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):

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:

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:

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:

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:

OMP_NUM_THREADS=4 topo-antarctic -iF comodo -o output input.nc

Notes¶

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).
Output Formats:
- netcdf: Standard NetCDF format. Supports compression (-deflate).
- grd: Binary grid format (integer values).
- grd-float: Binary grid format (floating-point values).
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.
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.
Inversion:
- The -inv option multiplies all depth values by -1, effectively converting depths to elevations (or vice versa).
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.