Reference Lines and Points for 2D Calibration¶
Author native reference features on a scratch Bald Eagle example, compute a one-day plan with HEC-RAS 6.6, and inspect the recorded geometry and time series. This run checks authoring and stored output; it does not establish calibration or hydraulic acceptance. Coordinates are in the example's stored project CRS.
The extraction and computed copy live under working/reference_points_207. A new
run folder is used for each execution. This notebook launches a real computation
through RasCmdr; use an installed HEC-RAS executable and allow the run to finish.
The original example archive stays unchanged.
from pathlib import Path
from datetime import datetime
from uuid import uuid4
import numpy as np
from ras_commander import (RasExamples, RasCmdr, RasPlan, init_ras_project, ras,
GeomReferenceFeatures, HdfMesh, HdfBndry, HdfResultsXsec)
RAS_EXE = Path(r"C:/Program Files (x86)/HEC/HEC-RAS/6.6/Ras.exe")
PLAN = "03"
WORK_ROOT = Path.cwd().parent / "working" / "reference_points_207"
assert RAS_EXE.is_file(), "Set RAS_EXE to an installed HEC-RAS 6.6 or 7.0.1 executable"
WORK_ROOT.mkdir(parents=True, exist_ok=True)
1. Extract and resolve the selected plan geometry¶
RasExamples.get_example_projects("6.6")
project_folder = RasExamples.extract_project("BaldEagleCrkMulti2D",
output_path=WORK_ROOT / "source", suffix="207")
init_ras_project(project_folder, RAS_EXE, hide_intro=True)
plan = ras.plan_df.loc[ras.plan_df.plan_number == PLAN].iloc[0]
geom_path = Path(plan['Geom Path'])
print("Selected plan:", PLAN, "geometry:", geom_path.name)
print("Existing native points:", GeomReferenceFeatures.get_reference_points(geom_path))
2026-10-20 18:57:17 - ras_commander.RasExamples - INFO - Successfully extracted project 'BaldEagleCrkMulti2D' to BaldEagleCrkMulti2D_207
Selected plan: 03 geometry: BaldEagleDamBrk.g09
Existing native points: []
2. Author features inside the BaldEagleCr mesh¶
Names and coordinates below are retained literally. Native points use Reference Point keys; IC Points are separate initial-condition features and are not converted. Mesh membership is checked against geometry before the plan is computed. Reference line vertex order is retained, so signed Flow is not reversed during extraction.
storage_area = "BaldEagleCr"
ref_points = [
{"name": "RP_Upper", "x": 2000000.0, "y": 312250.0},
{"name": "RP_Middle", "x": 2030250.0, "y": 335250.0},
{"name": "RP_Lower", "x": 2063500.0, "y": 352250.0},
]
ref_lines = [{"name": "RL_Mid", "coordinates": [
(2017750.0, 325250.0), (2016750.0, 325750.0), (2015750.0, 326250.0)]}]
# Geometry HDF comes from the selected plan's geometry, not the first geom_df row.
geom_hdf = Path(str(geom_path) + ".hdf")
mesh = HdfMesh.get_mesh_cell_polygons(geom_hdf)
from shapely.geometry import Point
for point in ref_points:
assert mesh.geometry.covers(Point(point['x'], point['y'])).any(), point['name']
GeomReferenceFeatures.add_reference_lines(geom_path, ref_lines, storage_area)
GeomReferenceFeatures.add_reference_points(geom_path, ref_points)
3
3. Verify the text round trip¶
read_points = GeomReferenceFeatures.get_reference_points(geom_path)
read_lines = GeomReferenceFeatures.get_reference_lines(geom_path)
assert read_points == ref_points
line = next(line for line in read_lines if line['name'] == 'RL_Mid')
assert line['storage_area'] == storage_area
np.testing.assert_array_equal(line['coordinates'], ref_lines[0]['coordinates'])
print("Native points:", read_points)
print("Reference line:", line)
print("Round trip passed; solver interpretation is checked next.")
Native points: [{'name': 'RP_Upper', 'x': 2000000.0, 'y': 312250.0}, {'name': 'RP_Middle', 'x': 2030250.0, 'y': 335250.0}, {'name': 'RP_Lower', 'x': 2063500.0, 'y': 352250.0}]
Reference line: {'name': 'RL_Mid', 'storage_area': 'BaldEagleCr', 'coordinates': [(2017750.0, 325250.0), (2016750.0, 325750.0), (2015750.0, 326250.0)]}
Round trip passed; solver interpretation is checked next.
4. Compute a separate one-day copy¶
RasPlan sets the time window through the API. RasCmdr copies the authored project into a new destination, clears geometry preprocessing data, and verifies the result. No direct Ras.exe launch or manual geometry/HDF editing is used.
RasPlan.update_simulation_date(PLAN, datetime(1999, 1, 1, 12), datetime(1999, 1, 2, 12))
RasPlan.set_hdf_output_variable(PLAN, "Cell Velocity", enabled=True)
run_folder = WORK_ROOT / ("computed_" + uuid4().hex[:8])
assert RasCmdr.compute_plan(PLAN, dest_folder=run_folder, clear_geompre=True,
force_rerun=True, num_cores=2, verify=True, max_runtime=900), "Plan computation failed"
init_ras_project(run_folder, RAS_EXE, hide_intro=True)
plan = ras.plan_df.loc[ras.plan_df.plan_number == PLAN].iloc[0]
plan_hdf = Path(plan['HDF_Results_Path'])
print("Computed HDF:", plan_hdf.relative_to(WORK_ROOT))
2026-10-20 18:57:20 - ras_commander.RasPlan - INFO - Updated simulation date in plan file: BaldEagleDamBrk.p03
2026-10-20 18:57:20 - ras_commander.RasPlan - INFO - Added HDF output variable 'Cell Velocity' to plan file: BaldEagleDamBrk.p03
2026-10-20 18:57:22 - ras_commander.RasCmdr - INFO - Copied project folder to destination: computed_d8a51a03
Computed HDF: computed_d8a51a03\BaldEagleDamBrk.p03.hdf
5. Read actual reference-point and reference-line results¶
HEC-RAS 6.6 stores point Water Surface and Velocity; 7.0.1 can also store Direction. Read the variables present in this computed file. Reference-point summaries are not assumed to exist. These values are recorded outputs, not nearest-cell postprocessing.
points_gdf = HdfBndry.get_reference_points(plan_hdf)
point_series = HdfResultsXsec.get_ref_points_timeseries(plan_hdf)
line_series = HdfResultsXsec.get_ref_lines_timeseries(plan_hdf)
assert len(points_gdf) == len(ref_points)
assert point_series.sizes['refpt_id'] == len(ref_points)
assert 'Water Surface' in point_series and 'Velocity' in point_series
assert point_series.sizes['time'] > 1
assert 'Flow' in line_series
print(points_gdf)
print(point_series)
print(line_series)
print("Native geometry and recorded series present; no point summaries inferred.")
refpt_id Name mesh_name Cell Index geometry
0 0 RP_Upper BaldEagleCr 14997 POINT (2000000 312250)
1 1 RP_Middle BaldEagleCr 9823 POINT (2030250 335250)
2 2 RP_Lower BaldEagleCr 5057 POINT (2063500 352250)
<xarray.Dataset> Size: 5kB
Dimensions: (time: 145, refpt_id: 3)
Coordinates:
* time (time) datetime64[us] 1kB 1999-01-01T12:00:00 ... 1999-01-...
* refpt_id (refpt_id) int64 24B 0 1 2
refpt_name (refpt_id) <U9 108B 'RP_Upper' 'RP_Middle' 'RP_Lower'
mesh_name (refpt_id) <U11 132B 'BaldEagleCr' ... 'BaldEagleCr'
Data variables:
Velocity (time, refpt_id) float32 2kB 1.52 0.0 0.0 ... 0.926 0.6305
Water Surface (time, refpt_id) float32 2kB 602.1 554.6 ... 562.0 536.2
<xarray.Dataset> Size: 5kB
Dimensions: (time: 145, refln_id: 1)
Coordinates:
* time (time) datetime64[us] 1kB 1999-01-01T12:00:00 ....
* refln_id (refln_id) int64 8B 0
refln_name (refln_id) <U6 24B 'RL_Mid'
mesh_name (refln_id) <U11 44B 'BaldEagleCr'
Data variables:
Flow (time, refln_id) float32 580B 0.0 0.0 ... -523.5
Velocity (time, refln_id) float32 580B 0.0 0.0 ... -0.2247
Water Surface (time, refln_id) float32 580B 570.9 ... 576.6
Water Surface Conveyance (time, refln_id) float32 580B 570.9 ... 576.6
Water Surface Max (time, refln_id) float32 580B 570.9 ... 577.0
Water Surface Min (time, refln_id) float32 580B 570.9 ... 575.9
Native geometry and recorded series present; no point summaries inferred.