# Implementierungsplan

Diese Checkliste ist die verbindliche Reihenfolge für die Entwicklung des MapTools Converters. Ein Block gilt erst als abgeschlossen, wenn seine Abnahmekriterien erfüllt, die automatisierten Prüfungen grün und die Dokumentation aktualisiert sind.

## Block 0 – Projektgrundlage ✅

- [x] Aufgeräumte Verzeichnisstruktur anlegen
- [x] Kotlin-Multiplatform-Core und Compose-Desktop-App einrichten
- [x] Microsoft OpenJDK 25 und Gradle-Wrapper verwenden
- [x] Portable Windows-x64-Distribution mit gebündelter Laufzeit erzeugen
- [x] Branding, Farben und Icons aus MapTools übernehmen
- [x] zentrale Versionsanzeige und Programminfo mit Entwickler-, Rechts- und Kontaktlinks ergänzen
- [x] Vier-Schritt-Workflow Quelle → Bereich → Inhalte → Export erstellen

Abnahme: `scripts/verify.ps1` erzeugt eine startfähige portable Anwendung.

## Block 1 – Eingabedatei und geografische Grenzen ✅

- [x] Unterstützte OSM-Dateiendungen erkennen
- [x] PBF-`OSMHeader` begrenzt und fehlertolerant lesen
- [x] RAW- und ZLIB-Header unterstützen
- [x] PBF-Gesamtgrenzen auf die normalisierte Auswahl abbilden
- [x] Koordinaten in Quelle, Bereich und Exportübersicht anzeigen
- [x] Unit-Tests für Header und Koordinaten ergänzen

Abnahme: Eine reale PBF-Datei kann gewählt werden, ohne die Kartendaten vollständig zu laden; ihre Grenzen werden angezeigt.

## Block 2 – Reale Testdaten und PBF-Blockindex ✅

- [x] Hessen-PBF über eine lokale, ignorierte Konfiguration referenzieren
- [x] Testdaten-Inventur reproduzierbar ausführen
- [x] Alle PBF-Blöcke sequenziell und speichersparend scannen
- [x] Dateioffset, Blobtyp, komprimierte und entpackte Größe indexieren
- [x] RAW-, ZLIB-, LZMA-, BZIP2-, LZ4- und ZSTD-Kennungen erfassen
- [x] Fortschritt und Abbruch auf Parser-Ebene vorsehen
- [x] Indexformat versionieren und atomar im Anwendungscache speicherbar machen
- [x] Unit-Tests mit synthetischen Mehrblock-PBFs ergänzen
- [x] Smoke-Test mit der Hessen-PBF ausführen

Abnahme: Die Hessen-Datei wird vollständig gescannt, ohne vollständig in den RAM geladen zu werden. Der Index kann erneut geladen und einer unveränderten Quelldatei eindeutig zugeordnet werden.

Ergebnis des lokalen Smoke-Tests vom 25.08.2026: 343.841.973 Byte, 4.601 Blöcke, davon 4.600 `OSMData`, ZLIB in allen Blöcken, Scanzeit rund 0,45 Sekunden. SHA-256: `5e0b30ec8dc6d42519e4cc6faadbc68025d81ecbc02100a34b3d75d8cf6bc0ed`.

## Block 3 – Vorschauobjekte extrahieren ✅

- [x] StringTable und PrimitiveGroups dekodieren
- [x] DenseNodes sowie normale Nodes dekodieren
- [x] Ways einschließlich Delta-kodierter Node-Referenzen dekodieren
- [x] relevante Tags klassifizieren (Straßen, Wege, Wasser, Land, Gebäude, POIs)
- [x] begrenzte und deterministisch vereinfachte Übersichtsgeometrien erzeugen
- [x] Vorschaugeometrien begrenzen und versioniert persistent zwischenspeichern
- [x] Parser-, Klassifikations- und Grenzfalltests ergänzen

Abnahme: Für Hessen werden echte Vorschaugeometrien erzeugt; Speicherbedarf und Cachegröße bleiben begrenzt.

Ergebnis des lokalen Smoke-Tests: 31.820.725 Nodes und 4.905.422 Ways wurden vollständig dekodiert. Der aktuelle Vorschauaufbau erzeugt 7.464 POI-Punkte, 188.378 Linien und 20.000 priorisierte Beschriftungen in rund 22,8 Sekunden. Die Oberfläche lädt den versionierten Cache bei unveränderter Quelle erneut.

## Block 4 – Interaktive echte Kartenvorschau ✅

- [x] Neutralen Platzhalter durch echte PBF-Vorschaugeometrien ersetzen
- [x] Darstellungsdichte abhängig von der Zoomstufe erhöhen
- [x] Zoomen per Mausrad und Verschieben per Ziehen implementieren
- [x] Auswahl- und Navigationsmodus eindeutig trennen
- [x] Layer ein-/ausblendbar machen
- [x] Auswahlkoordinaten, Zoomfaktor und Ladezustand anzeigen
- [x] ungefähre geografische Sichtbreite als Maßstabsinformation anzeigen
- [x] Rendering größenabhängig und mit DPI-skalierenden `dp`-Linienbreiten umsetzen
- [x] Orts-, Straßen-, Gewässer- und POI-Namen aus der PBF übernehmen und kollisionsarm darstellen
- [x] helle kartografische Layerfarben für Siedlungen, Landschaft, Wasser, Gebäude und Wegenetze verwenden
- [x] direkte Navigation per rechter/mittlerer Maustaste und Leertaste ergänzen
- [x] Gebäude, Nebenstraßen, Wege, POIs und Beschriftungen zoomabhängig ausdünnen
- [x] Darstellungsbudgets erst auf die im Viewport sichtbaren Geometrien anwenden
- [x] räumlichen Rasterindex für Linien, Flächen, POIs und Beschriftungen einsetzen
- [x] Tiefenzoom bis 250-fach sowie Fußwege, Wanderpfade, Treppen und Fußgängerbereiche darstellen
- [x] geografische Bounding-Box direkt anzeigen, validieren und manuell editierbar machen
- [x] OSM-Multipolygone für Wälder, Gewässer und Siedlungsflächen auflösen
- [x] bestehende Rechteckauswahl verschiebbar und an allen vier Ecken skalierbar machen
- [x] ab Tiefenzoom vollständige Details für den sichtbaren Bereich aus einem portablen Mapsforge-Cache nachladen
- [x] Orts- und POI-Suche mit temporärer Kartenmarkierung ergänzen
- [x] mehrere getrennte, einzeln verschieb- und löschbare Auswahlrechtecke unterstützen

Abnahme: Hessen lässt sich flüssig betrachten; Details werden räumlich nachgeladen, Suchtreffer markiert
und mehrere getrennte Rechtecke können präzise ausgewählt werden.

## Block 5 – Räumliches Zuschneiden und Inhaltsfilter ✅

- [x] Worker-Protokoll für Start und Ergebnis definieren
- [x] Worker-Protokoll um kontinuierlichen Lebensstatus und Abbruch ergänzen
- [x] kostenlosen plattformunabhängigen JVM-Worker rechtssicher anbinden
- [x] Rechteckzuschnitt mit vollständigen Node-/Way-/Relation-Abhängigkeiten erzeugen
- [x] gewählte Inhaltsgruppen in ein Mapsforge-Tag-Mapping übersetzen
- [x] zugeschnittene `.osm.pbf` schreiben
- [x] mehrere PBF-Quellen auswählen und in Vorschau sowie Export gemeinsam behandeln
- [x] Mapsforge-`.map` als Eingabe mit Headergrenzen, Zoomangaben und echter Vorschau lesen
- [x] Eine oder mehrere Mapsforge-`.poi`-Dateien prüfen, zuschneiden, zwischen Schema v3 und v4 migrieren und zusammenführen
- [x] Schnellweg für die vollständige Datei ohne Kartenanzeige und Bereichsauswahl anbieten
- [x] `.map`, PBF und gemischte Grenzregionen über synthetische, getrennte ID-Räume zusammenführen
- [x] `.osm.pbf`-Rohdatenausgabe bei verlustbehafteten `.map`-Quellen eindeutig deaktivieren
- [x] pro Quelle zuschneiden und überlappende OSM-IDs sortiert sowie versionsbasiert zusammenführen
- [x] temporäre Dateien atomar und aufräumbar verwalten
- [x] Ergebnis erneut einlesen und räumlich validieren

Abnahme: Ein ausgewählter Hessen-Ausschnitt wird als gültige PBF-Datei erzeugt und enthält die benötigten Referenzen.

Ergebnis des ersten Worker-Smoke-Tests: Ein Bereich von `8,15/50,0` bis `8,35/50,2` wurde mit vollständigen Ways und Relations aus der Hessen-PBF ausgeschnitten. Das Ergebnis umfasst 15.895.854 Byte, 155 gültige ZLIB-Blöcke und exakt die angeforderten Headergrenzen. Osmosis benötigte rund 158 Sekunden.

Die optionale `.osm.pbf`-Ausgabe bleibt absichtlich ein referenziell vollständiger Rohdatenausschnitt.
Die Inhaltsgruppen filtern die erkannten Tags der erzeugten Mapsforge-Karte; dadurch bleiben Rohdaten
für weitere Werkzeuge verlustfrei nutzbar.

## Block 6 – Mapsforge-Export

- [x] kompatible Mapsforge-Writer-Version und Lizenz festlegen
- [x] aus den Inhaltsgruppen dynamisch ein MapTools-Tag-Mapping ableiten
- [x] Mapsforge-`.map` wahlweise im Format v5 (Standard) oder v4 (Legacy) erzeugen
- [x] Mapsforge-`.poi` im Format 4 erzeugen
- [x] Attribution, Sprachen, Zoomintervalle und bevorzugte Startposition konfigurieren
- [x] Ergebnis automatisiert mit Mapsforge-Reader 0.29.0 aus MapTools öffnen
- [ ] Ergebnis manuell auf einem Android-Testgerät in MapTools darstellen

Abnahme: Die erzeugten Hessen-Testausschnitte lassen sich in MapTools anzeigen und enthalten die gewählten Layer und POIs.

Ergebnis des lokalen Smoke-Tests: Die vollständige Testkarte umfasst 6.044.103 Byte; die POI-Datenbank
6.717.440 Byte und 15.409 POIs. Ein dynamisches Mapping mit ausschließlich Straßen reduzierte dieselbe
Karte auf 1.440.981 Byte. Beide Karten wurden mit Mapsforge Reader 0.29.0 geöffnet und auf Formatversion,
Dateigröße, Grenzen, Startposition und Startzoom geprüft.

## Block 7 – Produktionsreifer Exportablauf ✅

- [x] gemeinsamen Basisnamen und sichere, formatspezifische Dateinamen anbieten
- [x] Überschreiben nur nach ausdrücklicher Bestätigung erlauben
- [x] Fortschritt, aktuelle Phase, Laufzeit und Protokoll anzeigen
- [x] laufende Arbeit durch Beenden des separaten Workers abbrechen
- [x] nativen Windows-Kindprozess bis zum tatsächlichen Worker-Ende überwachen
- [x] Fehler verständlich darstellen und Diagnoseprotokoll zugänglich machen
- [x] bekannte `.partial`-Dateien beim Start, Abbruch und Wiederanlauf bereinigen
- [x] reine Mapsforge-Aufträge vorab automatisch auf einen temporären PBF-Ausschnitt begrenzen
- [x] kleine PBF-Ausschnitte im RAM-Modus statt über langsame HD-Indizes schreiben

Abnahme: Große Aufträge können beobachtet und abgebrochen werden; Fehler hinterlassen keine unklaren Teilergebnisse.

Jeder Worker-Lauf schreibt ein UTF-8-Protokoll in den portablen Ordner `logs` neben der Anwendung.
Die Oberfläche zeigt strukturierte Phasen, Laufzeit und – soweit der Writer Zähler liefert – Prozentwerte.
Zieldateien werden zunächst als bekannte `.partial`-Dateien erzeugt und erst nach erfolgreicher Prüfung
atomar umbenannt.

- [x] Vorschau- und Konvertierungscache neben der ausführbaren Datei ablegen
- [x] Protokolle neben der ausführbaren Datei ablegen
- [x] sitzungsbezogene Tempdaten zentral anlegen und beim Beenden entfernen
- [x] alte AppData-/XDG-Ablagen früherer Versionen sicher bereinigen
- [x] freien Speicher prüfen und bei zu kleinem Datenträger verständlich warnen

## Block 8 – Veröffentlichung

- [x] kleine synthetische PBF-Testfixtures ohne fremde Daten automatisiert erzeugen
- [ ] zusätzlich zur Hessen-Datei eine Deutschland-PBF als Lasttest verwenden
- [x] erste RAM-, Speicher- und Laufzeitmessungen der Hessen-Tests dokumentieren
- [x] Converter eigenständig unter `GPL-3.0-only` lizenzieren und Android-App ausdrücklich ausnehmen
- [ ] Drittanbieter-Lizenzen und OSM-Attribution vollständig beilegen
- [x] ausschließlich portable Windows-ZIP-Ausgabe mit gebündelter Laufzeit erzeugen und prüfen
- [x] ausschließlich portable Linux-TAR.GZ-Ausgabe mit gebündelter Laufzeit erzeugen und prüfen
- [x] eigenständige Worker-Starter in alle nativen Pakete aufnehmen und testen
- [x] plattformspezifische Cache- und Protokollverzeichnisse verwenden
- [x] SHA-256-Prüfsummen und gemeinsames Quelltextarchiv erstellen
- [x] reproduzierbare Windows-Fensteraufnahme und Benutzeranleitung erstellen

Abnahme: Eine neue portable Windows- oder Linux-x64-Ausgabe benötigt weder Java noch weitere Werkzeuge
und kann den dokumentierten Beispielauftrag vollständig ausführen. Windows- und Linux-Pakete wurden
am 25.08.2026 gebaut; die Prüfsummen, Paketstruktur und nativen Worker-Starter wurden geprüft. Die
Linux-Oberfläche wurde unter Ubuntu/WSLg mit der Hessen-PBF gestartet.

## Block 9 – Parallele CPU-/Kachelpipeline und optionales CUDA

Der detaillierte, phasenweise Plan steht in
[parallel-conversion-plan.md](parallel-conversion-plan.md).

- [x] aktuelle Engpässe mit Hessen-Messwerten lokalisieren
- [x] vorhandenen Mapsforge-RAM-Modus und Mehrkernparameter aktivieren
- [x] technische Machbarkeit eines writer-neutralen Zwischenformats bewerten
- [x] deterministische Kachelvorbereitung und seriellen Format-5-Finalizer planen
- [x] optionalen CUDA-/nvCOMP-Proof-of-Concept mit Go/No-Go-Kriterien planen
- [x] reproduzierbaren JSON-Benchmark für Blockscan und Dekodierung implementieren
- [x] parallelen PBF-Blockdecoder mit Backpressure und geordneter Ausgabe implementieren
- [x] optionale Dekompressions-Backend-API mit CUDA-Erkennung und CPU-Fallback implementieren
- [x] versionierte ID-Shards, räumliche Auswahl und referenzgeprüfte Materialisierung implementieren
- [x] optimierte OSM-PBF schreiben und als Standard-Crop mit Osmosis-Fallback integrieren
- [ ] externe ID-Sortierung, Way-Bounding-Boxen und globale Topologiebarriere implementieren
- [ ] Kacheln parallel vorserialisieren
- [ ] eigenen Mapsforge-Format-5-Finalizer implementieren
- [ ] POI-Pipeline parallel vorbereiten und gebatcht schreiben
- [ ] CPU-Pipeline gegen Mapsforge/Osmosis vollständig validieren
- [ ] CUDA-Prototyp nur bei nachgewiesenem Dekompressionsengpass beginnen

Abnahme: Die neue CPU-Pipeline ist mindestens dreimal schneller als die bisherige End-to-End-
Verarbeitung des Hessen-Testauftrags, bleibt bei jeder Threadzahl semantisch deterministisch und
benötigt weder GPU noch zusätzliche Installation. CUDA bleibt eine optionale, austauschbare Erweiterung.

## Qualitätsregeln für jeden Block

- [ ] Keine große Datei vollständig im Arbeitsspeicher halten
- [ ] Dateigrößen, Längenfelder und Entpacken strikt begrenzen
- [ ] Längere Arbeit nicht im UI-Thread ausführen
- [ ] Neue Kernlogik mit automatisierten Tests absichern
- [ ] Keine lokalen Testdaten oder absoluten Benutzerpfade veröffentlichen
- [ ] Nach jedem Block `scripts/verify.ps1` erfolgreich ausführen
- [ ] Status und Entscheidungen in dieser Checkliste aktualisieren
