Metadata-Version: 2.4
Name: h5gears
Version: 0.3.0
Summary: A collection of tools for converting HDF5 model files to other mesh/model formats
Author-email: aaronchh <aaronhsu219@gmail.com>
License: MIT
Project-URL: Homepage, https://github.com/AaronOET/h5gears
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.20.0
Requires-Dist: h5py>=3.0.0
Provides-Extra: nc
Requires-Dist: netCDF4>=1.5.0; extra == "nc"
Provides-Extra: all
Requires-Dist: netCDF4>=1.5.0; extra == "all"
Dynamic: license-file

# H5GEARS

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

## Installation

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

Or from source:

```bash
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](#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:

```bash
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

```bash
# List all available commands
h5gears-info

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

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

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

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

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

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

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

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

### Python API

```python
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:

```bash
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:

```bash
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:

```bash
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`.
