@urban-toolkit/autk-grammar 4.4.1 → 5.0.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 +275 -5
- package/build/autk-grammar-schema.json +945 -425
- package/dist/autk-grammar.js +752 -426
- 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 +2 -0
- package/dist/data/autk-grammar-data.cjs.map +1 -0
- package/dist/data/autk-grammar-data.d.ts +349 -0
- package/dist/data/autk-grammar-data.js +165 -0
- package/dist/data/autk-grammar-data.js.map +1 -0
- package/dist/index.d.ts +555 -75
- package/package.json +7 -2
package/README.md
CHANGED
|
@@ -29,6 +29,61 @@ const grammar = new AutkGrammar({ map: 'map', plot: 'plot' }); // ids of the map
|
|
|
29
29
|
await grammar.run(spec);
|
|
30
30
|
```
|
|
31
31
|
|
|
32
|
+
## Data sources
|
|
33
|
+
|
|
34
|
+
Each entry of `data` loads or builds one table, in order. Its `type` selects its fields:
|
|
35
|
+
|
|
36
|
+
| `type` | Fields | Table |
|
|
37
|
+
|---|---|---|
|
|
38
|
+
| `osm` | `queryArea`, `pbfFileUrl`, `autoLoadLayers` | OpenStreetMap data for an area, from Overpass or a `.osm.pbf` extract (see [OpenStreetMap areas](#openstreetmap-areas)). `autoLoadLayers.layers` splits it into one table per layer, named `<outputTableName>_<layer>`. |
|
|
39
|
+
| `csv` | `csvFileUrl` or `csvObject`, `delimiter`, `geometryColumns` | The rows of a CSV file, or of arrays whose first row names the columns. |
|
|
40
|
+
| `json` | `jsonFileUrl` or `jsonObject`, `geometryColumns` | The rows of a JSON array. |
|
|
41
|
+
| `geojson` | `geojsonFileUrl` or `geojsonObject`, `coordinateFormat`, `layerType` | A FeatureCollection. `layerType` sets how a map draws it, for example `polylines`, or `buildings` for polygons; without it, autk-db reads it from the first feature with a geometry. A feature whose geometry is null is a row without one: a map draws nothing for it, and a plot counts it. |
|
|
42
|
+
| `geotiff` | `geotiffFileUrl`, `coordinateFormat`, `maxRasterCells`, `resampleMethod` | A raster read from a GeoTIFF file. |
|
|
43
|
+
| `heatmap` | `joinDataRef`, `near`, `grid`, `groupBy` | A raster grid over the workspace's extent, whose cells aggregate the rows of another table. |
|
|
44
|
+
| `join` | `dataRef`, `joinDataRef`, `near`, `groupBy` | No new table: it joins the rows of `joinDataRef` onto the features of `dataRef`, in place. |
|
|
45
|
+
|
|
46
|
+
Every source but `join` names its table with `outputTableName`, and every source takes a `workspace` (see [Workspaces](#workspaces)).
|
|
47
|
+
|
|
48
|
+
A `geotiff` source:
|
|
49
|
+
|
|
50
|
+
| Field | Effect |
|
|
51
|
+
|---|---|
|
|
52
|
+
| `geotiffFileUrl` | The file's URL, relative to the page or absolute. Its first image is read: each of its bands becomes a band of the table (`band_1`, `band_2`, ...), and the file's no-data value reads as no value. A rotated or sheared grid is refused. |
|
|
53
|
+
| `coordinateFormat` | The file's CRS, as an EPSG string. Defaults to `EPSG:4326`. |
|
|
54
|
+
| `maxRasterCells` | The most cells to decode: a larger raster is downsampled to fit. Defaults to 1,000,000. |
|
|
55
|
+
| `resampleMethod` | How a larger raster is downsampled: `nearest` or `bilinear`, the default. |
|
|
56
|
+
|
|
57
|
+
A map layer draws the band of a raster table that its `getFnv` names, else the first band.
|
|
58
|
+
|
|
59
|
+
A `join` or a `heatmap` source:
|
|
60
|
+
|
|
61
|
+
| Field | Effect |
|
|
62
|
+
|---|---|
|
|
63
|
+
| `dataRef` | A join's root table, which receives the joined rows. |
|
|
64
|
+
| `joinDataRef` | The table whose rows are joined onto the root table, or aggregated into a heatmap's cells. |
|
|
65
|
+
| `near` | `{ distance, useCentroid }`, with `distance` in workspace units. A join takes the rows within `distance` of each root feature instead of those that intersect it. A heatmap, which needs it, gives each cell the rows within `distance` of the cell's center. With `useCentroid`, the default, distances run between centroids: a root feature's and a row's, or a cell's center and a row's centroid. With `false`, they run between the geometries' nearest points, so features that touch are 0 apart. |
|
|
66
|
+
| `grid` | A heatmap's cells: `{ rows, columns }`, over the extent of the workspace. |
|
|
67
|
+
| `groupBy` | How the rows combine, as `[{ column, aggregateFn }]`, where `aggregateFn` is `sum`, `avg`, `count`, `min`, `max`, `weighted` or `collect`; a heatmap refuses `collect`, which lists rows, since a cell holds one value. A join writes the result on each root feature: `{ column: 'Unique Key', aggregateFn: 'count' }` writes `sjoin.count.<joinDataRef>`, and `normalize: true` adds the value rescaled from 0 to 1 across the features, under its key with `_norm` added. Without `groupBy`, a join lists the rows each feature matches in `sjoin.matches`. A heatmap has one band per entry, labelled `<aggregateFn>_<joinDataRef>`, which a layer's `getFnv` names as `<aggregateFn>.<joinDataRef>`, for example `count.noise`; without `groupBy`, one band counts the rows. |
|
|
68
|
+
|
|
69
|
+
```ts
|
|
70
|
+
await grammar.run({
|
|
71
|
+
data: [
|
|
72
|
+
{ type: 'geojson', outputTableName: 'neighborhoods', geojsonFileUrl: 'neighborhoods.geojson' },
|
|
73
|
+
{ type: 'csv', outputTableName: 'noise', csvFileUrl: 'noise.csv', geometryColumns: { latColumnName: 'Latitude', longColumnName: 'Longitude' } },
|
|
74
|
+
{ type: 'join', dataRef: 'neighborhoods', joinDataRef: 'noise', groupBy: [{ column: 'Unique Key', aggregateFn: 'count' }] },
|
|
75
|
+
{ type: 'heatmap', outputTableName: 'heat', joinDataRef: 'noise', near: { distance: 1000 }, grid: { rows: 20, columns: 20 } },
|
|
76
|
+
],
|
|
77
|
+
map: { layerRefs: [{ dataRef: 'neighborhoods', getFnv: 'sjoin.count.noise' }, { dataRef: 'heat', opacity: 0.5 }] },
|
|
78
|
+
});
|
|
79
|
+
```
|
|
80
|
+
|
|
81
|
+
### Workspaces
|
|
82
|
+
|
|
83
|
+
A workspace is an isolated set of tables with its own extent. The first source loaded into a workspace sets its extent, and later sources are cut to it, so two areas that must not clip each other go in two workspaces. A table is found by its name inside its workspace, so two workspaces may hold tables of the same name.
|
|
84
|
+
|
|
85
|
+
`workspace` names one, on a source (where its table goes), a compute pass (where it reads and writes), a map or a plot (where it reads its tables). An entry without one uses the default workspace.
|
|
86
|
+
|
|
32
87
|
## OpenStreetMap areas
|
|
33
88
|
|
|
34
89
|
An `osm` source's `queryArea` names the area to load in one of two ways, never both:
|
|
@@ -53,6 +108,51 @@ await grammar.run({
|
|
|
53
108
|
});
|
|
54
109
|
```
|
|
55
110
|
|
|
111
|
+
## Compute
|
|
112
|
+
|
|
113
|
+
Each entry of `compute` runs on the GPU with autk-compute, in order, once the data is loaded. Its `type` is `gpgpu`, the default, or `render`.
|
|
114
|
+
|
|
115
|
+
A GPGPU pass runs a WGSL function once per feature of a table:
|
|
116
|
+
|
|
117
|
+
| Field | Effect |
|
|
118
|
+
|---|---|
|
|
119
|
+
| `dataRef` | The table the function runs over. |
|
|
120
|
+
| `attributes` | WGSL variable names, each mapped to a feature property path. |
|
|
121
|
+
| `wgslFunction` | The body of the WGSL function. An array of strings is joined with newlines, which keeps long shaders readable in JSON. |
|
|
122
|
+
| `outputColumnName`, `outputColumns` | The column the function's result is written to, under `feature.properties.compute`, or the columns of a result of several values. |
|
|
123
|
+
| `outputTableName` | A new table that receives the result, so `dataRef` stays as it is and later passes, maps and plots can read both. Without it, the pass writes into `dataRef`. |
|
|
124
|
+
| `layerType` | How a map draws the new table. Defaults to the type of `dataRef`. Only used with `outputTableName`. |
|
|
125
|
+
|
|
126
|
+
`attributeArrays` and `attributeMatrices` pass more of each feature's values, and `uniforms`, `uniformArrays` and `uniformMatrices` pass values every invocation shares. `uniforms` and `uniformMatrices` can read theirs from a feature of a table (see [Compute helpers](#compute-helpers)).
|
|
127
|
+
|
|
128
|
+
A render pass renders tables on the GPU from each viewpoint, in several directions, and counts what each frame shows: a visibility or sky-view metric. Its result is a new table: the viewpoints' features, with the metrics in `feature.properties.compute.render`: `sampleCount`, the frames rendered from the feature, and `classes` or `objects`.
|
|
129
|
+
|
|
130
|
+
| Field | Effect |
|
|
131
|
+
|---|---|
|
|
132
|
+
| `outputTableName` | The new table. Required. |
|
|
133
|
+
| `layerType` | How a map draws it. Defaults to the type of the viewpoints table, or to `points` with the `building-windows` strategy, whose result holds one point per window. |
|
|
134
|
+
| `layers` | The tables drawn into the frames: `{ id, dataRef, type, objectIdProperty }`. `id` names the layer in the pass, `type` sets how it is drawn (`surface`, `parks`, `water`, `roads`, `buildings`, `polygons` or `polylines`: a render pass draws no points, and a run refuses any other type), and `objectIdProperty` names the property that holds an object's id. |
|
|
135
|
+
| `viewpoints.dataRef` | The table whose features the frames are rendered from. |
|
|
136
|
+
| `viewpoints.strategy` | `{ type: 'centroid' }`, the default: a viewpoint at each feature's centroid. `{ type: 'building-windows', floors }`: windows along each building's facades, `floors` rows of them up its height, each looking out from the facade and 30 degrees to either side. The result then holds one point per window instead of the table's features. |
|
|
137
|
+
| `viewpoints.sampling` | With `centroid`, the directions each viewpoint looks in: `directions` of them (1 by default), evenly spaced around the horizon, the first at `azimuthOffsetDeg` degrees counterclockwise from east (0 by default), all at `pitchDeg` degrees above the horizontal (0 by default). |
|
|
138
|
+
| `aggregation` | `{ type: 'classes' }` writes the share of each feature's frame pixels that each layer type covers, from 0 to 1. `includeBackground: true` also counts the pixels no layer covers, such as the sky, as one more class, `backgroundLayerType` (`background` by default). `{ type: 'objects' }` writes, for each object seen, the share of the feature's frames that show it. |
|
|
139
|
+
| `camera` | The lens of the frames: `fov`, the field of view of each square frame in degrees (90 by default), and `clip: { near, far }`, the nearest and farthest distances drawn, in workspace units (1 and 5000 by default). Unlike a map's `camera`, it sets no position or direction: `viewpoints` does. |
|
|
140
|
+
| `tileSize` | The size of each frame in pixels, a multiple of 8. Defaults to 64. |
|
|
141
|
+
|
|
142
|
+
```ts
|
|
143
|
+
await grammar.run({
|
|
144
|
+
data: [/* a buildings table named buildings, and a points table named sensors */],
|
|
145
|
+
compute: [{
|
|
146
|
+
type: 'render',
|
|
147
|
+
outputTableName: 'skyView',
|
|
148
|
+
layers: [{ id: 'buildings', dataRef: 'buildings', type: 'buildings' }],
|
|
149
|
+
viewpoints: { dataRef: 'sensors', sampling: { directions: 8, pitchDeg: 30 } },
|
|
150
|
+
aggregation: { type: 'classes', includeBackground: true },
|
|
151
|
+
}],
|
|
152
|
+
map: { layerRefs: [{ dataRef: 'buildings' }, { dataRef: 'skyView', getFnv: 'compute.render.classes.background' }] },
|
|
153
|
+
});
|
|
154
|
+
```
|
|
155
|
+
|
|
56
156
|
## Maps
|
|
57
157
|
|
|
58
158
|
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:
|
|
@@ -65,6 +165,22 @@ requestAnimationFrame(() => {
|
|
|
65
165
|
});
|
|
66
166
|
```
|
|
67
167
|
|
|
168
|
+
A map's `id` names it as the `target` of a link (see [Plots and links](#plots-and-links)). No two maps or plots of a spec share an id, and an id is never empty.
|
|
169
|
+
|
|
170
|
+
A map's `camera` moves its view from the one that fits its layers:
|
|
171
|
+
|
|
172
|
+
| Option | Effect |
|
|
173
|
+
|---|---|
|
|
174
|
+
| `zoom` | The eye's distance from the point the view looks at: `10000 / 2^(zoom - 10)` workspace units, so each step halves it. Without it, the distance of the view that fits the layers. |
|
|
175
|
+
| `pitch` | The tilt from straight down, from 0 to 90 degrees. |
|
|
176
|
+
| `bearing` | The compass heading the view faces, clockwise from north, from 0 to 360 degrees. |
|
|
177
|
+
|
|
178
|
+
The camera turns around the point the map looks at, which the view that fits the layers sets: the eye moves on a sphere around that point, so the layers stay in view at any pitch and bearing.
|
|
179
|
+
|
|
180
|
+
```ts
|
|
181
|
+
map: { id: 'downtown', camera: { zoom: 15, pitch: 50, bearing: 30 }, layerRefs: [{ dataRef: 'buildings' }] }
|
|
182
|
+
```
|
|
183
|
+
|
|
68
184
|
## Layer styling
|
|
69
185
|
|
|
70
186
|
Besides `dataRef`, a layer of `map.layerRefs` takes these styling options:
|
|
@@ -75,21 +191,23 @@ Besides `dataRef`, a layer of `map.layerRefs` takes these styling options:
|
|
|
75
191
|
| `color` | The layer's color, `#rrggbb`. The layer is drawn in it rather than by its `getFnv` value, unless `isColorMap` is `true`. |
|
|
76
192
|
| `stroke` | A polygon layer's outline: its color, `#rrggbb`, or `false` for none. |
|
|
77
193
|
| `width` | The width of a polylines or roads layer's lines, in the map's planar units (autk-map's `polylinesWidth`). |
|
|
194
|
+
| `pointSize` | The radius of each point of a points layer, in meters on the ground. The adapter converts it to the workspace's planar units at the middle of the layer, where World Mercator stretches a meter by about 1.34 at Chicago, and passes it as autk-map's `pointSize`. Without it, autk-map draws each point with a radius of 64 planar units, about 48 m at Chicago. Other layers ignore it. |
|
|
78
195
|
| `colorMapInterpolator` | The color scheme. A raster layer's cells and its legend's labels follow it. |
|
|
79
196
|
| `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
197
|
| `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
198
|
| `colorMapReverse` | On a raster layer, runs the color scale from the highest value to the lowest, or from `colorMapRange`'s high to its low. |
|
|
82
199
|
| `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. |
|
|
83
200
|
|
|
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
|
|
201
|
+
After a run, `grammar.mapLayer(dataRef)` finds the layer a map draws for a table: the `AutkMap` and the layer's id in it, the last map's when several maps draw the table. `grammar.mapLayers(dataRef)` lists every layer that draws it, in every map. `highlightOnMap`, `clearHighlightOnMap` and a plot's `mapRef` also name layers by their `dataRef` (see [Interactions](#interactions)).
|
|
85
202
|
|
|
86
203
|
```ts
|
|
87
204
|
await grammar.run({
|
|
88
|
-
data: [/* tables named routes and parcels, and a heatmap raster named change */],
|
|
205
|
+
data: [/* tables named routes and parcels, a points table named fixes, and a heatmap raster named change */],
|
|
89
206
|
map: {
|
|
90
207
|
layerRefs: [
|
|
91
208
|
{ dataRef: 'parcels', color: '#4e79a7', stroke: false },
|
|
92
209
|
{ dataRef: 'routes', title: 'Fastest route', color: '#e15759', width: 30 },
|
|
210
|
+
{ dataRef: 'fixes', title: 'GPS fixes', color: '#f28e2b', pointSize: 2 }, // discs 4 m across
|
|
93
211
|
{ dataRef: 'change', title: 'Change', colorMapInterpolator: ColorMapInterpolator.DIV_RED_BLUE, colorMapCenter: 0, colorMapReverse: true },
|
|
94
212
|
],
|
|
95
213
|
},
|
|
@@ -98,15 +216,97 @@ const { map, layerId } = grammar.mapLayer('routes')!; // layerId is 'Fastest rou
|
|
|
98
216
|
map.updateRenderInfo(layerId, { opacity: 0.5 });
|
|
99
217
|
```
|
|
100
218
|
|
|
219
|
+
## Plots and links
|
|
220
|
+
|
|
221
|
+
A plot reads only its table's properties, so it also draws a table without a geometry, such as a CSV or JSON table loaded without `geometryColumns`.
|
|
222
|
+
|
|
223
|
+
A plot's `id` names it: as the `source` of a link, as the `plotId` of its `plot:selection` events, and for `setPlotSelection` and `clearHighlightOnPlot`. Without an id, a plot is known by its `dataRef`, so a run refuses two plots known by one name: two plots of one table without ids, or a plot whose id is the `dataRef` of a plot without one. Give each plot an id.
|
|
224
|
+
|
|
225
|
+
`links` connect a plot to a layer of a map. Picking on the layer selects the same features in the plot (a pick on another layer of the map does not), and a selection in the plot, by an event its `events` lists, highlights them on the layer. The link makes the layer pickable. A selection passes by the rows each view drew, not by positions: a plot draws its table's rows in the order its source gave them, while a layer draws the rows autk-db holds, which can come in another order, and leaves out the rows without a geometry. Each row is found in the other view by its feature id: a GeoJSON feature's `id`, else the one autk-db gives it, `autk-feature-<index>`.
|
|
226
|
+
|
|
227
|
+
| Field | Effect |
|
|
228
|
+
|---|---|
|
|
229
|
+
| `source` | The plot: its `id`, else its `dataRef`. |
|
|
230
|
+
| `target` | The map: its `id`. |
|
|
231
|
+
| `layer` | The layer of the target map, by its `title`, else its `dataRef`. Defaults to the layer that draws the plot's `dataRef`. |
|
|
232
|
+
|
|
233
|
+
A run refuses a link that names no plot, map or layer of the spec. A plot's `mapRef` is a shorthand for links: it names the table (`dataRef`) of map layers, and links the plot to every layer that draws it, in every map.
|
|
234
|
+
|
|
235
|
+
```ts
|
|
236
|
+
await grammar.run({
|
|
237
|
+
layout: { type: 'horizontal', gap: 8 },
|
|
238
|
+
data: [/* a table named parcels */],
|
|
239
|
+
map: { id: 'city', layerRefs: [{ dataRef: 'parcels', title: 'Parcels' }] },
|
|
240
|
+
plot: { id: 'sizes', dataRef: 'parcels', mark: 'scatter', axis: ['area', 'perimeter'], events: ['brush'] },
|
|
241
|
+
links: [{ source: 'sizes', target: 'city', layer: 'Parcels' }],
|
|
242
|
+
});
|
|
243
|
+
```
|
|
244
|
+
|
|
101
245
|
## Interactions
|
|
102
246
|
|
|
103
|
-
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.
|
|
247
|
+
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). Every map of the spec reports its picks, though several draw one table. 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.
|
|
248
|
+
|
|
249
|
+
| Event | Field | Value |
|
|
250
|
+
|---|---|---|
|
|
251
|
+
| `map:picking` | `mapId` | The map the pick was made on: its `id`, else its index in `map` (0 for a single map). |
|
|
252
|
+
| `map:picking` | `layerId` | The picked layer's id in its map: its `title`, else its `dataRef`. |
|
|
253
|
+
| `map:picking` | `selection` | The picked features' ids. |
|
|
254
|
+
| `plot:selection` | `plotId` | The plot: its `id`, else its `dataRef`. |
|
|
255
|
+
| `plot:selection` | `event` | The interaction: `click`, `brush`, `brushX` or `brushY`. |
|
|
256
|
+
| `plot:selection` | `selection` | The selected features' ids. |
|
|
104
257
|
|
|
105
258
|
```ts
|
|
106
|
-
grammar.interactions.on('map:picking', ({ layerId, selection }) => { /* feature ids */ });
|
|
259
|
+
grammar.interactions.on('map:picking', ({ mapId, layerId, selection }) => { /* feature ids */ });
|
|
107
260
|
grammar.interactions.on('plot:selection', ({ plotId, event, selection }) => { /* feature ids */ });
|
|
108
261
|
```
|
|
109
262
|
|
|
263
|
+
An app sets selections with these calls, which take feature ids as the events give them. Each reaches every map that draws the table, or only the map its last argument, `mapId`, names:
|
|
264
|
+
|
|
265
|
+
| Call | Effect |
|
|
266
|
+
|---|---|
|
|
267
|
+
| `mapLayers(dataRef, mapId?)` | Every layer that draws the table, each as `{ map, layerId }`: the maps in the spec's order, each map's layers bottom first. |
|
|
268
|
+
| `mapLayer(dataRef, mapId?)` | The last of those: the last map's layer when several maps draw the table. |
|
|
269
|
+
| `highlightOnMap(dataRef, featureIds, mapId?)` | Highlights the features on each of those layers, and selects the same rows in the plots linked to the layers. |
|
|
270
|
+
| `clearHighlightOnMap(dataRef, mapId?)` | Clears those highlights, and the linked plots' selections. |
|
|
271
|
+
| `setPlotSelection(plotId, featureIds, mapId?)` | Selects the features in the plot (its `id`, else its `dataRef`), and highlights the same rows on the layers it is linked to. |
|
|
272
|
+
| `clearHighlightOnPlot(plotId, mapId?)` | Clears the plot's selection, and the highlights on the layers it is linked to. |
|
|
273
|
+
|
|
274
|
+
`mapId` names one map: a string by its `id`, a number by its index in `map`. The `mapId` of a `map:picking` event names the map it came from, so it can be passed back as it is.
|
|
275
|
+
|
|
276
|
+
```ts
|
|
277
|
+
grammar.highlightOnMap('buildings', [3, 7]); // every map that draws buildings
|
|
278
|
+
grammar.highlightOnMap('buildings', [3, 7], 'after'); // the map whose id is 'after'
|
|
279
|
+
grammar.clearHighlightOnMap('buildings', 0); // the first map
|
|
280
|
+
```
|
|
281
|
+
|
|
282
|
+
## Page layout
|
|
283
|
+
|
|
284
|
+
A spec's `layout` says how its maps and plots are arranged on the page. The grammar's run never reads it: the page that hosts the views does, when it makes their canvases and elements, with `arrangeViews(spec)` (see [For hosts](#for-hosts)), so every host arranges a spec's views alike.
|
|
285
|
+
|
|
286
|
+
| Field | Effect |
|
|
287
|
+
|---|---|
|
|
288
|
+
| `type` | `vertical`, the default, stacks the views; `horizontal` puts them side by side; `grid` fills `columns` columns, row by row. |
|
|
289
|
+
| `columns` | The number of columns of a `grid`, a whole number. Defaults to 2. |
|
|
290
|
+
| `gap` | The space between views, in pixels. Defaults to 0. |
|
|
291
|
+
|
|
292
|
+
Each view has its own pane: the maps first, in the order of `map`, then the plots, in the order of `plot`, as the grammar draws them.
|
|
293
|
+
|
|
294
|
+
The constructor names the elements the views draw in, by id:
|
|
295
|
+
|
|
296
|
+
| Target | Effect |
|
|
297
|
+
|---|---|
|
|
298
|
+
| `map` | The canvas a map draws on, or a list of ids, one canvas per entry of `map`, in order. |
|
|
299
|
+
| `plot` | The element the plots draw in, or a list of ids, one element per entry of `plot`, in order. With one id, every plot draws in that element. |
|
|
300
|
+
| `db` | An element that lists the loaded tables after each data source. |
|
|
301
|
+
|
|
302
|
+
```ts
|
|
303
|
+
const grammar = new AutkGrammar({ map: ['before', 'after'], plot: ['heights', 'areas'] });
|
|
304
|
+
```
|
|
305
|
+
|
|
306
|
+
## Lifecycle
|
|
307
|
+
|
|
308
|
+
`destroy()` releases what the last run made: it destroys each map (its layers' GPU buffers, its textures, its canvas context, the controls it adds to the page and its event handlers) and clears the grammar's registries, caches and event forwarding. autk-map's maps share one GPU device, which stays for the maps of the next run. `run()` calls it before it starts, so running a new spec on the same instance does not leak the maps of the old one, and its maps and plots draw only its own tables. Call it yourself before the page or the canvases go away. A map whose layers fail to load is destroyed as the run fails, so it leaves nothing on the page.
|
|
309
|
+
|
|
110
310
|
## JSON Schema
|
|
111
311
|
|
|
112
312
|
The package ships the grammar's JSON Schema (draft-07) as `@urban-toolkit/autk-grammar/build/autk-grammar-schema.json`, with `$id` `https://autarkjs.org/schema/autk-grammar/v1.json`. Validate a spec with any draft-07 validator:
|
|
@@ -121,7 +321,77 @@ if (!validate(spec)) console.error(validate.errors);
|
|
|
121
321
|
|
|
122
322
|
## Compute helpers
|
|
123
323
|
|
|
124
|
-
`runCompute(block, layers, run)` runs one `compute` entry against named FeatureCollections with a GPU runner you pass in, for example `params => new AutkComputeEngine().gpgpuPipeline(params)`. It joins a `
|
|
324
|
+
`runCompute(block, layers, run)` runs one `compute` entry against named FeatureCollections with a GPU runner you pass in, for example `params => new AutkComputeEngine().gpgpuPipeline(params)`. It joins a `wgslFunction` written as an array of lines, resolves `fromFeature` uniforms, and drives `iterate: 'all'` (one dispatch per feature, outputs summed) and `iterate: 'batched'` (one dispatch over packed uniform arrays). autk-compute 4 reads each packed array from a read-only storage buffer of its own, so a batched pass packs as many features as its largest array fits in 128 MiB, the storage buffer binding every WebGPU device supports: 4,194,304 with a matrix entry (a bounding box of eight floats per feature), and `maxBatchedFeatures` gives the count for a pass. `resolveComputeParams(block, layers, iterateIndex?)` returns the parameters of a single dispatch without running anything.
|
|
325
|
+
|
|
326
|
+
## For hosts
|
|
327
|
+
|
|
328
|
+
A host that runs part of a spec itself, a server that loads its tables for example, calls the functions the grammar runs, so it does exactly what `AutkGrammar` does, and a page arranges a spec's views with `arrangeViews`, as every host does:
|
|
329
|
+
|
|
330
|
+
| Export | Effect |
|
|
331
|
+
|---|---|
|
|
332
|
+
| `createDataAdapter(targets?, cache?)` | The data adapter. Its `resolveSource(db, source)` loads one `data` entry into an autk-db database, a new one when `db` is undefined, and returns it. `cache` receives each GeoJSON table and each table a join wrote. |
|
|
333
|
+
| `createComputeAdapter(cache?, types?)` | The compute adapter. Its `resolveCompute(db, pass)` runs one `compute` entry on the GPU. The results are kept only in `cache`, and `types` receives the layer type of each table a pass wrote under its own `outputTableName`. |
|
|
334
|
+
| `enterWorkspace(db, workspace?)` | Makes an entry's workspace (the default one without a name) the one autk-db works in, and switches only when another is current. Every adapter calls it before it reads or writes an entry's tables. |
|
|
335
|
+
| `tableKey(workspace, name)` | The key of a table in those caches: its name in the default workspace, `<workspace>/<name>` in another. |
|
|
336
|
+
| `applyCamera(map, camera)` | Moves an `AutkMap`'s camera as a map's `camera` says, from the view that fits its layers. The map adapter calls it once the layers are loaded, before the map's first `draw()`. |
|
|
337
|
+
| `arrangeViews(spec)` | Where each view of a spec goes on the page, as its `layout` says: a grid of panes, one per view (see [Arranging the views](#arranging-the-views)). It refuses a `layout` it cannot arrange, with a sentence that names the value. |
|
|
338
|
+
|
|
339
|
+
`@urban-toolkit/autk-grammar/data` exports `createDataAdapter`, `enterWorkspace` and `tableKey` with their types, as an ES module and a CommonJS one. Its code imports `@urban-toolkit/autk-db` alone, never autk-map, autk-plot, autk-compute or autk-core, so it loads where they cannot, such as Node:
|
|
340
|
+
|
|
341
|
+
```ts
|
|
342
|
+
import { createDataAdapter } from '@urban-toolkit/autk-grammar/data';
|
|
343
|
+
|
|
344
|
+
const adapter = createDataAdapter();
|
|
345
|
+
let db: unknown; // the AutkDb the first source creates
|
|
346
|
+
for (const source of spec.data ?? []) db = await adapter.resolveSource(db, source);
|
|
347
|
+
```
|
|
348
|
+
|
|
349
|
+
### Arranging the views
|
|
350
|
+
|
|
351
|
+
`arrangeViews(spec)` returns:
|
|
352
|
+
|
|
353
|
+
| Field | Value |
|
|
354
|
+
|---|---|
|
|
355
|
+
| `type` | `vertical`, `horizontal` or `grid`: the `layout`'s, else `vertical`. |
|
|
356
|
+
| `rows` | The rows of panes. |
|
|
357
|
+
| `columns` | The columns of panes: 1 for `vertical`, one per view for `horizontal`, and `layout.columns`, else 2, for `grid`. |
|
|
358
|
+
| `gap` | The space between neighboring panes, in pixels: `layout.gap`, else 0. |
|
|
359
|
+
| `panes` | One pane per view, in the order the grammar draws the views: the maps in the order of `map`, then the plots in the order of `plot`. |
|
|
360
|
+
|
|
361
|
+
Each pane has:
|
|
362
|
+
|
|
363
|
+
| Field | Value |
|
|
364
|
+
|---|---|
|
|
365
|
+
| `kind` | `map` or `plot`, which is also the target list, `map` or `plot`, that names the element the view draws in. |
|
|
366
|
+
| `index` | The view's position among the views of its kind: its element is entry `index` of that target list. |
|
|
367
|
+
| `id` | The view's `id`, when it has one. |
|
|
368
|
+
| `key` | The name the grammar knows the view by: its `id`, else a map's index or a plot's `dataRef`. A map's is the `mapId` of its `map:picking` events, a plot's the `plotId` of its `plot:selection` events. |
|
|
369
|
+
| `row` | The pane's row, from 0 at the top. |
|
|
370
|
+
| `column` | The pane's column, from 0 at the left. |
|
|
371
|
+
|
|
372
|
+
A host makes an element for each pane (a canvas for a map, a div for a plot), places it on a grid of `rows` by `columns`, `gap` pixels apart, and names it in the targets. Each map's canvas goes in a positioned pane of its own, since autk-map adds its controls to the canvas's parent:
|
|
373
|
+
|
|
374
|
+
```ts
|
|
375
|
+
import { AutkGrammar, arrangeViews } from '@urban-toolkit/autk-grammar';
|
|
376
|
+
|
|
377
|
+
const { rows, columns, gap, panes } = arrangeViews(spec);
|
|
378
|
+
Object.assign(container.style, {
|
|
379
|
+
display: 'grid', gap: `${gap}px`,
|
|
380
|
+
gridTemplateColumns: `repeat(${columns}, minmax(0, 1fr))`, gridTemplateRows: `repeat(${rows}, minmax(0, 1fr))`,
|
|
381
|
+
});
|
|
382
|
+
const targets: { map: string[]; plot: string[] } = { map: [], plot: [] };
|
|
383
|
+
for (const pane of panes) {
|
|
384
|
+
const cell = document.createElement('div');
|
|
385
|
+
Object.assign(cell.style, { position: 'relative', gridRow: `${pane.row + 1}`, gridColumn: `${pane.column + 1}` });
|
|
386
|
+
const element = document.createElement(pane.kind === 'map' ? 'canvas' : 'div');
|
|
387
|
+
element.id = `${pane.kind}-${pane.index}`;
|
|
388
|
+
Object.assign(element.style, { width: '100%', height: '100%' });
|
|
389
|
+
cell.appendChild(element);
|
|
390
|
+
container.appendChild(cell);
|
|
391
|
+
targets[pane.kind][pane.index] = element.id;
|
|
392
|
+
}
|
|
393
|
+
await new AutkGrammar(targets).run(spec);
|
|
394
|
+
```
|
|
125
395
|
|
|
126
396
|
## License
|
|
127
397
|
|