@urban-toolkit/autk-grammar 4.2.0 → 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:
@@ -1528,8 +1528,61 @@
1528
1528
  ],
1529
1529
  "type": "string"
1530
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
+ },
1531
1584
  "OsmDataSourceSpec": {
1532
- "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.",
1533
1586
  "properties": {
1534
1587
  "autoLoadLayers": {
1535
1588
  "description": "Split the raw OSM table into one table per layer, named `<outputTableName>_<layer>`.",
@@ -1559,25 +1612,15 @@
1559
1612
  "type": "string"
1560
1613
  },
1561
1614
  "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"
1615
+ "anyOf": [
1616
+ {
1617
+ "$ref": "#/definitions/OsmNamedArea"
1570
1618
  },
1571
- "geocodeArea": {
1572
- "description": "Region to geocode, for example a city name.",
1573
- "type": "string"
1619
+ {
1620
+ "$ref": "#/definitions/OsmBoundingBoxArea"
1574
1621
  }
1575
- },
1576
- "required": [
1577
- "geocodeArea",
1578
- "areas"
1579
1622
  ],
1580
- "type": "object"
1623
+ "description": "Area to load: sub-areas inside a geocoded region (`geocodeArea` with `areas`), or a box (`bbox`), not both."
1581
1624
  },
1582
1625
  "type": {
1583
1626
  "const": "osm",
@@ -1591,6 +1634,31 @@
1591
1634
  ],
1592
1635
  "type": "object"
1593
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
+ },
1594
1662
  "ParallelCoordinatesPlotSpec": {
1595
1663
  "description": "Parallel coordinates over the plotted columns.",
1596
1664
  "properties": {