Skip to content

ras2cng.pmtiles

ras2cng.pmtiles

PMTiles generation for the ras2cng pmtiles CLI surface.

Vector tiles: - GeoParquet -> reproject to EPSG:4326 -> newline-delimited GeoJSON -> tippecanoe -> PMTiles, or GeoParquet -> freestiler -> PMTiles when RAS2CNG_VECTOR_TILER resolves to freestiler (see :mod:ras2cng.vector_tiles). A freestiler with Arrow input reads the GeoParquet as an Arrow table and reprojects it in Rust (in Python with pyproj when it refuses the CRS); older builds get a GeoDataFrame.

Raster tiles: - delegated to :mod:ras2cng.maplibre, which colorizes at native resolution, warps to an exact Web Mercator zoom, and builds the tile pyramid.

Note: tippecanoe, gdal, and pmtiles are command-line tools and must be installed separately and available on PATH. freestiler is the optional ras2cng[freestiler] extra.

:mod:ras2cng.maplibre is the maintained implementation of both jobs and streams its inputs; this module is the older single-file CLI surface kept for ras2cng pmtiles.

generate_mesh_pmtiles(input_file, output, *, layer_name='mesh_cells', mesh_names=None, properties=None, min_zoom=10, max_zoom=14, source_crs=None, threads=None)

Tile HDF mesh cells through Rust, using pyproj for bulk reprojection.

Requires the separately built ras-commander-fast-hdf extension. The source may be geometry HDF or a computed plan containing geometry. Properties are column arrays keyed by mesh name, indexed by original cell ID. All selected meshes share a source layer, with mesh_name/cell_id properties preserving identity. This explicit HDF route does not use the GeoParquet tiler selector.

Source code in ras2cng/pmtiles.py
def generate_mesh_pmtiles(
    input_file: Path,
    output: Path,
    *,
    layer_name: str = "mesh_cells",
    mesh_names: Optional[list[str]] = None,
    properties: Optional[dict] = None,
    min_zoom: int = 10,
    max_zoom: int = 14,
    source_crs: Optional[str] = None,
    threads: Optional[int] = None,
) -> Path:
    """Tile HDF mesh cells through Rust, using pyproj for bulk reprojection.

    Requires the separately built ras-commander-fast-hdf extension. The source
    may be geometry HDF or a computed plan containing geometry. Properties are
    column arrays keyed by mesh name, indexed by original cell ID. All selected
    meshes share a source layer, with mesh_name/cell_id properties preserving
    identity. This explicit HDF route does not use the GeoParquet tiler selector.
    """
    from ras_commander.fast_hdf import export_mesh_pmtiles
    from ras2cng.cog import atomic_output

    input_file = Path(input_file)
    output = Path(output)
    if input_file.resolve() == output.resolve():
        raise ValueError("Output must not replace the source HDF")
    with atomic_output(output, suffix=".pmtiles") as staged:
        export_mesh_pmtiles(
            input_file, staged, layer_name=layer_name, mesh_names=mesh_names,
            properties=properties, min_zoom=min_zoom, max_zoom=max_zoom,
            source_crs=source_crs, threads=threads, backend="rust",
        )
    return output

generate_raster_pmtiles(input_file, output, min_zoom=None, max_zoom=None, *, map_type='depth')

Render a numeric raster to PNG PMTiles via the maplibre pipeline.

This used to run gdal_translate -of MBTiles -co TILE_FORMAT=PNG directly on the source. Against a float32 depth or WSE COG that produces an 8-bit image with no color ramp and no alpha -- nodata renders as opaque black -- and it built no overviews at all, so the MINZOOM creation option had nothing to apply to.

:func:ras2cng.maplibre._render_raster_pmtiles is the correct implementation of this job: it applies the color ramp at native resolution before any downsampling, warps to an exact Web Mercator zoom resolution, and builds the pyramid.

Source code in ras2cng/pmtiles.py
def generate_raster_pmtiles(
    input_file: Path,
    output: Path,
    min_zoom: Optional[int] = None,
    max_zoom: Optional[int] = None,
    *,
    map_type: str = "depth",
):
    """Render a numeric raster to PNG PMTiles via the maplibre pipeline.

    This used to run ``gdal_translate -of MBTiles -co TILE_FORMAT=PNG`` directly
    on the source.  Against a float32 depth or WSE COG that produces an 8-bit
    image with no color ramp and no alpha -- nodata renders as opaque black --
    and it built no overviews at all, so the ``MINZOOM`` creation option had
    nothing to apply to.

    :func:`ras2cng.maplibre._render_raster_pmtiles` is the correct
    implementation of this job: it applies the color ramp at native resolution
    before any downsampling, warps to an exact Web Mercator zoom resolution, and
    builds the pyramid.
    """

    from ras2cng import maplibre

    input_path = Path(input_file)
    output = Path(output)
    output.parent.mkdir(parents=True, exist_ok=True)

    backend = maplibre._raster_backend_for(input_path)

    info = maplibre._gdalinfo(input_path)
    bands = info.get("bands") or []
    if not bands:
        raise ValueError(f"Raster has no readable bands: {input_path}")
    band = bands[0]
    stats = {
        "minimum": float(band.get("minimum", 0.0)),
        "maximum": float(band.get("maximum", 1.0)),
    }

    def ramp_writer(path: Path) -> None:
        maplibre._result_color_ramp(stats, map_type, path)

    with tempfile.TemporaryDirectory(prefix="ras2cng-raster-pmtiles-") as scratch:
        maplibre._render_raster_pmtiles(
            input_path,
            output,
            ramp_writer=ramp_writer,
            max_zoom=max_zoom,
            scratch_dir=Path(scratch),
            prefix="cli-raster",
            backend=backend,
        )