Skip to content

Installation

Core Install

pip install ras2cng

Installs the geometry and results export pipeline. No DuckDB, PostGIS, or PMTiles extras needed for basic use.

Full Install (All Extras)

pip install "ras2cng[all]"

Using uv (recommended, 10–100x faster):

uv pip install "ras2cng[all]"

Install Specific Extras

pip install "ras2cng[duckdb]"    # DuckDB SQL analytics
pip install "ras2cng[postgis]"   # PostGIS sync (SQLAlchemy + GeoAlchemy2 + psycopg2)
pip install "ras2cng[pmtiles]"   # rasterio (PMTiles pipeline also needs external CLIs)
pip install "ras2cng[netcdf]"    # netCDF4, for ras2cng.rate_stack.write_rate_stack

Dev Install from Source

git clone https://github.com/gpt-cmdr/ras2cng.git
cd ras2cng
uv sync --all-extras
uv run ras2cng --help

PMTiles External CLI Tools

Vector tiles can be built without any external tools by installing the freestiler extra. auto prefers a freestiler build with Arrow input over tippecanoe; an older build is chosen only when tippecanoe is not on PATH (for example on Windows):

pip install "ras2cng[freestiler]"

The fastest vector path (Arrow input with no GeoJSON step, and per-zoom polygon simplification), complete short lines at low zoom, and the sparse-tileset options (deduplicate, sort_values, per-zoom line simplification) need the gpt-cmdr fork build of freestiler, published as GitHub Release assets rather than on PyPI:

pip install freestiler==0.3.0.4 \
  --find-links https://github.com/gpt-cmdr/freestiler/releases/expanded_assets/v0.3.0.4-gpt-cmdr

Likewise the direct HDF archive path, the native GeoParquet writer, the COG report and the Rust polygon filter need the CLB build of terrio (terrio-clb), also published as GitHub Release assets rather than on PyPI. 0.5.0.4 is built against ras-commander-fast-hdf 0.5.0, so older plan files whose 2D summaries store no Location also take the direct archive path:

pip install terrio==0.5.0.4 \
  --find-links https://github.com/CLB-Engineering-Corporation/terrio-clb/releases/expanded_assets/gpt-cmdr-v0.5.0.4

Both are optional and detected at run time; with the PyPI builds ras2cng keeps its Python paths. In a uv project, install them after uv sync and run with uv run --no-sync: a later uv sync, even with --inexact, reinstalls the locked PyPI builds.

Otherwise, vector tiles use two external CLI tools (not available via pip):

  • tippecanoe — Generates vector tiles from GeoJSON
  • pmtiles — go-pmtiles CLI for MBTiles → PMTiles conversion

Install via conda-forge:

conda install -c conda-forge tippecanoe pmtiles

Or download pre-built binaries from protomaps/go-pmtiles releases and felt/tippecanoe releases.

For raster PMTiles, gdal_translate (part of GDAL) is also required.

Requirements

  • Python >= 3.10
  • ras-commander 0.119.0 or newer (with its full extra: ras-commander-fast-hdf 0.5.0 and ras-commander-fast-map 0.18.0) — installed automatically as a dependency
  • Core: pandas, geopandas, pyarrow, typer, rich
  • Optional: duckdb, sqlalchemy, geoalchemy2, psycopg2-binary, rasterio