HEC-RAS

terrio reads the HDF5 files of HEC-RAS, the US Army Corps of Engineers' river and floodplain hydraulics model, as vector layers:

A file gives its 2D mesh (cells, cell centres, faces, face points, flow area perimeters), its 1D geometry (cross sections, rivers, storage areas, structures), its 2D features (boundary-condition lines, breaklines, refinement regions, reference lines and points), its pump stations and pipe networks, each with every attribute column HEC-RAS stored, and the results HEC-RAS stored, joined to those features on request. The driver only reads: it does not run HEC-RAS, write HEC-RAS files, or read the project and plan text files (.prj, .p##, .g##).

terrio info BaldEagleDamBrk.p18.all2d.hdf
terrio convert BaldEagleDamBrk.p18.all2d.hdf cells.fgb -l mesh_cells --oo "CELL_SUMMARIES=Maximum Water Surface"

Supported versions

The driver is tested on files written by HEC-RAS 7.0.1: the comparison with h5py and the real-data tests use 7.0.1 files only. Files from older versions (5.x, 6.x) are read where their layout is the same, best effort: a layout the engine does not support is refused with an error, never read as empty or approximate data.

Detection

A file is a HEC-RAS file when it has an HDF5 signature and its root File Type attribute is HEC-RAS Geometry or HEC-RAS Results. The extension decides nothing: HEC-RAS files share .hdf and .h5 with other HDF5 files. Every other file keeps its driver: NetCDF-4 files, HDF5 files without a File Type, and HEC's own terrain and land-cover files (File Type HEC Terrain, HEC Land Cover) are not claimed.

File Type only says that a file is HEC-RAS's, not which kind: plans written before 6.4 can say HEC-RAS Geometry, and geometry files written by 6.4 and later say HEC-RAS Results. The layers come from what the file stores. terrio::open, open_vector, terrio info and terrio convert read HEC-RAS files as vector layers; open_raster (and open_raster_bytes) still reads them as HDF5 rasters, as before.

Layers

A default open reads every layer the file stores. A layer the engine refuses there (an unsupported layout, or a table the file lacks, such as the ghost-cell count of HEC-RAS 5.0 files) is left out with a warning (a UserWarning in Python), unless an open option asks for something of that layer (a join, MESHES): then the refusal fails the open, and an option for layers the file does not store at all (XS_SUMMARIES on a file without cross sections, say) is an error naming the option. Damaged data and I/O errors always fail the open. A layer named with -l (layers) must read, or the open fails with the engine's refusal.

2D mesh

• mesh_name is the 2D flow area's name; cell_id, face_id and face_point_id are the stored row indices, which repeat across meshes.
• Cells are the engine's polygons: rings run clockwise from the first listed face. Cells HEC-RAS does not draw (fewer than three faces, such as ghost cells) are left out of mesh_cells; mesh_cell_points has every stored cell, with is_ghost true for the rows at and above the 2D flow area's physical cell count.
• Faces are polylines from the start face point through the stored perimeter vertices to the end face point.
• Face points are the mesh corners. is_perimeter is the stored FacePoints Is Perimeter integer, unconverted (HEC-RAS writes -1 on the perimeter and 0 inside), and elevation the stored FacePoints Elevation (null for a mesh that stores none).
• Perimeters are the stored Perimeter polygons, listed when every 2D flow area stores one. The 2D flow area table follows: name, locked, mann, multiple_face_mann_n, composite_lc, cell_vol_tol, cell_min_area_fraction, face_profile_tol, face_area_tol, face_conv_ratio, laminar_depth, min_face_length_ratio, spacing_dx, spacing_dy, shift_dx, shift_dy, cell_count (HEC-RAS 7.0.1; files without the table give mesh_name only).

1D, 2D and network features

Each feature has source_row, its row in the stored attribute table, then every stored column of that table as a field named after it (lower case, other characters as _: River Name is river_name, SA-2D is sa_2d), with its stored type (text, integer or float). The columns are the file's own; those HEC-RAS 7.0.1 writes are:

A line with several parts is a MultiLineString. A polygon feature with several parts is refused, because which parts are holes is not a proven layout.

Units

Values are the stored numbers, unconverted: f32 values are widened to f64 exactly, and nothing is rescaled. Coordinates are in the units of the file's CRS. Lengths, elevations, flows and velocities are in the model's unit system, the root Units System attribute (US Customary: feet, cubic feet per second; SI Units: metres, cubic metres per second). Times of maxima and minima are the stored days since the start of the simulation. The unit text HEC-RAS stores with each result (ft, cfs, ...) is reported on the terrio::hecras API (SummaryField::units, JoinedField::units, CrossSectionField::units, SeriesField::units), because vector layers have no metadata slot; HecRasHdf::units_system and HecRasHdf::file_attributes give the stored text of the root attributes.

Results

Stored results join to the layers through open options (--oo KEY=VALUE on the command line, options= in Python, openOptions in JavaScript, VectorOpenOptions::set in Rust). Every joined value is a stored number, joined by the engine's element or feature identity. Asking for a value the file does not store is an error, never an empty field. The options are checked before anything is read: an incomplete request (a series option without TIME_STEP, XS_RESULTS without TIME_STEP or XS_PROFILE) is an error whichever layers are read. With no layer named, an option whose layers the file does not store is an error; with layers named, options for the other layers are not looked up. Lists are comma-separated stored names, so a stored name that contains a comma (a 2D flow area or structure named Area, A) cannot be given. A key given twice keeps its last value.

Geometry and hydraulic values are the stored data. The only values not read as stored are the optional reductions (CELL_MAXIMUM, CELL_MINIMUM, FACE_MAXIMUM, FACE_MINIMUM): the engine's exact maximum or minimum of a stored series over its stored rows, with the row it was found at. No quantity is derived: depth, for example, is joined only where HEC-RAS stored it (HEC-RAS 5.0 plans store a cell Depth series), never computed from water surface and terrain; Summary Output maxima are HEC-RAS's own.

CRS

The CRS is the root Projection attribute, the WKT HEC-RAS stores, attached to every layer as that text. The driver sets no EPSG code and skips the EPSG re-identification terrio applies to other drivers' WKT (a shapefile's .prj, say), so the layer keeps exactly what the modeller set. terrio's CRS engine can still recognize the WKT when it parses it: terrio info shows EPSG:2271 (NAD83 / Pennsylvania North (ftUS)) for the Bald Eagle Creek files, and writers that store an authority code may store that one.

A file without a projection (many geometry files) gives layers without a CRS; give one with --s-srs on terrio convert. Malformed, conflicting, unsupported or corrupt projection evidence is an error (Error::Crs), never a guess. A project's .rasmap and .prj projection files are not read.

Enabling the driver

The driver is the hecras Cargo feature, part of the default features; it implies netcdf-hdf5.

• Rust: terrio = "0.5" includes it. With default-features = false, add it: features = ["hecras"]. The terrio::hecras module gives the typed API.
• Command line: the terrio binary and cargo install terrio-cli include it; terrio formats lists HECRAS.
• Python: the terrio wheels include it (pip install terrio).
• JavaScript: the full module includes it; the core module does not.

Examples

These read files of the HEC-RAS 7.0.1 golden corpus, ras-hdf-test-corpus (release v1.0.1, smoke profile), whose files come from HEC's public example projects, run in HEC-RAS 7.0.1: BaldEagleDamBrk.p18.all2d.hdf (Bald Eagle Creek dam break, 2D), BaldEagle.p02.hdf (Bald Eagle Creek, 1D steady, eight profiles) and DavisStormSystem.p02.hdf (Davis storm sewer, pipe network).

terrio info BaldEagleDamBrk.p18.all2d.hdf
terrio info BaldEagleDamBrk.p18.all2d.hdf -l mesh_cells --oo "CELL_SUMMARIES=Maximum Water Surface"

# 2D cells with the maximum water surface and its time, as GeoPackage
terrio convert BaldEagleDamBrk.p18.all2d.hdf cells.gpkg -l mesh_cells --oo "CELL_SUMMARIES=Maximum Water Surface"

# Cross sections with their station-elevation tables and the 100-year water surface (steady profile 7)
terrio convert BaldEagle.p02.hdf xs.geojson -l cross_sections --oo XS_GEOMETRY=STATION_ELEVATION --oo "XS_RESULTS=Water Surface" --oo XS_PROFILE=7

# The storm sewer network
terrio convert DavisStormSystem.p02.hdf pipes.fgb -l pipe_conduits

import terrio

ds = terrio.open_vector(
    "BaldEagleDamBrk.p18.all2d.hdf",
    layers=["mesh_cells", "mesh_faces"],
    options={"CELL_SUMMARIES": "Maximum Water Surface", "FACE_SUMMARIES": "Maximum Face Velocity"},
)
cells = ds["mesh_cells"].to_geopandas()
print(cells[["mesh_name", "cell_id", "maximum_water_surface", "maximum_water_surface_time"]].head())

```rust,no_run use terrio::hecras::{HecRasHdf, MeshOptions};

// Through terrio's generic API, with open options let mut options = terrio::VectorOpenOptions { layers: vec!["mesh_cells".into()], ..Default::default() }; options.set("CELL_SUMMARIES", "Maximum Water Surface")?; let ds = terrio::open_vector("BaldEagleDamBrk.p18.all2d.hdf", &options)?; terrio::write_vector(&ds.layers, "cells.fgb", &Default::default())?;

// Or the typed API, with the reports of each read (units, omitted cells, time rows) let hdf = HecRasHdf::open("BaldEagleDamBrk.p18.all2d.hdf")?; let cells = hdf.mesh_cells(&MeshOptions::default().with_summary("Maximum Water Surface"))?; println!("{} cells, {} omitted, units {:?}", cells.layer.len(), cells.omitted.len(), cells.summaries[0].units);

Ok::<(), terrio::Error>(())

```js
const ds = terrio.openVector(bytes, "BaldEagleDamBrk.p18.all2d.hdf", {
  layers: ["mesh_cells"],
  openOptions: { CELL_SUMMARIES: "Maximum Water Surface" },
});

Refusals and errors

A read the engine cannot prove exact is refused: it is an error, never an empty layer, a partial result or a guessed value. Refusals keep the engine's stable spelling at the start of the message (HEC-RAS unsupported(identity_layout): ...), and map to terrio's errors:

A default open leaves a refused layer out with a warning (Unsupported or InvalidArgument); naming the layer shows the refusal. Damaged data and I/O errors always fail the open.

Limitations

Not read, on purpose:

• Project and plan text files (.prj, .p##, .g##, .u##, .rasmap), HEC-RAS execution and editing, and RAS Mapper's raster outputs (depth and velocity grids).
• Derived values: depth where only water surface is stored, maxima of structure series.
• Storage-area results (the engine refuses their column order).
• Multi-part polygons with holes (unproven layout).
• Structures stored without a centerline (an attribute row with no Centerline datasets, such as some lateral structures): there is no geometry to draw.
• 2D flow areas stored as outlines only, with no computed mesh: the mesh layers are listed but refused.
• Calibration regions (no tested file stores one), pipe network cells (Geometry/Pipe Networks), cross-section interpolation surfaces, bridge and culvert profile and coefficient tables, and hydraulic property tables: model tables rather than feature layers.

In memory and in WebAssembly

terrio::memory::open_bytes, open_vector_bytes, Python's open_bytes and the JavaScript package's open and openVector read HEC-RAS files from bytes (natively the bytes are spilled to a temporary file; in WebAssembly the engine reads them in memory). Limits:

• The whole file is held in memory while it is open, and opening needs about twice its size for a moment (detection and the root-attribute budget read the file's metadata from a copy).
• The wasm32 module's memory is 4 GiB in all, so plan files approaching that size cannot be read there; native builds have no such limit.
• The byte budgets (METADATA_MAX_BYTES, MAX_BYTES) apply as for files: root attributes and datasets above them are refused before they are decoded.

Range reads (HTTP, S3) are not supported yet.

How it works

The driver is a thin adapter over ras-commander-fast-hdf, the read-only HEC-RAS HDF engine of the ras-commander Python library (MIT). The engine owns every HEC-RAS rule: the HDF layouts, mesh, cell and cross-section identities, polygon ring order, CRS evidence, units and refusals. The driver translates its values into terrio layers, fields and errors. Attributes are read without h5py: compound Attributes tables column by column with their stored types, fixed-length strings decoded as h5py decodes them (padding removed, nothing else trimmed), and root attributes (File Type, File Version, Units System, Projection) through HecRasHdf::file_attributes.

terrio and the engine use the same hdf5-reader 0.10.1 from crates.io (roteiro-gis/netcdf-rust), so a build with hecras compiles one HDF5 reader (cargo tree -d -e normal -p terrio lists the same duplicate crates with and without hecras, none of them an HDF5 or NetCDF crate).

Build and size

hecras is a default feature, as every terrio driver is. Over the other default features it adds one crate, the engine (ras-commander-fast-hdf 0.2.4, with the features hdf, mesh and results); its other dependencies, including the HDF5 reader, are already terrio's. Measured on Windows x86-64 with Rust 1.99.1, release profile (2026-10-28):

To reproduce them from a checkout:

# Command-line binary, with hecras (the defaults), then without it
cargo build --release -p terrio-cli
sed -i 's/"libzstd", "hecras"\]/"libzstd"]/' crates/terrio/Cargo.toml
CARGO_TARGET_DIR=target-without cargo build --release -p terrio-cli
git checkout -- crates/terrio/Cargo.toml

# JavaScript module, without and with hecras
F=cad,core,parquet,avif,netcdf-hdf5,osm,jp2,pointcloud,zarr,grib
cargo build --release -p terrio-js --target wasm32-unknown-unknown --no-default-features --features $F
cargo build --release -p terrio-js --target wasm32-unknown-unknown --no-default-features --features $F,hecras

Licence. The engine is MIT; its crate licence is MIT AND ISC because it vendors freestiler-core, whose supercluster/KDBush port is ISC. That code compiles only under the engine's python feature, which terrio does not enable, so no ISC-licensed code is compiled into terrio. Cargo's licence metadata is per crate, so cargo about (LICENSE-THIRD-PARTY.md) still lists ISC for the engine.

Testing

cargo test -p terrio --test hecras_driver --test hecras_results --test hecras_synthetic
python scripts/compare_hecras_with_h5py.py <corpus>/fixtures   # the 7.0.1 comparison with h5py

• Unit tests run on synthetic files in crates/terrio/tests/data/hecras (written by scripts/make_hecras_fixture.py, scripts/make_hecras_root_fixtures.py and scripts/make_hecras_area_fixture.py, or copied from the engine's committed synthetic fixtures; no model data).
• The comparison with h5py reads a corpus directory, whose location is a parameter, and compares its HEC-RAS 7.0.1 files: every cell polygon, face polyline, perimeter ring and face point, every family feature with every stored attribute column (type and value), the 2D flow area and cross-section tables, the root attributes, and every joined value, bit for bit. A refusal is accepted only where the test lists it. GDAL cannot read HEC-RAS files, so the reference is h5py: ras-commander reads these datasets with h5py, and scripts/hecras_oracle.py reads them the same way, independently of terrio and its engine. See Conformance.
• Test data is public only: the ras-hdf-test-corpus release (HEC's example projects and FEMA eBFE models, run in HEC-RAS 7.0.1, plus synthetic files derived from them, such as one with its projection replaced; CC0-1.0 for the corpus's own contribution, with each file's source or derivation in its manifest and the upstream attribution in its NOTICE), fetched at a pinned tag with its SHA-256 sums checked. CI runs the comparison on its smoke profile on every push to main and, for pull requests, on demand (the ci:hecras label, or a manual run of CI (npm and conformance)); no model file is committed to terrio.