Installation¶
Core Install¶
Installs the geometry and results export pipeline. No DuckDB, PostGIS, or PMTiles extras needed for basic use.
Full Install (All Extras)¶
Using uv (recommended, 10–100x faster):
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):
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:
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
fullextra: 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