diff --git a/README.md b/README.md index 39f9913..4c6680b 100644 --- a/README.md +++ b/README.md @@ -41,6 +41,7 @@ All prizes live in the `[prizes/](prizes/)` directory. Each prize is a markdown | [LP-0015](prizes/LP-0015.md) | General cross-program calls via tail calls | Large | Closed | | [LP-0016](prizes/LP-0016.md) | Anonymous Forum with Threshold Moderation | Large | Open | | [LP-0017](prizes/LP-0017.md) | Whistleblower: document upload and indexing Basecamp app | Medium | Open | +| [LP-0020](prizes/LP-0020.md) | OSM Map Viewer — offline rendering, search, and POI discovery | Large | Draft | ### Proposing a New Prize diff --git a/prizes/LP-0020.md b/prizes/LP-0020.md new file mode 100644 index 0000000..4a98a65 --- /dev/null +++ b/prizes/LP-0020.md @@ -0,0 +1,164 @@ +--- +dependencies: + - id: LP-0018 + reason: Provides the OSM data source — Geofabrik-verified PBF snapshots stored in Logos Storage with an on-chain LEZ registry. This prize consumes that data for offline rendering, search, and POI discovery. +--- + +# LP-0020: OSM Map Viewer — Offline Map Rendering, Search, and POI Discovery [DRAFT] + +**`Status: Draft`** +**`Logos Circle: N/A`** + +## Overview + +This prize funds an **offline map viewer** for the Logos ecosystem. It consumes OSM PBF snapshots distributed via LP-0018 (Logos Storage + on-chain LEZ registry) and turns them into a usable map experience: client-side vector rendering, offline geocoding search, and POI discovery — with no external tile, search, or routing servers. + +The deliverable has two required parts: a **Logos Basecamp app** (region management, map view, search, POI browsing) and a standalone **map engine module/SDK** (PBF → vector tiles + search index) reusable by other Logos apps. + +**Requires:** +- LP-0018's OSM registry LEZ program and Logos Storage-hosted PBF snapshots (Geofabrik direct download as fallback, consistent with LP-0018). + +The target platform is **desktop/laptop** (Basecamp's primary form factor). Mobile support is welcome but not required, and the success criteria are calibrated for desktop-class hardware. + +The **Success Criteria**, **Scope**, and **Submission Requirements** below are the authoritative checklist for evaluators. + +## Motivation + +LP-0018 solves decentralized **distribution** of map data, but the data is only useful to people who already run GIS tools or third-party apps (OsmAnd, Organic Maps). There is no Logos-native way to actually *look at* the maps. + +A first-party viewer closes the loop: + +- **Privacy**: every pan, zoom, and search query against a public tile/geocoding server leaks location intent. Local rendering and local search leak nothing. +- **Offline use**: once a region is downloaded, the full experience (view, search, POIs) works without any network access. +- **Composability**: it exercises LP-0018's registry and storage pipeline end-to-end and produces a reusable map engine module other Logos apps can embed (e.g., showing a meeting point in a messaging app). +- **Demonstration value**: a smooth, beautiful offline map is the most visceral demo of "real apps on the Logos stack" available today. + +## Success Criteria + +### Functionality + +- [ ] **Region browser**: query the LP-0018 OSM registry for available regions; show hosted/not-hosted status and versions; download selected regions from Logos Storage (Geofabrik direct fallback) with checksum verification per LP-0018 conventions. +- [ ] **Region lifecycle**: list installed regions with size on disk and snapshot version; check the registry for newer versions; update and delete regions. Multiple installed regions are viewable seamlessly (no manual switching between regions on the map). +- [ ] **Offline processing pipeline**: convert downloaded PBF into a local renderable form (vector tiles, e.g. MBTiles/PMTiles) plus a search index, fully client-side. No external tile or processing server. Processing runs in the background with progress indication and is resumable or restartable after interruption. +- [ ] **Map rendering**: smooth pan/zoom vector map with a clean default style: roads, buildings, water, landuse, place labels, and POI icons with zoom-dependent detail. Map controls: zoom buttons, scale bar, north reset, and a coordinate readout. Keyboard and mouse-wheel navigation (desktop-grade interaction). +- [ ] **Location search (offline geocoding)**: search box with type-ahead over place names, streets, and addresses in installed regions; ranked results; selecting a result pans/zooms the map and drops a marker. Prefix and fuzzy matching for typos. +- [ ] **POI discovery**: browse POIs by category (food & drink, shopping, transport, health, tourism, amenities); POIs visible in the current viewport listed and highlighted on the map; tapping a POI shows a detail card with its OSM tags (name, opening hours, website, etc. where present). +- [ ] **POI search**: search POIs by name or type, optionally filtered to the current viewport ("cafes near the center of view"). +- [ ] **Bookmarks**: save locations/POIs to a local, persistent favorites list; jump to a bookmark from the list. +- [ ] **Permalinks/state**: the app restores the last viewport on restart and can copy coordinates (lat/lon + zoom) to the clipboard for sharing. +- [ ] **Map engine module**: extract the PBF-processing, tile-serving, and search logic into a self-contained module/SDK with a documented API, reusable by other Logos apps without depending on the Basecamp app itself. + +### Usability + +- [ ] Provide a Logos Basecamp app GUI with local build instructions, downloadable assets, and loadable in Logos app (Basecamp). +- [ ] Provide a module/SDK (the map engine) that can be used to build Logos modules for offline map rendering and search, with API documentation and a minimal embedding example. + +> **Note on the standard SPEL IDL requirement:** this prize defines **no new LEZ program** — it is a read-only consumer of LP-0018's OSM registry, using LP-0018's published IDL and registry module. The IDL requirement from the prize template therefore does not apply here. +- [ ] Clear UX: download/processing progress per region, installed-region status, offline-first behavior (no broken network calls when offline), and search results with sensible relevance ranking. + +### Reliability + +- [ ] Corrupted or incomplete PBF/tile data is detected and reported with clear errors; the app never crashes on bad data. +- [ ] Region downloads resume or restart cleanly after interruption. +- [ ] Processing failures leave the app in a consistent state (failed region can be re-processed or removed). + +### Performance + +Measured and documented on a defined reference desktop machine (CPU, RAM, OS stated in the README): + +- [ ] Pan/zoom rendering at interactive frame rates for a city-scale region (e.g., Berlin) — document measured FPS. +- [ ] Search results within 500 ms for typical queries on a city-scale region; document latency for a country-scale region (e.g., Germany). +- [ ] Document PBF→tiles+index processing time and resulting disk footprint for a small (Berlin ~93 MB) and a large (Germany ~4 GB) region. +- [ ] Document peak memory usage during processing and during map interaction. + +### Supportability + +- [ ] Desktop is the primary supported target; document tested OS(es). Mobile/small-screen support is a bonus, not a requirement. +- [ ] Integration with the LP-0018 registry tested against LEZ devnet/testnet (read/query path). +- [ ] Integration tests for the processing pipeline and search (PBF fixture → tiles + index → query assertions) run in CI; CI is green on the default branch. +- [ ] A README covers: build steps, region management, search usage, performance results, reference hardware, and troubleshooting. +- [ ] A reproducible demo script (or documented manual flow) from clean environment to rendered map works without modification. + +## Scope + +### In Scope + +- Region discovery/download/update via the LP-0018 registry and Logos Storage (Geofabrik fallback). +- Client-side PBF → vector tiles + search index processing. +- Vector map rendering with a default style. +- Offline geocoding search (places, streets, addresses). +- POI browsing by category and POI search. +- Bookmarks and viewport persistence. +- Map engine module/SDK extracted from the app, with documented API. +- Integration tests and CI. + +### Out of Scope + +- Turn-by-turn navigation and route planning (candidate follow-up prize). +- Real-time OSM synchronization (snapshots only, per LP-0018). +- Map editing or uploading changes to OSM. +- GPS/live location tracking (desktop-first; not required). +- Custom map style editor (one good default style suffices; theming is a bonus). +- Server-side rendering or any hosted tile/search backend — the application must not depend on any centralised server or service. Geofabrik is permitted only as a direct-download fallback, mirroring LP-0018. +- Hosting/registering map data (that is LP-0018's job; this app is a consumer). +- A new LEZ program (none required; registry access goes through LP-0018's program and module). + +## Prize Structure + +- **Total Prize:** $X +- **Effort:** L + +> Leave prize pool blank — this will be determined by the Logos team. Single winner by default. + +## Eligibility + +Open to any individual or team. Submissions must be original work. Teams must hold the rights to all submitted code and agree to license it under MIT or Apache-2.0. Use of existing open-source map libraries (MapLibre, tilemaker, Planetiler, etc.) is allowed and encouraged, provided licenses are compatible. + +## Submission Requirements + +- Public repository (MIT or Apache-2.0) containing: + - the map viewer Basecamp app, + - the map engine module/SDK with API documentation, + - integration tests runnable in CI. +- README with: build steps, region management, search usage, performance results (with reference hardware), and troubleshooting. +- A narrated video walkthrough in which the builder explains what they built and why, walks through the architecture and key implementation decisions, and demonstrates (see [demo requirements](../README.md#evaluation-policies)): + - region discovery via the LP-0018 registry and download from Logos Storage, + - background processing of a downloaded region with progress indication, + - smooth pan/zoom on the rendered map, including zooming from country level into street level, + - offline operation (network disabled) for viewing, search, and POI browsing, + - location search with ranked results and map fly-to, + - POI browsing by category and a POI detail card, + - error handling for a corrupted/incomplete region. + A silent screencast without explanation is not sufficient. +- GitHub issues filed for any problems encountered with Logos technology. +- Submissions must include a FURPS self-assessment as part of the solution (see [solution template](../solutions/LP-0000.md)). + +## Evaluation Process + +By default, submissions are evaluated first-come-first-served against the success criteria. The first submission that meets **all** criteria wins. + +Evaluators will independently clone the repository and run the demo from a clean environment; it must succeed without modification. Evaluators may also ask technical follow-up questions to verify authorship and understanding of the implementation. + +The following policies apply to all prizes (see [evaluation policies](../README.md#evaluation-policies)): + +- **Submissions:** each builder (or team) is allowed a maximum of **3 submissions** per prize, with at most **one submission/review per week**. +- **Feedback:** initial evaluation feedback is limited to a pass/fail indication against the success criteria. + +## Resources + +- [LP-0018](LP-0018.md) — OSM Integration (data source: registry + storage) +- [OSM PBF Format](https://wiki.openstreetmap.org/wiki/PBF_Format) +- [MapLibre GL JS](https://github.com/maplibre/maplibre-gl-js) — client-side vector rendering (WebGL) +- [PMTiles](https://github.com/protomaps/PMTiles) — single-file tile archives, ideal for offline use +- [tilemaker](https://github.com/systemed/tilemaker) / [Planetiler](https://github.com/onthegomap/planetiler) — PBF → vector tiles +- [Protomaps basemaps](https://github.com/protomaps/basemaps) — reference tile schema and styles +- [Nominatim address ranking](https://nominatim.org/release-docs/latest/develop/Ranking/) — reference for geocoding relevance +- [Logos Basecamp](https://github.com/logos-co/logos-basecamp) +- [Logos Storage Module](https://logos-storage-docs.netlify.app/tutorials/storage-module/) + +## Potential for Subsequent λ Prizes + +- **Offline routing** — route planning and turn-by-turn directions on LP-0018 data (the natural next step deliberately excluded here). +- **Custom POI layers** — user-defined overlays (GeoJSON import, custom icons) shareable via Logos Storage. +- **Location sharing** — share a location/viewport via Logos Messaging using the map engine module. +- **Mobile-optimized viewer** — touch-first UI and GPS integration once Basecamp mobile matures.