Viewer¶
The viewer shows the projects in its data directory. It has no built-in layers or projects: which layers belong together and in which order comes from the project files that openwater writes (projects/<id>.json), what a layer is from its layer.json, and how it looks from its style.json, which you edit in the viewer. Site texts and all defaults come from the viewer configuration viewer/viewer.yaml.
Map buttons¶
| Button | Opens |
|---|---|
| Docs | This documentation site (DOCS_URL) |
| Settings | Overview of all projects and their layers; background map |
| About | The site introduction, and for each shown layer: description, classification, rules with conditions and match counts, assumptions, what's not implemented yet, sources, and a GeoJSON download |
Side panel¶
Project. With more than one project in the data directory, the panel shows a Project list. Choosing a project shows its layers in the project's drawing order and zooms to them. Which project is shown is in the URL (?project=kiel) and remembered in your browser; new visitors see map.default_project from the viewer configuration.
Layers. One bold heading per layer of the project, with a checkbox to switch it off, and one entry per category with its number of features. A project can mark layers as off at start (e.g. the pedestrian attractors); tick them to show them. These checkboxes only change your view, temporarily. A layer of the project that isn't exported yet, or doesn't match the layer format, is listed with the reason.
The sliders button next to a layer opens its layer style.
Layer style¶
The layer style opens as a panel on the right; the map stays visible, and every change shows on it immediately. Save writes the style to layers/<id>/style.json for everyone. Close (or Esc) undoes unsaved changes after asking; Unsaved changes next to the buttons shows that there are some. Reset deletes the saved style.
| Tab | Settings |
|---|---|
| Legend | Title of the layer in the legend and popups (empty = the layer's own title). Group by: nothing (one colour, one legend entry), or an attribute with listed values. Then one legend entry per value, with: order (↑ ↓), Show (unticked = not on the map and not in the legend), colour, label (empty = the value's label), Hollow (points). Other values: colour, or untick to hide them. The Features column counts the features after the filter |
| Filter | For every other attribute with listed values: tick the values to show (All / None for quick changes). All ticked = no filter. The tab shows how many attributes filter. E.g. only underground hydrants. Not shown for layers without such attributes |
| Look | Points: Display markers or heat map. Markers: shape (circle, square, triangle, diamond), size in px at zoom 14, outline colour and width. Heat map: weight (any numeric attribute, scaled by its 95th percentile, or each feature counts 1), radius, intensity, opacity, and the colour map: a preset (Reds, Blues, Greens, Purples, Viridis, Magma) or five custom colours from low to high density; group and filter still decide which features count, heat maps have no popups, switching back to markers keeps the heat-map settings. Circle around features (points): a circle with a real-world radius, e.g. a catchment: radius fixed or from a layer parameter, only for features with a given value, colour (as the features, or one of its own), opacity, legend label. Lines: width, solid or dashed. Areas: fill opacity |
| Popup | Heading (an attribute whose value label becomes the title), table rows, which rule attributes explain the feature, OSM tag list |
A layer without a saved style gets a default: grouped by its first attribute with a closed list of values, no filter.
Settings¶
Projects. Every project with its description and layers (drawing order, top first), their number of features and export date; the shown project is open. Show switches to a project. Layers that are exported but not part of any project are listed under Not in a project: the map can't show them until a layer script adds them to a project. Projects and layers that don't match the data format are listed with the reason.
What decides the legend. Each shown layer gets one bold heading (its title). Below it: one entry per shown category of the Group by attribute that has features, in the configured order, with the number of features after the filter, plus Other values if there are any, and the circle around features if configured. Without Group by, a single entry. The checkboxes in the legend only switch entries off temporarily, in your browser.
Background map. Choose Raster (a tile URL with {z}/{x}/{y}, e.g. https://tile.openstreetmap.org/{z}/{x}/{y}.png) or Vector (a style URL, e.g. https://tiles.openfreemap.org/styles/positron) and enter the URL; it is applied right away. A vector URL is checked first. Stored in your browser; the default is set in the viewer configuration.
Who may edit¶
Saving and resetting layer styles is allowed for anyone who reaches the viewer when VIEWER_READ_ONLY is false. That is the default with make dev only; make up and plain docker compose up start the viewer read-only. Read-only, the layer settings still preview changes but can't be saved. Style the layers locally and copy their style.json files to the server, see Production deployment.
Showing layers and changing the background map are always allowed; they only affect the visitor's own browser.
Viewer configuration¶
viewer/viewer.yaml, baked into the image as /app/viewer.yaml; another file can be used via VIEWER_CONFIG. Checked against viewer/server/config.schema.json when the server starts. A broken file stops the server with a list of the problems.
| Section | Content |
|---|---|
site |
Title, subtitle, introduction (shown in About; blank line = new paragraph) |
map |
default_project (id; empty = the first by title), initial_view when nothing is shown |
basemap |
default (type raster or vector, url), examples shown in Settings, raster_attribution |
style_defaults |
Colour palette and starting values for layers without a saved style, including the heat map's radius, intensity, opacity, default colour map and the colour-map presets (heatmap.ramps) |
labels |
Display names of rule statuses and marker shapes |
In development (make dev) the viewer/ folder is mounted and changes apply on the next page load.
Style format¶
layers/<id>/style.json, schema viewer/server/style.schema.json. It refers to the layer's attributes and value keys from layer.json. categories is in legend order; filter maps attributes to the values to show:
{
"version": 1,
"title": "Underground hydrants",
"filter": { "type": ["underground"] },
"color_by": "status",
"categories": {
"candidate_covered": {"color": "#f2a65a"},
"candidate_gap": {"color": "#d9480f", "label": "Gap: fountain would help"},
"excluded": {"color": "#868e96", "hidden": true}
},
"other_color": "#adb5bd",
"shape": "circle", "size": 8, "stroke_color": "#ffffff", "stroke_width": 1,
"render": "markers",
"heatmap": { "weight": "weight", "radius": 22, "intensity": 1, "opacity": 0.8,
"colors": ["#440154", "#3b528b", "#21918c", "#5ec962", "#fde725"] },
"buffer": { "radius_m": 300, "radius_parameter": "walking_distance_m", "attribute": "public", "value": "true", "opacity": 0.08 },
"popup": { "title": "status", "rules": ["excluded_by"], "rows": ["type", "position"], "osm_tags": true }
}
If a re-export removes an attribute the style refers to, the viewer ignores that part of the style and falls back to defaults.
Server API¶
Used by the web app; handy for scripting.
| Endpoint | Purpose |
|---|---|
GET /api/config |
Docs URL, read-only flag, viewer configuration |
GET /api/layers |
All layers with summary and validity |
GET /api/layers/<id> |
The layer's layer.json |
GET /api/layers/<id>/data.geojson |
Download of the features |
GET /api/layers/<id>/tiles.pmtiles |
Vector tiles (built when missing or outdated; supports range requests) |
GET/PUT/DELETE /api/layers/<id>/style |
The layer's style (PUT/DELETE refused when read-only) |
POST /api/layers/<id>/counts |
Features per value after a filter: {"by": "status", "filter": {"type": ["underground"]}} → {"total", "counts"} (for the legend) |
Files¶
| Path | Content |
|---|---|
viewer/server/app.py |
Server (Starlette): API, tiles (tippecanoe), static files |
viewer/server/style.schema.json |
Style format |
viewer/web/src/app.js |
Map, legend, popups, About |
viewer/web/src/styles.js |
Default styles, style → MapLibre layers, marker shapes |
viewer/web/src/settings.js |
Settings dialog and layer configuration |
viewer/viewer.yaml |
Viewer configuration (site texts, defaults) |
viewer/server/config.schema.json |
Its schema |
viewer/web/src/config.js |
Holds the configuration in the browser (filled from /api/config) |