h5gears 0.1.0__tar.gz

h5gears-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Aaron Hsu
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

h5gears-0.1.0/MANIFEST.in

@@ -0,0 +1,3 @@
+include LICENSE
+include README.md
+include requirements.txt

h5gears-0.1.0/PKG-INFO

@@ -0,0 +1,76 @@
+Metadata-Version: 2.4
+Name: h5gears
+Version: 0.1.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
+Requires-Dist: netCDF4>=1.5.0
+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
+```
+
+Or from source:
+
+```bash
+pip install -e .
+```
+
+## Features
+
+- **h52nc**: Convert an SRH-2D mesh file (`.h5`) to a Delft3D FM (D-Flow FM) UGRID `net.nc` mesh file
+
+## 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
+```
+
+### 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)
+```
+
+## 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.
+- 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.

h5gears-0.1.0/README.md

@@ -0,0 +1,58 @@
+# H5GEARS
+
+A collection of Python tools for converting HDF5 model/mesh files to other mesh/model formats.
+
+## Installation
+
+```bash
+pip install h5gears
+```
+
+Or from source:
+
+```bash
+pip install -e .
+```
+
+## Features
+
+- **h52nc**: Convert an SRH-2D mesh file (`.h5`) to a Delft3D FM (D-Flow FM) UGRID `net.nc` mesh file
+
+## 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
+```
+
+### 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)
+```
+
+## 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.
+- 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.

h5gears-0.1.0/h5gears/__init__.py

@@ -0,0 +1,15 @@
+"""
+H5GEARS - A collection of tools for converting HDF5 model files to other
+mesh/model formats.
+"""
+
+__version__ = '0.1.0'
+
+__all__ = [
+    'h52nc',
+    'describe',
+]
+
+from . import h52nc
+from . import describe
+from . import cli

h5gears-0.1.0/h5gears/cli.py

@@ -0,0 +1,44 @@
+#!/usr/bin/env python
+"""
+Top-level `h5gears` command. Running `h5gears -h` (or with no arguments)
+prints the same information shown by `h5gears-info`. Running `h5gears -v`
+prints the installed h5gears version.
+"""
+
+import sys
+
+from . import __version__, describe
+
+
+def _print_info(tool=None):
+    argv_backup = sys.argv
+    try:
+        sys.argv = ['h5gears-info'] + ([tool] if tool else [])
+        describe.main()
+    finally:
+        sys.argv = argv_backup
+
+
+def main():
+    args = sys.argv[1:]
+
+    if not args or args[0] in ('-h', '--help'):
+        _print_info()
+        return
+
+    if args[0] in ('-v', '--version'):
+        print(f"h5gears {__version__}")
+        return
+
+    tool = args[0]
+    if tool in describe.TOOL_DESCRIPTIONS:
+        _print_info(tool)
+        return
+
+    print(f"Unknown option or tool: {tool}", file=sys.stderr)
+    print("Run 'h5gears -h' to see available tools.", file=sys.stderr)
+    sys.exit(2)
+
+
+if __name__ == "__main__":
+    main()

h5gears-0.1.0/h5gears/describe.py

@@ -0,0 +1,53 @@
+#!/usr/bin/env python
+"""
+Command-line utility to display descriptions of h5gears functionality.
+"""
+
+import argparse
+from textwrap import dedent
+
+TOOL_DESCRIPTIONS = {
+    'h52nc': """
+        Convert SRH-2D HDF5 mesh files (*.h5) to Delft3D FM (D-Flow FM)
+        UGRID net.nc files.
+
+        This tool reads the node coordinates and element connectivity of
+        every mesh in a SRH-2D '2DMeshModule' HDF5 file (read-only, no
+        modification) and writes one UGRID net.nc file per mesh.
+
+        Examples:
+            h52nc -i mesh.h5               # Convert every mesh in mesh.h5
+            h52nc -i *.h5                  # Convert every mesh in all matches
+            h52nc -i mesh.h5 -n Mesh001     # Convert only mesh 'Mesh001'
+            h52nc -i mesh.h5 -o out/ -d 3  # Write to out/, include elevation
+    """,
+}
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        prog='h5gears-info',
+        description='Display descriptions of h5gears commands',
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+    )
+    parser.add_argument(
+        'tool',
+        nargs='?',
+        choices=list(TOOL_DESCRIPTIONS.keys()),
+        help='Tool name to describe (omit to list all tools)',
+    )
+    args = parser.parse_args()
+
+    if args.tool:
+        print(f"\n--- {args.tool} ---")
+        print(dedent(TOOL_DESCRIPTIONS[args.tool]))
+    else:
+        print("\nH5GEARS — HDF5 mesh conversion commands\n")
+        for tool, desc in TOOL_DESCRIPTIONS.items():
+            first_line = dedent(desc).strip().splitlines()[0]
+            print(f"  {tool:<14} {first_line}")
+        print("\nRun 'h5gears-info <tool>' for details on a specific command.")
+
+
+if __name__ == "__main__":
+    main()

h5gears-0.1.0/h5gears/h52nc.py

@@ -0,0 +1,295 @@
+#!/usr/bin/env python3
+"""
+h52nc - Convert SRH-2D HDF5 mesh files (*.h5) to Delft3D FM (D-Flow FM)
+UGRID net.nc files.
+"""
+
+import argparse
+import glob
+import os
+import sys
+
+import h5py
+import numpy as np
+import netCDF4 as nc
+
+
+def list_meshes(h5_path):
+    """
+    List the mesh names contained in an SRH-2D .h5 mesh file.
+
+    Args:
+        h5_path (str): Path to the SRH-2D mesh file
+
+    Returns:
+        list[str]: Names of the meshes found under '2DMeshModule'
+    """
+    with h5py.File(h5_path, 'r') as f:
+        if '2DMeshModule' not in f:
+            return []
+        return list(f['2DMeshModule'].keys())
+
+
+def read_mesh(h5_path, mesh_name):
+    """
+    Read node coordinates and element connectivity for one mesh.
+
+    Args:
+        h5_path (str): Path to the SRH-2D mesh file
+        mesh_name (str): Mesh name within the file (e.g. 'Mesh001')
+
+    Returns:
+        tuple: (x, y, z, links)
+            x, y, z (np.ndarray): 1-D node coordinate arrays, one entry per
+                node, ordered to match the file's 1-indexed node ids.
+            links (np.ndarray): (n_links, 2) array of unique, 1-indexed
+                node-id pairs describing each element boundary edge.
+    """
+    with h5py.File(h5_path, 'r') as f:
+        mesh = f['2DMeshModule'][mesh_name]
+        node_locs = mesh['Nodes']['NodeLocs'][:]
+        node_ids = mesh['Elements']['Nodeids'][:]
+
+    x = node_locs[:, 0]
+    y = node_locs[:, 1]
+    z = node_locs[:, 2] if node_locs.shape[1] > 2 else np.zeros_like(x)
+
+    links = _extract_links(node_ids)
+    return x, y, z, links
+
+
+def _extract_links(node_ids):
+    """
+    Derive unique, undirected element-boundary links from an element/node-id
+    array.
+
+    Each row of `node_ids` lists the corner node ids of one element (SRH-2D
+    elements are triangles or quadrilaterals); unused corners in a mixed
+    tri/quad array are marked with -1. Node ids are 1-indexed, matching the
+    convention used by D-Flow FM's `NetLink` (start_index=1).
+
+    Args:
+        node_ids (np.ndarray): (n_elements, 3) or (n_elements, 4) array of
+            1-indexed node ids bounding each element
+
+    Returns:
+        np.ndarray: (n_links, 2) array of unique 1-indexed node-id pairs
+    """
+    links = []
+    for elem in node_ids:
+        corners = [int(node) for node in elem if node != -1]
+        n = len(corners)
+        for i in range(n):
+            links.append((corners[i], corners[(i + 1) % n]))
+
+    links = np.array(links, dtype=np.int32)
+    links_sorted = np.sort(links, axis=1)
+    return np.unique(links_sorted, axis=0)
+
+
+def write_ugrid_net(x, y, links, out_path, z=None):
+    """
+    Write a D-Flow FM UGRID net.nc file from node coordinates and links.
+
+    Args:
+        x, y (np.ndarray): 1-D node coordinate arrays
+        links (np.ndarray): (n_links, 2) array of 1-indexed node-id pairs
+        out_path (str): Output .nc file path
+        z (np.ndarray, optional): 1-D node elevation array; included as
+            NetNode_z when provided
+
+    Returns:
+        str: The output file path
+    """
+    with nc.Dataset(out_path, 'w', format='NETCDF4') as ds:
+        ds.createDimension('nNetNode', len(x))
+        ds.createDimension('nNetLink', len(links))
+        ds.createDimension('nNetLinkPts', 2)
+
+        var_x = ds.createVariable('NetNode_x', 'f8', ('nNetNode',))
+        var_x.axis = 'X'
+        var_x.long_name = 'x-coordinate in Cartesian system'
+        var_x.units = 'metre'
+        var_x.standard_name = 'projection_x_coordinate'
+        var_x[:] = x
+
+        var_y = ds.createVariable('NetNode_y', 'f8', ('nNetNode',))
+        var_y.axis = 'Y'
+        var_y.long_name = 'y-coordinate in Cartesian system'
+        var_y.units = 'metre'
+        var_y.standard_name = 'projection_y_coordinate'
+        var_y[:] = y
+
+        if z is not None:
+            var_z = ds.createVariable('NetNode_z', 'f8', ('nNetNode',))
+            var_z.long_name = 'z-coordinate in Cartesian system'
+            var_z.units = 'metre'
+            var_z.standard_name = 'sea_floor_depth'
+            var_z[:] = z
+
+        var_link_type = ds.createVariable('NetLinkType', 'i4', ('nNetLink',))
+        var_link_type.long_name = 'type of netlink'
+        var_link_type[:] = 0
+
+        var_link = ds.createVariable('NetLink', 'i4', ('nNetLink', 'nNetLinkPts'))
+        var_link.long_name = 'link between two netnodes'
+        var_link.start_index = 1
+        var_link[:] = links
+
+    return out_path
+
+
+def convert_file(h5_path, mesh_names=None, out_dir=None, dim=2):
+    """
+    Convert one SRH-2D .h5 mesh file to one net.nc file per mesh.
+
+    Args:
+        h5_path (str): Path to the SRH-2D mesh file
+        mesh_names (list[str], optional): Restrict conversion to these mesh
+            names (default: convert every mesh found in the file)
+        out_dir (str, optional): Directory to write net.nc files to
+            (default: alongside the input file)
+        dim (int): 2 for x/y only, 3 to also write node elevation (z)
+
+    Returns:
+        list[str]: Paths of the net.nc files written
+    """
+    available = list_meshes(h5_path)
+    if not available:
+        raise ValueError(f"No '2DMeshModule' meshes found in {h5_path}")
+
+    if mesh_names:
+        missing = [m for m in mesh_names if m not in available]
+        if missing:
+            raise ValueError(
+                f"Mesh(es) {missing} not found in {h5_path}; "
+                f"available: {available}"
+            )
+        targets = mesh_names
+    else:
+        targets = available
+
+    base = os.path.splitext(os.path.basename(h5_path))[0]
+    out_dir = out_dir or os.path.dirname(os.path.abspath(h5_path))
+
+    outputs = []
+    for mesh_name in targets:
+        x, y, z, links = read_mesh(h5_path, mesh_name)
+
+        if len(available) > 1 or mesh_names:
+            out_name = f"{base}_{mesh_name}_net.nc"
+        else:
+            out_name = f"{base}_net.nc"
+        out_path = os.path.join(out_dir, out_name)
+
+        write_ugrid_net(x, y, links, out_path, z=z if dim == 3 else None)
+        outputs.append(out_path)
+        print(f"  {mesh_name}: {len(x)} nodes, {len(links)} links -> {out_path}")
+
+    return outputs
+
+
+def _expand_inputs(patterns):
+    """Expand glob patterns / literal paths into a de-duplicated file list."""
+    files = []
+    for pattern in patterns:
+        matches = sorted(glob.glob(pattern))
+        if matches:
+            files.extend(matches)
+        elif os.path.exists(pattern):
+            files.append(pattern)
+        else:
+            print(f"Warning: no file matches '{pattern}'", file=sys.stderr)
+
+    seen = set()
+    unique = []
+    for f in files:
+        if f not in seen:
+            seen.add(f)
+            unique.append(f)
+    return unique
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        prog='h52nc',
+        description=(
+            'Convert SRH-2D HDF5 mesh files (*.h5) to Delft3D FM '
+            '(D-Flow FM) UGRID net.nc files'
+        ),
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog="""
+Examples:
+  h52nc -i mesh.h5               # Convert every mesh in mesh.h5
+  h52nc -i *.h5                  # Convert every mesh in all matching files
+  h52nc -i mesh.h5 -n Mesh001     # Convert only mesh 'Mesh001'
+  h52nc -i mesh.h5 -o out/ -d 3  # Write to out/, include node elevation
+        """
+    )
+    parser.add_argument(
+        '-i', '--input',
+        dest='inputs',
+        nargs='+',
+        required=True,
+        metavar='FILE',
+        help='One or more SRH-2D .h5 mesh files (glob patterns supported)',
+    )
+    parser.add_argument(
+        '-n', '--name',
+        dest='mesh_names',
+        nargs='+',
+        default=None,
+        metavar='MESH',
+        help='Restrict conversion to specific mesh name(s) '
+             '(default: convert every mesh found)',
+    )
+    parser.add_argument(
+        '-o', '--outdir',
+        dest='outdir',
+        default=None,
+        metavar='DIR',
+        help='Output directory for net.nc files '
+             '(default: alongside each input file)',
+    )
+    parser.add_argument(
+        '-d', '--dim',
+        dest='dim',
+        type=int,
+        choices=[2, 3],
+        default=2,
+        help='Mesh dimension: 2 (x, y only) or 3 (also write node '
+             'elevation z) (default: 2)',
+    )
+
+    args = parser.parse_args()
+
+    files = _expand_inputs(args.inputs)
+    if not files:
+        print("No input .h5 files found.", file=sys.stderr)
+        sys.exit(1)
+
+    if args.outdir:
+        os.makedirs(args.outdir, exist_ok=True)
+
+    print(f"h52nc: converting {len(files)} file(s)")
+    print("=" * 60)
+
+    exit_code = 0
+    for h5_path in files:
+        print(f"Processing: {h5_path}")
+        try:
+            convert_file(
+                h5_path,
+                mesh_names=args.mesh_names,
+                out_dir=args.outdir,
+                dim=args.dim,
+            )
+        except Exception as exc:
+            print(f"  Error: {exc}", file=sys.stderr)
+            exit_code = 1
+
+    sys.exit(exit_code)
+
+
+if __name__ == "__main__":
+    main()

h5gears-0.1.0/h5gears.egg-info/PKG-INFO

@@ -0,0 +1,76 @@
+Metadata-Version: 2.4
+Name: h5gears
+Version: 0.1.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
+Requires-Dist: netCDF4>=1.5.0
+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
+```
+
+Or from source:
+
+```bash
+pip install -e .
+```
+
+## Features
+
+- **h52nc**: Convert an SRH-2D mesh file (`.h5`) to a Delft3D FM (D-Flow FM) UGRID `net.nc` mesh file
+
+## 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
+```
+
+### 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)
+```
+
+## 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.
+- 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.

h5gears-0.1.0/h5gears.egg-info/SOURCES.txt

@@ -0,0 +1,15 @@
+LICENSE
+MANIFEST.in
+README.md
+pyproject.toml
+requirements.txt
+h5gears/__init__.py
+h5gears/cli.py
+h5gears/describe.py
+h5gears/h52nc.py
+h5gears.egg-info/PKG-INFO
+h5gears.egg-info/SOURCES.txt
+h5gears.egg-info/dependency_links.txt
+h5gears.egg-info/entry_points.txt
+h5gears.egg-info/requires.txt
+h5gears.egg-info/top_level.txt

h5gears-0.1.0/h5gears.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

h5gears-0.1.0/h5gears.egg-info/entry_points.txt

@@ -0,0 +1,4 @@
+[console_scripts]
+h52nc = h5gears.h52nc:main
+h5gears = h5gears.cli:main
+h5gears-info = h5gears.describe:main

h5gears-0.1.0/h5gears.egg-info/requires.txt

@@ -0,0 +1,3 @@
+numpy>=1.20.0
+h5py>=3.0.0
+netCDF4>=1.5.0

h5gears-0.1.0/h5gears.egg-info/top_level.txt

@@ -0,0 +1 @@
+h5gears

h5gears-0.1.0/pyproject.toml

@@ -0,0 +1,35 @@
+[build-system]
+requires = ["setuptools>=61.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "h5gears"
+version = "0.1.0"
+authors = [
+    { name = "aaronchh", email = "aaronhsu219@gmail.com" },
+]
+description = "A collection of tools for converting HDF5 model files to other mesh/model formats"
+readme = "README.md"
+license = { text = "MIT" }
+requires-python = ">=3.8"
+dependencies = [
+    "numpy>=1.20.0",
+    "h5py>=3.0.0",
+    "netCDF4>=1.5.0",
+]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+]
+
+[project.urls]
+Homepage = "https://github.com/AaronOET/h5gears"
+
+[tool.setuptools]
+packages = ["h5gears"]
+
+[project.scripts]
+h5gears = "h5gears.cli:main"
+h5gears-info = "h5gears.describe:main"
+h52nc = "h5gears.h52nc:main"

h5gears-0.1.0/requirements.txt

@@ -0,0 +1,3 @@
+numpy>=1.20.0
+h5py>=3.0.0
+netCDF4>=1.5.0

h5gears-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+