Skip to content

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.

Python
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

Python
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))
Text Only
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.

Python
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)
Text Only
3

3. Verify the text round trip

Python
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.")
Text Only
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.

Python
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))
Text Only
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.

Python
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.")
Text Only
   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.