@urban-toolkit/autk-grammar 0.2.1 → 4.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/index.d.ts CHANGED
@@ -1,7 +1,13 @@
1
1
  import { AutkMap } from '@urban-toolkit/autk-map';
2
2
  import { AutkPlot } from '@urban-toolkit/autk-plot';
3
+ import { BBox } from 'geojson';
4
+ import { Feature } from 'geojson';
3
5
  import { FeatureCollection } from 'geojson';
6
+ import { GeoJsonProperties } from 'geojson';
7
+ import { Geometry } from 'geojson';
8
+ import { GpgpuPipelineParams } from '@urban-toolkit/autk-compute';
4
9
 
10
+ /** How joined rows are combined per feature. */
5
11
  export declare type AggregateFunction = 'sum' | 'avg' | 'count' | 'min' | 'max' | 'weighted' | 'collect';
6
12
 
7
13
  export declare class AutkGrammar {
@@ -54,6 +60,12 @@ export declare class AutkGrammar {
54
60
 
55
61
  export declare type AutkGrammarSpec = UrbanSpec;
56
62
 
63
+ /** A bar chart. A transform, when given, must be `binning-1d`. */
64
+ export declare interface BarPlotSpec extends PlotBase {
65
+ mark: 'bar';
66
+ transform?: PlotTransformSpec<'binning-1d'>;
67
+ }
68
+
57
69
  export declare interface BoundingBox {
58
70
  minLon: number;
59
71
  minLat: number;
@@ -61,6 +73,23 @@ export declare interface BoundingBox {
61
73
  maxLat: number;
62
74
  }
63
75
 
76
+ /**
77
+ * Packs every feature of a `batched` layer into uniform arrays:
78
+ * - a scalar entry becomes an array of one value per feature, under the entry's name;
79
+ * - a matrix entry becomes each feature's axis-aligned bounding box as four corners
80
+ * `[xmin,ymin, xmax,ymin, xmax,ymax, xmin,ymax]`, eight values per feature;
81
+ * - `num_features` holds the feature count.
82
+ * Features missing a `required` path are dropped first, and at most {@link maxBatchedFeatures}
83
+ * are packed: as many as the largest array holds in one storage buffer binding of `bindingSize`
84
+ * bytes. Plain numbers pass through; other entries that do not iterate are left to
85
+ * {@link resolveComputeParams}.
86
+ */
87
+ export declare function buildBatchedUniforms(uniforms: Record<string, UniformEntry> | undefined, matrices: Record<string, MatrixEntry> | undefined, sources: Feature[], bindingSize?: number): {
88
+ uniforms: Record<string, number>;
89
+ uniformArrays: Record<string, number[]>;
90
+ };
91
+
92
+ /** Color scheme for a colored map layer: `scheme*` names are categorical, `interpolate*` names are sequential or diverging. */
64
93
  export declare enum ColorMapInterpolator {
65
94
  CAT_ACCENT = "schemeAccent",
66
95
  CAT_DARK2 = "schemeDark2",
@@ -87,13 +116,16 @@ export declare enum ColorMapInterpolator {
87
116
  SEQ_CIVIDIS = "interpolateCividis",
88
117
  SEQ_WARM = "interpolateWarm",
89
118
  SEQ_COOL = "interpolateCool",
119
+ SEQ_CUBEHELIX_DEFAULT = "interpolateCubehelixDefault",
90
120
  SEQ_BU_GN = "interpolateBuGn",
91
121
  SEQ_BU_PU = "interpolateBuPu",
92
122
  SEQ_GN_BU = "interpolateGnBu",
93
123
  SEQ_OR_RD = "interpolateOrRd",
124
+ SEQ_PU_BU_GN = "interpolatePuBuGn",
94
125
  SEQ_PU_BU = "interpolatePuBu",
95
126
  SEQ_PU_RD = "interpolatePuRd",
96
127
  SEQ_RD_PU = "interpolateRdPu",
128
+ SEQ_YL_GN_BU = "interpolateYlGnBu",
97
129
  SEQ_YL_GN = "interpolateYlGn",
98
130
  SEQ_YL_OR_BR = "interpolateYlOrBr",
99
131
  SEQ_YL_OR_RD = "interpolateYlOrRd",
@@ -112,41 +144,81 @@ export declare interface ComputeAdapter {
112
144
  resolveCompute(context: unknown, spec: ComputeSpec): Promise<unknown>;
113
145
  }
114
146
 
115
- export declare type ComputeCache = Map<string, FeatureCollection>;
116
-
117
- export declare type ComputeSpec = {
147
+ declare type ComputeBase = {
148
+ /** Name of the table the shader runs over, one invocation per feature. */
118
149
  dataRef: string;
150
+ /** Maps WGSL variable names to feature property paths. */
119
151
  attributes: Record<string, string>;
120
152
  attributeArrays?: Record<string, number>;
121
153
  attributeMatrices?: Record<string, {
122
154
  rows: number | 'auto';
123
155
  cols: number;
124
156
  }>;
125
- uniforms?: Record<string, number>;
157
+ /** Scalar constants shared by every invocation, written inline or read from a feature. */
158
+ uniforms?: Record<string, number | FromFeatureDirective>;
126
159
  uniformArrays?: Record<string, number[]>;
160
+ /** Matrix constants shared by every invocation, written inline or read from a feature. */
127
161
  uniformMatrices?: Record<string, {
128
162
  data: number[][];
129
163
  cols: number;
130
- }>;
131
- outputColumnName?: string;
132
- outputColumns?: string[];
133
- wglsFunction: string;
164
+ } | FromFeatureDirective>;
165
+ /** WGSL body of the compute function. An array is joined with newlines, which keeps long shaders readable in JSON. */
166
+ wglsFunction: string | string[];
134
167
  };
135
168
 
169
+ export declare type ComputeCache = Map<string, FeatureCollection>;
170
+
171
+ /** Every table a compute pass reads: its `dataRef` plus each `fromFeature` layer. */
172
+ export declare function computeLayerNames(block: ComputeSpec): string[];
173
+
174
+ /** Tables a compute pass can read, keyed by table name. */
175
+ export declare type ComputeLayers = Record<string, FeatureCollection | undefined> | Map<string, FeatureCollection>;
176
+
177
+ /** Runs one GPU dispatch, for example `params => new AutkComputeEngine().gpgpuPipeline(params)`. */
178
+ export declare type ComputeRunner = (params: GpgpuPipelineParams) => Promise<FeatureCollection>;
179
+
180
+ /**
181
+ * A GPU compute pass over a table. Results are written to `feature.properties.compute.<column>`.
182
+ * It needs `outputColumnName` for a single result or `outputColumns` for several.
183
+ */
184
+ export declare type ComputeSpec = ComputeBase & ({
185
+ /** Column written when the shader returns one value. */
186
+ outputColumnName: string;
187
+ /** @minItems 1 */
188
+ outputColumns?: string[];
189
+ } | {
190
+ outputColumnName?: string;
191
+ /**
192
+ * Columns written when the shader returns several values, in order.
193
+ * @minItems 1
194
+ */
195
+ outputColumns: string[];
196
+ });
197
+
136
198
  export declare function createEngine(options: EngineOptions): IEngine;
137
199
 
138
- export declare type CsvDataSourceSpec = TableSourceSpec & {
200
+ /**
201
+ * Loads a CSV table from exactly one of `csvFileUrl` or `csvObject`.
202
+ * @if { "required": ["csvFileUrl"] }
203
+ * @then { "not": { "required": ["csvObject"] } }
204
+ * @else { "required": ["csvObject"] }
205
+ */
206
+ export declare interface CsvDataSourceSpec extends TableSourceBase {
207
+ type: 'csv';
139
208
  csvFileUrl?: string;
209
+ /** Rows as arrays; the first row holds the column names. */
140
210
  csvObject?: unknown[][];
141
211
  delimiter?: string;
142
- geometryColumns?: {
143
- latColumnName: string;
144
- longColumnName: string;
145
- coordinateFormat?: string;
146
- };
147
- };
212
+ geometryColumns?: GeometryColumns;
213
+ }
148
214
 
149
- export declare type CustomDataSourceSpec = TableSourceSpec & {
215
+ /**
216
+ * Loads a GeoJSON FeatureCollection from `geojsonFileUrl` or `geojsonObject`. When both are given, the Autark adapter reads the URL.
217
+ * @if { "not": { "required": ["geojsonFileUrl"] } }
218
+ * @then { "required": ["geojsonObject"] }
219
+ */
220
+ export declare interface CustomDataSourceSpec extends TableSourceBase {
221
+ type: 'geojson';
150
222
  geojsonFileUrl?: string;
151
223
  /**
152
224
  * GeoJSON FeatureCollection to load directly.
@@ -159,7 +231,7 @@ export declare type CustomDataSourceSpec = TableSourceSpec & {
159
231
  * of the input data. Omitting `coordinateFormat` when the data is not in EPSG:4326
160
232
  * will cause the spatial transform to produce invalid geometry.
161
233
  */
162
- geojsonObject?: FeatureCollection;
234
+ geojsonObject?: InlineFeatureCollection;
163
235
  /**
164
236
  * Source coordinate reference system of the input data, expressed as an EPSG string
165
237
  * (e.g. `'EPSG:4326'`, `'EPSG:3395'`).
@@ -170,14 +242,19 @@ export declare type CustomDataSourceSpec = TableSourceSpec & {
170
242
  */
171
243
  coordinateFormat?: string;
172
244
  boundingBox?: BoundingBox;
173
- };
245
+ }
174
246
 
175
247
  export declare interface DataAdapter {
176
248
  resolveSource(context: unknown, spec: DataSourceSpec): Promise<unknown>;
177
249
  }
178
250
 
251
+ /**
252
+ * One entry of `data`. The `type` field selects which fields apply.
253
+ * @discriminator type
254
+ */
179
255
  export declare type DataSourceSpec = OsmDataSourceSpec | CsvDataSourceSpec | JsonDataSourceSpec | CustomDataSourceSpec | HeatmapSourceSpec | JoinSourceSpec;
180
256
 
257
+ /** Kind of data source; selects which fields a `data` entry takes. */
181
258
  export declare type DataSourceType = 'osm' | 'csv' | 'json' | 'geojson' | 'heatmap' | 'join';
182
259
 
183
260
  export declare type EngineOptions = {
@@ -190,8 +267,49 @@ export declare type EngineOptions = {
190
267
  };
191
268
  };
192
269
 
270
+ /**
271
+ * The iteration a compute pass asks for, or `null`. Every iterating directive must read the same
272
+ * layer; the first one found decides the mode and the layer.
273
+ */
274
+ export declare function findIterateSource(block: ComputeSpec): {
275
+ mode: 'all' | 'batched';
276
+ layer: string;
277
+ } | null;
278
+
279
+ /**
280
+ * Reads a uniform's value from a feature of a loaded table instead of writing it inline.
281
+ */
282
+ export declare type FromFeatureDirective = {
283
+ fromFeature: {
284
+ /** Table to read from. */
285
+ layer: string;
286
+ /** Dot path from the feature root, for example `properties.height` or `geometry.coordinates.0`. */
287
+ path: string;
288
+ /** Feature index to read. Defaults to 0. */
289
+ index?: number;
290
+ /**
291
+ * Iterate over every feature of `layer`. `all` runs the shader once per feature and sums the
292
+ * outputs. `batched` packs every feature's value into a uniform array named after this entry
293
+ * (matrix entries become each feature's bounding box as four corners), adds a `num_features`
294
+ * uniform, and runs the shader once.
295
+ */
296
+ iterate?: 'all' | 'batched';
297
+ /** With `iterate: 'batched'`, drop features whose `path` does not resolve to a finite value. */
298
+ required?: boolean;
299
+ };
300
+ /** Value used when `path` does not resolve. Without it the entry is dropped. */
301
+ default?: number | number[][];
302
+ /** Matrix column count, for entries in `uniformMatrices`. */
303
+ cols?: number;
304
+ };
305
+
193
306
  export declare type GeoJsonCache = Map<string, FeatureCollection>;
194
307
 
308
+ /**
309
+ * How rows become features: `true` reads the `Latitude` and `Longitude` columns, or name the columns.
310
+ */
311
+ export declare type GeometryColumns = true | LatLongGeometryColumns | WktGeometryColumns;
312
+
195
313
  export declare class GrammarEventEmitter {
196
314
  private _listeners;
197
315
  on<K extends keyof GrammarEventRecord>(event: K, listener: (payload: GrammarEventRecord[K]) => void): () => void;
@@ -214,8 +332,14 @@ export declare interface GrammarPlotSelectionEvent {
214
332
  selection: number[];
215
333
  }
216
334
 
217
- export declare type HeatmapSourceSpec = TableSourceSpec & {
335
+ /**
336
+ * Aggregates a table onto a regular grid, producing a raster heatmap table.
337
+ */
338
+ export declare interface HeatmapSourceSpec extends TableSourceBase {
339
+ type: 'heatmap';
340
+ /** Table whose rows are aggregated onto the grid. */
218
341
  tableJoinName: string;
342
+ /** Radius around each grid cell, in workspace units, within which rows are aggregated. */
219
343
  near: {
220
344
  distance: number;
221
345
  };
@@ -223,11 +347,18 @@ export declare type HeatmapSourceSpec = TableSourceSpec & {
223
347
  column: string;
224
348
  aggregateFn?: AggregateFunction;
225
349
  }>;
350
+ /** Grid resolution. */
226
351
  grid: {
227
352
  rows: number;
228
353
  columns: number;
229
354
  };
230
- };
355
+ }
356
+
357
+ /** A heat matrix over a `binning-2d` transform, which it requires. */
358
+ export declare interface HeatmatrixPlotSpec extends PlotBase {
359
+ mark: 'heatmatrix';
360
+ transform: PlotTransformSpec<'binning-2d'>;
361
+ }
231
362
 
232
363
  export declare interface IEngine {
233
364
  run(): Promise<void>;
@@ -236,32 +367,87 @@ export declare interface IEngine {
236
367
  readonly context: unknown;
237
368
  }
238
369
 
239
- export declare type JoinSourceSpec = Omit<TableSourceSpec, 'outputTableName'> & {
370
+ /**
371
+ * A GeoJSON feature as the loader accepts it: `geometry` may be null and `properties` may be omitted.
372
+ */
373
+ export declare type InlineFeature = {
374
+ type: 'Feature';
375
+ geometry: Geometry | null;
376
+ properties?: GeoJsonProperties;
377
+ id?: string | number;
378
+ bbox?: BBox;
379
+ };
380
+
381
+ /**
382
+ * A GeoJSON FeatureCollection with at least one feature.
383
+ */
384
+ export declare type InlineFeatureCollection = {
385
+ type: 'FeatureCollection';
386
+ /** @minItems 1 */
387
+ features: InlineFeature[];
388
+ bbox?: BBox;
389
+ };
390
+
391
+ /** True when a uniform entry reads its value from a feature. */
392
+ export declare function isFromFeature(value: unknown): value is FromFeatureDirective;
393
+
394
+ /**
395
+ * Spatially joins one table onto another. The result replaces the root table.
396
+ */
397
+ export declare interface JoinSourceSpec {
398
+ type: 'join';
399
+ /** Table that receives the joined columns. */
240
400
  tableRootName: string;
401
+ /** Table whose rows are joined onto the root table. */
241
402
  tableJoinName: string;
403
+ /** Join rows within `distance` (in workspace units) instead of by containment. */
242
404
  near?: {
243
405
  distance: number;
244
406
  useCentroid?: boolean;
245
407
  };
408
+ /** Aggregate the joined rows per root feature. */
246
409
  groupBy?: Array<{
247
410
  column: string;
248
411
  aggregateFn?: AggregateFunction;
249
412
  normalize?: boolean;
250
413
  }>;
251
- };
414
+ }
415
+
416
+ /** Joins a `wglsFunction` written as an array of lines. Any other separator would let a `//` comment swallow the lines after it. */
417
+ export declare function joinWgsl(body: string | string[]): string;
252
418
 
253
- export declare type JsonDataSourceSpec = TableSourceSpec & {
419
+ /**
420
+ * Loads a JSON table from exactly one of `jsonFileUrl` or `jsonObject`.
421
+ * @if { "required": ["jsonFileUrl"] }
422
+ * @then { "not": { "required": ["jsonObject"] } }
423
+ * @else { "required": ["jsonObject"] }
424
+ */
425
+ export declare interface JsonDataSourceSpec extends TableSourceBase {
426
+ type: 'json';
254
427
  jsonFileUrl?: string;
255
428
  jsonObject?: unknown[];
256
- geometryColumns?: {
257
- latColumnName: string;
258
- longColumnName: string;
259
- coordinateFormat?: string;
260
- };
429
+ geometryColumns?: GeometryColumns;
430
+ }
431
+
432
+ /**
433
+ * Point geometry from two columns holding latitude and longitude.
434
+ */
435
+ export declare type LatLongGeometryColumns = {
436
+ latColumnName: string;
437
+ longColumnName: string;
438
+ /** CRS of the coordinates, as an EPSG string. Defaults to `'EPSG:4326'`. */
439
+ coordinateFormat?: string;
261
440
  };
262
441
 
442
+ /** OSM layer a data source can split out, or a generic geometry layer. */
263
443
  export declare type LayerType = 'surface' | 'water' | 'parks' | 'roads' | 'buildings' | 'points' | 'polygons' | 'polylines' | 'raster';
264
444
 
445
+ /** A line chart over a `reduce-series` or `binning-events` transform, which it requires. */
446
+ export declare interface LinePlotSpec extends PlotBase {
447
+ mark: 'line' | 'linechart';
448
+ transform: PlotTransformSpec<'reduce-series' | 'binning-events'>;
449
+ }
450
+
265
451
  /**
266
452
  * Interface for map styles.
267
453
  * @property {Promise<unknown>} resolveMap - Resolves map specification.
@@ -272,81 +458,116 @@ export declare interface MapAdapter {
272
458
  resolveMap(context: unknown, spec: MapSpec, index?: number): Promise<unknown>;
273
459
  }
274
460
 
461
+ /**
462
+ * One layer drawn by a map.
463
+ */
464
+ export declare type MapLayerSpec = {
465
+ /** Name of the table to draw, as produced by a data source or a compute pass. */
466
+ dataRef: string;
467
+ /** Layer opacity, from 0 to 1. */
468
+ opacity?: number;
469
+ /** Color the layer by the value read with `getFnv`. */
470
+ isColorMap?: boolean;
471
+ /** Color scheme used when `isColorMap` is set. */
472
+ colorMapInterpolator?: ColorMapInterpolator;
473
+ /** Legend labels. Read by the deck.gl adapter; the Autark adapter ignores it. */
474
+ colorMapLabels?: string[];
475
+ /** Feature ids drawn as picked. Read by the deck.gl adapter; the Autark adapter ignores it. */
476
+ pickedComps?: number[];
477
+ /** How values are rescaled before coloring. */
478
+ normalization?: {
479
+ mode: NormalizationMode;
480
+ lowerPercentile?: number;
481
+ upperPercentile?: number;
482
+ };
483
+ /** Load the layer without drawing it. */
484
+ isSkip?: boolean;
485
+ /** Allow picking features on this layer. */
486
+ isPick?: boolean;
487
+ /** Dot path to the thematic value, relative to `feature.properties` (for example `tags.highway` or `compute.result`). */
488
+ getFnv?: string;
489
+ /** `categorical` reads the value as a string for discrete palettes; `quantitative` reads it as a number for continuous scales. Read by the deck.gl adapter; the Autark adapter ignores it. */
490
+ getFnvType?: 'categorical' | 'quantitative';
491
+ /** Allowed category values; anything else is drawn as the catch-all category. Only used when `getFnvType` is `categorical`. */
492
+ colorMapDomain?: string[];
493
+ catchAllCategory?: string;
494
+ /** Value used for features where `getFnv` resolves to nothing. Read by the deck.gl adapter; the Autark adapter ignores it. */
495
+ defaultFnv?: string | number;
496
+ };
497
+
275
498
  export declare type MapRegistry = Map<string, AutkMap>;
276
499
 
277
500
  /**
278
- * Type for map.
279
- * @property {string} style Map style.
280
- * @property {...} layerRef Reference to layer in data specification.
281
- * @property {number} opacity Opacity of the layer.
282
- * @property {boolean} [isColorMap] Indicates if the layer is a color map.
283
- * @property {ColorMapInterpolator} colorMapInterpolator Interpolator for color mapping.
284
- * @property {number[]} [pickedComps] Components that are picked, if any.
285
- * @property {boolean} [isSkip] Indicates if the layer should be skipped in rendering.
286
- * @property {boolean} [isPick] Indicates if the layer is for picking
287
- * @property {string} getFnv Field path to extract thematic values from. Supports dot notation for nested properties (e.g. "tags.highway" resolves to feature.properties.tags.highway).
288
- * @property {'categorical' | 'quantitative'} getFnvType How to interpret the extracted value. 'categorical' coerces to string (for discrete color palettes); 'quantitative' coerces to number (for continuous/diverging scales). When omitted the raw value is used as-is.
289
- * @property {string[]} colorMapDomain Explicit set of allowed category values. Values not in this list are collapsed to 'other'. Only meaningful when getFnvType is 'categorical'.
501
+ * A map view.
290
502
  */
291
503
  export declare type MapSpec = {
504
+ /** Map style. */
292
505
  style?: string;
293
- layerRefs: {
294
- dataRef: string;
295
- opacity?: number;
296
- isColorMap?: boolean;
297
- colorMapInterpolator?: ColorMapInterpolator;
298
- colorMapLabels?: string[];
299
- pickedComps?: number[];
300
- normalization?: {
301
- mode: NormalizationMode;
302
- lowerPercentile?: number;
303
- upperPercentile?: number;
304
- };
305
- isSkip?: boolean;
306
- isPick?: boolean;
307
- getFnv?: string;
308
- getFnvType?: 'categorical' | 'quantitative';
309
- colorMapDomain?: string[];
310
- catchAllCategory?: string;
311
- defaultFnv?: string | number;
312
- }[];
506
+ /** Layers to draw, bottom first. Each names a table with `dataRef`. */
507
+ layerRefs: MapLayerSpec[];
313
508
  };
314
509
 
510
+ declare type MatrixEntry = {
511
+ data: number[][];
512
+ cols: number;
513
+ } | FromFeatureDirective;
514
+
515
+ /**
516
+ * Most features a batched pass packs: as many as its largest array holds in one storage buffer
517
+ * binding of `bindingSize` bytes. With {@link STORAGE_BUFFER_BINDING_SIZE} that is 4,194,304
518
+ * features for a pass with a matrix entry, and 33,554,432 for one with scalar entries only.
519
+ */
520
+ export declare function maxBatchedFeatures(uniforms: Record<string, UniformEntry> | undefined, matrices: Record<string, MatrixEntry> | undefined, bindingSize?: number): number;
521
+
522
+ /** How values are rescaled before coloring. */
315
523
  export declare enum NormalizationMode {
316
524
  MIN_MAX = "minMax",
317
525
  PERCENTILE = "percentile"
318
526
  }
319
527
 
320
- export declare type OsmDataSourceSpec = TableSourceSpec & {
528
+ /**
529
+ * Loads OpenStreetMap data for a named area, from Overpass or from a PBF extract.
530
+ */
531
+ export declare interface OsmDataSourceSpec extends TableSourceBase {
532
+ type: 'osm';
533
+ /** URL of a local or remote `.osm.pbf` extract to read instead of querying Overpass. */
321
534
  pbfFileUrl?: string;
535
+ /** Split the raw OSM table into one table per layer, named `<outputTableName>_<layer>`. */
322
536
  autoLoadLayers?: {
323
- dropOsmTable: boolean;
537
+ /** Currently ignored by both adapters. */
538
+ dropOsmTable?: boolean;
324
539
  layers: Array<LayerType>;
325
540
  };
541
+ /** Area to load: the named sub-areas inside a geocoded region. */
326
542
  queryArea: {
543
+ /** Region to geocode, for example a city name. */
327
544
  geocodeArea: string;
545
+ /** Sub-areas inside the region, for example neighborhood names. */
328
546
  areas: string[];
329
547
  };
330
- };
548
+ }
549
+
550
+ /** Parallel coordinates over the plotted columns. */
551
+ export declare interface ParallelCoordinatesPlotSpec extends PlotBase {
552
+ mark: 'parallel-coordinates';
553
+ transform?: PlotTransformSpec;
554
+ }
331
555
 
332
556
  export declare interface PlotAdapter {
333
557
  resolvePlot(context: unknown, spec: PlotSpec): Promise<unknown>;
334
558
  }
335
559
 
336
- export declare type PlotEvent = 'click' | 'brush' | 'brushY' | 'brushX';
337
-
338
- export declare type PlotMapLinks = Map<string, string>;
339
-
340
- export declare type PlotMark = 'scatter' | 'bar' | 'line' | 'linechart' | 'parallel-coordinates' | 'table' | 'heatmatrix';
341
-
342
- export declare type PlotRegistry = Map<string, AutkPlot>;
343
-
344
- export declare type PlotSpec = {
560
+ export declare interface PlotBase {
561
+ /** Name of the table to plot. */
345
562
  dataRef: string;
346
- mark: PlotMark;
563
+ /**
564
+ * Columns to plot, in axis order. At least one is required.
565
+ * @minItems 1
566
+ */
347
567
  axis: string[];
348
568
  color?: string;
349
569
  title?: string;
570
+ /** Interactions the plot emits. */
350
571
  events?: PlotEvent[];
351
572
  width?: number;
352
573
  height?: number;
@@ -356,16 +577,105 @@ export declare type PlotSpec = {
356
577
  top: number;
357
578
  bottom: number;
358
579
  };
359
- transform?: {
360
- preset: string;
361
- options?: Record<string, unknown>;
362
- };
580
+ /** Layer id of a map this plot links its selection to. */
363
581
  mapRef?: string;
364
- };
582
+ }
365
583
 
366
- export declare type TableSourceSpec = {
367
- type: DataSourceType;
584
+ /** Interaction a plot emits. */
585
+ export declare type PlotEvent = 'click' | 'brush' | 'brushY' | 'brushX';
586
+
587
+ export declare type PlotMapLinks = Map<string, string>;
588
+
589
+ /** Plot type. */
590
+ export declare type PlotMark = 'scatter' | 'bar' | 'line' | 'linechart' | 'parallel-coordinates' | 'table' | 'heatmatrix';
591
+
592
+ export declare type PlotRegistry = Map<string, AutkPlot>;
593
+
594
+ /**
595
+ * A plot view. The `mark` field selects which transforms apply.
596
+ * @discriminator mark
597
+ */
598
+ export declare type PlotSpec = ScatterPlotSpec | BarPlotSpec | LinePlotSpec | ParallelCoordinatesPlotSpec | TablePlotSpec | HeatmatrixPlotSpec;
599
+
600
+ /** Transform presets a plot accepts. */
601
+ export declare type PlotTransformPreset = 'binning-1d' | 'binning-2d' | 'binning-events' | 'reduce-series' | 'sort';
602
+
603
+ /**
604
+ * Reshapes the table before plotting.
605
+ */
606
+ export declare interface PlotTransformSpec<P extends PlotTransformPreset = PlotTransformPreset> {
607
+ preset: P;
608
+ options?: Record<string, unknown>;
609
+ }
610
+
611
+ /**
612
+ * Turns a compute pass into the parameters of one GPU dispatch. Pure: it reads `layers` and runs
613
+ * nothing. With `iterate: 'all'`, pass the feature index as `iterateIndex` for each dispatch (see
614
+ * {@link runCompute}). Throws when the pass's `dataRef` is not in `layers`.
615
+ */
616
+ export declare function resolveComputeParams(block: ComputeSpec, layers: ComputeLayers, iterateIndex?: number): GpgpuPipelineParams;
617
+
618
+ /**
619
+ * Resolves the `fromFeature` entries of `uniformMatrices` to `{ data, cols }`. An entry that does
620
+ * not resolve to an array takes its `default`, or is dropped when it has none.
621
+ */
622
+ export declare function resolveUniformMatrices(matrices: Record<string, MatrixEntry> | undefined, layers: ComputeLayers, iterateIndex?: number): Record<string, {
623
+ data: number[][];
624
+ cols: number;
625
+ }> | undefined;
626
+
627
+ /**
628
+ * Resolves the `fromFeature` entries of `uniforms` to numbers. An entry that does not resolve to a
629
+ * finite number takes its `default`, or is dropped when it has none.
630
+ */
631
+ export declare function resolveUniforms(uniforms: Record<string, UniformEntry> | undefined, layers: ComputeLayers, iterateIndex?: number): Record<string, number> | undefined;
632
+
633
+ /**
634
+ * Runs a compute pass. Without iteration, or with `batched`, that is one dispatch. With `all` it is
635
+ * one dispatch per feature of the iterated layer, and each output column holds the sum over them.
636
+ */
637
+ export declare function runCompute(block: ComputeSpec, layers: ComputeLayers, run: ComputeRunner): Promise<FeatureCollection>;
638
+
639
+ /** A scatterplot of two or more columns. */
640
+ export declare interface ScatterPlotSpec extends PlotBase {
641
+ mark: 'scatter';
642
+ /**
643
+ * Columns to plot, in axis order. At least two are required.
644
+ * @minItems 2
645
+ */
646
+ axis: string[];
647
+ transform?: PlotTransformSpec;
648
+ }
649
+
650
+ /**
651
+ * The storage buffer binding every WebGPU device supports: the default
652
+ * `maxStorageBufferBindingSize`, 128 MiB. autk-compute 4 reads each array a `batched` directive
653
+ * packs from a read-only storage buffer of its own, so every packed array must fit one binding.
654
+ * autk-compute 3 bound them as uniform buffers, which hold 64 KiB (2048 bounding boxes).
655
+ */
656
+ export declare const STORAGE_BUFFER_BINDING_SIZE = 134217728;
657
+
658
+ /** A table. A transform, when given, must be `sort`. */
659
+ export declare interface TablePlotSpec extends PlotBase {
660
+ mark: 'table';
661
+ transform?: PlotTransformSpec<'sort'>;
662
+ }
663
+
664
+ /**
665
+ * Fields every table-producing data source shares.
666
+ */
667
+ export declare interface TableSourceBase {
668
+ /** Name of the table this source creates. Later sources, compute passes, maps and plots refer to it by this name. */
368
669
  outputTableName: string;
670
+ }
671
+
672
+ /**
673
+ * A data source that produces a table.
674
+ *
675
+ * @deprecated Use {@link DataSourceSpec} or one of its members; kept so older code that names this type still compiles.
676
+ */
677
+ export declare type TableSourceSpec = TableSourceBase & {
678
+ type: DataSourceType;
369
679
  };
370
680
 
371
681
  export declare type Targets = {
@@ -375,11 +685,31 @@ export declare type Targets = {
375
685
  plot?: string;
376
686
  };
377
687
 
688
+ declare type UniformEntry = number | FromFeatureDirective;
689
+
690
+ /**
691
+ * An Autark grammar specification. It names at least one of `data`, `compute`, `map` or `plot`.
692
+ */
378
693
  export declare type UrbanSpec = {
694
+ /** URL of the JSON Schema this specification follows. */
695
+ $schema?: string;
696
+ /** Tables to load, in order. */
379
697
  data?: DataSourceSpec[];
698
+ /** Compute passes, run in order after the data is loaded. */
380
699
  compute?: ComputeSpec[];
700
+ /** One map, or several. */
381
701
  map?: MapSpec[] | MapSpec;
702
+ /** One plot, or several. */
382
703
  plot?: PlotSpec[] | PlotSpec;
383
704
  };
384
705
 
706
+ /**
707
+ * Geometry from one column holding WKT text such as `POLYGON((...))`. Read by the Autark adapter only.
708
+ */
709
+ export declare type WktGeometryColumns = {
710
+ wktColumnName: string;
711
+ /** CRS of the geometry, as an EPSG string. Defaults to `'EPSG:4326'`. */
712
+ coordinateFormat?: string;
713
+ };
714
+
385
715
  export { }