terrain¶
Terrain discovery and consolidation for HEC-RAS projects.
Overview¶
The terrain module discovers named terrain layers from a HEC-RAS project's rasmap configuration and consolidates each surface's TIFF members independently. This is useful for:
- Inspecting terrain configuration: Enumerate all terrain layers, their CRS, resolution, and file locations
- Consolidating terrain: Merge the TIFF members of each named terrain into its own authoritative file
- Downsampling without upsampling: Select a whole native-cell multiple with a 5 ft publication floor
- Recovering relocated projects: Consolidate an explicit, priority-ordered TIFF list when stored RASMapper paths cannot be resolved on the processing host
- Publishing source construction: Export source TIFF footprints and terrain-modification vectors
- Creating HEC-RAS terrain HDFs: Generate new terrain HDF files via RasProcess.exe (required for result mapping)
- Native modification-aware export: Ask RAS Mapper to consolidate a registered terrain into one validated GeoTIFF while preserving source priority, stitches, masks, and vector modifications
Terrain Modification Vectors¶
extract_terrain_modification_layers() (and export_terrain_modifications(), which writes
each non-empty layer as GeoParquet) reads the terrain HDF's /Modifications group. Each
modification layer can hold several features, and each feature is one row with its own
attributes (feature_index, feature_name).
| Layer | Contents |
|---|---|
terrain_modification_lines |
Line, levee and channel centrelines with width (top width), left_slope, right_slope and max_extent (RAS Mapper's Max Reach) |
terrain_modification_polygons |
Polygon modifications (shape_type="polygon") and the outlines of pier, rectangle, ellipse and triangle modifications (shape_type), built from their stored parameters |
terrain_modification_footprints |
One polygon per feature covering the terrain it can change: lines buffered by max_extent (or, when no max extent is stored, half the top width, an estimate that can omit side-slope reach; see footprint_basis and footprint_half_width), polygons and shapes as drawn. A line with neither a positive max_extent nor a positive width has no footprint |
terrain_modification_control_points |
Elevation control points |
A centreline is not a footprint: a channel or levee changes the terrain across its top width
and side slopes, up to Max Reach either side. Use terrain_modification_footprints to
test whether a feature can affect a location. A max_extent footprint is an upper bound; how
far the side slopes actually reach depends on the terrain. A top_width footprint (no max
extent stored) covers only the top width and can omit side-slope reach, so do not use it to
rule out an effect at a location. A line with no usable max extent or width
has no footprint, so check terrain_modification_lines when every feature must be covered.
Stored vs Active Modifications¶
A terrain HDF stores modification layers under /Modifications. RAS Mapper (HEC-RAS 6.6,
7.0.1) applies them only when the project's .rasmap terrain layer has an
ElevationModificationGroup named exactly Modifications, and then applies every stored
layer: the group's per-layer entries and Checked state are not consulted. Two projects can
share one terrain HDF and still map on different terrains: a project whose terrain layer has
no Modifications group (none, or only one under another name) maps on the unmodified
terrain, and a RAS Mapper export through it is identical to the unmodified terrain.
from ras2cng.terrain import terrain_modification_status, active_terrain_modifications
status = terrain_modification_status("Terrain/T.hdf", "Model.rasmap")
status.stored # layers in the HDF
status.active # layers RAS Mapper applies in this project
status.inactive # stored but not applied (no Modifications group)
status.registered # layers the .rasmap lists (informational)
status.basis # "rasmap", or "hdf" when the .rasmap has no entry for this terrain
Without a .rasmap, or when it has no layer for this terrain HDF, every stored layer counts
as active, so an unknown activation is never treated as unmodified.
active_terrain_modifications() returns the labels of the active set; fast-map uses it to
choose between native terrain operations and the RAS Mapper export.
terrain_modifications() remains an inventory of everything stored or registered.
ras2cng inspect shows active/stored counts per terrain, and archive manifests record
stored_modifications, active_modifications, inactive_modifications and
activation_basis in each terrain_modifications entry.
How Terrain Discovery Works¶
- Reads the project's
.rasmapfile to get terrain names in priority order - For each terrain name, locates the corresponding
.hdffile in theTerrain/directory - Discovers associated
.tiffiles by matching the HDF stem against TIF file names - Optionally reads CRS and resolution from TIF files using rasterio
Terrain Name Matching¶
TIF files are associated with a terrain by matching the file stem against the terrain name. The matching is case-insensitive and allows suffixes separated by ., _, or -:
| TIF Stem | Terrain Name | Match? |
|---|---|---|
Terrain50 |
Terrain50 |
Yes (exact) |
Terrain50.muncie_clip |
Terrain50 |
Yes (dot separator) |
Terrain50_tile2 |
Terrain50 |
Yes (underscore separator) |
Terrain50-highres |
Terrain50 |
Yes (dash separator) |
Terrain50WithChannel |
Terrain50 |
No (alphanumeric continuation) |
How Terrain Consolidation Works¶
- Discover terrain TIFs from rasmap (priority ordered)
- Keep terrain names separate: different named RASMapper terrains are never merged implicitly
- Choose a target grid: preserve native resolution at or above 5 ft; otherwise use the smallest whole native-cell multiple at or above 5 ft. A mixed-resolution mosaic requires an explicit target that is a whole multiple of its coarsest native grid; every source factor is retained in provenance.
- Merge by windows: reproject each member to the target grid and let the first RASMapper source win in overlaps without allocating the full mosaic in memory
- Optionally create HEC-RAS terrain HDF via
RasTerrain.create_terrain_from_rasters()(requires RasProcess.exe) - Optionally register the new terrain in the project's rasmap
Steps 5-6 require RasProcess.exe (Windows or Wine). Steps 1-4 are pure Python (rasterio).
Merge engine (opt-in)¶
Step 4 warps each 512-pixel destination block separately with rasterio. Setting
RAS2CNG_TERRAIN_MERGE_ENGINE=terrio does one whole-output warp of every source
with terrio instead (it needs the CLB terrio build; without it, or when the
sources do not share one CRS, the merge stays on rasterio and the reason is
recorded). auto and rasterio keep the default.
The switch changes the values. terrio's mosaic is bit-identical to GDAL's
own whole-output warp, and the blockwise output is not: on the Bald Eagle
terrain (two sources, 40 ft target) 18.5 M of 49.7 M pixels differ between the
two, by up to 4.44 ft (274 pixels by more than 1 ft), with identical valid
masks. terrio took 4.9 s against 20.9 s, with a 453 MiB peak against 829 MiB.
It is off by default so that existing outputs do not change. The engine used
is written to the terrain provenance file as merge_engine.
Native Registered-Terrain Export¶
export_modified_terrain() is the production path for a single,
modification-aware terrain TIFF. It delegates to
RasTerrain.export_rasmapper_terrain() rather than selecting the first source
TIFF or reconstructing terrain-modification mathematics in Python. RAS Mapper
performs the consolidation and nearest-neighbor resampling on the authoritative
source grid. Exact source-derived scale factors are 1, 2, 4, and 8.
The output is committed only after ras-commander semantically validates it; a
JSON receipt is written beside the TIFF. Existing output and receipt files are
protected unless overwrite=True (or --overwrite in the CLI).
The optional geometry argument is deprecated and ignored because native
registered-terrain export does not consume a geometry HDF. terrain_name may
be omitted only when the project registers exactly one terrain; ambiguous
projects must select the exact RAS Mapper terrain name. The compatibility
argument is scheduled for removal in ras2cng 1.1.
This path uses ras-commander 0.100.0 or newer, which exposes
RasTerrain.export_rasmapper_terrain(). An older installation receives an
explicit upgrade error instead of falling back to the numerically different
row sampler.
Qualified runtimes are HEC-RAS 6.4.1, 6.5, 6.6, and 7.0.1 on native Windows and Wine. HEC-RAS 6.3, 6.4.0, 6.7 beta builds, and 7.0.0 are rejected. Stable 7.1 is forward-open: ras-commander will accept it only when the installed binary satisfies the exact managed API contract.
API Reference¶
ras2cng.terrain.TerrainInfo
dataclass
¶
Information about a single terrain layer discovered from a RAS project.
Source code in ras2cng/terrain.py
ras2cng.terrain.discover_terrains(project_path)
¶
Discover terrain layers from rasmap in priority order.
Uses RasMap.get_terrain_names() + rasmap_df['terrain_hdf_path']. For each terrain HDF, discovers associated .tif files in same directory.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
project_path
|
Path
|
Path to .prj file or project directory |
required |
Returns:
| Type | Description |
|---|---|
list[TerrainInfo]
|
List of TerrainInfo in rasmap priority order |
Source code in ras2cng/terrain.py
269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 | |
ras2cng.terrain.consolidate_terrain(project_path, output_dir, *, terrain_name='Consolidated', downsample_factor=None, target_resolution=None, terrain_names=None, horizontal_units='Feet', units='Feet', ras_version='6.6', create_hdf=True, register_rasmap=True)
¶
Consolidate project terrains and create a new HEC-RAS terrain HDF.
Full pipeline: 1. Discover terrain TIFFs from rasmap (priority ordered) 2. Merge via rasterio.merge.merge(method='first') -- first wins in overlaps 3. Optionally downsample (reduce resolution) 4. Create HEC-RAS terrain HDF via RasTerrain.create_terrain_from_rasters() 5. Register new terrain in rasmap via RasMap.add_terrain_layer()
Steps 4-5 require RasProcess.exe. If create_hdf=False, only produces the merged TIFF (useful for exporting to cloud-native COG pipeline).
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
project_path
|
Path
|
Path to .prj file or project directory |
required |
output_dir
|
Path
|
Directory for output terrain files |
required |
terrain_name
|
str
|
Name for the consolidated terrain (default: "Consolidated") |
'Consolidated'
|
downsample_factor
|
Optional[float]
|
Factor to reduce resolution (2.0 = half resolution) |
None
|
target_resolution
|
Optional[float]
|
Target cell size in project units (overrides downsample_factor) |
None
|
terrain_names
|
Optional[list[str]]
|
One named terrain to consolidate. Required when the project contains multiple named terrains. |
None
|
horizontal_units
|
str
|
Horizontal raster units (Feet or Meters), used to enforce the five-foot publication floor. |
'Feet'
|
units
|
str
|
Vertical units "Feet" or "Meters" |
'Feet'
|
ras_version
|
str
|
HEC-RAS version for RasProcess.exe |
'6.6'
|
create_hdf
|
bool
|
If True, create HEC-RAS terrain HDF (requires RasProcess.exe) |
True
|
register_rasmap
|
bool
|
If True, register new terrain in project rasmap |
True
|
Returns:
| Type | Description |
|---|---|
Path
|
Path to consolidated terrain HDF (if create_hdf) or TIFF (if not) |
Source code in ras2cng/terrain.py
394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 451 452 453 454 455 456 457 458 459 460 461 462 463 464 465 466 467 468 469 470 471 472 473 474 475 476 477 478 479 480 481 482 483 484 485 486 487 488 489 490 491 492 493 494 495 496 497 498 499 500 501 502 503 504 505 506 507 508 509 510 511 512 513 514 515 516 517 518 519 520 521 522 523 524 525 526 527 528 | |
ras2cng.terrain.consolidate_terrain_files(tif_files, output_dir, *, terrain_name='Consolidated', source_terrain_name=None, downsample_factor=None, target_resolution=None, horizontal_units='Feet', source_paths=None)
¶
Consolidate an explicit, priority-ordered terrain TIFF mosaic.
This entry point supports projects whose RAS Mapper paths cannot be resolved on the processing host. The first source wins where valid pixels overlap, and the normal no-upsample publication policy is always enforced.
Source code in ras2cng/terrain.py
184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 | |
ras2cng.terrain.consolidate_project_terrains(project_path, output_dir, *, target_resolutions=None, horizontal_units='Feet')
¶
Consolidate TIFF members separately for every named project terrain.
Source code in ras2cng/terrain.py
ras2cng.terrain.export_modified_terrain(project_path, output_tif, *, geometry=None, terrain_name=None, downsample_factor=1, overwrite=False, hecras_version=None)
¶
Export a registered terrain with modifications applied as one GeoTIFF.
Delegates consolidation, grid alignment, nearest-neighbor downsampling, and vector-modification rasterization to RAS Mapper's native terrain export. Registered source priority, stitches, and masks are therefore preserved.
HEC-RAS 6.4.1, 6.5, 6.6, and 7.0.1 are qualified on Windows and Wine. Stable 7.1 is forward-open subject to ras-commander's managed-contract check. Unsupported project/runtime versions fail before native execution.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
project_path
|
Path
|
Path to .prj file or project directory |
required |
output_tif
|
Path
|
Output GeoTIFF path |
required |
geometry
|
Optional[str]
|
Deprecated compatibility argument. Native registered-terrain export does not use a geometry HDF, so any supplied value is ignored. |
None
|
terrain_name
|
Optional[str]
|
Exact registered terrain name. May be omitted only when the project registers exactly one terrain. |
None
|
downsample_factor
|
int
|
Exact source-derived factor: 1, 2, 4, or 8. |
1
|
overwrite
|
bool
|
Replace an existing output and receipt when true. |
False
|
hecras_version
|
Optional[str]
|
Installed HEC-RAS version to export with (e.g. "7.0.1"). None lets ras-commander choose from the project. |
None
|
Returns:
| Type | Description |
|---|---|
Path
|
Path to the output GeoTIFF |
Raises:
| Type | Description |
|---|---|
RuntimeError
|
If ras-commander lacks native terrain export support or RAS Mapper reports an operational failure. |
Source code in ras2cng/terrain.py
1852 1853 1854 1855 1856 1857 1858 1859 1860 1861 1862 1863 1864 1865 1866 1867 1868 1869 1870 1871 1872 1873 1874 1875 1876 1877 1878 1879 1880 1881 1882 1883 1884 1885 1886 1887 1888 1889 1890 1891 1892 1893 1894 1895 1896 1897 1898 1899 1900 1901 1902 1903 1904 1905 1906 1907 1908 1909 1910 1911 1912 1913 1914 1915 1916 1917 1918 1919 1920 1921 1922 1923 1924 1925 1926 1927 1928 1929 1930 1931 1932 1933 1934 1935 1936 1937 1938 1939 1940 1941 1942 1943 1944 1945 1946 1947 1948 | |
ras2cng.terrain.extract_terrain_source_footprints(tif_files, *, out_crs=None)
¶
Build one queryable footprint polygon per native terrain TIFF member.
Source code in ras2cng/terrain.py
ras2cng.terrain.extract_terrain_modification_layers(terrain_hdf_path, *, crs=None)
¶
Read RASMapper terrain modification vectors from a terrain HDF.
Each /Modifications/<layer> group can hold several features; every
feature becomes its own row (feature_index within the layer, with that
feature's own Attributes row).
Returns four GeoDataFrames (always present, possibly empty):
terrain_modification_lines: line, levee and channel centrelines with theirwidth(top width),left_slope,right_slopeandmax_extent(RAS Mapper's "Max Reach": how far either side of the centreline the modification may change the terrain).terrain_modification_polygons: polygon modifications, and the outlines of pier, rectangle, ellipse and triangle modifications (shape_type), built from their stored parameters the way RAS Mapper builds them.terrain_modification_footprints: one polygon per feature covering the terrain the feature can change. Lines are buffered bymax_extent(or by half the top width when no max extent is stored;footprint_basissays which andfootprint_half_widthby how much); polygons and shapes are their own footprint. A line with neither value has no footprint row.terrain_modification_control_points.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
terrain_hdf_path
|
Path
|
HEC-RAS terrain HDF. |
required |
crs
|
Optional[str]
|
CRS to assign (default: the terrain HDF's projection). |
None
|
Raises:
| Type | Description |
|---|---|
FileNotFoundError
|
The terrain HDF does not exist. |
ValueError
|
No CRS is given and the HDF has none. |
Source code in ras2cng/terrain.py
589 590 591 592 593 594 595 596 597 598 599 600 601 602 603 604 605 606 607 608 609 610 611 612 613 614 615 616 617 618 619 620 621 622 623 624 625 626 627 628 629 630 631 632 633 634 635 636 637 638 639 640 641 642 643 644 645 646 647 648 649 650 651 652 653 654 655 656 657 658 659 660 661 662 663 664 665 666 | |
ras2cng.terrain.terrain_modification_status(terrain_hdf, rasmap_path=None)
¶
Which of a terrain's modifications RAS Mapper applies in a project.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
terrain_hdf
|
Path
|
The terrain HDF. |
required |
rasmap_path
|
Optional[Path]
|
The project's |
None
|
Returns:
| Type | Description |
|---|---|
TerrainModificationStatus
|
class: |
Source code in ras2cng/terrain.py
ras2cng.terrain.active_terrain_modifications(terrain_hdf, rasmap_path=None)
¶
Labels of the modifications RAS Mapper applies, or [].
Use this, not :func:terrain_modifications, wherever modifications
change mapping or routing. See :func:terrain_modification_status.
Source code in ras2cng/terrain.py
ras2cng.terrain.TerrainModificationStatus
dataclass
¶
Stored vs active terrain modifications for one terrain in one project.
RAS Mapper (HEC-RAS 6.6, 7.0.1) applies a terrain HDF's modification
layers only when the project's .rasmap terrain layer has an
ElevationModificationGroup named exactly Modifications. With
one, it applies every layer the HDF stores: the group's per-layer
entries and their Checked state are not consulted (T14;
ras-commander RasFim.top_priority_terrain_source). Without one (no
group, or only a group under another name) it applies none: a RAS Mapper
export through such a project was identical to the unmodified terrain.
A modified terrain goes to RAS Mapper's export unless the engine
advertises rasmapper-effective-terrain/2 and every modification form
is qualified (see fast_map.TerrainResolver.modified_route).
Attributes:
| Name | Type | Description |
|---|---|---|
terrain_hdf |
str
|
The terrain HDF. |
rasmap |
Optional[str]
|
The |
stored |
list[str]
|
Layer names in the HDF's |
registered |
list[str]
|
Layer names the |
active |
list[str]
|
What RAS Mapper applies: every |
basis |
str
|
|
problems |
list[str]
|
An unreadable or linked |
Source code in ras2cng/terrain.py
1243 1244 1245 1246 1247 1248 1249 1250 1251 1252 1253 1254 1255 1256 1257 1258 1259 1260 1261 1262 1263 1264 1265 1266 1267 1268 1269 1270 1271 1272 1273 1274 1275 1276 1277 1278 1279 1280 1281 1282 1283 1284 1285 1286 1287 1288 1289 1290 1291 1292 1293 1294 1295 1296 1297 1298 1299 1300 1301 1302 1303 1304 1305 | |
inactive
property
¶
Stored layers RAS Mapper does not apply in this project.
active_labels()
¶
hdf:/rasmap: labels of the active set, plus HDF problems.
Empty only when nothing is applied and nothing is unknown.