H5GEARS

A collection of Python tools for converting HDF5 model/mesh files to other mesh/model formats.

Installation

pip install h5gears            # core: h52xyz, h5gears-info, h5gears doctor
pip install "h5gears[nc]"      # adds netCDF4, required by h52nc

Or from source:

pip install -e ".[nc]"

netCDF4 is an optional extra because it is a compiled extension linking native HDF5 and netCDF-C libraries. Installing the pip wheel on top of a conda-managed HDF5 stack is the usual cause of import failures — see Troubleshooting.

conda / miniforge environments

Install netCDF4 and h5py from conda-forge, then add h5gears with --no-deps so pip does not replace them with wheels:

conda install -c conda-forge netcdf4 h5py numpy
pip install --no-deps h5gears

Features

• h52nc: Convert an SRH-2D mesh file (.h5) to a Delft3D FM (D-Flow FM) UGRID net.nc mesh file — requires netCDF4
• h52xyz: Extract node coordinates from an SRH-2D mesh file (.h5) to a <MeshName>_nodes.csv file — needs only h5py
• h5gears doctor: Report on the installed HDF5 / netCDF stack and diagnose netCDF4 extension-load failures

Usage

Command-line

# List all available commands
h5gears-info

# Convert every mesh in a single SRH-2D mesh file
h52nc mesh.h5

# Convert every mesh in all matching files (glob expansion supported)
h52nc *.h5

# Convert only a specific mesh by name
h52nc mesh.h5 -n Mesh001

# Write outputs to a specific directory, including node elevation (z)
h52nc mesh.h5 -o out/ -d 3

# Extract node coordinates from every mesh in a single SRH-2D mesh file
h52xyz mesh.h5

# Extract only a specific mesh by name
h52xyz mesh.h5 -n Mesh001

# Write outputs to a specific directory, including node elevation (z)
h52xyz mesh.h5 -o out/ -d 3

# Check the HDF5 / netCDF stack
h5gears doctor
h5gears doctor --json

Python API

from h5gears import h52nc

# List the mesh names contained in an SRH-2D file
h52nc.list_meshes("mesh.h5")

# Convert every mesh in a file to net.nc, returning the output paths
h52nc.convert_file("mesh.h5", out_dir="out/", dim=2)

# Extract node coordinates from every mesh in a file to CSV, returning the output paths
from h5gears import h52xyz
h52xyz.convert_file("mesh.h5", out_dir="out/", dim=2)

Submodules are imported lazily, so import h5gears never pulls in netCDF4. Only h52nc.write_ugrid_net / h52nc.convert_file require it, and they raise a descriptive ImportError if it is unavailable.

Troubleshooting

ImportError: DLL load failed while importing _netCDF4: The specified procedure could not be found.

This is a native-library conflict, not an h5gears bug. netCDF4 ships a compiled extension linked against HDF5, netCDF-C and their dependencies (zlib, libcurl). The message means Windows found a dependent DLL but a symbol the extension expected was not in it — the signature of a version mismatch, almost always caused by mixing conda packages with pip wheels (each pip wheel of netCDF4 and h5py bundles its own HDF5). On Linux/macOS the same fault appears as undefined symbol.

Start with:

h5gears doctor

It reports the version and install channel of numpy, h5py, netCDF4 and cftime, the HDF5 and libnetcdf versions each links against, the full import error, and which layer is at fault. It exits 0 when clean, 1 when problems are found.

To repair a mixed environment, make the whole stack come from one channel:

pip uninstall -y netCDF4 h5py
conda install -c conda-forge netcdf4 h5py hdf5 libnetcdf --force-reinstall

Check for a version pin before force-reinstalling if other packages in the environment constrain netCDF4. If you would rather not disturb a working environment, build a clean one instead:

conda create -n d3dtools2 -c conda-forge python=3.12 netcdf4 h5py numpy
conda activate d3dtools2
pip install --no-deps h5gears

In the meantime, h52xyz, h5gears-info and h5gears doctor keep working — they do not touch netCDF4.

Notes

• h52nc reads mesh geometry from the 2DMeshModule group of SRH-2D HDF5 mesh files (node coordinates and element connectivity) and writes it out as a UGRID-style net.nc file compatible with Delft3D FM / D-Flow FM.
• h52xyz reads node coordinates from the same 2DMeshModule group and writes a <MeshName>_nodes.csv file with columns NodeID,x,y (or NodeID,x,y,z with -d 3), one row per 1-indexed node id.
• By default, every mesh found in an input file is converted; use -n/--name to restrict conversion to specific mesh names.
• Output files are written alongside each input file by default; use -o/--outdir to choose a different destination directory.
• Shared HDF5-reading and path helpers live in h5gears._common, which depends only on h5py and numpy.