topo-fuse v3.2.3¶

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

Description¶

topo-fuse merges Digital Terrain Models (MNTs) into a quadtree file for enhanced performance and storage efficiency. It is designed to combine multiple bathymetry or topography datasets into a single, optimized structure.

Usage¶

topo-fuse [OPTIONS] input

Options¶

General Options¶

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

Input/Output Options¶

Option	Description
`input`	Input file (required).
`-b <file>`	Base bathymetry file to merge with.
`-l <file>`	ASCII file containing a list of input files (overrides the `input` argument).
`-iF <format>`	Input format: `grd`, `grd-float`, `netcdf`, or `xyz`. Default: `grd`.
`--proj=<params>`	Libproj4 projection parameters. Only effective if `-iF` is specified. Warning: May crash on mode 0 and 1 grids.
`-o <file>`	Output filename (NetCDF quadtree format).

Deprecated Options¶

Note: These options are no longer recommended and may be removed in future versions.

Option	Description
`-oF <format>`, `-f <format>`	Output format: `grd`, `grd-float`, `netcdf`, or `xyz`. Default: `grd`.
`-p <file>`	Selection polygon file.
`-inv`	Toggle depth/altitude on the final topography.
`-positive`	Toggle depth/altitude on the imported topography.
`-zmin <value>`	Minimum imported depth.
`-zmax <value>`	Maximum imported depth.
`-add <file>`	Path to a file to convert hydrographic level to mean level by adding its values.
`-subtract`, `-substract <file>`	Path to a file to convert hydrographic level to mean level by subtracting its values.
`-persistence`	Unused.
`-tag`	Unused.
`--masked-only`	Only import data on masked areas.

Examples¶

Basic Usage¶

Merge a single input file into a quadtree:

topo-fuse input.grd -o output.nc

Merge with a Base Bathymetry¶

Combine an input file with a base bathymetry:

topo-fuse input.grd -b base_bathymetry.grd -o output.nc

Use a List of Input Files¶

Merge multiple files listed in files.txt:

topo-fuse -l files.txt -o output.nc

Specify Input Format¶

Merge a NetCDF input file:

topo-fuse input.nc -iF netcdf -o output.nc

Apply Projection Parameters¶

Merge with a custom projection (e.g., UTM zone 33N):

topo-fuse input.grd --proj="+proj=utm +zone=33 +ellps=GRS80 +units=m" -o output.nc

Debug Mode¶

Enable debug verbose mode for troubleshooting:

topo-fuse input.grd -debug -o output.nc

Only Import Masked Areas¶

Import data only where the mask is applied:

topo-fuse input.grd --masked-only -o output.nc

Environment Variables¶

topo-fuse uses OpenMP (version 201511) for parallelization. Key environment variables:

Variable	Description
`OMP_NUM_THREADS`	Number of threads to use.
`OMP_SCHEDULE`	Runtime schedule type and chunk size.
`OMP_DYNAMIC`	Enable/disable dynamic thread adjustment.
`OMP_NESTED`	Enable/disable nested parallelism.

Example:

OMP_NUM_THREADS=6 topo-fuse input.grd -o output.nc

Note: If running on a busy machine, limit threads to the number of free CPUs to avoid performance degradation.

Notes¶

Input Files:
- Supported formats: grd, grd-float, netcdf, xyz.
- The -iF option is required for non-default formats.
Output:
- Default output format: NetCDF quadtree (-o option).
- Deprecated output formats (-oF, -f) are not recommended.
Projection:
- Use --proj= to specify custom projection parameters (requires -iF).
- Warning: Projections may not work with mode 0 and 1 grids.
Performance:
- For large datasets, use -debug to monitor progress and identify bottlenecks.
- Adjust OMP_NUM_THREADS based on available CPU resources.
Masking:
- Use --masked-only to import data only where the mask is applied.
Depth/Altitude:
- Use -inv or -positive to toggle depth/altitude values (deprecated).