Skip to content

mapping

Result raster generation for HEC-RAS projects using the RASMapper engine.

Overview

The mapping module generates georeferenced raster files (GeoTIFF) from completed HEC-RAS plan results. It uses a private compatibility adapter around ras-commander's stored-map APIs so profile selection is explicit and validated before map generation mutates the project.

Max and Min remain explicit summary selections. An exact named steady profile is resolved from the plan HDF and sent through RasMap.store_all_maps(mode="steady_profiles"); a missing or duplicate name raises an error instead of silently producing Max. Unsteady timestamps are likewise validated exactly. Whole-simulation products such as arrival time are generated separately because they do not have a profile dimension.

On Linux, RasProcess.exe runs under Wine. See the Linux/Wine Setup guide.

Supported Map Types

Map Type CLI Flag Default Description
wse --wse/--no-wse On Water Surface Elevation
depth --depth/--no-depth On Depth
velocity --velocity/--no-velocity On Velocity
froude --froude Off Froude Number
shear_stress --shear-stress Off Shear Stress
depth_x_velocity --dv Off Depth x Velocity
depth_x_velocity_sq --dv-sq Off Depth x Velocity²
inundation_boundary --inundation-boundary Off Inundation Boundary (GeoJSON from the default fast-map engine, much faster; shapefile from RAS Mapper)
arrival_time --arrival-time Off Arrival Time (hours, whole-simulation)
duration --duration Off Inundation Duration (hours, whole-simulation)
percent_inundated --percent-inundated Off Percent Time Inundated (whole-simulation)

--recession is accepted for compatibility but ignored with a warning — RasMapperLib has no recession map type, and only RasMapperLib-native outputs are produced.

Whole-simulation map types

arrival_time, duration, and percent_inundated are computed over the entire simulation — the --profile option does not apply to them. Their filenames carry the --arrival-depth wet/dry threshold instead of the profile name, e.g. Arrival Time (0.1ft hrs).tif. They work with any ras-commander version: newer versions generate them natively via store_maps(); on older versions ras2cng pre-injects the stored-map entries into the .rasmap (restored afterwards) so the same StoreAllMaps run produces them.

Generating these types causes RasMapperLib to build a PostProcessing.hdf cache that can exceed the plan HDF in size; ras2cng deletes it from the output directory unless --keep-postprocessing is passed.

Local performance policy

The default DEFAULT_LOCAL_MAP_PERFORMANCE preset is tuned for local processing on the 8-core, 31.8 GiB development workstation:

  • memory-aware automatic helper selection (max_workers=None);
  • enforced memory admission with an 8192 MiB / 25 percent reserve;
  • one GDAL thread per helper to prevent nested oversubscription;
  • a 64 MiB GDAL cache cap charged to every helper's memory estimate.

Only independent WSE, Depth, and Velocity products run concurrently. Large terrain estimates and products that require shared ordered state automatically use one helper. On the Spring River fixture, the measured estimate is about 11.2 GiB per helper, so this 31.8 GiB machine remains serial; a machine with more available memory can admit two or three map helpers without changing the call.

Use --map-workers 1 for a controlled serial comparison, or set the helper ceiling, reserve, and cache explicitly:

ras2cng map model.prj ./maps \
  --map-workers 2 \
  --map-reserve-memory-mb 8192 \
  --map-gdal-cache-mb 64

Python callers can provide the full typed policy without adding a second map function:

from ras_commander import StoreMapPerformanceOptions
from ras2cng import generate_result_maps

results = generate_result_maps(
    "model.prj",
    "maps",
    performance=StoreMapPerformanceOptions(
        max_workers=None,
        reserve_memory_mb=8192,
        gdal_cachemax_mb=64,
    ),
)

Render Mode

The --render-mode option controls how the water surface is rendered to raster grids. This is critical for pixel-perfect output — HEC-RAS 6.x's RasProcess.exe ignores the render mode from the .rasmap file, so ras-commander uses RasStoreMapHelper.exe to set the mode explicitly before generating maps.

Mode Flag Description
horizontal --render-mode horizontal Flat water surface within each mesh cell (default)
sloping --render-mode sloping Interpolated sloping water surface
slopingPretty --render-mode slopingPretty Sloping with depth-weighted face reduction (HEC-RAS 6.4+)

If --render-mode is not specified, the mode is read from the project's .rasmap file (defaults to horizontal if not set).

# Generate maps with sloping render mode
ras2cng map /path/to/project /output/maps --render-mode sloping

# Archive with slopingPretty render mode (requires HEC-RAS 6.4+)
ras2cng archive /path/to/project ./archive/ --results --map --render-mode slopingPretty

Mapping engine: RAS Mapper or fast-map

fast-map is the default engine. It maps selected products through the Rust ras-commander-fast-map engine and hands everything else to RAS Mapper (RasStoreMapHelper.exe) per product group, printing the reason; --engine rasmapper (or RAS2CNG_MAP_ENGINE=rasmapper) renders every product through RAS Mapper. The water-surface render mode comes from the project's .rasmap, as RAS Mapper takes it (--render-mode overrides it); a project with no stored mode goes to RAS Mapper, which applies its own default. fast-map is built for FIM library creation on pure 2D models, not for general use across all model types: every fast-map product is qualified against RAS Mapper output (pixel conformance against native HEC-RAS 7.0.1 stored maps on the named models), and everything else falls back to RAS Mapper. ras-commander installs the engine through ras-commander[full] on Windows x64 and Linux x64 (ras2cng[fast-map] requests it explicitly). The mapping arithmetic needs no GDAL, and with the source-terrain path below no HEC-RAS either.

# Default: Rust WSE/Depth, arrival time and percent inundated; the rest via RAS Mapper
ras2cng map /path/to/project /output/maps \
    --arrival-time --percent-inundated --arrival-depth 0.5 --ras-version 7.0.1

# Everything through RAS Mapper
ras2cng map /path/to/project /output/maps --engine rasmapper

# Reuse a terrain export across runs
ras2cng map /path/to/project /output/maps --engine fast-map \
    --fast-map-terrain /output/maps/_fast_map_terrain/Terrain50.tif

# Fail instead of falling back (qualification runs)
ras2cng map /path/to/project /output/maps --engine fast-map --fast-map-strict

# Map a plan with storage areas in Rust (opt-in; otherwise RAS Mapper maps it)
ras2cng map /path/to/project /output/maps --fast-map-storage-areas

RAS2CNG_MAP_ENGINE selects the engine everywhere, including ras2cng archive --map. Scope, engine and render mode are checked from the plan HDF and .rasmap before any terrain work, so an out-of-scope plan goes to RAS Mapper without a terrain export.

Product fast-map Qualification against RAS Mapper
WSE, Depth (Max) yes identical float32 values and masks on five models (1.2–3.6× faster for horizontal and plain sloping, 1.8–7.3× for depth-weighted sloping faces; evidence); Davis p02 and Bald Eagle bridges p05 again on the source-terrain path
WSE, Depth with storage areas opt-in (--fast-map-storage-areas; slower than RAS Mapper today), as RAS Mapper level pools, when the engine advertises storage-area-level-pool/1 identical on Bald Eagle p07 and p04 in every render mode (466,912 / 461,639 storage-area px); p07 Max sloping through ras2cng map: 0 mask and 0 bit differences on 1,345,691 px
Arrival time, percent time inundated yes (--no-fast-map-whole-simulation to opt out) identical on Davis p02 (4,879 px) and bridges p05 (959,043 px) at 0.5 ft, horizontal and plain sloping; with a storage area, p07 (1,333,183 px)
Duration yes, when the engine advertises RAS Mapper's recession rule (rasmapper-backward-window-recession/1); not with storage areas identical on Davis p02 and bridges p05 at 0.5 ft
Velocity (Max) yes in plain sloping and horizontal when the engine advertises velocity_depth; --no-fast-map-velocity to opt out; not with storage areas bridges p05: 0 value and 0 mask differences in sloping (973,902 px) and horizontal (973,532 px). Older engines: opt-in, plain sloping only
Velocity (Max), slopingPretty yes when the engine advertises rasmapper-with-faces-velocity-derived/1 (fast-map 0.16.0 / ras-commander 0.117.0, the versions ras2cng requires), with the .rasmap's shallow-reduction and depth-weighting flags passed unchanged; with older engines it is opt-in (--fast-map-velocity) and plain slopingPretty only 0 mask and 0 bit differences on bridges p05 and Davis p02 in all four option combinations (plain, shallow reduction, depth-weighted, both). The mask is the depth rendered with the same options, so the wrong flags give a different mask: an earlier 75 + 28 px difference on bridges compared a plain run with a shallow-reduction reference
D × V, D × V², Froude (Max) yes in plain sloping and horizontal (--no-fast-map-derived to opt out), and in slopingPretty under the same engine record as velocity; not with storage areas per-time product, pixelwise Max over every output time, as RAS Mapper computes it: 0 / 0 on bridges p05 over 433 times (973,956 px sloping); Davis within 2 ulp on ≤ 5 px. slopingPretty: 0 / 0 on bridges p05 and Davis p02, four option combinations
Shear stress (Max) yes in plain sloping and horizontal when RasFim.supports_shear_stress() is true (rasmapper-face-shear-max/1; fast-map 0.16.0 / ras-commander 0.117.0); --no-fast-map-shear to opt out; not in slopingPretty or with storage areas. With older engines: RAS Mapper 0 mask and 0 bit differences on bridges p05 (973,902 px sloping, 973,532 px horizontal) and Davis p02 (22,041 / 20,560 px). bridges 4.7 s against RAS Mapper's 84.8 s
Inundation boundary yes (see below): deterministic contours by default, the native-serial contract on request deterministic: close to, not identical with, RAS Mapper's polygons. native-serial: exact against RAS Mapper's serial boundary export on named fixtures only; the engine labels it unqualified

A plan is sent to RAS Mapper instead when:

Condition Why
1D river reaches or cross sections Outside the engine's method (RasFim.validate_2d_model)
Storage areas, unless --fast-map-storage-areas (fast_map_storage_areas=True, RAS2CNG_FAST_MAP_STORAGE_AREAS=1) is given Not a default until it is faster than RAS Mapper: Bald Eagle p07 WSE + Depth took 18.7 s in Rust against 12.2 s. Opt in to map storage-area plans without HEC-RAS (Linux, FIM batches)
Storage areas, opted in, with an engine that does not advertise storage-area-level-pool/1 It would leave the storage-area pixels blank
A profile other than Max (per-profile products only; arrival, duration and percent are whole-simulation) Timestep mapping is not wired through ras2cng yet. Decided before any terrain work
No usable terrain See below
Engine missing or failed No arithmetic fallback inside fast-map

Terrain. With ras-commander's RasFim.top_priority_terrain_source (ras-commander #724, fast-map #11), ras2cng maps on the terrain's unmodified priority-1 source TIFF, with its terrain-HDF footprint mask, and skips the RAS Mapper terrain export. Inside that footprint the source TIFF is the effective terrain, and the engine refuses when a wet cell would draw outside it. ras2cng then:

  1. retries on the source's CRS-canonical copy, only when the refusal was about the CRS (Davis);
  2. otherwise builds the native effective terrain once per run, when the engine advertises rasmapper-effective-terrain/1 and RasFim has build_effective_terrain: RAS Mapper's multi-source mosaic (stitch TIN first, then each source in priority order) rebuilt in Rust from the source TIFFs, their level-0 masks and the stitch TIN, without HEC-RAS. On Bald Eagle Terrain50 the valid mask is identical on 197,179,058 px and 8 values differ, all in stitch-TIN corners where RAS Mapper's own exports disagree (max 1.53 ft); it took 7.0 s and 1.4 GB, against about 190 s for the export. Terrains with modifications only on the conditions below. An unmodified terrain also needs a qualified HEC-RAS release (QUALIFIED_EFFECTIVE_RUNTIMES: 6.6, 6.7 Beta 4/5, 7.0, 7.0.1, 7.0.2; the 2026-11-12 qualification found base terrains on 6.5 and earlier differ from RAS Mapper, and later releases are unqualified): the run's release (--ras-version, else ras-commander's detection) or, when no installed HEC-RAS resolves one (Linux), the newest Program Version of the project's plan and geometry files. Any other release skips this step with reason_code: "hecras_version_unqualified", and a release that does not resolve with "hecras_version_unresolved" (pass --ras-version). The decision is recorded under effective_terrain in MapResult.fast_map_terrain_route (route native-effective or rasmapper-export, reason, reason_code, hecras_release, hecras_release_basis) and in the route manifest's effective_terrain list (TerrainResolver.effective_route). The priority-1 source TIFF path above builds no effective terrain and is used on any release;
  3. otherwise exports the plan's terrain once per run through RAS Mapper (RasTerrain.export_rasmapper_terrain, HEC-RAS 6.4.1/6.5/6.6/7.0.1/7.1; pass --ras-version).

--fast-map-terrain supplies a float32 export (with modifications) instead, --no-fast-map-effective-terrain skips step 2, and --no-fast-map-source-terrain skips the source TIFF.

Terrains with modifications. The earlier rule that every modified terrain goes to RAS Mapper (user decision 2026-10-30) is superseded: the project engineer confirmed the reversal on 2026-11-11, now that the native route is implemented. Before any of the steps above, ras2cng reads the terrain HDF's /Modifications group and the .rasmap's modification layers (ras2cng.terrain.terrain_modifications). If it finds any, or cannot read the terrain HDF, the source TIFF (and step 1) is skipped. The inundation boundary is drawn in Rust on the stored-map effective terrain when step 2 builds one (a single-source terrain, see below), and by RAS Mapper otherwise. Step 2 then builds the native effective terrain with the modifications applied only when every one of these holds (TerrainResolver.modified_route):

  • the installed engine advertises rasmapper-effective-terrain/2 (Fast-Map 0.18.0 and later; 0.17.0 advertises only /1) with a modifications record and accepts ras-commander-effective-terrain-request/2;
  • ras-commander has the terrain-modification reader that stages the engine's modification_layers, and it stages every layer without refusing one. ras2cng uses the public RasFim.read_terrain_modifications (ras-commander 0.119.0 and later) and falls back to the private ras_commander.fim._terrain_mods.read_layers on a ras-commander that has only that; with neither, the terrain goes to RAS Mapper. A polygon with more than one ring (holes or separate parts) is refused by the reader (ras-commander 0.119.0, code multi_ring_polygon) and goes to RAS Mapper with refusal_reason: "multi_ring_polygon" recorded;
  • every staged layer kind, ground-line subtype and elevation type is in the engine's qualified list (effective_terrain.modifications.supported), and no layer is a form the engine refuses (shape-Z polygons without boundary elevations, multi-part polygons that need a TIN);
  • the modification layers are readable and stored in the terrain HDF (not only in the .rasmap), HEC-RAS 6.6 projects have an engine that advertises hecras_version, and the effective terrain is enabled (--fast-map-effective-terrain, the default) and supported by RasFim;
  • the HEC-RAS release of the run resolves to one the engine's modification rules are qualified against: 6.6, 6.7 (Beta 4/5), 7.0, 7.0.1 or 7.0.2 (QUALIFIED_MODIFICATION_RUNTIMES; per-release qualification 2026-11-12, 0 mask and 0 value differences on every accepted layer). ras2cng resolves one release per run (TerrainResolver.hecras_runtime): --ras-version when given, else the release ras-commander's init_ras_project detects from the project's plan files, which is what the export uses. The export, Commander's reader and the native build all take it, so the two routes never follow different releases. Commander is given the release when it maps releases itself (ras-commander after 0.119.0, which picks the rule from the engine's advertised table), else the engine rule (MODIFICATION_RELEASE_RULES: 6.7 -> 6.6, 7.0.x -> 7.0.1), never a label that 0.119.0 or Fast-Map 0.18.0 would map wrongly or refuse. A release before 6.6 or after 7.0.2 (for example 6.5, 6.4.1, 7.1) keeps the terrain on the export with reason_code: "hecras_version_unqualified"; one that cannot be resolved also stays there. The 6.7 betas and 7.0.0 take the native route although the export refuses them (prerelease; 7.0.0's known modification-export defect), recorded as export_problem; if the engine then refuses the terrain, the export fallback fails as it always did for those releases.

Otherwise RAS Mapper's export builds the terrain (step 3), exactly as before, and the reason is recorded. An engine refusal on the native route (at build or mapping time) also falls back to the export. The decision is kept in MapResult.fast_map_terrain_route (per product: route is native-effective, rasmapper-export or unmodified (below; a native-effective route also records effective_terrain_basis, stored_map for a modified single-source terrain when the engine and ras-commander offer it, else export, and effective_terrain_basis_reason), with reason, the staged layers, hecras_runtime and hecras_runtime_basis (the one release both routes use, and where it came from), hecras_version (the engine rules), any refusal_reason, modification_reader (RasFim.read_terrain_modifications, ras_commander.fim._terrain_mods.read_layers or None) and any fallback) and in _fast_map_terrain/fast_map_terrain_route.json under the output folder. Each product group's entry in MapResult.fast_map_terrain_route is its own snapshot, taken when that group mapped (product_group, and terrain, the terrain kind it used), so a later group's fallback never appears on an earlier group's products; the manifest keeps the same per-group snapshots under product_groups[<plan HDF>][<group>]. Each run starts a new manifest: one left in the folder by an earlier run is removed.

Modification layers RAS Mapper does not apply. RAS Mapper (HEC-RAS 6.6, 7.0.1) applies a terrain's HDF modification layers only when its .rasmap layer has an ElevationModificationGroup named exactly Modifications. When ras-commander 0.119 reports that RAS Mapper applies none of them (RasFim.top_priority_terrain_source(..., rasmap_path=...) returns modified: False with a modification_group_misnamed or modification_group_missing warning), ras2cng maps the terrain as unmodified, as RAS Mapper does: the source TIFF and the unmodified effective terrain may be used. The route record has route: "unmodified", the HDF layers under modifications, and Commander's warning under rasmap_warnings and reason. When Commander cannot tell (no .rasmap, an unreadable terrain), the layers still count. Rust inundation boundaries still refuse such a terrain (they read the terrain HDF directly).

The native route is qualified through ras2cng map (ras-commander 0.119.0, Fast-Map 0.18.0, HEC-RAS 7.0.1 and 6.6) on Bald Eagle p08 with single-ring polygons and with rotated ellipses: 0 mask and 0 value differences in the modified area and in WSE, Depth and Velocity (Max) against two repeat RAS Mapper exports; the only whole-terrain differences are a few base-terrain stitch-TIN pixels that the unmodified native build shows too. Multi-ring polygons go to RAS Mapper with refusal_reason: "multi_ring_polygon". A terrain whose CRS has no EPSG code (for example ESRI:102630) takes the native route only when the engine's effective_terrain and sloping records advertise crs_any (Fast-Map 0.19+) and ras-commander passes it on; otherwise it goes to the export with the reason recorded (terrain_crs in the route record; Fast-Map's own qualification is in its feature_dev_notes/effective_terrain_modifications/modification_rules.md). Effective-terrain values change with /2 for unmodified terrains too: Fast-Map runs one rule, rasmapper-effective-terrain/2, for both request schemas, so schema 1 (no modifications) results from a /2 engine differ numerically from a /1 engine's (its receipts report /2). map-hdf with a single raw --terrain TIFF passes that TIFF directly.

Measured on a shared, loaded host:

Run Time Terrain
Bald Eagle bridges p05, WSE + Depth 4.5 s end to end, no HEC-RAS priority-1 source TIFF
bridges p05, WSE, Depth, velocity, arrival, percent 16.6 s reused export
bridges p05, same five, nothing supplied 181 s (≈160 s is the HEC-RAS export; arrival/percent were refused on the source) source, then export
RAS Mapper, bridges p05 ≈215 s for the seven Max products; ≈26 s for arrival/percent
Davis p02, all five 5.4 s, no HEC-RAS CRS-canonical source copy
bridges p05 sloping, nine products (adds velocity, D × V, D × V², Froude, duration) 251 s / 1.5 GB with one output time in flight in the derived pass; the derived pass alone is now 141 s / 2.6 GB source; effective terrain for arrival/duration/percent
RAS Mapper, the same nine 235 s / 2.4 GB; derived only 206 s / 2.3 GB; the other six 34 s
fast-map, the other six 25 s / 1.5 GB source and effective
Bald Eagle p07 (storage area), WSE + Depth 18.7 s / 1.5 GB (RAS Mapper: 12.2 s / 1.2 GB) native effective terrain (the source TIFF is refused: 28 storage-area pixels outside it)
p07, arrival + percent 31 s (RAS Mapper: 82 s) native effective terrain

Every fast-map product in the bridges and p07 rows was compared with RAS Mapper 7.0.1 stored maps: 0 mask and 0 bit differences (bridges: 18 products over sloping and horizontal; p07: 1,345,691 and 1,333,183 px).

Output. Products are named like RAS Mapper's (WSE (Max).tif, Depth (Max).tif, Velocity (Max).tif, D _ V (Max).tif, D _ V^2 (Max).tif, Froude (Max).tif, Arrival Time (0.5ft hrs).tif, Duration (0.5ft hrs).tif, Percent Time Inundated (0.5ft).tif) on the terrain's pixel grid, with NaN nodata, next to fast_map_manifest.json, fast_map_velocity_manifest.json, fast_map_derived_manifest.json and fast_map_whole_simulation_manifest.json (engine version, method, terrain, storage areas, timings). Arrival time is in hours since the simulation start. MapResult.engines records which engine produced each map type, MapResult.fast_map_skipped why a map type went to RAS Mapper under the fast-map engine (for example storage areas without the opt-in), and MapResult.fast_map_terrain which terrain fast-map used (source, source-canonical, effective, export, export-canonical or supplied; export-canonical is the RAS Mapper export's CRS-canonical copy, the same pixels with EPSG GeoTIFF keys, used only after the engine refuses the export's CRS identity). Velocity and shear stress are each their own engine call, so a refusal of either never costs WSE/Depth, and WSE/Depth keep the native GeoTIFF writer; in horizontal mode they are rendered plain sloping and clipped with the horizontal depth, as RAS Mapper does. Shear stress is written as Shear Stress (Max).tif with fast_map_shear_manifest.json. --min-depth, --wgs84 and --cog apply unchanged. Other options: --fast-map-threads (default CPUs − 1) and --fast-map-memory-mib (planned working memory; default a quarter of RAM, 1–16 GiB).

Invalid cell polygons. HEC-RAS can compute 2D cells whose face polylines cross. With ras-commander 0.110.2 or newer, fast-map maps those meshes under an explicit policy instead of refusing them:

--fast-map-invalid-cells Pixel ownership of an invalid cell
repair (engine default) polygonize the cell's faces, remove area owned by valid cells, keep the largest part
hull the face-point convex hull, with the same overlap removal
omit the cell owns no pixels
raise refuse; the products fall back to RAS Mapper (--fast-map-strict raises)

Hydraulic connectivity and interpolation always use the complete HDF topology; only pixel ownership changes. RAS Mapper's own rendering of such cells has not been qualified against repair. Every affected cell (mesh, cell id, reason, action, original and mapped area) is recorded as fim-invalid-cells/1 in MapResult.invalid_cells, fast_map_manifest.json and fast_map_whole_simulation_manifest.json, and a non-zero count is printed.

GeoTIFF delivery. With ras-commander-fast-map 0.11 the engine writes the sloping WSE/Depth GeoTIFFs itself (terrio, LZW) instead of handing float32 arrays back to Python for rasterio. --fast-map-writer auto (default) uses it when the engine supports it and velocity is not requested; native requires it and rasterio keeps the previous path (RAS2CNG_FAST_MAP_WRITER sets the default). On Bald Eagle bridges p05 Max the two writers gave identical pixels and the same LZW strip layout; native files were about 4% smaller and the engine call used about 18% less peak memory. --cog converts either through the shared COG policy with identical results. MapResult.fast_map_writer records the writer.

RAS Mapper's inundation-boundary export is very slow. With fast-map (the default engine), --inundation-boundary is mapped by the Rust engine (RasFim.map_inundation_boundaries) whenever the plan is in scope. In ras-commander's Davis pipes/conduits comparison, the Rust batch for Max plus one timestep took 3.5 s against 85 s for the two native RAS Mapper calls. It is not the default engine, but it is the recommended way to produce boundaries for pure 2D models.

# Rust WSE/Depth and boundary; velocity still through RAS Mapper
ras2cng map /path/to/project /output/maps --engine fast-map --inundation-boundary

# Explicit single-source terrain HDF (its TIFF is found beside it)
ras2cng map /path/to/project /output/maps --engine fast-map --inundation-boundary \
    --fast-map-terrain-hdf /path/to/project/Terrain/Terrain.hdf

# Keep boundaries on RAS Mapper while still using Rust rasters
ras2cng map /path/to/project /output/maps --engine fast-map --inundation-boundary \
    --no-fast-map-boundary

The default is a different method, not a copy of RAS Mapper's polygons. The Rust engine traces deterministic zero-depth contours (deterministic-zero-depth-contours/1): the same inputs always give byte-identical GeoJSON, on Windows and Linux and at any worker count. RAS Mapper's own boundary polygons are order-dependent and can differ between identical exports, so the two are close but not equal. On Davis Max the Rust contour had 66 holes and 47,426 vertices, against RAS Mapper's 65 and 47,396. Almost all of the 7,423 ft² difference was one hole that RAS Mapper filled. The Depth/WSE rasters are unaffected; they still match RAS Mapper bit for bit.

Modified terrains. A modified single-source terrain on the native route is contoured on the same stored-map effective terrain its rasters use (both methods). Tile masks come from the terrain HDF; tile-edge samples that a modification changed come from the effective terrain. This needs a ras-commander with that support (fast_map.commander_stored_map_boundaries); otherwise, and for an export-basis effective terrain or a terrain routed to the RAS Mapper export, the boundary goes to RAS Mapper with the reason. On Helena with two polygon modifications crossing the wet edge, the Rust boundaries equal RAS Mapper 7.0.1's (0 ft² difference, horizontal and sloping).

The native-serial method (opt-in)

ras2cng map /path/to/project /output/maps --inundation-boundary \
    --fast-map-boundary-method native-serial

--fast-map-boundary-method native-serial (fast_map_boundary_method, RAS2CNG_FAST_MAP_BOUNDARY_METHOD) asks the engine for its native-serial contour contract (rasmapper-serial-zero-depth-contours/1; since fast-map 0.15.0 and ras-commander 0.116.0). The engine and ras-commander label this method unqualified, and ras2cng requests it with that explicit opt-in. It is not the default.

What has been checked, and all that should be claimed: on Windows x64, in plain sloping, with original terrain layouts, the engine's boundary has the same valid geometry and the same unrounded coordinates (ring start, direction and part order aside) as the boundary RAS Mapper exports with its serial polygon loop, on the fixtures in ras-commander's mapping guide: Baxter (three steady profiles), Davis (Max and one saved time, 7.0.1), Bald Eagle (Max and one saved time, two terrain sources and a storage area) and Reese (mixed-model Max). Run through ras2cng map against RAS Mapper 7.0.1 on project copies:

Plan Polygons / holes / vertices Against RAS Mapper's serial export Rust, end to end RAS Mapper
Davis p02 Max 274 / 65 / 47,272 geometry and coordinates equal 4.0 s 44.6 s (serial)
Bald Eagle bridges p05 Max (two terrain sources) 194 / 344 / 108,189 geometry and coordinates equal 8.9 s 8.5 s (ordinary), 12.4 s (serial)
Bald Eagle p07 Max (two sources, one storage area; --fast-map-storage-areas) 117 / 214 / 104,486 geometry and coordinates equal 17.2 s 8.0 s (ordinary), 10.8 s (serial)

RAS Mapper's ordinary export is not serial, and its polygons have differed between identical exports. On bridges p05 and p07 the ordinary export happened to equal the serial one; that is an observation on two plans, not a claim that the method reproduces every RAS Mapper shapefile. Other models, other profiles, modified terrains and other platforms are not covered.

A terrain CRS without an EPSG code (for example ESRI:102630, whose RAS Mapper source TIFFs carry no CRS tags) takes both boundary methods when the engine's boundary methods advertise crs_any (Fast-Map 0.19+) and ras-commander reads the terrain HDF Projection for the untagged source (the release after 0.119.0). The GeoJSON carries GDAL's WKT of that CRS and reads back exactly. On unmodified Helena (Middle Cahaba p01 Max, 7.0.1) the native-serial boundary equals RAS Mapper's ordinary export (821 polygons, 320 holes, 712,847 vertices). With older engines or Commander releases the boundary goes to RAS Mapper with the refusal recorded.

Scope in ras2cng: the Max profile, plain sloping, unmodified terrains. A terrain with several source TIFFs is accepted (ras2cng passes the first one in the terrain HDF's priority order; the engine checks it and refuses a wrong one). Storage areas are included only with --fast-map-storage-areas. Anything else falls back to RAS Mapper. The boundary manifest records ras2cng.boundary_method.

Extra scope for deterministic boundaries, on top of the pure-2D rules above (each falls back to RAS Mapper on its own, so the rasters can still use Rust):

Condition Why
Terrain with more than one source TIFF The deterministic method needs the original terrain HDF's masks, perimeters and stitch TIN for a single source. The flattened raster export cannot stand in for them. --fast-map-boundary-method native-serial takes every source
Terrain modifications Refused by ras2cng before the engine runs (terrain_modifications): boundaries on modified terrains always go to RAS Mapper, even when the raster products use the native effective terrain with modifications
slopingPretty render mode Contours support horizontal and plain sloping only
ras-commander without RasFim.map_inundation_boundaries Introduced in ras-commander 0.113.0; ras2cng requires 0.119.0
Storage areas The deterministic method draws 2D cells only; the level pool would be missing. The native-serial method includes them when storage areas are opted in
A terrain CRS the engine and rasterio read differently (Davis), without --fast-map-terrain-crs-hash The engine cannot name an EPSG code for it; ras2cng never guesses the identity (see below)

User-supplied terrain CRS. When the engine cannot name the terrain's EPSG code and reads its WKT differently from rasterio (Davis), the boundary falls back to RAS Mapper, and the message prints the engine's WKT hash, for example:

engine terrain CRS differs from rasterio CRS EPSG:2871; the engine reports
crs_wkt_fnv1a64=e446f7bd6bdb4d7f for Terrain (1).Davis_terrain2.tif ...

Check the CRS first (ras2fim-batch terrain-info <terrain.tif> prints the engine's WKT and crs_wkt_fnv1a64), then pass the hash:

ras2cng map /path/to/Davis /output/maps --inundation-boundary \
    --fast-map-terrain-crs-hash e446f7bd6bdb4d7f

The Python API takes fast_map_terrain_crs_fnv1a64=. It applies to the boundary terrain only, is used only when the engine reports no EPSG code, and a value that does not equal the engine's hash is refused. The boundary manifest records it as ras2cng.terrain_crs_fnv1a64.

Output. Inundation Boundary (Max).geojson: a MultiPolygon with holes, in the model CRS. RAS Mapper writes a shapefile. It sits next to fast_map_boundary_manifest.json, which records the method, polygon/hole/vertex counts, area, terrain and timings. A plan with no flooded area writes no boundary.

Post-Processing Options

  • Minimum depth threshold (--min-depth): Set pixels below a depth threshold to NoData
  • WGS84 reprojection (--wgs84): Reproject output rasters to EPSG:4326 (<name>_wgs84.tif), with terrio when the installed build has the streaming warp (the CLB terrio build) and otherwise with rasterio; the grid is the same and values agree to float rounding (RAS2CNG_REPROJECT_ENGINE = auto/terrio/rasterio). A raster that cannot be reprojected is an error. Before 0.16 this option did nothing: a wrong import was caught and the rasters were returned in the model CRS with a "rasterio not available" warning. Rasters published with --wgs84 from an earlier version are in the model CRS; check their CRS and re-run.
  • Cloud Optimized GeoTIFF (--cog): Convert output to COG using gdal_translate

API Reference

ras2cng.mapping.MapResult dataclass

Result of map generation for a single plan.

Source code in ras2cng/mapping.py
@dataclass
class MapResult:
    """Result of map generation for a single plan."""
    plan_id: str
    plan_number: str
    map_types: dict[str, list[Path]] = field(default_factory=dict)  # {"depth": [Path(...)]}
    output_dir: Path = field(default_factory=lambda: Path("."))
    errors: list[str] = field(default_factory=list)
    # Engine that produced each map type: "rasmapper" or "fast-map".
    engines: dict[str, str] = field(default_factory=dict)
    # For fast-map products, the terrain the engine mapped on: "supplied"
    # (--fast-map-terrain), "source" (the priority-1 terrain source TIFF, no
    # export), "source-canonical" (its CRS-canonical copy), "effective" (RAS
    # Mapper's effective terrain rebuilt in Rust), "export" (the RAS Mapper
    # terrain export) or "export-canonical" (the export's CRS-canonical copy).
    fast_map_terrain: dict[str, str] = field(default_factory=dict)
    # For fast-map products, the engine's ``fim-invalid-cells/1`` record
    # (ras-commander 0.110.2+): the policy, the count and every cell whose
    # face polylines do not form a valid polygon, with the action taken.
    # Absent for map types RAS Mapper produced or older ras-commander.
    invalid_cells: dict[str, dict] = field(default_factory=dict)
    # For fast-map sloping WSE/Depth/velocity, how the GeoTIFFs were written:
    # "native" (terrio LZW, in the engine) or "rasterio".
    fast_map_writer: dict[str, str] = field(default_factory=dict)
    # With the fast-map engine, why a map type went to RAS Mapper instead
    # (e.g. storage areas without --fast-map-storage-areas, 1D elements, a
    # non-Max profile). Empty under --engine rasmapper.
    fast_map_skipped: dict[str, str] = field(default_factory=dict)
    # For fast-map products on a modified terrain, the routing decision
    # (fast_map.TerrainResolver.modified_route): ``route`` is
    # "native-effective" (rasmapper-effective-terrain/2 with modifications)
    # or "rasmapper-export", with the ``reason`` for the export and any
    # engine ``fallback``. Absent for unmodified terrains.
    fast_map_terrain_route: dict[str, dict] = field(default_factory=dict)

ras2cng.mapping.generate_result_maps(project_path, output_dir, *, plans=None, profile='Max', wse=True, depth=True, velocity=True, froude=False, shear_stress=False, depth_x_velocity=False, depth_x_velocity_sq=False, inundation_boundary=False, arrival_time=False, duration=False, recession=False, percent_inundated=False, arrival_depth=0.0, terrain_name=None, ras_version=None, rasprocess_path=None, render_mode=None, min_depth=0.0, reproject_wgs84=False, convert_cog=False, timeout=10800, skip_errors=True, keep_postprocessing=False, performance=None, map_engine=None, fast_map_terrain=None, fast_map_threads=None, fast_map_fallback=True, fast_map_memory_mib=None, fast_map_boundary=True, fast_map_terrain_hdf=None, fast_map_source_terrain=True, fast_map_whole_simulation=True, fast_map_velocity=None, fast_map_invalid_cells=None, fast_map_writer=None, fast_map_derived=True, fast_map_effective_terrain=True, fast_map_storage_areas=None, fast_map_terrain_crs_fnv1a64=None, fast_map_shear=True, fast_map_boundary_method=None, native_only=False)

Generate result rasters for plans in a HEC-RAS project.

Uses the canonical RasMap.store_all_maps(mode="selected") API with RasStoreMapHelper.exe to generate raw TIFs from completed plan HDF files. With ras-commander 0.99.0 or newer, the default is memory-aware local auto parallelism. ras-commander 0.98.2 retains its serial compatibility path.

Parameters:

Name Type Description Default
project_path Path

Path to .prj file or project directory

required
output_dir Path

Directory for output raster files

required
plans Optional[list[str]]

Plan IDs to process (e.g. ["p01", "p02"]). None = all with results

None
profile str

Output profile: "Max", "Min", an exact named steady profile, or an exact unsteady timestamp

'Max'
wse bool

Generate Water Surface Elevation rasters

True
depth bool

Generate Depth rasters

True
velocity bool

Generate Velocity rasters

True
froude bool

Generate Froude Number rasters

False
shear_stress bool

Generate Shear Stress rasters

False
depth_x_velocity bool

Generate Depth x Velocity rasters

False
depth_x_velocity_sq bool

Generate Depth x Velocity² rasters

False
inundation_boundary bool

Generate Inundation Boundary polygon (shapefile)

False
arrival_time bool

Generate Arrival Time rasters (hours; whole-simulation, ignores profile)

False
duration bool

Generate Duration rasters (hours; whole-simulation)

False
recession bool

Not supported — RasMapperLib has no recession map type; a warning is printed and the flag is ignored

False
percent_inundated bool

Generate Percent Time Inundated rasters

False
arrival_depth float

Wet/dry depth threshold (model vertical units) for arrival/duration/recession/percent_inundated (default: 0.0)

0.0
terrain_name Optional[str]

Specific terrain name from rasmap to use for mapping

None
ras_version Optional[str]

HEC-RAS version (auto-detected if None)

None
rasprocess_path Optional[Path]

Path to HEC-RAS install directory (for helper deployment)

None
render_mode Optional[str]

Water surface render mode: "horizontal", "sloping", or "slopingPretty". If None, reads from the .rasmap file (default: horizontal).

None
min_depth float

Minimum depth threshold for depth rasters (default: 0.0)

0.0
reproject_wgs84 bool

Reproject output rasters to WGS84

False
convert_cog bool

Convert output to Cloud Optimized GeoTIFF

False
timeout int

Per-plan timeout in seconds (default: 10800 = 3 hours)

10800
skip_errors bool

If True, log and continue past errors

True
keep_postprocessing bool

Keep the PostProcessing.hdf cache RasMapperLib creates for derived map types (can exceed the plan HDF in size). Default: delete it from the output directory.

False
performance Optional['StoreMapPerformanceOptions']

Optional ras-commander StoreMap performance policy. None selects :data:DEFAULT_LOCAL_MAP_PERFORMANCE when the canonical API is available. Pass StoreMapPerformanceOptions(max_workers=1) for the legacy serial execution policy.

None
map_engine Optional[str]

"fast-map" (default) maps, on pure 2D models, the products the Rust ras-commander-fast-map engine is qualified for against RAS Mapper stored maps (Max WSE/Depth, velocity, D x V, D x V², Froude, shear stress, arrival time, percent inundated, duration, each as far as the installed engine advertises it; storage areas as level pools) and the inundation boundary through deterministic contours (much faster than RAS Mapper's export; close to, not identical with, its polygons). It is built for FIM library creation, not every model type: 1D elements, other profiles and unqualified render modes fall back to RAS Mapper per product group. "rasmapper" renders every map type through RAS Mapper. None reads RAS2CNG_MAP_ENGINE, else fast_map.DEFAULT_MAP_ENGINE. The render mode comes from the project's .rasmap unless render_mode is given. See :mod:ras2cng.fast_map for scope.

None
fast_map_terrain Optional[Path]

Float32 GeoTIFF of the registered terrain (with modifications) for fast-map. None maps on the priority-1 source TIFF where the engine accepts it, else on the native effective terrain, else exports the plan's terrain once per run through RAS Mapper.

None
fast_map_threads Optional[int]

Rust worker count (default: CPUs - 1, max 64).

None
fast_map_memory_mib Optional[int]

Planned engine memory budget in MiB (default: a quarter of physical RAM, 1-16 GiB). Not a hard RSS limit.

None
fast_map_boundary bool

With fast-map, also map the inundation boundary in Rust (written as Inundation Boundary (Max).geojson). False keeps boundaries on RAS Mapper (shapefile).

True
fast_map_terrain_hdf Optional[Path]

Original single-source terrain HDF for Rust boundaries; its TIFF is found beside it. None uses the plan's terrain (or terrain_name).

None
fast_map_source_terrain bool

With fast-map and no fast_map_terrain, map on the terrain's priority-1 source TIFF first, skipping the RAS Mapper terrain export, and export only when the engine refuses (a wet cell draws outside that source's footprint). Needs ras-commander with RasFim.top_priority_terrain_source.

True
fast_map_whole_simulation bool

With fast-map, also map arrival_time and percent_inundated in Rust (threshold arrival_depth; horizontal and plain sloping), and duration when the engine advertises RAS Mapper's recession rule (fast-map

20) and the plan has no storage areas. Needs

RasFim.map_whole_simulation.

True
fast_map_velocity Optional[bool]

None (default): map Max velocity in Rust in plain sloping and horizontal mode when the engine has the fast-map #20 velocity rules (0 value / 0 mask differences on bridges p05), and in slopingPretty, with the .rasmap's shallow-reduction and depth-weighting flags passed unchanged, when the engine advertises rasmapper-with-faces-velocity-derived/1 (0 / 0 on bridges p05 and Davis p02 in all four option combinations). True also maps plain slopingPretty velocity on an engine without that record, and plain sloping on older engines. False leaves velocity to RAS Mapper.

None
fast_map_derived bool

With fast-map, map Max D x V, D x V² and Froude in Rust (one time-series pass, reduce_max/1) in plain sloping and horizontal mode, and in slopingPretty under the same engine record as velocity. False leaves them to RAS Mapper.

True
fast_map_shear bool

With fast-map, map Max shear stress in Rust (Shear Stress (Max).tif) in plain sloping and horizontal mode when RasFim.supports_shear_stress() is true (rasmapper-face-shear-max/1; 0 mask / 0 bit differences on bridges p05 and Davis p02). slopingPretty and storage-area plans stay on RAS Mapper. False leaves shear stress to RAS Mapper.

True
fast_map_boundary_method Optional[str]

"deterministic" (default) or "native-serial" (opt-in; None reads RAS2CNG_FAST_MAP_BOUNDARY_METHOD). native-serial requests the engine's rasmapper-serial-zero-depth-contours/1 contract: plain sloping, every original terrain source, storage areas when opted in. The engine labels it unqualified; see :func:ras2cng.fast_map.map_boundary for exactly what has been checked against RAS Mapper's serial boundary export.

None
fast_map_effective_terrain bool

Before exporting the terrain through RAS Mapper, try RAS Mapper's effective terrain rebuilt in Rust (fast-map #19). Modified terrains use it only with an engine advertising rasmapper-effective-terrain/2 and every modification form qualified (see MapResult.fast_map_terrain_route). False skips it.

True
fast_map_storage_areas Optional[bool]

Map plans with storage areas in Rust, drawing them as RAS Mapper level pools (WSE/Depth, arrival time, percent inundated; qualified 0/0 on Bald Eagle p07/p04). Opt-in: it is slower than RAS Mapper today (p07 WSE + Depth 18.7 s vs 12.2 s), so by default (None reads RAS2CNG_FAST_MAP_STORAGE_AREAS, else off) such plans go wholly to RAS Mapper, and MapResult.fast_map_skipped says why. Use it to map storage-area plans without HEC-RAS (Linux, FIM batches).

None
fast_map_terrain_crs_fnv1a64 Optional[str]

For Rust inundation boundaries only: the engine's WKT hash (crs_wkt_fnv1a64) of the boundary terrain TIFF, accepted when the engine cannot identify the terrain's EPSG code and its CRS reads differently from rasterio's (e.g. Davis). ras2cng never guesses it: obtain it with ras2fim-batch terrain-info <terrain.tif> (or from the refusal message, which prints it), check the CRS is right, and pass it. A mismatch with the engine's hash is refused.

None
fast_map_invalid_cells Optional[str]

Pixel ownership for 2D cells whose face polylines do not form a valid polygon: "repair" (the engine default), "hull", "omit" or "raise" (refuse, so the products fall back to RAS Mapper). None keeps the engine default. Needs ras-commander 0.110.2+; the affected cells are recorded in MapResult.invalid_cells and the fast-map manifests.

None
fast_map_writer Optional[str]

Sloping GeoTIFF delivery: "auto" (default; native terrio LZW when the engine supports it and velocity is not requested), "native" (required) or "rasterio". None reads RAS2CNG_FAST_MAP_WRITER. Both give identical pixels and the same LZW strip layout; --cog still goes through :mod:ras2cng.cog.

None
native_only bool

Map with fast-map only, on fast_map_terrain, and never call RAS Mapper (no HEC-RAS terrain is needed or used). Requires the fast-map engine and fast_map_terrain; implies fast_map_fallback=False. Any requested product fast-map cannot map raises :class:ras2cng.fast_map.FastMapUnavailable, whatever skip_errors says.

False
fast_map_fallback bool

When a plan is outside fast-map's scope (1D elements, a non-Max profile, no usable terrain, engine missing or failed), render it through RAS Mapper instead. False raises.

True

Returns:

Type Description
list[MapResult]

List of MapResult, one per processed plan

Source code in ras2cng/mapping.py
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
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
267
268
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
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
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
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
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
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
def generate_result_maps(
    project_path: Path,
    output_dir: Path,
    *,
    plans: Optional[list[str]] = None,
    profile: str = "Max",
    wse: bool = True,
    depth: bool = True,
    velocity: bool = True,
    froude: bool = False,
    shear_stress: bool = False,
    depth_x_velocity: bool = False,
    depth_x_velocity_sq: bool = False,
    inundation_boundary: bool = False,
    arrival_time: bool = False,
    duration: bool = False,
    recession: bool = False,
    percent_inundated: bool = False,
    arrival_depth: float = 0.0,
    terrain_name: Optional[str] = None,
    ras_version: Optional[str] = None,
    rasprocess_path: Optional[Path] = None,
    render_mode: Optional[str] = None,
    min_depth: float = 0.0,
    reproject_wgs84: bool = False,
    convert_cog: bool = False,
    timeout: int = 10800,
    skip_errors: bool = True,
    keep_postprocessing: bool = False,
    performance: Optional["StoreMapPerformanceOptions"] = None,
    map_engine: Optional[str] = None,
    fast_map_terrain: Optional[Path] = None,
    fast_map_threads: Optional[int] = None,
    fast_map_fallback: bool = True,
    fast_map_memory_mib: Optional[int] = None,
    fast_map_boundary: bool = True,
    fast_map_terrain_hdf: Optional[Path] = None,
    fast_map_source_terrain: bool = True,
    fast_map_whole_simulation: bool = True,
    fast_map_velocity: Optional[bool] = None,
    fast_map_invalid_cells: Optional[str] = None,
    fast_map_writer: Optional[str] = None,
    fast_map_derived: bool = True,
    fast_map_effective_terrain: bool = True,
    fast_map_storage_areas: Optional[bool] = None,
    fast_map_terrain_crs_fnv1a64: Optional[str] = None,
    fast_map_shear: bool = True,
    fast_map_boundary_method: Optional[str] = None,
    native_only: bool = False,
) -> list[MapResult]:
    """Generate result rasters for plans in a HEC-RAS project.

    Uses the canonical ``RasMap.store_all_maps(mode="selected")`` API with
    RasStoreMapHelper.exe to generate raw TIFs from completed plan HDF files.
    With ras-commander 0.99.0 or newer, the default is memory-aware local auto
    parallelism. ras-commander 0.98.2 retains its serial compatibility path.

    Args:
        project_path: Path to .prj file or project directory
        output_dir: Directory for output raster files
        plans: Plan IDs to process (e.g. ["p01", "p02"]). None = all with results
        profile: Output profile: "Max", "Min", an exact named steady profile,
            or an exact unsteady timestamp
        wse: Generate Water Surface Elevation rasters
        depth: Generate Depth rasters
        velocity: Generate Velocity rasters
        froude: Generate Froude Number rasters
        shear_stress: Generate Shear Stress rasters
        depth_x_velocity: Generate Depth x Velocity rasters
        depth_x_velocity_sq: Generate Depth x Velocity² rasters
        inundation_boundary: Generate Inundation Boundary polygon (shapefile)
        arrival_time: Generate Arrival Time rasters (hours; whole-simulation,
            ignores `profile`)
        duration: Generate Duration rasters (hours; whole-simulation)
        recession: Not supported — RasMapperLib has no recession map type;
            a warning is printed and the flag is ignored
        percent_inundated: Generate Percent Time Inundated rasters
        arrival_depth: Wet/dry depth threshold (model vertical units) for
            arrival/duration/recession/percent_inundated (default: 0.0)
        terrain_name: Specific terrain name from rasmap to use for mapping
        ras_version: HEC-RAS version (auto-detected if None)
        rasprocess_path: Path to HEC-RAS install directory (for helper deployment)
        render_mode: Water surface render mode: "horizontal", "sloping", or "slopingPretty".
            If None, reads from the .rasmap file (default: horizontal).
        min_depth: Minimum depth threshold for depth rasters (default: 0.0)
        reproject_wgs84: Reproject output rasters to WGS84
        convert_cog: Convert output to Cloud Optimized GeoTIFF
        timeout: Per-plan timeout in seconds (default: 10800 = 3 hours)
        skip_errors: If True, log and continue past errors
        keep_postprocessing: Keep the PostProcessing.hdf cache RasMapperLib
            creates for derived map types (can exceed the plan HDF in size).
            Default: delete it from the output directory.
        performance: Optional ras-commander StoreMap performance policy. None
            selects :data:`DEFAULT_LOCAL_MAP_PERFORMANCE` when the canonical
            API is available. Pass ``StoreMapPerformanceOptions(max_workers=1)``
            for the legacy serial execution policy.
        map_engine: ``"fast-map"`` (default) maps, on pure 2D models, the
            products the Rust ``ras-commander-fast-map`` engine is qualified
            for against RAS Mapper stored maps (Max WSE/Depth, velocity, D x V,
            D x V², Froude, shear stress, arrival time, percent inundated,
            duration, each as far as the installed engine advertises it;
            storage areas as level pools) and the inundation boundary through
            deterministic contours (much faster than RAS Mapper's export;
            close to, not identical with, its polygons). It is built for FIM
            library creation, not every model type: 1D elements, other
            profiles and unqualified render modes fall back to RAS Mapper per
            product group. ``"rasmapper"`` renders every map type
            through RAS Mapper. None reads ``RAS2CNG_MAP_ENGINE``, else
            ``fast_map.DEFAULT_MAP_ENGINE``. The render mode comes from the
            project's ``.rasmap`` unless ``render_mode`` is given. See
            :mod:`ras2cng.fast_map` for scope.
        fast_map_terrain: Float32 GeoTIFF of the registered terrain (with
            modifications) for fast-map. None maps on the priority-1 source
            TIFF where the engine accepts it, else on the native effective
            terrain, else exports the plan's terrain once per run through RAS
            Mapper.
        fast_map_threads: Rust worker count (default: CPUs - 1, max 64).
        fast_map_memory_mib: Planned engine memory budget in MiB (default: a
            quarter of physical RAM, 1-16 GiB). Not a hard RSS limit.
        fast_map_boundary: With fast-map, also map the inundation boundary
            in Rust (written as ``Inundation Boundary (Max).geojson``).
            False keeps boundaries on RAS Mapper (shapefile).
        fast_map_terrain_hdf: Original single-source terrain HDF for Rust
            boundaries; its TIFF is found beside it. None uses the plan's
            terrain (or ``terrain_name``).
        fast_map_source_terrain: With fast-map and no ``fast_map_terrain``,
            map on the terrain's priority-1 source TIFF first, skipping the
            RAS Mapper terrain export, and export only when the engine refuses
            (a wet cell draws outside that source's footprint). Needs
            ras-commander with ``RasFim.top_priority_terrain_source``.
        fast_map_whole_simulation: With fast-map, also map
            ``arrival_time`` and ``percent_inundated`` in Rust (threshold
            ``arrival_depth``; horizontal and plain sloping), and ``duration``
            when the engine advertises RAS Mapper's recession rule (fast-map
            #20) and the plan has no storage areas. Needs
            ``RasFim.map_whole_simulation``.
        fast_map_velocity: ``None`` (default): map Max velocity in Rust in
            plain sloping and horizontal mode when the engine has the
            fast-map #20 velocity rules (0 value / 0 mask differences on
            bridges p05), and in slopingPretty, with the ``.rasmap``'s
            shallow-reduction and depth-weighting flags passed unchanged,
            when the engine advertises
            ``rasmapper-with-faces-velocity-derived/1`` (0 / 0 on bridges p05
            and Davis p02 in all four option combinations). ``True`` also
            maps plain slopingPretty velocity on an engine without that
            record, and plain sloping on older engines. ``False`` leaves
            velocity to RAS Mapper.
        fast_map_derived: With fast-map, map Max D x V, D x V² and Froude in
            Rust (one time-series pass, ``reduce_max/1``) in plain sloping and
            horizontal mode, and in slopingPretty under the same engine record
            as velocity. False leaves them to RAS Mapper.
        fast_map_shear: With fast-map, map Max shear stress in Rust
            (``Shear Stress (Max).tif``) in plain sloping and horizontal mode
            when ``RasFim.supports_shear_stress()`` is true
            (``rasmapper-face-shear-max/1``; 0 mask / 0 bit differences on
            bridges p05 and Davis p02). slopingPretty and storage-area plans
            stay on RAS Mapper. False leaves shear stress to RAS Mapper.
        fast_map_boundary_method: ``"deterministic"`` (default) or
            ``"native-serial"`` (opt-in; None reads
            ``RAS2CNG_FAST_MAP_BOUNDARY_METHOD``). native-serial requests the
            engine's ``rasmapper-serial-zero-depth-contours/1`` contract:
            plain sloping, every original terrain source, storage areas when
            opted in. The engine labels it unqualified; see
            :func:`ras2cng.fast_map.map_boundary` for exactly what has been
            checked against RAS Mapper's serial boundary export.
        fast_map_effective_terrain: Before exporting the terrain through RAS
            Mapper, try RAS Mapper's effective terrain rebuilt in Rust
            (fast-map #19). Modified terrains use it only with an engine
            advertising ``rasmapper-effective-terrain/2`` and every
            modification form qualified (see
            ``MapResult.fast_map_terrain_route``). False skips it.
        fast_map_storage_areas: Map plans with storage areas in Rust, drawing
            them as RAS Mapper level pools (WSE/Depth, arrival time, percent
            inundated; qualified 0/0 on Bald Eagle p07/p04). **Opt-in**: it
            is slower than RAS Mapper today (p07 WSE + Depth 18.7 s vs
            12.2 s), so by default (``None`` reads
            ``RAS2CNG_FAST_MAP_STORAGE_AREAS``, else off) such plans go wholly
            to RAS Mapper, and ``MapResult.fast_map_skipped`` says why. Use it
            to map storage-area plans without HEC-RAS (Linux, FIM batches).
        fast_map_terrain_crs_fnv1a64: For Rust inundation boundaries only:
            the engine's WKT hash (``crs_wkt_fnv1a64``) of the boundary
            terrain TIFF, accepted when the engine cannot identify the
            terrain's EPSG code and its CRS reads differently from rasterio's
            (e.g. Davis). ras2cng never guesses it: obtain it with
            ``ras2fim-batch terrain-info <terrain.tif>`` (or from the refusal
            message, which prints it), check the CRS is right, and pass it.
            A mismatch with the engine's hash is refused.
        fast_map_invalid_cells: Pixel ownership for 2D cells whose face
            polylines do not form a valid polygon: ``"repair"`` (the engine
            default), ``"hull"``, ``"omit"`` or ``"raise"`` (refuse, so the
            products fall back to RAS Mapper). None keeps the engine default.
            Needs ras-commander 0.110.2+; the affected cells are recorded in
            ``MapResult.invalid_cells`` and the fast-map manifests.
        fast_map_writer: Sloping GeoTIFF delivery: ``"auto"`` (default;
            native terrio LZW when the engine supports it and velocity is not
            requested), ``"native"`` (required) or ``"rasterio"``. None reads
            ``RAS2CNG_FAST_MAP_WRITER``. Both give identical pixels and the
            same LZW strip layout; ``--cog`` still goes through
            :mod:`ras2cng.cog`.
        native_only: Map with fast-map only, on ``fast_map_terrain``, and
            never call RAS Mapper (no HEC-RAS terrain is needed or used).
            Requires the fast-map engine and ``fast_map_terrain``; implies
            ``fast_map_fallback=False``. Any requested product fast-map
            cannot map raises :class:`ras2cng.fast_map.FastMapUnavailable`,
            whatever ``skip_errors`` says.
        fast_map_fallback: When a plan is outside fast-map's scope (1D
            elements, a non-Max profile, no usable terrain, engine missing or
            failed), render it through RAS Mapper instead. False raises.

    Returns:
        List of MapResult, one per processed plan
    """
    from ras2cng import fast_map as _fast_map
    from ras2cng.project import resolve_project_path

    # Validate fast-map options before any project or engine work.
    fast_map_invalid_cells = _fast_map.normalize_invalid_cells(fast_map_invalid_cells)
    fast_map_writer = _fast_map.resolve_product_writer(fast_map_writer)
    fast_map_storage_areas = _fast_map.resolve_storage_areas(fast_map_storage_areas)
    fast_map_terrain_crs_fnv1a64 = _fast_map.normalize_crs_fnv1a64(
        fast_map_terrain_crs_fnv1a64
    )
    fast_map_boundary_method = _fast_map.resolve_boundary_method(fast_map_boundary_method)

    if native_only:
        native_engine = _fast_map.resolve_map_engine(map_engine)
        if native_engine != _fast_map.FAST_MAP:
            raise ValueError(
                f"native-only mapping needs the fast-map engine (got {native_engine!r})"
            )
        if fast_map_terrain is None:
            raise ValueError(
                "native-only mapping needs fast_map_terrain (--fast-map-terrain): "
                "a float32 GeoTIFF of the terrain to map on"
            )
        if not Path(fast_map_terrain).is_file():
            raise FileNotFoundError(f"fast-map terrain not found: {fast_map_terrain}")
        # Fail closed: nothing may fall back to RAS Mapper.
        fast_map_fallback = False

    project_path = Path(project_path)
    # Absolute: RAS Mapper resolves a relative folder against the project, so
    # its rasters would land under the project instead of here.
    output_dir = Path(output_dir).resolve()
    output_dir.mkdir(parents=True, exist_ok=True)

    project_dir, prj_file = resolve_project_path(project_path)

    console.print(f"\n[bold cyan]ras2cng map[/bold cyan] -> {output_dir}")
    console.print(f"  Project : {prj_file.name}")
    console.print(f"  Profile : {profile}")

    engine = _fast_map.resolve_map_engine(map_engine)
    terrain_resolver = None
    if engine == _fast_map.FAST_MAP:
        rust_products = ["WSE/Depth"]
        if fast_map_velocity is not False:
            rust_products.append("velocity")
        if fast_map_derived:
            rust_products.append("D x V/Froude (Max)")
        if fast_map_shear:
            rust_products.append("shear stress (Max)")
        if fast_map_whole_simulation:
            rust_products.append("arrival time/percent inundated/duration")
        if fast_map_boundary:
            rust_products.append("inundation boundary")
        if fast_map_storage_areas:
            rust_products.append("storage areas (opt-in)")
        console.print(
            f"  Engine  : fast-map (Rust) for {', '.join(rust_products)} on pure 2D "
            "models (FIM library scope) where the installed engine is qualified; "
            "RAS Mapper for everything else"
        )
        terrain_resolver = _fast_map.TerrainResolver(
            prj_file,
            output_dir / "_fast_map_terrain",
            terrain_path=fast_map_terrain,
            terrain_name=terrain_name,
            ras_version=ras_version,
            terrain_hdf=fast_map_terrain_hdf,
            effective=fast_map_effective_terrain,
            threads=fast_map_threads,
            max_working_mib=fast_map_memory_mib,
        )
    else:
        console.print("  Engine  : RAS Mapper")

    optimized_store_maps = _supports_optimized_store_maps()
    if performance is not None and not optimized_store_maps:
        raise RuntimeError(
            "performance requires ras-commander>=0.99.0; upgrade ras-commander "
            "or omit performance to use the serial compatibility path"
        )
    if performance is not None:
        effective_performance = performance
    elif optimized_store_maps:
        effective_performance = DEFAULT_LOCAL_MAP_PERFORMANCE
    else:
        effective_performance = None
    if effective_performance is not None:
        worker_label = (
            "auto"
            if effective_performance.max_workers is None
            else str(effective_performance.max_workers)
        )
        console.print(
            f"  Mapping : {worker_label} helper(s), "
            f"{effective_performance.memory_policy} memory admission"
        )
    else:
        console.print("  Mapping : serial compatibility path")

    # Configure RasProcess
    _configure_rasprocess(rasprocess_path, ras_version)

    # Initialize project (pass ras_version to avoid auto-detecting old versions from plan files)
    init_kwargs = dict(ras_object="new", load_results_summary=True)
    if ras_version:
        init_kwargs["ras_version"] = ras_version
    ras = init_ras_project(project_dir, **init_kwargs)
    if rasprocess_path:
        exe_path = Path(rasprocess_path)
        ras.ras_exe_path = str(
            exe_path
            if exe_path.suffix.lower() == ".exe"
            else exe_path / "RasProcess.exe"
        )

    # RasMapperLib has no recession MapType (verified 6.6/7.0.1) — only
    # RasMapperLib-native products are generated.
    if recession:
        console.print(
            "  [yellow]Warning:[/yellow] recession has no RasMapperLib map type "
            "- skipping (arrival_time and duration are available)"
        )
        recession = False

    # Build list of requested map types
    requested_types = _build_requested_types(
        wse=wse, depth=depth, velocity=velocity,
        froude=froude, shear_stress=shear_stress,
        depth_x_velocity=depth_x_velocity,
        depth_x_velocity_sq=depth_x_velocity_sq,
        inundation_boundary=inundation_boundary,
        arrival_time=arrival_time, duration=duration,
        percent_inundated=percent_inundated,
    )

    if not requested_types:
        console.print("[yellow]Warning:[/yellow] No map types selected")
        return []

    if "inundation_boundary" in requested_types and (reproject_wgs84 or convert_cog):
        console.print(
            "  [yellow]Note:[/yellow] raster post-processing (--wgs84/--cog) does "
            "not apply to the inundation boundary shapefile - it stays in the "
            "model CRS"
        )

    console.print(f"  Map types: {', '.join(requested_types)}")

    # Determine which plans to process
    plan_filter = set(plans) if plans else None
    plan_rows = ras.plan_df if ras.plan_df is not None and not ras.plan_df.empty else None

    if plan_rows is None:
        console.print("[yellow]Warning:[/yellow] No plans found in project")
        return []

    results: list[MapResult] = []

    for _, row in plan_rows.iterrows():
        plan_num = str(row.get("plan_number", "")).zfill(2)
        plan_id = f"p{plan_num}"

        if plan_filter and plan_id not in plan_filter:
            continue

        plan_hdf = project_dir / f"{ras.project_name}.p{plan_num}.hdf"
        if not plan_hdf.exists():
            console.print(f"  [{plan_id}] No HDF results - skipping")
            continue

        plan_output = output_dir / plan_id
        plan_output.mkdir(parents=True, exist_ok=True)

        map_result = MapResult(
            plan_id=plan_id,
            plan_number=plan_num,
            output_dir=plan_output,
        )

        console.print(f"  [{plan_id}] Generating maps...")

        try:
            fast_results: dict[str, list[Path]] = {}
            fast_render = None
            if terrain_resolver is not None:
                # Scope, engine and render mode first: an out-of-scope plan
                # (1D, storage areas, no stored render mode) must not pay for
                # a terrain export before going to RAS Mapper.
                try:
                    fast_render = _fast_map.preflight(
                        plan_hdf, ras, render_mode, storage_areas=fast_map_storage_areas,
                    )
                except _fast_map.FastMapUnavailable as exc:
                    if not fast_map_fallback:
                        raise
                    console.print(
                        f"    [yellow]fast-map not used[/yellow] ({exc}); using RAS Mapper"
                    )
                    for map_type in requested_types:
                        map_result.fast_map_skipped[map_type] = str(exc)
            if fast_render is not None:
                # WSE/Depth and the boundary use different terrain inputs, so
                # each falls back to RAS Mapper on its own.
                def _fast_group(label, run, types=()):
                    try:
                        produced = run()
                    except Exception as exc:
                        if not fast_map_fallback:
                            raise
                        console.print(
                            f"    [yellow]fast-map {label} unavailable[/yellow] "
                            f"({exc}); using RAS Mapper"
                        )
                        for map_type in types:
                            if map_type in requested_types:
                                map_result.fast_map_skipped[map_type] = str(exc)
                        return {}
                    console.print(
                        f"    fast-map: {', '.join(produced)} mapped in Rust"
                    )
                    record = getattr(produced, "invalid_cells", None)
                    writer = getattr(produced, "product_writer", None)
                    for map_type in produced:
                        if record is not None:
                            map_result.invalid_cells[map_type] = record
                        if writer is not None:
                            map_result.fast_map_writer[map_type] = writer
                    if record and record.get("count"):
                        console.print(
                            f"    [yellow]fast-map {label}:[/yellow] {record['count']} invalid "
                            f"2D cell polygon(s) handled with invalid_cells="
                            f"{record.get('policy')!r} (see the fast-map manifest)"
                        )
                    return produced

                def _on_terrain(label, run):
                    """Run on the cheapest terrain the engine accepts; record it."""
                    notes_before = len(terrain_resolver.notes)
                    try:
                        produced, kind = _fast_map.with_terrain(
                            terrain_resolver, plan_hdf, run, use_source=fast_map_source_terrain,
                        )
                    finally:
                        # Also when every candidate was refused: the last
                        # refusal alone does not say why the cheaper terrains
                        # were passed over.
                        for note in terrain_resolver.notes[notes_before:]:
                            console.print(f"    fast-map {label}: {note}")
                    # A snapshot per product group: a later group's fallback
                    # must not change what this group's products record.
                    route = terrain_resolver.record_product_group(plan_hdf, label, kind)
                    for map_type in produced:
                        map_result.fast_map_terrain[map_type] = kind
                        if route is not None:
                            map_result.fast_map_terrain_route[map_type] = route
                    return produced

                def _skip(label, reason, *, strict=False, types=()):
                    """A product group outside fast-map's scope goes to RAS Mapper.

                    ``strict``: also refused under --fast-map-strict (as the
                    per-profile maps always were); qualification limits such
                    as slopingPretty velocity are not errors. ``types`` are
                    recorded in ``MapResult.fast_map_skipped``.
                    """
                    if strict and not fast_map_fallback:
                        raise _fast_map.FastMapUnavailable(f"{label}: {reason}")
                    for map_type in types:
                        if map_type in requested_types:
                            map_result.fast_map_skipped[map_type] = reason
                    console.print(
                        f"    [yellow]fast-map {label} not used[/yellow] ({reason}); "
                        "using RAS Mapper"
                    )

                # Per-profile products are Max only through fast-map. Decided
                # here, before any terrain work: inside with_terrain a refusal
                # reads as a terrain refusal and would cost an export.
                max_profile = profile == "Max"
                profile_reason = f"fast-map maps the Max profile only (got {profile!r})"
                if not max_profile and any(
                    t in requested_types
                    for t in (*_fast_map.FAST_MAP_RASTER_TYPES, "velocity",
                              *_fast_map.FAST_MAP_DERIVED_TYPES, _fast_map.FAST_MAP_SHEAR,
                              _fast_map.FAST_MAP_BOUNDARY)
                ):
                    _skip("per-profile maps", profile_reason, strict=True, types=(
                        *_fast_map.FAST_MAP_RASTER_TYPES, "velocity",
                        *_fast_map.FAST_MAP_DERIVED_TYPES, _fast_map.FAST_MAP_SHEAR,
                        _fast_map.FAST_MAP_BOUNDARY,
                    ))
                if max_profile and any(
                    t in _fast_map.FAST_MAP_RASTER_TYPES for t in requested_types
                ):
                    fast_results.update(_fast_group("WSE/Depth", lambda: _on_terrain(
                        "WSE/Depth",
                        lambda tif, hdf, kind: _fast_map.map_plan(
                            plan_hdf,
                            tif,
                            plan_output,
                            map_types=requested_types,
                            profile=profile,
                            render=fast_render,
                            threads=fast_map_threads,
                            timeout=timeout,
                            max_working_mib=fast_map_memory_mib,
                            terrain_hdf=hdf,
                            terrain_kind=kind,
                            invalid_cells=fast_map_invalid_cells,
                            product_writer=fast_map_writer,
                        ),
                    ), types=_fast_map.FAST_MAP_RASTER_TYPES))
                if max_profile and "velocity" in requested_types:
                    velocity_depth, reason = _fast_map.velocity_plan(
                        fast_render, fast_map_velocity
                    )
                    if reason is not None:
                        _skip("velocity", reason, types=("velocity",))
                    else:
                        fast_results.update(_fast_group("velocity", lambda: _on_terrain(
                            "velocity",
                            lambda tif, hdf, kind: _fast_map.map_velocity(
                                plan_hdf,
                                tif,
                                plan_output,
                                render=fast_render,
                                velocity_depth=velocity_depth,
                                profile=profile,
                                threads=fast_map_threads,
                                timeout=timeout,
                                max_working_mib=fast_map_memory_mib,
                                terrain_hdf=hdf,
                                terrain_kind=kind,
                                invalid_cells=fast_map_invalid_cells,
                            ),
                        ), types=("velocity",)))
                derived_types = [
                    t for t in _fast_map.FAST_MAP_DERIVED_TYPES if t in requested_types
                ]
                if max_profile and derived_types:
                    reason = _fast_map.derived_plan(fast_render, fast_map_derived)
                    if reason is not None:
                        _skip("D x V/Froude", reason, types=derived_types)
                    else:
                        fast_results.update(_fast_group("D x V/Froude", lambda: _on_terrain(
                            "D x V/Froude",
                            lambda tif, hdf, kind: _fast_map.map_derived(
                                plan_hdf,
                                tif,
                                plan_output,
                                map_types=derived_types,
                                render=fast_render,
                                profile=profile,
                                threads=fast_map_threads,
                                timeout=timeout,
                                max_working_mib=fast_map_memory_mib,
                                terrain_hdf=hdf,
                                terrain_kind=kind,
                                invalid_cells=fast_map_invalid_cells,
                            ),
                        ), types=derived_types))
                if max_profile and _fast_map.FAST_MAP_SHEAR in requested_types:
                    shear_depth, reason = _fast_map.shear_plan(fast_render, fast_map_shear)
                    if reason is not None:
                        _skip("shear stress", reason, types=(_fast_map.FAST_MAP_SHEAR,))
                    else:
                        fast_results.update(_fast_group("shear stress", lambda: _on_terrain(
                            "shear stress",
                            lambda tif, hdf, kind: _fast_map.map_shear(
                                plan_hdf,
                                tif,
                                plan_output,
                                render=fast_render,
                                shear_depth=shear_depth,
                                profile=profile,
                                threads=fast_map_threads,
                                timeout=timeout,
                                max_working_mib=fast_map_memory_mib,
                                terrain_hdf=hdf,
                                terrain_kind=kind,
                                invalid_cells=fast_map_invalid_cells,
                            ),
                        ), types=(_fast_map.FAST_MAP_SHEAR,)))
                whole_types, whole_notes = _fast_map.whole_simulation_types(
                    requested_types, fast_render
                )
                for note in whole_notes if fast_map_whole_simulation else ():
                    _skip("whole simulation", note)
                if fast_map_whole_simulation and whole_types:
                    fast_results.update(_fast_group("whole simulation", lambda: _on_terrain(
                        "whole simulation",
                        lambda tif, hdf, kind: _fast_map.map_whole_simulation(
                            plan_hdf,
                            tif,
                            plan_output,
                            map_types=whole_types,
                            threshold=arrival_depth,
                            render=fast_render,
                            terrain_hdf=hdf,
                            threads=fast_map_threads,
                            timeout=timeout,
                            max_working_mib=fast_map_memory_mib,
                            terrain_kind=kind,
                            invalid_cells=fast_map_invalid_cells,
                        ),
                    ), types=whole_types))
                if (
                    max_profile and fast_map_boundary
                    and _fast_map.FAST_MAP_BOUNDARY in requested_types
                ):
                    def _boundary():
                        tif, terrain_hdf = terrain_resolver.boundary_terrain(
                            plan_hdf, fast_map_boundary_method
                        )
                        return _fast_map.map_boundary(
                            plan_hdf, tif, terrain_hdf, plan_output,
                            profile=profile,
                            render=fast_render,
                            method=fast_map_boundary_method,
                            terrain_crs_fnv1a64=fast_map_terrain_crs_fnv1a64,
                            threads=fast_map_threads,
                            timeout=timeout,
                            max_working_mib=fast_map_memory_mib,
                            invalid_cells=fast_map_invalid_cells,
                        )
                    fast_results.update(_fast_group(
                        "inundation boundary", _boundary, types=(_fast_map.FAST_MAP_BOUNDARY,)
                    ))

            rasmapper_types = [t for t in requested_types if t not in fast_results]
            if native_only and rasmapper_types:
                reasons = "; ".join(
                    f"{t} ({map_result.fast_map_skipped.get(t, 'not mapped by fast-map')})"
                    for t in rasmapper_types
                )
                raise _fast_map.FastMapUnavailable(
                    "native-only mapping cannot use RAS Mapper (no HEC-RAS terrain); "
                    f"not mapped natively: {reasons}"
                )

            # Build boolean flags for RasProcess.store_maps()
            type_flags = {t: (t in rasmapper_types) for t in MAP_TYPE_VARIABLES}

            plan_run_started = time.time() - 2  # filesystem mtime slack

            result_dict: dict[str, list[Path]] = {}
            if rasmapper_types:
                result_dict = _generate_plan_maps(
                    ras=ras,
                    plan_number=plan_num,
                    profile=profile,
                    output_dir=plan_output,
                    terrain_name=terrain_name,
                    render_mode=render_mode,
                    timeout=timeout,
                    arrival_depth=arrival_depth,
                    ras_version=ras_version,
                    performance=effective_performance,
                    **type_flags,
                )
            for map_type in rasmapper_types:
                map_result.engines[map_type] = _fast_map.RASMAPPER
            for map_type, paths in fast_results.items():
                result_dict[map_type] = paths
                map_result.engines[map_type] = _fast_map.FAST_MAP

            # Shapefile outputs (inundation boundary) are moved by store_maps
            # but not included in its TIF-oriented return dict — glob them,
            # restricted to files produced by this run.
            if "inundation_boundary" in requested_types and not result_dict.get("inundation_boundary"):
                shp_paths = sorted(
                    p for p in plan_output.glob("*.shp")
                    if p.stat().st_mtime >= plan_run_started
                )
                if shp_paths:
                    result_dict["inundation_boundary"] = shp_paths

            for map_type in requested_types:
                tif_paths = result_dict.get(map_type, [])

                # Raster post-processing does not apply to shapefile outputs
                if map_type != "inundation_boundary":
                    # Post-process: depth threshold
                    if map_type == "depth" and min_depth > 0.0:
                        tif_paths = _apply_depth_threshold(tif_paths, min_depth)

                    # Post-process: reproject to WGS84
                    if reproject_wgs84:
                        tif_paths = _reproject_tifs(tif_paths, "EPSG:4326")

                    # Post-process: convert to COG
                    if convert_cog:
                        tif_paths = _convert_to_cog(tif_paths, map_type=map_type)

                if tif_paths:
                    map_result.map_types[map_type] = tif_paths
                    console.print(f"    {map_type}: {len(tif_paths)} raster(s)")

            postprocessing_hdf = plan_output / "PostProcessing.hdf"
            if postprocessing_hdf.exists() and not keep_postprocessing:
                size_mb = postprocessing_hdf.stat().st_size / 1e6
                postprocessing_hdf.unlink()
                console.print(f"    Removed PostProcessing.hdf cache ({size_mb:.0f} MB)")

        except Exception as e:
            error_msg = f"plan {plan_id}: {e}"
            map_result.errors.append(error_msg)
            console.print(f"    [yellow]Warning:[/yellow] {error_msg}")
            if not skip_errors or native_only:
                raise

        results.append(map_result)

    total_maps = sum(
        sum(len(paths) for paths in r.map_types.values())
        for r in results
    )
    total_errors = sum(len(r.errors) for r in results)
    console.print(f"\n[green]OK[/green] Generated {total_maps} raster(s) from {len(results)} plan(s)")
    if total_errors:
        console.print(f"  [yellow]{total_errors} error(s)[/yellow]")

    return results

ras2cng.mapping.DEFAULT_LOCAL_MAP_PERFORMANCE = StoreMapPerformanceOptions(max_workers=None, memory_policy='enforce', reserve_memory_mb=8192, reserve_memory_fraction=0.25, gdal_num_threads_per_helper=1, gdal_cachemax_mb=64) if StoreMapPerformanceOptions is not None else None module-attribute

ras2cng.mapping.MAP_TYPE_VARIABLES = {'wse': 'Water Surface', 'depth': 'Depth', 'velocity': 'Velocity', 'froude': 'Froude Number', 'shear_stress': 'Shear Stress', 'depth_x_velocity': 'Depth x Velocity', 'depth_x_velocity_sq': 'Depth x Velocity²', 'inundation_boundary': 'Inundation Boundary', 'arrival_time': 'Arrival Time', 'duration': 'Duration', 'recession': 'Recession', 'percent_inundated': 'Percent Time Inundated'} module-attribute