@versatiles/versatiles-rs 4.9.0 → 4.10.0

package/vpl.js

@@ -1,6 +1,6 @@
 // AUTO-GENERATED — DO NOT EDIT
 // Generated from Rust VPL operation metadata
-import { TileSource, parseVpl, parseVplCst, stringifyVpl, stringifyVplCst } from './index.js';
+import { TileSource, formatVplCst, parseVpl, parseVplCst, stringifyVpl, stringifyVplCst } from './index.js';
 /** Parse VPL text into a lossless syntax tree, returning the error rather than throwing. */
 export function parseCstResult(vpl) {
     return JSON.parse(parseVplCst(vpl));
@@ -19,12 +19,22 @@ export function parseCst(vpl) {
 export function stringifyCst(cst) {
     return stringifyVplCst(JSON.stringify(cst));
 }
+/**
+* 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 function formatCst(cst) {
+    return JSON.parse(formatVplCst(JSON.stringify(cst)));
+}
 export class VPL {
     steps;
     constructor(steps) {
         this.steps = steps;
     }
-    /** Generates solid-color tiles of the specified size and format. */
+    /** Generates raster tiles of a single solid colour. */
     static fromColor(options) {
         const params = {};
         if (options?.color !== undefined)
@@ -43,7 +53,7 @@ export class VPL {
             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. */
+    /** Reads a CSV file with longitude and latitude columns and emits MVT point tiles. */
     static fromCsv(options) {
         const params = {};
         params['filename'] = options.filename;
@@ -77,7 +87,7 @@ export class VPL {
             params['max_tile_bytes'] = options.maxTileBytes;
         return new VPL([{ name: 'from_csv', params }]);
     }
-    /** Generates debug tiles that display their coordinates as text. */
+    /** Generates tiles that draw their own coordinates, for inspecting a pipeline. */
     static fromDebug(options) {
         const params = {};
         if (options?.format !== undefined)
@@ -120,7 +130,7 @@ export class VPL {
             params['ignore_id'] = options.ignoreId;
         return new VPL([{ name: 'from_geo', params }]);
     }
-    /** 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) {
         const params = {};
         params['epsg'] = options.epsg;
@@ -148,7 +158,7 @@ export class VPL {
             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. */
+    /** Generates vector tiles holding H3 hexagons. */
     static fromH3(options) {
         const params = {};
         params['resolution'] = options.resolution;
@@ -163,12 +173,12 @@ export class VPL {
             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. */
+    /** Merges several vector tile sources into one, keeping every feature. */
     static fromMergedVector(sources) {
         const params = {};
         return new VPL([{ name: 'from_merged_vector', params, sources }]);
     }
-    /** Overlays multiple raster tile sources on top of each other. */
+    /** Blends several raster tile sources into one by alpha-compositing them. */
     static fromStackedRaster(sources, options) {
         const params = {};
         if (options?.format !== undefined)
@@ -177,18 +187,18 @@ export class VPL {
             params['auto_overscale'] = options?.autoOverscale;
         return new VPL([{ name: 'from_stacked_raster', params, sources }]);
     }
-    /** 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) {
         const params = {};
         return new VPL([{ name: 'from_stacked', params, sources }]);
     }
-    /** 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) {
         const params = {};
         params['filename'] = options.filename;
         return new VPL([{ name: 'from_tile', params }]);
     }
-    /** 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) {
         const params = {};
         params['url'] = options.url;
@@ -198,7 +208,7 @@ export class VPL {
             params['max_concurrent_requests'] = options.maxConcurrentRequests;
         return new VPL([{ name: 'from_tilejson', params }]);
     }
-    /** 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) {
         const params = {};
         if (options?.bbox !== undefined)
@@ -213,7 +223,7 @@ export class VPL {
             params['filename'] = options?.filename;
         return new VPL([...this.steps, { name: 'filter', params }]);
     }
-    /** 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) {
         const params = {};
         if (options?.attribution !== undefined)
@@ -246,7 +256,7 @@ 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. */
+    /** Relabels tile coordinates, correcting a source that uses TMS row order or `z/y/x` paths. */
     remapCoords(options) {
         const params = {};
         if (options?.flipX !== undefined)
@@ -257,7 +267,7 @@ export class VPL {
             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. */
+    /** Generates lower-zoom DEM overview tiles by averaging 24-bit elevation values. */
     demOverview(options) {
         const params = {};
         if (options?.level !== undefined)
@@ -266,7 +276,7 @@ export class VPL {
             params['encoding'] = options?.encoding;
         return new VPL([...this.steps, { name: 'dem_overview', params }]);
     }
-    /** 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) {
         const params = {};
         if (options?.elevationError !== undefined)
@@ -277,23 +287,22 @@ export class VPL {
             params['encoding'] = options?.encoding;
         return new VPL([...this.steps, { name: 'dem_quantize', params }]);
     }
-    /** Convert DEM tile size between 256px and 512px by splitting or merging tiles. */
+    /** Converts DEM tiles between 256 and 512 pixels by splitting or merging them. */
     demTileResize(options) {
         const params = {};
-        if (options?.tileSize !== undefined)
-            params['tile_size'] = options?.tileSize;
-        if (options?.encoding !== undefined)
-            params['encoding'] = options?.encoding;
+        params['tile_size'] = options.tileSize;
+        if (options.encoding !== undefined)
+            params['encoding'] = options.encoding;
         return new VPL([...this.steps, { name: 'dem_tile_resize', params }]);
     }
-    /** Flattens (translucent) raster tiles onto a background */
+    /** Composites translucent raster tiles onto an opaque background colour. */
     rasterFlatten(options) {
         const params = {};
         if (options?.color !== undefined)
             params['color'] = options?.color;
         return new VPL([...this.steps, { name: 'raster_flatten', params }]);
     }
-    /** 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) {
         const params = {};
         if (options?.format !== undefined)
@@ -306,7 +315,7 @@ export class VPL {
             params['effort'] = options?.effort;
         return new VPL([...this.steps, { name: 'raster_format', params }]);
     }
-    /** Adjust brightness, contrast and gamma of raster tiles. */
+    /** Adjusts the brightness, contrast and gamma of raster tiles. */
     rasterLevels(options) {
         const params = {};
         if (options?.brightness !== undefined)
@@ -317,7 +326,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. Pixels outside the polygon become transparent. */
+    /** Makes raster pixels outside a GeoJSON polygon transparent. */
     rasterMask(options) {
         const params = {};
         params['geojson'] = options.geojson;
@@ -329,7 +338,7 @@ export class VPL {
             params['blur_function'] = options.blurFunction;
         return new VPL([...this.steps, { name: 'raster_mask', params }]);
     }
-    /** Raster overscale operation - generates tiles beyond the source's native resolution. */
+    /** Serves raster tiles above the source's native resolution by upscaling. */
     rasterOverscale(options) {
         const params = {};
         if (options?.levelBase !== undefined)
@@ -340,28 +349,27 @@ export class VPL {
             params['enable_climbing'] = options?.enableClimbing;
         return new VPL([...this.steps, { name: 'raster_overscale', params }]);
     }
-    /** 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) {
         const params = {};
         if (options?.level !== undefined)
             params['level'] = options?.level;
         return new VPL([...this.steps, { name: 'raster_overview', params }]);
     }
-    /** Convert the size of tiles by splitting or merging them to a width of 256px or 512px. */
+    /** Converts raster tiles between 256 and 512 pixels by splitting or merging them. */
     rasterTileResize(options) {
         const params = {};
-        if (options?.tileSize !== undefined)
-            params['tile_size'] = options?.tileSize;
+        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. Features in layers outside `layer` pass through untouched. */
+    /** Drops vector features in selected layers that do not satisfy a boolean expression. */
     vectorFilterFeatures(options) {
         const params = {};
         params['layer'] = options.layer;
         params['expr'] = options.expr;
         return new VPL([...this.steps, { name: 'vector_filter_features', params }]);
     }
-    /** Filters vector tile layers by name. */
+    /** Removes whole layers from vector tiles by name. */
     vectorFilterLayers(options) {
         const params = {};
         params['filter'] = options.filter;
@@ -369,7 +377,7 @@ export class VPL {
             params['invert'] = options.invert;
         return new VPL([...this.steps, { name: 'vector_filter_layers', params }]);
     }
-    /** Filters properties based on a regular expressions. */
+    /** Removes feature properties from vector tiles by matching their names against a regex. */
     vectorFilterProperties(options) {
         const params = {};
         params['regex'] = options.regex;
@@ -377,7 +385,7 @@ export class VPL {
             params['invert'] = options.invert;
         return new VPL([...this.steps, { name: 'vector_filter_properties', params }]);
     }
-    /** 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) {
         const params = {};
         if (options?.levelBase !== undefined)
@@ -390,14 +398,14 @@ export class VPL {
             params['buffer'] = options?.buffer;
         return new VPL([...this.steps, { name: 'vector_overzoom', params }]);
     }
-    /** Repairs vector tiles to conform to MVT 2.1. */
+    /** Repairs vector tiles so that they conform to MVT 2.1. */
     vectorRepair(options) {
         const params = {};
         if (options?.dropOffenders !== undefined)
             params['drop_offenders'] = options?.dropOffenders;
         return new VPL([...this.steps, { name: 'vector_repair', params }]);
     }
-    /** Arguments for the `vector_update_properties` operation. */
+    /** Joins tabular data onto vector features, matching on an id column. */
     vectorUpdateProperties(options) {
         const params = {};
         params['data_source_path'] = options.dataSourcePath;