@versatiles/versatiles-rs 4.8.0 → 4.9.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@versatiles/versatiles-rs",
-  "version": "4.8.0",
+  "version": "4.9.0",
   "description": "Node.js bindings for VersaTiles - convert, serve, and process map tiles",
   "main": "index.js",
   "types": "index.d.ts",
@@ -102,14 +102,14 @@
     "vitest": "^4.1.10"
   },
   "optionalDependencies": {
-    "@versatiles/versatiles-rs-darwin-arm64": "4.8.0",
-    "@versatiles/versatiles-rs-darwin-x64": "4.8.0",
-    "@versatiles/versatiles-rs-linux-arm64-gnu": "4.8.0",
-    "@versatiles/versatiles-rs-linux-arm64-musl": "4.8.0",
-    "@versatiles/versatiles-rs-linux-x64-gnu": "4.8.0",
-    "@versatiles/versatiles-rs-linux-x64-musl": "4.8.0",
-    "@versatiles/versatiles-rs-win32-arm64-msvc": "4.8.0",
-    "@versatiles/versatiles-rs-win32-x64-msvc": "4.8.0"
+    "@versatiles/versatiles-rs-darwin-arm64": "4.9.0",
+    "@versatiles/versatiles-rs-darwin-x64": "4.9.0",
+    "@versatiles/versatiles-rs-linux-arm64-gnu": "4.9.0",
+    "@versatiles/versatiles-rs-linux-arm64-musl": "4.9.0",
+    "@versatiles/versatiles-rs-linux-x64-gnu": "4.9.0",
+    "@versatiles/versatiles-rs-linux-x64-musl": "4.9.0",
+    "@versatiles/versatiles-rs-win32-arm64-msvc": "4.9.0",
+    "@versatiles/versatiles-rs-win32-x64-msvc": "4.9.0"
   },
   "allowScripts": {
     "esbuild": true,

package/vpl.d.ts

@@ -109,8 +109,10 @@ export interface FromColorOptions {
     format?: "avif" | "bin" | "geojson" | "jpg" | "json" | "mvt" | "png" | "svg" | "topojson" | "webp";
 }
 export interface FromContainerOptions {
-    /** The filename of the tile container (relative to the VPL file path), or a URL (http/https). For example: `filename="world.versatiles"` or `filename="https://example.com/world.versatiles"`. */
+    /** 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. */
     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. */
+    sshIdentity?: string;
 }
 export interface FromCsvOptions {
     /** Filename of the CSV file (relative to the VPL file path). */
@@ -184,6 +186,48 @@ export interface FromGeoOptions {
     /** 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. */
     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: 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. */
+    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. */
+    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. */
+    offset?: unknown;
+    /** Roughly how many cells one tile may hold. Decides the lowest zoom level this source offers. Default: `1024`. */
+    maxCellsPerTile?: number;
+    /** Highest zoom level to generate. Defaults to three levels above the derived minimum, since further levels repeat the same cells. */
+    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`. */
+    idTemplate?: string;
+    /** Name of the string property holding the cell 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. */
+    xField?: string;
+    /** See `x_field`. */
+    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`. */
+    densifyTolerance?: number;
+    /** Name of the layer in the generated tiles. 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. */
+    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. */
+    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`. */
+    maxCellsPerTile?: number;
+    /** Highest zoom level to generate. Defaults to three levels above the derived minimum, since further levels repeat the same cells. */
+    maxZoom?: number;
+    /** Name of the layer in the generated tiles. 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. */
+    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";
@@ -205,6 +249,8 @@ export interface FromTilejsonOptions {
 export interface FilterOptions {
     /** Bounding box in WGS84: [min lng, min lat, max lng, max lat]. */
     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. */
+    bboxBorder?: number;
     /** minimal zoom level */
     levelMin?: number;
     /** maximal zoom level */
@@ -242,6 +288,14 @@ export interface MetaUpdateOptions {
     /** 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`. */
     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`. */
+    flipX?: boolean;
+    /** Mirror vertically within each zoom level: `y` becomes `2^z - 1 - y`. This is the TMS ↔ XYZ correction. Defaults to `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`. */
+    swapXy?: boolean;
+}
 export interface DemOverviewOptions {
     /** Use this zoom level to build the overview. Defaults to the maximum zoom level of the source. */
     level?: number;
@@ -375,7 +429,11 @@ export declare class VPL {
     static fromDebug(options?: FromDebugOptions): VPL;
     /** Reads a GeoJSON or Shapefile and emits MVT vector tiles. */
     static fromGeo(options: FromGeoOptions): VPL;
-    /** Merges multiple vector tile sources. */
+    /** Generates vector tiles containing the cells of a projected square grid, ready to be joined with data keyed on the cell id. */
+    static fromGrid(options: FromGridOptions): VPL;
+    /** Generates vector tiles containing H3 grid cells, ready to be joined with data keyed on the H3 index. */
+    static fromH3(options: FromH3Options): VPL;
+    /** Merges multiple vector tile sources. Each resulting tile will contain all the features and properties from all the sources. */
     static fromMergedVector(sources: VPL[]): VPL;
     /** Overlays multiple raster tile sources on top of each other. */
     static fromStackedRaster(sources: VPL[], options?: Omit<FromStackedRasterOptions, 'sources'>): VPL;
@@ -383,12 +441,14 @@ export declare class VPL {
     static fromStacked(sources: VPL[]): VPL;
     /** Reads a single tile file and uses it as a template for all tile requests. */
     static fromTile(options: FromTileOptions): VPL;
-    /** Reads tiles from a remote tile server via a TileJSON endpoint. */
+    /** 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. */
     static fromTilejson(options: FromTilejsonOptions): VPL;
     /** Filter tiles by bounding box, zoom levels, and/or the tile coordinates present in another container. */
     filter(options?: FilterOptions): VPL;
     /** Update metadata, see also <https://github.com/mapbox/tilejson-spec/tree/master/3.0.0> */
     metaUpdate(options?: MetaUpdateOptions): VPL;
+    /** Relabels tile coordinates, e.g. to correct 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. */
     demOverview(options?: DemOverviewOptions): VPL;
     /** Quantize DEM (elevation) raster tiles by rounding to a per-tile power-of-two step. */
@@ -401,7 +461,7 @@ export declare class VPL {
     rasterFormat(options?: RasterFormatOptions): VPL;
     /** Adjust brightness, contrast and gamma of raster tiles. */
     rasterLevels(options?: RasterLevelsOptions): VPL;
-    /** Apply a polygon mask from GeoJSON to raster tiles. */
+    /** Apply a polygon mask from GeoJSON to raster tiles. Pixels outside the polygon become transparent. */
     rasterMask(options: RasterMaskOptions): VPL;
     /** Raster overscale operation - generates tiles beyond the source's native resolution. */
     rasterOverscale(options?: RasterOverscaleOptions): VPL;
@@ -409,7 +469,7 @@ export declare class VPL {
     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. */
+    /** Drops vector features in selected layers that do not satisfy a boolean CEL expression. Features in layers outside `layer` pass through untouched. */
     vectorFilterFeatures(options: VectorFilterFeaturesOptions): VPL;
     /** Filters vector tile layers by name. */
     vectorFilterLayers(options: VectorFilterLayersOptions): VPL;

package/vpl.js

@@ -39,6 +39,8 @@ export class VPL {
     static fromContainer(options) {
         const params = {};
         params['filename'] = options.filename;
+        if (options.sshIdentity !== undefined)
+            params['ssh_identity'] = options.sshIdentity;
         return new VPL([{ name: 'from_container', params }]);
     }
     /** Reads a CSV file with longitude/latitude columns and emits MVT point tiles. */
@@ -118,7 +120,50 @@ export class VPL {
             params['ignore_id'] = options.ignoreId;
         return new VPL([{ name: 'from_geo', params }]);
     }
-    /** Merges multiple vector tile sources. */
+    /** Generates vector tiles containing the cells of a projected square grid, ready to be joined with data keyed on the cell id. */
+    static fromGrid(options) {
+        const params = {};
+        params['epsg'] = options.epsg;
+        params['size'] = options.size;
+        params['bbox'] = options.bbox;
+        if (options.offset !== undefined)
+            params['offset'] = options.offset;
+        if (options.maxCellsPerTile !== undefined)
+            params['max_cells_per_tile'] = options.maxCellsPerTile;
+        if (options.maxZoom !== undefined)
+            params['max_zoom'] = options.maxZoom;
+        if (options.idPreset !== undefined)
+            params['id_preset'] = options.idPreset;
+        if (options.idTemplate !== undefined)
+            params['id_template'] = options.idTemplate;
+        if (options.idField !== undefined)
+            params['id_field'] = options.idField;
+        if (options.xField !== undefined)
+            params['x_field'] = options.xField;
+        if (options.yField !== undefined)
+            params['y_field'] = options.yField;
+        if (options.densifyTolerance !== undefined)
+            params['densify_tolerance'] = options.densifyTolerance;
+        if (options.layerName !== undefined)
+            params['layer_name'] = options.layerName;
+        return new VPL([{ name: 'from_grid', params }]);
+    }
+    /** Generates vector tiles containing H3 grid cells, ready to be joined with data keyed on the H3 index. */
+    static fromH3(options) {
+        const params = {};
+        params['resolution'] = options.resolution;
+        params['bbox'] = options.bbox;
+        if (options.maxCellsPerTile !== undefined)
+            params['max_cells_per_tile'] = options.maxCellsPerTile;
+        if (options.maxZoom !== undefined)
+            params['max_zoom'] = options.maxZoom;
+        if (options.layerName !== undefined)
+            params['layer_name'] = options.layerName;
+        if (options.idField !== undefined)
+            params['id_field'] = options.idField;
+        return new VPL([{ name: 'from_h3', params }]);
+    }
+    /** Merges multiple vector tile sources. Each resulting tile will contain all the features and properties from all the sources. */
     static fromMergedVector(sources) {
         const params = {};
         return new VPL([{ name: 'from_merged_vector', params, sources }]);
@@ -143,7 +188,7 @@ export class VPL {
         params['filename'] = options.filename;
         return new VPL([{ name: 'from_tile', params }]);
     }
-    /** Reads tiles from a remote tile server via a TileJSON endpoint. */
+    /** 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. */
     static fromTilejson(options) {
         const params = {};
         params['url'] = options.url;
@@ -158,6 +203,8 @@ export class VPL {
         const params = {};
         if (options?.bbox !== undefined)
             params['bbox'] = options?.bbox;
+        if (options?.bboxBorder !== undefined)
+            params['bbox_border'] = options?.bboxBorder;
         if (options?.levelMin !== undefined)
             params['level_min'] = options?.levelMin;
         if (options?.levelMax !== undefined)
@@ -199,6 +246,17 @@ export class VPL {
             params['vector_layers_file'] = options?.vectorLayersFile;
         return new VPL([...this.steps, { name: 'meta_update', params }]);
     }
+    /** Relabels tile coordinates, e.g. to correct a source that uses TMS row order or `z/y/x` paths. */
+    remapCoords(options) {
+        const params = {};
+        if (options?.flipX !== undefined)
+            params['flip_x'] = options?.flipX;
+        if (options?.flipY !== undefined)
+            params['flip_y'] = options?.flipY;
+        if (options?.swapXy !== undefined)
+            params['swap_xy'] = options?.swapXy;
+        return new VPL([...this.steps, { name: 'remap_coords', params }]);
+    }
     /** Generate lower-zoom DEM overview tiles by averaging 24-bit elevation values. */
     demOverview(options) {
         const params = {};
@@ -259,7 +317,7 @@ export class VPL {
             params['gamma'] = options?.gamma;
         return new VPL([...this.steps, { name: 'raster_levels', params }]);
     }
-    /** Apply a polygon mask from GeoJSON to raster tiles. */
+    /** Apply a polygon mask from GeoJSON to raster tiles. Pixels outside the polygon become transparent. */
     rasterMask(options) {
         const params = {};
         params['geojson'] = options.geojson;
@@ -296,7 +354,7 @@ export class VPL {
             params['tile_size'] = options?.tileSize;
         return new VPL([...this.steps, { name: 'raster_tile_resize', params }]);
     }
-    /** Drops vector features in selected layers that do not satisfy a boolean CEL expression. */
+    /** Drops vector features in selected layers that do not satisfy a boolean CEL expression. Features in layers outside `layer` pass through untouched. */
     vectorFilterFeatures(options) {
         const params = {};
         params['layer'] = options.layer;