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