@versatiles/versatiles-rs 4.9.0 → 4.10.0

package/vpl.d.ts

@@ -100,386 +100,614 @@ export declare function parseCstResult(vpl: string): CstParseResult;
 export declare function parseCst(vpl: string): CstFile;
 /** Write a lossless syntax tree back out as VPL text. */
 export declare function stringifyCst(cst: CstFile): string;
+/**
+* Reformat a syntax tree, keeping its comments.
+*
+* Whitespace and nothing else is rewritten: parameters keep the order they were written in
+* and values keep the quotes the author chose. Every comment keeps the token it was attached
+* to and takes that token's line and indentation. The returned tree carries fresh spans.
+*/
+export declare function formatCst(cst: CstFile): CstFile;
 export interface FromColorOptions {
-    /** Hex color in RGB or RGBA format (e.g., "FF5733" or "FF573380"). Defaults to "000000" (black). */
+    /**
+     * Hex colour, `RRGGBB` or `RRGGBBAA`. Defaults to `000000`.
+     *
+     * @default 000000
+     */
     color?: string;
-    /** Tile size in pixels (256 or 512). Defaults to 512. */
+    /**
+     * Tile size in pixels, `256` or `512`. Defaults to `512`.
+     *
+     * @default 512
+     */
     size?: number;
-    /** Tile format: one of "avif", "jpg", "png", or "webp". Defaults to "png". */
-    format?: "avif" | "bin" | "geojson" | "jpg" | "json" | "mvt" | "png" | "svg" | "topojson" | "webp";
+    /**
+     * Format to encode the tiles in. Defaults to `png`.
+     *
+     * @default png
+     */
+    format?: "avif" | "jpg" | "png" | "webp";
 }
 export interface FromContainerOptions {
-    /** The filename of the tile container (relative to the VPL file path), or a URL (`http`, `https`, or `sftp`). For example: `filename="world.versatiles"` or `filename="https://example.com/world.versatiles"`. See `versatiles help source` for URL and authentication details. */
+    /** Path to the container, or an `http`, `https` or `sftp` URL. */
     filename: string;
-    /** The private key file to authenticate this `sftp://` source with, for example `ssh_identity="/home/deploy/.ssh/id_ed25519"`. A relative path resolves against the VPL file, like `filename`. It applies to this source alone and overrides `--ssh-identity` and `VERSATILES_SSH_IDENTITY`, which apply to every source — so one pipeline can read from two SFTP hosts that need different keys. Ignored for other schemes. Note that naming a key makes the VPL file specific to machines that have it. */
+    /** Private key for this one `sftp://` source. Defaults to the global setting. */
     sshIdentity?: string;
 }
 export interface FromCsvOptions {
-    /** Filename of the CSV file (relative to the VPL file path). */
+    /** Path to the CSV file. */
     filename: string;
-    /** Header column name holding the longitude (degrees, WGS84). Required. */
+    /** Column holding the longitude, in WGS84 degrees. */
     lonColumn: string;
-    /** Header column name holding the latitude (degrees, WGS84). Required. */
+    /** Column holding the latitude, in WGS84 degrees. */
     latColumn: string;
-    /** Optional column to expose as the MVT feature `id` (numeric if it parses as `u64`, else string). */
+    /** Column to expose as the feature id. Defaults to emitting no id. */
     idColumn?: string;
-    /** Field delimiter as a single ASCII character. Defaults to `,`. */
+    /**
+     * Character separating a row's fields. Defaults to `,`.
+     *
+     * @default ,
+     */
     delimiter?: string;
-    /** Whether row 1 contains column names. Defaults to `true`. Header-less CSVs aren't supported in v1. */
+    /**
+     * Whether the first row holds column names; `false` is not supported yet. Defaults to `true`.
+     *
+     * @default true
+     */
     hasHeader?: boolean;
-    /** Name of the MVT layer in the output tiles. Defaults to the filename stem. */
+    /** Name of the layer to write into. Defaults to the file's stem. */
     layerName?: string;
-    /** Lowest zoom level emitted (default 0). */
+    /**
+     * Lowest zoom level to emit. Defaults to `0`.
+     *
+     * @default 0
+     */
     minZoom?: number;
-    /** Highest zoom level emitted. Defaults to an auto-heuristic (median feature size ≈ 4 tile-pixels, capped at 14). For point-only inputs the heuristic returns 14. */
+    /** Highest zoom level to emit. Defaults to a heuristic capped at `14`. */
     maxZoom?: number;
-    /** Bounding-box clip in degrees `[w, s, e, n]`. Not supported in v1; setting this errors out. */
+    /** Area to restrict the output to, in WGS84 degrees. Defaults to the input's extent. */
     bbox?: [number, number, number, number];
-    /** Property whitelist: keep only the named columns as feature properties, drop everything else. Mutually exclusive with `properties_exclude`. (`lon_column` / `lat_column` / `id_column` are consumed earlier by the CSV adapter and aren't affected.) */
+    /** Columns to keep as properties. Mutually exclusive with `properties_exclude`. Defaults to all. */
     propertiesInclude?: unknown;
-    /** Property blacklist: drop the named properties, keep everything else. Mutually exclusive with `properties_include`. */
+    /** Columns to drop. Mutually exclusive with `properties_include`. Defaults to none. */
     propertiesExclude?: unknown;
-    /** Point reduction strategy: `none` / `drop_rate` / `min_distance` (default `min_distance`). */
+    /**
+     * How to thin out points too close to distinguish. Defaults to `min_distance`.
+     *
+     * @default min_distance
+     */
     pointReduction?: "none" | "drop_rate" | "min_distance";
-    /** Numeric value whose meaning depends on `point_reduction`: - `min_distance` (default): minimum distance between kept points, in tile-pixels at the current zoom. Defaults to 16. - `drop_rate`: per-zoom keep-fraction in `[0, 1]`. Defaults to 0.5. - `none`: ignored. */
+    /** Distance in tile-pixels for `min_distance`, keep-fraction for `drop_rate`. Defaults to `16`/`0.5`. */
     pointReductionValue?: number;
-    /** Tile-compression applied before the tiles leave this operation: `gzip` (default), `brotli`, `zstd`, or `none`. */
+    /**
+     * Compression applied before the tiles leave. Defaults to `gzip`.
+     *
+     * @default gzip
+     */
     compression?: "none" | "gzip" | "brotli" | "zstd";
-    /** Maximum encoded tile size in bytes before a tile is considered broken and dropped (streaming path) / errors out (single-tile path). Defaults to 1048576 (1 MiB). Raise it when a legitimate low-zoom tile exceeds the default (e.g. `max_tile_bytes=2097152` for 2 MiB), or set `max_tile_bytes=none` to emit tiles at any size. The soft-cap warning threshold (200 KB at the default cap) scales with this value. */
+    /**
+     * Size in bytes above which a tile counts as broken. Defaults to `1048576`.
+     *
+     * @default 1048576
+     */
     maxTileBytes?: number | "none";
 }
 export interface FromDebugOptions {
-    /** Target tile format: one of `"mvt"` (default), `"avif"`, `"jpg"`, `"png"` or `"webp"` */
-    format?: "avif" | "bin" | "geojson" | "jpg" | "json" | "mvt" | "png" | "svg" | "topojson" | "webp";
+    /**
+     * Format to generate the tiles in. Defaults to `mvt`.
+     *
+     * @default mvt
+     */
+    format?: "mvt" | "avif" | "jpg" | "png" | "webp";
 }
 export interface FromGeoOptions {
-    /** Filename of the input (relative to the VPL file path). Format is detected from the extension: - `.geojson` / `.json` — GeoJSON `FeatureCollection` - `.ndjson` / `.geojsonl` / `.ndgeojson` / `.geojsonseq` — line-delimited GeoJSON (one feature per line; `.geojsonseq` may use the RFC 8142 record-separator prefix `U+001E`) - `.shp` — Esri Shapefile */
+    /** Path to the input file; its format comes from the extension. */
     filename: string;
-    /** Name of the MVT layer in the output tiles. Defaults to the filename stem. */
+    /** Name of the layer to write into. Defaults to the file's stem. */
     layerName?: string;
-    /** Lowest zoom level emitted (default 0). */
+    /**
+     * Lowest zoom level to emit. Defaults to `0`.
+     *
+     * @default 0
+     */
     minZoom?: number;
-    /** Highest zoom level emitted. Defaults to an auto-heuristic (median feature size ≈ 4 tile-pixels, capped at 14). */
+    /** Highest zoom level to emit. Defaults to a heuristic capped at `14`. */
     maxZoom?: number;
-    /** Bounding-box clip in degrees `[w, s, e, n]`. Not supported in v1; setting this errors out. */
+    /** Area to restrict the output to, in WGS84 degrees. Defaults to the input's extent. */
     bbox?: [number, number, number, number];
-    /** Property whitelist: keep only the named properties, drop everything else. Mutually exclusive with `properties_exclude`. */
+    /** Properties to keep. Mutually exclusive with `properties_exclude`. Defaults to all. */
     propertiesInclude?: unknown;
-    /** Property blacklist: drop the named properties, keep everything else. Mutually exclusive with `properties_include`. */
+    /** Properties to drop. Mutually exclusive with `properties_include`. Defaults to none. */
     propertiesExclude?: unknown;
-    /** Drop polygons whose area is below this many tile-pixels² (default 4). */
+    /**
+     * Area in square tile-pixels below which a polygon is dropped. Defaults to `4`.
+     *
+     * @default 4
+     */
     polygonMinArea?: number;
-    /** Douglas-Peucker tolerance for polygons, in tile-pixels (default 4). */
+    /**
+     * Douglas-Peucker tolerance for polygons, in tile-pixels. Defaults to `4`.
+     *
+     * @default 4
+     */
     polygonSimplify?: number;
-    /** Drop lines whose length is below this many tile-pixels (default 4). */
+    /**
+     * Length in tile-pixels below which a line is dropped. Defaults to `4`.
+     *
+     * @default 4
+     */
     lineMinLength?: number;
-    /** Douglas-Peucker tolerance for lines, in tile-pixels (default 4). */
+    /**
+     * Douglas-Peucker tolerance for lines, in tile-pixels. Defaults to `4`.
+     *
+     * @default 4
+     */
     lineSimplify?: number;
-    /** Point reduction strategy: `none` / `drop_rate` / `min_distance` (default `min_distance`). */
+    /**
+     * How to thin out points too close to distinguish. Defaults to `min_distance`.
+     *
+     * @default min_distance
+     */
     pointReduction?: "none" | "drop_rate" | "min_distance";
-    /** Numeric value whose meaning depends on `point_reduction`: - `min_distance` (default): minimum distance between kept points, in tile-pixels at the current zoom. Defaults to 16. - `drop_rate`: per-zoom keep-fraction in `[0, 1]`. Defaults to 0.5. - `none`: ignored. */
+    /** Distance in tile-pixels for `min_distance`, keep-fraction for `drop_rate`. Defaults to `16`/`0.5`. */
     pointReductionValue?: number;
-    /** Tile-compression applied before the tiles leave this operation: `gzip` (default), `brotli`, `zstd`, or `none`. */
+    /**
+     * Compression applied before the tiles leave. Defaults to `gzip`.
+     *
+     * @default gzip
+     */
     compression?: "none" | "gzip" | "brotli" | "zstd";
-    /** Maximum encoded tile size in bytes before a tile is considered broken and dropped (streaming path) / errors out (single-tile path). Defaults to 1048576 (1 MiB). Raise it when a legitimate low-zoom tile exceeds the default (e.g. `max_tile_bytes=2097152` for 2 MiB), or set `max_tile_bytes=none` to emit tiles at any size. The soft-cap warning threshold (200 KB at the default cap) scales with this value. */
+    /**
+     * Size in bytes above which a tile counts as broken. Defaults to `1048576`.
+     *
+     * @default 1048576
+     */
     maxTileBytes?: number | "none";
-    /** If `true`, drop the GeoJSON / Shapefile `id` field from every feature before encoding. Useful for sources where the id is a string (e.g. USGS earthquakes — those would be silently dropped at MVT encode anyway, since MVT requires `uint64` ids), or when the id is just noise. Defaults to `false` — keep the id when it's a non-negative integer. */
+    /**
+     * Whether to drop each feature's `id` before encoding. Defaults to `false`.
+     *
+     * @default false
+     */
     ignoreId?: boolean;
 }
 export interface FromGridOptions {
-    /** EPSG code of the grid's coordinate reference system. Without GDAL: `3035` (ETRS89-LAEA, what European gridded statistics use), `3857` (web mercator) and `4326` (WGS84 lon/lat). */
+    /** EPSG code of the grid's coordinate reference system. */
     epsg: number;
-    /** Edge length of a cell, in the CRS's own units — meters for a projected CRS, degrees for `epsg=4326`. For example: `size=1000` for the 1 km grid Eurostat publishes. */
+    /** Edge length of a cell, in the CRS's units — meters, or degrees for `epsg=4326`. */
     size: number;
-    /** The area to cover, as `[west, south, east, north]` in WGS84 degrees. Required: an unbounded grid has no pyramid to derive, and at most cell sizes it is more tiles than can be written. */
+    /** Area to cover, as `[west, south, east, north]` in WGS84 degrees. */
     bbox: [number, number, number, number];
-    /** Where the cell with index `(0, 0)` has its lower-left corner, in CRS units. Default: `[0,0]`, which is what published grids align to. */
+    /**
+     * Lower-left corner of cell `(0, 0)`, in CRS units. Defaults to `[0,0]`.
+     *
+     * @default [0,0]
+     */
     offset?: unknown;
-    /** Roughly how many cells one tile may hold. Decides the lowest zoom level this source offers. Default: `1024`. */
+    /**
+     * Roughly how many cells one tile may hold. Defaults to `1024`.
+     *
+     * @default 1024
+     */
     maxCellsPerTile?: number;
-    /** Highest zoom level to generate. Defaults to three levels above the derived minimum, since further levels repeat the same cells. */
+    /** Highest zoom level to generate. Defaults to three above the derived minimum. */
     maxZoom?: number;
-    /** Ready-made id format. Either `"inspire"` (default), which produces `CRS3035RES1000mN2691000E4341000`, or `"geostat"`, which produces `1kmN2689E4337`. */
-    idPreset?: string;
-    /** Id format spelled out, for a grid whose publisher uses neither preset. `{x}` and `{y}` are the lower-left corner, each taking an optional divisor and zero-padded width: `E{x/100:04}N{y/100:04}` produces `E0643N4567`, the form Dutch grid statistics use. Overrides `id_preset`. */
+    /**
+     * Ready-made id format. Overridden by `id_template`. Defaults to `inspire`.
+     *
+     * @default inspire
+     */
+    idPreset?: "inspire" | "geostat";
+    /** Id format spelled out, with `{x}` and `{y}` for the corner. Defaults to `id_preset`. */
     idTemplate?: string;
-    /** Name of the string property holding the cell id. Default: `"id"`. */
+    /**
+     * Property holding the cell id. Defaults to `id`.
+     *
+     * @default id
+     */
     idField?: string;
-    /** Names of the number properties holding the lower-left corner. Defaults: `"x"` and `"y"`, mirroring the `X_LLC` / `Y_LLC` columns Eurostat ships beside its ids. */
+    /**
+     * Property holding the corner's easting. Defaults to `x`.
+     *
+     * @default x
+     */
     xField?: string;
-    /** See `x_field`. */
+    /**
+     * Property holding the corner's northing. Defaults to `y`.
+     *
+     * @default y
+     */
     yField?: string;
-    /** How far a cell edge may stray from its true curve, in tile pixels. Only matters for a CRS whose straight lines bend in mercator; in `3857` and `4326` no vertices are added whatever this says. Default: `0.5`. */
+    /**
+     * How far a cell edge may stray from its true curve, in tile pixels. Defaults to `0.5`.
+     *
+     * @default 0.5
+     */
     densifyTolerance?: number;
-    /** Name of the layer in the generated tiles. Default: `"grid"`. */
+    /**
+     * Name of the layer to write into. Defaults to `grid`.
+     *
+     * @default grid
+     */
     layerName?: string;
 }
 export interface FromH3Options {
-    /** H3 resolution, `0` (cells of ~4,250,000 km²) to `15` (~0.9 m²). For example: `resolution=8` for cells of roughly 0.7 km². See <https://h3geo.org/docs/core-library/restable/> for the full table. */
+    /** H3 resolution, `0` (coarsest) to `15` (finest). */
     resolution: number;
-    /** The area to cover, as `[west, south, east, north]` in WGS84 degrees. For example: `bbox=[13.0,52.3,13.8,52.7]` for Berlin. Required: a grid without bounds would be generated for the whole planet, which at most resolutions is more tiles than can be written. */
+    /** Area to cover, as `[west, south, east, north]` in WGS84 degrees. */
     bbox: [number, number, number, number];
-    /** Roughly how many cells one tile may hold. Decides the lowest zoom level this source offers: below it a single tile would carry more cells than a tile can usefully hold. Default: `1024`. */
+    /**
+     * Roughly how many cells one tile may hold. Defaults to `1024`.
+     *
+     * @default 1024
+     */
     maxCellsPerTile?: number;
-    /** Highest zoom level to generate. Defaults to three levels above the derived minimum, since further levels repeat the same cells. */
+    /** Highest zoom level to generate. Defaults to three above the derived minimum. */
     maxZoom?: number;
-    /** Name of the layer in the generated tiles. Default: `"grid"`. */
+    /**
+     * Name of the layer to write into. Defaults to `grid`.
+     *
+     * @default grid
+     */
     layerName?: string;
-    /** Name of the string property holding the H3 index, e.g. `"8928308280fffff"`. Default: `"h3"`, matching how H3 datasets usually name the column. */
+    /**
+     * Property holding the H3 index. Defaults to `h3`.
+     *
+     * @default h3
+     */
     idField?: string;
 }
 export interface FromStackedRasterOptions {
-    /** The tile format to use for the output tiles. Default: format of the first source. */
-    format?: "avif" | "bin" | "geojson" | "jpg" | "json" | "mvt" | "png" | "svg" | "topojson" | "webp";
-    /** Whether to automatically wrap each source with `raster_overscale` so that sources missing native tiles at the requested zoom level still contribute via upscaled tiles. When all sources overlapping a requested bbox are overscaled (none have native data), this operation returns an empty stream. Place a `raster_overscale` *after* `from_stacked_raster` in the pipeline to cover those tiles — it is more efficient to upscale one blended tile than N individual tiles. Default: `false`. */
+    /** Format to encode the blended tiles in. Defaults to the first source's. */
+    format?: "avif" | "jpg" | "png" | "webp";
+    /**
+     * Whether to wrap each source in `raster_overscale`. Defaults to `false`.
+     *
+     * @default false
+     */
     autoOverscale?: boolean;
 }
 export interface FromTileOptions {
-    /** The filename of the tile. Supported formats: png, jpg/jpeg, webp, avif, pbf/mvt. The format is automatically detected from the file extension. */
+    /** Path to the tile file; its format comes from the extension. */
     filename: string;
 }
 export interface FromTilejsonOptions {
-    /** The URL of the TileJSON endpoint. For example: `url="https://example.com/tiles.json"`. */
+    /** URL of the TileJSON endpoint. */
     url: string;
-    /** Maximum number of retries per tile request (default: 3). */
+    /**
+     * How often to retry a failed tile request. Defaults to `3`.
+     *
+     * @default 3
+     */
     maxRetries?: number;
-    /** Maximum number of concurrent tile requests (default: io_bound concurrency limit). */
+    /** How many tile requests may be in flight. Defaults to the I/O concurrency limit. */
     maxConcurrentRequests?: number;
 }
 export interface FilterOptions {
-    /** Bounding box in WGS84: [min lng, min lat, max lng, max lat]. */
+    /** Area to keep, in WGS84 degrees. Defaults to the source's own bounds. */
     bbox?: [number, number, number, number];
-    /** Ring of extra tiles to keep around `bbox`, in tiles per zoom level. Note that this is the one parameter here that *widens*: every other parameter narrows the tile set, but `bbox_border=2` keeps tiles the bbox alone would have dropped. Those tiles lie outside the crop, so the advertised bounds are extended to cover them and a client actually requests them. This matters wherever a cropped tileset is rendered rather than just stored: without a border, labels and geometry near the edge have no neighbouring tiles to be laid out against. Requires `bbox`; setting it alone is an error rather than a no-op. */
+    /**
+     * Ring of extra tiles kept around `bbox`, per zoom level. Requires `bbox`. Defaults to `0`.
+     *
+     * @default 0
+     */
     bboxBorder?: number;
-    /** minimal zoom level */
+    /** Lowest zoom level to keep. Defaults to the source's lowest. */
     levelMin?: number;
-    /** maximal zoom level */
+    /** Highest zoom level to keep. Defaults to the source's highest. */
     levelMax?: number;
-    /** Path to a tile container used as a coordinate allow-list. Only tiles whose coordinates exist in this container are passed through. Accepts the same path/URL syntax as `from_container`. Note: opening the container and building the allow-list requires I/O at pipeline build time. */
+    /** Tile container whose coordinates act as an allow-list. Defaults to no allow-list. */
     filename?: string;
 }
 export interface MetaUpdateOptions {
-    /** Attribution text. */
+    /** Attribution text. Defaults to the source's. */
     attribution?: string;
-    /** Geographic bounding box [west, south, east, north]. */
+    /** Area covered, as `[west, south, east, north]` in WGS84 degrees. Defaults to the source's. */
     bounds?: [number, number, number, number];
-    /** Default center [longitude, latitude, zoom]. */
+    /** Where a client should open the map, as `[lon, lat, zoom]`. Defaults to the source's. */
     center?: [number, number, number];
-    /** Description text. */
+    /** Description text. Defaults to the source's. */
     description?: string;
-    /** Fill zoom level. */
+    /** Zoom level from which clients should fill from the parent tile. Defaults to the source's. */
     fillzoom?: number;
-    /** Legend text. */
+    /** Legend text. Defaults to the source's. */
     legend?: string;
-    /** Name text. */
+    /** Name of the tileset. Defaults to the source's. */
     name?: string;
-    /** Tile schema, allowed values: "rgb", "rgba", "dem/mapbox", "dem/terrarium", "dem/versatiles", "openmaptiles", "shortbread@1.0", "other", "unknown" */
+    /** What the tiles contain. Defaults to the source's. */
     schema?: "rgb" | "rgba" | "dem/mapbox" | "dem/terrarium" | "dem/versatiles" | "openmaptiles" | "shortbread@1.0" | "other";
-    /** A complete TileJSON document (JSON string) used as the basis for the new metadata. When given, the new metadata starts from this document instead of the source's; the other parameters then override individual fields on top of it. */
+    /** Complete TileJSON document, as a JSON string. Defaults to the source's metadata. */
     tilejson?: string;
-    /** Path to a file containing a complete TileJSON document, resolved relative to the VPL file. Use instead of `tilejson` to avoid inline JSON quoting. Mutually exclusive with `tilejson`. */
+    /** Path to a file holding a complete TileJSON document. Defaults to the source's metadata. */
     tilejsonFile?: string;
-    /** A partial TileJSON document (JSON string) merged onto the current metadata. Scalar fields (e.g. `name`, `attribution`) and `vector_layers` overwrite; `bounds` and the zoom range are widened to the union. The individual parameters still take precedence. */
+    /** Partial TileJSON document to merge on, as a JSON string. Defaults to merging nothing. */
     tilejsonUpdate?: string;
-    /** Path to a file containing a partial TileJSON document, resolved relative to the VPL file. Use instead of `tilejson_update`. Mutually exclusive with `tilejson_update`. */
+    /** Path to a file holding a partial TileJSON document. Defaults to merging nothing. */
     tilejsonUpdateFile?: string;
-    /** The `vector_layers` array as a JSON string. It is parsed and validated against the TileJSON spec before replacing the source's `vector_layers`. */
+    /** The `vector_layers` array as a JSON string. Defaults to the source's. */
     vectorLayers?: string;
-    /** Path to a file containing the `vector_layers` array as JSON, resolved relative to the VPL file. Use instead of `vector_layers`. Mutually exclusive with `vector_layers`. */
+    /** Path to a file holding the `vector_layers` array as JSON. Defaults to the source's. */
     vectorLayersFile?: string;
 }
 export interface RemapCoordsOptions {
-    /** Mirror horizontally within each zoom level: `x` becomes `2^z - 1 - x`. No tile scheme uses this on its own; it is what makes the rotations reachable. Defaults to `false`. */
+    /**
+     * Whether to mirror horizontally, so `x` becomes `2^z - 1 - x`. Defaults to `false`.
+     *
+     * @default false
+     */
     flipX?: boolean;
-    /** Mirror vertically within each zoom level: `y` becomes `2^z - 1 - y`. This is the TMS ↔ XYZ correction. Defaults to `false`. */
+    /**
+     * Whether to mirror vertically, so `y` becomes `2^z - 1 - y`. Defaults to `false`.
+     *
+     * @default false
+     */
     flipY?: boolean;
-    /** Exchange the axes: `(x, y)` becomes `(y, x)`, for sources laid out as `z/y/x`. Applied after the flips. Defaults to `false`. */
+    /**
+     * Whether to exchange the axes, so `(x, y)` becomes `(y, x)`. Defaults to `false`.
+     *
+     * @default false
+     */
     swapXy?: boolean;
 }
 export interface DemOverviewOptions {
-    /** Use this zoom level to build the overview. Defaults to the maximum zoom level of the source. */
+    /** Zoom level to build the overview from. Defaults to the source's highest. */
     level?: number;
-    /** Override auto-detection of DEM encoding. Values: "mapbox", "terrarium". */
-    encoding?: string;
+    /** DEM encoding of the source. Defaults to the encoding its tile schema implies. */
+    encoding?: "mapbox" | "terrarium";
 }
 export interface DemQuantizeOptions {
-    /** Allowed elevation error as fraction of pixel ground size. E.g. 0.1 means for a 10 m pixel, allow up to 1 m elevation error. Defaults to 0.1. */
+    /**
+     * Allowed elevation error as a fraction of the pixel's ground size. Defaults to `0.1`.
+     *
+     * @default 0.1
+     */
     elevationError?: number;
-    /** Maximum allowed slope change in degrees due to quantization. Defaults to 1.0. */
+    /**
+     * Largest slope change in degrees that quantization may introduce. Defaults to `1.0`.
+     *
+     * @default 1.0
+     */
     slopeError?: number;
-    /** Override auto-detection of DEM encoding. Values: "mapbox", "terrarium". */
-    encoding?: string;
+    /** DEM encoding of the source. Defaults to the encoding its tile schema implies. */
+    encoding?: "mapbox" | "terrarium";
 }
 export interface DemTileResizeOptions {
-    /** Target tile size in pixels. Must be 256 or 512. */
-    tileSize?: number;
-    /** Override auto-detection of DEM encoding. Values: "mapbox", "terrarium". */
-    encoding?: string;
+    /** Target tile size in pixels, `256` or `512`, and it must differ from the source's. */
+    tileSize: number;
+    /** DEM encoding of the source. Defaults to the encoding its tile schema implies. */
+    encoding?: "mapbox" | "terrarium";
 }
 export interface RasterFlattenOptions {
-    /** background color to use for the flattened tiles, in RGB format. Defaults to white. */
+    /** Background colour, as `[r, g, b]`. Defaults to white. */
     color?: [number, number, number];
 }
 export interface RasterFormatOptions {
-    /** The desired tile format. Allowed values are: AVIF, JPG, PNG or WEBP. If not specified, the source format will be used. */
+    /** Format to encode the tiles into. Defaults to the source's. */
     format?: "avif" | "jpg" | "png" | "webp";
-    /** Quality level for the tile compression (only AVIF, JPG or WEBP), between 0 (worst) and 100 (lossless). To allow different quality levels for different zoom levels, this can also be a comma-separated list like this: "70,14:50,15:20", where the first value is the default quality, and the other values specify the quality for the specified zoom level (and higher). */
+    /** Encoder quality, `0` (worst) to `100` (lossless). Defaults to the encoder's own. */
     quality?: string;
-    /** Quality level for translucent (semi-transparent) tiles, using the same zoom-dependent syntax as quality. When set, tiles are checked for opacity: opaque tiles use the normal quality setting, while translucent tiles use this value (typically 100 for lossless). */
+    /** Encoder quality for tiles with translucent pixels. Defaults to using `quality` throughout. */
     qualityTranslucent?: string;
-    /** Compression effort, between 0 (fastest) and 100 (slowest/best). */
+    /** Encoder effort, `0` (fastest) to `100` (smallest). Defaults to the encoder's own. */
     effort?: number;
 }
 export interface RasterLevelsOptions {
-    /** Brightness adjustment, between -255 and 255. Defaults to 0.0 (no change). */
+    /**
+     * Offset added to every channel, `-255` to `255`. Defaults to `0.0`.
+     *
+     * @default 0.0
+     */
     brightness?: number;
-    /** Contrast adjustment, between 0 and infinity. Defaults to 1.0 (no change). */
+    /**
+     * Factor applied around mid-grey, above `0`. Defaults to `1.0`.
+     *
+     * @default 1.0
+     */
     contrast?: number;
-    /** Gamma adjustment, between 0 and infinity. Defaults to 1.0 (no change). */
+    /**
+     * Gamma exponent, above `0`. Defaults to `1.0`.
+     *
+     * @default 1.0
+     */
     gamma?: number;
 }
 export interface RasterMaskOptions {
-    /** Path to GeoJSON file with Polygon or MultiPolygon geometry. */
+    /** Path to a GeoJSON file holding a Polygon or MultiPolygon, in EPSG:4326 lon/lat degrees. */
     geojson: string;
-    /** Buffer distance in meters. Positive values expand the mask, negative values shrink it. Default: 0 */
+    /**
+     * Distance in meters by which to grow the mask, or shrink it when negative. Defaults to `0`.
+     *
+     * @default 0
+     */
     buffer?: number;
-    /** Edge blur distance in meters. Creates a soft transition at the mask edge. Default: 0 */
+    /**
+     * Width in meters of the soft transition at the mask edge. Defaults to `0`.
+     *
+     * @default 0
+     */
     blur?: number;
-    /** Blur falloff function: "linear" or "cosine". Default: "linear" */
-    blurFunction?: string;
+    /**
+     * Falloff curve across the `blur` band. Defaults to `linear`.
+     *
+     * @default linear
+     */
+    blurFunction?: "linear" | "cosine";
 }
 export interface RasterOverscaleOptions {
-    /** The zoom level to use as the source for overscaling. Tiles at this level and below are passed through unchanged. Tiles above this level are generated by extracting and upscaling from this level. Defaults to the maximum zoom level of the source. */
+    /** Zoom level to upscale from. Defaults to the source's highest. */
     levelBase?: number;
-    /** The maximum zoom level to support. Defaults to 30. Requests above this level will not return tiles. */
+    /**
+     * Highest zoom level to serve. Defaults to `30`.
+     *
+     * @default 30
+     */
     levelMax?: number;
-    /** Enable tile climbing when the expected source tile doesn't exist. When true, the operation will search parent tiles at lower zoom levels until it finds an existing tile, then extract and upscale from there. Defaults to false. */
+    /**
+     * Whether to climb to lower levels when the `level_base` tile is missing. Defaults to `false`.
+     *
+     * @default false
+     */
     enableClimbing?: boolean;
 }
 export interface RasterOverviewOptions {
-    /** use this zoom level to build the overview. Defaults to the maximum zoom level of the source. */
+    /** Zoom level to build the overview from. Defaults to the source's highest. */
     level?: number;
 }
 export interface RasterTileResizeOptions {
-    /** Target tile size in pixels. A value of `256` expects source tiles of 512px, which will be split into four 256px output tiles at the next higher zoom level. Level 0 is downscaled instead. A value of `512` expects source tiles measuring 256px, which will be merged into 512px output tiles at the next lower zoom level. */
-    tileSize?: number;
+    /** Target tile size in pixels, `256` or `512`, and it must differ from the source's. */
+    tileSize: number;
 }
 export interface VectorFilterFeaturesOptions {
-    /** Layers the expression applies to, as a VPL array of strings. Features in all other layers are left unchanged. Example: `layer=["poi","place"]`. */
+    /** Layers the expression applies to, for example `layer=["poi","place"]`. */
     layer: unknown;
-    /** CEL (Common Expression Language) boolean expression. Feature properties are available as `props["key"]`; properties whose names are valid CEL identifiers (letters, digits, underscore) are also exposed as top-level identifiers. Missing keys resolve to null; use `name != null` (for identifier-safe keys) or `has(props.key)` (for any key) for explicit presence checks. See `versatiles help` for a CEL operator cheat-sheet. */
+    /** Boolean CEL expression over the feature's properties. */
     expr: string;
 }
 export interface VectorFilterLayersOptions {
-    /** Layer names to remove from the tiles, e.g. `filter=["pois","ocean"]`. */
+    /** Layer names to remove, for example `filter=["pois","ocean"]`. */
     filter: unknown;
-    /** If set, inverts the filter logic (i.e., keeps only layers matching the filter). */
+    /**
+     * Whether to keep the named layers instead of removing them. Defaults to `false`.
+     *
+     * @default false
+     */
     invert?: boolean;
 }
 export interface VectorFilterPropertiesOptions {
-    /** A regular expression pattern that should match property names to be removed from all features. The property names contain the layer name as a prefix, e.g., `layer_name/property_name`, so an expression like `regex="^layer_name/"` will match all properties of that layer or `regex="/name_.*$"` will match all properties starting with `name_` in all layers. */
+    /** Regular expression matched against each property's prefixed name. */
     regex: string;
-    /** If set, inverts the filter logic (i.e., keeps only properties matching the filter). */
+    /**
+     * Whether to keep the matching properties instead of removing them. Defaults to `false`.
+     *
+     * @default false
+     */
     invert?: boolean;
 }
 export interface VectorOverzoomOptions {
-    /** The zoom level to use as the source for overzooming. Tiles at this level and below are passed through unchanged. Tiles above this level are generated by clipping and rescaling features from the corresponding parent tile at this level. Defaults to the maximum zoom level of the source. */
+    /** Zoom level to overzoom from. Defaults to the source's highest. */
     levelBase?: number;
-    /** The maximum zoom level to support. Defaults to `level_base + 4` (each extra level quadruples the tile count, so 4 levels = 256× — usually the sweet spot before the pyramid becomes unwieldy). Set explicitly if you want to overzoom further. Capped at 30. */
+    /** Highest zoom level to serve, capped at `30`. Defaults to `level_base + 4`. */
     levelMax?: number;
-    /** Enable tile climbing when the expected source tile doesn't exist. When true, the operation will search parent tiles at lower zoom levels until it finds an existing tile, then clip and rescale from there. Defaults to false. */
+    /**
+     * Whether to climb to lower levels when the `level_base` tile is missing. Defaults to `false`.
+     *
+     * @default false
+     */
     enableClimbing?: boolean;
-    /** Clip buffer in tile-extent units, applied to the child tile's sub-region so that features straddling tile boundaries (labels, lines) survive intact. Defaults to 80. */
+    /**
+     * Clip buffer in tile-extent units, so edge-straddling features survive. Defaults to `80`.
+     *
+     * @default 80
+     */
     buffer?: number;
 }
 export interface VectorRepairOptions {
-    /** Drop features that cannot be decoded rather than leaving them in place. Defaults to false. */
+    /**
+     * Whether to remove features whose geometry cannot be decoded. Defaults to `false`.
+     *
+     * @default false
+     */
     dropOffenders?: boolean;
 }
 export interface VectorUpdatePropertiesOptions {
-    /** Path to the CSV/TSV data file: The file must have a header row. Each subsequent row will be matched to vector features using the ID fields. */
+    /** Path to the CSV or TSV file, which must have a header row. */
     dataSourcePath: string;
-    /** Name of the vector layer to update: Only features in this layer will be modified. Other layers pass through unchanged. */
+    /** Name of the layer whose features are updated. */
     layerName: string;
-    /** Field name in the vector tiles that contains the feature ID: This field is used to match features with rows in the data source. */
+    /** Feature property holding the id to match on. */
     idFieldTiles: string;
-    /** Column name in the data source that contains the matching ID: This column is used to look up data for each feature. */
+    /** Column in the data file holding the id to match on. */
     idFieldData: string;
-    /** If `true`, replaces all existing properties with the data source values. If `false` (default), merges new properties with existing ones. */
+    /**
+     * Whether to replace a feature's properties instead of merging. Defaults to `false`.
+     *
+     * @default false
+     */
     replaceProperties?: boolean;
-    /** If `true`, removes features that don't have a matching row in the data source. If `false` (default), non-matching features are kept unchanged. */
+    /**
+     * Whether to drop features that have no matching row. Defaults to `false`.
+     *
+     * @default false
+     */
     removeNonMatching?: boolean;
-    /** If `true`, includes the ID field from the data source in the output properties. If `false` (default), the ID field is excluded from the merged properties. */
+    /**
+     * Whether to keep the id column among the written properties. Defaults to `false`.
+     *
+     * @default false
+     */
     includeId?: boolean;
-    /** Field separator character for the data file: Default for `.csv` files is `,` (comma). Default for `.tsv` files is `\t` (tab, auto-detected) */
+    /** Character separating a row's fields. Defaults to `,` for `.csv` and a tab for `.tsv`. */
     fieldSeparator?: string;
-    /** Decimal separator character for parsing numbers: Default is `.` (US/UK format). Use `,` (comma) e.g. for German/European number format like `1.234,56` */
+    /**
+     * Decimal separator for parsing numbers, so `,` reads `1.234,56`. Defaults to `.`.
+     *
+     * @default .
+     */
     decimalSeparator?: string;
 }
 export declare class VPL {
     private steps;
     private constructor();
-    /** Generates solid-color tiles of the specified size and format. */
+    /** Generates raster tiles of a single solid colour. */
     static fromColor(options?: FromColorOptions): VPL;
     /** Reads a tile container, such as a `*.versatiles`, `*.mbtiles`, `*.pmtiles` or `*.tar` file. */
     static fromContainer(options: FromContainerOptions): VPL;
-    /** Reads a CSV file with longitude/latitude columns and emits MVT point tiles. */
+    /** Reads a CSV file with longitude and latitude columns and emits MVT point tiles. */
     static fromCsv(options: FromCsvOptions): VPL;
-    /** Generates debug tiles that display their coordinates as text. */
+    /** Generates tiles that draw their own coordinates, for inspecting a pipeline. */
     static fromDebug(options?: FromDebugOptions): VPL;
     /** Reads a GeoJSON or Shapefile and emits MVT vector tiles. */
     static fromGeo(options: FromGeoOptions): VPL;
-    /** Generates vector tiles containing the cells of a projected square grid, ready to be joined with data keyed on the cell id. */
+    /** Generates vector tiles holding the cells of a projected square grid. */
     static fromGrid(options: FromGridOptions): VPL;
-    /** Generates vector tiles containing H3 grid cells, ready to be joined with data keyed on the H3 index. */
+    /** Generates vector tiles holding H3 hexagons. */
     static fromH3(options: FromH3Options): VPL;
-    /** Merges multiple vector tile sources. Each resulting tile will contain all the features and properties from all the sources. */
+    /** Merges several vector tile sources into one, keeping every feature. */
     static fromMergedVector(sources: VPL[]): VPL;
-    /** Overlays multiple raster tile sources on top of each other. */
+    /** Blends several raster tile sources into one by alpha-compositing them. */
     static fromStackedRaster(sources: VPL[], options?: Omit<FromStackedRasterOptions, 'sources'>): VPL;
-    /** Overlays multiple tile sources, using the tile from the first source that provides it. */
+    /** Overlays several tile sources, taking each tile from the first source that has it. */
     static fromStacked(sources: VPL[]): VPL;
-    /** Reads a single tile file and uses it as a template for all tile requests. */
+    /** Reads one tile file and returns it for every requested coordinate. */
     static fromTile(options: FromTileOptions): VPL;
-    /** Reads tiles from a remote tile server via a TileJSON endpoint. The TileJSON is fetched from the given URL, and tiles are loaded individually using the URL template from the TileJSON `tiles` array. */
+    /** Reads tiles from a remote tile server described by a TileJSON endpoint. */
     static fromTilejson(options: FromTilejsonOptions): VPL;
-    /** Filter tiles by bounding box, zoom levels, and/or the tile coordinates present in another container. */
+    /** Filters tiles by bounding box, zoom range, or the coordinates present in another container. */
     filter(options?: FilterOptions): VPL;
-    /** Update metadata, see also <https://github.com/mapbox/tilejson-spec/tree/master/3.0.0> */
+    /** Overwrites fields of the source's TileJSON metadata. */
     metaUpdate(options?: MetaUpdateOptions): VPL;
-    /** Relabels tile coordinates, e.g. to correct a source that uses TMS row order or `z/y/x` paths. */
+    /** Relabels tile coordinates, correcting a source that uses TMS row order or `z/y/x` paths. */
     remapCoords(options?: RemapCoordsOptions): VPL;
-    /** Generate lower-zoom DEM overview tiles by averaging 24-bit elevation values. */
+    /** Generates lower-zoom DEM overview tiles by averaging 24-bit elevation values. */
     demOverview(options?: DemOverviewOptions): VPL;
-    /** Quantize DEM (elevation) raster tiles by rounding to a per-tile power-of-two step. */
+    /** Quantizes DEM raster tiles by rounding elevations to a per-tile power-of-two step. */
     demQuantize(options?: DemQuantizeOptions): VPL;
-    /** Convert DEM tile size between 256px and 512px by splitting or merging tiles. */
-    demTileResize(options?: DemTileResizeOptions): VPL;
-    /** Flattens (translucent) raster tiles onto a background */
+    /** Converts DEM tiles between 256 and 512 pixels by splitting or merging them. */
+    demTileResize(options: DemTileResizeOptions): VPL;
+    /** Composites translucent raster tiles onto an opaque background colour. */
     rasterFlatten(options?: RasterFlattenOptions): VPL;
-    /** Convert raster tiles to a different image format and/or adjust quality/effort settings. */
+    /** Re-encodes raster tiles into another image format, quality or effort setting. */
     rasterFormat(options?: RasterFormatOptions): VPL;
-    /** Adjust brightness, contrast and gamma of raster tiles. */
+    /** Adjusts the brightness, contrast and gamma of raster tiles. */
     rasterLevels(options?: RasterLevelsOptions): VPL;
-    /** Apply a polygon mask from GeoJSON to raster tiles. Pixels outside the polygon become transparent. */
+    /** Makes raster pixels outside a GeoJSON polygon transparent. */
     rasterMask(options: RasterMaskOptions): VPL;
-    /** Raster overscale operation - generates tiles beyond the source's native resolution. */
+    /** Serves raster tiles above the source's native resolution by upscaling. */
     rasterOverscale(options?: RasterOverscaleOptions): VPL;
-    /** Generate lower-zoom overview tiles by downscaling from a base zoom level. */
+    /** Generates the lower zoom levels of a raster pyramid by downscaling. */
     rasterOverview(options?: RasterOverviewOptions): VPL;
-    /** Convert the size of tiles by splitting or merging them to a width of 256px or 512px. */
-    rasterTileResize(options?: RasterTileResizeOptions): VPL;
-    /** Drops vector features in selected layers that do not satisfy a boolean CEL expression. Features in layers outside `layer` pass through untouched. */
+    /** Converts raster tiles between 256 and 512 pixels by splitting or merging them. */
+    rasterTileResize(options: RasterTileResizeOptions): VPL;
+    /** Drops vector features in selected layers that do not satisfy a boolean expression. */
     vectorFilterFeatures(options: VectorFilterFeaturesOptions): VPL;
-    /** Filters vector tile layers by name. */
+    /** Removes whole layers from vector tiles by name. */
     vectorFilterLayers(options: VectorFilterLayersOptions): VPL;
-    /** Filters properties based on a regular expressions. */
+    /** Removes feature properties from vector tiles by matching their names against a regex. */
     vectorFilterProperties(options: VectorFilterPropertiesOptions): VPL;
-    /** Vector overzoom operation - generates vector tiles beyond the source's native max zoom. */
+    /** Serves vector tiles above the source's highest zoom level by clipping and rescaling. */
     vectorOverzoom(options?: VectorOverzoomOptions): VPL;
-    /** Repairs vector tiles to conform to MVT 2.1. */
+    /** Repairs vector tiles so that they conform to MVT 2.1. */
     vectorRepair(options?: VectorRepairOptions): VPL;
-    /** Arguments for the `vector_update_properties` operation. */
+    /** Joins tabular data onto vector features, matching on an id column. */
     vectorUpdateProperties(options: VectorUpdatePropertiesOptions): VPL;
     /** Serialize this VPL pipeline to a string. */
     toString(): string;