# ArxSilex MapTools Converter

Kostenloser Desktop-Konverter für OpenStreetMap-, Mapsforge- und Höhendaten. Die Anwendung zeigt große Quellen lokal an, lässt geografische Ausschnitte auswählen und erzeugt daraus passende Dateien für MapTools und andere kompatible Anwendungen.

## Projektstatus

Funktionsfähige Entwicklungsversion mit einem durchgängigen Offline-Workflow:

1. Eine oder mehrere `.osm.pbf`-/`.pbf`-, Mapsforge-`.map`-/`.poi`- oder unterstützte Höhendatenquellen direkt oder aus ZIP-Archiven öffnen und sicher prüfen.
2. Straßen, Wege, Flächen, Gebäude und POIs zoomabhängig nachladen; Höhendaten erscheinen als farbige Schummerung mit transparenter NoData-Darstellung.
3. Orte und POIs lokal suchen sowie mehrere veränderbare Rechteck- und Kreisbereiche wählen; Überlappungen werden nur einmal verarbeitet.
4. Mapsforge `.map` (Format v5 oder v4), `.poi` (Schema v3 oder v4), bei reinen PBF-Quellen
   optional einen vollständigen PBF-Ausschnitt sowie GeoTIFF-, ESRI-ASCII-, HGT- oder DTED-Höhendaten exportieren.

Bei einer einzelnen Quelle kann **Gesamte Datei direkt konvertieren** die Kartenvorschau und
Bereichsauswahl überspringen. Mapsforge-Karten werden vollständig gelesen und mit dem offiziellen Writer
als v4 oder v5 neu aufgebaut. Eine oder mehrere `.poi`-Dateien werden zugeschnitten, auf das gewählte
Schema v3 oder v4 normalisiert und atomar zusammengeführt. POI-Daten und Kategorien bleiben erhalten;
lokale IDs sowie Kategoriehierarchien werden neu zugeordnet und exakte Grenzduplikate entfernt.

Die Verarbeitung läuft außerhalb des UI-Threads in einem abbrechbaren Worker-Prozess. Mapsforge 0.29.0,
Osmosis und eine reduzierte Java-Laufzeit werden in den Windows- und Linux-Ausgaben mitgeliefert.

ZIP-Archive können unterstützte Karten-, POI- und Höhendatenformate gemischt enthalten. Vor dem
Entpacken wird die gewünschte Auswahl angezeigt. Der Import begrenzt Anzahl, Einzel- und Gesamtgröße,
Kompressionsverhältnis und tatsächlich geschriebene Daten, prüft Pfade, freien Speicher und CRC und
öffnet verschachtelte ZIP-Archive nicht rekursiv. Entpackte Quellen liegen ausschließlich im portablen
Sitzungsordner und werden beim Beenden entfernt.

Die Oberfläche ist in denselben 17 Sprachen wie die MapTools-Android-App verfügbar: Deutsch,
Englisch, Französisch, Spanisch, Italienisch, Portugiesisch, Niederländisch, Polnisch, Tschechisch,
Türkisch, Ukrainisch, Japanisch, Koreanisch, vereinfachtes Chinesisch, Russisch, Rumänisch und
Schwedisch. Entfernungen und Flächen lassen sich unabhängig von der Sprache metrisch oder imperial
anzeigen; beide Einstellungen werden portabel neben der Anwendung gespeichert.

## Voraussetzungen für die Entwicklung

- Windows 10 oder 11 (x64) beziehungsweise Ubuntu 24.04 x64
- Microsoft OpenJDK 25 LTS
- `JAVA_HOME` zeigt auf das JDK

Gradle wird über den mitgelieferten Wrapper gestartet; eine separate Gradle-Installation ist nicht nötig.
Endanwender benötigen später weder Java noch Gradle, da jedes native Paket eine reduzierte Java-Laufzeit enthält.

Die Laufzeitablage ist portabel: `cache` und `logs` entstehen neben der ausführbaren Datei. Temporäre
Sitzungsdaten bleiben ebenfalls dort und werden beim Beenden entfernt; AppData, XDG-Verzeichnisse und
der Benutzer-Tempordner werden nicht als Speicherziel verwendet.
Auch Sprache und Einheitensystem liegen ausschließlich in `settings/preferences.properties` neben der
Anwendung.

In Android Studio wird der Ordner `application` als Projekt geöffnet. Unter **Settings → Build Tools → Gradle → Gradle JDK** soll das Microsoft OpenJDK 25 ausgewählt sein.

## Starten

```powershell
cd application
.\gradlew.bat :desktopApp:run
```

## Prüfen und portable App bauen

```powershell
.\scripts\verify.ps1
```

## Portable Windows-Ausgabe erzeugen

```powershell
.\scripts\package-windows.ps1
```

Das Skript erzeugt unter `release` ausschließlich ein portables Windows-x64-ZIP, das gemeinsame
Quelltextarchiv und SHA-256-Prüfsummen. Eine Installation und spätere Deinstallation sind nicht nötig.

Beim POI-Export kann zwischen zwei offiziellen Mapsforge-Schemata gewählt werden:

- **POI v3 (Kompatibilitätsstandard):** klassisches `lat`/`lon`-Schema für ältere und aktuelle Apps.
- **POI v4 (schnelle Suche):** aktuelles Schema mit RTree-Raumindex und FTS5-Volltextindex.

Vorhandene `.poi`-Dateien können ohne PBF-Quelle einzeln oder gemeinsam in beide Richtungen v3 ↔ v4
konvertiert werden. Mehrere Länder- oder Regionaldateien werden zu einer durchsuchbaren Ausgabe vereinigt.

Auch das davon unabhängige binäre Mapsforge-Kartenformat ist auswählbar:

- **Karte v5 (Standard):** aktuelles Format mit variablen Tagwerten für aktuelle Mapsforge-Apps.
- **Karte v4 (Legacy):** Kompatibilitätsausgabe für ältere Reader; variable Tagwerte stehen dort nicht zur Verfügung.

Die Anwendung prüft nach dem Export sowohl den Dateikopf als auch die Lesbarkeit und akzeptiert nur die
tatsächlich ausgewählte Kartenformatversion.

Alternativ stehen im Ordner `scripts` kurze PowerShell-Hilfen zum Starten, Prüfen und Paketieren bereit.

## Linux unter WSL2

Die Ubuntu-WSL-Distribution kann direkt mit den Quellen unter `/mnt/d/...` arbeiten. Windows und Linux
verwenden getrennte Build- und Gradle-Caches. Das Linux-JDK wird ohne Systeminstallation unter `Linux/.tools`
bereitgestellt und anhand der von Microsoft veröffentlichten SHA-256-Datei geprüft.

```bash
cd /mnt/d/Programmieren/Android/newProjects/MapTools-Converter
bash scripts/verify-linux.sh
bash scripts/package-linux.sh
```

`package-linux.sh` erzeugt unter `Linux/release` ausschließlich eine portable `tar.gz`, das gemeinsame
Quelltextarchiv und SHA-256-Prüfsummen.

## Struktur

- `application`: vollständiges Gradle-Projekt
  - `core`: gemeinsam nutzbare Modelle sowie der Desktop-Adapter zum sicheren Lesen von PBF-Headern
  - `desktopApp`: Windows-Oberfläche und Desktop-Integration
- `documentation`: Architektur, Entscheidungen und spätere Benutzerhilfe
- `test-data`: lokale kleine und große Kartendateien für manuelle Tests
- `screenshots`: Bilder für Homepage, Dokumentation und Releases
- `release`: fertig benannte portable Archive, Quelltextarchive und Prüfsummendateien
- `scripts`: wiederholbare Entwicklungs- und Paketierbefehle
- `build`: automatisch erzeugte Build-Artefakte; wird nicht versioniert

## Vorgesehene Verarbeitung

1. Eine oder mehrere OSM-PBFs öffnen und geografische Header-Metadaten prüfen.
2. Gemeinsame Kartenvorschau aus begrenzt zwischengespeicherten PBF-Geometrien anzeigen.
3. Rechteck, Inhaltsgruppen und Ausgabeformate wählen.
4. Jede relevante Quelle mit der parallelen MTCI-Pipeline referenziell vollständig zuschneiden,
   Überlappungen versionsbasiert zusammenführen; Osmosis bleibt als automatischer Kompatibilitäts-
   Fallback erhalten.
5. Aus einem dynamischen Tag-Mapping Mapsforge-`.map`, `.poi` und optional einen vollständigen `.osm.pbf`-Ausschnitt exportieren.

## Lizenz

Der **ArxSilex MapTools Converter** ist freie Software unter der
[GNU General Public License Version 3, ausschließlich dieser Version](LICENSE) (`GPL-3.0-only`).
Bei Weitergabe abgeleiteter Fassungen müssen die Bedingungen der GPL-3.0 erfüllt und der zugehörige
Quelltext verfügbar gemacht werden.

Diese Lizenz gilt ausschließlich für den eigenständigen Converter und nicht für die separate
ArxSilex-MapTools-Android-App. Fremdkomponenten behalten ihre jeweiligen Lizenzen; Einzelheiten und
Datenhinweise stehen in [NOTICE.md](NOTICE.md) und
[documentation/dependencies.md](documentation/dependencies.md).

Die Bedienung ist in der [Benutzeranleitung](documentation/user-guide.md) beschrieben.

Der aktuelle Arbeitsstand und die Abnahmekriterien jedes Entwicklungsblocks stehen im [Implementierungsplan](documentation/implementation-plan.md).
