jeroen/cartopolis

Watch

Fork 0

PDOK aerial imagery: is it worth wiring in? #175

New issue

Closed

opened 2026-08-29 16:54:21 +00:00 by viberfox-agent · 7 comments

viberfox-agent commented

2026-08-29 16:54:21 +00:00

Collaborator

Problem

docs/direction.md:53 lists PDOK aerial imagery as an unverified frontier candidate. The first half of this ticket was to check the interface, the licence and the cost. All three check out, so it is worth doing — and it is much cheaper than the ticket assumed.

The interface exists and is already the shape this client consumes. PDOK's Luchtfoto RGB WMTS publishes a RESTful ResourceURL that is an ordinary XYZ template:

https://service.pdok.nl/hwh/luchtfotorgb/wmts/v1_0/{Layer}/EPSG:3857/{z}/{x}/{y}.jpeg

Probed from this container on 2026-08-29 (four curls, Groningen and Berlin):

fact	measured
status / type	`200`, `image/jpeg`, 256×256
body size	26,690 B (orthoHR z18), 36,349 B (ortho25 z14), 14,240 B (z20)
CORS	`Access-Control-Allow-Origin: *`
caching	`Cache-Control: public, max-age=259200`, `ETag`, `Last-Modified`
zoom identifiers	unpadded (`14`, `18`, `20`, `21` all resolve)
outside NL (Berlin z14)	`200` + a 1,651-byte near-uniform JPEG — not a 404

GetCapabilities lists Actueel_orthoHR, Actueel_ortho25 and per-year layers back to 2016, all image/jpeg, all offering EPSG:3857 and OGC:1.0:GoogleMapsCompatible at z00–z21, 256 px.

That template drops straight into the existing plumbing: format_osm_tile_url (crates/core/src/world.rs:60) substitutes {z}/{x}/{y} verbatim, tile_source_kind (crates/core/src/world.rs:91) classifies a .jpeg tail as Raster, looks_like_raster already recognises the JPEG magic (crates/geo/src/vector_tiles.rs:4191), and image is built with the jpeg feature (Cargo.toml:163).

The licence is clear. The imagery is CC BY 4.0 (PDOK Luchtfoto RGB (Open)), free for all applications, with a request to reference beeldmateriaal.nl. Caching and redistributing derived pixels are permitted; the obligation is the credit. No rate limit is published.

It changes the picture, and the reason is specific. The flat clipmap runs z10 (map_stream.rs:61) up to the anchor zoom of 17 (map_stream.rs:395), but Shortbread stops at MAX_SOURCE_ZOOM = 14 (crates/geo/src/vector_tiles.rs:260) — so z15–z17 are magnified z14 renders, 179 of a fresh anchor's 424 tiles (docs/notes/tile-raster-cost.md). PDOK serves those zooms natively. And the ground texture is genuinely visible: tessellate_surfaces only meshes ocean/water_polygons, sites and grouped land features (crates/geo/src/vector_tiles.rs:1629-1633), so the imagery is the backdrop between the polygons, as tile-raster-cost.md states.

What is missing is only the wiring. There is one tile template for the whole client, OsmTileUrlTemplate, and every consumer reads it (map_stream.rs:874, map_geometry.rs:805, globe.rs:1539, navigation.rs:592). There is no per-consumer source and no aerial toggle anywhere in DataLayers (data_layers.rs:456-660).

The ticket's suggested shape — an extractor under tools/ plus a coverage manifest — is the wrong one here, and this is a deliberate deviation. The five surveyed extractors exist because their sources are WFS/GML needing RD→WGS84 reprojection and tessellation (docs/notes/where-the-map-data-is-built.md), and they now live in cartopy anyway. Imagery needs none of that: it is already tiled, already Web Mercator, already CDN-cached, and already CORS-open. Mirroring it is also not affordable — the Netherlands at z20 is on the order of 78 million tiles at ~20 KB, i.e. ~1.5 TB, against a VPS that also hosts nominatim, overpass and the tile server. The in-tree precedent for exactly this is the height layer: systems::height reaches service.pdok.nl directly from the client with an envelope constant for coverage and a Layers toggle that is off by default (height.rs:53, height.rs:60-61, data_layers.rs:823). Aerial imagery is the same case with a simpler payload.

Approach

One crate, cartopolis. No wire-protocol change, no schema change, no new dependency.

1. A source constant and its coverage envelope — new crates/cartopolis/src/systems/map/aerial.rs.
Mirror height.rs's head: the PDOK origin, the layer identifier, the template, and a lat/lng envelope. Coverage must be an envelope rather than an HTTP status, because the probe above shows PDOK answers 200 with a blank JPEG outside the Netherlands — a status check would paper the whole planet in grey. Reuse height.rs:60-61's AHN box or state a Luchtfoto one from the WMTS WGS84BoundingBox; they are the same country.

Default layer: Actueel_ortho25, behind a CARTO_AERIAL_LAYER env override. The reasoning, so it is not re-litigated: the clipmap tops out at z17 (map_stream.rs:395), whose ground scale at 53° N is ~0.36 m/px at tile_px = 512 and ~0.71 m/px at 256 — 25 cm source is already finer than the target, so Actueel_orthoHR's 8 cm would be oversampled 4–5×; and ortho25 is the summer flight, which matches the foliage systems::vegetation draws on top, where orthoHR is winter and leaf-off.

2. Choose the template per tile — map_stream::spawn_map_tile (map_stream.rs:449).
It already takes template: String and hands it to fetch_tile_payload (map_stream.rs:482). Pick the aerial template instead when the toggle is on and the tile's centre is inside the envelope; otherwise pass what it passes today. Everything downstream is unchanged: fetch_tile_payload (tile_loader.rs:422) takes the Raster arm, decode_tile_image (tile_loader.rs:405) is already bounded by MAX_TILE_EDGE_PX, and the finished pixels ride the same apply_stream_textures path (map_stream.rs:1100), which is bounded in both items (MAX_UPLOADS_PER_FRAME) and bytes (quality::upload_ceiling). Ground sampling is unchanged (tile_loader.rs:23).

Only map_stream changes source. map_geometry, globe, navigation and the router keep the vector template; the globe because the Netherlands is a few pixels from orbit, the rest because they need MVT geometry, not pixels.

3. Fix the cache-key collision this creates — tile_source.rs.
tile_cache_key writes tiles/{z}/{x}/{y}.png for anything Raster (tile_source.rs:45-51) and the in-memory CacheKey is (TileKey, TileSourceKind) (tile_source.rs:66-70). Two raster sources at one key collide — on disk and in memory — and a raster basemap is reachable today via CARTO_TILE_URL and is what an unconfigured --shot falls back to. The key must gain the source's identity (a short stable slug, not the whole URL) before a second raster source exists.

4. The toggle — data_layers.rs.
Add aerial_enabled: bool, default false, next to height_enabled (data_layers.rs:555, default at :823) and with the same reason in its doc comment. A Map-group row beside the height row (data_layers.rs:2460), and a field in LayerPrefs (user_store.rs:258) so it persists. Flipping it must retear the standing tiles — reuse the generation bump the re-anchor path already uses (map_stream.rs:310-336, spawn_map_tile's live_gen at :454), not a full re-anchor.

5. Attribution — LICENSE-THIRD-PARTY.md.
A record beside the AHN one (LICENSE-THIRD-PARTY.md:85-91): license: CC BY 4.0, url: https://www.beeldmateriaal.nl/, a notice: crediting Beeldmateriaal Nederland / PDOK, scope: Netherlands only. The Settings panel renders it and settings.rs:1740 guards the file against trimming.

6. Headless opt-in and a metric — lib.rs, shot_harness.rs.
An --aerial flag copying --height verbatim (lib.rs:199, applied at lib.rs:1869), because a scripted run has no Layers panel. One ShotMetrics field, aerial_tiles: usize — the count of standing clipmap tiles textured from the aerial source — which appears in the shot state line, --csv and --dump-state at once, and is therefore assertable with --expect.

7. A note — docs/notes/.
Record the four probe measurements above (with the date and the curl that produced them), the blank-tile-outside-NL behaviour, the licence, the ortho25-vs-orthoHR reasoning, and why there is no extractor. Update the docs/direction.md:53 row from candidate to wired.

Acceptance criteria

DataLayers::aerial_enabled exists, defaults to false, is a Map-group row in the Layers panel, and round-trips through LayerPrefs / data/user.json.
With the toggle off, the aerial template is never formatted and no request reaches service.pdok.nl from map_stream — the default picture and the default request set are byte-for-byte what they are on main.
With the toggle on, clipmap tiles whose centre falls inside the coverage envelope are textured from the PDOK template; tiles outside it fall back to the vector basemap in the same frame, with no gap and no placeholder left standing.
Coverage is decided by the envelope constant, not by HTTP status or by inspecting the returned pixels.
map_geometry, globe, navigation and the routing corridor still read OsmTileUrlTemplate; routing, street labels, water shading and both building streamers behave identically with the toggle on and off.
tile_source::tile_cache_key and tile_source::CacheKey distinguish two raster sources, with a unit test in tile_source.rs's existing module alongside cache_keys_separate_by_source_kind (tile_source.rs:407) asserting that two raster templates do not share bytes.
Flipping the toggle retears the standing tiles through the existing generation bump; no re-anchor, and no unbounded despawn or upload burst (the existing MAX_TILE_DESPAWNS_PER_FRAME and quality::upload_ceiling bounds still apply and are not bypassed).
--aerial sets the toggle for a scripted run, and ShotMetrics::aerial_tiles is present in the shot state line, the --csv header (shot_harness.rs:783) and --dump-state.
LICENSE-THIRD-PARTY.md carries a Beeldmateriaal / PDOK record with a non-empty notice: and license: CC BY 4.0, and settings.rs's notice tests still pass.
A docs/notes/ file records the interface, the licence, the probe measurements with their date, and the no-extractor decision; docs/direction.md:53 moves out of the candidates table into Wired.
cargo fmt --check over the workspace is clean.

Verification

Runnable here (this container renders headlessly on lavapipe):

cargo test -p cartopolis
cargo test -p cartopolis_core
cargo fmt --check

# Off by default: the metric must be zero and no PDOK request made.
cargo run -p cartopolis -- --shot /tmp/aerial_off.png \
    --at 53.2194,6.5665,400 --look=-45,0 --hide-ui \
    --dump-state /tmp/off.json --expect 'aerial_tiles==0'

# On: tiles must actually arrive and settle.
cargo run -p cartopolis -- --aerial --shot /tmp/aerial_on.png \
    --at 53.2194,6.5665,400 --look=-45,0 --hide-ui \
    --dump-state /tmp/on.json --expect 'settled==true' --expect 'aerial_tiles>0'

# Outside the envelope the fallback must hold, not blank the ground.
cargo run -p cartopolis -- --aerial --shot /tmp/berlin.png \
    --at 52.5200,13.4050,400 --look=-45,0 --hide-ui \
    --dump-state /tmp/berlin.json --expect 'aerial_tiles==0' --expect 'settled==true'

Diff /tmp/off.json against /tmp/on.json for gpu_resident_kb, upload_peak_asset_kb, draws and settled_s — a 256² JPEG per tile against a 512² RGBA render should reduce resident bytes on the desktop rung, and any increase is a finding.

Only a workstation can judge, and none of it is a gate here (docs/notes/headless-shots-software-renderer.md: colour and exposure are not evidence on this rasteriser):

Whether a photographic backdrop reads well under the drawn land / water / sites polygons at street level.
The texel-density trade: PDOK's 256 px tile is ~0.71 m/px at z17 against the current 512 px vector render's ~0.36 m/px. Real ground detail at half the sampling — a look call, and the input to whether the toggle should ever become default-on.
Actueel_ortho25 (summer, 25 cm) against Actueel_orthoHR (winter, 8 cm) side by side, via CARTO_AERIAL_LAYER.
Android: the phone rung already renders at tile_px = 256, so aerial matches it exactly there — worth one run on the VPS emulator (android-emulator-on-the-vps) to confirm the toggle survives quality::handset_guarded.

Out of scope

Any extractor, coverage manifest or self-hosted mirror. PDOK is fetched directly, for the reasons in Problem. systems::coverage's CoverageSlot is not used and gains no slot.
The globe tier. globe.rs keeps the planet-wide vector source; the Netherlands is not resolvable from orbit.
Suppressing or restyling the drawn surface polygons over aerial cells. The land / water / sites meshes keep drawing exactly as they do now. Deciding whether a park should stop being painted green over a photograph of itself is a look pass, and a separate ticket.
Making aerial the default basemap. It ships off, like height_enabled.
The infrared, per-year and quick-ortho layers, historical imagery, and any time-slider over the 2016→2026 archive.
A web-build proxy. PDOK answers Access-Control-Allow-Origin: *, so http::upstream_url (platform/http.rs:56) is not needed and no Trunk.toml / Caddy path mount is added — unlike AHN, which needed one (height.rs:543).
Any change to PROTOCOL_HISTORY or the SQLite schema. Neither is touched.

Open questions

None.

Branch: feat/175-pdok-aerial-basemap

Original request

From the frontier in docs/direction.md: PDOK aerial imagery — true-colour ground at the scale the drawn map cannot reach.

The first half of this ticket is deciding whether it is worth doing at all:

Is there an interface a client or an extractor can use, and what does it cost per cell?
Does the licence allow redistributing what we would cache?
Does it change the picture, or only the data behind it?

Not worth it is a valid answer. Record it in docs/direction.md against this row
with the reason, and close this ticket — that is the result, not a failure.

If it is worth doing, follow the shape the surveyed layers already use:
an extractor under tools/, a coverage manifest, a streamer that adds to what
is drawn rather than replacing it, and no unbounded per-frame upload.

_{Filed by the autopilot.}

_{🤖 Refined by the viberfox issue agent. Reply with @agent refine and what is wrong to have this rewritten.}

## Problem `docs/direction.md:53` lists **PDOK aerial imagery** as an unverified frontier candidate. The first half of this ticket was to check the interface, the licence and the cost. All three check out, so it is worth doing — and it is much cheaper than the ticket assumed. **The interface exists and is already the shape this client consumes.** PDOK's Luchtfoto RGB WMTS publishes a `RESTful` ResourceURL that is an ordinary XYZ template: ``` https://service.pdok.nl/hwh/luchtfotorgb/wmts/v1_0/{Layer}/EPSG:3857/{z}/{x}/{y}.jpeg ``` Probed from this container on 2026-08-29 (four `curl`s, Groningen and Berlin): | fact | measured | |---|---| | status / type | `200`, `image/jpeg`, 256×256 | | body size | 26,690 B (orthoHR z18), 36,349 B (ortho25 z14), 14,240 B (z20) | | CORS | `Access-Control-Allow-Origin: *` | | caching | `Cache-Control: public, max-age=259200`, `ETag`, `Last-Modified` | | zoom identifiers | unpadded (`14`, `18`, `20`, `21` all resolve) | | outside NL (Berlin z14) | `200` + a 1,651-byte near-uniform JPEG — **not** a 404 | `GetCapabilities` lists `Actueel_orthoHR`, `Actueel_ortho25` and per-year layers back to 2016, all `image/jpeg`, all offering `EPSG:3857` and `OGC:1.0:GoogleMapsCompatible` at z00–z21, 256 px. That template drops straight into the existing plumbing: `format_osm_tile_url` (`crates/core/src/world.rs:60`) substitutes `{z}/{x}/{y}` verbatim, `tile_source_kind` (`crates/core/src/world.rs:91`) classifies a `.jpeg` tail as `Raster`, `looks_like_raster` already recognises the JPEG magic (`crates/geo/src/vector_tiles.rs:4191`), and `image` is built with the `jpeg` feature (`Cargo.toml:163`). **The licence is clear.** The imagery is CC BY 4.0 ([PDOK Luchtfoto RGB (Open)](https://www.pdok.nl/introductie/-/article/pdok-luchtfoto-rgb-open-)), free for all applications, with a request to reference `beeldmateriaal.nl`. Caching and redistributing derived pixels are permitted; the obligation is the credit. No rate limit is published. **It changes the picture, and the reason is specific.** The flat clipmap runs z10 (`map_stream.rs:61`) up to the anchor zoom of 17 (`map_stream.rs:395`), but Shortbread stops at `MAX_SOURCE_ZOOM = 14` (`crates/geo/src/vector_tiles.rs:260`) — so **z15–z17 are magnified z14 renders**, 179 of a fresh anchor's 424 tiles (`docs/notes/tile-raster-cost.md`). PDOK serves those zooms natively. And the ground texture is genuinely visible: `tessellate_surfaces` only meshes `ocean`/`water_polygons`, `sites` and grouped `land` features (`crates/geo/src/vector_tiles.rs:1629-1633`), so the imagery is the backdrop between the polygons, as `tile-raster-cost.md` states. **What is missing is only the wiring.** There is one tile template for the whole client, `OsmTileUrlTemplate`, and every consumer reads it (`map_stream.rs:874`, `map_geometry.rs:805`, `globe.rs:1539`, `navigation.rs:592`). There is no per-consumer source and no aerial toggle anywhere in `DataLayers` (`data_layers.rs:456-660`). **The ticket's suggested shape — an extractor under `tools/` plus a coverage manifest — is the wrong one here, and this is a deliberate deviation.** The five surveyed extractors exist because their sources are WFS/GML needing RD→WGS84 reprojection and tessellation (`docs/notes/where-the-map-data-is-built.md`), and they now live in cartopy anyway. Imagery needs none of that: it is already tiled, already Web Mercator, already CDN-cached, and already CORS-open. Mirroring it is also not affordable — the Netherlands at z20 is on the order of 78 million tiles at ~20 KB, i.e. ~1.5 TB, against a VPS that also hosts nominatim, overpass and the tile server. The in-tree precedent for exactly this is the **height layer**: `systems::height` reaches `service.pdok.nl` directly from the client with an envelope constant for coverage and a Layers toggle that is off by default (`height.rs:53`, `height.rs:60-61`, `data_layers.rs:823`). Aerial imagery is the same case with a simpler payload. ## Approach One crate, `cartopolis`. No wire-protocol change, no schema change, no new dependency. **1. A source constant and its coverage envelope — new `crates/cartopolis/src/systems/map/aerial.rs`.** Mirror `height.rs`'s head: the PDOK origin, the layer identifier, the template, and a lat/lng envelope. Coverage **must** be an envelope rather than an HTTP status, because the probe above shows PDOK answers `200` with a blank JPEG outside the Netherlands — a status check would paper the whole planet in grey. Reuse `height.rs:60-61`'s AHN box or state a Luchtfoto one from the WMTS `WGS84BoundingBox`; they are the same country. Default layer: **`Actueel_ortho25`**, behind a `CARTO_AERIAL_LAYER` env override. The reasoning, so it is not re-litigated: the clipmap tops out at z17 (`map_stream.rs:395`), whose ground scale at 53° N is ~0.36 m/px at `tile_px = 512` and ~0.71 m/px at 256 — 25 cm source is already finer than the target, so `Actueel_orthoHR`'s 8 cm would be oversampled 4–5×; and ortho25 is the summer flight, which matches the foliage `systems::vegetation` draws on top, where orthoHR is winter and leaf-off. **2. Choose the template per tile — `map_stream::spawn_map_tile` (`map_stream.rs:449`).** It already takes `template: String` and hands it to `fetch_tile_payload` (`map_stream.rs:482`). Pick the aerial template instead when the toggle is on and the tile's centre is inside the envelope; otherwise pass what it passes today. Everything downstream is unchanged: `fetch_tile_payload` (`tile_loader.rs:422`) takes the `Raster` arm, `decode_tile_image` (`tile_loader.rs:405`) is already bounded by `MAX_TILE_EDGE_PX`, and the finished pixels ride the same `apply_stream_textures` path (`map_stream.rs:1100`), which is bounded in **both** items (`MAX_UPLOADS_PER_FRAME`) and bytes (`quality::upload_ceiling`). Ground sampling is unchanged (`tile_loader.rs:23`). **Only `map_stream` changes source.** `map_geometry`, `globe`, `navigation` and the router keep the vector template; the globe because the Netherlands is a few pixels from orbit, the rest because they need MVT geometry, not pixels. **3. Fix the cache-key collision this creates — `tile_source.rs`.** `tile_cache_key` writes `tiles/{z}/{x}/{y}.png` for anything `Raster` (`tile_source.rs:45-51`) and the in-memory `CacheKey` is `(TileKey, TileSourceKind)` (`tile_source.rs:66-70`). Two raster sources at one key collide — on disk and in memory — and a raster basemap is reachable today via `CARTO_TILE_URL` and is what an unconfigured `--shot` falls back to. The key must gain the source's identity (a short stable slug, not the whole URL) before a second raster source exists. **4. The toggle — `data_layers.rs`.** Add `aerial_enabled: bool`, default `false`, next to `height_enabled` (`data_layers.rs:555`, default at `:823`) and with the same reason in its doc comment. A Map-group row beside the height row (`data_layers.rs:2460`), and a field in `LayerPrefs` (`user_store.rs:258`) so it persists. Flipping it must retear the standing tiles — reuse the generation bump the re-anchor path already uses (`map_stream.rs:310-336`, `spawn_map_tile`'s `live_gen` at `:454`), not a full re-anchor. **5. Attribution — `LICENSE-THIRD-PARTY.md`.** A record beside the AHN one (`LICENSE-THIRD-PARTY.md:85-91`): `license: CC BY 4.0`, `url: https://www.beeldmateriaal.nl/`, a `notice:` crediting Beeldmateriaal Nederland / PDOK, `scope: Netherlands only`. The Settings panel renders it and `settings.rs:1740` guards the file against trimming. **6. Headless opt-in and a metric — `lib.rs`, `shot_harness.rs`.** An `--aerial` flag copying `--height` verbatim (`lib.rs:199`, applied at `lib.rs:1869`), because a scripted run has no Layers panel. One `ShotMetrics` field, `aerial_tiles: usize` — the count of standing clipmap tiles textured from the aerial source — which appears in the `shot state` line, `--csv` and `--dump-state` at once, and is therefore assertable with `--expect`. **7. A note — `docs/notes/`.** Record the four probe measurements above (with the date and the `curl` that produced them), the blank-tile-outside-NL behaviour, the licence, the ortho25-vs-orthoHR reasoning, and why there is no extractor. Update the `docs/direction.md:53` row from candidate to wired. ## Acceptance criteria - [ ] `DataLayers::aerial_enabled` exists, defaults to `false`, is a Map-group row in the Layers panel, and round-trips through `LayerPrefs` / `data/user.json`. - [ ] With the toggle off, the aerial template is never formatted and no request reaches `service.pdok.nl` from `map_stream` — the default picture and the default request set are byte-for-byte what they are on `main`. - [ ] With the toggle on, clipmap tiles whose centre falls inside the coverage envelope are textured from the PDOK template; tiles outside it fall back to the vector basemap in the same frame, with no gap and no placeholder left standing. - [ ] Coverage is decided by the envelope constant, not by HTTP status or by inspecting the returned pixels. - [ ] `map_geometry`, `globe`, `navigation` and the routing corridor still read `OsmTileUrlTemplate`; routing, street labels, water shading and both building streamers behave identically with the toggle on and off. - [ ] `tile_source::tile_cache_key` and `tile_source::CacheKey` distinguish two raster sources, with a unit test in `tile_source.rs`'s existing module alongside `cache_keys_separate_by_source_kind` (`tile_source.rs:407`) asserting that two raster templates do not share bytes. - [ ] Flipping the toggle retears the standing tiles through the existing generation bump; no re-anchor, and no unbounded despawn or upload burst (the existing `MAX_TILE_DESPAWNS_PER_FRAME` and `quality::upload_ceiling` bounds still apply and are not bypassed). - [ ] `--aerial` sets the toggle for a scripted run, and `ShotMetrics::aerial_tiles` is present in the `shot state` line, the `--csv` header (`shot_harness.rs:783`) and `--dump-state`. - [ ] `LICENSE-THIRD-PARTY.md` carries a Beeldmateriaal / PDOK record with a non-empty `notice:` and `license: CC BY 4.0`, and `settings.rs`'s notice tests still pass. - [ ] A `docs/notes/` file records the interface, the licence, the probe measurements with their date, and the no-extractor decision; `docs/direction.md:53` moves out of the candidates table into **Wired**. - [ ] `cargo fmt --check` over the workspace is clean. ## Verification Runnable here (this container renders headlessly on lavapipe): ```bash cargo test -p cartopolis cargo test -p cartopolis_core cargo fmt --check # Off by default: the metric must be zero and no PDOK request made. cargo run -p cartopolis -- --shot /tmp/aerial_off.png \ --at 53.2194,6.5665,400 --look=-45,0 --hide-ui \ --dump-state /tmp/off.json --expect 'aerial_tiles==0' # On: tiles must actually arrive and settle. cargo run -p cartopolis -- --aerial --shot /tmp/aerial_on.png \ --at 53.2194,6.5665,400 --look=-45,0 --hide-ui \ --dump-state /tmp/on.json --expect 'settled==true' --expect 'aerial_tiles>0' # Outside the envelope the fallback must hold, not blank the ground. cargo run -p cartopolis -- --aerial --shot /tmp/berlin.png \ --at 52.5200,13.4050,400 --look=-45,0 --hide-ui \ --dump-state /tmp/berlin.json --expect 'aerial_tiles==0' --expect 'settled==true' ``` Diff `/tmp/off.json` against `/tmp/on.json` for `gpu_resident_kb`, `upload_peak_asset_kb`, `draws` and `settled_s` — a 256² JPEG per tile against a 512² RGBA render should *reduce* resident bytes on the desktop rung, and any increase is a finding. **Only a workstation can judge, and none of it is a gate here** (`docs/notes/headless-shots-software-renderer.md`: colour and exposure are not evidence on this rasteriser): - Whether a photographic backdrop reads well under the drawn `land` / `water` / `sites` polygons at street level. - The texel-density trade: PDOK's 256 px tile is ~0.71 m/px at z17 against the current 512 px vector render's ~0.36 m/px. Real ground detail at half the sampling — a look call, and the input to whether the toggle should ever become default-on. - `Actueel_ortho25` (summer, 25 cm) against `Actueel_orthoHR` (winter, 8 cm) side by side, via `CARTO_AERIAL_LAYER`. - Android: the phone rung already renders at `tile_px = 256`, so aerial matches it exactly there — worth one run on the VPS emulator (`android-emulator-on-the-vps`) to confirm the toggle survives `quality::handset_guarded`. ## Out of scope - **Any extractor, coverage manifest or self-hosted mirror.** PDOK is fetched directly, for the reasons in Problem. `systems::coverage`'s `CoverageSlot` is not used and gains no slot. - **The globe tier.** `globe.rs` keeps the planet-wide vector source; the Netherlands is not resolvable from orbit. - **Suppressing or restyling the drawn surface polygons over aerial cells.** The `land` / `water` / `sites` meshes keep drawing exactly as they do now. Deciding whether a park should stop being painted green over a photograph of itself is a look pass, and a separate ticket. - **Making aerial the default basemap.** It ships off, like `height_enabled`. - **The infrared, per-year and quick-ortho layers**, historical imagery, and any time-slider over the 2016→2026 archive. - **A web-build proxy.** PDOK answers `Access-Control-Allow-Origin: *`, so `http::upstream_url` (`platform/http.rs:56`) is not needed and no `Trunk.toml` / Caddy path mount is added — unlike AHN, which needed one (`height.rs:543`). - **Any change to `PROTOCOL_HISTORY` or the SQLite schema.** Neither is touched. ## Open questions None. --- Branch: `feat/175-pdok-aerial-basemap` <details><summary>Original request</summary> From the frontier in [`docs/direction.md`](../src/branch/main/docs/direction.md): **PDOK aerial imagery** — true-colour ground at the scale the drawn map cannot reach. The first half of this ticket is deciding whether it is worth doing at all: - Is there an interface a client or an extractor can use, and what does it cost per cell? - Does the licence allow redistributing what we would cache? - Does it change the picture, or only the data behind it? **Not worth it is a valid answer.** Record it in `docs/direction.md` against this row with the reason, and close this ticket — that is the result, not a failure. If it is worth doing, follow the shape the surveyed layers already use: an extractor under `tools/`, a coverage manifest, a streamer that adds to what is drawn rather than replacing it, and no unbounded per-frame upload. Filed by the autopilot.  </details> 🤖 Refined by the viberfox issue agent. Reply with **@agent refine** and what is wrong to have this rewritten.

viberfox-agent added the

labels

2026-08-29 16:54:21 +00:00

viberfox-agent added this to the Viberfox project

2026-08-29 16:54:50 +00:00

viberfox-agent commented

2026-08-29 16:54:58 +00:00

Author

Collaborator

🤖 Refining this before anything gets built — reading the code, no branch, no commits. If it turns out I'd have to guess at the requirements I'll stop and ask instead.

viberfox-agent added

agent:refined

and removed

agent:refining

labels

2026-08-29 17:02:03 +00:00

viberfox-agent commented

2026-08-29 17:02:03 +00:00

Author

Collaborator

🤖 Refined. The description above is now the spec; I'll pick it up for implementation on the next poll.

If the direction is wrong, say so now — @agent refine with a correction rewrites it, and agent:skip stops me.

_{🤖 viberfox issue agent on the VPS — 54 turns · $4.45 · session c1f2a760-a6c2-4ad9-9dd0-f3ac4d9bed84. Reply with @agent to continue this session.}

🤖 **Refined.** The description above is now the spec; I'll pick it up for implementation on the next poll. If the direction is wrong, say so now — **@agent refine** with a correction rewrites it, and `agent:skip` stops me. --- 🤖 viberfox issue agent on the VPS — 54 turns · $4.45 · session `c1f2a760-a6c2-4ad9-9dd0-f3ac4d9bed84`. Reply with **@agent** to continue this session.

viberfox-agent added

agent:running

and removed

agent:refined

labels

2026-08-29 17:02:21 +00:00

viberfox-agent commented

2026-08-29 17:02:27 +00:00

Author

Collaborator

🤖 Picked this up — working on branch feat/175-pdok-aerial-basemap in a fresh worktree on the VPS. I'll report back here when I'm done.

_{Label an issue agent:skip to keep me off it, or driven to keep it in a session you are driving.}

🤖 Picked this up — working on branch `feat/175-pdok-aerial-basemap` in a fresh worktree on the VPS. I'll report back here when I'm done. Label an issue `agent:skip` to keep me off it, or `driven` to keep it in a session you are driving.

viberfox-agent referenced this issue from a commit

2026-08-29 17:45:36 +00:00

feat(map): the ground can be a photograph, over the Netherlands

viberfox-agent commented

2026-08-29 17:46:05 +00:00

Author

Collaborator

Aerial photography is now a Layers toggle, off by default. With it on, the ground tiles over the Netherlands come from PDOK's Luchtfoto RGB instead of the drawn map; everywhere else, and with the toggle off, nothing changes.

What I changed

New file crates/cartopolis/src/systems/map/aerial.rs — the tile URL template, the layer identifier (Actueel_ortho25, overridable with CARTO_AERIAL_LAYER), and the coverage box.
map_stream picks the source per tile. It is the only consumer that switched. map_geometry, the globe, navigation and the router still read the vector template, so routing, street names, water shading and both building layers behave identically either way.
Fixed a cache collision this would otherwise have caused. The tile cache keyed only on "raster or vector", so the drawn map and the photograph would have shared one entry in memory and one path on disk, and whichever arrived first would have been served to the other. Tile identity now includes a short hash of the source URL. This orphans previously cached tiles once — they are re-fetched, and the existing size-bounded cache sweep reclaims the old files.
Flipping the toggle rebuilds only the ground tiles. I added a second counter rather than reusing the existing anchor counter, which sixteen other systems answer by rebuilding every building, the terrain and the weather.
Added: the --aerial command-line flag, an aerial_tiles count in the screenshot metrics, the setting saved to data/user.json, a Beeldmateriaal/PDOK credit in LICENSE-THIRD-PARTY.md, docs/notes/aerial-imagery.md, and manual/CLAUDE.md entries. docs/direction.md moves this row from candidates to wired.

Why it is worth doing

The drawn map's deepest source data is zoom 14, but the ground under the camera is drawn at zoom 17 — 179 of 424 tiles in a fresh view are magnified. PDOK has real photographs at those scales. It is CC BY 4.0, free, and allows caching. I re-ran the probes from the ticket on 2026-08-29 and they hold: a Groningen tile is 33 kB of JPEG, Access-Control-Allow-Origin: *, three-day cache headers. A Berlin tile answers 200 with a 1.6 kB blank image rather than a 404 — which is why coverage is a fixed box, not an HTTP check.

I also checked the service's own bounding box and rejected it: it covers −1.7° to 12.4° east and 48.0° to 56.1° north, i.e. most of Germany and half of France. That is the tile grid's extent, not where photographs exist. The box in the code is AHN's, which this client already uses for the same country.

How I verified it

cargo test -p cartopolis_core (52 passed), cargo test -p cartopolis_geo (196 passed), cargo test -p cartopolis (777 passed, 0 failed), cargo fmt --check clean across the workspace. Six of those tests are new, including the one the ticket asked for: two raster URLs must not share cached bytes or a cache path.

What is not verified

This container has no sound library installed, so I could only build with --no-default-features. That compiles everything I touched but leaves out the audio wiring. In that configuration ten pre-existing "never used" errors appear in voice.rs, traffic.rs and resources.rs — all audio-gated code, none in files I changed. Continuous integration builds with sound and will exercise the full crate.
I could not run a screenshot. The instructions for this session say the rendering harness does not work here, so I never attempted the three captures in the ticket. Nobody has seen an aerial tile in the app.
No run on Android.

For you to decide

Two look questions I deliberately did not answer, both written up in the new note:

The coarse-zoom border. A tile takes its source from its own centre, so a tile is never half photograph and half drawing — but the widest zoom level's tiles are about 39 km across, and one centred inside the Netherlands can still reach over Germany or the North Sea, where PDOK renders blank. If that reads badly at the edge of the view, the fix is to require the whole tile inside the box, or to use photographs only at close zooms.
Whether the drawn green parks, blue water and grey site polygons should keep being painted over a photograph of themselves. They currently do. That is a separate ticket.

Branch feat/175-pdok-aerial-basemap (pushed)

6bf16d7 feat(map): the ground can be a photograph, over the Netherlands

_{🤖 viberfox issue agent on the VPS — 219 turns · $24.97 · session 846a59e9-5872-4b55-a675-3e692f82aa87. Reply with @agent to continue this session.}

**Aerial photography is now a Layers toggle, off by default.** With it on, the ground tiles over the Netherlands come from PDOK's Luchtfoto RGB instead of the drawn map; everywhere else, and with the toggle off, nothing changes. ## What I changed - **New file `crates/cartopolis/src/systems/map/aerial.rs`** — the tile URL template, the layer identifier (`Actueel_ortho25`, overridable with `CARTO_AERIAL_LAYER`), and the coverage box. - **`map_stream` picks the source per tile.** It is the only consumer that switched. `map_geometry`, the globe, `navigation` and the router still read the vector template, so routing, street names, water shading and both building layers behave identically either way. - **Fixed a cache collision this would otherwise have caused.** The tile cache keyed only on "raster or vector", so the drawn map and the photograph would have shared one entry in memory and one path on disk, and whichever arrived first would have been served to the other. Tile identity now includes a short hash of the source URL. This orphans previously cached tiles once — they are re-fetched, and the existing size-bounded cache sweep reclaims the old files. - **Flipping the toggle rebuilds only the ground tiles.** I added a second counter rather than reusing the existing anchor counter, which sixteen other systems answer by rebuilding every building, the terrain and the weather. - Added: the `--aerial` command-line flag, an `aerial_tiles` count in the screenshot metrics, the setting saved to `data/user.json`, a Beeldmateriaal/PDOK credit in `LICENSE-THIRD-PARTY.md`, `docs/notes/aerial-imagery.md`, and manual/CLAUDE.md entries. `docs/direction.md` moves this row from candidates to wired. ## Why it is worth doing The drawn map's deepest source data is zoom 14, but the ground under the camera is drawn at zoom 17 — 179 of 424 tiles in a fresh view are magnified. PDOK has real photographs at those scales. It is CC BY 4.0, free, and allows caching. I re-ran the probes from the ticket on 2026-08-29 and they hold: a Groningen tile is 33 kB of JPEG, `Access-Control-Allow-Origin: *`, three-day cache headers. A Berlin tile answers `200` with a 1.6 kB blank image rather than a 404 — which is why coverage is a fixed box, not an HTTP check. I also checked the service's own bounding box and **rejected it**: it covers −1.7° to 12.4° east and 48.0° to 56.1° north, i.e. most of Germany and half of France. That is the tile grid's extent, not where photographs exist. The box in the code is AHN's, which this client already uses for the same country. ## How I verified it `cargo test -p cartopolis_core` (52 passed), `cargo test -p cartopolis_geo` (196 passed), `cargo test -p cartopolis` (777 passed, 0 failed), `cargo fmt --check` clean across the workspace. Six of those tests are new, including the one the ticket asked for: two raster URLs must not share cached bytes or a cache path. ## What is not verified - **This container has no sound library installed, so I could only build with `--no-default-features`.** That compiles everything I touched but leaves out the audio wiring. In that configuration ten pre-existing "never used" errors appear in `voice.rs`, `traffic.rs` and `resources.rs` — all audio-gated code, none in files I changed. Continuous integration builds with sound and will exercise the full crate. - **I could not run a screenshot.** The instructions for this session say the rendering harness does not work here, so I never attempted the three captures in the ticket. Nobody has seen an aerial tile in the app. - **No run on Android.** ## For you to decide Two look questions I deliberately did not answer, both written up in the new note: 1. **The coarse-zoom border.** A tile takes its source from its own centre, so a tile is never half photograph and half drawing — but the widest zoom level's tiles are about 39 km across, and one centred inside the Netherlands can still reach over Germany or the North Sea, where PDOK renders blank. If that reads badly at the edge of the view, the fix is to require the whole tile inside the box, or to use photographs only at close zooms. 2. **Whether the drawn green parks, blue water and grey site polygons should keep being painted over a photograph of themselves.** They currently do. That is a separate ticket. **Branch** `feat/175-pdok-aerial-basemap` (pushed) ``` 6bf16d7 feat(map): the ground can be a photograph, over the Netherlands ``` --- 🤖 viberfox issue agent on the VPS — 219 turns · $24.97 · session `846a59e9-5872-4b55-a675-3e692f82aa87`. Reply with **@agent** to continue this session.

viberfox-agent added

agent:done

and removed

agent:running

labels

2026-08-29 17:46:05 +00:00

viberfox-agent commented

2026-08-29 17:47:34 +00:00

Author

Collaborator

🤖 Marked agent:done without a CI verdict on 6bf16d70 — no workflow reported on this commit. The branch is waiting for review; check the run yourself before landing it.

🤖 Marked `agent:done` **without a CI verdict** on `6bf16d70` — no workflow reported on this commit. The branch is waiting for review; check the run yourself before landing it.

viberfox-agent referenced this issue from a pull request that will close it,

2026-08-29 17:51:05 +00:00

PDOK aerial imagery: is it worth wiring in? #179

viberfox-agent referenced this issue from a commit

2026-08-29 17:51:32 +00:00

fix(autopilot): open the pull request first — a branch push gets no CI at all

viberfox-agent referenced this issue

2026-08-29 18:00:11 +00:00

Autopilot log #181

viberfox-agent

2026-08-29 18:54:37 +00:00