@urban-toolkit/autk-grammar 4.1.1 → 4.2.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
@@ -41,6 +41,38 @@ requestAnimationFrame(() => {
41
41
  });
42
42
  ```
43
43
 
44
+ ## Layer styling
45
+
46
+ Besides `dataRef`, a layer of `map.layerRefs` takes these styling options:
47
+
48
+ | Option | Effect |
49
+ |---|---|
50
+ | `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. |
51
+ | `color` | The layer's color, `#rrggbb`. The layer is drawn in it rather than by its `getFnv` value, unless `isColorMap` is `true`. |
52
+ | `stroke` | A polygon layer's outline: its color, `#rrggbb`, or `false` for none. |
53
+ | `width` | The width of a polylines or roads layer's lines, in the map's planar units (autk-map's `polylinesWidth`). |
54
+ | `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. |
57
+ | `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
+
59
+ 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`.
60
+
61
+ ```ts
62
+ await grammar.run({
63
+ data: [/* tables named routes and parcels, and a heatmap raster named change */],
64
+ map: {
65
+ layerRefs: [
66
+ { dataRef: 'parcels', color: '#4e79a7', stroke: false },
67
+ { dataRef: 'routes', title: 'Fastest route', color: '#e15759', width: 30 },
68
+ { dataRef: 'change', title: 'Change', colorMapInterpolator: ColorMapInterpolator.DIV_RED_BLUE, colorMapCenter: 0, colorMapReverse: true },
69
+ ],
70
+ },
71
+ });
72
+ const { map, layerId } = grammar.mapLayer('routes')!; // layerId is 'Fastest route'
73
+ map.updateRenderInfo(layerId, { opacity: 0.5 });
74
+ ```
75
+
44
76
  ## Interactions
45
77
 
46
78
  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": [
@@ -1577,7 +1620,7 @@
1577
1620
  "type": "number"
1578
1621
  },
1579
1622
  "mapRef": {
1580
- "description": "Layer id of a map this plot links its selection to.",
1623
+ "description": "`dataRef` of the map layer this plot links its selection to.",
1581
1624
  "type": "string"
1582
1625
  },
1583
1626
  "margins": {
@@ -1900,6 +1943,42 @@
1900
1943
  },
1901
1944
  "type": "array"
1902
1945
  },
1946
+ "RasterTransferFunction": {
1947
+ "description": "How opaque a raster layer's cells are by value: autk-map's transfer function. A cell with no value is clear.",
1948
+ "properties": {
1949
+ "gamma": {
1950
+ "description": "Exponent applied to a cell's place between the lowest and highest opacity. Defaults to 1.",
1951
+ "exclusiveMinimum": 0,
1952
+ "type": "number"
1953
+ },
1954
+ "mode": {
1955
+ "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.",
1956
+ "enum": [
1957
+ "near-zero",
1958
+ "far-zero",
1959
+ "linear"
1960
+ ],
1961
+ "type": "string"
1962
+ },
1963
+ "opacityMax": {
1964
+ "description": "Highest opacity, from 0 to 1. Defaults to 1.",
1965
+ "maximum": 1,
1966
+ "minimum": 0,
1967
+ "type": "number"
1968
+ },
1969
+ "opacityMin": {
1970
+ "description": "Lowest opacity, from 0 to 1. Defaults to 0.",
1971
+ "maximum": 1,
1972
+ "minimum": 0,
1973
+ "type": "number"
1974
+ },
1975
+ "zeroCenter": {
1976
+ "description": "Value the `far-zero` and `near-zero` modes measure from. Defaults to 0.",
1977
+ "type": "number"
1978
+ }
1979
+ },
1980
+ "type": "object"
1981
+ },
1903
1982
  "ScatterPlotSpec": {
1904
1983
  "description": "A scatterplot of two or more columns.",
1905
1984
  "properties": {
@@ -1929,7 +2008,7 @@
1929
2008
  "type": "number"
1930
2009
  },
1931
2010
  "mapRef": {
1932
- "description": "Layer id of a map this plot links its selection to.",
2011
+ "description": "`dataRef` of the map layer this plot links its selection to.",
1933
2012
  "type": "string"
1934
2013
  },
1935
2014
  "margins": {
@@ -2013,7 +2092,7 @@
2013
2092
  "type": "number"
2014
2093
  },
2015
2094
  "mapRef": {
2016
- "description": "Layer id of a map this plot links its selection to.",
2095
+ "description": "`dataRef` of the map layer this plot links its selection to.",
2017
2096
  "type": "string"
2018
2097
  },
2019
2098
  "margins": {