@urban-toolkit/autk-grammar 4.1.1 → 4.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -12,7 +12,7 @@ A declarative grammar for urban visual analytics, running on [Autark](https://au
12
12
  npm install @urban-toolkit/autk-grammar
13
13
  ```
14
14
 
15
- It runs on Autark 4.1: `@urban-toolkit/autk-core`, `autk-db`, `autk-map`, `autk-plot` and `autk-compute` 4.1 or a later 4.x, installed with it.
15
+ It runs on Autark 4.1.1: `@urban-toolkit/autk-core`, `autk-db`, `autk-map`, `autk-plot` and `autk-compute` 4.1.1 or a later 4.x, installed with it.
16
16
 
17
17
  ## Usage
18
18
 
@@ -29,6 +29,30 @@ const grammar = new AutkGrammar({ map: 'map', plot: 'plot' }); // ids of the map
29
29
  await grammar.run(spec);
30
30
  ```
31
31
 
32
+ ## OpenStreetMap areas
33
+
34
+ An `osm` source's `queryArea` names the area to load in one of two ways, never both:
35
+
36
+ | Area | Effect |
37
+ |---|---|
38
+ | `{ geocodeArea, areas }` | The boundaries named in `areas` inside the region `geocodeArea`, for example `{ geocodeArea: 'Chicago', areas: ['Loop'] }`. |
39
+ | `{ bbox }` | A box, `[west, south, east, north]` in degrees (WGS84). The box is the whole area: no boundary is read. Each layer is cut to the box, except buildings, which are kept or dropped whole. |
40
+
41
+ A box needs west less than east and south less than north, and cannot cross the antimeridian. The run refuses any other box, and a `queryArea` with both, with a message that names the source.
42
+
43
+ ```ts
44
+ await grammar.run({
45
+ data: [{
46
+ type: 'osm',
47
+ outputTableName: 'downtown',
48
+ pbfFileUrl: 'chicago_downtown.osm.pbf',
49
+ queryArea: { bbox: [-87.66415, 41.858, -87.61232, 41.89966] },
50
+ autoLoadLayers: { layers: ['roads', 'buildings'] },
51
+ }],
52
+ map: { layerRefs: [{ dataRef: 'downtown_roads' }, { dataRef: 'downtown_buildings' }] },
53
+ });
54
+ ```
55
+
32
56
  ## Maps
33
57
 
34
58
  Each map draws on demand: one frame once its layers are loaded, then one each time it changes. `grammar.maps` holds the `AutkMap` of each `map` entry of the last run, in order. Between frames a map canvas can read back empty, so to read a map's pixels (for example with `canvas.toDataURL()`), call its `requestRender()` and read in a `requestAnimationFrame` callback registered after that call:
@@ -41,6 +65,38 @@ requestAnimationFrame(() => {
41
65
  });
42
66
  ```
43
67
 
68
+ ## Layer styling
69
+
70
+ Besides `dataRef`, a layer of `map.layerRefs` takes these styling options:
71
+
72
+ | Option | Effect |
73
+ |---|---|
74
+ | `title` | The layer's id in its map, which its legend shows as its title. Without a title, the id is the `dataRef`. Two layers of one map cannot have the same id. |
75
+ | `color` | The layer's color, `#rrggbb`. The layer is drawn in it rather than by its `getFnv` value, unless `isColorMap` is `true`. |
76
+ | `stroke` | A polygon layer's outline: its color, `#rrggbb`, or `false` for none. |
77
+ | `width` | The width of a polylines or roads layer's lines, in the map's planar units (autk-map's `polylinesWidth`). |
78
+ | `colorMapInterpolator` | The color scheme. A raster layer's cells and its legend's labels follow it. |
79
+ | `colorMapCenter` | On a raster layer, the value at the middle of the color scale. The scale then runs from the center less the farthest value's distance to it, to the center plus that distance. |
80
+ | `colorMapReverse` | On a raster layer, runs the color scale from the highest value to the lowest. |
81
+ | `transferFunction` | On a raster layer, how opaque its cells are by value: autk-map's transfer function (`mode`, `opacityMin`, `opacityMax`, `gamma`, `zeroCenter`). `{ opacityMin: 1, opacityMax: 1 }` draws every cell with a value fully opaque. |
82
+
83
+ After a run, `grammar.mapLayer(dataRef)` finds the layer a map draws for a table: the `AutkMap` and the layer's id in it. `highlightOnMap`, `clearHighlightOnMap` and a plot's `mapRef` also name a layer by its `dataRef`.
84
+
85
+ ```ts
86
+ await grammar.run({
87
+ data: [/* tables named routes and parcels, and a heatmap raster named change */],
88
+ map: {
89
+ layerRefs: [
90
+ { dataRef: 'parcels', color: '#4e79a7', stroke: false },
91
+ { dataRef: 'routes', title: 'Fastest route', color: '#e15759', width: 30 },
92
+ { dataRef: 'change', title: 'Change', colorMapInterpolator: ColorMapInterpolator.DIV_RED_BLUE, colorMapCenter: 0, colorMapReverse: true },
93
+ ],
94
+ },
95
+ });
96
+ const { map, layerId } = grammar.mapLayer('routes')!; // layerId is 'Fastest route'
97
+ map.updateRenderInfo(layerId, { opacity: 0.5 });
98
+ ```
99
+
44
100
  ## Interactions
45
101
 
46
102
  A layer with `isPick` and a plot with `events` report what the user selects on `grammar.interactions`: `map:picking` and `plot:selection` give feature ids, the positions of the selected features among those the layer or the plot draws (a map layer leaves out features without a geometry). To link a selection to other tables, name the columns whose values identify those rows with `selectFields` on the layer or the plot, for example `selectFields: ['nta2020']`. The grammar does not read it; the events still report feature ids, and the app reads the key values from those rows.
@@ -66,7 +66,7 @@
66
66
  "type": "number"
67
67
  },
68
68
  "mapRef": {
69
- "description": "Layer id of a map this plot links its selection to.",
69
+ "description": "`dataRef` of the map layer this plot links its selection to.",
70
70
  "type": "string"
71
71
  },
72
72
  "margins": {
@@ -903,7 +903,7 @@
903
903
  "type": "number"
904
904
  },
905
905
  "mapRef": {
906
- "description": "Layer id of a map this plot links its selection to.",
906
+ "description": "`dataRef` of the map layer this plot links its selection to.",
907
907
  "type": "string"
908
908
  },
909
909
  "margins": {
@@ -959,6 +959,11 @@
959
959
  ],
960
960
  "type": "object"
961
961
  },
962
+ "HexColor": {
963
+ "description": "A color as `#rrggbb`.",
964
+ "pattern": "^#[0-9a-fA-F]{6}$",
965
+ "type": "string"
966
+ },
962
967
  "InlineFeature": {
963
968
  "description": "A GeoJSON feature as the loader accepts it: `geometry` may be null and `properties` may be omitted.",
964
969
  "properties": {
@@ -1187,7 +1192,7 @@
1187
1192
  "type": "number"
1188
1193
  },
1189
1194
  "mapRef": {
1190
- "description": "Layer id of a map this plot links its selection to.",
1195
+ "description": "`dataRef` of the map layer this plot links its selection to.",
1191
1196
  "type": "string"
1192
1197
  },
1193
1198
  "margins": {
@@ -1277,6 +1282,14 @@
1277
1282
  "catchAllCategory": {
1278
1283
  "type": "string"
1279
1284
  },
1285
+ "color": {
1286
+ "$ref": "#/definitions/HexColor",
1287
+ "description": "Color of the layer, as `#rrggbb`. A layer with a color is drawn in it rather than by its `getFnv` value, unless `isColorMap` is `true`. Raster layers are always colored by value. Read by the Autark adapter; the deck.gl adapter ignores it."
1288
+ },
1289
+ "colorMapCenter": {
1290
+ "description": "Value at the middle of a raster layer's color scale: the scale runs from this value less the farthest value's distance to it, to this value plus that distance, so a diverging scheme's middle color marks it. Read by the Autark adapter for raster layers; other layers and the deck.gl adapter ignore it.",
1291
+ "type": "number"
1292
+ },
1280
1293
  "colorMapDomain": {
1281
1294
  "description": "Allowed category values; anything else is drawn as the catch-all category. Only used when `getFnvType` is `categorical`.",
1282
1295
  "items": {
@@ -1295,6 +1308,10 @@
1295
1308
  },
1296
1309
  "type": "array"
1297
1310
  },
1311
+ "colorMapReverse": {
1312
+ "description": "Run a raster layer's color scale from its highest value to its lowest, so the scheme's first color marks the highest value. Read by the Autark adapter for raster layers; other layers and the deck.gl adapter ignore it.",
1313
+ "type": "boolean"
1314
+ },
1298
1315
  "dataRef": {
1299
1316
  "description": "Name of the table to draw, as produced by a data source or a compute pass.",
1300
1317
  "type": "string"
@@ -1366,6 +1383,32 @@
1366
1383
  },
1367
1384
  "minItems": 1,
1368
1385
  "type": "array"
1386
+ },
1387
+ "stroke": {
1388
+ "anyOf": [
1389
+ {
1390
+ "$ref": "#/definitions/HexColor"
1391
+ },
1392
+ {
1393
+ "const": false,
1394
+ "type": "boolean"
1395
+ }
1396
+ ],
1397
+ "description": "Outline of a polygon layer: its color, as `#rrggbb`, or `false` to draw no outline. Read by the Autark adapter, which outlines polygon layers only; the deck.gl adapter ignores it."
1398
+ },
1399
+ "title": {
1400
+ "description": "Name of the layer, shown as its legend's title. It becomes the layer's id in the map, so two layers of one map cannot have the same title, and a title cannot be another layer's `dataRef` in that map. Without it, the layer's id is its `dataRef`. Read by the Autark adapter; the deck.gl adapter ignores it.",
1401
+ "minLength": 1,
1402
+ "type": "string"
1403
+ },
1404
+ "transferFunction": {
1405
+ "$ref": "#/definitions/RasterTransferFunction",
1406
+ "description": "How opaque a raster layer's cells are by value, as autk-map's transfer function: for example `{ opacityMin: 1, opacityMax: 1 }` draws every cell with a value fully opaque. Read by the Autark adapter for raster layers; other layers and the deck.gl adapter ignore it."
1407
+ },
1408
+ "width": {
1409
+ "description": "Width of the lines of a polylines or roads layer, in the map's planar units (about meters). It replaces the widths a roads layer gives each kind of road. Read by the Autark adapter; the deck.gl adapter ignores it.",
1410
+ "exclusiveMinimum": 0,
1411
+ "type": "number"
1369
1412
  }
1370
1413
  },
1371
1414
  "required": [
@@ -1485,8 +1528,61 @@
1485
1528
  ],
1486
1529
  "type": "string"
1487
1530
  },
1531
+ "OsmBoundingBoxArea": {
1532
+ "description": "An area given as a box instead of boundary names. The box is the whole area: no boundary is read.",
1533
+ "properties": {
1534
+ "areas": {
1535
+ "description": "Not with `bbox`.",
1536
+ "not": {}
1537
+ },
1538
+ "bbox": {
1539
+ "description": "The box as `[west, south, east, north]` in degrees (WGS84), with west less than east and south less than north. A box across the antimeridian is not supported. The Autark adapter cuts each layer to the box, but keeps or drops each building whole.",
1540
+ "items": [
1541
+ {
1542
+ "description": "A longitude in degrees (WGS84).",
1543
+ "maximum": 180,
1544
+ "minimum": -180,
1545
+ "title": "west",
1546
+ "type": "number"
1547
+ },
1548
+ {
1549
+ "description": "A latitude in degrees (WGS84).",
1550
+ "maximum": 90,
1551
+ "minimum": -90,
1552
+ "title": "south",
1553
+ "type": "number"
1554
+ },
1555
+ {
1556
+ "description": "A longitude in degrees (WGS84).",
1557
+ "maximum": 180,
1558
+ "minimum": -180,
1559
+ "title": "east",
1560
+ "type": "number"
1561
+ },
1562
+ {
1563
+ "description": "A latitude in degrees (WGS84).",
1564
+ "maximum": 90,
1565
+ "minimum": -90,
1566
+ "title": "north",
1567
+ "type": "number"
1568
+ }
1569
+ ],
1570
+ "maxItems": 4,
1571
+ "minItems": 4,
1572
+ "type": "array"
1573
+ },
1574
+ "geocodeArea": {
1575
+ "description": "Not with `bbox`.",
1576
+ "not": {}
1577
+ }
1578
+ },
1579
+ "required": [
1580
+ "bbox"
1581
+ ],
1582
+ "type": "object"
1583
+ },
1488
1584
  "OsmDataSourceSpec": {
1489
- "description": "Loads OpenStreetMap data for a named area, from Overpass or from a PBF extract.",
1585
+ "description": "Loads OpenStreetMap data for a named area or a box, from Overpass or from a PBF extract.",
1490
1586
  "properties": {
1491
1587
  "autoLoadLayers": {
1492
1588
  "description": "Split the raw OSM table into one table per layer, named `<outputTableName>_<layer>`.",
@@ -1516,25 +1612,15 @@
1516
1612
  "type": "string"
1517
1613
  },
1518
1614
  "queryArea": {
1519
- "description": "Area to load: the named sub-areas inside a geocoded region.",
1520
- "properties": {
1521
- "areas": {
1522
- "description": "Sub-areas inside the region, for example neighborhood names.",
1523
- "items": {
1524
- "type": "string"
1525
- },
1526
- "type": "array"
1615
+ "anyOf": [
1616
+ {
1617
+ "$ref": "#/definitions/OsmNamedArea"
1527
1618
  },
1528
- "geocodeArea": {
1529
- "description": "Region to geocode, for example a city name.",
1530
- "type": "string"
1619
+ {
1620
+ "$ref": "#/definitions/OsmBoundingBoxArea"
1531
1621
  }
1532
- },
1533
- "required": [
1534
- "geocodeArea",
1535
- "areas"
1536
1622
  ],
1537
- "type": "object"
1623
+ "description": "Area to load: sub-areas inside a geocoded region (`geocodeArea` with `areas`), or a box (`bbox`), not both."
1538
1624
  },
1539
1625
  "type": {
1540
1626
  "const": "osm",
@@ -1548,6 +1634,31 @@
1548
1634
  ],
1549
1635
  "type": "object"
1550
1636
  },
1637
+ "OsmNamedArea": {
1638
+ "description": "An area named by OpenStreetMap boundaries: sub-areas inside a geocoded region.",
1639
+ "properties": {
1640
+ "areas": {
1641
+ "description": "Sub-areas inside the region, for example neighborhood names.",
1642
+ "items": {
1643
+ "type": "string"
1644
+ },
1645
+ "type": "array"
1646
+ },
1647
+ "bbox": {
1648
+ "description": "Not with `geocodeArea` and `areas`.",
1649
+ "not": {}
1650
+ },
1651
+ "geocodeArea": {
1652
+ "description": "Region to geocode, for example a city name.",
1653
+ "type": "string"
1654
+ }
1655
+ },
1656
+ "required": [
1657
+ "geocodeArea",
1658
+ "areas"
1659
+ ],
1660
+ "type": "object"
1661
+ },
1551
1662
  "ParallelCoordinatesPlotSpec": {
1552
1663
  "description": "Parallel coordinates over the plotted columns.",
1553
1664
  "properties": {
@@ -1577,7 +1688,7 @@
1577
1688
  "type": "number"
1578
1689
  },
1579
1690
  "mapRef": {
1580
- "description": "Layer id of a map this plot links its selection to.",
1691
+ "description": "`dataRef` of the map layer this plot links its selection to.",
1581
1692
  "type": "string"
1582
1693
  },
1583
1694
  "margins": {
@@ -1900,6 +2011,42 @@
1900
2011
  },
1901
2012
  "type": "array"
1902
2013
  },
2014
+ "RasterTransferFunction": {
2015
+ "description": "How opaque a raster layer's cells are by value: autk-map's transfer function. A cell with no value is clear.",
2016
+ "properties": {
2017
+ "gamma": {
2018
+ "description": "Exponent applied to a cell's place between the lowest and highest opacity. Defaults to 1.",
2019
+ "exclusiveMinimum": 0,
2020
+ "type": "number"
2021
+ },
2022
+ "mode": {
2023
+ "description": "`far-zero`: cells farther from `zeroCenter` are more opaque (autk-map's default). `near-zero`: cells closer to `zeroCenter` are more opaque. `linear`: opacity grows from the lowest value to the highest.",
2024
+ "enum": [
2025
+ "near-zero",
2026
+ "far-zero",
2027
+ "linear"
2028
+ ],
2029
+ "type": "string"
2030
+ },
2031
+ "opacityMax": {
2032
+ "description": "Highest opacity, from 0 to 1. Defaults to 1.",
2033
+ "maximum": 1,
2034
+ "minimum": 0,
2035
+ "type": "number"
2036
+ },
2037
+ "opacityMin": {
2038
+ "description": "Lowest opacity, from 0 to 1. Defaults to 0.",
2039
+ "maximum": 1,
2040
+ "minimum": 0,
2041
+ "type": "number"
2042
+ },
2043
+ "zeroCenter": {
2044
+ "description": "Value the `far-zero` and `near-zero` modes measure from. Defaults to 0.",
2045
+ "type": "number"
2046
+ }
2047
+ },
2048
+ "type": "object"
2049
+ },
1903
2050
  "ScatterPlotSpec": {
1904
2051
  "description": "A scatterplot of two or more columns.",
1905
2052
  "properties": {
@@ -1929,7 +2076,7 @@
1929
2076
  "type": "number"
1930
2077
  },
1931
2078
  "mapRef": {
1932
- "description": "Layer id of a map this plot links its selection to.",
2079
+ "description": "`dataRef` of the map layer this plot links its selection to.",
1933
2080
  "type": "string"
1934
2081
  },
1935
2082
  "margins": {
@@ -2013,7 +2160,7 @@
2013
2160
  "type": "number"
2014
2161
  },
2015
2162
  "mapRef": {
2016
- "description": "Layer id of a map this plot links its selection to.",
2163
+ "description": "`dataRef` of the map layer this plot links its selection to.",
2017
2164
  "type": "string"
2018
2165
  },
2019
2166
  "margins": {