ras2cng — RAS to Cloud Native GIS

Full-project archival and cloud-native export tool for HEC-RAS. Extracts geometry, results, and terrain from any HEC-RAS project into hierarchical GeoParquet archives with a manifest.json catalog and spatial index metadata — ready for DuckDB analytics, PMTiles tile delivery, and PostGIS sync. Archives are spatially post-processed by default for predicate pushdown and stable viewer-side joins.

Built on ras-commander by CLB Engineering Corporation.

Installation

# Core (geometry + results + project archive)
pip install ras2cng

# All optional extras (DuckDB analytics, PostGIS sync, PMTiles rasterio)
pip install "ras2cng[all]"

# Individual extras
pip install "ras2cng[duckdb]"    # DuckDB SQL analytics
pip install "ras2cng[postgis]"   # PostGIS sync
pip install "ras2cng[pmtiles]"   # rasterio (PMTiles also needs tippecanoe + pmtiles CLIs)

Quick Start

Full Project Archive (recommended)

# Inspect project structure (no export)
ras2cng inspect path/to/MyProject/

# Archive all geometry from all geometry files (default — safe, no results duplication)
ras2cng archive path/to/MyProject/ ./archive/

# Also export plan results summary variables
ras2cng archive path/to/MyProject/ ./archive/ --results

# Also convert terrain TIFFs to Cloud Optimized GeoTIFF
ras2cng archive path/to/MyProject/ ./archive/ --results --terrain

# Constrained-worker workflow: extract now, index later on a larger worker
ras2cng archive path/to/MyProject/ ./archive/ --results \
  --results-layout variable --results-geometry none --no-sort
ras2cng spatial-index ./archive/

Output structure (consolidated parquet per source file):

archive/
├── manifest.json              # Project catalog (schema v2.5, index and terrain metadata)
├── MyProject.parquet          # Project metadata (RasPrj dataframes, _table column)
├── MyProject.g01.parquet      # All geometry from g01 (HDF + text), layer column
├── MyProject.g06.parquet      # All geometry from g06
├── MyProject.p01.parquet      # All results from p01, layer column (--results)
└── terrain/                   # (--terrain flag)
    └── Terrain50_cog.tif

Query layers within consolidated files:

SELECT * FROM 'MyProject.g01.parquet' WHERE layer = 'mesh_cells'
SELECT * FROM 'MyProject.p01.parquet' WHERE layer = 'maximum_depth'
SELECT * FROM 'MyProject.parquet' WHERE _table = 'plan_df'

Archive GeoParquet files keep bbox covering metadata and, unless --no-sort was used, include a persisted hilbert_index sorted by layer,hilbert_index. Geometryless result tables get join_index; when matching mesh_cells or mesh_faces geometry is present, they also inherit hilbert_index for spatially local joins.

Single-File Export

# Export mesh cell geometry from HDF
ras2cng geometry model.g01.hdf mesh_cells.parquet --layer mesh_cells

# Export max depth results joined to polygon geometry
ras2cng results model.p01.hdf max_depth.parquet \
  --geometry mesh_cells.parquet --var "Maximum Depth"

# Export gridded precipitation and cumulative precipitation GeoTIFFs
ras2cng precip model.p01.hdf ./precipitation/

# Query with DuckDB (use _ as table name)
ras2cng query max_depth.parquet \
  "SELECT mesh_name, AVG(maximum_depth) FROM _ GROUP BY mesh_name"

# Generate PMTiles (requires tippecanoe + pmtiles on PATH)
ras2cng pmtiles max_depth.parquet flood_depth.pmtiles --layer flood --min-zoom 8 --max-zoom 14

# Sync to PostGIS
ras2cng sync max_depth.parquet "postgresql://user:pass@host/db" max_depth --schema hydraulics

Python API

from ras2cng import (
    archive_project,
    inspect_project,
    export_geometry_layers,
    export_results_layer,
    export_all_variables,
    export_precipitation_rasters,
    list_precipitation_timestamps,
    DuckSession,
    query_parquet,
    generate_pmtiles_from_input,
    sync_to_postgres,
)
from pathlib import Path

# Full project archive
manifest = archive_project(
    Path("path/to/MyProject/"),
    Path("./archive/"),
    include_results=True,
    include_terrain=True,
)
print(f"Exported {len(manifest.geometry)} geometry configurations")

# Inspect project without extracting
info = inspect_project(Path("path/to/MyProject/"))
print(f"{info.name}: {len(info.geom_files)} geometry files, {len(info.plan_files)} plans")

# Single file export
export_geometry_layers(Path("model.g01.hdf"), Path("mesh_cells.parquet"), layer="mesh_cells")

# Gridded precipitation rasters
export_precipitation_rasters(Path("model.p01.hdf"), Path("./precipitation"))

# DuckDB query (table alias is always _)
df = query_parquet(Path("max_depth.parquet"), "SELECT * FROM _ WHERE maximum_depth > 3.0")

Extractable Data

Geometry Layers (from .g##.hdf)

Results Variables (from .p##.hdf, opt-in)

Exported from plan HDF files. Common 2D mesh summary variables:

• Maximum Depth → maximum_depth
• Maximum Water Surface → maximum_water_surface
• Maximum Face Velocity → maximum_face_velocity

Column names are snake_case (ras-commander normalization). Use --all flag to export every available variable.

Why results are opt-in: Plan HDF files contain a copy of the geometry. Exporting geometry first (archive default), then adding --results avoids redundant extraction.

Gridded Precipitation Rasters (from .p##.hdf or .u##.hdf)

Exported from Event Conditions/Meteorology/Precipitation as GeoTIFF rasters:

• Per-timestep precipitation amount rasters
• Cumulative-through-timestep precipitation rasters
• CRS, transform, timestamps, and units preserved from HDF attributes

Use ras2cng precip model.p01.hdf ./precipitation/ for the CLI workflow.

Output Formats

External CLIs for PMTiles / COG

# via conda-forge
conda install -c conda-forge tippecanoe pmtiles gdal

Or download from felt/tippecanoe and protomaps/go-pmtiles.

Documentation

Full documentation: https://ras2cng.readthedocs.io/en/latest/

GitHub Pages mirror: https://gpt-cmdr.github.io/ras2cng/

About CLB Engineering

ras2cng is an open-source project of CLB Engineering Corporation, the creators of ras-commander and hms-commander.

CLB pioneered the LLM Forward approach to civil engineering — a framework where licensed professional engineers leverage Large Language Models to accelerate H&H modeling workflows while maintaining full professional responsibility.

Contact: info@clbengineering.com | Website: clbengineering.com

License

MIT License — see LICENSE for details.