@urban-toolkit/autk-grammar 4.4.0 → 5.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,3 +1,4 @@
1
+ import { AutkDb } from '@urban-toolkit/autk-db';
1
2
  import { AutkMap } from '@urban-toolkit/autk-map';
2
3
  import { AutkPlot } from '@urban-toolkit/autk-plot';
3
4
  import { BBox } from 'geojson';
@@ -10,6 +11,33 @@ import { GpgpuPipelineParams } from '@urban-toolkit/autk-compute';
10
11
  /** How joined rows are combined per feature. */
11
12
  export declare type AggregateFunction = 'sum' | 'avg' | 'count' | 'min' | 'max' | 'weighted' | 'collect';
12
13
 
14
+ /**
15
+ * Moves a map's camera as `camera` says, from the view that fits the map's layers. The camera reports each change,
16
+ * so the map redraws without a request.
17
+ *
18
+ * The map adapter calls it once the map's layers are loaded and before the map's first `draw()`. A host that builds
19
+ * its own map from a spec's `map` entry calls it at the same point, so the map looks from where the grammar's would.
20
+ */
21
+ export declare function applyCamera(map: AutkMap, camera: CameraSpec): void;
22
+
23
+ /**
24
+ * Where each view of a spec goes on the page, as its `layout` says, so every host arranges a spec's views alike. The
25
+ * host makes an element for each pane (a canvas for an Autark map), places it at the pane's row and column of a grid
26
+ * of `rows` by `columns`, `gap` pixels apart, and names it in the adapter's targets: entry `index` of the `map` or
27
+ * `plot` list. Without a `layout`, the panes stack.
28
+ *
29
+ * A layout whose `type`, `columns` or `gap` cannot be arranged is refused, with a sentence that names the value.
30
+ *
31
+ * @example
32
+ * const { columns, gap, panes } = arrangeViews(spec);
33
+ * for (const pane of panes) {
34
+ * const element = document.createElement(pane.kind === 'map' ? 'canvas' : 'div');
35
+ * element.style.gridRow = String(pane.row + 1);
36
+ * element.style.gridColumn = String(pane.column + 1);
37
+ * }
38
+ */
39
+ export declare function arrangeViews(spec: UrbanSpec): ViewArrangement;
40
+
13
41
  export declare class AutkGrammar {
14
42
  private dataAdapter?;
15
43
  private mapAdapter?;
@@ -17,13 +45,17 @@ export declare class AutkGrammar {
17
45
  private computeAdapter?;
18
46
  private grammarEngine?;
19
47
  private _computeCache;
48
+ private _computeTypes;
20
49
  private _data;
21
- private _mapRegistry;
22
- private _mapLayerIds;
50
+ private _layers;
23
51
  private _maps;
24
52
  private _plotRegistry;
25
53
  private _fwdCleanups;
26
- private _plotMapLinks;
54
+ private _plotLinks;
55
+ private _plotRows;
56
+ private _exports;
57
+ /** Each GeoJSON table a run loaded and each table a join wrote, which its plots read before the database. */
58
+ private _geojsonCache;
27
59
  readonly interactions: GrammarEventEmitter;
28
60
  constructor(targets?: Targets);
29
61
  /**
@@ -45,37 +77,92 @@ export declare class AutkGrammar {
45
77
  * and read in a `requestAnimationFrame` callback registered after that call.
46
78
  */
47
79
  get maps(): readonly AutkMap[];
80
+ /**
81
+ * Every layer the maps of the last {@link run} draw for a table, found by the table's name (a layer's `dataRef`):
82
+ * for each, the map that draws it and the layer's id in that map, which is its `title`, else its `dataRef`. The
83
+ * maps come in the spec's order, each map's layers bottom first. Empty when no map draws the table.
84
+ *
85
+ * @param dataRef The table's name.
86
+ * @param mapId The map to look in, by its {@link MapId}: a string names a map by its `id`, a number by its index in
87
+ * the spec's `map` list. Without it, every map.
88
+ */
89
+ mapLayers(dataRef: string, mapId?: MapId): GrammarMapLayer[];
48
90
  /**
49
91
  * The layer a map of the last {@link run} draws for a table, found by the table's name (a layer's `dataRef`):
50
92
  * the map that draws it, and the layer's id in that map, which is its `title`, else its `dataRef`.
51
- * `undefined` when no map draws the table. When several layers draw it, the last one.
93
+ * `undefined` when no map draws the table. When several layers draw it, the last one, which is the last map's;
94
+ * {@link mapLayers} lists them all.
95
+ *
96
+ * @param dataRef The table's name.
97
+ * @param mapId The map to look in, by its {@link MapId}: a string names a map by its `id`, a number by its index in
98
+ * the spec's `map` list. Without it, every map.
52
99
  *
53
100
  * @example
54
101
  * const layer = grammar.mapLayer('buildings');
55
102
  * layer?.map.updateRenderInfo(layer.layerId, { opacity: 0.5 });
56
103
  */
57
- mapLayer(dataRef: string): GrammarMapLayer | undefined;
104
+ mapLayer(dataRef: string, mapId?: MapId): GrammarMapLayer | undefined;
105
+ /** The drawn layers of a table, on every map or on the one `mapId` names. */
106
+ private _layersOf;
107
+ /**
108
+ * Releases what the last run created: every map (its layers' GPU buffers, its textures, its canvas context, the
109
+ * controls it adds to the page and its event handlers) and the grammar's own registries, caches and event
110
+ * forwarding. autk-map's maps share one GPU device, which stays for the maps of the next run. Call it before the
111
+ * page or the container goes away; `run` calls it before it starts, so running a new spec on the same instance
112
+ * does not leak the maps of the old one.
113
+ */
114
+ destroy(): void;
58
115
  run(spec: UrbanSpec): Promise<void>;
59
116
  /**
60
- * Highlights features on the map layer that draws the table `dataRef` (see {@link mapLayer}).
61
- * If that layer is linked to a plot via `mapRef`, the plot selection is updated too.
117
+ * Highlights features on every layer that draws the table `dataRef`, in every map (see {@link mapLayers}), or only
118
+ * in the map `mapId` names. If a plot is linked to one of those layers, by a link or its `mapRef`, the plot
119
+ * selection is updated too, to the same rows: the plot finds them by their feature ids, since it can draw the
120
+ * table's rows in another order and draws the rows without a geometry, which a layer leaves out.
121
+ *
122
+ * @param dataRef The table's name.
123
+ * @param featureIds The features to highlight: their positions among those the layer draws.
124
+ * @param mapId The map to highlight on, by its {@link MapId}: a string names a map by its `id`, a number by its
125
+ * index in the spec's `map` list. Without it, every map that draws the table.
62
126
  */
63
- highlightOnMap(dataRef: string, featureIds: number[]): void;
127
+ highlightOnMap(dataRef: string, featureIds: number[], mapId?: MapId): void;
64
128
  /**
65
- * Clears highlighted features on the map layer that draws the table `dataRef` (see {@link mapLayer}).
66
- * If that layer is linked to a plot via `mapRef`, the plot selection is cleared too.
129
+ * Clears highlighted features on every layer that draws the table `dataRef`, in every map (see {@link mapLayers}),
130
+ * or only in the map `mapId` names. If a plot is linked to one of those layers, by a link or its `mapRef`, the plot
131
+ * selection is cleared too.
132
+ *
133
+ * @param dataRef The table's name.
134
+ * @param mapId The map to clear, by its {@link MapId}: a string names a map by its `id`, a number by its index in
135
+ * the spec's `map` list. Without it, every map that draws the table.
136
+ */
137
+ clearHighlightOnMap(dataRef: string, mapId?: MapId): void;
138
+ /**
139
+ * Clears the selection on the plot `plotId` names: its `id`, else its `dataRef`.
140
+ * If that plot is linked to map layers, by links or its `mapRef`, their highlights are cleared too: on every map,
141
+ * or only on the map `mapId` names.
142
+ *
143
+ * @param plotId The plot: its `id`, else its `dataRef`.
144
+ * @param mapId The map whose linked layers to clear, by its {@link MapId}: a string names a map by its `id`, a
145
+ * number by its index in the spec's `map` list. Without it, every linked layer.
67
146
  */
68
- clearHighlightOnMap(dataRef: string): void;
147
+ clearHighlightOnPlot(plotId: string, mapId?: MapId): void;
69
148
  /**
70
- * Clears the selection on the plot identified by `plotId` (its dataRef).
71
- * If that plot is linked to a map via `mapRef`, the map highlight is cleared too.
149
+ * Applies a selection to the plot `plotId` names: its `id`, else its `dataRef`.
150
+ * If that plot is linked to map layers, by links or its `mapRef`, their highlights are updated too, to the same rows
151
+ * (see {@link highlightOnMap}): on every map, or only on the map `mapId` names.
152
+ *
153
+ * @param plotId The plot: its `id`, else its `dataRef`.
154
+ * @param featureIds The features to select: their positions among those the plot draws.
155
+ * @param mapId The map whose linked layers to highlight, by its {@link MapId}: a string names a map by its `id`, a
156
+ * number by its index in the spec's `map` list. Without it, every linked layer.
72
157
  */
73
- clearHighlightOnPlot(plotId: string): void;
158
+ setPlotSelection(plotId: string, featureIds: number[], mapId?: MapId): void;
74
159
  /**
75
- * Applies a selection to the plot identified by `plotId` (its dataRef).
76
- * If that plot is linked to a map via `mapRef`, the map highlight is updated too.
160
+ * Applies a selection made on `layers`, by their positions `featureIds`, to every plot linked to one of them, at the
161
+ * plot's own positions of the selected rows.
77
162
  */
78
- setPlotSelection(plotId: string, featureIds: number[]): void;
163
+ private _selectInLinkedPlots;
164
+ /** Wires each entry of `links` between a plot and a layer of a map, both now drawn. */
165
+ private _wireLinks;
79
166
  private _rewireInteractions;
80
167
  }
81
168
 
@@ -110,6 +197,31 @@ export declare function buildBatchedUniforms(uniforms: Record<string, UniformEnt
110
197
  uniformArrays: Record<string, number[]>;
111
198
  };
112
199
 
200
+ /**
201
+ * Where a map looks from. Each field is optional; an omitted field keeps the view that fits the map's layers.
202
+ * Read by the Autark adapter; the deck.gl adapter ignores it.
203
+ */
204
+ export declare type CameraSpec = {
205
+ /**
206
+ * Zoom level: the eye sits `10000 / 2^(zoom - 10)` workspace units from the point the map looks at (straight
207
+ * above it without `pitch`), so each step doubles the scale.
208
+ * @minimum 0
209
+ */
210
+ zoom?: number;
211
+ /**
212
+ * Tilt from straight down, in degrees.
213
+ * @minimum 0
214
+ * @maximum 90
215
+ */
216
+ pitch?: number;
217
+ /**
218
+ * Compass heading the view faces, in degrees clockwise from north: the map turns around the point it looks at.
219
+ * @minimum 0
220
+ * @maximum 360
221
+ */
222
+ bearing?: number;
223
+ };
224
+
113
225
  /** Color scheme for a colored map layer: `scheme*` names are categorical, `interpolate*` names are sequential or diverging. */
114
226
  export declare enum ColorMapInterpolator {
115
227
  CAT_ACCENT = "schemeAccent",
@@ -165,56 +277,60 @@ export declare interface ComputeAdapter {
165
277
  resolveCompute(context: unknown, spec: ComputeSpec): Promise<unknown>;
166
278
  }
167
279
 
168
- declare type ComputeBase = {
169
- /** Name of the table the shader runs over, one invocation per feature. */
170
- dataRef: string;
171
- /** Maps WGSL variable names to feature property paths. */
172
- attributes: Record<string, string>;
173
- attributeArrays?: Record<string, number>;
174
- attributeMatrices?: Record<string, {
175
- rows: number | 'auto';
176
- cols: number;
177
- }>;
178
- /** Scalar constants shared by every invocation, written inline or read from a feature. */
179
- uniforms?: Record<string, number | FromFeatureDirective>;
180
- uniformArrays?: Record<string, number[]>;
181
- /** Matrix constants shared by every invocation, written inline or read from a feature. */
182
- uniformMatrices?: Record<string, {
183
- data: number[][];
184
- cols: number;
185
- } | FromFeatureDirective>;
186
- /** WGSL body of the compute function. An array is joined with newlines, which keeps long shaders readable in JSON. */
187
- wglsFunction: string | string[];
188
- };
189
-
190
280
  export declare type ComputeCache = Map<string, FeatureCollection>;
191
281
 
192
282
  /** Every table a compute pass reads: its `dataRef` plus each `fromFeature` layer. */
193
- export declare function computeLayerNames(block: ComputeSpec): string[];
283
+ export declare function computeLayerNames(block: GpgpuComputeSpec): string[];
194
284
 
195
285
  /** Tables a compute pass can read, keyed by table name. */
196
286
  export declare type ComputeLayers = Record<string, FeatureCollection | undefined> | Map<string, FeatureCollection>;
197
287
 
288
+ /** How the map draws a table a compute pass wrote under `outputTableName`, which the database does not know. */
289
+ export declare type ComputeLayerTypes = Map<string, LayerType>;
290
+
291
+ /** Where a GPGPU pass writes its result. A render pass declares its own `outputTableName` and `layerType`. */
292
+ declare type ComputeOutput = {
293
+ /**
294
+ * Name of a new table that receives the result, so the source table stays as it is and later passes, maps and
295
+ * plots can read both. Without it, the pass writes into its `dataRef` table.
296
+ */
297
+ outputTableName?: string;
298
+ /**
299
+ * How the map draws the new table. Defaults to the type of the table it was computed from. Only used with
300
+ * `outputTableName`.
301
+ */
302
+ layerType?: LayerType;
303
+ };
304
+
198
305
  /** Runs one GPU dispatch, for example `params => new AutkComputeEngine().gpgpuPipeline(params)`. */
199
306
  export declare type ComputeRunner = (params: GpgpuPipelineParams) => Promise<FeatureCollection>;
200
307
 
308
+ /** One entry of `compute`. A pass with `type: 'render'` is a {@link RenderComputeSpec}, any other a {@link GpgpuComputeSpec}. */
309
+ export declare type ComputeSpec = GpgpuComputeSpec | RenderComputeSpec;
310
+
201
311
  /**
202
- * A GPU compute pass over a table. Results are written to `feature.properties.compute.<column>`.
203
- * It needs `outputColumnName` for a single result or `outputColumns` for several.
312
+ * The compute adapter `AutkGrammar` runs. Its `resolveCompute(db, pass)` runs one entry of a spec's `compute`, a
313
+ * GPGPU pass or a render pass, on autk-compute, in the pass's workspace, which it leaves current. It does nothing
314
+ * without a database.
315
+ *
316
+ * A host calls it to run compute passes exactly as the grammar does. The passes need WebGPU, and their results are
317
+ * kept only in the caches: `cache` receives each pass's result under {@link tableKey} of its `outputTableName`, or of
318
+ * the table it computed over, and a later pass reads a table from it first. `types` receives the layer type of each
319
+ * table a pass wrote under its own `outputTableName`, which a map needs to draw it.
204
320
  */
205
- export declare type ComputeSpec = ComputeBase & ({
206
- /** Column written when the shader returns one value. */
207
- outputColumnName: string;
208
- /** @minItems 1 */
209
- outputColumns?: string[];
210
- } | {
211
- outputColumnName?: string;
212
- /**
213
- * Columns written when the shader returns several values, in order.
214
- * @minItems 1
215
- */
216
- outputColumns: string[];
217
- });
321
+ export declare function createComputeAdapter(cache?: ComputeCache, types?: ComputeLayerTypes): ComputeAdapter;
322
+
323
+ /**
324
+ * The data adapter `AutkGrammar` runs. Its `resolveSource(db, source)` loads one entry of a spec's `data` into the
325
+ * autk-db database `db` (a new one when `db` is undefined), in the entry's workspace, which it leaves current, and
326
+ * returns the database.
327
+ *
328
+ * A host calls it to load a spec's tables exactly as the grammar does, for example on a server without a map: the
329
+ * `./data` entry exports it with autk-db as its only import. `targets.db` names an element that lists the tables
330
+ * after each load. `cache`, when given, receives each GeoJSON table and each table a join wrote, under
331
+ * {@link tableKey}.
332
+ */
333
+ export declare function createDataAdapter(targets?: Targets, cache?: GeoJsonCache): DataAdapter;
218
334
 
219
335
  export declare function createEngine(options: EngineOptions): IEngine;
220
336
 
@@ -263,6 +379,11 @@ export declare interface CustomDataSourceSpec extends TableSourceBase {
263
379
  */
264
380
  coordinateFormat?: string;
265
381
  boundingBox?: BoundingBox;
382
+ /**
383
+ * How the map draws the layer. When omitted, autk-db reads it from the first feature's geometry. Set it to draw
384
+ * lines as `polylines` or polygons as a `buildings` layer, for example. Read by the Autark adapter only.
385
+ */
386
+ layerType?: LayerType;
266
387
  }
267
388
 
268
389
  export declare interface DataAdapter {
@@ -273,10 +394,10 @@ export declare interface DataAdapter {
273
394
  * One entry of `data`. The `type` field selects which fields apply.
274
395
  * @discriminator type
275
396
  */
276
- export declare type DataSourceSpec = OsmDataSourceSpec | CsvDataSourceSpec | JsonDataSourceSpec | CustomDataSourceSpec | HeatmapSourceSpec | JoinSourceSpec;
397
+ export declare type DataSourceSpec = OsmDataSourceSpec | CsvDataSourceSpec | JsonDataSourceSpec | CustomDataSourceSpec | GeoTiffDataSourceSpec | HeatmapSourceSpec | JoinSourceSpec;
277
398
 
278
399
  /** Kind of data source; selects which fields a `data` entry takes. */
279
- export declare type DataSourceType = 'osm' | 'csv' | 'json' | 'geojson' | 'heatmap' | 'join';
400
+ export declare type DataSourceType = 'osm' | 'csv' | 'json' | 'geojson' | 'geotiff' | 'heatmap' | 'join';
280
401
 
281
402
  export declare type EngineOptions = {
282
403
  spec: UrbanSpec;
@@ -288,11 +409,21 @@ export declare type EngineOptions = {
288
409
  };
289
410
  };
290
411
 
412
+ /**
413
+ * Makes `workspace` (the default one without a name) the workspace `db` works in; autk-db creates it on first use.
414
+ * It calls autk-db's `setWorkspace` only when `getCurrentWorkspace()` names another one.
415
+ *
416
+ * Every adapter calls it before it reads or writes a table of a spec entry, with the entry's `workspace`. A host that
417
+ * reads a spec's tables itself calls it the same way, since autk-db finds a table by its name in the current
418
+ * workspace only.
419
+ */
420
+ export declare function enterWorkspace(db: AutkDb, workspace?: string): Promise<void>;
421
+
291
422
  /**
292
423
  * The iteration a compute pass asks for, or `null`. Every iterating directive must read the same
293
424
  * layer; the first one found decides the mode and the layer.
294
425
  */
295
- export declare function findIterateSource(block: ComputeSpec): {
426
+ export declare function findIterateSource(block: GpgpuComputeSpec): {
296
427
  mode: 'all' | 'batched';
297
428
  layer: string;
298
429
  } | null;
@@ -331,6 +462,71 @@ export declare type GeoJsonCache = Map<string, FeatureCollection>;
331
462
  */
332
463
  export declare type GeometryColumns = true | LatLongGeometryColumns | WktGeometryColumns;
333
464
 
465
+ /**
466
+ * Loads a GeoTIFF raster from `geotiffFileUrl` as a raster table: one feature, with one band per value. Read by the
467
+ * Autark adapter only.
468
+ */
469
+ export declare interface GeoTiffDataSourceSpec extends TableSourceBase {
470
+ type: 'geotiff';
471
+ /**
472
+ * URL of the GeoTIFF file, relative to the page or absolute, which autk-db fetches. The file's first image is
473
+ * read: each of its bands becomes a band of the table (`band_1`, `band_2`, ...), where the file's no-data value
474
+ * reads as no value. A rotated or sheared grid is refused.
475
+ */
476
+ geotiffFileUrl: string;
477
+ /** CRS of the file, as an EPSG string. Defaults to `'EPSG:4326'`. */
478
+ coordinateFormat?: string;
479
+ /** Most cells to decode; a larger raster is downsampled to fit. Defaults to 1 000 000. */
480
+ maxRasterCells?: number;
481
+ /** How a larger raster is downsampled. Defaults to `'bilinear'`. */
482
+ resampleMethod?: 'nearest' | 'bilinear';
483
+ }
484
+
485
+ declare type GpgpuComputeBase = {
486
+ /** Workspace of the tables the pass reads and writes. */
487
+ workspace?: WorkspaceName;
488
+ /** Name of the table the shader runs over, one invocation per feature. */
489
+ dataRef: string;
490
+ /** Maps WGSL variable names to feature property paths. */
491
+ attributes: Record<string, string>;
492
+ attributeArrays?: Record<string, number>;
493
+ attributeMatrices?: Record<string, {
494
+ rows: number | 'auto';
495
+ cols: number;
496
+ }>;
497
+ /** Scalar constants shared by every invocation, written inline or read from a feature. */
498
+ uniforms?: Record<string, number | FromFeatureDirective>;
499
+ uniformArrays?: Record<string, number[]>;
500
+ /** Matrix constants shared by every invocation, written inline or read from a feature. */
501
+ uniformMatrices?: Record<string, {
502
+ data: number[][];
503
+ cols: number;
504
+ } | FromFeatureDirective>;
505
+ /** WGSL body of the compute function. An array is joined with newlines, which keeps long shaders readable in JSON. */
506
+ wgslFunction: string | string[];
507
+ };
508
+
509
+ /**
510
+ * A GPGPU compute pass over a table. Results are written to `feature.properties.compute.<column>`.
511
+ * It needs `outputColumnName` for a single result or `outputColumns` for several.
512
+ */
513
+ export declare type GpgpuComputeSpec = GpgpuComputeBase & ComputeOutput & ({
514
+ /** Column written when the shader returns one value. */
515
+ outputColumnName: string;
516
+ /** @minItems 1 */
517
+ outputColumns?: string[];
518
+ } | {
519
+ outputColumnName?: string;
520
+ /**
521
+ * Columns written when the shader returns several values, in order.
522
+ * @minItems 1
523
+ */
524
+ outputColumns: string[];
525
+ }) & {
526
+ /** `gpgpu` is the default, so existing specifications need not set it. */
527
+ type?: 'gpgpu';
528
+ };
529
+
334
530
  export declare class GrammarEventEmitter {
335
531
  private _listeners;
336
532
  on<K extends keyof GrammarEventRecord>(event: K, listener: (payload: GrammarEventRecord[K]) => void): () => void;
@@ -351,30 +547,48 @@ export declare interface GrammarMapLayer {
351
547
  }
352
548
 
353
549
  export declare interface GrammarPickingEvent {
550
+ /** The map the pick was made on, by its {@link MapId}: its `id`, else its index in the spec's `map` list. */
551
+ mapId: MapId;
552
+ /** The picked layer's id in its map: its `title`, else its `dataRef`. */
354
553
  layerId: string;
355
554
  selection: number[];
356
555
  }
357
556
 
358
557
  export declare interface GrammarPlotSelectionEvent {
558
+ /** The plot's `id`, else its `dataRef`. */
359
559
  plotId: string;
360
560
  event: 'click' | 'brush' | 'brushX' | 'brushY';
361
561
  selection: number[];
362
562
  }
363
563
 
564
+ /**
565
+ * How the rows near a heatmap cell are combined into its value: any aggregate function but `collect`, which lists the
566
+ * rows, while a cell holds one value.
567
+ */
568
+ export declare type HeatmapAggregateFunction = Exclude<AggregateFunction, 'collect'>;
569
+
364
570
  /**
365
571
  * Aggregates a table onto a regular grid, producing a raster heatmap table.
366
572
  */
367
573
  export declare interface HeatmapSourceSpec extends TableSourceBase {
368
574
  type: 'heatmap';
369
575
  /** Table whose rows are aggregated onto the grid. */
370
- tableJoinName: string;
371
- /** Radius around each grid cell, in workspace units, within which rows are aggregated. */
576
+ joinDataRef: string;
577
+ /** Which rows count toward a grid cell: those within `distance` of the cell's center. */
372
578
  near: {
579
+ /** Radius around each cell's center, in workspace units. */
373
580
  distance: number;
581
+ /**
582
+ * Measure from the cell's center to each row's centroid, the default. With `false`, measure to the nearest
583
+ * point of the row's geometry, so a long road counts in every cell within `distance` of any part of it.
584
+ */
585
+ useCentroid?: boolean;
374
586
  };
587
+ /** Aggregate the rows near each cell, one raster band per entry. */
375
588
  groupBy?: Array<{
376
589
  column: string;
377
- aggregateFn?: AggregateFunction;
590
+ /** How the rows combine into the cell's value: any aggregate but `collect`, which lists rows, while a cell holds one value. */
591
+ aggregateFn?: HeatmapAggregateFunction;
378
592
  }>;
379
593
  /** Grid resolution. */
380
594
  grid: {
@@ -431,13 +645,20 @@ export declare function isFromFeature(value: unknown): value is FromFeatureDirec
431
645
  */
432
646
  export declare interface JoinSourceSpec {
433
647
  type: 'join';
648
+ /** Workspace of the two tables. */
649
+ workspace?: WorkspaceName;
434
650
  /** Table that receives the joined columns. */
435
- tableRootName: string;
651
+ dataRef: string;
436
652
  /** Table whose rows are joined onto the root table. */
437
- tableJoinName: string;
438
- /** Join rows within `distance` (in workspace units) instead of by containment. */
653
+ joinDataRef: string;
654
+ /** Join the rows within `distance` of each root feature instead of the rows that intersect it. */
439
655
  near?: {
656
+ /** Greatest distance from a root feature to a row it receives, in workspace units. */
440
657
  distance: number;
658
+ /**
659
+ * Measure from the root feature's centroid to the row's centroid, the default. With `false`, measure between
660
+ * the geometries themselves, from their nearest points, so features that touch are 0 apart.
661
+ */
441
662
  useCentroid?: boolean;
442
663
  };
443
664
  /** Aggregate the joined rows per root feature. */
@@ -448,7 +669,7 @@ export declare interface JoinSourceSpec {
448
669
  }>;
449
670
  }
450
671
 
451
- /** Joins a `wglsFunction` written as an array of lines. Any other separator would let a `//` comment swallow the lines after it. */
672
+ /** Joins a `wgslFunction` written as an array of lines. Any other separator would let a `//` comment swallow the lines after it. */
452
673
  export declare function joinWgsl(body: string | string[]): string;
453
674
 
454
675
  /**
@@ -484,12 +705,57 @@ export declare type LatLongGeometryColumns = {
484
705
  /** OSM layer a data source can split out, or a generic geometry layer. */
485
706
  export declare type LayerType = 'surface' | 'water' | 'parks' | 'roads' | 'buildings' | 'points' | 'polygons' | 'polylines' | 'raster';
486
707
 
708
+ /**
709
+ * How the maps and plots of a specification are arranged on the page.
710
+ *
711
+ * The engine does not read it: the host that creates the map canvases and the plot elements does, through
712
+ * `arrangeViews`, which gives each view its pane.
713
+ */
714
+ export declare type LayoutSpec = {
715
+ /** `vertical` stacks the views, `horizontal` puts them side by side, `grid` fills `columns` columns. Defaults to `vertical`. */
716
+ type?: 'vertical' | 'horizontal' | 'grid';
717
+ /**
718
+ * Number of columns of a `grid`, a whole number. Defaults to 2.
719
+ * @minimum 1
720
+ * @multipleOf 1
721
+ */
722
+ columns?: number;
723
+ /**
724
+ * Space between views, in pixels. Defaults to 0.
725
+ * @minimum 0
726
+ */
727
+ gap?: number;
728
+ };
729
+
487
730
  /** A line chart over a `reduce-series` or `binning-events` transform, which it requires. */
488
731
  export declare interface LinePlotSpec extends PlotBase {
489
732
  mark: 'line' | 'linechart';
490
733
  transform: PlotTransformSpec<'reduce-series' | 'binning-events'>;
491
734
  }
492
735
 
736
+ /**
737
+ * Links a plot to a layer of a map: selecting in the plot highlights the same features on the layer, and picking on
738
+ * the layer selects them in the plot. Read by the Autark adapter; the deck.gl adapter ignores it.
739
+ */
740
+ export declare type LinkSpec = {
741
+ /**
742
+ * `id` of the plot, or its `dataRef` when it has no id.
743
+ * @minLength 1
744
+ */
745
+ source: string;
746
+ /**
747
+ * `id` of the map that highlights.
748
+ * @minLength 1
749
+ */
750
+ target: string;
751
+ /**
752
+ * Layer of the target map, by its `title`, else its `dataRef`. Defaults to the layer that draws the plot's
753
+ * `dataRef`.
754
+ * @minLength 1
755
+ */
756
+ layer?: string;
757
+ };
758
+
493
759
  /**
494
760
  * A longitude in degrees (WGS84).
495
761
  * @minimum -180
@@ -507,7 +773,13 @@ export declare interface MapAdapter {
507
773
  resolveMap(context: unknown, spec: MapSpec, index?: number): Promise<unknown>;
508
774
  }
509
775
 
510
- export declare type MapLayerIds = Map<string, string>;
776
+ /**
777
+ * How the grammar names a map of the spec: its `id`, else its index in the spec's `map` list (0 for a single map).
778
+ * `map:picking` events name the map by it, and the calls that take a `mapId` (`mapLayers`, `mapLayer`,
779
+ * `highlightOnMap`, `clearHighlightOnMap`, `setPlotSelection`, `clearHighlightOnPlot`) address one map with it: a
780
+ * string names a map by its `id`, a number by its index.
781
+ */
782
+ export declare type MapId = string | number;
511
783
 
512
784
  /**
513
785
  * One layer drawn by a map.
@@ -543,6 +815,14 @@ export declare type MapLayerSpec = {
543
815
  * @exclusiveMinimum 0
544
816
  */
545
817
  width?: number;
818
+ /**
819
+ * Radius of each point of a points layer, in meters on the ground. The Autark adapter converts it to the
820
+ * workspace's planar units at the middle of the layer's extent, where World Mercator, the default, stretches a
821
+ * meter by about 1.34 at Chicago, and passes it as autk-map's `pointSize`. Without it, autk-map's radius of 64
822
+ * planar units applies. Other layers and the deck.gl adapter ignore it.
823
+ * @exclusiveMinimum 0
824
+ */
825
+ pointSize?: number;
546
826
  /** Color the layer by the value read with `getFnv`. */
547
827
  isColorMap?: boolean;
548
828
  /** Color scheme used when `isColorMap` is set. */
@@ -608,14 +888,21 @@ export declare type MapLayerSpec = {
608
888
  defaultFnv?: string | number;
609
889
  };
610
890
 
611
- export declare type MapRegistry = Map<string, AutkMap>;
612
-
613
891
  /**
614
892
  * A map view.
615
893
  */
616
894
  export declare type MapSpec = {
895
+ /**
896
+ * Name of the map, which a link in `links` uses as its `target`. Unique among the ids of the maps and plots.
897
+ * @minLength 1
898
+ */
899
+ id?: string;
900
+ /** Workspace the map reads its layers' tables from. */
901
+ workspace?: WorkspaceName;
617
902
  /** Map style. */
618
903
  style?: string;
904
+ /** Where the map looks from. */
905
+ camera?: CameraSpec;
619
906
  /** Layers to draw, bottom first. Each names a table with `dataRef`. */
620
907
  layerRefs: MapLayerSpec[];
621
908
  };
@@ -689,13 +976,29 @@ export declare interface ParallelCoordinatesPlotSpec extends PlotBase {
689
976
  transform?: PlotTransformSpec;
690
977
  }
691
978
 
979
+ /**
980
+ * Interface for plots.
981
+ * @property {Promise<unknown>} resolvePlot - Resolves a plot specification.
982
+ * @param {unknown} context Grand grammar context for sharing data between adapters.
983
+ * @param {PlotSpec} spec The plot to draw.
984
+ * @param {number} index Position of the plot among the plots of the specification, so an adapter given one target per plot can pick its own.
985
+ */
692
986
  export declare interface PlotAdapter {
693
- resolvePlot(context: unknown, spec: PlotSpec): Promise<unknown>;
987
+ resolvePlot(context: unknown, spec: PlotSpec, index?: number): Promise<unknown>;
694
988
  }
695
989
 
696
990
  export declare interface PlotBase {
991
+ /**
992
+ * Name of the plot, which a link in `links` uses as its `source`. Unique among the ids of the maps and plots.
993
+ * Without it a plot is known by its `dataRef`, so two plots of one table need ids: a run refuses two plots known
994
+ * by one name.
995
+ * @minLength 1
996
+ */
997
+ id?: string;
697
998
  /** Name of the table to plot. */
698
999
  dataRef: string;
1000
+ /** Workspace the table is read from. */
1001
+ workspace?: WorkspaceName;
699
1002
  /**
700
1003
  * Columns to plot, in axis order. At least one is required.
701
1004
  * @minItems 1
@@ -720,15 +1023,13 @@ export declare interface PlotBase {
720
1023
  top: number;
721
1024
  bottom: number;
722
1025
  };
723
- /** `dataRef` of the map layer this plot links its selection to. */
1026
+ /** `dataRef` of the map layer this plot links its selection to. A shorthand for a link in `links`. */
724
1027
  mapRef?: string;
725
1028
  }
726
1029
 
727
1030
  /** Interaction a plot emits. */
728
1031
  export declare type PlotEvent = 'click' | 'brush' | 'brushY' | 'brushX';
729
1032
 
730
- export declare type PlotMapLinks = Map<string, string>;
731
-
732
1033
  /** Plot type. */
733
1034
  export declare type PlotMark = 'scatter' | 'bar' | 'line' | 'linechart' | 'parallel-coordinates' | 'table' | 'heatmatrix';
734
1035
 
@@ -781,12 +1082,118 @@ export declare type RasterTransferFunction = {
781
1082
  zeroCenter?: number;
782
1083
  };
783
1084
 
1085
+ /**
1086
+ * A render-based compute pass: from each viewpoint of a table it renders the layers in several directions on the GPU
1087
+ * and counts what each frame shows (a visibility or sky-view metric). The result, the viewpoints table's features
1088
+ * (one point per window with the `building-windows` strategy) with the metrics in `feature.properties.compute.render`,
1089
+ * is stored as the table `outputTableName`. Read by the Autark adapter only.
1090
+ */
1091
+ export declare type RenderComputeSpec = {
1092
+ /** Selects a render pass. */
1093
+ type: 'render';
1094
+ /** Workspace of the tables the pass reads and writes. */
1095
+ workspace?: WorkspaceName;
1096
+ /** Name of the table that receives the result. Later passes, maps and plots read it by this name. */
1097
+ outputTableName: string;
1098
+ /**
1099
+ * How the map draws the new table. Defaults to the type of the viewpoints table, or to `points` with the
1100
+ * `building-windows` strategy, whose result holds one point per window.
1101
+ */
1102
+ layerType?: LayerType;
1103
+ /**
1104
+ * Layers to render.
1105
+ * @minItems 1
1106
+ */
1107
+ layers: RenderLayerSpec[];
1108
+ /** Where the frames are rendered from: the features of a table, and the directions each one looks in. */
1109
+ viewpoints: {
1110
+ /** Name of the table whose features are the viewpoints. */
1111
+ dataRef: string;
1112
+ /**
1113
+ * Where the viewpoints are: each feature's centroid (the default), looking in the directions `sampling` sets,
1114
+ * or `building-windows`: windows along each building's facades, each looking out from the facade and 30
1115
+ * degrees to either side. The result then holds one point per window instead of the table's features.
1116
+ */
1117
+ strategy?: {
1118
+ type: 'centroid';
1119
+ } | {
1120
+ type: 'building-windows';
1121
+ /** Rows of windows on each facade, spread evenly up the building's height. */
1122
+ floors: number;
1123
+ };
1124
+ /** The directions each viewpoint looks in, around the horizon. Read with the `centroid` strategy only. */
1125
+ sampling?: {
1126
+ /** Directions sampled around each viewpoint, evenly spaced. Defaults to 1. */
1127
+ directions?: number;
1128
+ /**
1129
+ * Angle of the first direction, in degrees counterclockwise from east (0 looks east, 90 north); the others
1130
+ * follow every 360 / `directions` degrees. Defaults to 0.
1131
+ */
1132
+ azimuthOffsetDeg?: number;
1133
+ /**
1134
+ * Angle of every direction above the horizontal, in degrees: up when positive, down when negative.
1135
+ * Defaults to 0.
1136
+ */
1137
+ pitchDeg?: number;
1138
+ };
1139
+ };
1140
+ /**
1141
+ * What each feature of the result receives: `classes`, the share of its frames' pixels each layer type covers,
1142
+ * from 0 to 1; `objects`, for each object seen, the share of its frames that show it.
1143
+ */
1144
+ aggregation: {
1145
+ type: 'classes';
1146
+ /** Also count the pixels where no layer is drawn, such as the sky, as one more class. */
1147
+ includeBackground?: boolean;
1148
+ /** Name of that class. Defaults to `background`, and it must not be the type of a rendered layer. */
1149
+ backgroundLayerType?: string;
1150
+ } | {
1151
+ type: 'objects';
1152
+ };
1153
+ /**
1154
+ * The lens of the frames each viewpoint renders. Unlike a map's `camera`, which sets where a map view looks from,
1155
+ * it sets no position or direction: `viewpoints` does.
1156
+ */
1157
+ camera?: {
1158
+ /** Field of view of each square frame, in degrees. Defaults to 90. */
1159
+ fov?: number;
1160
+ /** How near and how far from the viewpoint the frames show the layers, in workspace units. */
1161
+ clip?: {
1162
+ /** Nearest distance drawn. Defaults to 1. */
1163
+ near?: number;
1164
+ /** Farthest distance drawn. Defaults to 5000. */
1165
+ far?: number;
1166
+ };
1167
+ };
1168
+ /**
1169
+ * Frame size in pixels.
1170
+ * @minimum 8
1171
+ * @multipleOf 8
1172
+ */
1173
+ tileSize?: number;
1174
+ };
1175
+
1176
+ /** A table drawn into the frames a render pass samples. */
1177
+ export declare type RenderLayerSpec = {
1178
+ /**
1179
+ * Name given to the layer in the pass. Letters, digits and underscores, not starting with a digit.
1180
+ * @pattern ^[A-Za-z_][A-Za-z0-9_]*$
1181
+ */
1182
+ id: string;
1183
+ /** Name of the table to draw. */
1184
+ dataRef: string;
1185
+ /** How the layer is drawn into the frames. A render pass draws no points. */
1186
+ type: 'surface' | 'parks' | 'water' | 'roads' | 'buildings' | 'polygons' | 'polylines';
1187
+ /** Property that holds the object's id, for `aggregation.type` `objects`. */
1188
+ objectIdProperty?: string;
1189
+ };
1190
+
784
1191
  /**
785
1192
  * Turns a compute pass into the parameters of one GPU dispatch. Pure: it reads `layers` and runs
786
1193
  * nothing. With `iterate: 'all'`, pass the feature index as `iterateIndex` for each dispatch (see
787
1194
  * {@link runCompute}). Throws when the pass's `dataRef` is not in `layers`.
788
1195
  */
789
- export declare function resolveComputeParams(block: ComputeSpec, layers: ComputeLayers, iterateIndex?: number): GpgpuPipelineParams;
1196
+ export declare function resolveComputeParams(block: GpgpuComputeSpec, layers: ComputeLayers, iterateIndex?: number): GpgpuPipelineParams;
790
1197
 
791
1198
  /**
792
1199
  * Resolves the `fromFeature` entries of `uniformMatrices` to `{ data, cols }`. An entry that does
@@ -807,7 +1214,7 @@ export declare function resolveUniforms(uniforms: Record<string, UniformEntry> |
807
1214
  * Runs a compute pass. Without iteration, or with `batched`, that is one dispatch. With `all` it is
808
1215
  * one dispatch per feature of the iterated layer, and each output column holds the sum over them.
809
1216
  */
810
- export declare function runCompute(block: ComputeSpec, layers: ComputeLayers, run: ComputeRunner): Promise<FeatureCollection>;
1217
+ export declare function runCompute(block: GpgpuComputeSpec, layers: ComputeLayers, run: ComputeRunner): Promise<FeatureCollection>;
811
1218
 
812
1219
  /** A scatterplot of two or more columns. */
813
1220
  export declare interface ScatterPlotSpec extends PlotBase {
@@ -828,6 +1235,13 @@ export declare interface ScatterPlotSpec extends PlotBase {
828
1235
  */
829
1236
  export declare const STORAGE_BUFFER_BINDING_SIZE = 134217728;
830
1237
 
1238
+ /**
1239
+ * The key a table has in the grammar's caches: its name in the default workspace, `<workspace>/<name>` in another, so
1240
+ * two workspaces can hold tables of the same name. A host reads the caches it passes to `createDataAdapter` and
1241
+ * `createComputeAdapter` with it.
1242
+ */
1243
+ export declare function tableKey(workspace: string | undefined, name: string): string;
1244
+
831
1245
  /** A table. A transform, when given, must be `sort`. */
832
1246
  export declare interface TablePlotSpec extends PlotBase {
833
1247
  mark: 'table';
@@ -840,6 +1254,8 @@ export declare interface TablePlotSpec extends PlotBase {
840
1254
  export declare interface TableSourceBase {
841
1255
  /** Name of the table this source creates. Later sources, compute passes, maps and plots refer to it by this name. */
842
1256
  outputTableName: string;
1257
+ /** Workspace the table is created in. */
1258
+ workspace?: WorkspaceName;
843
1259
  }
844
1260
 
845
1261
  /**
@@ -851,11 +1267,19 @@ export declare type TableSourceSpec = TableSourceBase & {
851
1267
  type: DataSourceType;
852
1268
  };
853
1269
 
1270
+ /** The elements of the page `AutkGrammar` draws in, by id. */
854
1271
  export declare type Targets = {
1272
+ /** Not read by the adapter. */
855
1273
  compute?: string;
1274
+ /** Id of an element that lists the loaded tables after each data source. */
856
1275
  db?: string;
1276
+ /** Id of the canvas a map draws on, or a list of ids, one canvas per entry of `map`, in order. */
857
1277
  map?: string[] | string;
858
- plot?: string;
1278
+ /**
1279
+ * Id of the element the plots draw in, or a list of ids, one element per entry of `plot`, in order. With one id,
1280
+ * every plot draws in that element.
1281
+ */
1282
+ plot?: string[] | string;
859
1283
  };
860
1284
 
861
1285
  declare type UniformEntry = number | FromFeatureDirective;
@@ -866,6 +1290,8 @@ declare type UniformEntry = number | FromFeatureDirective;
866
1290
  export declare type UrbanSpec = {
867
1291
  /** URL of the JSON Schema this specification follows. */
868
1292
  $schema?: string;
1293
+ /** How the host arranges the maps and plots. */
1294
+ layout?: LayoutSpec;
869
1295
  /** Tables to load, in order. */
870
1296
  data?: DataSourceSpec[];
871
1297
  /** Compute passes, run in order after the data is loaded. */
@@ -874,6 +1300,51 @@ export declare type UrbanSpec = {
874
1300
  map?: MapSpec[] | MapSpec;
875
1301
  /** One plot, or several. */
876
1302
  plot?: PlotSpec[] | PlotSpec;
1303
+ /** Links between plots and map layers. The engine does not read them; the adapter wires them once the maps and plots exist. */
1304
+ links?: LinkSpec[];
1305
+ };
1306
+
1307
+ /** How the views of a spec are arranged on the page: a grid of `rows` by `columns` panes, `gap` pixels apart. */
1308
+ export declare type ViewArrangement = {
1309
+ /**
1310
+ * `vertical` stacks the panes, `horizontal` puts them side by side, and `grid` fills `columns` columns, row by row:
1311
+ * the spec's `layout.type`, else `vertical`.
1312
+ */
1313
+ type: 'vertical' | 'horizontal' | 'grid';
1314
+ /** The rows of panes. */
1315
+ rows: number;
1316
+ /** The columns of panes: 1 when `vertical`, one per view when `horizontal`, and `layout.columns`, else 2, for a `grid`. */
1317
+ columns: number;
1318
+ /** The space between neighboring panes, in pixels: the spec's `layout.gap`, else 0. */
1319
+ gap: number;
1320
+ /**
1321
+ * One pane per view, in the order the grammar draws them: the maps in the order of `map`, then the plots in the
1322
+ * order of `plot`.
1323
+ */
1324
+ panes: ViewPane[];
1325
+ };
1326
+
1327
+ /** A view's pane, as {@link arrangeViews} places it. */
1328
+ export declare type ViewPane = {
1329
+ /** `map` or `plot`. It is also the key of the adapter's targets whose list names the element the view draws in. */
1330
+ kind: 'map' | 'plot';
1331
+ /**
1332
+ * The view's position among the views of its kind, in the spec's order: its element is entry `index` of the `map`
1333
+ * or `plot` target list.
1334
+ */
1335
+ index: number;
1336
+ /** The view's `id`, when it has one. */
1337
+ id?: string;
1338
+ /**
1339
+ * The name the grammar knows the view by: its `id`, else a map's `index` or a plot's `dataRef`. A map's is the
1340
+ * `mapId` of its `map:picking` events, and a plot's the `plotId` of its `plot:selection` events; the calls that
1341
+ * address one map or plot take it.
1342
+ */
1343
+ key: string | number;
1344
+ /** The pane's row in the arrangement, from 0 at the top. */
1345
+ row: number;
1346
+ /** The pane's column in the arrangement, from 0 at the left. */
1347
+ column: number;
877
1348
  };
878
1349
 
879
1350
  /**
@@ -885,4 +1356,13 @@ export declare type WktGeometryColumns = {
885
1356
  coordinateFormat?: string;
886
1357
  };
887
1358
 
1359
+ /**
1360
+ * Name of a workspace: an isolated set of tables with its own extent. The first source loaded into a workspace sets its
1361
+ * extent and later sources are cut to it, so two areas that must not clip each other go in two workspaces. A table is
1362
+ * found by its name inside its workspace, so two workspaces may hold tables of the same name. Entries without a
1363
+ * workspace use the default one. Read by the Autark adapter only.
1364
+ * @minLength 1
1365
+ */
1366
+ export declare type WorkspaceName = string;
1367
+
888
1368
  export { }