# Benutzeranleitung

## Installation

Unter Windows wird die portable x64-Ausgabe entpackt und über
`ArxSilex MapTools Converter.exe` gestartet. Unter Linux wird das x64-`tar.gz` entpackt und das
Programm unter `bin/ArxSilex MapTools Converter` gestartet. Die App wird nicht installiert: Zum
Entfernen genügt es, ihren entpackten Ordner zu löschen. Java, Gradle, Osmosis oder Mapsforge müssen
auf keinem der beiden Zielsysteme separat installiert werden.

Über die beiden Auswahlfelder oben rechts werden Sprache und Einheitensystem unabhängig voneinander
gewechselt. Zur Wahl stehen dieselben 17 Sprachen wie in der MapTools-Android-App sowie metrische und
imperiale Einheiten. Die Auswahl bleibt im portablen Unterordner `settings` erhalten. Unter **Info**
finden sich Programmversion, Converter-Lizenz, Drittanbieterhinweise und ein Link zur Android-App.

Die Anwendung arbeitet vollständig portabel. Neben der ausführbaren Datei liegen `cache` für
wiederverwendbare Daten und `logs` für Exportprotokolle. Ein sitzungsbezogener Ordner `temp` wird nur
während der Ausführung verwendet und beim normalen Beenden wieder entfernt. Alte Ablagen früherer
Versionen unter AppData beziehungsweise den XDG-Benutzerverzeichnissen werden beim ersten Start der
portablen Version entfernt.

## 1. Quelldateien

Über **Erste Quelle auswählen** werden eine oder mehrere lokale `.osm.pbf`-, `.pbf`-, Mapsforge-`.map`-,
`.poi`- oder Höhendateien geöffnet.
Weitere Dateien können mit **Weitere Quelle hinzufügen** ergänzt und einzeln wieder entfernt werden. Der
Dateidialog darf dabei bei jedem Aufruf in einem anderen Ordner geöffnet werden. Das ist
insbesondere für Bundeslandkarten und Ausschnitte an Datensatzgrenzen gedacht. Der Converter liest
zunächst nur die PBF- beziehungsweise Mapsforge-Header und zeigt Dateigrößen und geografische Grenzen an.
Andere OSM-Formate sind für spätere Versionen vorgesehen, im aktuellen Release aber bewusst
nicht auswählbar.

Nicht unterstützte oder unlesbare Dateien werden nicht still verworfen: Die Quellseite zeigt für
jede abgelehnte Datei ihren Namen, den vollständigen Pfad und den konkreten Grund. PBF- und `.map`-Quellen
können gemeinsam verwendet werden, etwa Hessen mit Nordrhein-Westfalen oder Bayern mit Südtirol.

Über **ZIP-Archiv importieren** lassen sich ein oder mehrere `.zip`-Container öffnen. Ein Archiv darf
Karten-, POI- und Höhendateien in beliebiger unterstützter Kombination enthalten. Vor dem Entpacken
zeigt der Converter alle erkannten Einträge an; zunächst sind sie ausgewählt und können einzeln
abgewählt werden. Mehrere Karten-, POI- und Höhendateien werden gemeinsam übernommen. Ein Archiv darf
dabei Karten, mehrere POI-Datenbanken und Höhendaten zugleich enthalten.

Der ZIP-Import entpackt ausschließlich die gewählten Dateien in einen zufällig benannten Ordner unter
dem portablen Sitzungsspeicher. Er prüft vor und während des Entpackens Pfade, Anzahl, deklarierte und
tatsächliche Größen, Kompressionsverhältnis, freien Speicher und CRC. Es gelten höchstens 20.000
Archiveinträge, 16 GiB pro unterstützter Datei und 64 GiB unterstützte entpackte Daten insgesamt; 512
MiB bleiben als Speicherreserve frei. Absolute Pfade, `..`, nicht portable Windows-Namen sowie
auffällige Kompressionsverhältnisse werden abgelehnt. Verschlüsselte oder beschädigte ZIPs werden nicht
importiert. Enthaltene ZIP-Dateien werden angezeigt, aber aus Schutz vor rekursiven ZIP-Bomben nicht
geöffnet. Die temporären Dateien werden beim Beenden der Anwendung entfernt.

Bei genau einer Quelle bietet **Gesamte Datei direkt konvertieren** einen Schnellweg ohne Kartenanzeige
und Bereichsauswahl. Eine oder mehrere `.poi` können vollständig konvertiert oder anhand ihrer
gespeicherten Kartengrenzen räumlich zugeschnitten werden. Karten und beliebig viele zusätzliche `.poi`
lassen sich gemeinsam öffnen: Karte und Kartenausgabe stammen dabei aus den Kartenquellen, während Suche
und POI-Ausgabe alle vollständigeren POI-Quellen verwenden.

## 2. Kartenausschnitt

Beim ersten Öffnen baut der Converter aus der PBF- oder `.map`-Datei eine begrenzte Vorschau auf. Der Cache
liegt im Unterordner `cache/preview` neben der Anwendung und wird bei unveränderter Quelldatei
wiederverwendet. Große Mapsforge-Landeskarten werden dabei abschnittsweise gelesen, damit der
Vorschauaufbau keinen Arbeitsspeicher in Größe der vollständigen Karte benötigt.

Ab siebenfachem Zoom lädt die App vollständige Details für den sichtbaren Bereich nach. Vorhandene
Mapsforge-Dateien werden direkt räumlich gelesen. Für PBF-Quellen erzeugt die App beim ersten Tiefenzoom
einmalig eine interne Mapsforge-Detailkarte und eine POI-Suchdatenbank unter `cache/preview/detail`.
Dieser Aufbau kann bei großen Landesdateien mehrere Minuten dauern; weitere Zoom- und Suchvorgänge
verwenden den portablen Cache und sind deutlich schneller.

- Mausrad: um den Mauszeiger zoomen
- Pfeilsymbol: vorhandene Rechtecke und Kreise anklicken und bearbeiten
- Rechtecksymbol mit Plus: ein weiteres Rechteck für den Export ziehen
- Kreissymbol mit Plus: Mittelpunkt anklicken und anschließend den Radius in der gewählten Einheit eingeben oder den Radius direkt aufziehen
- innerhalb des bereits aktiven Bereichs ziehen: Auswahl verschieben; ein erster Klick aktiviert einen anderen Bereich
- einen Eckpunkt des aktiven Bereichs ziehen: Rechteckgröße beziehungsweise Kreisradius verändern
- Verschiebesymbol: Karte mit gedrückter linker Maustaste verschieben
- mittlere Maustaste ziehen: Karte unabhängig vom aktiven Werkzeug verschieben
- Rahmensymbol: Zoom und Kartenposition auf die komplette Ansicht zurücksetzen
- rotes X: den aktiven Auswahlbereich entfernen
- Zurück-/Vorwärtspfeil: bis zu 20 abgeschlossene Auswahlaktionen rückgängig machen oder wiederholen
- Suche nach Ort oder POI: Treffer anklicken, um dorthin zu zoomen und ihn temporär zu markieren; **Umkreis** übernimmt ihn mit wählbarem Radius als Kreisfläche
- Layer-Schalter: Verkehr, Landschaft und POIs nur in der Vorschau ein-/ausblenden
- Bounding-Box-Felder: West, Süd, Ost und Nord in WGS-84-Dezimalgrad anzeigen oder manuell ändern;
  **Koordinaten übernehmen** aktualisiert das Auswahlrechteck
- **Gesamte Quelldatei**: Auswahl auf die vollständigen PBF-Grenzen zurücksetzen

Mehrere Rechtecke und Kreise können gleichzeitig ausgewählt sein; genau ein Bereich ist zur Bearbeitung
aktiv. Die nummerierte Liste links wählt und zentriert jeden Bereich. Sie zeigt geodätische Maße,
Mittelpunkt, Fläche sowie ausdrücklich als Schätzung gekennzeichnete Objekt- und Größenintervalle.
Gesamtfläche, Objektzahl und Ausgabegröße basieren auf der geometrischen Vereinigungsmenge;
Überschneidungen werden nicht doppelt gezählt. Das Mapsforge-Dateiformat besitzt weiterhin
eine rechteckige äußere Bounding-Box. Zwischen getrennten Auswahlgebieten enthält die Datei deshalb eine
leere Kartenfläche, aber keine flächendeckenden Kartendaten.

Die Vorschau verwendet einen hellen Kartenhintergrund und unterscheidet unter anderem Siedlungsflächen,
Grünflächen, Gewässer, Gebäude, Straßen und Wege farblich. Orts-, Straßen-, Gewässer- und POI-Namen
stammen direkt aus `name:de`, `name` oder `ref` der Quelldatei. Kleine Details und Beschriftungen werden
erst beim Hineinzoomen eingeblendet. Die Zeichenbudgets und nachgeladenen Daten werden auf den gerade
sichtbaren Kartenausschnitt angewendet; dadurch erscheinen Nebenstraßen, Wege, Gebäude und POIs, ohne die
Gesamtansicht zu überladen. Flächen aus OSM-Multipolygonen, etwa größere Wälder und Gewässer, werden
ebenfalls aufgelöst. Der Tiefenzoom reicht bis 250-fach und zeigt neben Pfaden, Fuß- und Radwegen auch
Treppen sowie Fußgängerbereiche. Ein räumlicher Vorschauindex zeichnet beim Zoomen und Verschieben nur
die betroffenen Rasterzellen. Bei mehreren Quellen zeigt die Vorschau deren gemeinsame geografische
Ausdehnung.

## 3. Inhalte und Formate

Eine vollständige `.map` v4 kann als v5 neu geschrieben werden und umgekehrt. Dazu liest der Converter
die vorhandenen Vektordaten, materialisiert einen temporären referenziell vollständigen PBF-Strom und
erzeugt die Zielkarte mit dem offiziellen Mapsforge-Writer. Weil eine `.map` nicht mehr alle
ursprünglichen OSM-Metadaten enthält, ist die Ausgabe fachlich kompatibel, aber nicht bitidentisch.

Bei ausschließlich `.poi`-Quellen erscheint nur die Schemawahl. POI v3 → v4 baut RTree und FTS5 auf;
POI v4 → v3 erzeugt den klassischen `lat`/`lon`-Index und entfernt FTS5. Vor dem Zusammenführen werden
alle Quellen auf das Zielschema normalisiert. Kategorien werden anhand ihres vollständigen Pfads vereinigt,
lokale Kategorie- und POI-IDs neu vergeben und exakt gleiche POIs in Quellüberlappungen nur einmal ausgegeben.
Der Worker verändert nie die Quellen und ersetzt die Ausgabedatei erst nach erfolgreicher Verarbeitung atomar.

Die Inhaltsgruppen bestimmen, welche erkannten OSM-Tags in die Mapsforge-`.map` übernommen
werden. Die separate `.poi`-Datenbank ist nur zusammen mit **Points of Interest** verfügbar.

Die optionale `.osm.pbf` bleibt dagegen ein vollständiger Rohdatenausschnitt mit benötigten
Node-, Way- und Relation-Referenzen. Sie wird nicht durch die Inhaltsgruppen ausgedünnt und ist deshalb
nur verfügbar, wenn alle Eingaben PBF-Dateien sind. Eine Mapsforge-`.map` enthält weder alle ursprünglichen
OSM-Tags noch verlässlich die ursprünglichen OSM-IDs; daraus erzeugt der Converter nur neue `.map`- und
`.poi`-Dateien aus den noch vorhandenen Vektordaten.

## 4. Export

**Export starten** öffnet die Dateiauswahl für einen gemeinsamen Basisnamen. Aus
`mein-gebiet` entstehen abhängig von der Auswahl beispielsweise:

- `mein-gebiet.map`
- `mein-gebiet.poi`
- `mein-gebiet.osm.pbf`

Vorhandene Zieldateien werden nur nach einer ausdrücklichen Bestätigung ersetzt. Während der
Verarbeitung zeigt die App Phase, Laufzeit oder prozentualen Writer-Fortschritt. **Abbrechen**
beendet den Worker und entfernt bekannte Teildateien.

Bei mehreren Quellen schneidet der Worker zunächst nur die Datensätze zu, die mindestens einen gewählten Bereich
berühren. Anschließend sortiert und vereinigt er die Ausschnitte. Gleiche OSM-Objekt-IDs aus
Überlappungsbereichen werden anhand ihrer Version aufgelöst, bevor `.map`, `.poi` oder `.osm.pbf`
geschrieben werden.

Rechtecke werden über ihre geografischen Grenzen, Kreise über die tatsächliche Entfernung zum
Mittelpunkt gefiltert. Für referenziell vollständige OSM-Ausgaben ergänzt der Worker die benötigten
Knoten, Ways und Relations anschließend genau einmal.

Der Fortschrittsbalken läuft beim vollständigen PBF-Zuschnitt unbestimmt, weil Osmosis dafür keinen
Objektgesamtzähler meldet. Die neue Standardpipeline zeigt dagegen Blockscan, parallelen Cacheaufbau,
räumliche Auswahl, Abhängigkeitsauflösung und PBF-Ausgabe als getrennte Phasen mit echten Zählern.
Nur wenn sie automatisch auf Osmosis zurückfällt, bleibt der Zuschnittsbalken unbestimmt. Bei
Mapsforge-Phasen mit bekannten Objekt- oder Schreibmengen zeigt die App ebenfalls Prozentwerte.
Die Weg-Geometrievorbereitung nutzt automatisch bis zu acht CPU-Threads.

Jeder Worker-Lauf schreibt ein Diagnoseprotokoll nach `logs` neben der ausführbaren Datei. Nach
Erfolg oder Fehler öffnet die Schaltfläche **Protokollordner** diesen Speicherort.

## Leistungshinweise

Mapsforge verarbeitet viele OSM-Abhängigkeiten und kann für große Gebiete mehrere Minuten dauern.
Beim ersten Export einer Quelle erzeugt der Converter parallel ein wiederverwendbares MTCI-
Zwischenformat. Es liegt im portablen Unterordner `cache/conversion`. Für die 343,8-MiB-Hessenquelle
benötigt dieser Cache rund 1,94 GB; spätere Ausschnitte derselben unveränderten Quelle überspringen
den Aufbau. Ausgewählte temporäre Shards werden nach jedem Auftrag entfernt.

Die Quellseite zeigt den freien Speicher des Datenträgers und eine konservative Schätzung für die
Konvertierung. Reicht der Platz beispielsweise auf einer SD-Karte nicht, wird der Export vor dem
Cacheaufbau mit einem verständlichen Hinweis angehalten. Dann kann der vorhandene `cache`-Ordner
geleert oder der gesamte portable Anwendungsordner auf einen größeren Datenträger verschoben werden.

Anschließend verarbeitet der Writer PBF-Ausschnitte bis 256 MiB im schnellen RAM-Modus; größere
Eingaben wechseln automatisch auf Festplattenindizes. Auch wenn keine `.osm.pbf`-Ausgabe gewählt wurde,
erzeugt der Converter intern einen temporären Ausschnitt und entfernt ihn nach dem Auftrag. Der Worker
darf bis zu 4 GiB Heap verwenden. Für große Quelldateien müssen zusätzlich Cachegröße und freier
Datenträgerspeicher berücksichtigt werden.

## Datenlizenz

Bei OpenStreetMap-Daten müssen die OpenStreetMap-Mitwirkenden genannt und die Bedingungen der
Open Database License beachtet werden. Der Converter trägt einen entsprechenden Kommentar in die
erzeugten Dateien ein; bei einer Weitergabe oder Darstellung der Karte bleibt die korrekte Attribution
Aufgabe des Herausgebers beziehungsweise der verwendenden App.

## Programmlizenz

Der eigenständige ArxSilex MapTools Converter ist freie Software unter `GPL-3.0-only`. Die Lizenz
verpflichtet bei der Weitergabe veränderter Fassungen dazu, den zugehörigen Quelltext unter denselben
GPL-Bedingungen zugänglich zu machen. Sie gilt ausschließlich für den Converter und nicht für die
separate MapTools-Android-App. Der vollständige Text liegt als `LICENSE` in jedem Programmpaket;
`NOTICE.md` grenzt Converter-, Fremdkomponenten- und Kartendatenlizenzen voneinander ab.
