topo-format v3.2.3¶

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

Description¶

topo-format is a tool designed to predict tides for PEPS images. It processes input files in various formats, applies transformations (scaling, offset, flipping, etc.), and saves the output in the desired format.

Usage¶

topo-format [OPTIONS]

Options¶

General Options¶

Option	Description
`--help`, `-h`	Display help and exit.
`-info`	Print mapping info of the input file and exit.

Input/Output Options¶

Option	Description
`-iF <fmt>`	Input format. One of: `NETCDF`, `COMODO` (equivalent to `NETCDF`), `GLOBE`, `GRD`, `ASCII`, `GIS`, `SLIM`, `GEOTIFF`, or `DTU`.
`-oF <fmt>`, `-f <fmt>`	Output format. One of: `grd`, `grd-float`, `netcdf`, `xyz`, or `gis`.
`-iV <name>`, `-v <name>`	Input variable name (only useful when input format is `NETCDF` or `COMODO`).
`-oV <name>`	Output variable name. Default: `bathymetry`.
`-o <name>`	Root name for the output file. Default: `out`.

Processing Options¶

Option	Description
`-c <name>`	Variable name to process (multiple uses possible).
`--cartesian-mapping <grid>`	Cartesian grid settings in the format `[xmin:dx:xmax;ymin:dy:ymax]` (for handling poorly geo-referenced rasters).
`--proj=<proj4_string>`	PROJ4 option string to convert Cartesian coordinates to spherical.
`-flip`	Flip the data north-south.
`-zmax <float>`	Maximum value to constrain the output.
`-offset <float>`	Add an offset to the field data (applied after scaling).
`-scale <float>`	Apply a scale factor to the field data.
`-inv`	Equivalent to `-scale -1`.
`-add <file>`	File to convert hydrographic levels to mean levels by adding its values.
`-substract <file>`	File to convert hydrographic levels to mean levels by subtracting its values.
`--time <date>`	Date in the format `YYYY-MM-DD HH:MM:SS`. Activates saving with a time dimension.
`-max-valid <float>`	Maximum depth above which the output will be masked.
`-mask <float>`	Mask value to override the input mask (required for `GEOTIFF` input format).
`-deflate`	NetCDF compression level. Default: none. Only useful for `grd`, `grd-float`, or `netcdf` output formats.

Examples¶

Convert a NetCDF File to GRD Format¶

topo-format -iF NETCDF -oF grd -iV elevation -o output_root input.nc

Apply Scaling and Offset¶

topo-format -iF NETCDF -oF netcdf -scale 10.0 -offset 5.0 -o scaled_output input.nc

Flip Data North-South¶

topo-format -iF GRD -flip -o flipped_output input.grd

Convert Hydrographic Levels to Mean Levels¶

topo-format -iF NETCDF -add mean_level.nc -o adjusted_output input.nc

Use Cartesian Mapping¶

topo-format -iF GEOTIFF --cartesian-mapping "[0:1:100;0:1:100]" -o cartesian_output input.tif

Apply PROJ4 Projection¶

topo-format -iF GRD --proj="merc ellps=WGS84 lon_0=0E lat_ts=46N" -o projected_output input.grd

Save Output with Time Dimension¶

topo-format -iF NETCDF --time "2026-08-04 12:00:00" -oF netcdf -o time_output input.nc

Mask Output Based on Depth¶

topo-format -iF NETCDF -max-valid 200.0 -o masked_output input.nc

Convert to NetCDF with Compression¶

topo-format -iF GRD -oF netcdf -deflate 5 -o compressed_output input.grd

Environment Variables¶

topo-format does not rely on specific environment variables. However, if you are using PROJ4 for coordinate transformations, ensure the PROJ_LIB environment variable is set to the directory containing PROJ4 data files.

Notes¶

Input Formats:

Supported formats: NETCDF, COMODO, GLOBE, GRD, ASCII, GIS, SLIM, GEOTIFF, DTU.
For NETCDF or COMODO input, specify the variable name using -iV or -v.

Output Formats:

Supported formats: grd, grd-float, netcdf, xyz, gis.
Default output variable name: bathymetry.

Masking:

Use -mask to override the input mask (required for GEOTIFF input).
Use -max-valid to mask depths above a specified threshold.

Coordinate Transformations:

Use --proj to specify a PROJ4 string for converting Cartesian coordinates to spherical.
Use --cartesian-mapping to define a Cartesian grid for poorly geo-referenced rasters.

Compression:

Use -deflate to enable NetCDF compression (only for grd, grd-float, or netcdf output).

Time Dimension:

Use --time to include a time dimension in the output (format: YYYY-MM-DD HH:MM:SS).