@urban-toolkit/autk-grammar 4.2.0 → 4.4.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:
@@ -52,8 +76,9 @@ Besides `dataRef`, a layer of `map.layerRefs` takes these styling options:
52
76
  | `stroke` | A polygon layer's outline: its color, `#rrggbb`, or `false` for none. |
53
77
  | `width` | The width of a polylines or roads layer's lines, in the map's planar units (autk-map's `polylinesWidth`). |
54
78
  | `colorMapInterpolator` | The color scheme. A raster layer's cells and its legend's labels follow it. |
55
- | `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. |
56
- | `colorMapReverse` | On a raster layer, runs the color scale from the highest value to the lowest. |
79
+ | `colorMapRange` | The ends of the color scale, `[low, high]` with low less than high. The layer is colored over this range instead of its own lowest and highest values, so layers that set the same range, in one map or in maps side by side, color the same value alike. Raster and vector layers. A categorical scheme ignores it, and a layer cannot set both `colorMapRange` and `colorMapDomain`. On a raster layer, a `transferFunction` still sets opacity from the layer's own values. |
80
+ | `colorMapCenter` | On a raster layer, the value at the middle of the color scale. With `colorMapRange`, the scale runs from the range's low through the center to its high (a sequential scheme keeps only the ends). Without it, the scale runs from the center less the farthest value's distance to it, to the center plus that distance. |
81
+ | `colorMapReverse` | On a raster layer, runs the color scale from the highest value to the lowest, or from `colorMapRange`'s high to its low. |
57
82
  | `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. |
58
83
 
59
84
  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`.
@@ -1278,6 +1278,11 @@
1278
1278
  },
1279
1279
  "MapLayerSpec": {
1280
1280
  "description": "One layer drawn by a map.",
1281
+ "if": {
1282
+ "required": [
1283
+ "colorMapRange"
1284
+ ]
1285
+ },
1281
1286
  "properties": {
1282
1287
  "catchAllCategory": {
1283
1288
  "type": "string"
@@ -1287,11 +1292,11 @@
1287
1292
  "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
1293
  },
1289
1294
  "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.",
1295
+ "description": "Value at the middle of a raster layer's color scale, so a diverging scheme's middle color marks it. With `colorMapRange`, the scale runs from the range's low through this value to its high (a sequential scheme keeps only the ends); without it, from this value less the farthest value's distance to it, to this value plus that distance. Read by the Autark adapter for raster layers; other layers and the deck.gl adapter ignore it.",
1291
1296
  "type": "number"
1292
1297
  },
1293
1298
  "colorMapDomain": {
1294
- "description": "Allowed category values; anything else is drawn as the catch-all category. Only used when `getFnvType` is `categorical`.",
1299
+ "description": "Allowed category values; anything else is drawn as the catch-all category. Only used when `getFnvType` is `categorical`. Not with `colorMapRange`.",
1295
1300
  "items": {
1296
1301
  "type": "string"
1297
1302
  },
@@ -1308,8 +1313,25 @@
1308
1313
  },
1309
1314
  "type": "array"
1310
1315
  },
1316
+ "colorMapRange": {
1317
+ "description": "Ends of the layer's color scale, as `[low, high]` with low less than high. The layer is colored over this range instead of its own lowest and highest values, so layers that set the same range color the same value alike, in one map or in maps side by side. On a raster layer, `colorMapCenter` and `colorMapReverse` apply within it, and a `transferFunction` still sets opacity from the layer's own values. A categorical scheme ignores it, and it cannot be set with `colorMapDomain`. Read by the Autark adapter for raster and vector layers; the deck.gl adapter ignores it.",
1318
+ "items": [
1319
+ {
1320
+ "title": "low",
1321
+ "type": "number"
1322
+ },
1323
+ {
1324
+ "title": "high",
1325
+ "type": "number"
1326
+ }
1327
+ ],
1328
+ "maxItems": 2,
1329
+ "minItems": 2,
1330
+ "type": "array",
1331
+ "uniqueItems": true
1332
+ },
1311
1333
  "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.",
1334
+ "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; with `colorMapRange`, from the range's high to its low. Read by the Autark adapter for raster layers; other layers and the deck.gl adapter ignore it.",
1313
1335
  "type": "boolean"
1314
1336
  },
1315
1337
  "dataRef": {
@@ -1414,6 +1436,13 @@
1414
1436
  "required": [
1415
1437
  "dataRef"
1416
1438
  ],
1439
+ "then": {
1440
+ "not": {
1441
+ "required": [
1442
+ "colorMapDomain"
1443
+ ]
1444
+ }
1445
+ },
1417
1446
  "type": "object"
1418
1447
  },
1419
1448
  "MapSpec": {
@@ -1528,8 +1557,61 @@
1528
1557
  ],
1529
1558
  "type": "string"
1530
1559
  },
1560
+ "OsmBoundingBoxArea": {
1561
+ "description": "An area given as a box instead of boundary names. The box is the whole area: no boundary is read.",
1562
+ "properties": {
1563
+ "areas": {
1564
+ "description": "Not with `bbox`.",
1565
+ "not": {}
1566
+ },
1567
+ "bbox": {
1568
+ "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.",
1569
+ "items": [
1570
+ {
1571
+ "description": "A longitude in degrees (WGS84).",
1572
+ "maximum": 180,
1573
+ "minimum": -180,
1574
+ "title": "west",
1575
+ "type": "number"
1576
+ },
1577
+ {
1578
+ "description": "A latitude in degrees (WGS84).",
1579
+ "maximum": 90,
1580
+ "minimum": -90,
1581
+ "title": "south",
1582
+ "type": "number"
1583
+ },
1584
+ {
1585
+ "description": "A longitude in degrees (WGS84).",
1586
+ "maximum": 180,
1587
+ "minimum": -180,
1588
+ "title": "east",
1589
+ "type": "number"
1590
+ },
1591
+ {
1592
+ "description": "A latitude in degrees (WGS84).",
1593
+ "maximum": 90,
1594
+ "minimum": -90,
1595
+ "title": "north",
1596
+ "type": "number"
1597
+ }
1598
+ ],
1599
+ "maxItems": 4,
1600
+ "minItems": 4,
1601
+ "type": "array"
1602
+ },
1603
+ "geocodeArea": {
1604
+ "description": "Not with `bbox`.",
1605
+ "not": {}
1606
+ }
1607
+ },
1608
+ "required": [
1609
+ "bbox"
1610
+ ],
1611
+ "type": "object"
1612
+ },
1531
1613
  "OsmDataSourceSpec": {
1532
- "description": "Loads OpenStreetMap data for a named area, from Overpass or from a PBF extract.",
1614
+ "description": "Loads OpenStreetMap data for a named area or a box, from Overpass or from a PBF extract.",
1533
1615
  "properties": {
1534
1616
  "autoLoadLayers": {
1535
1617
  "description": "Split the raw OSM table into one table per layer, named `<outputTableName>_<layer>`.",
@@ -1559,25 +1641,15 @@
1559
1641
  "type": "string"
1560
1642
  },
1561
1643
  "queryArea": {
1562
- "description": "Area to load: the named sub-areas inside a geocoded region.",
1563
- "properties": {
1564
- "areas": {
1565
- "description": "Sub-areas inside the region, for example neighborhood names.",
1566
- "items": {
1567
- "type": "string"
1568
- },
1569
- "type": "array"
1644
+ "anyOf": [
1645
+ {
1646
+ "$ref": "#/definitions/OsmNamedArea"
1570
1647
  },
1571
- "geocodeArea": {
1572
- "description": "Region to geocode, for example a city name.",
1573
- "type": "string"
1648
+ {
1649
+ "$ref": "#/definitions/OsmBoundingBoxArea"
1574
1650
  }
1575
- },
1576
- "required": [
1577
- "geocodeArea",
1578
- "areas"
1579
1651
  ],
1580
- "type": "object"
1652
+ "description": "Area to load: sub-areas inside a geocoded region (`geocodeArea` with `areas`), or a box (`bbox`), not both."
1581
1653
  },
1582
1654
  "type": {
1583
1655
  "const": "osm",
@@ -1591,6 +1663,31 @@
1591
1663
  ],
1592
1664
  "type": "object"
1593
1665
  },
1666
+ "OsmNamedArea": {
1667
+ "description": "An area named by OpenStreetMap boundaries: sub-areas inside a geocoded region.",
1668
+ "properties": {
1669
+ "areas": {
1670
+ "description": "Sub-areas inside the region, for example neighborhood names.",
1671
+ "items": {
1672
+ "type": "string"
1673
+ },
1674
+ "type": "array"
1675
+ },
1676
+ "bbox": {
1677
+ "description": "Not with `geocodeArea` and `areas`.",
1678
+ "not": {}
1679
+ },
1680
+ "geocodeArea": {
1681
+ "description": "Region to geocode, for example a city name.",
1682
+ "type": "string"
1683
+ }
1684
+ },
1685
+ "required": [
1686
+ "geocodeArea",
1687
+ "areas"
1688
+ ],
1689
+ "type": "object"
1690
+ },
1594
1691
  "ParallelCoordinatesPlotSpec": {
1595
1692
  "description": "Parallel coordinates over the plotted columns.",
1596
1693
  "properties": {