Alby96andClaude Opus 5
91f9ac0fbf
Completes milestone 3: frames render over the map, play as a loop, and can be scrubbed, with the legend drawn from the manifest rather than a constant that could drift from what the worker actually rendered. The overlay alternates two MapLibre image sources. Updating one source in place flickers, because the layer briefly shows a half-written texture; adding every frame as its own layer avoids that but pins them all in GPU memory, and twenty 512x512 RGBA frames is about 80 MB. Two buffers cost the same whether the timeline holds six frames or sixty. Platform-channel work is serialised because `show` is called faster than the round trip completes during playback, and overlapping updates would swap visibility out of order and strobe. Prefetching loads a window around the playhead, nearest first and forward before backward, since playback moves forward and that frame is needed soonest. `FrameCache` is byte-budgeted rather than entry-counted because frame size tracks how much precipitation is on screen, and it evicts by distance from the playhead: plain LRU would keep frames the prefetcher touched a moment ago even after the playhead moved to the far end of the timeline. Also adds DpcRadarSource, which reads published frames from our CDN and never from the DPC API. Without it, the `dpc` adapter would have had to fall back to mock, putting demo frames on screen under the label of live data — exactly the confusion the adapter split exists to prevent. It now fails naming the missing setting instead. Running it on the emulator caught three things the tests had not: - The notifier wrote to `state` from inside `build()`, which Riverpod rejects as an uninitialised provider. That broke startup, not just tests. - Eight-month-old demo frames rendered as "Aggiornato 342535 minuti fa". The age formatter now steps up to hours and days. - Demo mode sat permanently behind a stale-data warning and so never showed the working state it exists to demonstrate. MockRadarSource now shifts the bundled timestamps onto the present, leaving images, order and spacing untouched, so the timeline behaves exactly as it would on live data. Corrects docs/stack-decisions.md, which described a disk cache that was not built: mock frames already live in the asset bundle, so a disk layer belongs with the network adapter where it would save a real request. Verified: analyze clean, 129 tests passing, and on the emulator the loop advances, wraps, and reports "Aggiornato ora". Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Nuvolari
Precipitation radar for Piedmont, Italy. Android first, iOS later, one Flutter codebase.
Radar imagery comes from the public Radar-DPC platform, forecasts from MET Norway, weather alerts from the ARPA Piemonte XML-CAP bulletin. The app is free and ad-supported, with GDPR consent through Google's UMP.
Nuvolari is an independent app. It is not affiliated with, endorsed by, or operated by ARPA Piemonte or the Dipartimento della Protezione Civile. For civil-protection purposes the official channels always prevail.
Layout
app/ Flutter application (Dart package "nuvolari")
backend/ Python worker: fetches DPC rasters, crops, reprojects, renders PNG frames
docs/ architecture, data sources, licenses, stack decisions, roadmap, privacy
tool/ verification scripts
Start with docs/architecture.md, then docs/roadmap.md for what is built and what is next.
Toolchain
| Tool | Version |
|---|---|
| Flutter | 3.47.3 stable (Dart 3.13.3) |
| Android SDK | platform 36, build-tools 36.0.0, platform-tools |
| JDK | 21 |
| Python | 3.12+ (3.14 works; rasterio ships wheels for it) |
| Android NDK | 28.2.13676358 — pinned by maplibre_gl, not by this project |
A full toolchain plus a warm Gradle cache needs roughly 14 GB of disk: Flutter
3 GB, Android SDK 2.5 GB (2 GB of which is the NDK the map plugin pins), the Gradle
cache 5 GB, and build output around 2 GB. flutter clean reclaims the last of those.
Configuration
Secrets never enter the repository. Copy the template and fill it in:
cp env.example.json env.json # env.json is git-ignored
| Key | Purpose |
|---|---|
MAP_STYLE_URL |
MapLibre style URL. Empty falls back to a local offline style. |
RADAR_MANIFEST_URL |
Base URL of the published manifest.json. |
RADAR_SOURCE |
mock (offline demo), dpc (live), arpa (disabled stub). |
METNO_USER_AGENT_CONTACT |
Contact address for the MET Norway User-Agent — mandatory for forecasts. |
ADMOB_APP_ID, ADMOB_BANNER_UNIT_ID |
Empty means Google's test ad units are used. |
Running
cd app
flutter run --dart-define-from-file=../env.json
With no env.json the app starts in demo mode: mock radar frames from assets, offline
base map style, test ad units. No network and no credentials required.
Debugging in VS Code
Open the Nuvolari folder as the workspace root — the configurations in
.vscode/ are relative to it. Then pick one in Run and Debug and press F5:
| Configuration | Use it for |
|---|---|
| Nuvolari — debug (emulatore) | Everyday work. Demo mode, no env.json needed, hot reload on save. |
| Nuvolari — profile | Judging animation smoothness. Debug builds run the Dart VM unoptimised, so the radar timeline always looks worse than it is — never assess it in debug. |
| Nuvolari — debug con env.json | Real endpoints and keys. |
| Nuvolari — debug su Windows | Fast UI iteration with no emulator. The native map does not render here. |
| Test — tutti / Test — file corrente | Debugging tests with breakpoints. |
Every emulator configuration runs tool/start_emulator.ps1 first, so F5 works from a
cold machine. The script exits immediately when a device is already attached, so
pressing F5 twice does not start two emulators.
Ctrl+Shift+B runs the full verification. Other tasks live under
Terminal → Run Task: quick verification, regenerating the demo radar frames, and
shutting the emulator down.
Verifying
.\tool\verify.ps1 # format, analyze, test, build, lint, pytest
.\tool\verify.ps1 -SkipBuild # fast inner loop
Stages whose target does not exist yet are skipped, so this runs from day one.
Attribution
Radar-DPC (CC BY-SA) · MET Norway (CC BY 4.0) · Arpa Piemonte · © OpenStreetMap contributors (ODbL). See docs/licenses.md for the obligations these carry — in particular, the rendered radar frames are a derived product of CC BY-SA data and inherit share-alike.