@urban-toolkit/autk-grammar 5.0.0 → 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/README.md +156 -7
- package/build/autk-grammar-schema.json +345 -3
- package/dist/autk-grammar.js +550 -434
- package/dist/autk-grammar.js.map +1 -1
- package/dist/autk-grammar.umd.cjs +2 -2
- package/dist/autk-grammar.umd.cjs.map +1 -1
- package/dist/data/autk-grammar-data.cjs +1 -1
- package/dist/data/autk-grammar-data.cjs.map +1 -1
- package/dist/data/autk-grammar-data.d.ts +172 -5
- package/dist/data/autk-grammar-data.js +213 -113
- package/dist/data/autk-grammar-data.js.map +1 -1
- package/dist/index.d.ts +198 -10
- package/package.json +1 -1
package/dist/index.d.ts
CHANGED
|
@@ -13,7 +13,7 @@ export declare type AggregateFunction = 'sum' | 'avg' | 'count' | 'min' | 'max'
|
|
|
13
13
|
|
|
14
14
|
/**
|
|
15
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.
|
|
16
|
+
* so the map redraws without a request. It refuses a pitch that is not at least 0 and less than 90 degrees.
|
|
17
17
|
*
|
|
18
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
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.
|
|
@@ -59,7 +59,8 @@ export declare class AutkGrammar {
|
|
|
59
59
|
readonly interactions: GrammarEventEmitter;
|
|
60
60
|
constructor(targets?: Targets);
|
|
61
61
|
/**
|
|
62
|
-
* The coordinate reference system
|
|
62
|
+
* The coordinate reference system autk-db stores a workspace's tables in, unless the spec's `workspaces` sets
|
|
63
|
+
* another for it.
|
|
63
64
|
*
|
|
64
65
|
* Input data is expected in EPSG:4326 (WGS84) by default and is transformed
|
|
65
66
|
* to this CRS on load. Consumers that prepare data for injection (e.g. by
|
|
@@ -209,9 +210,10 @@ export declare type CameraSpec = {
|
|
|
209
210
|
*/
|
|
210
211
|
zoom?: number;
|
|
211
212
|
/**
|
|
212
|
-
* Tilt from straight down, in degrees
|
|
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.
|
|
213
215
|
* @minimum 0
|
|
214
|
-
* @
|
|
216
|
+
* @exclusiveMaximum 90
|
|
215
217
|
*/
|
|
216
218
|
pitch?: number;
|
|
217
219
|
/**
|
|
@@ -323,14 +325,15 @@ export declare function createComputeAdapter(cache?: ComputeCache, types?: Compu
|
|
|
323
325
|
/**
|
|
324
326
|
* The data adapter `AutkGrammar` runs. Its `resolveSource(db, source)` loads one entry of a spec's `data` into the
|
|
325
327
|
* 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.
|
|
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.
|
|
327
330
|
*
|
|
328
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
|
|
329
332
|
* `./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}.
|
|
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.
|
|
332
335
|
*/
|
|
333
|
-
export declare function createDataAdapter(targets?: Targets, cache?: GeoJsonCache): DataAdapter
|
|
336
|
+
export declare function createDataAdapter(targets?: Targets, cache?: GeoJsonCache): Required<DataAdapter>;
|
|
334
337
|
|
|
335
338
|
export declare function createEngine(options: EngineOptions): IEngine;
|
|
336
339
|
|
|
@@ -388,16 +391,33 @@ export declare interface CustomDataSourceSpec extends TableSourceBase {
|
|
|
388
391
|
|
|
389
392
|
export declare interface DataAdapter {
|
|
390
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>;
|
|
391
399
|
}
|
|
392
400
|
|
|
393
401
|
/**
|
|
394
402
|
* One entry of `data`. The `type` field selects which fields apply.
|
|
395
403
|
* @discriminator type
|
|
396
404
|
*/
|
|
397
|
-
export declare type DataSourceSpec = OsmDataSourceSpec | CsvDataSourceSpec | JsonDataSourceSpec | CustomDataSourceSpec | GeoTiffDataSourceSpec | HeatmapSourceSpec | JoinSourceSpec;
|
|
405
|
+
export declare type DataSourceSpec = OsmDataSourceSpec | CsvDataSourceSpec | JsonDataSourceSpec | CustomDataSourceSpec | GeoTiffDataSourceSpec | HeatmapSourceSpec | JoinSourceSpec | SqlSourceSpec | UpdateSourceSpec | DropSourceSpec;
|
|
398
406
|
|
|
399
407
|
/** Kind of data source; selects which fields a `data` entry takes. */
|
|
400
|
-
export declare type DataSourceType = 'osm' | 'csv' | 'json' | 'geojson' | 'geotiff' | '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
|
+
}
|
|
401
421
|
|
|
402
422
|
export declare type EngineOptions = {
|
|
403
423
|
spec: UrbanSpec;
|
|
@@ -589,6 +609,12 @@ export declare interface HeatmapSourceSpec extends TableSourceBase {
|
|
|
589
609
|
column: string;
|
|
590
610
|
/** How the rows combine into the cell's value: any aggregate but `collect`, which lists rows, while a cell holds one value. */
|
|
591
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;
|
|
592
618
|
}>;
|
|
593
619
|
/** Grid resolution. */
|
|
594
620
|
grid: {
|
|
@@ -877,6 +903,13 @@ export declare type MapLayerSpec = {
|
|
|
877
903
|
* @minItems 1
|
|
878
904
|
*/
|
|
879
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;
|
|
880
913
|
/** Dot path to the thematic value, relative to `feature.properties` (for example `tags.highway` or `compute.result`). */
|
|
881
914
|
getFnv?: string;
|
|
882
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. */
|
|
@@ -943,15 +976,36 @@ export declare interface OsmBoundingBoxArea {
|
|
|
943
976
|
|
|
944
977
|
/**
|
|
945
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 } } } }
|
|
946
981
|
*/
|
|
947
982
|
export declare interface OsmDataSourceSpec extends TableSourceBase {
|
|
948
983
|
type: 'osm';
|
|
949
984
|
/** URL of a local or remote `.osm.pbf` extract to read instead of querying Overpass. */
|
|
950
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;
|
|
951
999
|
/** Split the raw OSM table into one table per layer, named `<outputTableName>_<layer>`. */
|
|
952
1000
|
autoLoadLayers?: {
|
|
953
1001
|
/** Currently ignored by both adapters. */
|
|
954
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;
|
|
955
1009
|
layers: Array<LayerType>;
|
|
956
1010
|
};
|
|
957
1011
|
/** Area to load: sub-areas inside a geocoded region (`geocodeArea` with `areas`), or a box (`bbox`), not both. */
|
|
@@ -970,6 +1024,49 @@ export declare interface OsmNamedArea {
|
|
|
970
1024
|
bbox?: undefined;
|
|
971
1025
|
}
|
|
972
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
|
+
|
|
973
1070
|
/** Parallel coordinates over the plotted columns. */
|
|
974
1071
|
export declare interface ParallelCoordinatesPlotSpec extends PlotBase {
|
|
975
1072
|
mark: 'parallel-coordinates';
|
|
@@ -1025,6 +1122,13 @@ export declare interface PlotBase {
|
|
|
1025
1122
|
};
|
|
1026
1123
|
/** `dataRef` of the map layer this plot links its selection to. A shorthand for a link in `links`. */
|
|
1027
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;
|
|
1028
1132
|
}
|
|
1029
1133
|
|
|
1030
1134
|
/** Interaction a plot emits. */
|
|
@@ -1227,6 +1331,26 @@ export declare interface ScatterPlotSpec extends PlotBase {
|
|
|
1227
1331
|
transform?: PlotTransformSpec;
|
|
1228
1332
|
}
|
|
1229
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
|
+
|
|
1230
1354
|
/**
|
|
1231
1355
|
* The storage buffer binding every WebGPU device supports: the default
|
|
1232
1356
|
* `maxStorageBufferBindingSize`, 128 MiB. autk-compute 4 reads each array a `batched` directive
|
|
@@ -1284,6 +1408,43 @@ export declare type Targets = {
|
|
|
1284
1408
|
|
|
1285
1409
|
declare type UniformEntry = number | FromFeatureDirective;
|
|
1286
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
|
+
|
|
1287
1448
|
/**
|
|
1288
1449
|
* An Autark grammar specification. It names at least one of `data`, `compute`, `map` or `plot`.
|
|
1289
1450
|
*/
|
|
@@ -1292,6 +1453,11 @@ export declare type UrbanSpec = {
|
|
|
1292
1453
|
$schema?: string;
|
|
1293
1454
|
/** How the host arranges the maps and plots. */
|
|
1294
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[];
|
|
1295
1461
|
/** Tables to load, in order. */
|
|
1296
1462
|
data?: DataSourceSpec[];
|
|
1297
1463
|
/** Compute passes, run in order after the data is loaded. */
|
|
@@ -1365,4 +1531,26 @@ export declare type WktGeometryColumns = {
|
|
|
1365
1531
|
*/
|
|
1366
1532
|
export declare type WorkspaceName = string;
|
|
1367
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
|
+
|
|
1368
1556
|
export { }
|