Skip to content

HDF Modules

Classes for reading and processing HEC-RAS HDF result files.

Core Classes

HdfBase

Base functionality for HDF file operations.

  • get_dataset_info(hdf_path, group_path=None) - Print HDF structure
  • get_attrs(hdf_path, path) - Get attributes at path
  • get_projection(hdf_path) - Get coordinate system
  • get_result_unit_metadata(hdf_path, strict=True) - Read normalized unit metadata and source evidence from a standalone plan-result HDF
  • parse_ras_datetime(datetime_str) - Parse HEC-RAS datetime string
  • parse_ras_datetime_ms(datetime_bytes) - Parse datetime with milliseconds

get_result_unit_metadata() is deliberately a result-HDF fallback. When the full project is available, use RasPrj.get_project_units() and treat the text .prj marker as authoritative. The HDF reader never defaults missing metadata to English units. It raises on missing, unrecognized, geometry-only, or contradictory metadata unless strict=False, which returns the raw evidence and an unresolved status for audit workflows.

HdfPlan

Plan-level information from HDF files.

  • get_plan_info(hdf_path) - Get plan metadata
  • get_simulation_times(hdf_path) - Get start/end times
  • get_plan_parameters(hdf_path) - Get computation parameters
  • get_2d_flow_options(hdf_path) - Get 2D equation set, initial condition time, tolerances, and solver options from computed HDF output

HdfProject

Project-wide extent and coordinate-system helpers.

  • get_project_extent(hdf_path=None, include_1d=True, include_2d=True, include_storage=True, buffer_percent=50.0, buffer_x_percent=None, buffer_y_percent=None, geometry_type="footprint", fill_holes=True, *, geom_path=None, fallback_to_plaintext=True, ras_object=None) - Return a footprint or buffered bounding box and its project-coordinate bounds.
  • get_project_bounds_latlon(hdf_path=None, buffer_percent=50.0, include_1d=True, include_2d=True, include_storage=True, project_crs=None, *, geom_path=None, fallback_to_plaintext=True, ras_object=None) - Return the project bounds in WGS84.
  • export_extent_geojson(hdf_path, output_path, buffer_percent=50.0, *, geom_path=None, fallback_to_plaintext=True, ras_object=None) - Export the project extent as GeoJSON.

Extent extraction prefers usable HDF geometry independently for 1D reaches, 2D flow areas, and storage areas. With the default fallback_to_plaintext=True, a matching plain-text .g## file supplies only components unavailable from HDF; a text-only 1D footprint is constructed from cross-section cut-line endpoints. Set fallback_to_plaintext=False for strict HDF-only behavior. include_storage=True is also component-aware: HDF storage polygons are preferred and companion text geometry is used only when needed.

Mesh Operations

HdfMesh

Mesh geometry data.

  • get_mesh_area_names(hdf_path) - List 2D flow areas
  • get_mesh_cell_polygons(hdf_path) - Get cell polygons as GeoDataFrame
  • get_mesh_cell_faces(hdf_path) - Get cell face lines
  • get_mesh_cell_points(hdf_path) - Get cell center points
  • get_mesh_perimeter(hdf_path) - Get mesh perimeter polygon
  • get_mesh_cell_count(hdf_path) - Get number of cells
  • get_nearest_cell(hdf_path, point) - Find nearest cell to point
  • get_nearest_face(hdf_path, point) - Find nearest face to point
  • get_mesh_face_property_tables(hdf_path) - Read face elevation/area/wetted-perimeter/Manning tables

EXPERIMENTAL — not recommended for production or any other non-experimental use. These direct writes have been tested only with HEC-RAS 7.0 April 2026 in one Windows-preprocess/Linux-solve *.p##.tmp.hdf workflow. All other HEC-RAS versions and workflows are untested. They are not general land-cover or geometry-authoring APIs.

The methods require acknowledge_unsupported=True, validate the exact temporary-result role and schema, retain a unique full-file backup, emit a runtime warning, and verify readback:

  • write_linux_tmp_face_property_tables(...) - Replace selected temporary face tables
  • extend_linux_tmp_face_property_tables(...) - Extend temporary tables and return a structured report
  • transform_linux_tmp_face_mannings_n(...) - Transform only the temporary-table Manning column
  • sample_linux_tmp_face_mannings_n_from_landcover_curves(...) - Apply the documented equal-class land-cover sampling heuristic
  • set_mesh_pinned_attribute(...) - Set informational Pinned metadata; this does not protect edits from Windows preprocessing

The former names remain compatibility wrappers through v1.1.x and will not be removed before v1.2.0:

Compatibility name Canonical replacement
set_mesh_face_property_tables() write_linux_tmp_face_property_tables()
extend_face_property_tables() extend_linux_tmp_face_property_tables()
set_face_mannings_n_values() transform_linux_tmp_face_mannings_n()
recompute_face_mannings_n_from_landcover_curves() sample_linux_tmp_face_mannings_n_from_landcover_curves()
pin_property_tables() set_mesh_pinned_attribute()

HdfResultsMesh

2D mesh results.

  • get_mesh_max_ws(hdf_path) - Maximum water surface elevation
  • get_mesh_max_ws_time(hdf_path) - Time of maximum WSE
  • get_mesh_max_depth(hdf_path) - Maximum depth from stored HEC-RAS Depth when present, otherwise derived in memory from Water Surface - Cells Minimum Elevation
  • get_mesh_max_face_v(hdf_path) - Maximum face velocity
  • get_mesh_timeseries(hdf_path, mesh, var) - Time series for mesh
  • get_mesh_cells_timeseries(hdf_path, mesh, cell_ids, var) - Cell time series
  • get_mesh_faces_timeseries(hdf_path, mesh, face_ids, var) - Face time series
  • get_profile_line_flow_timeseries(hdf_path, line_name, mesh_name=None, profile_lines_path=None, direction="absolute") - Flow time series across a RAS Mapper profile/reference line
  • get_profile_line_peak_flow(hdf_path, line_name, mesh_name=None, profile_lines_path=None, direction="absolute") - Peak Q and peak time for a profile/reference line

get_mesh_max_depth() logs one INFO source message per mesh. Stored Depth is read only. The fallback is computed only in memory and does not create or write Depth in the HDF. Temporary synthetic test HDFs are test artifacts; they are not producer output and are labeled separately from pre-existing HEC-RAS result fixtures.

HdfResultsProducts

Inspection and deterministic product contracts for completed unsteady result HDFs.

  • inspect_result(hdf_path) - Read an existing result HDF without mutation and fail closed on incomplete or conflicting completion evidence, inconsistent time axes, missing CRS or units, and mesh/result/topology misalignment
  • export(hdf_path, output_directory, *, resolution=None, max_dimension=2048, nodata=-9999.0, include_preview=True) - Generate a checksum-pinned hydraulic product package without modifying the producer HDF

Current HEC-RAS results can establish completion with Event Conditions/Completed Successfully=True. Older producer HDFs that do not contain that attribute can establish completion with their embedded Complete Process compute-message marker. An explicit false or malformed attribute is never overridden by messages.

The returned inspection identifies whether maximum depth will be read from the stored HEC-RAS Depth time series or derived in memory from Water Surface - Cells Minimum Elevation. It also records hydraulic_qaqc: not_evaluated: mechanical completion and product readiness are not engineering acceptance.

Python
from ras_commander import HdfResultsProducts

inspection = HdfResultsProducts.inspect_result("project.p02.hdf")
manifest = HdfResultsProducts.export(
    "project.p02.hdf",
    "project-p02-hydraulic-products",
)

export() supports completed unsteady HDFs with 2D flow areas. It writes a common-grid trio of Cloud Optimized GeoTIFFs for maximum WSE, maximum depth, and maximum adjacent-face velocity; a fixed-schema Arrow/Parquet boundary hydrograph table; result metadata; numerical evidence; a WGS84 GeoJSON footprint; and, by default, a depth preview. pyarrow>=14.0 is a required core dependency because Arrow and Parquet are part of the modern geospatial product contract, not an optional fallback.

Raster dimensions are bounded twice: neither width nor height may exceed max_dimension, and the total raster contains at most 16,777,216 cells. The nodata argument is normalized to float32 before collision checks so a nearby double-precision value cannot silently become equal to valid stored data. Pixels are square at the exact selected resolution; when a footprint span is not evenly divisible, raster bounds expand by less than one pixel on the right or bottom rather than silently changing the requested cell size.

The source HDF is opened read-only and protected by point-in-time digest checks. The files in the output directory are newly generated ras-commander derivative artifacts; they are not newly generated HEC-RAS model output. The output directory must not already exist. Assets are published without overwriting and hydraulic-products.json is linked last, so consumers must use that manifest as the package-complete marker. A package that lacks the manifest is incomplete. Publication requires same-filesystem hard-link support and fails closed when the destination filesystem cannot provide it.

The exporter preserves valid negative-datum WSE and uses 2D flow-area footprints as raster support. It does not infer hydraulic acceptability: numerical-qaqc.json preserves evidence while the manifest remains hydraulic_qaqc: not_evaluated. A result with no boundary-condition series gets a valid, empty Parquet table with the same schema rather than losing the asset.

Synthetic HDFs created by focused tests are labeled test artifacts. Real-file integration uses pre-existing producer HDFs read-only and does not run HEC-RAS or generate model output; it generates only temporary derivative packages.

Plan Results

HdfResultsPlan

Plan-level results.

  • get_runtime_data(hdf_path) - Runtime statistics
  • get_volume_accounting(hdf_path) - Volume accounting data
  • get_compute_messages(hdf_path) - Computation messages
  • get_compute_options(hdf_path) - Computation options used
  • is_steady_plan(hdf_path) - Check if steady state
  • get_steady_profile_names(hdf_path) - Get steady profile names
  • get_steady_wse(hdf_path) - Get steady water surface elevations
  • get_steady_info(hdf_path) - Get steady flow metadata

HdfResultsXsec

1D cross-section results.

  • get_xsec_timeseries(hdf_path) - All cross-section time series
  • get_xsec_summary(hdf_path) - Cross-section summary data

1D Geometry

HdfXsec

Cross-section and river geometry extraction from HDF.

  • get_cross_sections(hdf_path, ras_object=None) - Extract cross-section geometries as a GeoDataFrame. Accepts a geometry HDF path or a plan selector; multipart cut lines are returned as MultiLineString without synthetic connectors.
  • get_xs_coords(hdf_path, river=None, reach=None, rs=None) - Extract native station/elevation points as XYZ with point/station order, cut-line distance, Manning's n, bank classification, coordinate metadata, and source provenance
  • get_river_centerlines(hdf_path) - Extract river centerlines as LineString or MultiLineString geometries
  • get_river_stationing(hdf_path) - Calculate river stationing along centerlines
  • get_river_reaches(hdf_path) - Return model 1D river reach lines with stable river_id and computed length columns
  • get_river_edge_lines(hdf_path) - Return river edge lines
  • get_river_bank_lines(hdf_path) - Extract river bank lines

Structure Data

HdfStruc

Structure geometry and SA/2D connections.

  • get_connection_list(hdf_path) - List SA/2D connections
  • get_connection_profile(hdf_path, name) - Get connection profile
  • get_connection_gates(hdf_path, name) - Get gate data
  • get_storage_area_polygons(hdf_path, *, ras_object=None) - Extract storage area polygons and attributes from geometry or plan HDF files, including multi-ring polygons with interior rings; returns an empty GeoDataFrame when no storage areas are present.

HdfResultsBreach

Dam breach results.

  • get_breach_timeseries(hdf_path, structure) - Breach time series
  • get_breach_summary(hdf_path, structure) - Breach summary statistics
  • get_breaching_variables(hdf_path, structure) - Breach geometry evolution
  • get_structure_variables(hdf_path, structure) - Structure flow variables

HdfStorageArea

Storage area volume-elevation curve extraction from HDF.

  • get_volume_elevation_curve(hdf_path, sa_name) - Get volume-elevation curve for a storage area
  • get_storage_area_names(hdf_path) - List storage areas in HDF

HdfChannelCapacity

1D channel capacity analysis (multi-AEP).

  • get_channel_capacity(hdf_path, river=None, reach=None) - Compute channel capacity from cross-section geometry and results
  • get_multi_aep_capacity(hdf_paths, aep_labels) - Compare capacity across multiple AEP simulations

HdfStruc1D

1D structure result extraction from plan HDF results.

  • get_structure_max_values(hdf_path, river, reach, rs) - Extract maximum headwater, tailwater, and flow for a bridge, culvert, inline weir, or inline control structure. Raises an actionable ValueError when the plan HDF has no steady/unsteady results, required cross-section result datasets are absent, or the requested structure is not present in the results.
  • list_1d_structures(hdf_path) - List 1D structures identified from result markers. Returns an empty DataFrame quietly when no structures are present in an otherwise readable HDF.

For steady plans, get_structure_max_values() can use the flanking cross sections when the structure is represented in HDF Node Info instead of Cross Section Attributes. The returned hw_source, tw_source, and flow_source fields identify the result locations used.

HdfHydraulicTables

Cross section property tables (HTAB).

  • get_xs_htab(hdf_path, river, reach, station) - Get HTAB data

Infrastructure

HdfPipe

Pipe network analysis.

  • get_pipe_conduits(hdf_path) - Get conduit geometry
  • get_pipe_nodes(hdf_path) - Get node locations
  • get_pipe_network_timeseries(hdf_path, var) - Network time series
  • get_pipe_network_summary(hdf_path) - Network summary
  • get_pipe_profile(hdf_path, conduit_id) - Get conduit profile

HdfPump

Pump station analysis.

  • get_pump_stations(hdf_path) - Get station locations
  • get_pump_groups(hdf_path) - Get pump groups
  • get_pump_station_timeseries(hdf_path, name) - Station time series
  • get_pump_station_summary(hdf_path) - Station summary
  • get_pump_operation_timeseries(hdf_path, name) - Operation history

Analysis

HdfFluvialPluvial

Fluvial-pluvial boundary analysis.

  • calculate_fluvial_pluvial_boundary(hdf_path, delta_t) - Calculate boundary

HdfInfiltration

Native infiltration authoring and read-only inspection.

Geometry File Operations:

  • get_preprocessed_infiltration(hdf_path, mesh_name=None, variable=...) - Read solver-owned per-cell infiltration arrays
  • get_infiltration_baseoverrides(hdf_path) - Retrieve the geometry-wide class-to-parameter fallback table
  • get_infiltration_calibration_regions(hdf_path) - Read every region table in the bulk variable-oriented HDF view
  • get_infiltration_region_overrides(hdf_path, region_name=..., hecras_version=...) - Read one selected region in the class-ordered native view
  • get_infiltration_region_names(hdf_path) - Read stable region names
  • get_infiltration_region_polygons(hdf_path) - Read stable region IDs, names, and polygon geometry
  • create_infiltration_override_regions(hdf_path, region_names, hecras_version=...) - Create native geometry override regions from existing Manning-region polygons
  • set_infiltration_base_overrides(hdf_path, data, hecras_version=...) - Set the native geometry-wide Base Overrides fallback
  • scale_infiltration_base_overrides(hdf_path, data, scale_factors, hecras_version=...) - Scale active geometry-wide Base Overrides while preserving sentinel values
  • set_infiltration_region_overrides(hdf_path, data, region_name=..., hecras_version=...) - Set one native region's parameter table without changing Base Overrides or other regions
  • scale_infiltration_region_overrides(hdf_path, data, scale_factors, region_name=..., hecras_version=...) - Scale one selected region while preserving sentinel values

Raster and Layer Operations:

  • get_infiltration_layer_data(hdf_path) - Get infiltration layer data from HDF
  • set_infiltration_sidecar_parameters(hdf_path, data, hecras_version=...) - Set sidecar parameters through native RASMapper serialization
  • scale_infiltration_sidecar_parameters(hdf_path, data, scale_factors, hecras_version=...) - Scale and save sidecar parameters natively
  • get_classification_polygons(hdf_path) - Read infiltration sidecar classification polygon overrides
  • get_infiltration_map(hdf_path=None, ras_object=None) - Read the infiltration raster map; without an explicit path, resolve the first usable rasmap_df["infiltration_hdf_path"]
  • calculate_soil_statistics(hdf_path) - Process zonal statistics for soil analysis
  • get_soils_raster_stats(geom_hdf_path, soil_hdf_path=None, ras_object=None) - Resolve the soil sidecar consistently; lookup failures retain the empty-frame recovery contract
  • get_soil_raster_stats(...), get_infiltration_stats(...), and get_landcover_raster_stats(...) - Use the same status-aware sidecar resolver and empty-frame recovery contract

The compatibility names create_infiltration_group(), set_infiltration_baseoverrides(), set_infiltration_layer_data(), and scale_infiltration_baseoverrides() delegate to the canonical native APIs through the v1.1.x compatibility window. The historical scale_infiltration_data() name was ambiguous between a geometry HDF and an infiltration sidecar and now fails closed with three explicit choices: the geometry-wide, selected-region, or sidecar scaler. These compatibility names will not be removed before v1.2.0. Ras Commander never hand-authors or selectively deletes /Geometry/Infiltration datasets.

Soil Analysis:

  • get_significant_mukeys(hdf_path, threshold) - Identify mukeys above percentage threshold
  • calculate_total_significant_percentage(hdf_path) - Compute total coverage
  • get_infiltration_parameters(hdf_path=None, mukey=None, ras_object=None) - Get parameters for a specific mukey, with the same optional rasmap_df lookup
  • calculate_weighted_parameters(hdf_path) - Compute weighted average parameters

Data Export:

  • save_statistics(data, path) - Export soil statistics to CSV

HdfLandCover

Land-cover sidecar and final Manning's n extraction.

  • get_landcover_raster_map(hdf_path) - Read land-cover class IDs, names, and Manning's n values
  • set_landcover_mannings_n(hdf_path, mapping, hecras_version=...) - Set sidecar Manning's n through native RASMapper serialization
  • get_classification_polygons(hdf_path) - Read land-cover sidecar classification polygon overrides
  • get_preprocessed_mannings_n(hdf_path) - Read preprocessed cell-center Manning's n values from geometry HDF
  • audit_final_mannings_n(hdf_path, ...) - Strictly audit solver-owned final cell/face Manning arrays
  • estimate_final_mannings_raster(hdf_path, ...) - Build a non-authoritative visualization estimate

Compatibility mappings are retained through v1.1.x and will not be removed before v1.2.0:

Compatibility name Canonical replacement
set_landcover_raster_map() set_landcover_mannings_n()
compute_final_mannings_raster() estimate_final_mannings_raster() for visualization, or audit_final_mannings_n() for solver evidence

HdfBndry

Boundary condition geometry.

  • get_bc_lines(hdf_path) - Get BC lines
  • get_breaklines(hdf_path) - Get breaklines

Utilities

HdfUtils

Utility class for HDF file operations.

Data Conversion:

  • convert_ras_string(value) - Convert RAS HDF strings to Python objects
  • convert_ras_hdf_value(value) - Convert general HDF values to Python objects
  • convert_df_datetimes_to_str(df) - Convert DataFrame datetime columns to strings
  • convert_hdf5_attrs_to_dict(attrs) - Convert HDF5 attributes to dictionary
  • convert_timesteps_to_datetimes(timesteps) - Convert timesteps to datetime objects

Spatial Operations:

  • perform_kdtree_query(source, target) - KDTree search between datasets
  • find_nearest_neighbors(data, k) - Find nearest neighbors within dataset

DateTime Parsing:

  • parse_ras_datetime(datetime_str) - Parse RAS datetime (ddMMMYYYY HH:MM:SS)
  • parse_ras_window_datetime(datetime_str) - Parse simulation window datetime
  • parse_duration(duration_str) - Parse duration strings (HH:MM:SS)
  • parse_ras_datetime_ms(datetime_bytes) - Parse datetime with milliseconds
  • parse_run_time_window(window_str) - Parse time window strings

Visualization

HdfPlot & HdfResultsPlot

Basic plotting utilities.

  • plot_results_max_wsel(gdf) - Plot maximum WSE map

Usage Example

Python
from ras_commander import HdfResultsMesh, HdfResultsPlan, init_ras_project

init_ras_project("/path/to/project", "6.5")

# Get HDF path
hdf_path = ras.plan_df.loc[ras.plan_df['plan_number'] == '01', 'hdf_path'].iloc[0]

# Extract max WSE
max_wse = HdfResultsMesh.get_mesh_max_ws(hdf_path)

# Get runtime stats
runtime = HdfResultsPlan.get_runtime_data(hdf_path)
CLB Engineering Corporation  ·  LLM Forward Engineering
RAS Commander Documentation is a free and open-source project maintained by CLB Engineering Corporation. For agencies and firms modernizing H&H workflows with LLM Forward approaches, contact CLB to partner with the engineers who wrote the automation.