MapLibre Project Bundles¶
ras2cng maplibre converts a completed GeoParquet archive into the compact delivery
bundle used by the RAS Commander Example Project Library. It creates one PMTiles source
for model geometry, an optional second PMTiles source for raw vector results, and a
viewer manifest that keeps the layer controls grouped like RASMapper.
Viewer Manifest v2¶
New bundles use rascommander.maplibre/v2. The contract separates storage resources,
display layers, navigation, and interaction state:
| Field | Purpose |
|---|---|
resources |
PMTiles, numeric COGs, and viewer-managed basemaps. A display raster and its numeric COG are separate resources. |
layers |
Stable semantic records for style, visibility, provenance, units, query behavior, plan, geometry, and terrain associations. |
tree |
Ordered Features, Geometries, Results, Map Layers, and Terrains hierarchy. |
associations |
Explicit plan-to-geometry and geometry-to-terrain links. |
legends |
Reusable categorical or continuous legend definitions and fixed/current-view domain policy. |
interaction |
The active Identify layer and up to three optional pinned comparison layers. |
timeAxes |
Named time axes for time-varying result layers. |
provenance |
Generator, source CRS/project, archive schema, and result-value semantics. |
Each plan always contains Raw Computation Values, Published Raster Maps, and
Calculated Layers, even when one branch is empty. Raw HDF layers retain values at
HEC-RAS computation elements and declare that no surface interpolation occurred.
Published raster maps identify RASMapper/RasProcess as the interpolation authority.
The manifest temporarily retains v1 tilesets and groups fields so deployed viewers
can be upgraded independently. Consumers should treat the v2 fields as authoritative.
Use ras2cng.apply_manifest_v2() to upgrade an in-memory v1 manifest and
ras2cng.validate_manifest_v2() to reject missing resources, invalid tree references,
or invalid active/pinned layer state.
Required Inputs¶
The archive must have a valid CRS. Supply an original geometry HDF for every geometry configuration in the archive:
ras2cng maplibre ARCHIVE_DIR VIEWER_DIR \
--geometry-hdf g01=/models/Example.g01.hdf \
--geometry-hdf g02=/models/Example.g02.hdf \
--scratch-dir /large-local-scratch
The command calls:
This makes the published extent an API-derived model footprint based on the 1D and 2D
model elements, rather than a bounding box or an approximation reconstructed from tiles.
Install ras-commander from current main; the released package before the footprint API
will be rejected with a clear error.
For large 2D models, pass --scratch-dir on a local volume with substantially more free
space than the system temporary directory. ras2cng writes temporary NDGeoJSON there and
directs the vector tiler's own workspace beneath it; no source features are dropped.
Some legacy HDF files omit their projection while the archive's sibling project.json
records a verified CRS from packaged projection material. In that case the command uses
the archive CRS. A validated CRS can be supplied explicitly with --crs; an unknown CRS
remains a hard error.
Polygon Simplification¶
Before polygon layers are tiled, ras2cng simplifies them with Douglas-Peucker at
1 ft (RAS Mapper's own default filter is 0.1 ft; pass --simplify-tolerance 0.1 for
that). The tolerance is converted to each layer's CRS units (1 in a US survey or
international foot CRS, 0.3048 m in a metre CRS) and applied in the model CRS, before
reprojection. With the freestiler fork build the tiler then simplifies the same layers
once per zoom (below).
| Setting | Default | Effect |
|---|---|---|
RAS2CNG_SIMPLIFY_TOLERANCE, CLI --simplify-tolerance FT |
1 ft | Tolerance in feet; 0 or off turns this filter off |
RAS2CNG_TILE_POLYGON_SIMPLIFY, CLI --tile-polygon-simplify PX |
0.5 tile pixels | The tiler's per-zoom tolerance, above 0 and at most 64, in 1/4096 of a tile; 0 or off turns it off |
CLI --no-tile-polygon-simplify |
Turn off only the per-zoom option | |
CLI --no-simplify |
Turn off both, and the per-zoom line option: tile every vertex at every zoom | |
RAS2CNG_SIMPLIFY_ENGINE |
auto |
terrio (Rust terrio.simplify_wkb, in the CLB terrio build), shapely (GEOS), or auto: terrio when the installed build has it |
What is simplified: the polygons of every layer, for example Manning's n land cover,
2D flow area perimeters, refinement regions, storage areas, terrain modification and
source footprint polygons, model extents and Stored Map polygons. What is never
simplified: mesh_cells and mesh_faces (neighbouring cells share edges, which must
stay coincident), lines and points, and layers in a geographic CRS (skipped with a
warning).
Both engines run GEOS's DouglasPeuckerSimplifier ring by ring and give the same
vertices. A ring that would be left with fewer than four points keeps its vertices, so
no polygon or hole disappears. There is no repair step, so at large tolerances a ring can
self-intersect. At the default maximum zoom (17) one tile coordinate unit is about
0.12-0.13 ft at Texas latitudes, so 1 ft is about 8 units there: half of one CSS pixel,
and less at every lower zoom. The polygon's area changed by -0.2% on the models measured.
Per-zoom simplification¶
With a freestiler build that has polygon_simplify (the fork build 0.3.0.2 or later, see
Installation) and Arrow input, the same polygon
layers also get polygon_simplify=0.5: the tiler simplifies each ring once per zoom and
cuts it down a tile tree, where it otherwise sweeps the whole ring once per tile in the
layer's bounding box. It is never applied to mesh_cells or mesh_faces, including
results joined to them, because each polygon is simplified on its own and shared edges
would stop matching. Every vertex of the input is kept at the layer's maximum zoom, and a
feature whose area collapses at a low zoom is still drawn, so no feature is dropped.
0.5 pixels was chosen over 1.0 for less area bias at middle zooms (-4.8% against -7.3%
at z8 on the thin UPGU3 land-cover network, where unsimplified tiles are within 0.05%)
for tiles about 7.5% larger. Older freestiler builds, RAS2CNG_FREESTILER_INPUT=geojson
and tippecanoe tile as before.
The manifest records what was done: vectorSimplification at the top, with
perZoom saying which layers got the option or why it did not run, and a simplification
record (tolerance in feet and CRS units, engine, vertices in and out, collapsed rings
kept, seconds) on each simplified layer.
Measured on FEMA eBFE models whose single Manning's n land-cover polygon dominated
tiling (maplibre geometry tiles, median of three, freestiler 0.3.0.2): UPGU3 1,062,037
vertices to 122,122, 1,615 s (0.13.0) to 14.9 s; UPGU4 533,600 vertices to 79,364, 400 s
(0.1 ft) to 32.9 s. The speed comes from the per-zoom option: on one host at one load
UPGU3 took 16.1 s with it alone and 150 s with the 1 ft filter alone. The polygons are
smooth, over-densified outlines rather than raster staircases.
Vector Tiler¶
Vector PMTiles are built by one of two interchangeable backends, chosen with
RAS2CNG_VECTOR_TILER:
| Value | Backend | Notes |
|---|---|---|
auto (default) |
freestiler when the build has Arrow input; otherwise tippecanoe when tippecanoe and pmtiles are on PATH; otherwise any freestiler |
An older freestiler keeps the previous preference |
tippecanoe |
tippecanoe + pmtiles CLIs |
Always available by name. Smaller sparse low-zoom layers |
freestiler |
In-process Rust tiler, pip install ras2cng[freestiler] |
No external tools. Bald Eagle p07 viewer with vector results: 36 s against 1,745 s for tippecanoe. Total size +5% with feature IDs, -10% without; Davis +12% and +3%. One layer of a tileset in memory at a time when the build has freestile_layers |
freestiler options (tippecanoe ignores them; its tiles never carry feature IDs):
| Setting | Default | Effect |
|---|---|---|
RAS2CNG_VECTOR_TILE_IDS, CLI --feature-ids/--no-feature-ids |
off (since 0.13) | 1 / --feature-ids keeps an MVT feature ID on every feature (generate_ids=True). Off, the Bald Eagle 87k-cell mesh, z10-15, is 1.7 MB smaller (-14%), and the Bald Eagle p07 viewer with results is 10.0% smaller than tippecanoe's instead of 5.4% larger. The ras2cng viewer does not use IDs; opt in if a consumer uses MapLibre feature-state without promoteId |
RAS2CNG_VECTOR_TILE_GZIP_LEVEL |
6 | Tile gzip level 0-9, when the installed freestiler accepts gzip_level (freestiler's own default is 1). Same mesh: -14%, tile contents unchanged |
RAS2CNG_FREESTILER_INPUT |
auto |
auto / arrow hand layers over as Arrow with no GeoJSON step (arrow fails on a build without Arrow input); geojson keeps the older path. Decoded tiles are identical on Bald Eagle p07 and Davis |
With Arrow input, mesh cell and face layers that are not joined to results go
from the archive GeoParquet to freestiler in the model CRS and are reprojected
in Rust. Other layers are already reprojected for the viewer metadata and join,
and travel as EPSG:4326 Arrow tables. freestiler refuses CRSs that PROJ shifts by
datum grids (NAD83(HARN), NAD27 and a few others); those layers are reprojected
in Python with pyproj, with a warning, and still skip GeoJSON. A layer with no
CRS is refused. The clip buffer is always buffer=5 when the build accepts it.
Multi-layer tilesets use freestiler.freestile_layers when available, reading
each layer's source only when its turn comes. If that build's
freestile_layers has no gzip_level, ras2cng warns once and those tilesets
keep freestiler's default compression.
Both keep every feature at every zoom of a tileset and keep shared mesh edges
coincident. Neither ever drops features to cap tile size: thinning a uniform
mesh renders as stripes. Tile weight is bounded by each tileset's minimum zoom
instead (see below). The comparison behind this choice is in
feature_dev_notes/vector_tiler_evaluation_2026-10-12.md.
Short lines¶
A vector tile cannot hold a line of zero length, so a line whose two ends snap to one tile
pixel has no form at that zoom. With a freestiler build that has keep_short_lines (the fork
build 0.3.0.3 or later, see Installation) and Arrow input,
mesh_faces and breaklines, alone or joined to results, write such a line once per zoom as
a one-unit segment (1/4096 of a tile) that carries its properties, in the tile holding its
first vertex. Those layers are then complete at every zoom. At low zoom such a feature draws as
a dot the width of the line style.
Other line layers (conduits, BC and reference lines, structures) stay as they were, and a
line that collapses is absent at that zoom: their low-zoom tiles would repeat every feature's
properties, +18.4% of geometry.pmtiles on the Davis pipe network. Older freestiler builds,
RAS2CNG_FREESTILER_INPUT=geojson and tippecanoe also keep the old behaviour.
| Setting | Default | Effect |
|---|---|---|
RAS2CNG_KEEP_SHORT_LINES, CLI --keep-short-lines/--no-keep-short-lines |
on | 0 or --no-keep-short-lines turns it off |
The manifest's vectorShortLines records the layers that got the option, or why none did.
Sparse tilesets: line simplification, deduplication, sorted values¶
With a freestiler build that has them (the gpt-cmdr fork build 0.3.0.4; detected from the API, so older builds tile as before), three more options apply:
| Setting | Default | Effect |
|---|---|---|
RAS2CNG_TILE_LINE_SIMPLIFY, CLI --tile-line-simplify PX |
1 tile pixel | Per-zoom Douglas-Peucker on the lines of every layer except mesh_faces (and results joined to them), at every zoom. 0, off or --no-tile-line-simplify turns it off; --no-simplify turns it off with the polygon filters |
RAS2CNG_VECTOR_TILE_COMPACT, CLI --compact-tiles/--no-compact-tiles |
on | deduplicate and sort_values together; 0 turns both off |
RAS2CNG_VECTOR_TILE_SORT_VALUES |
auto |
sort_values alone: auto sorts tilesets without mesh layers, 1 every tileset, 0 none |
- Line simplification replaces the tiler's default pre-simplification of lines, which
kept 1.2-1.6 times tippecanoe's vertices on dense breaklines. Endpoints are kept, a line
that would collapse keeps its vertices, and
keep_short_linesstill applies, so no feature is lost: every breakline is present at every zoom. The worst distance from an input vertex to the drawn line is 1.6 tile pixels (about 0.1 CSS pixel), against 5.0 before. It is never applied tomesh_faces: a face's vertices are the cells' vertices. deduplicatestores identical tiles once, aspmtiles convertdoes for tippecanoe's output. Every tile is still addressed and decompresses to the same bytes.sort_valueswrites each layer's value table sorted and ahead of its features, which compresses better where values repeat; tiles decode to the same content. It is left off for tilesets with mesh layers, where it measured 3-6% larger. It changes the archive bytes, so turn it off for a byte comparison with an older archive.
geometry.pmtiles |
tippecanoe 2.82.0 (ras2cng's flags, with --drop-rate=1) |
freestiler 0.3.0.3 | freestiler 0.3.0.4, ras2cng defaults |
|---|---|---|---|
| Bald Eagle p07 | 972,440 | 1,300,546 (+33.7%) | 966,399 (-0.6%) |
Davis (without Terrain_Profiles) |
350,842 | 360,134 (+2.6%) | 343,964 (-2.0%) |
| UPGU3 | 7,048,586 | 9,369,259 | 7,248,146 (+2.8%) |
Mesh tilesets are unchanged by these options (deduplicate finds no duplicate mesh tile).
results.pmtiles is 0.2-3.4% smaller, almost all of it from sort_values.
The manifest records them: vectorSimplification.lines (enabled, tilePixels, layers, or
the reason it did not run), a per-layer simplification.tileLinePixels, and
vectorArchive (deduplicate, sortValues, sortValuesScope, archiveOnlyColumns).
Columns kept out of tiles¶
Terrain_Profiles, the station/elevation list ras-commander attaches to every pipe
conduit, stays in the archive GeoParquet (WHERE layer = 'pipe_conduits') and is not
delivered in tiles. It was delivered as the text of a NumPy array, repeated in every tile
a conduit crosses at every zoom: 70% of the Davis geometry.pmtiles (1,129,401 bytes with
it, 343,964 without). Compact JSON was measured and is not small either (1,028,364 bytes;
769,016 at two decimals).
tippecanoe¶
The tippecanoe path now passes --drop-rate=1. Tippecanoe's default rate thins point
layers below the maximum zoom whatever the size limits say: the Davis pipe network lost
2,243 of its node points over z0-z16 (1 of 133 left at z0). Tilesets with point layers
built with tippecanoe by an earlier version are incomplete at low zoom; rebuild them.
Raster Tiler¶
Terrain and result rasters (Stored Maps, calculated layers, ras2cng pmtiles on
a GeoTIFF) are colorized, warped to Web Mercator and written as PNG PMTiles by
one of two backends, chosen with RAS2CNG_RASTER_TILER:
| Value | Backend | Notes |
|---|---|---|
auto (default) |
terrio when installed and the raster fits, otherwise GDAL | terrio ships in the pmtiles, terrio and all extras |
terrio |
In-process pure-Rust tiler (terrio) | No GDAL or pmtiles CLIs; terrain hillshade; whole raster held in memory |
gdal |
gdaldem → gdalwarp → gdal_translate → gdaladdo → pmtiles convert |
Streams through files, so any size; no hillshade |
Measured on Bald Eagle Creek rasters through the real packagers:
| Layer | terrio | GDAL chain |
|---|---|---|
| Terrain, 6705 × 4852 px at 20 ft | 6.8 s (hillshaded) | 13.4 s |
| Depth Stored Map | 1.6 s | 4.7 s |
At full resolution terrio's tile colours are within 0.2/255 of the GDAL chain on average. terrio also fixes two display defects of the GDAL chain:
- Flood extent holds at every zoom. Result-layer overviews use
NEAREST, so the visible wet area at z10 is 1.000× the full-resolution area. The GDAL chain'sgdaladdo -r averageshowed 1.225× at z10. That is the same extent growthras2cng.cogprevents in COG overviews. - No dark terrain fringe. The GDAL chain's semi-transparent terrain-edge pixels were black at every overview level; terrio's keep the ramp colour.
Terrain overviews use AVERAGE (a smooth, fully covered surface).
RAS2CNG_RASTER_TILE_RESAMPLING=NEAREST|AVERAGE overrides both kinds. Rasters
larger than RAS2CNG_TERRIO_MAX_PIXELS (default 400 million pixels) use the
GDAL chain under auto, because terrio processes the raster in memory.
Layer Behavior¶
- Geometry is delivered as one vector PMTiles file, with source layers for every archive
sublayer and a
Model Extentslayer for each geometry configuration. - Native terrain TIFF footprints and terrain-modification construction vectors are delivered
as queryable vector layers under
Terrains. Modification lines, polygons, and elevation control points preserve their operation metadata; they are not flattened into the final DEM. - Only the first geometry group is enabled at startup. Within it,
2D Mesh Cellsis the preferred default; for a 1D model the first useful line layer is selected instead. - Every additional geometry and every other sublayer remains available in the manifest but starts hidden.
- Browser delivery is always 2D. A source geometry with a
NaNZ ordinate is normalized to 2D before reprojection so it cannot invalidate a PMTiles layer; the archived GeoParquet remains unchanged. - Dense
2D Mesh Cellsand2D Mesh Facesare delivered in a separate PMTiles source that starts at the detail floor: zoom 13, or higher for a fine mesh -- the first zoom where the median cell is at least two screen pixels across. Every cell is present at every zoom where the layer is drawn. Below the floor, complete mesh tiles are multi-megabyte (measured 1.2-1.6 MB at z12 and 4-9 MB at z10), and thinning them to fit renders as stripes, so the layer is simply not drawn there. - Reference line and point summaries are stored long, one row per feature, variable and
statistic. A tile feature carries one row, so the viewer pivots them to
flow_maximum,flow_maximum_time,flow_unitsand so on. Every value is kept, and a table where a value would be lost is refused. The archive keeps the long table. --vector-resultscreates separate sources, grouped by plan. Each result is raw HDF summary data joined to the matching model feature only for visual delivery. Mesh results join onmesh_nameand the cell or face ID, because IDs restart in every 2D flow area; keys that are not unique are refused rather than attributed to a feature. Its manifest record identifies its raw HDF source and geometry join key (rawResult.joinKeys). Results joined to sparse features (cross sections, reference lines and points) go inresults.pmtilesat every zoom; results joined to mesh cells or faces are as dense as the mesh and go inresults-detail.pmtiles, which shares the detail floor. Use the published stored-map rasters for the overview zooms.- With a freestiler that has Arrow input, mesh results use far less memory: the mesh is kept on disk and shared by its result layers. On a 1,063,548-cell model the peak goes from 16,283 MiB to 2,265 MiB, with byte-identical tiles. tippecanoe, GeoJSON input and older freestiler builds still join in pandas, reading only each variable's rows.
- Steady 1D cross-section results are split into one layer per HDF profile. Each layer joins
to its source cross section on
River,Reach, andRS, so a profile selection does not create duplicate coincident features. The records remain raw HDF element values, not an interpolated water-surface or velocity surface. - This command does not create interpolated result maps. Generate RASMapper stored maps
with
RasProcess.store_maps, publish their COGs, and add those as raster result sources.
Output¶
viewer/
├── manifest.json
├── model_extent.geojson
└── tiles/
├── geometry.pmtiles
├── geometry-detail.pmtiles # Dense mesh cells/faces, from the detail floor (z13+)
├── results.pmtiles # --vector-results joined to sparse features
└── results-detail.pmtiles # --vector-results joined to mesh cells/faces, detail floor
The output directory must be empty. This prevents a failed or partial run from silently mixing artifacts from different input archives.
Terrain Publication¶
Publish terrain after the vector viewer is built. ras2cng maplibre-terrain consumes the
archived terrain COG, adds a terrain PMTiles layer to the existing viewer manifest, and
keeps the COG as the numerical source for map identify queries:
ras2cng maplibre-terrain ARCHIVE_DIR/terrain/Terrain_cog.tif VIEWER_DIR \
--scratch-dir /large-local-scratch
The command creates viewer/tiles/terrain.pmtiles, enables the terrain layer by default,
and adds it to the Terrain control group. Its display palette is the RASMapper terrain
palette stretched over the source elevation range. The original COG remains unmodified and
is referenced as sourceCog, allowing a click to report the original elevation rather than
the colorized tile value.
With the terrio raster tiler the display tiles are hillshaded by default: a
multidirectional terrio hillshade is multiplied into the terrain colours, as RAS
Mapper shades terrain. terrio's hillshade is not pixel-identical to gdaldem;
that is accepted for a display layer. Identify values still come from the
unshaded COG. --no-hillshade publishes flat colour relief, and the manifest
records hillshade and rasterTiler on the terrain tileset. Hillshaded archives
are larger (Bald Eagle: 6.3 MB against 3.9 MB flat), because shading adds texture.
The display raster is reprojected to Web Mercator only for tiled delivery. Its maximum zoom
is capped at the native terrain cell resolution; --max-zoom may lower that cap but cannot
force an upsample. Use an external --source-cog href only when the archive layout differs
from the normal sibling archive/ and viewer/ directories.
Raster warps use four GDAL worker threads by default to remain predictable on shared compute
containers. Set RAS2CNG_GDAL_THREADS for an isolated worker when a different bounded limit
is appropriate.
Stored Map Publication¶
Use the numerical COG created by RASMapper/RasProcess as the authoritative result source.
maplibre-stored-map creates a precolored PMTiles display derivative and records both
resources under the associated plan:
ras2cng maplibre-stored-map maps/p03/Velocity_Max.cog.tif VIEWER_DIR \
--plan p03 --geometry g03 --map-type Velocity --profile Max \
--name "Velocity (Max)" --units ft/s \
--source-cog ../archive/maps/p03/Velocity_Max.cog.tif
The PMTiles derivative is the fast default display. Identify reads the numerical COG, not
the colorized pixels. The manifest records RASMapper/RasProcess as the interpolation
authority, making the layer distinct from raw HDF computation-element values. Raster nodata
is transparent. Stored Maps are hidden initially unless --visible is passed.
For a complete project tranche, use maplibre-import-stored-maps with its default
--require-all policy. Admission then requires every completed plan to contain Depth,
WSE, Velocity, Froude Number, Shear Stress, Depth x Velocity, Depth x Velocity Squared,
Arrival Time, Duration, Percent Time Inundated, and the inundation boundary. Reserve
--allow-partial for explicit diagnostic or exploratory bundles.
Tranche imports cap precolored display PMTiles at zoom 16 by default. This limits browser
payload and packaging work for very fine or very large result grids without changing the
authoritative numerical COG. Identify and analysis therefore retain the full source fidelity.
Use --max-zoom to select a lower display cap; the renderer will not upsample beyond the
native grid resolution.
Use --domain-policy current-view only when the deployed WebGIS service supports bounded
window statistics and styled tiles. A precolored PMTiles file cannot be faithfully recolored
because it no longer contains the original scalar values.
Attach service asset IDs after all published paths are final. See the Numeric Raster Service guide. Every service-backed continuous terrain or raster-result layer exposes a Color Map by Extents switch plus Dataset and Custom range modes. The viewer immediately restores the PMTiles dataset view if a statistics or styled-tile request fails.
Calculated Layer Publication¶
Controlled outputs from raster-calculate publish under each plan's Calculated Layers
branch with maplibre-calculated-map. Their provenance records both ras2cng's arithmetic
and RASMapper/RasProcess as the source-surface interpolation authority. See
Controlled Raster Recipes for synchronized profile requirements and
the fixed hazard/threshold categories.
Example Library Publication Gate¶
Validate a complete archive/viewer pair before catalog admission:
ras2cng validate-publication VIEWER_DIR/manifest.json ARCHIVE_DIR/manifest.json
ras2cng validate-publication VIEWER_DIR/manifest.json ARCHIVE_DIR/manifest.json \
--check-http-ranges --json
The gate requires manifest v2, a validated CRS, API-derived and initially visible model
extents, valid plan/geometry/terrain associations, raw HDF and Stored Map result families,
numerical COG provenance, and visible terrain for a 2D model. Local COGs are checked for CRS,
tiling, overviews, and nodata/mask behavior; hosted artifacts can be required to return HTTP
206 Partial Content for byte-range requests.