@urban-toolkit/autk-grammar 4.4.1 → 5.1.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. It refuses a pitch that is not at least 0 and less than 90 degrees.
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,17 +45,22 @@ 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
  /**
30
- * The coordinate reference system used internally by the autk workspace.
62
+ * The coordinate reference system autk-db stores a workspace's tables in, unless the spec's `workspaces` sets
63
+ * another for it.
31
64
  *
32
65
  * Input data is expected in EPSG:4326 (WGS84) by default and is transformed
33
66
  * to this CRS on load. Consumers that prepare data for injection (e.g. by
@@ -45,37 +78,92 @@ export declare class AutkGrammar {
45
78
  * and read in a `requestAnimationFrame` callback registered after that call.
46
79
  */
47
80
  get maps(): readonly AutkMap[];
81
+ /**
82
+ * Every layer the maps of the last {@link run} draw for a table, found by the table's name (a layer's `dataRef`):
83
+ * for each, the map that draws it and the layer's id in that map, which is its `title`, else its `dataRef`. The
84
+ * maps come in the spec's order, each map's layers bottom first. Empty when no map draws the table.
85
+ *
86
+ * @param dataRef The table's name.
87
+ * @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
88
+ * the spec's `map` list. Without it, every map.
89
+ */
90
+ mapLayers(dataRef: string, mapId?: MapId): GrammarMapLayer[];
48
91
  /**
49
92
  * The layer a map of the last {@link run} draws for a table, found by the table's name (a layer's `dataRef`):
50
93
  * 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.
94
+ * `undefined` when no map draws the table. When several layers draw it, the last one, which is the last map's;
95
+ * {@link mapLayers} lists them all.
96
+ *
97
+ * @param dataRef The table's name.
98
+ * @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
99
+ * the spec's `map` list. Without it, every map.
52
100
  *
53
101
  * @example
54
102
  * const layer = grammar.mapLayer('buildings');
55
103
  * layer?.map.updateRenderInfo(layer.layerId, { opacity: 0.5 });
56
104
  */
57
- mapLayer(dataRef: string): GrammarMapLayer | undefined;
105
+ mapLayer(dataRef: string, mapId?: MapId): GrammarMapLayer | undefined;
106
+ /** The drawn layers of a table, on every map or on the one `mapId` names. */
107
+ private _layersOf;
108
+ /**
109
+ * Releases what the last run created: every map (its layers' GPU buffers, its textures, its canvas context, the
110
+ * controls it adds to the page and its event handlers) and the grammar's own registries, caches and event
111
+ * forwarding. autk-map's maps share one GPU device, which stays for the maps of the next run. Call it before the
112
+ * page or the container goes away; `run` calls it before it starts, so running a new spec on the same instance
113
+ * does not leak the maps of the old one.
114
+ */
115
+ destroy(): void;
58
116
  run(spec: UrbanSpec): Promise<void>;
59
117
  /**
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.
118
+ * Highlights features on every layer that draws the table `dataRef`, in every map (see {@link mapLayers}), or only
119
+ * in the map `mapId` names. If a plot is linked to one of those layers, by a link or its `mapRef`, the plot
120
+ * selection is updated too, to the same rows: the plot finds them by their feature ids, since it can draw the
121
+ * table's rows in another order and draws the rows without a geometry, which a layer leaves out.
122
+ *
123
+ * @param dataRef The table's name.
124
+ * @param featureIds The features to highlight: their positions among those the layer draws.
125
+ * @param mapId The map to highlight on, by its {@link MapId}: a string names a map by its `id`, a number by its
126
+ * index in the spec's `map` list. Without it, every map that draws the table.
127
+ */
128
+ highlightOnMap(dataRef: string, featureIds: number[], mapId?: MapId): void;
129
+ /**
130
+ * Clears highlighted features on every layer that draws the table `dataRef`, in every map (see {@link mapLayers}),
131
+ * 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
132
+ * selection is cleared too.
133
+ *
134
+ * @param dataRef The table's name.
135
+ * @param mapId The map to clear, by its {@link MapId}: a string names a map by its `id`, a number by its index in
136
+ * the spec's `map` list. Without it, every map that draws the table.
62
137
  */
63
- highlightOnMap(dataRef: string, featureIds: number[]): void;
138
+ clearHighlightOnMap(dataRef: string, mapId?: MapId): void;
64
139
  /**
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.
140
+ * Clears the selection on the plot `plotId` names: its `id`, else its `dataRef`.
141
+ * If that plot is linked to map layers, by links or its `mapRef`, their highlights are cleared too: on every map,
142
+ * or only on the map `mapId` names.
143
+ *
144
+ * @param plotId The plot: its `id`, else its `dataRef`.
145
+ * @param mapId The map whose linked layers to clear, by its {@link MapId}: a string names a map by its `id`, a
146
+ * number by its index in the spec's `map` list. Without it, every linked layer.
67
147
  */
68
- clearHighlightOnMap(dataRef: string): void;
148
+ clearHighlightOnPlot(plotId: string, mapId?: MapId): void;
69
149
  /**
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.
150
+ * Applies a selection to the plot `plotId` names: its `id`, else its `dataRef`.
151
+ * If that plot is linked to map layers, by links or its `mapRef`, their highlights are updated too, to the same rows
152
+ * (see {@link highlightOnMap}): on every map, or only on the map `mapId` names.
153
+ *
154
+ * @param plotId The plot: its `id`, else its `dataRef`.
155
+ * @param featureIds The features to select: their positions among those the plot draws.
156
+ * @param mapId The map whose linked layers to highlight, by its {@link MapId}: a string names a map by its `id`, a
157
+ * number by its index in the spec's `map` list. Without it, every linked layer.
72
158
  */
73
- clearHighlightOnPlot(plotId: string): void;
159
+ setPlotSelection(plotId: string, featureIds: number[], mapId?: MapId): void;
74
160
  /**
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.
161
+ * Applies a selection made on `layers`, by their positions `featureIds`, to every plot linked to one of them, at the
162
+ * plot's own positions of the selected rows.
77
163
  */
78
- setPlotSelection(plotId: string, featureIds: number[]): void;
164
+ private _selectInLinkedPlots;
165
+ /** Wires each entry of `links` between a plot and a layer of a map, both now drawn. */
166
+ private _wireLinks;
79
167
  private _rewireInteractions;
80
168
  }
81
169
 
@@ -110,6 +198,32 @@ export declare function buildBatchedUniforms(uniforms: Record<string, UniformEnt
110
198
  uniformArrays: Record<string, number[]>;
111
199
  };
112
200
 
201
+ /**
202
+ * Where a map looks from. Each field is optional; an omitted field keeps the view that fits the map's layers.
203
+ * Read by the Autark adapter; the deck.gl adapter ignores it.
204
+ */
205
+ export declare type CameraSpec = {
206
+ /**
207
+ * Zoom level: the eye sits `10000 / 2^(zoom - 10)` workspace units from the point the map looks at (straight
208
+ * above it without `pitch`), so each step doubles the scale.
209
+ * @minimum 0
210
+ */
211
+ zoom?: number;
212
+ /**
213
+ * Tilt from straight down, in degrees, less than 90: at 90 the eye would sit on the ground, edge-on to the map's flat
214
+ * layers, and the map could not pan.
215
+ * @minimum 0
216
+ * @exclusiveMaximum 90
217
+ */
218
+ pitch?: number;
219
+ /**
220
+ * Compass heading the view faces, in degrees clockwise from north: the map turns around the point it looks at.
221
+ * @minimum 0
222
+ * @maximum 360
223
+ */
224
+ bearing?: number;
225
+ };
226
+
113
227
  /** Color scheme for a colored map layer: `scheme*` names are categorical, `interpolate*` names are sequential or diverging. */
114
228
  export declare enum ColorMapInterpolator {
115
229
  CAT_ACCENT = "schemeAccent",
@@ -165,56 +279,61 @@ export declare interface ComputeAdapter {
165
279
  resolveCompute(context: unknown, spec: ComputeSpec): Promise<unknown>;
166
280
  }
167
281
 
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
282
  export declare type ComputeCache = Map<string, FeatureCollection>;
191
283
 
192
284
  /** Every table a compute pass reads: its `dataRef` plus each `fromFeature` layer. */
193
- export declare function computeLayerNames(block: ComputeSpec): string[];
285
+ export declare function computeLayerNames(block: GpgpuComputeSpec): string[];
194
286
 
195
287
  /** Tables a compute pass can read, keyed by table name. */
196
288
  export declare type ComputeLayers = Record<string, FeatureCollection | undefined> | Map<string, FeatureCollection>;
197
289
 
290
+ /** How the map draws a table a compute pass wrote under `outputTableName`, which the database does not know. */
291
+ export declare type ComputeLayerTypes = Map<string, LayerType>;
292
+
293
+ /** Where a GPGPU pass writes its result. A render pass declares its own `outputTableName` and `layerType`. */
294
+ declare type ComputeOutput = {
295
+ /**
296
+ * Name of a new table that receives the result, so the source table stays as it is and later passes, maps and
297
+ * plots can read both. Without it, the pass writes into its `dataRef` table.
298
+ */
299
+ outputTableName?: string;
300
+ /**
301
+ * How the map draws the new table. Defaults to the type of the table it was computed from. Only used with
302
+ * `outputTableName`.
303
+ */
304
+ layerType?: LayerType;
305
+ };
306
+
198
307
  /** Runs one GPU dispatch, for example `params => new AutkComputeEngine().gpgpuPipeline(params)`. */
199
308
  export declare type ComputeRunner = (params: GpgpuPipelineParams) => Promise<FeatureCollection>;
200
309
 
310
+ /** One entry of `compute`. A pass with `type: 'render'` is a {@link RenderComputeSpec}, any other a {@link GpgpuComputeSpec}. */
311
+ export declare type ComputeSpec = GpgpuComputeSpec | RenderComputeSpec;
312
+
201
313
  /**
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.
314
+ * The compute adapter `AutkGrammar` runs. Its `resolveCompute(db, pass)` runs one entry of a spec's `compute`, a
315
+ * GPGPU pass or a render pass, on autk-compute, in the pass's workspace, which it leaves current. It does nothing
316
+ * without a database.
317
+ *
318
+ * A host calls it to run compute passes exactly as the grammar does. The passes need WebGPU, and their results are
319
+ * kept only in the caches: `cache` receives each pass's result under {@link tableKey} of its `outputTableName`, or of
320
+ * the table it computed over, and a later pass reads a table from it first. `types` receives the layer type of each
321
+ * table a pass wrote under its own `outputTableName`, which a map needs to draw it.
204
322
  */
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
- });
323
+ export declare function createComputeAdapter(cache?: ComputeCache, types?: ComputeLayerTypes): ComputeAdapter;
324
+
325
+ /**
326
+ * The data adapter `AutkGrammar` runs. Its `resolveSource(db, source)` loads one entry of a spec's `data` into the
327
+ * autk-db database `db` (a new one when `db` is undefined), in the entry's workspace, which it leaves current, and
328
+ * returns the database. Its `resolveWorkspaces(db, workspaces)` sets each workspace a spec's `workspaces` lists to its
329
+ * CRS and precision grid, before the first source loads, leaves the default workspace current and returns the database.
330
+ *
331
+ * A host calls it to load a spec's tables exactly as the grammar does, for example on a server without a map: the
332
+ * `./data` entry exports it with autk-db as its only import. `targets.db` names an element that lists the tables
333
+ * after each load. `cache`, when given, receives each GeoJSON table and each table a join or an update wrote, under
334
+ * {@link tableKey}, and loses each table a `sql` source replaces or a `drop` source drops.
335
+ */
336
+ export declare function createDataAdapter(targets?: Targets, cache?: GeoJsonCache): Required<DataAdapter>;
218
337
 
219
338
  export declare function createEngine(options: EngineOptions): IEngine;
220
339
 
@@ -263,20 +382,42 @@ export declare interface CustomDataSourceSpec extends TableSourceBase {
263
382
  */
264
383
  coordinateFormat?: string;
265
384
  boundingBox?: BoundingBox;
385
+ /**
386
+ * How the map draws the layer. When omitted, autk-db reads it from the first feature's geometry. Set it to draw
387
+ * lines as `polylines` or polygons as a `buildings` layer, for example. Read by the Autark adapter only.
388
+ */
389
+ layerType?: LayerType;
266
390
  }
267
391
 
268
392
  export declare interface DataAdapter {
269
393
  resolveSource(context: unknown, spec: DataSourceSpec): Promise<unknown>;
394
+ /**
395
+ * Sets up the workspaces a spec's `workspaces` lists, before its first source loads, and returns the context. An
396
+ * adapter without workspaces leaves it out, and the engine then skips `workspaces`.
397
+ */
398
+ resolveWorkspaces?(context: unknown, workspaces: WorkspaceSpec[]): Promise<unknown>;
270
399
  }
271
400
 
272
401
  /**
273
402
  * One entry of `data`. The `type` field selects which fields apply.
274
403
  * @discriminator type
275
404
  */
276
- export declare type DataSourceSpec = OsmDataSourceSpec | CsvDataSourceSpec | JsonDataSourceSpec | CustomDataSourceSpec | HeatmapSourceSpec | JoinSourceSpec;
405
+ export declare type DataSourceSpec = OsmDataSourceSpec | CsvDataSourceSpec | JsonDataSourceSpec | CustomDataSourceSpec | GeoTiffDataSourceSpec | HeatmapSourceSpec | JoinSourceSpec | SqlSourceSpec | UpdateSourceSpec | DropSourceSpec;
277
406
 
278
407
  /** Kind of data source; selects which fields a `data` entry takes. */
279
- export declare type DataSourceType = 'osm' | 'csv' | 'json' | 'geojson' | 'heatmap' | 'join';
408
+ export declare type DataSourceType = 'osm' | 'csv' | 'json' | 'geojson' | 'geotiff' | 'heatmap' | 'join' | 'sql' | 'update' | 'drop';
409
+
410
+ /**
411
+ * Drops a table, so the sources, compute passes, maps and plots after it no longer find it, and `AutkGrammar.data` no
412
+ * longer lists it. Read by the Autark adapter only.
413
+ */
414
+ export declare interface DropSourceSpec {
415
+ type: 'drop';
416
+ /** Workspace of the table. */
417
+ workspace?: WorkspaceName;
418
+ /** The table to drop. */
419
+ dataRef: string;
420
+ }
280
421
 
281
422
  export declare type EngineOptions = {
282
423
  spec: UrbanSpec;
@@ -288,11 +429,21 @@ export declare type EngineOptions = {
288
429
  };
289
430
  };
290
431
 
432
+ /**
433
+ * Makes `workspace` (the default one without a name) the workspace `db` works in; autk-db creates it on first use.
434
+ * It calls autk-db's `setWorkspace` only when `getCurrentWorkspace()` names another one.
435
+ *
436
+ * Every adapter calls it before it reads or writes a table of a spec entry, with the entry's `workspace`. A host that
437
+ * reads a spec's tables itself calls it the same way, since autk-db finds a table by its name in the current
438
+ * workspace only.
439
+ */
440
+ export declare function enterWorkspace(db: AutkDb, workspace?: string): Promise<void>;
441
+
291
442
  /**
292
443
  * The iteration a compute pass asks for, or `null`. Every iterating directive must read the same
293
444
  * layer; the first one found decides the mode and the layer.
294
445
  */
295
- export declare function findIterateSource(block: ComputeSpec): {
446
+ export declare function findIterateSource(block: GpgpuComputeSpec): {
296
447
  mode: 'all' | 'batched';
297
448
  layer: string;
298
449
  } | null;
@@ -331,6 +482,71 @@ export declare type GeoJsonCache = Map<string, FeatureCollection>;
331
482
  */
332
483
  export declare type GeometryColumns = true | LatLongGeometryColumns | WktGeometryColumns;
333
484
 
485
+ /**
486
+ * Loads a GeoTIFF raster from `geotiffFileUrl` as a raster table: one feature, with one band per value. Read by the
487
+ * Autark adapter only.
488
+ */
489
+ export declare interface GeoTiffDataSourceSpec extends TableSourceBase {
490
+ type: 'geotiff';
491
+ /**
492
+ * URL of the GeoTIFF file, relative to the page or absolute, which autk-db fetches. The file's first image is
493
+ * read: each of its bands becomes a band of the table (`band_1`, `band_2`, ...), where the file's no-data value
494
+ * reads as no value. A rotated or sheared grid is refused.
495
+ */
496
+ geotiffFileUrl: string;
497
+ /** CRS of the file, as an EPSG string. Defaults to `'EPSG:4326'`. */
498
+ coordinateFormat?: string;
499
+ /** Most cells to decode; a larger raster is downsampled to fit. Defaults to 1 000 000. */
500
+ maxRasterCells?: number;
501
+ /** How a larger raster is downsampled. Defaults to `'bilinear'`. */
502
+ resampleMethod?: 'nearest' | 'bilinear';
503
+ }
504
+
505
+ declare type GpgpuComputeBase = {
506
+ /** Workspace of the tables the pass reads and writes. */
507
+ workspace?: WorkspaceName;
508
+ /** Name of the table the shader runs over, one invocation per feature. */
509
+ dataRef: string;
510
+ /** Maps WGSL variable names to feature property paths. */
511
+ attributes: Record<string, string>;
512
+ attributeArrays?: Record<string, number>;
513
+ attributeMatrices?: Record<string, {
514
+ rows: number | 'auto';
515
+ cols: number;
516
+ }>;
517
+ /** Scalar constants shared by every invocation, written inline or read from a feature. */
518
+ uniforms?: Record<string, number | FromFeatureDirective>;
519
+ uniformArrays?: Record<string, number[]>;
520
+ /** Matrix constants shared by every invocation, written inline or read from a feature. */
521
+ uniformMatrices?: Record<string, {
522
+ data: number[][];
523
+ cols: number;
524
+ } | FromFeatureDirective>;
525
+ /** WGSL body of the compute function. An array is joined with newlines, which keeps long shaders readable in JSON. */
526
+ wgslFunction: string | string[];
527
+ };
528
+
529
+ /**
530
+ * A GPGPU compute pass over a table. Results are written to `feature.properties.compute.<column>`.
531
+ * It needs `outputColumnName` for a single result or `outputColumns` for several.
532
+ */
533
+ export declare type GpgpuComputeSpec = GpgpuComputeBase & ComputeOutput & ({
534
+ /** Column written when the shader returns one value. */
535
+ outputColumnName: string;
536
+ /** @minItems 1 */
537
+ outputColumns?: string[];
538
+ } | {
539
+ outputColumnName?: string;
540
+ /**
541
+ * Columns written when the shader returns several values, in order.
542
+ * @minItems 1
543
+ */
544
+ outputColumns: string[];
545
+ }) & {
546
+ /** `gpgpu` is the default, so existing specifications need not set it. */
547
+ type?: 'gpgpu';
548
+ };
549
+
334
550
  export declare class GrammarEventEmitter {
335
551
  private _listeners;
336
552
  on<K extends keyof GrammarEventRecord>(event: K, listener: (payload: GrammarEventRecord[K]) => void): () => void;
@@ -351,30 +567,54 @@ export declare interface GrammarMapLayer {
351
567
  }
352
568
 
353
569
  export declare interface GrammarPickingEvent {
570
+ /** The map the pick was made on, by its {@link MapId}: its `id`, else its index in the spec's `map` list. */
571
+ mapId: MapId;
572
+ /** The picked layer's id in its map: its `title`, else its `dataRef`. */
354
573
  layerId: string;
355
574
  selection: number[];
356
575
  }
357
576
 
358
577
  export declare interface GrammarPlotSelectionEvent {
578
+ /** The plot's `id`, else its `dataRef`. */
359
579
  plotId: string;
360
580
  event: 'click' | 'brush' | 'brushX' | 'brushY';
361
581
  selection: number[];
362
582
  }
363
583
 
584
+ /**
585
+ * How the rows near a heatmap cell are combined into its value: any aggregate function but `collect`, which lists the
586
+ * rows, while a cell holds one value.
587
+ */
588
+ export declare type HeatmapAggregateFunction = Exclude<AggregateFunction, 'collect'>;
589
+
364
590
  /**
365
591
  * Aggregates a table onto a regular grid, producing a raster heatmap table.
366
592
  */
367
593
  export declare interface HeatmapSourceSpec extends TableSourceBase {
368
594
  type: 'heatmap';
369
595
  /** 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. */
596
+ joinDataRef: string;
597
+ /** Which rows count toward a grid cell: those within `distance` of the cell's center. */
372
598
  near: {
599
+ /** Radius around each cell's center, in workspace units. */
373
600
  distance: number;
601
+ /**
602
+ * Measure from the cell's center to each row's centroid, the default. With `false`, measure to the nearest
603
+ * point of the row's geometry, so a long road counts in every cell within `distance` of any part of it.
604
+ */
605
+ useCentroid?: boolean;
374
606
  };
607
+ /** Aggregate the rows near each cell, one raster band per entry. */
375
608
  groupBy?: Array<{
376
609
  column: string;
377
- aggregateFn?: AggregateFunction;
610
+ /** How the rows combine into the cell's value: any aggregate but `collect`, which lists rows, while a cell holds one value. */
611
+ aggregateFn?: HeatmapAggregateFunction;
612
+ /**
613
+ * Rescale the band's values from 0 to 1 across the grid's cells. It needs an autk-db with
614
+ * urban-toolkit/autark#132, which also adds `_norm` to the band's label; autk-db 4.1.1 builds the band from the
615
+ * values as they are.
616
+ */
617
+ normalize?: boolean;
378
618
  }>;
379
619
  /** Grid resolution. */
380
620
  grid: {
@@ -431,13 +671,20 @@ export declare function isFromFeature(value: unknown): value is FromFeatureDirec
431
671
  */
432
672
  export declare interface JoinSourceSpec {
433
673
  type: 'join';
674
+ /** Workspace of the two tables. */
675
+ workspace?: WorkspaceName;
434
676
  /** Table that receives the joined columns. */
435
- tableRootName: string;
677
+ dataRef: string;
436
678
  /** Table whose rows are joined onto the root table. */
437
- tableJoinName: string;
438
- /** Join rows within `distance` (in workspace units) instead of by containment. */
679
+ joinDataRef: string;
680
+ /** Join the rows within `distance` of each root feature instead of the rows that intersect it. */
439
681
  near?: {
682
+ /** Greatest distance from a root feature to a row it receives, in workspace units. */
440
683
  distance: number;
684
+ /**
685
+ * Measure from the root feature's centroid to the row's centroid, the default. With `false`, measure between
686
+ * the geometries themselves, from their nearest points, so features that touch are 0 apart.
687
+ */
441
688
  useCentroid?: boolean;
442
689
  };
443
690
  /** Aggregate the joined rows per root feature. */
@@ -448,7 +695,7 @@ export declare interface JoinSourceSpec {
448
695
  }>;
449
696
  }
450
697
 
451
- /** Joins a `wglsFunction` written as an array of lines. Any other separator would let a `//` comment swallow the lines after it. */
698
+ /** Joins a `wgslFunction` written as an array of lines. Any other separator would let a `//` comment swallow the lines after it. */
452
699
  export declare function joinWgsl(body: string | string[]): string;
453
700
 
454
701
  /**
@@ -484,12 +731,57 @@ export declare type LatLongGeometryColumns = {
484
731
  /** OSM layer a data source can split out, or a generic geometry layer. */
485
732
  export declare type LayerType = 'surface' | 'water' | 'parks' | 'roads' | 'buildings' | 'points' | 'polygons' | 'polylines' | 'raster';
486
733
 
734
+ /**
735
+ * How the maps and plots of a specification are arranged on the page.
736
+ *
737
+ * The engine does not read it: the host that creates the map canvases and the plot elements does, through
738
+ * `arrangeViews`, which gives each view its pane.
739
+ */
740
+ export declare type LayoutSpec = {
741
+ /** `vertical` stacks the views, `horizontal` puts them side by side, `grid` fills `columns` columns. Defaults to `vertical`. */
742
+ type?: 'vertical' | 'horizontal' | 'grid';
743
+ /**
744
+ * Number of columns of a `grid`, a whole number. Defaults to 2.
745
+ * @minimum 1
746
+ * @multipleOf 1
747
+ */
748
+ columns?: number;
749
+ /**
750
+ * Space between views, in pixels. Defaults to 0.
751
+ * @minimum 0
752
+ */
753
+ gap?: number;
754
+ };
755
+
487
756
  /** A line chart over a `reduce-series` or `binning-events` transform, which it requires. */
488
757
  export declare interface LinePlotSpec extends PlotBase {
489
758
  mark: 'line' | 'linechart';
490
759
  transform: PlotTransformSpec<'reduce-series' | 'binning-events'>;
491
760
  }
492
761
 
762
+ /**
763
+ * Links a plot to a layer of a map: selecting in the plot highlights the same features on the layer, and picking on
764
+ * the layer selects them in the plot. Read by the Autark adapter; the deck.gl adapter ignores it.
765
+ */
766
+ export declare type LinkSpec = {
767
+ /**
768
+ * `id` of the plot, or its `dataRef` when it has no id.
769
+ * @minLength 1
770
+ */
771
+ source: string;
772
+ /**
773
+ * `id` of the map that highlights.
774
+ * @minLength 1
775
+ */
776
+ target: string;
777
+ /**
778
+ * Layer of the target map, by its `title`, else its `dataRef`. Defaults to the layer that draws the plot's
779
+ * `dataRef`.
780
+ * @minLength 1
781
+ */
782
+ layer?: string;
783
+ };
784
+
493
785
  /**
494
786
  * A longitude in degrees (WGS84).
495
787
  * @minimum -180
@@ -507,7 +799,13 @@ export declare interface MapAdapter {
507
799
  resolveMap(context: unknown, spec: MapSpec, index?: number): Promise<unknown>;
508
800
  }
509
801
 
510
- export declare type MapLayerIds = Map<string, string>;
802
+ /**
803
+ * 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).
804
+ * `map:picking` events name the map by it, and the calls that take a `mapId` (`mapLayers`, `mapLayer`,
805
+ * `highlightOnMap`, `clearHighlightOnMap`, `setPlotSelection`, `clearHighlightOnPlot`) address one map with it: a
806
+ * string names a map by its `id`, a number by its index.
807
+ */
808
+ export declare type MapId = string | number;
511
809
 
512
810
  /**
513
811
  * One layer drawn by a map.
@@ -543,6 +841,14 @@ export declare type MapLayerSpec = {
543
841
  * @exclusiveMinimum 0
544
842
  */
545
843
  width?: number;
844
+ /**
845
+ * Radius of each point of a points layer, in meters on the ground. The Autark adapter converts it to the
846
+ * workspace's planar units at the middle of the layer's extent, where World Mercator, the default, stretches a
847
+ * meter by about 1.34 at Chicago, and passes it as autk-map's `pointSize`. Without it, autk-map's radius of 64
848
+ * planar units applies. Other layers and the deck.gl adapter ignore it.
849
+ * @exclusiveMinimum 0
850
+ */
851
+ pointSize?: number;
546
852
  /** Color the layer by the value read with `getFnv`. */
547
853
  isColorMap?: boolean;
548
854
  /** Color scheme used when `isColorMap` is set. */
@@ -597,6 +903,13 @@ export declare type MapLayerSpec = {
597
903
  * @minItems 1
598
904
  */
599
905
  selectFields?: string[];
906
+ /**
907
+ * Draw an OpenStreetMap layer table as one feature per OSM element it was built from, each with the element's tags,
908
+ * `osm_type` and `osm_id` as its properties (and `building_id` in a buildings table, whose parts are elements of
909
+ * their own), rather than one feature per row. A table that is not an OSM layer, a surface, and an OSM table an
910
+ * update changed are drawn row by row, as without it. Read by the Autark adapter only.
911
+ */
912
+ osmElements?: boolean;
600
913
  /** Dot path to the thematic value, relative to `feature.properties` (for example `tags.highway` or `compute.result`). */
601
914
  getFnv?: string;
602
915
  /** `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. */
@@ -608,14 +921,21 @@ export declare type MapLayerSpec = {
608
921
  defaultFnv?: string | number;
609
922
  };
610
923
 
611
- export declare type MapRegistry = Map<string, AutkMap>;
612
-
613
924
  /**
614
925
  * A map view.
615
926
  */
616
927
  export declare type MapSpec = {
928
+ /**
929
+ * Name of the map, which a link in `links` uses as its `target`. Unique among the ids of the maps and plots.
930
+ * @minLength 1
931
+ */
932
+ id?: string;
933
+ /** Workspace the map reads its layers' tables from. */
934
+ workspace?: WorkspaceName;
617
935
  /** Map style. */
618
936
  style?: string;
937
+ /** Where the map looks from. */
938
+ camera?: CameraSpec;
619
939
  /** Layers to draw, bottom first. Each names a table with `dataRef`. */
620
940
  layerRefs: MapLayerSpec[];
621
941
  };
@@ -656,15 +976,36 @@ export declare interface OsmBoundingBoxArea {
656
976
 
657
977
  /**
658
978
  * Loads OpenStreetMap data for a named area or a box, from Overpass or from a PBF extract.
979
+ * @if { "required": ["pbfFileUrl"] }
980
+ * @then { "not": { "required": ["tagSets"], "properties": { "tagSets": { "minItems": 1 } } } }
659
981
  */
660
982
  export declare interface OsmDataSourceSpec extends TableSourceBase {
661
983
  type: 'osm';
662
984
  /** URL of a local or remote `.osm.pbf` extract to read instead of querying Overpass. */
663
985
  pbfFileUrl?: string;
986
+ /**
987
+ * Features chosen by their tags, each set as a table of its own, `<outputTableName>_<name>_<type>`, cut to the
988
+ * area. A set that matches no feature in the area makes no table. Read from the Overpass API only: a source with
989
+ * `pbfFileUrl` cannot take them. Read by the Autark adapter only.
990
+ * @maxItems 8
991
+ */
992
+ tagSets?: OsmTagSet[];
993
+ /**
994
+ * Query the Overpass API again rather than read the answer the browser cached for this area, its layers and its tag
995
+ * sets, which autk-db keeps for 24 hours. A source with `pbfFileUrl` reads its file each time and ignores it. Read
996
+ * by the Autark adapter only.
997
+ */
998
+ forceRefresh?: boolean;
664
999
  /** Split the raw OSM table into one table per layer, named `<outputTableName>_<layer>`. */
665
1000
  autoLoadLayers?: {
666
1001
  /** Currently ignored by both adapters. */
667
1002
  dropOsmTable?: boolean;
1003
+ /**
1004
+ * CRS of the OpenStreetMap data's coordinates, as an EPSG string. Defaults to `'EPSG:4326'`, the degrees the
1005
+ * Overpass API and OpenStreetMap's extracts give. The layers and the tag sets are read in it. Read by the Autark
1006
+ * adapter only.
1007
+ */
1008
+ coordinateFormat?: string;
668
1009
  layers: Array<LayerType>;
669
1010
  };
670
1011
  /** Area to load: sub-areas inside a geocoded region (`geocodeArea` with `areas`), or a box (`bbox`), not both. */
@@ -683,19 +1024,78 @@ export declare interface OsmNamedArea {
683
1024
  bbox?: undefined;
684
1025
  }
685
1026
 
1027
+ /**
1028
+ * An OpenStreetMap tag a tag set matches: the tag `key` with the value `value`, or with any value when `value` is
1029
+ * omitted.
1030
+ */
1031
+ export declare type OsmTagFilter = {
1032
+ /**
1033
+ * The tag's key, such as `amenity` or `addr:street`: letters, digits, `_`, `:`, `.` and `-`, starting with a letter
1034
+ * or a digit.
1035
+ * @pattern ^[A-Za-z0-9][A-Za-z0-9_:.-]{0,254}$
1036
+ */
1037
+ key: string;
1038
+ /**
1039
+ * The tag's value, such as `cafe`. Without it, the key with any value matches.
1040
+ * @minLength 1
1041
+ * @maxLength 255
1042
+ */
1043
+ value?: string;
1044
+ };
1045
+
1046
+ /**
1047
+ * OpenStreetMap features chosen by their tags, as one table of one geometry type.
1048
+ */
1049
+ export declare type OsmTagSet = {
1050
+ /**
1051
+ * Names the set's table, `<outputTableName>_<name>_<type>`: a lowercase letter, then up to 31 lowercase letters,
1052
+ * digits or `_`. No two sets of a source share a name.
1053
+ * @pattern ^[a-z][a-z0-9_]{0,31}$
1054
+ */
1055
+ name: string;
1056
+ /**
1057
+ * The geometry the table holds: `points`, the tagged nodes; `polylines`, the open ways and the ways tagged as
1058
+ * lines (`highway`, `barrier`, `railway`, `waterway`, or `area=no`); `polygons`, the other closed ways and the
1059
+ * multipolygon relations.
1060
+ */
1061
+ type: 'points' | 'polylines' | 'polygons';
1062
+ /**
1063
+ * The tags a feature is chosen by: it is in the set when it has any one of them.
1064
+ * @minItems 1
1065
+ * @maxItems 64
1066
+ */
1067
+ tags: OsmTagFilter[];
1068
+ };
1069
+
686
1070
  /** Parallel coordinates over the plotted columns. */
687
1071
  export declare interface ParallelCoordinatesPlotSpec extends PlotBase {
688
1072
  mark: 'parallel-coordinates';
689
1073
  transform?: PlotTransformSpec;
690
1074
  }
691
1075
 
1076
+ /**
1077
+ * Interface for plots.
1078
+ * @property {Promise<unknown>} resolvePlot - Resolves a plot specification.
1079
+ * @param {unknown} context Grand grammar context for sharing data between adapters.
1080
+ * @param {PlotSpec} spec The plot to draw.
1081
+ * @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.
1082
+ */
692
1083
  export declare interface PlotAdapter {
693
- resolvePlot(context: unknown, spec: PlotSpec): Promise<unknown>;
1084
+ resolvePlot(context: unknown, spec: PlotSpec, index?: number): Promise<unknown>;
694
1085
  }
695
1086
 
696
1087
  export declare interface PlotBase {
1088
+ /**
1089
+ * Name of the plot, which a link in `links` uses as its `source`. Unique among the ids of the maps and plots.
1090
+ * Without it a plot is known by its `dataRef`, so two plots of one table need ids: a run refuses two plots known
1091
+ * by one name.
1092
+ * @minLength 1
1093
+ */
1094
+ id?: string;
697
1095
  /** Name of the table to plot. */
698
1096
  dataRef: string;
1097
+ /** Workspace the table is read from. */
1098
+ workspace?: WorkspaceName;
699
1099
  /**
700
1100
  * Columns to plot, in axis order. At least one is required.
701
1101
  * @minItems 1
@@ -720,15 +1120,20 @@ export declare interface PlotBase {
720
1120
  top: number;
721
1121
  bottom: number;
722
1122
  };
723
- /** `dataRef` of the map layer this plot links its selection to. */
1123
+ /** `dataRef` of the map layer this plot links its selection to. A shorthand for a link in `links`. */
724
1124
  mapRef?: string;
1125
+ /**
1126
+ * Plot an OpenStreetMap layer table as one row per OSM element it was built from, each with the element's tags,
1127
+ * `osm_type` and `osm_id` (and `building_id` in a buildings table), rather than one row per table row. A table that
1128
+ * is not an OSM layer, a surface, and an OSM table an update changed are plotted row by row, as without it. Read by
1129
+ * the Autark adapter only.
1130
+ */
1131
+ osmElements?: boolean;
725
1132
  }
726
1133
 
727
1134
  /** Interaction a plot emits. */
728
1135
  export declare type PlotEvent = 'click' | 'brush' | 'brushY' | 'brushX';
729
1136
 
730
- export declare type PlotMapLinks = Map<string, string>;
731
-
732
1137
  /** Plot type. */
733
1138
  export declare type PlotMark = 'scatter' | 'bar' | 'line' | 'linechart' | 'parallel-coordinates' | 'table' | 'heatmatrix';
734
1139
 
@@ -781,12 +1186,118 @@ export declare type RasterTransferFunction = {
781
1186
  zeroCenter?: number;
782
1187
  };
783
1188
 
1189
+ /**
1190
+ * A render-based compute pass: from each viewpoint of a table it renders the layers in several directions on the GPU
1191
+ * and counts what each frame shows (a visibility or sky-view metric). The result, the viewpoints table's features
1192
+ * (one point per window with the `building-windows` strategy) with the metrics in `feature.properties.compute.render`,
1193
+ * is stored as the table `outputTableName`. Read by the Autark adapter only.
1194
+ */
1195
+ export declare type RenderComputeSpec = {
1196
+ /** Selects a render pass. */
1197
+ type: 'render';
1198
+ /** Workspace of the tables the pass reads and writes. */
1199
+ workspace?: WorkspaceName;
1200
+ /** Name of the table that receives the result. Later passes, maps and plots read it by this name. */
1201
+ outputTableName: string;
1202
+ /**
1203
+ * How the map draws the new table. Defaults to the type of the viewpoints table, or to `points` with the
1204
+ * `building-windows` strategy, whose result holds one point per window.
1205
+ */
1206
+ layerType?: LayerType;
1207
+ /**
1208
+ * Layers to render.
1209
+ * @minItems 1
1210
+ */
1211
+ layers: RenderLayerSpec[];
1212
+ /** Where the frames are rendered from: the features of a table, and the directions each one looks in. */
1213
+ viewpoints: {
1214
+ /** Name of the table whose features are the viewpoints. */
1215
+ dataRef: string;
1216
+ /**
1217
+ * Where the viewpoints are: each feature's centroid (the default), looking in the directions `sampling` sets,
1218
+ * or `building-windows`: windows along each building's facades, each looking out from the facade and 30
1219
+ * degrees to either side. The result then holds one point per window instead of the table's features.
1220
+ */
1221
+ strategy?: {
1222
+ type: 'centroid';
1223
+ } | {
1224
+ type: 'building-windows';
1225
+ /** Rows of windows on each facade, spread evenly up the building's height. */
1226
+ floors: number;
1227
+ };
1228
+ /** The directions each viewpoint looks in, around the horizon. Read with the `centroid` strategy only. */
1229
+ sampling?: {
1230
+ /** Directions sampled around each viewpoint, evenly spaced. Defaults to 1. */
1231
+ directions?: number;
1232
+ /**
1233
+ * Angle of the first direction, in degrees counterclockwise from east (0 looks east, 90 north); the others
1234
+ * follow every 360 / `directions` degrees. Defaults to 0.
1235
+ */
1236
+ azimuthOffsetDeg?: number;
1237
+ /**
1238
+ * Angle of every direction above the horizontal, in degrees: up when positive, down when negative.
1239
+ * Defaults to 0.
1240
+ */
1241
+ pitchDeg?: number;
1242
+ };
1243
+ };
1244
+ /**
1245
+ * What each feature of the result receives: `classes`, the share of its frames' pixels each layer type covers,
1246
+ * from 0 to 1; `objects`, for each object seen, the share of its frames that show it.
1247
+ */
1248
+ aggregation: {
1249
+ type: 'classes';
1250
+ /** Also count the pixels where no layer is drawn, such as the sky, as one more class. */
1251
+ includeBackground?: boolean;
1252
+ /** Name of that class. Defaults to `background`, and it must not be the type of a rendered layer. */
1253
+ backgroundLayerType?: string;
1254
+ } | {
1255
+ type: 'objects';
1256
+ };
1257
+ /**
1258
+ * The lens of the frames each viewpoint renders. Unlike a map's `camera`, which sets where a map view looks from,
1259
+ * it sets no position or direction: `viewpoints` does.
1260
+ */
1261
+ camera?: {
1262
+ /** Field of view of each square frame, in degrees. Defaults to 90. */
1263
+ fov?: number;
1264
+ /** How near and how far from the viewpoint the frames show the layers, in workspace units. */
1265
+ clip?: {
1266
+ /** Nearest distance drawn. Defaults to 1. */
1267
+ near?: number;
1268
+ /** Farthest distance drawn. Defaults to 5000. */
1269
+ far?: number;
1270
+ };
1271
+ };
1272
+ /**
1273
+ * Frame size in pixels.
1274
+ * @minimum 8
1275
+ * @multipleOf 8
1276
+ */
1277
+ tileSize?: number;
1278
+ };
1279
+
1280
+ /** A table drawn into the frames a render pass samples. */
1281
+ export declare type RenderLayerSpec = {
1282
+ /**
1283
+ * Name given to the layer in the pass. Letters, digits and underscores, not starting with a digit.
1284
+ * @pattern ^[A-Za-z_][A-Za-z0-9_]*$
1285
+ */
1286
+ id: string;
1287
+ /** Name of the table to draw. */
1288
+ dataRef: string;
1289
+ /** How the layer is drawn into the frames. A render pass draws no points. */
1290
+ type: 'surface' | 'parks' | 'water' | 'roads' | 'buildings' | 'polygons' | 'polylines';
1291
+ /** Property that holds the object's id, for `aggregation.type` `objects`. */
1292
+ objectIdProperty?: string;
1293
+ };
1294
+
784
1295
  /**
785
1296
  * Turns a compute pass into the parameters of one GPU dispatch. Pure: it reads `layers` and runs
786
1297
  * nothing. With `iterate: 'all'`, pass the feature index as `iterateIndex` for each dispatch (see
787
1298
  * {@link runCompute}). Throws when the pass's `dataRef` is not in `layers`.
788
1299
  */
789
- export declare function resolveComputeParams(block: ComputeSpec, layers: ComputeLayers, iterateIndex?: number): GpgpuPipelineParams;
1300
+ export declare function resolveComputeParams(block: GpgpuComputeSpec, layers: ComputeLayers, iterateIndex?: number): GpgpuPipelineParams;
790
1301
 
791
1302
  /**
792
1303
  * Resolves the `fromFeature` entries of `uniformMatrices` to `{ data, cols }`. An entry that does
@@ -807,7 +1318,7 @@ export declare function resolveUniforms(uniforms: Record<string, UniformEntry> |
807
1318
  * Runs a compute pass. Without iteration, or with `batched`, that is one dispatch. With `all` it is
808
1319
  * one dispatch per feature of the iterated layer, and each output column holds the sum over them.
809
1320
  */
810
- export declare function runCompute(block: ComputeSpec, layers: ComputeLayers, run: ComputeRunner): Promise<FeatureCollection>;
1321
+ export declare function runCompute(block: GpgpuComputeSpec, layers: ComputeLayers, run: ComputeRunner): Promise<FeatureCollection>;
811
1322
 
812
1323
  /** A scatterplot of two or more columns. */
813
1324
  export declare interface ScatterPlotSpec extends PlotBase {
@@ -820,6 +1331,26 @@ export declare interface ScatterPlotSpec extends PlotBase {
820
1331
  transform?: PlotTransformSpec;
821
1332
  }
822
1333
 
1334
+ /**
1335
+ * Saves the rows of a SQL query over the workspace's tables as a new table. Read by the Autark adapter only.
1336
+ */
1337
+ export declare interface SqlSourceSpec extends TableSourceBase {
1338
+ type: 'sql';
1339
+ /**
1340
+ * A `SELECT`, or a `WITH` query that ends in one, in DuckDB's SQL, over the tables of the source's workspace by their
1341
+ * names. autk-db refuses any other statement, and any query in which `insert`, `update`, `delete`, `create`,
1342
+ * `alter`, `drop`, `truncate` or `replace` appears as a word, even inside a string.
1343
+ * @minLength 1
1344
+ */
1345
+ query: string;
1346
+ /**
1347
+ * How a map draws the new table, whose geometry must then be in a column named `geometry`, in the workspace's CRS,
1348
+ * as the workspace's tables hold it. Without it, the table has no layer type: a plot draws its rows, while a map
1349
+ * does not draw it and `AutkGrammar.data` does not list it.
1350
+ */
1351
+ layerType?: LayerType;
1352
+ }
1353
+
823
1354
  /**
824
1355
  * The storage buffer binding every WebGPU device supports: the default
825
1356
  * `maxStorageBufferBindingSize`, 128 MiB. autk-compute 4 reads each array a `batched` directive
@@ -828,6 +1359,13 @@ export declare interface ScatterPlotSpec extends PlotBase {
828
1359
  */
829
1360
  export declare const STORAGE_BUFFER_BINDING_SIZE = 134217728;
830
1361
 
1362
+ /**
1363
+ * The key a table has in the grammar's caches: its name in the default workspace, `<workspace>/<name>` in another, so
1364
+ * two workspaces can hold tables of the same name. A host reads the caches it passes to `createDataAdapter` and
1365
+ * `createComputeAdapter` with it.
1366
+ */
1367
+ export declare function tableKey(workspace: string | undefined, name: string): string;
1368
+
831
1369
  /** A table. A transform, when given, must be `sort`. */
832
1370
  export declare interface TablePlotSpec extends PlotBase {
833
1371
  mark: 'table';
@@ -840,6 +1378,8 @@ export declare interface TablePlotSpec extends PlotBase {
840
1378
  export declare interface TableSourceBase {
841
1379
  /** Name of the table this source creates. Later sources, compute passes, maps and plots refer to it by this name. */
842
1380
  outputTableName: string;
1381
+ /** Workspace the table is created in. */
1382
+ workspace?: WorkspaceName;
843
1383
  }
844
1384
 
845
1385
  /**
@@ -851,21 +1391,73 @@ export declare type TableSourceSpec = TableSourceBase & {
851
1391
  type: DataSourceType;
852
1392
  };
853
1393
 
1394
+ /** The elements of the page `AutkGrammar` draws in, by id. */
854
1395
  export declare type Targets = {
1396
+ /** Not read by the adapter. */
855
1397
  compute?: string;
1398
+ /** Id of an element that lists the loaded tables after each data source. */
856
1399
  db?: string;
1400
+ /** Id of the canvas a map draws on, or a list of ids, one canvas per entry of `map`, in order. */
857
1401
  map?: string[] | string;
858
- plot?: string;
1402
+ /**
1403
+ * Id of the element the plots draw in, or a list of ids, one element per entry of `plot`, in order. With one id,
1404
+ * every plot draws in that element.
1405
+ */
1406
+ plot?: string[] | string;
859
1407
  };
860
1408
 
861
1409
  declare type UniformEntry = number | FromFeatureDirective;
862
1410
 
1411
+ /**
1412
+ * Replaces or changes the rows of a table already loaded, with rows given inline: a FeatureCollection for a table with
1413
+ * a geometry, an array of objects for a table without one. Read by the Autark adapter only.
1414
+ * @if { "required": ["geojsonObject"] }
1415
+ * @then { "not": { "required": ["jsonObject"] }, "if": { "required": ["strategy"], "properties": { "strategy": { "const": "update" } } }, "then": { "required": ["idColumn"] } }
1416
+ * @else { "required": ["jsonObject"], "if": { "required": ["strategy"], "properties": { "strategy": { "const": "update" } } }, "then": { "required": ["idColumn"] } }
1417
+ */
1418
+ export declare interface UpdateSourceSpec {
1419
+ type: 'update';
1420
+ /** Workspace of the table. */
1421
+ workspace?: WorkspaceName;
1422
+ /** The table to change. */
1423
+ dataRef: string;
1424
+ /**
1425
+ * `replace` swaps every row of the table for the given rows. `update` changes the rows whose `idColumn` value a
1426
+ * given row has: in a table with a geometry, each takes the given row's geometry and properties, and no row is
1427
+ * added; in a table without one, the given rows replace them, and those that match no row are added.
1428
+ */
1429
+ strategy: 'replace' | 'update';
1430
+ /**
1431
+ * With `update`, the column that matches a given row to the table's rows: a column such as `month`, or a feature
1432
+ * property as `properties.<name>`, such as `properties.parcel_id`.
1433
+ * @minLength 1
1434
+ */
1435
+ idColumn?: string;
1436
+ /**
1437
+ * The rows of a table with a geometry. autk-db stores their coordinates as they come, so they are in the
1438
+ * workspace's CRS, as `AutkGrammar.data` gives a table's features.
1439
+ */
1440
+ geojsonObject?: InlineFeatureCollection;
1441
+ /**
1442
+ * The rows of a table without a geometry, such as a CSV or JSON table loaded without `geometryColumns`.
1443
+ * @minItems 1
1444
+ */
1445
+ jsonObject?: Array<Record<string, unknown>>;
1446
+ }
1447
+
863
1448
  /**
864
1449
  * An Autark grammar specification. It names at least one of `data`, `compute`, `map` or `plot`.
865
1450
  */
866
1451
  export declare type UrbanSpec = {
867
1452
  /** URL of the JSON Schema this specification follows. */
868
1453
  $schema?: string;
1454
+ /** How the host arranges the maps and plots. */
1455
+ layout?: LayoutSpec;
1456
+ /**
1457
+ * How workspaces store their tables, one entry per workspace, set before the first source loads. A workspace
1458
+ * without an entry keeps autk-db's CRS and grid. Read by the Autark adapter only.
1459
+ */
1460
+ workspaces?: WorkspaceSpec[];
869
1461
  /** Tables to load, in order. */
870
1462
  data?: DataSourceSpec[];
871
1463
  /** Compute passes, run in order after the data is loaded. */
@@ -874,6 +1466,51 @@ export declare type UrbanSpec = {
874
1466
  map?: MapSpec[] | MapSpec;
875
1467
  /** One plot, or several. */
876
1468
  plot?: PlotSpec[] | PlotSpec;
1469
+ /** Links between plots and map layers. The engine does not read them; the adapter wires them once the maps and plots exist. */
1470
+ links?: LinkSpec[];
1471
+ };
1472
+
1473
+ /** How the views of a spec are arranged on the page: a grid of `rows` by `columns` panes, `gap` pixels apart. */
1474
+ export declare type ViewArrangement = {
1475
+ /**
1476
+ * `vertical` stacks the panes, `horizontal` puts them side by side, and `grid` fills `columns` columns, row by row:
1477
+ * the spec's `layout.type`, else `vertical`.
1478
+ */
1479
+ type: 'vertical' | 'horizontal' | 'grid';
1480
+ /** The rows of panes. */
1481
+ rows: number;
1482
+ /** The columns of panes: 1 when `vertical`, one per view when `horizontal`, and `layout.columns`, else 2, for a `grid`. */
1483
+ columns: number;
1484
+ /** The space between neighboring panes, in pixels: the spec's `layout.gap`, else 0. */
1485
+ gap: number;
1486
+ /**
1487
+ * One pane per view, in the order the grammar draws them: the maps in the order of `map`, then the plots in the
1488
+ * order of `plot`.
1489
+ */
1490
+ panes: ViewPane[];
1491
+ };
1492
+
1493
+ /** A view's pane, as {@link arrangeViews} places it. */
1494
+ export declare type ViewPane = {
1495
+ /** `map` or `plot`. It is also the key of the adapter's targets whose list names the element the view draws in. */
1496
+ kind: 'map' | 'plot';
1497
+ /**
1498
+ * The view's position among the views of its kind, in the spec's order: its element is entry `index` of the `map`
1499
+ * or `plot` target list.
1500
+ */
1501
+ index: number;
1502
+ /** The view's `id`, when it has one. */
1503
+ id?: string;
1504
+ /**
1505
+ * 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
1506
+ * `mapId` of its `map:picking` events, and a plot's the `plotId` of its `plot:selection` events; the calls that
1507
+ * address one map or plot take it.
1508
+ */
1509
+ key: string | number;
1510
+ /** The pane's row in the arrangement, from 0 at the top. */
1511
+ row: number;
1512
+ /** The pane's column in the arrangement, from 0 at the left. */
1513
+ column: number;
877
1514
  };
878
1515
 
879
1516
  /**
@@ -885,4 +1522,35 @@ export declare type WktGeometryColumns = {
885
1522
  coordinateFormat?: string;
886
1523
  };
887
1524
 
1525
+ /**
1526
+ * Name of a workspace: an isolated set of tables with its own extent. The first source loaded into a workspace sets its
1527
+ * extent and later sources are cut to it, so two areas that must not clip each other go in two workspaces. A table is
1528
+ * found by its name inside its workspace, so two workspaces may hold tables of the same name. Entries without a
1529
+ * workspace use the default one. Read by the Autark adapter only.
1530
+ * @minLength 1
1531
+ */
1532
+ export declare type WorkspaceName = string;
1533
+
1534
+ /**
1535
+ * How a workspace stores its tables: the coordinate system they are kept in, and the grid their coordinates are rounded
1536
+ * to. Read by the Autark adapter only.
1537
+ */
1538
+ export declare type WorkspaceSpec = {
1539
+ /** The workspace, by the name sources, compute passes, maps and plots give as their `workspace`. Without it, the default workspace. */
1540
+ name?: WorkspaceName;
1541
+ /**
1542
+ * CRS the workspace stores its tables in, as an EPSG string such as `'EPSG:3857'`. Each source is transformed to
1543
+ * it as it loads, its maps draw in its units, and so are the lengths given in workspace units, such as a join's
1544
+ * `near.distance`. autk-db's default is `'EPSG:3395'`, World Mercator, in meters.
1545
+ * @minLength 1
1546
+ */
1547
+ coordinateFormat: string;
1548
+ /**
1549
+ * Grid every stored coordinate is rounded to, in the CRS's units. autk-db's default is `0.01`, a centimeter in World
1550
+ * Mercator. A geometry the grid collapses is refused as it loads.
1551
+ * @exclusiveMinimum 0
1552
+ */
1553
+ precisionGrid: number;
1554
+ };
1555
+
888
1556
  export { }