Skip to content

Commit 7d9a1cb

Browse files
billycbillyc
authored
Merge pull request #8 from tomstephen/main
Add AequilibraE support
2 parents 98c316d + f22a9d2 commit 7d9a1cb

File tree

3 files changed

+331
-2
lines changed

3 files changed

+331
-2
lines changed

‎docs/ref-aequilibrae-map.md‎

Lines changed: 278 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,278 @@
1+
---
2+
id: aequilibrae-map
3+
title: AequilibraE Map
4+
---
5+
6+
![AequilibraE Map Example](assets/aequlibrae-map.png)
7+
8+
# Overview
9+
10+
The AequilibraE Map plugin displays geometries (points, lines, polygons) stored in an AequilibraE project SQLite database and allows styling using model and result attributes. Panels using this plugin are added inside dashboard YAML files; use `type: aequilibrae` for the panel.
11+
12+
# Usage
13+
14+
- Add the panel to a dashboard row in a `dashboard-*.yaml` file using `type: aequilibrae`.
15+
- The panel accepts either a direct `config` object from code or a path to a YAML visualization config via `yamlConfig` (parsed by the plugin).
16+
- Use `extraDatabases` when you need to join attributes from other SQLite files (e.g. a results DB).
17+
18+
# Properties
19+
20+
This section describes top-level panel properties and layer configuration. Fields are split into *Required* and *Optional* where appropriate.
21+
22+
## Dashboard panel properties
23+
24+
| Property | Usage |
25+
| --- | --- |
26+
| `type` | MUST be set to `aequilibrae` in `dashboard-*.yaml` files |
27+
| `title` | Panel title shown above the map |
28+
| `height` | Relative height of the panel (default depends on layout) |
29+
| `width` | Relative width of the panel |
30+
31+
## Required top-level properties
32+
33+
| Property | Type | Description |
34+
| --- | --- | --- |
35+
| `database` | string | Path to the main AequilibraE SQLite database (e.g. `project_database.sqlite`). In YAML visualizations this may be provided as `database` or `file` (both accepted). |
36+
37+
## Optional top-level properties
38+
39+
| Property | Type | Description |
40+
| --- | --- | --- |
41+
| `extraDatabases` | map<string,string> | Named map of additional SQLite DBs used for joins. Example: `results: results_database.sqlite` |
42+
| `center` | array or string | Map center as `[lon, lat]` or a string interpreted by the frontend. If omitted the viewer will compute a suitable center. |
43+
| `zoom` | number | Initial zoom level |
44+
| `projection` | string | Coordinate reference system, e.g. `"EPSG:32719"` |
45+
| `bearing` | number | Map rotation |
46+
| `pitch` | number | Map pitch |
47+
| `defaults` | object | Default style values applied to all layers (see below) |
48+
| `legend` | array | Explicit legend items (array of `{ label, color, size, shape, subtitle }`) |
49+
| `minimalProperties` | boolean | If true request a smaller set of feature properties to reduce payload |
50+
| `geometryLimit` | number | Limit number of geometries loaded (useful for very large DBs) |
51+
52+
---
53+
54+
## Layer definitions (`layers`)
55+
56+
Layers are defined under the `layers:` map. Each key is a layer id and contains configuration for a set of features.
57+
58+
Supported layer fields:
59+
60+
- `table` (string) — table name in the SQLite DB containing geometry and attributes.
61+
- `geometry` (string) — one of `point`, `line`, or `polygon`.
62+
- `sqlFilter` (string, optional) — SQL WHERE clause to filter rows, e.g. `"is_centroid=1"`.
63+
- `join` (object, optional) — join config to attach attributes from another table (see Joins).
64+
- `style` (object) — visual style settings (see Layer styles below).
65+
66+
Example minimal layer:
67+
68+
```yaml
69+
layers:
70+
links:
71+
table: links
72+
geometry: line
73+
style:
74+
lineColor: "#74BBCD"
75+
lineWidth: 0.5
76+
```
77+
78+
## Joins & `extraDatabases`
79+
80+
Provide additional databases at the top level using `extraDatabases`:
81+
82+
```yaml
83+
extraDatabases:
84+
results: results_database.sqlite
85+
```
86+
87+
Then in the geometry layer, reference the named database in a layer `join` to attach attributes from another table:
88+
89+
```yaml
90+
join:
91+
database: results # matches a key specified in extraDatabases
92+
table: base_case # table of the database to join
93+
leftKey: link_id # geometry database ("project_database.sqlite", typically)
94+
rightKey: link_id # joined database table
95+
type: left # optional: 'left' (default) or 'inner'
96+
```
97+
98+
After the join, columns from the joined table are available for styling (e.g. quantitative palettes using a result column).
99+
100+
## Layer styles
101+
102+
Style keys supported: `fillColor`, `lineColor`, `lineWidth`, `pointRadius`, `fillHeight`. (Note: client-side include/exclude filters were removed — use `sqlFilter` on the layer instead.)
103+
104+
### Default Styles (`defaults`)
105+
The optional `defaults` object sets baseline style values applied to all features before layer-specific styles are applied. If a layer doesn't specify a particular style property, the default value is used.
106+
Supported properties in `defaults`:
107+
| Property | Type | Description | Default if omitted |
108+
| --- | --- | --- | --- |
109+
| `fillColor` | string | Default fill color for polygons and points (hex) | `"#59a14f"` |
110+
| `lineColor` | string | Default line color (hex) | `"#4e79a7"` |
111+
| `lineWidth` | number | Default line width in meters | `2` |
112+
| `pointRadius` | number | Default point radius in meters | `4` |
113+
| `fillHeight` | number | Default height for 3D extrusion | `0` |
114+
Example:
115+
```yaml
116+
defaults:
117+
fillColor: "#6f6f6f"
118+
lineColor: "#FF6600"
119+
lineWidth: 2
120+
pointRadius: 4
121+
```
122+
123+
124+
125+
### Colors (`fillColor`, `lineColor`)
126+
127+
Colors may be specified in three ways:
128+
129+
1. Static hex string: `"#FF6600"`
130+
2. Categorical mapping:
131+
132+
```yaml
133+
fillColor:
134+
column: is_centroid
135+
colors:
136+
1: "#FF6600"
137+
0: "#cacaca"
138+
```
139+
140+
3. Quantitative mapping (palette):
141+
142+
```yaml
143+
lineColor:
144+
column: Delay_factor_Max
145+
palette: Temps
146+
dataRange: [1,3]
147+
```
148+
149+
Fields supported for quantitative mapping: `column`, `palette`, `numColors`, `range`, `dataRange`.
150+
151+
Palettes are provided by [CARTOColor](https://carto.com/carto-colors/).
152+
153+
### Geometry sizes (`lineWidth`, `pointRadius`)
154+
155+
Geometry sizes can be defined in a few ways,
156+
157+
- a static number: `2`
158+
- a categorical mapping:
159+
160+
```yaml
161+
lineWidth:
162+
column: link_type
163+
widths:
164+
road: 20
165+
freeway: 80
166+
centroid_connector: 20
167+
```
168+
- or a continuous mapping:
169+
```yaml
170+
pointRadius:
171+
column: some_metric
172+
dataRange: [0, 100] # optional: clamp the input data range
173+
widthRange: [1, 50] # optional: set the output data range to map to
174+
```
175+
176+
### Filtering features
177+
178+
Use SQL-level filtering — `sqlFilter` on the layer — to restrict rows returned by the database. This prevents unwanted geometries (for example centroids) from being loaded into memory and rendered, and is the supported method for filtering.
179+
180+
Example: to exclude centroid nodes:
181+
182+
```yaml
183+
layers:
184+
nodes:
185+
table: nodes
186+
geometry: point
187+
sqlFilter: "is_centroid = 0" # only non-centroid nodes
188+
```
189+
190+
## Legend
191+
192+
- Legends are auto-generated from categorical/color/width mappings where possible.
193+
- You can provide an explicit `legend` array at the panel level to control labels/colors/sizes manually. Each legend item may include `label`, `color`, `size`, `shape`, `subtitle`.
194+
195+
Example explicit legend:
196+
197+
```yaml
198+
legend:
199+
- subtitle: "Link Types"
200+
- label: "Freeway"
201+
color: "#C3A34B"
202+
size: 4
203+
shape: line
204+
```
205+
206+
# Examples
207+
208+
Examples below are taken from the Chicago sample dashboards in this repository.
209+
210+
## Simple entire network
211+
212+
```yaml
213+
- type: aequilibrae
214+
title: "Entire Network"
215+
database: project_database.sqlite
216+
center: [-87.6298, 41.8781]
217+
zoom: 10
218+
defaults:
219+
fillColor: "#6f6f6f"
220+
lineColor: "#FF6600"
221+
lineWidth: 2
222+
pointRadius: 4
223+
layers:
224+
nodes:
225+
table: nodes
226+
geometry: point
227+
sqlFilter: "is_centroid = 0" # show only non-centroid nodes
228+
style:
229+
fillColor:
230+
column: is_centroid
231+
colors:
232+
1: "#FF6600"
233+
0: "#cacaca"
234+
links:
235+
table: links
236+
geometry: line
237+
style:
238+
lineColor: "#74BBCD"
239+
lineWidth: 0.5
240+
```
241+
242+
## Join with results DB and palette mapping
243+
244+
```yaml
245+
- type: aequilibrae
246+
title: "Delay Factor"
247+
database: project_database.sqlite
248+
extraDatabases:
249+
results: results_database.sqlite
250+
defaults:
251+
lineWidth: 4
252+
layers:
253+
links:
254+
table: links
255+
geometry: line
256+
join:
257+
database: results
258+
table: base_case
259+
leftKey: link_id
260+
rightKey: link_id
261+
type: left
262+
style:
263+
lineColor:
264+
column: Delay_factor_Max
265+
palette: Temps
266+
dataRange: [1,3]
267+
lineWidth:
268+
column: link_type
269+
widths:
270+
3: 20
271+
2: 40
272+
1: 20
273+
```
274+
275+
# Tips & Notes
276+
277+
- Use `sqlFilter` to reduce the number of features rendered and improve performance.
278+
- For very large datasets, set `geometryLimit` or `minimalProperties` to reduce memory and payload size.

‎docs/ref-tiles.md‎

Lines changed: 52 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -16,19 +16,69 @@ The Tiles plug in displays key data for a good overview.
1616
The tiles plug-in can only be included as panels in **Dashboards**. See Dashboard documentation for general tips on creating dashboard configurations.
1717

1818
- Each table viewer panel is defined inside a **row** in a `dashboard-*.yaml` file.
19-
- Use panel `type: csv` in the dashboard configuration.
19+
- Use panel `type: tile` in the dashboard configuration.
2020
- Standard title, description, and width fields define the frame.
2121

22+
Data for the tiles can be provided in a number of ways,
23+
24+
- As a `.csv` file
25+
- Hard-coded `title` and `value` pairs
26+
- As a sqlite table
27+
- As individual `title` and sqlite-query pairs
28+
29+
Additionally, the color palette for the tiles can be set via the `colors` parameter. Options are `pastel` (default), `vivid`, and `monochrome`.
30+
2231
---
2332

2433
### Sample dashboard.yaml config snippet
2534

35+
For data source from csv, a sqlite table, hardcoded and a series of sqlite queries,
36+
37+
```yaml
38+
layout:
39+
csv_row:
40+
- type: 'tile'
41+
title: Tiles Plug-in Example
42+
dataset: 'data.csv'
43+
sqlite_table_row:
44+
- type: 'tile'
45+
title: "My Tile Panel"
46+
dataset:
47+
database: project_database.sqlite
48+
query: "SELECT metric, value FROM metadata_table;"
49+
titleCol: metric (n.b., optional, these default to 'metric' and 'value')
50+
valueCol: value
51+
hardcoded_row:
52+
- type: 'tile'
53+
title: "My Tile Panel"
54+
dataset:
55+
- key: "Total trips"
56+
value: 54321
57+
- key: "Average speed"
58+
value: 23.4
59+
sqlite_queries_row:
60+
- type: 'tile'
61+
title: "My Tile Panel"
62+
dataset:
63+
- key: "Total trips"
64+
value:
65+
database: project_database.sqlite
66+
query: "SELECT COUNT(*) FROM trips;"
67+
- key: "Average speed"
68+
value:
69+
database: project_database.sqlite
70+
query: "SELECT AVG(speed) FROM trips;"
71+
```
72+
73+
To change the color palette.
74+
2675
```yaml
2776
layout:
28-
row1:
77+
csv_row:
2978
- type: 'tile'
3079
title: Tiles Plug-in Example
3180
dataset: 'data.csv'
81+
colors: 'monochrome'
3282
```
3383
3484
---

‎website/sidebars.json‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -18,6 +18,7 @@
1818
"matsim-events"
1919
],
2020
"API Reference / General": [
21+
"aequilibrae-map",
2122
"aggregate-od",
2223
"bar-area-line",
2324
"calculation-tables",

0 commit comments

Comments
 (0)