CLI Reference¶
ras2cng --help¶
Usage: ras2cng [OPTIONS] COMMAND [ARGS]...
ras2cng — HEC-RAS to Cloud Native GIS.
Archive full projects or export individual files to GeoParquet,
DuckDB, PMTiles, and PostGIS.
Commands:
inspect Inspect a HEC-RAS project structure without extracting any data.
archive Archive a HEC-RAS project to consolidated GeoParquet files.
spatial-index Post-process an existing archive with Hilbert sorting and join indexes.
geometry Export HEC-RAS geometry to GeoParquet.
results Export HEC-RAS 2D mesh summary results to GeoParquet.
precip Export gridded precipitation and cumulative precipitation GeoTIFFs.
query Query GeoParquet files using DuckDB SQL.
pmtiles Generate PMTiles from GeoParquet (vector) or GeoTIFF (raster).
audit-overviews Check whether a raster's overviews preserve wet extent.
maplibre Build a MapLibre PMTiles bundle from a completed ras2cng archive.
maplibre-terrain Publish a RAS-styled terrain PMTiles layer into a MapLibre viewer.
maplibre-stored-map Publish a queryable RASMapper Stored Map into a MapLibre viewer.
validate-publication Enforce the Example Library publication contract.
sync Sync GeoParquet data to PostGIS.
terrain Consolidate one selected named terrain into a merged TIFF.
map Generate result rasters (WSE, Depth, Velocity, etc.).
terrain-mod Export terrain with modifications as GeoTIFF.
mannings Export final Manning's n raster.
ras2cng inspect¶
Usage: ras2cng inspect [OPTIONS] PROJECT
Inspect a HEC-RAS project structure without extracting any data.
Arguments:
PROJECT HEC-RAS project directory or .prj file
Options:
--json Output as JSON instead of table
ras2cng archive¶
Usage: ras2cng archive [OPTIONS] PROJECT OUTPUT
Archive a HEC-RAS project to consolidated GeoParquet files.
Produces one parquet per geometry file and one per plan, plus a project
metadata parquet. All layers within each file are distinguished by a
`layer` column — query with `WHERE layer = 'mesh_cells'`.
Geometry is exported by default. Results, terrain, and map generation are opt-in.
Arguments:
PROJECT HEC-RAS project directory or .prj file
OUTPUT Archive output directory (created if needed)
Options:
--results / --no-results Include plan results (summary variables)
--terrain / --no-terrain Convert terrain TIFFs to Cloud Optimized GeoTIFF
--plan-geometry Also extract geometry copy embedded in plan HDF files
--plans TEXT Comma-separated plan IDs to include, e.g. p01,p02 (default: all)
--result-variables TEXT Comma-separated result summary variables or slugs to include
--results-layout TEXT Results output layout: plan or variable
--results-geometry TEXT Results geometry mode: polygon, point, or none
--auxiliary-results / --mesh-results-only
Include raw reference, structure, pump, and pipe summaries
--skip-errors / --fail-fast Skip individual layer errors vs abort
--no-sort Disable Hilbert spatial post-processing (on by default)
--map / --no-map Generate result rasters via RasStoreMapHelper
--consolidate-terrain Create one authoritative COG per named terrain
--terrain-resolution TEXT Explicit named-terrain cell size as NAME=VALUE; repeatable
--render-mode TEXT Water surface render mode: horizontal, sloping, slopingPretty
--ras-version TEXT HEC-RAS version for RasProcess mapping
--rasprocess PATH Path to HEC-RAS install directory (for helper deployment)
archive runs the same spatial post-processing pass as spatial-index by
default. The pass adds hilbert_index to GeoParquet geometry, sorts rows by
layer,hilbert_index, and preserves GeoParquet bbox covering metadata.
Geometryless result tables receive join_index; when matching mesh geometry is
available, they also inherit hilbert_index by mesh_name plus cell_id or
face_id. Use --no-sort for extraction-only runs on memory-constrained
workers, then run ras2cng spatial-index ARCHIVE_DIR later.
ras2cng spatial-index¶
Usage: ras2cng spatial-index [OPTIONS] ARCHIVE_DIR
Post-process an existing archive with Hilbert sorting and join indexes.
Arguments:
ARCHIVE_DIR ras2cng archive directory containing manifest.json
Options:
--hilbert-level INTEGER Hilbert curve level [default: 16]
--skip-errors / --fail-fast Skip individual parquet errors vs abort
spatial-index updates the archive in place and rewrites manifest.json
schema 2.5 index metadata. Geometry layers record hilbert_index, sort_order,
and bbox columns. Result variables record join metadata such as index_column,
geometry_filter, join_index, hilbert_index, sort_order, and
index_status (spatial_join, join_key, skipped, or error).
ras2cng geometry¶
Usage: ras2cng geometry [OPTIONS] GEOM_FILE OUTPUT
Export HEC-RAS geometry to GeoParquet.
Arguments:
GEOM_FILE HEC-RAS geometry file (*.g??) or geometry HDF (*.g??.hdf)
OUTPUT Output GeoParquet file path
Options:
-l, --layer TEXT Geometry layer: mesh_cells, mesh_faces, mesh_areas,
cross_sections, centerlines, river_reaches, edge_lines,
bank_lines, bc_lines,
breaklines, refinement_regions, reference_lines,
reference_points, structures, pipe_conduits, pipe_nodes,
storage_areas, pump_stations, mannings_n_regions,
infiltration_regions
ras2cng results¶
Usage: ras2cng results [OPTIONS] PLAN_HDF OUTPUT
Export HEC-RAS 2D mesh summary results to GeoParquet.
Arguments:
PLAN_HDF HEC-RAS plan HDF file (*.p??.hdf)
OUTPUT Output GeoParquet path (or directory when using --all)
Options:
-g, --geometry PATH Geometry GeoParquet for spatial join
-v, --var TEXT Result variable to export [default: Maximum Depth]
--all Export all available summary variables to the output directory
ras2cng precip¶
Usage: ras2cng precip [OPTIONS] HDF_FILE OUTPUT
Export gridded precipitation and cumulative precipitation GeoTIFFs.
Arguments:
HDF_FILE HEC-RAS plan or unsteady HDF file containing gridded precipitation
OUTPUT Output directory for precipitation GeoTIFFs
Options:
--source TEXT Precipitation source: auto, processed, or imported
[default: auto]
--timestamps TEXT Comma-separated timestamp labels or zero-based indices to export
--incremental / --no-incremental
Write per-timestep precipitation rasters
--cumulative / --no-cumulative
Write cumulative-through-timestep precipitation rasters
--prefix TEXT Optional filename prefix
--no-overwrite Fail if an output GeoTIFF already exists
ras2cng query¶
Usage: ras2cng query [OPTIONS] INPUT_FILE SQL
Query GeoParquet files using DuckDB SQL.
Arguments:
INPUT_FILE Input GeoParquet file
SQL SQL query (use _ as table name)
Options:
-o, --output PATH Optional output file (CSV or Parquet)
ras2cng pmtiles¶
Usage: ras2cng pmtiles [OPTIONS] INPUT_FILE OUTPUT
Generate PMTiles from GeoParquet (vector) or GeoTIFF (raster).
Arguments:
INPUT_FILE Input GeoParquet file or GeoTIFF
OUTPUT Output PMTiles file path
Options:
-l, --layer TEXT Vector tile layer name [default: layer]
--min-zoom INTEGER Minimum zoom
--max-zoom INTEGER Maximum zoom
ras2cng maplibre¶
Polygon simplification options, also on maplibre-stored-vector (see
MapLibre):
--simplify-tolerance FLOAT Douglas-Peucker tolerance in feet before tiling (default 1; 0 = off)
--no-simplify Turn off the filter and the per-zoom option
--tile-polygon-simplify FLOAT Per-zoom tolerance in tile pixels (default 0.5; 0 = off)
--no-tile-polygon-simplify Turn off only the per-zoom option
ras2cng maplibre only, with a freestiler that has the options (see
MapLibre):
--tile-line-simplify FLOAT Per-zoom line tolerance in tile pixels (default 1; 0 = off);
never mesh faces
--no-tile-line-simplify Turn off only the per-zoom line option
--compact-tiles / --no-compact-tiles
Store identical tiles once and sort each layer's values
(lossless; default on; RAS2CNG_VECTOR_TILE_COMPACT)
ras2cng maplibre only (see
MapLibre):
--keep-short-lines / --no-keep-short-lines
Write mesh faces and breaklines that collapse to one tile
pixel as one-unit segments (default on, with a freestiler
that has keep_short_lines; RAS2CNG_KEEP_SHORT_LINES)
ras2cng audit-overviews¶
Usage: ras2cng audit-overviews [OPTIONS] RASTER
Check whether a raster's overviews preserve wet extent. Reads whatever overviews
the file stores, so it works on rasters ras2cng did not write.
Options:
-t, --threshold FLOAT Wet cutoff in the raster's own units [required]
-b, --band INTEGER 1-based band index [default: 1]
--json Output as JSON instead of a table
--strict Exit non-zero unless the verdict is stable (for CI gates)
Python: ras2cng.cog.audit_overview_extent. It reads each level at size // factor, so
its ratios can differ slightly from the written overview_area_ratios tag (0.994 against
1.000 at level 16 on Bald Eagle).
ras2cng maplibre-stored-map¶
Usage: ras2cng maplibre-stored-map [OPTIONS] COG_PATH VIEWER_DIR
Publish a queryable RASMapper Stored Map under its source plan.
Required options:
--plan TEXT Source plan identifier, such as p03
--map-type TEXT RASMapper map type, such as Depth or Velocity
Other options:
--name TEXT Layer display name
--profile TEXT Profile, summary, or time label
--geometry TEXT Associated geometry identifier
--source-cog TEXT Public or manifest-relative numeric COG href
--units TEXT Result units shown in legends and Identify
--visible / --hidden Initial visibility [default: hidden]
--domain-policy TEXT fixed or current-view [default: fixed]
--max-zoom INTEGER Maximum display zoom, capped by native resolution
--scratch-dir PATH Local scratch for bounded raster processing
--overwrite Replace an existing layer/display derivative
ras2cng maplibre-import-stored-maps¶
Usage: ras2cng maplibre-import-stored-maps [OPTIONS] MAPS_DIR ARCHIVE_DIR VIEWER_DIR
Import and publish a complete distributed RasProcess Stored Map tranche.
Options:
--scratch-dir PATH Local scratch for bounded raster processing
--domain-policy TEXT Initial raster legend policy [default: fixed]
--max-zoom INTEGER Maximum zoom for precolored PMTiles [default: 16]
--require-all / --allow-partial
Require all supported map families [default: require-all]
--overwrite Replace imported artifacts and viewer layers
--max-zoom applies only to the precolored browser derivative. The authoritative numeric
COG retains its full source resolution for Identify and analysis, and display PMTiles are
never upsampled beyond the native grid.
ras2cng validate-publication¶
Usage: ras2cng validate-publication [OPTIONS] VIEWER_MANIFEST ARCHIVE_MANIFEST
Enforce the Example Library catalog-admission contract.
Options:
--check-files / --manifest-only Validate local referenced artifacts [default: check]
--check-http-ranges Require HTTP 206 for hosted PMTiles/COGs
--json Emit a machine-readable report
ras2cng sync¶
Usage: ras2cng sync [OPTIONS] INPUT_FILE POSTGRES_URI TABLE_NAME
Sync GeoParquet data to PostGIS.
Arguments:
INPUT_FILE Input GeoParquet file
POSTGRES_URI PostgreSQL connection URI
TABLE_NAME Target table name
Options:
-s, --schema TEXT Target schema [default: public]
--if-exists TEXT replace|append|fail [default: replace]
ras2cng terrain¶
Usage: ras2cng terrain [OPTIONS] PROJECT OUTPUT
Consolidate one selected named terrain into a merged TIFF and HEC-RAS terrain HDF.
Arguments:
PROJECT HEC-RAS project directory or .prj file
OUTPUT Output directory for consolidated terrain files
Options:
--name TEXT Terrain name [default: Consolidated]
--downsample FLOAT Downsample factor (2.0 = half resolution)
--resolution FLOAT Target cell size in project units
--terrains TEXT Comma-separated terrain names to include
--units TEXT Vertical units: Feet or Meters [default: Feet]
--ras-version TEXT HEC-RAS version [default: 6.6]
--tiff-only Only produce merged TIFF, skip HDF creation
--no-register Don't register new terrain in rasmap
terrain requires the selected TIFFs to belong to one named RASMapper surface. For
Example Library archives, prefer archive --consolidate-terrain, which processes each
named terrain independently and records the resolution decision and source inventory.
When a relocated project's stored RASMapper paths cannot be resolved, use the Python
consolidate_terrain_files() API with an explicit priority-ordered source list. It applies
the same bounded-memory merge, transparent NoData, no-upsample policy, and provenance model.
ras2cng map¶
Usage: ras2cng map [OPTIONS] PROJECT OUTPUT
Generate result rasters (WSE, Depth, Velocity, etc.) via RasStoreMapHelper.
Renders completed plan results to GeoTIFF rasters using the HEC-RAS
mapping engine via RasStoreMapHelper.exe (bundled with ras-commander).
Arguments:
PROJECT HEC-RAS project directory or .prj file
OUTPUT Output directory for result rasters
Options:
--plans TEXT Comma-separated plan IDs (default: all with results)
--profile TEXT Max, Min, exact steady profile, or timestamp [default: Max]
--wse / --no-wse Water Surface Elevation [default: on]
--depth / --no-depth Depth [default: on]
--velocity / --no-velocity Velocity [default: on]
--froude Froude number
--shear-stress Shear stress
--dv Depth x Velocity
--dv-sq Depth x Velocity²
--inundation-boundary Inundation boundary polygon
--arrival-time Arrival time (hours, whole-simulation)
--duration Inundation duration (hours)
--percent-inundated Percent time inundated
--arrival-depth FLOAT Wet/dry depth threshold for arrival/duration/
percent-inundated [default: 0.0]
--terrain TEXT Specific terrain name from rasmap
--render-mode TEXT Water surface render mode: horizontal, sloping, slopingPretty
--ras-version TEXT HEC-RAS version (e.g. 6.6)
--rasprocess PATH Path to HEC-RAS install directory (for helper deployment)
--min-depth FLOAT Min depth threshold [default: 0.0]
--wgs84 Reproject output to WGS84
--cog Convert output to Cloud Optimized GeoTIFF
--timeout INTEGER Per-plan timeout in seconds [default: 10800]
--skip-errors / --fail-fast Skip errors vs abort
--keep-postprocessing Keep the (large) PostProcessing.hdf cache in the output directory
--map-workers INTEGER Map helper ceiling; 1=serial (default: memory-aware auto)
--map-reserve-memory-mb INTEGER
Minimum physical-memory reserve in MiB [default: 8192]
--map-gdal-cache-mb INTEGER Optional GDAL cache cap per map helper in MiB [default: 64]
fast-map options added in 0.16 (the full list is in ras2cng map --help; see
Mapping):
--fast-map-shear / --no-fast-map-shear
Map Max --shear-stress in Rust when the engine has it
(plain sloping and horizontal) [default: on]
--fast-map-boundary-method TEXT
deterministic (default) or native-serial (opt-in; the
engine labels it unqualified)
[env: RAS2CNG_FAST_MAP_BOUNDARY_METHOD]
--wgs84 reprojects for real since 0.16 (it returned the model CRS before); see
Post-Processing Options.
Notes on whole-simulation types: --arrival-time, --duration, and
--percent-inundated are computed over the entire simulation (the --profile
option does not apply) and their filenames carry the --arrival-depth
threshold, e.g. Arrival Time (0.1ft hrs).tif. Works with any ras-commander
version: newer versions generate these natively; older versions are handled by
a rasmap pre-injection shim inside ras2cng. --recession is accepted but
ignored with a warning — RasMapperLib has no recession map type.
With the supported ras-commander 0.100.0 or newer, omitted performance options use memory-aware local auto selection. Independent WSE, Depth, and Velocity maps may run in separate helpers when the terrain-based estimate fits available physical and committed memory. Unsupported combinations automatically retain the ordered serial path.
ras2cng map-hdf¶
Usage: ras2cng map-hdf [OPTIONS] PLAN_HDF OUTPUT
Generate result rasters from just a plan HDF + terrain (no project needed).
Synthesizes a barebones HEC-RAS project around the plan HDF (projection,
units, and plan metadata are read from the HDF itself), builds the HEC-RAS
terrain from raw GeoTIFF(s) via RasProcess.exe CreateTerrain (or reuses a
pre-built terrain HDF), then renders stored maps through RASMapper.
With only --fast-map-terrain (a pre-exported terrain GeoTIFF, e.g. from
`ras2cng terrain-mod`), no HEC-RAS terrain is built: fast-map maps every
product on that TIFF and the command fails if any product would need
RAS Mapper (native-only; implies --fast-map-strict).
Arguments:
PLAN_HDF Computed plan results HDF (*.pNN.hdf, any filename)
OUTPUT Output directory for result rasters
Options:
--terrain PATH Raw terrain GeoTIFF (repeatable; tiles are stitched)
--terrain-hdf PATH Pre-built HEC-RAS terrain HDF (its .vrt and tile
TIFFs must sit beside it)
--projection PATH ESRI .prj projection file (default: read WKT from
the plan HDF)
--workdir PATH Scaffold directory (default: OUTPUT/_scaffold;
reused across reruns)
--rm-scaffold Delete the scaffold directory after the run
--profile TEXT Max, Min, exact steady profile, or timestamp [default: Max]
--wse / --no-wse Water Surface Elevation [default: on]
--depth / --no-depth Depth [default: on]
--velocity / --no-velocity Velocity [default: on]
--froude Froude number
--shear-stress Shear stress
--dv Depth x Velocity
--dv-sq Depth x Velocity²
--inundation-boundary Inundation boundary polygon
--arrival-time Arrival time (hours, whole-simulation)
--duration Inundation duration (hours)
--percent-inundated Percent time inundated
--arrival-depth FLOAT Wet/dry depth threshold for arrival/duration/
percent-inundated [default: 0.0]
--render-mode TEXT Water surface render mode [default: sloping]
--ras-version TEXT HEC-RAS version [default: 6.6]
--rasprocess PATH Path to HEC-RAS install directory (for helper deployment)
--min-depth FLOAT Min depth threshold [default: 0.0]
--wgs84 Reproject output to WGS84
--cog Convert output to Cloud Optimized GeoTIFF
--timeout INTEGER Timeout in seconds [default: 10800]
--keep-postprocessing Keep the (large) PostProcessing.hdf cache in the output directory
--map-workers INTEGER Map helper ceiling; 1=serial (default: memory-aware auto)
--map-reserve-memory-mb INTEGER
Minimum physical-memory reserve in MiB [default: 8192]
--map-gdal-cache-mb INTEGER Optional GDAL cache cap per map helper in MiB [default: 64]
Examples:
# Raw terrain TIFF — terrain HDF is built headlessly via RasProcess.exe
ras2cng map-hdf results.p01.hdf ./maps --terrain dem.tif
# Multiple terrain tiles (stitched)
ras2cng map-hdf results.p01.hdf ./maps --terrain dem_a.tif --terrain dem_b.tif
# Pre-built HEC-RAS terrain (skips the terrain build)
ras2cng map-hdf results.p01.hdf ./maps --terrain-hdf Terrain50.hdf
# Native-only: map on a pre-exported terrain GeoTIFF, no HEC-RAS needed
ras2cng map-hdf results.p01.hdf ./maps --fast-map-terrain terrain_export.tif
--terrain and --terrain-hdf need a Windows HEC-RAS install (RasMapperLib +
bundled GDAL) or the Wine setup; give at most one of them. The plan HDF must
carry a Projection attribute or --projection must be supplied.
Native-only mapping. --fast-map-terrain without --terrain /
--terrain-hdf maps on that GeoTIFF with the fast-map engine and nothing else:
no terrain is built or copied (the scaffold's .rasmap has no terrain layer),
no terrain sidecar set is needed, and RAS Mapper is never called. It fails
closed: --engine rasmapper is refused, fast-map engine failures are errors
(as with --fast-map-strict), and a requested product fast-map does not map
(for example a non-Max profile, a 1D or storage-area plan, or an inundation
boundary, which needs the terrain HDF) fails the command instead of going to
RAS Mapper. The TIFF is used as given: supply a float32 export of the terrain
the model was run on, with the modifications its .rasmap activates (for
example ras2cng terrain-mod on the source project). Results record
fast_map_terrain = "supplied".
ras2cng terrain-mod¶
Usage: ras2cng terrain-mod [OPTIONS] PROJECT OUTPUT
Export one registered terrain with native modifications as one GeoTIFF.
RAS Mapper performs source consolidation, grid-aligned nearest-neighbor
downsampling, and vector-modification rasterization. Qualified on Windows
and Wine for HEC-RAS 6.4.1, 6.5, 6.6, and 7.0.1; stable 7.1 remains
forward-open behind ras-commander's managed-contract check.
Arguments:
PROJECT HEC-RAS project directory or .prj file
OUTPUT Output GeoTIFF path
Options:
-g, --geometry TEXT Deprecated and ignored; native terrain export
does not use geometry HDF
--terrain TEXT Exact registered terrain name (required if
ambiguous)
--downsample-factor INTEGER Exact source-derived downsampling factor: 1, 2,
4, or 8 [default: 1]
--overwrite Replace an existing GeoTIFF and receipt
ras2cng mannings¶
Usage: ras2cng mannings [OPTIONS] PROJECT OUTPUT
Export the final Manning's n raster (RAS Mapper's "Final n Values").
By default written in Rust and pixel-identical to RAS Mapper 7.0.1's
Export Raster of the geometry's Final n Values layer (RAS Mapper's grid:
geometry extent, land-cover cell size). Geometries the engine refuses fall
back to the older Python estimate with a warning. The method used is
recorded in the GeoTIFF tag ras2cng_mannings_method.
Arguments:
PROJECT HEC-RAS project directory or .prj file
OUTPUT Output GeoTIFF path
Options:
-g, --geometry TEXT Geometry number (e.g. g01). Default: g01
--method TEXT auto: RAS Mapper's Final n Values in Rust (pixel-identical
to RAS Mapper 7.0.1, no HEC-RAS), falling back with a
warning to the Python estimate for geometries the engine
refuses (e.g. 1D); rasmapper: no fallback; estimate: the
pre-0.13 Python estimate [default: auto]
ras2cng raster-calculate¶
Runs one allowlisted, unit-aware recipe over aligned numeric COGs. Supply each required
role with repeatable --input ROLE=PATH; synchronized recipes also require --profile.
See Controlled Raster Recipes.
ras2cng maplibre-calculated-map¶
Packages a raster-calculate output as display PMTiles plus an authoritative numeric COG
manifest resource under its plan's Calculated Layers branch.
ras2cng raster-service-catalog¶
Builds the WebGIS numeric-raster allowlist. --attach-manifests writes stable asset IDs,
revisions, and the public service endpoint into manifest v2 bundles.
ras2cng raster-service¶
Runs the bounded statistics and styled-tile API. The listener is restricted to loopback and must be published through a reverse proxy. See Numeric Raster Service.
ras2cng raster-release-service¶
Runs the release-aware form of the numeric raster API. It loads each immutable release's
catalog on demand from releases/<release-id>/raster-assets.json, so publishing a release
does not require a global catalog merge or service restart.