Deploy punkst results to CartoScope

punkst deploy-cartoscope packages completed punkst workflow output into a CartoScope deployment directory.

Run it after the standard punkst workflow has finished and one or more factor models have been fitted.

Scope

deploy-cartoscope starts from the output of a completed punkst analysis workflow. It takes tiled transcripts, fitted models, pixel decode results, and optional cell projection/boundary data, then writes the PMTiles and metadata files CartoScope needs.

Deployment currently covers transcript density as the default basemap; pixel/molecule, hexagon, and cell level factor inferences results; and limited support for including morphology images. It is meant to be a lightweight alternative to cartloader for fast exploration.

Quickstart

If you have run a workflow generated by the template Makefile in punkst/examples/basic/, you can prepare the CartoScope deployment directory directly by providing the same input config file to deploy-cartoscope, which will locate output files based on the naming convention in the template Makefile.

punkst deploy-cartoscope --pmtiles-format MVT \
  --config /path/to/punkst/output/config.json \
  --id sample-id --title "Sample title" \
  --out-dir /path/for/carto --threads 4

--pmtiles-format is required and must be either MLT or MVT. Currently CartoScope prefers MVT.

Existing output files are reused by default. Add --overwrite to regenerate and overwrite files that are already present. If --overwrite is not set, files with the intended output names that exist in the output directory are reused, except for sidecars that deployment can identify as incompatible.

Serve the data from a local machine

Open a terminal and serve the deployment directory (which contains catalog.yaml generated by deploy-cartoscope)

cd /path/for/carto
npx http-server --cors

Then use the URL http://127.0.0.1:8080/catalog.yaml (the actual port may differ) on CartoScope.

Input Modes

Standard Workflow Config

Use --config for output produced by the standard workflow template (see Quickstart and punkst/examples/basic/).

For each model prefix, the workflow output should contain files like:

<model-prefix>.results.tsv
<model-prefix>.model.tsv
<model-prefix>.color.rgb.tsv
<model-prefix>.pixel.bin
<model-prefix>.pixel.index
<model-prefix>.pixel.pseudobulk.tsv
<model-prefix>.pixel.de_bulk.tsv

The standard template writes model prefixes as h<H>.k<K>, for example h12.k24 for hexagon grid size 12 and K=24 factors.

If workflow.pixel_decode_mode is set, deployment uses the matching pixel-output suffix:

pixel             -> <model-prefix>.pixel.*
feature_pixel     -> <model-prefix>.sf_pixel.*
single_molecule   -> <model-prefix>.sgl_mol.*

Default deployment model IDs use names such as h12-k24, h12-k24-sf-pixel, and h12-k24-sgl-mol.

Deploy only selected models with --model-prefix <model-prefix>, e.g. --model-prefix h12.k24. The normalized model ID is also accepted; normalization replaces _, ., /, and \ with -, so h12.k24 becomes h12-k24.

Explicit Input JSON

Use --input-json when your data was not produced by (a single run of) the standard workflow template.

punkst deploy-cartoscope --pmtiles-format MVT \
  --input-json /path/to/deploy_inputs.json \
  --id sample-id --title "Sample title" \
  --out-dir /path/for/carto --threads 4

Example with the standard pipeline

{
  "transcripts": {
    "tiled_prefix": "/path/to/transcripts.tiled",
    "feature_count_tsv": "/path/to/transcripts.tiled.features.tsv",
    "icol_x": 0,
    "icol_y": 1,
    "icol_feature": 2,
    "icol_count": 3,
    "null_str": "NA"
  },
  "models": [
    {
      "id": "<model-id>",
      "hex_grid_dist": 12,
      "results_tsv": "/path/to/<model-prefix>.results.tsv",
      "model_tsv": "/path/to/<model-prefix>.model.tsv",
      "color_rgb_tsv": "/path/to/<model-prefix>.color.rgb.tsv",
      "pixel_decode_mode": "pixel",
      "pixel_prefix": "/path/to/<model-prefix>.pixel",
      "de_tsv": "/path/to/<model-prefix>.pixel.de_bulk.tsv",
      "pseudobulk_tsv": "/path/to/<model-prefix>.pixel.pseudobulk.tsv"
    }
  ]
}

You can add more than one model entry, each with a different id.

pixel_decode_mode is optional; when omitted, deployment infers the mode based on files provided through pixel_prefix. Depending on the decoding mode, your pixel_prefix (if you used the template workflow) may have a different suffix such as .sf_pixel or .sgl_mol instead of .pixel.

When pseudobulk_tsv is omitted, it is assumed to be <pixel_prefix>.pseudobulk.tsv.

Set skip_hex_pmtiles: true on a default model to package only pixel raster and raw-pixel assets for that model. In this mode results_tsv and hex_grid_dist may be omitted, and the generated catalog will not include a pmtiles.hex entry for the model.

If the same fitted model is decoded in multiple pixel modes, list those outputs as separate model entries with different id values. The entries can reuse the same results_tsv, model_tsv, and color_rgb_tsv while pointing to different pixel prefixes, pseudobulk tables, and DE tables.

For results_tsv with nonstandard header:

Outputs produced by punkst normally use numeric column names 0,...,K-1 for factor probabilities, or use columns names matching that in the pseudobulk matrix (pseudobulk_tsv). If your results_tsv has a different header pattern, you can specify the 0-based inclusive column index range by adding factor_col_begin and factor_col_end to the model entry. The columns in the specified range should be ordered in the same way as those in the pseudobulk matrix.

Add cell-level results and cell boundaries

Cell-level PMTiles from the same model as the pixel level results can be added to that model entry. There are two ways to provide cell-level data (the data up to "pseudobulk_tsv" are the same as the above standard pixel-only example):

1. Use existing PMTiles, which can be generated by cells2pmtiles, under cell_pmtiles:

{
  "id": "<model-id>",
  "hex_grid_dist": 12,
  "results_tsv": "/path/to/<model-prefix>.results.tsv",
  "model_tsv": "/path/to/<model-prefix>.model.tsv",
  "color_rgb_tsv": "/path/to/<model-prefix>.color.rgb.tsv",
  "pixel_prefix": "/path/to/<model-prefix>.pixel",
  "de_tsv": "/path/to/<model-prefix>.pixel.de_bulk.tsv",
  "pseudobulk_tsv": "/path/to/<model-prefix>.pixel.pseudobulk.tsv",
  "cell_pmtiles": {
    "cells": "/path/to/<model-id>-cells.pmtiles",
    "boundaries": "/path/to/<model-id>-boundaries.pmtiles"
  }
}

1. Provide source files that deployment will pass through cells2pmtiles:

{
  "id": "<model-id>",
  "hex_grid_dist": 12,
  "results_tsv": "/path/to/<model-prefix>.results.tsv",
  "model_tsv": "/path/to/<model-prefix>.model.tsv",
  "color_rgb_tsv": "/path/to/<model-prefix>.color.rgb.tsv",
  "pixel_prefix": "/path/to/<model-prefix>.pixel",
  "de_tsv": "/path/to/<model-prefix>.pixel.de_bulk.tsv",
  "pseudobulk_tsv": "/path/to/<model-prefix>.pixel.pseudobulk.tsv",
  "cell_results_tsv": "/path/to/cells.results.tsv",
  "cell_result_id_col": "cell_id",
  "cell_boundaries": "/path/to/cell_boundaries.tsv",
  "cell_boundary_format": "table",
  "cell_b_icol_id": 0,
  "cell_b_icol_x": 1,
  "cell_b_icol_y": 2
}

File paths can be absolute or relative to the directory of the input JSON file. For prebuilt PMTiles, if the source path is already the target file inside the deployment directory, deployment leaves it in place.

For source cell boundaries, cell_boundary_format can be omitted in the common case. cells2pmtiles infers .json/.geojson as GeoJSON and .tsv/.csv/.txt as flat tables, including .gz variants. Boundary and center tables can be comma- or tab-delimited, may include # comment lines, and may be either headered or headerless when the relevant ID/X/Y columns are provided as 0-based indexes. The cell projection/result TSV uses a named ID column via cell_result_id_col.

The cell center table is optional. If cell_centers_tsv is omitted, cells2pmtiles computes centers from the boundary polygons. If a center table is provided, use cell_c_icol_id, cell_c_icol_x, and cell_c_icol_y to specify its 0-based cell ID and coordinate columns.

Boundaries provided as flat tables should contain one vertex per row. All rows for a cell must be consecutive, but the cell order can be arbitrary. In the file cell_boundaries.tsv from the unpacked example dataset, the cell ID, x coordinate, and y coordinate are in columns 0, 1, and 2, respectively, so the matching JSON fields are cell_b_icol_id: 0, cell_b_icol_x: 1, and cell_b_icol_y: 2.

#cell_index vertex_x    vertex_y
0   7266.073738 6771.112935
0   7267.797005 6774.856543
0   7269.785159 6777.095995

The equivalent GeoJSON example in the unpacked dataset is cell_boundaries.geojson. It is a standard FeatureCollection; each feature has a Polygon or MultiPolygon geometry, and the cell ID is stored in properties.cell_id.

{
  "type": "FeatureCollection",
  "features": [
    {
      "type": "Feature",
      "id": "0",
      "properties": {"cell_id": "0"},
      "geometry": {
        "type": "Polygon",
        "coordinates": [
          [
            [7266.073738, 6771.112935],
            [7267.797005, 6774.856543],
            [7269.785159, 6777.095995],
            [7266.073738, 6771.112935]
          ]
        ]
      }
    }
  ]
}

To use such a GeoJSON file for cell boundaries, replace the table-boundary fields in the previous JSON example with:

{
  "cell_boundaries": "/path/to/cell_boundaries.geojson",
  "cell_boundary_id_prop": "cell_id"
}

cell_boundary_id_prop is only necessary if the cell ID property has a name other than cell_id.

Cell-only model entry

To deploy a separate set of cell-only factor results, add a model entry with "type": "cell_only" alongside at least one default model with pixel-level data.

This mode assumes the cell-level data has its own model, thus requiring pseudobulk_tsv, rgb_tsv or color_rgb_tsv. de_tsv is optional, and if it is not provided de-chisq is run using the pseudobulk matrix.

{
  "id": "<cell-model-id>",
  "type": "cell_only",
  "results_tsv": "/path/to/cells.results.tsv",
  "result_id_col": "cell_id",
  "rgb_tsv": "/path/to/cells-rgb.tsv",
  "pseudobulk_tsv": "/path/to/cells.pseudobulk.tsv",
  "boundaries": "/path/to/cell_boundaries.geojson"
}

(The available fields for providing cell boundaries are the same as in the previous example; here we show the GeoJSON option for variety.)

You can also replace "boundaries" with prebuilt PMTiles directly through

  "cell_pmtiles": {
    "cells": "/path/to/<model-id>-cells.pmtiles",
    "boundaries": "/path/to/<model-id>-boundaries.pmtiles"
  }

Add background image PMTiles

Background images can be added as CartoScope basemaps in explicit input JSON mode. Images are not aligned or registered by punkst. Provide the alignment through pixel size plus offset, a full 3x3 transform, or two image grid reference points that map to the same micron coordinate system used by the transcript data.

Supported image inputs are PNG and narrowly defined TIFF: tiled TIFF with uncompressed or Deflate/zlib-compressed tiles, using 8-bit RGB/RGBA, 8-bit grayscale, or 16-bit grayscale pixels. Unsupported OME-TIFF, JPEG/JPEG-2000/LZW-compressed TIFF, and other fancier formats should be converted first.

convert OME-TIFF

Use ext/py/convert_tiff_for_image2pmtiles.py to convert OME-TIFF or generic TIFF files into the supported tiled TIFF subset. The helper writes uint8 output by default, using percentile scaling for non-uint8 inputs (--uint8-percentiles 1 99 by default); use --preserve-depth only when you intentionally want to keep supported 16-bit grayscale TIFF data for native punkst scaling. The script uses Python numpy and tifffile. For TIFF compression codecs that tifffile delegates to optional decoders, install the matching Python package as well; in practice, JPEG/JPEG2000-compressed OME-TIFFs commonly require imagecodecs.

python -m pip install numpy tifffile imagecodecs

Example OME/generic compressed TIFF conversion:

python ext/py/convert_tiff_for_image2pmtiles.py \
  --input spatial/tissue_hires_image.ome.tif \
  --output carto/HnE.supported.tif \
  --id HnE

The conversion helper writes <output>.image2pmtiles.json that can be passed on to deploy-cartoscope with --image-json directly, which runs image2pmtiles internally to produce CartoScope-compatible PMTiles. When OME physical pixel metadata is available, the JSON records a pixel-to-micron transform for the selected --series, --level, and --page based on the metadata, which is then used during PMTiles construction.

For generic TIFFs without OME metadata, pass either --microns-per-pixel with optional offsets --offset-x-um --offset-y-um, a full 3x3 matrix with --transform (row-wise flatten to 9 comma/space-separated values), or --pix-zero x1 y1 --pix-max x2 y2; otherwise the JSON is marked requires_transform.

Supply (converted) TIFF to deploy-cartoscope

If your image files are converted by with above python helper ext/py/convert_tiff_for_image2pmtiles.py, pass its output <output>.image2pmtiles.json to deploy-cartoscope directly with --image-json.

Otherwise, include supported source image information as additional sections in the input JSON file for deploy-cartoscope:

Example with two images:

{
  "images": [
    {
      "id": "HnE",
      "src": "spatial/tissue_hires_image.tif",
      "microns_per_pixel": 0.5,
      "offset_x_um": 0,
      "offset_y_um": 0
    },
    {
      "id": "DAPI",
      "src": "dapi.supported.tif",
      "transform": [
        [0.5, 0.0, 10.0],
        [0.0, 0.5, 20.0],
        [0.0, 0.0, 1.0]
      ]
    },
    {
      "id": "IF",
      "src": "if.supported.tif",
      "pix_zero": [10.0, 20.0],
      "pix_max": [510.0, 420.0]
    }
  ]
}

(Note: provide exactly one alignment mode for each image; if one of the images is converted by the python helper you can copy over the JSON section under "deploy_cartoscope" from image2pmtiles.json)

deploy-cartoscope Options

punkst deploy-cartoscope accepts the following command-line options:

Option	Default	Description
--config	none	Standard workflow config JSON. Provide exactly one of --config or --input-json.
--input-json	none	Explicit deployment input JSON. Provide exactly one of --config or --input-json.
--image-json	none	Additional image fragment JSON, typically <output>.image2pmtiles.json from convert_tiff_for_image2pmtiles.py. May be repeated; requires --input-json.
--out-dir	required	Output deployment directory.
--id	required	Dataset ID written to the deployment metadata.
--title	empty	Dataset title.
--desc	empty	Dataset description.
--pmtiles-format	required	Tile encoding format: MLT or MVT.
--model-prefix	all models	Optional model prefixes or normalized model IDs to deploy. Can be repeated or given multiple values, depending on shell usage.
--point-min-zoom	10	Minimum zoom for transcript PMTiles pyramids.
--point-max-zoom	18	Maximum zoom for transcript PMTiles export.
--polygon-min-zoom	10	Minimum zoom for hex and cell PMTiles pyramids.
--polygon-max-zoom	18	Maximum zoom for hex and cell PMTiles export.
--n-gene-bins	50	Maximum number of gene bins for transcript PMTiles in adaptive mode.
--gene-bin-mode	adaptive	Gene-bin packing mode: adaptive or fixed. Use fixed for legacy contiguous count buckets.
--gene-bin-target-molecules	1000000	Target molecules per adaptive gene bin.
--gene-bin-singleton-ratio	1.0	Put genes with counts at least this multiple of the target into singleton bins when capacity allows.
--threads	4	Number of threads.
--max-point-tile-bytes	5000000	Maximum compressed bytes per point tile.
--max-point-tile-features	50000	Maximum features per point tile.
--max-polygon-tile-bytes	500000	Maximum compressed bytes per polygon tile.
--max-polygon-tile-features	5000	Maximum features per polygon tile.
--basemap-min-zoom	7	Minimum zoom for SGE mono basemap PMTiles.
--basemap-max-zoom	--point-max-zoom	Maximum zoom for SGE mono basemap PMTiles.
--mono-max-zoom-from-raw	--basemap-max-zoom	Parse raw data for SGE mono basemap zoom levels greater than or equal to this value; derive lower zooms from parent layers.
--basemap-adjust-quantile	0.99	Quantile for SGE mono basemap density auto-adjustment.
--basemap-display-transform	linear	Display transform for SGE mono basemap intensity: linear or log1p.
--scale-factor-compression	10.0	Pyramid compression aggressiveness estimate.
--hex-prob-thres	0.001	Minimum hex factor probability retained.
--null-str	none	Replace empty string query properties with this placeholder in transcript PMTiles packaging. If omitted, empty strings are preserved.
--use-png	false	Use pre-rendered pixel PNGs for raster PMTiles in --config mode.
--skip-basemap	false	Skip SGE mono basemap PMTiles generation.
--overwrite	false	Overwrite existing deployment output files.

Output

catalog.yaml in the deployment directory registers each factor with the available PMTiles. Serve that file to CartoScope to visualize the data.

A typical catalog.yaml looks like this:

assets:
  sge:
    all: genes_all.pmtiles
    bins:
    - genes_bin1.pmtiles
    counts: genes_bin_counts.json
  overview: sge-mono-dark.pmtiles
  factors:
  - id: h12-k24
    model_id: h12-k24
    decode_id: h12-k24-pixel
    raw_pixel_col: h12-k24-pixel
    de: h12-k24-bulk-de.tsv
    info: h12-k24-info.tsv
    rgb: h12-k24-rgb.tsv
    pmtiles:
      hex: h12-k24.pmtiles
      raster: h12-k24-pixel-raster.pmtiles
      raw_pixel: genes_all.pmtiles
      cells: h12-k24-cells.pmtiles
      boundaries: h12-k24-boundaries.pmtiles
  basemap:
    sge:
      default: dark
      dark: sge-mono-dark.pmtiles

For models with non-numeric factor names, the factor entry also includes alias: <model-id>-alias.tsv.

PMTiles and Zooms

(See more about PMTiles utilities in Modules)

Transcript PMTiles are written at --point-max-zoom, then pyramid levels are built down to --point-min-zoom.

When existing transcript PMTiles are reused, they must already cover the requested --point-max-zoom. Deployment can add missing lower zoom pyramid levels in place, but it cannot synthesize higher zoom tiles from an existing lower-max-zoom archive; rerun with --overwrite after increasing --point-max-zoom.

Hexagon PMTiles are written at --polygon-max-zoom, then pyramid levels are built down to --polygon-min-zoom.

Cell PMTiles generated from source inputs are also written at --polygon-max-zoom, then pyramids are built down to --polygon-min-zoom. This applies to both cell-center points and cell-boundary polygons.

The mono SGE basemap is written as PNG raster PMTiles (disable with --skip-basemap). Its zoom range and density scaling are controlled separately from vector PMTiles:

--basemap-min-zoom 7
--basemap-max-zoom 18
--mono-max-zoom-from-raw 18
--basemap-adjust-quantile 0.99
--basemap-display-transform linear

If --basemap-max-zoom is omitted, it defaults to --point-max-zoom.

By default, the basemap (transcript density) parses raw transcript counts only at --basemap-max-zoom and derives lower zooms by summing parent layers. The lazy lower-zoom path preserves full accumulated counts until final PNG encoding. Use --mono-max-zoom-from-raw to parse raw data for zooms greater than or equal to that value, and use --basemap-display-transform log1p to compress high-density regions while preserving visible heterogeneity.

Write cell-level PMTiles separately

punkst cells2pmtiles packages cell-level factor assignments, cell centers, and cell boundary geometry into CartoScope-ready PMTiles. It writes geometry PMTiles only; CartoScope sidecars such as DE, pseudobulk, factor info, RGB tables, ficture_assets.json, and catalog.yaml are produced by punkst deploy-cartoscope.

Typical use:

punkst lda-transform \
  --in-model model.tsv \
  --in-dge-dir cell_feature_matrix/ \
  --out-prefix cells \
  --topk-only 3

punkst cells2pmtiles \
  --in-results cells.results.tsv \
  --id-col cell_id \
  --in-boundaries cell_boundaries.geojson \
  --out-prefix carto/cells \
  --format MVT --min-zoom 10 --max-zoom 18

Input

The result table can contain dense factor columns named 0..K-1, compact top-k columns from lda-transform --topk-only, or topK/topP columns:

cell_id K1  K2  K3  P1  P2  P3

Use --id-col to select the cell ID column in the result table by name. For dense factor columns, --top-k controls how many top factors are retained (default: 3).

Boundary input may be GeoJSON Feature records with Polygon or MultiPolygon geometry, or a flat TSV/CSV table with consecutive vertices per cell. For table boundaries, use --b-icol-id, --b-icol-x, and --b-icol-y to specify the 0-based column indexes for cell ID and coordinates.

When --boundary-format is left as auto, cells2pmtiles infers JSON/GeoJSON vs table input from the file extension (.json, .geojson, .tsv, .csv, .txt, including .gz variants). Flat boundary and center tables may be comma- or tab-delimited. Lines beginning with # are skipped, and the first non-comment line is treated as a header only when the configured coordinate columns do not parse as numeric values.

Output

<prefix>-boundaries.pmtiles
<prefix>-cells.pmtiles

cells2pmtiles Options

punkst cells2pmtiles accepts the following command-line options:

Option	Default	Description
--in-results	required	Cell projection result TSV.
--in-boundaries	required	Cell boundary GeoJSON/JSON or flat TSV/CSV table.
--in-centers	none	Optional cell center TSV/CSV. If omitted, centers are computed from boundary geometry.
--out-prefix	required	Output prefix. Writes <prefix>-cells.pmtiles and <prefix>-boundaries.pmtiles.
--format	MVT	Tile encoding format: MLT or MVT.
--boundary-format	auto	Boundary input format: auto, geojson, json, table, tsv, or csv.
--id-col	cell_id	Cell ID column name in projection results.
--top-k	3	Number of top factors to keep from dense factor columns.
--b-icol-id	0	0-based cell ID column in table boundaries.
--b-icol-x	1	0-based x column in table boundaries.
--b-icol-y	2	0-based y column in table boundaries.
--c-icol-id	0	0-based cell ID column in --in-centers.
--c-icol-x	1	0-based center x column in --in-centers.
--c-icol-y	2	0-based center y column in --in-centers.
--boundary-id-prop	cell_id	Cell ID property in boundary GeoJSON features.
--min-zoom	10	Minimum zoom for pyramids.
--max-zoom	18	Maximum zoom for initial export.
--max-point-tile-bytes	5000000	Maximum compressed bytes per point tile.
--max-point-tile-features	50000	Maximum point features per tile.
--max-polygon-tile-bytes	500000	Maximum compressed bytes per polygon tile.
--max-polygon-tile-features	5000	Maximum polygon features per tile.
--coord-scale	1.0	Scale applied to input coordinates before tiling.
--prob-thres	0.0001	Minimum probability retained for nullable K/P fields.
--scale-factor-compression	10.0	Pyramid compression aggressiveness estimate.
--tile-buffer-px	5.0	Polygon tile buffer in screen pixels.
--clip-scale	1024	Integer scale used for polygon clipping.
--extent	4096	Vector tile extent.
--threads	1	Number of threads.
--overwrite	false	Overwrite PMTiles outputs.

Convert PNG/TIFF to PMTiles

You can also run punkst image2pmtiles separately for supported/converted images to produce PMTiles, then pass its output to deploy-cartoscope.

punkst image2pmtiles \
  --in-image tissue_hires_image.tif \
  --out-prefix carto/HnE \
  --id HnE \
  --microns-per-pixel 0.5 \
  --offset-x-um 0 \
  --offset-y-um 0 \
  --min-zoom 10 \
  --max-zoom 18

This writes:

carto/HnE.pmtiles
carto/HnE_assets.json

Include the asset JSON in deployment input:

{
  "image_assets": [
    "carto/HnE_assets.json"
  ]
}

image2pmtiles Options

punkst image2pmtiles accepts the following command-line options:

Option	Default	Description
--in-image	required	Input PNG or supported tiled TIFF.
--out-prefix	required	Output prefix. Writes <prefix>.pmtiles and <prefix>_assets.json unless --asset-json overrides the asset JSON path.
--asset-json	<out-prefix>_assets.json	Output asset JSON path for later use through deploy-cartoscope image_assets.
--id	required	Image/basemap ID written to the asset JSON and CartoScope catalog.
--min-zoom	7	Minimum PMTiles zoom.
--max-zoom	18	Maximum PMTiles zoom.
--microns-per-pixel	none	Pixel size in punkst coordinate units for scale-only alignment. Mutually exclusive with other alignment modes.
--offset-x-um	0	X offset used with --microns-per-pixel.
--offset-y-um	0	Y offset used with --microns-per-pixel.
--transform	none	Full 3x3 pixel-to-micron transform as 9 comma/space-separated values (row-major). Mutually exclusive with other alignment modes.
--pix-zero	none	Two micron coordinates for image grid point (0,0). Must be used with --pix-max; mutually exclusive with --transform, --microns-per-pixel, and offsets.
--pix-max	none	Two micron coordinates for image grid point (W,H) for image width W and height H. Must be used with --pix-zero.
--gray-percentiles	1 99	Low/high percentile bounds for mapping 16-bit grayscale TIFF data to 8-bit PNG tiles.
--gray-sample-fraction	0.05	Fraction of TIFF tiles sampled for 16-bit grayscale percentile estimation.
--gray-sample-tiles	10	Minimum number of TIFF tiles sampled for percentile estimation; use 0 to scan all tiles.
--gray-sample-seed	1	Random seed for TIFF tile sampling.
--tile-cache-mb	0	Optional decoded TIFF tile cache guard in MB; 0 disables the absolute memory guard.
--tiff-source-level	auto	TIFF source level to read: auto, base, or a numeric IFD/SubIFD level.
--overwrite	false	Overwrite existing PMTiles and asset JSON outputs.