feat(android): map polish — zoom-to-fit, photo markers at every count, bigger tiles, faster caching #1151

Merged
chris merged 6 commits from ux-android-map-polish into main 2026-10-12 17:33:42 +02:00
Owner

What

Four KARTE-tab polish items from user feedback, in priority order.

1. Zoom-to-fit on open + re-fit on scope chip change

What the bug actually was (chain verified against osmdroid 6.1.20 bytecode):

  1. The first AndroidView update runs pre-layout and re-applied the tile source through a throwaway arrayOfNulls(1) key → setTileSource → MapView.setTileLevel → setZoomLevel unconditionally dispatches a ZoomEvent to our MapListener.
  2. emitViewport answered by reading the bounding box of the not-yet-laid-out (0×0) projection → a degenerate world box at zoom 2.
  3. That poisoned lastViewport, so savedCamera() returned non-null garbage that shadowed state.initialCamera in the camera block.
  4. zoomToSpan(0.0, 0.0) is a silent no-op in osmdroid (any latSpan <= 0 returns early) and animateTo((0, 0)) no-ops too → the camera sat at the factory's world zoom (2.0) at (0,0) forever, and every re-entry stayed poisoned until the user manually panned.

Fix: a pure fitToBounds(south, west, north, east, width, height, padding, minZoom, maxZoom) in Web-Mercator (new MapCameraFit.kt, JVM-tested in MapCameraFitTest: binding axis, padding, clamps, Mercator centre, date-line wrap) applied atomically as setZoom + setCenter after layout (doOnLayout). emitViewport refuses zero-size views, and the factory seeds the shared appliedTileKey so the first update cannot re-apply the source. MapUiState.cameraEpoch is bumped whenever new bounds land, so the screen fits exactly once per epoch: the first fit prefers the remembered viewport, a scope-chip refit (setScope → new refitBounds()) fits the new box only; a failed refit keeps the camera quietly (the viewport re-cluster/banner still tells the user the scope changed).

Constants: 48 dp fit padding, min zoom = world (2.0), max = drill max (18). Drill-down untouched: tap still zooms +2 levels / opens the sheet; the larger icons make larger tap targets.

2. Photo thumbnails on EVERY marker, readable count on big clusters

  • Clusters photo at every count when any member has a photo URL (server's representative first, else the first member with a URL). Counts ≤ 9 keep the circle badge; above it the count becomes a readable pill on the 45° corner (clamped inside the canvas, ringed) — 10, 100, 1000 all show a photo plus a legible count.
  • No member with a photo URL → new neutral slate tile carrying the count pill. Never a bare count circle: a marker always says what it counts.
  • Reuses the MarkerThumbnails.kt plan/cache/render structure; cache keys gained the pill height so a resize can't hand back a stale bitmap.

3. Bigger markers, sizes named in one place

All in MarkerThumbnails.kt: photo tile 44 → 72 dp (radius 12 → 18), cluster photo 40 → 64 dp, corner badge 18 → 24 dp, new 26 dp count pill, new 48 dp placeholder badge (was a local 40.dp in the screen), new 72 dp neutral tile, decode target 160 → 256 px, icon bitmap cache 8 → 24 MB.

4. Faster tiles: explicit cache config + bounded prefetch

New MapTileCache.kt (configureOsmdroid, run before the first MapView):

  • Cache location: filesDir/osmdroid/tiles, not cacheDir — private, always mounted, and survives cacheDir sweeps; a warm tile cache costs real data to rebuild. osmdroid's default (external storage) can be unmounted and sits in a shared tree.
  • 512 MB LRU cap / 384 MB trim (defaults 600/500), 4 download threads (default 2), 64-deep queue (default 40).
  • Ordering matters, documented from bytecode: Configuration.load rewrites the paths from shared preferences and lets persisted thread counts win over in-memory values → everything is set after load, correct on first run and every run after.
  • Timeouts: honestly none. osmdroid 6.1.20 exposes no connect/read timeout API anywhere (TileDownloader sets none; IConfigurationProvider has no setters). A stalled socket is bounded only by the queue — noted in code instead of faked.
  • Offline cache reads verified in bytecode: CacheManager.loadTile returns as soon as the file or SqlTileWriter knows the tile, before any download, and download failures are swallowed per tile by osmdroid (never surface as app exceptions).
  • Bounded, cancellable prefetch over the fitted bbox at zoom 8..13, budget 800 tiles (the cited bound: tens of MB, one sequential background connection on top of the map's own 4), ensureActive() between tiles — each applied fit cancels the previous warm-up, leaving the tab cancels the last; 6 consecutive failures (airplane mode, server down) abort.
  • First load still leans on whatever server stands behind the tile template; if the admin proxies tile.openstreetmap.org that is shared etiquette. A self-hosted tile server is the follow-up — deliberately not implemented here. No settings UI, per scope.

Verification

cd apps/android && ./gradlew :app:testDebugUnitTest :app:assembleDebug → green: 400 tests, 0 failures (+9 MapCameraFitTest, +3 scope-refit MapViewModelTest, marker plan/key coverage extended for NeutralTile / all-count ClusterPhoto / pill keys). Rebased onto latest origin/main and re-verified after. Lint untouched (pre-existing baseline). No new user-facing strings, so no res/ or locale changes (de/da/en unchanged).

Risks

  • The fit math is JVM-tested; its application inside osmdroid is not (ISSUE-132) — worth one on-device pass: open the tab, switch Alle/Meine, drill into a cluster.
  • Prefetch downloads tiles the user may never pan to; the 800-tile budget and tab-scoped cancellation cap it.
  • No HTTP timeout API means a stalled tile socket can hold a download slot until the queue rotates (osmdroid limitation, called out in code).
  • Marker hit areas grew with the icons (mostly a win; adjacent markers at max zoom can overlap a little more).

Commits: fix camera fit → feat marker plans/sizes → perf cache + prefetch → feat screen wiring → chore version bump (16/0.4.1 → 17/0.4.2, ledger updated).

## What Four KARTE-tab polish items from user feedback, in priority order. ### 1. Zoom-to-fit on open + re-fit on scope chip change **What the bug actually was** (chain verified against osmdroid 6.1.20 bytecode): 1. The first `AndroidView` update runs pre-layout and re-applied the tile source through a throwaway `arrayOfNulls(1)` key → `setTileSource` → `MapView.setTileLevel` → `setZoomLevel` **unconditionally dispatches a `ZoomEvent`** to our `MapListener`. 2. `emitViewport` answered by reading the bounding box of the not-yet-laid-out (0×0) projection → a degenerate world box at zoom 2. 3. That poisoned `lastViewport`, so `savedCamera()` returned non-null garbage that **shadowed** `state.initialCamera` in the camera block. 4. `zoomToSpan(0.0, 0.0)` is a silent no-op in osmdroid (any `latSpan <= 0` returns early) and `animateTo((0, 0))` no-ops too → the camera sat at the factory's world zoom (2.0) at (0,0) forever, and every re-entry stayed poisoned until the user manually panned. **Fix:** a pure `fitToBounds(south, west, north, east, width, height, padding, minZoom, maxZoom)` in Web-Mercator (new `MapCameraFit.kt`, JVM-tested in `MapCameraFitTest`: binding axis, padding, clamps, Mercator centre, date-line wrap) applied atomically as `setZoom` + `setCenter` after layout (`doOnLayout`). `emitViewport` refuses zero-size views, and the factory seeds the shared `appliedTileKey` so the first update cannot re-apply the source. `MapUiState.cameraEpoch` is bumped whenever new bounds land, so the screen fits exactly **once per epoch**: the first fit prefers the remembered viewport, a scope-chip refit (`setScope` → new `refitBounds()`) fits the new box only; a failed refit keeps the camera quietly (the viewport re-cluster/banner still tells the user the scope changed). Constants: 48 dp fit padding, min zoom = world (2.0), max = drill max (18). Drill-down untouched: tap still zooms +2 levels / opens the sheet; the larger icons make larger tap targets. ### 2. Photo thumbnails on EVERY marker, readable count on big clusters - Clusters photo at **every** count when any member has a photo URL (server's representative first, else the first member with a URL). Counts ≤ 9 keep the circle badge; above it the count becomes a **readable pill** on the 45° corner (clamped inside the canvas, ringed) — 10, 100, 1000 all show a photo plus a legible count. - No member with a photo URL → new **neutral slate tile** carrying the count pill. Never a bare count circle: a marker always says what it counts. - Reuses the `MarkerThumbnails.kt` plan/cache/render structure; cache keys gained the pill height so a resize can't hand back a stale bitmap. ### 3. Bigger markers, sizes named in one place All in `MarkerThumbnails.kt`: photo tile 44 → **72 dp** (radius 12 → 18), cluster photo 40 → **64 dp**, corner badge 18 → **24 dp**, new **26 dp** count pill, new **48 dp** placeholder badge (was a local `40.dp` in the screen), new 72 dp neutral tile, decode target 160 → **256 px**, icon bitmap cache 8 → **24 MB**. ### 4. Faster tiles: explicit cache config + bounded prefetch New `MapTileCache.kt` (`configureOsmdroid`, run before the first `MapView`): - **Cache location: `filesDir/osmdroid/tiles`, not `cacheDir`** — private, always mounted, and survives cacheDir sweeps; a warm tile cache costs real data to rebuild. osmdroid's default (external storage) can be unmounted and sits in a shared tree. - **512 MB LRU cap / 384 MB trim** (defaults 600/500), **4 download threads** (default 2), **64-deep queue** (default 40). - **Ordering matters**, documented from bytecode: `Configuration.load` rewrites the paths from shared preferences and lets persisted thread counts win over in-memory values → everything is set **after** `load`, correct on first run and every run after. - **Timeouts: honestly none.** osmdroid 6.1.20 exposes no connect/read timeout API anywhere (`TileDownloader` sets none; `IConfigurationProvider` has no setters). A stalled socket is bounded only by the queue — noted in code instead of faked. - **Offline cache reads verified** in bytecode: `CacheManager.loadTile` returns as soon as the file or `SqlTileWriter` knows the tile, *before* any download, and download failures are swallowed per tile by osmdroid (never surface as app exceptions). - **Bounded, cancellable prefetch** over the fitted bbox at zoom **8..13**, budget **800 tiles** (the cited bound: tens of MB, one sequential background connection on top of the map's own 4), `ensureActive()` between tiles — each applied fit cancels the previous warm-up, leaving the tab cancels the last; 6 consecutive failures (airplane mode, server down) abort. - First load still leans on whatever server stands behind the tile template; if the admin proxies `tile.openstreetmap.org` that is shared etiquette. **A self-hosted tile server is the follow-up — deliberately not implemented here.** No settings UI, per scope. ## Verification `cd apps/android && ./gradlew :app:testDebugUnitTest :app:assembleDebug` → **green: 400 tests, 0 failures** (+9 `MapCameraFitTest`, +3 scope-refit `MapViewModelTest`, marker plan/key coverage extended for NeutralTile / all-count ClusterPhoto / pill keys). Rebased onto latest `origin/main` and re-verified after. Lint untouched (pre-existing baseline). No new user-facing strings, so no `res/` or locale changes (de/da/en unchanged). ## Risks - The fit math is JVM-tested; its application inside osmdroid is not (ISSUE-132) — worth one on-device pass: open the tab, switch Alle/Meine, drill into a cluster. - Prefetch downloads tiles the user may never pan to; the 800-tile budget and tab-scoped cancellation cap it. - No HTTP timeout API means a stalled tile socket can hold a download slot until the queue rotates (osmdroid limitation, called out in code). - Marker hit areas grew with the icons (mostly a win; adjacent markers at max zoom can overlap a little more). Commits: `fix` camera fit → `feat` marker plans/sizes → `perf` cache + prefetch → `feat` screen wiring → `chore` version bump (16/0.4.1 → 17/0.4.2, ledger updated).
The map opened at world zoom and ignored the loaded bounds. The chain
(verified against osmdroid 6.1.20 bytecode): the first AndroidView update
re-applied the tile source through a throwaway key, setTileSource ran
before layout, MapView.setTileLevel dispatched a ZoomEvent to our
MapListener, emitViewport read a degenerate 0x0 bounding box at zoom 2 and
poisoned lastViewport — so the non-null garbage from savedCamera() shadowed
initialCamera, zoomToSpan(0.0, 0.0) silently no-oped and the camera stayed
at the factory's world zoom forever.

Replace it with a pure fitToBounds(south, west, north, east, size, pad,
min, max) in Web-Mercator (new MapCameraFit.kt, JVM-tested), applied
atomically as setZoom + setCenter. The ViewModel now bumps a cameraEpoch
whenever bounds change hands, so the screen fits once per epoch: first
fit prefers the remembered viewport, a scope-chip refit fits the new box.
setScope refetches bounds (silent failure keeps the camera) and emitViewport
refuses to report before layout, so a zero-size projection can never
pollute the saved camera again.
Marker plans no longer stop at a count limit: clusters photo at EVERY
count when any member carries a photo URL — up to 9 the badge stays a
circle, past it the count becomes a readable pill drawn on the 45° corner
(clamped inside the canvas, ringed in the shared near-white). A cluster
where no member has a photo URL falls back to a new neutral slate tile
carrying the pill, never a bare count circle, so a marker always says
what it is counting.

Sizes move to named constants in one place and grow for legibility:
photo tiles 44 -> 72 dp (radius 12 -> 18), cluster photo 40 -> 64 dp,
corner badge 18 -> 24, new 26 dp count pill, new 48 dp placeholder badge,
new 72 dp neutral tile; decode target 160 -> 256 px and the icon cache
8 -> 24 MB to match. Cache keys gain the pill height so a resize cannot
hand back a stale bitmap.
Configure osmdroid once per process before any tile work: cache lives in
filesDir/osmdroid/tiles (private, always mounted, survives cacheDir
sweeps — a warm tile cache is worth keeping), capped at 512 MB with a
384 MB LRU trim (defaults 600/500), 4 download threads with a 64-deep
queue (defaults 2/40). Everything is set AFTER Configuration.load: load
rewrites the paths from shared preferences and lets the persisted thread
counts win over in-memory values, so post-load is the only ordering that
sticks on first run and every run after.

New prefetchViewportTiles warms the fitted bounds over zoom 8..13,
sequential on Dispatchers.IO (one background connection), bounded by an
800-tile budget and cancellable between tiles — each applied fit cancels
the previous warm-up, leaving the tab cancels the last. Cached tiles are
skipped by loadTile before any download (verified in bytecode), and six
consecutive failures (offline, server down) abort the loop.

Honest notes kept in the code: osmdroid 6.1.20 exposes NO HTTP timeout
API, so a stalled socket is bounded only by the queue; first-load
etiquette still depends on the tile server behind the template, and a
self-hosted tile server is the follow-up, not done here.
MapCanvas now fits the camera once per cameraEpoch through doOnLayout
(the projection must be laid out before any fit means anything), applies
fitToBounds atomically as setZoom + setCenter, re-fits when a scope chip
changes the bounds, and refuses to emit a viewport from a zero-size view
so the poisoned-saved-camera bug cannot return. The shared appliedTileKey
is seeded by the factory, so the first update no longer re-applies the
tile source pre-layout.

The marker rebuild walks the plan first: a pin stays stock, a neutral
tile renders synchronously (nothing to load) into the bitmap cache, and
photo plans park their placeholder (count circle for clusters, pin for
singles) before upgrading when Coil delivers — counts of 10 and 1000 now
photo like counts of 2. Drill-down handlers are untouched; the bigger
icons just make bigger tap targets. Each applied fit also launches the
bounded tile warm-up on a scope tied to the composition.
chore(android): bump to 0.4.2 (versionCode 17)
All checks were successful
Wiki Sync / Sync wiki from docs (push) Has been skipped
Build and Deploy / Detect changed services and test scopes (push) Successful in 2s
Build and Deploy / Smoke API and media worker (push) Has been skipped
Build and Deploy / Smoke web (push) Has been skipped
Build and Deploy / Smoke ML worker (push) Has been skipped
Build and Deploy / Smoke people worker (push) Has been skipped
Build and Deploy / Build postgres image (push) Has been skipped
Build and Deploy / Build plants worker image (push) Has been skipped
Build and Deploy / Build converter worker image (push) Has been skipped
Build and Deploy / Deploy postgres (push) Has been skipped
Build and Deploy / Build API image (push) Has been skipped
Build and Deploy / Build media worker image (push) Has been skipped
Build and Deploy / Build ML worker image (push) Has been skipped
Build and Deploy / Build people worker image (push) Has been skipped
Build and Deploy / Build web image (push) Has been skipped
Build and Deploy / Deploy API (push) Has been skipped
Build and Deploy / Deploy web (push) Has been skipped
Build and Deploy / Deploy media worker (push) Has been skipped
Build and Deploy / Deploy ML worker (push) Has been skipped
Build and Deploy / Deploy plants worker (push) Has been skipped
Build and Deploy / Deploy people worker (push) Has been skipped
Build and Deploy / Deploy converter worker (push) Has been skipped
Build and Deploy / Clean Docker build artifacts (push) Has been skipped
Build and Deploy / Run scoped PR tests (push) Successful in 4s
Build and Deploy / Android unit tests and debug APK (push) Successful in 1m50s
e943c59f0c
Map polish: zoom-to-fit, photo markers at every count, bigger tiles,
faster caching.
docs: record ISSUE-141 (osmdroid exposes no HTTP timeout API)
All checks were successful
Wiki Sync / Sync wiki from docs (push) Has been skipped
Build and Deploy / Detect changed services and test scopes (push) Successful in 2s
Build and Deploy / Smoke API and media worker (push) Has been skipped
Build and Deploy / Smoke web (push) Has been skipped
Build and Deploy / Smoke ML worker (push) Has been skipped
Build and Deploy / Smoke people worker (push) Has been skipped
Build and Deploy / Build postgres image (push) Has been skipped
Build and Deploy / Build plants worker image (push) Has been skipped
Build and Deploy / Build converter worker image (push) Has been skipped
Build and Deploy / Deploy postgres (push) Has been skipped
Build and Deploy / Build API image (push) Has been skipped
Build and Deploy / Build media worker image (push) Has been skipped
Build and Deploy / Build ML worker image (push) Has been skipped
Build and Deploy / Build people worker image (push) Has been skipped
Build and Deploy / Build web image (push) Has been skipped
Build and Deploy / Deploy API (push) Has been skipped
Build and Deploy / Deploy web (push) Has been skipped
Build and Deploy / Deploy media worker (push) Has been skipped
Build and Deploy / Deploy ML worker (push) Has been skipped
Build and Deploy / Deploy plants worker (push) Has been skipped
Build and Deploy / Deploy people worker (push) Has been skipped
Build and Deploy / Deploy converter worker (push) Has been skipped
Build and Deploy / Clean Docker build artifacts (push) Has been skipped
Build and Deploy / Run scoped PR tests (push) Successful in 4s
Build and Deploy / Android unit tests and debug APK (push) Successful in 1m45s
416ed05efd
Found while configuring the Karte tab's tile cache for PR#1151: there is
no connect/read timeout setter anywhere in osmdroid 6.1.20, so a stalled
socket is only bounded by the download queue. Logged honestly instead of
claiming timeouts are configured.
chris merged commit e1dbe52f25 into main 2026-10-12 17:33:42 +02:00
Sign in to join this conversation.
No reviewers
No labels
No milestone
No project
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set

Reference
chris/memories!1151
No description provided.