Add documentation for zip-file usage

config/de/mkdocs.yml

@@ -10,6 +10,7 @@ nav:
     - Installation: requiredSoftware.md
     - Erster Start: firstRun.md
     - Nutzeroberfläche: userInterface.md
+    - Zip Dateien: zipFiles.md
     - Prüfplan: validationPlan.md
     - Anforderungen:
       - Grundbegriffe: basic.md

config/en/mkdocs.yml

@@ -10,6 +10,7 @@ nav:
     - Installation: requiredSoftware.md
     - First Start: firstRun.md
     - User Interface: userInterface.md
+    - Zip files: zipFiles.md
     - Validation Plan: validationPlan.md
     - Requirements:
       - Fundamentals: basic.md

docs/de/zipFiles.md

+# Zip-Archive
+
+CityDoctor kann Zip-Dateien einlesen und enthaltene CityGML Dateien validieren.
+
+## Laden von Zip-Archiven
+
+![Archiv laden](img/archive_load.png)
+
+Zip-Dateien können über den Ladedialog ausgewählt und importiert werden. CityDoctor durchsucht die Zip-Datei nach möglichen CityGML Dateien
+
+## Zip-Eintrag Manager
+
+![Zipeintragmanager](img/archive_imported.png)
+
+Nachdem CityDoctor erfolgreich ein Zip-Archiv importiert hat, wird der Zip-Eintrag Manager angezeigt. Der Zip-Eintrag Manager hat folgende Schaltflächen:
+
+1. **Modell anzeigen:** Zeigt das Stadtmodell der ausgewählten, entpackten Datei im Hauptfenster von CityDoctor.
+2. **Datei entpacken:** Entpackt die ausgewählte Datei.
+3. **Fehlerstatistik anzeigen:** Zeigt die Fehlerstatistik der ausgewählten Datei. Nur verfügbar bei validierten Dateien.
+4. **Alle Dateien entpacken:** Entpackt alle Dateien im Archiv.
+5. **Alle Dateien prüfen:** Öffnet den Check-Dialog für die Batch-Validierung aller Dateien. Siehe [Validierung](#validierung) für mehr Informationen.
+6. **Validierungsergebnisse exportieren:** Ermöglicht das Speichern der Validierungsberichte. Verfügbar nachdem mindestens eine Datei validiert wurde.
+
+![Farbcode](img/color_coding.png)
+
+Der aktuelle Status der Dateien wird mithilfe eines Farbcodes angezeigt:
+
+- **Komprimiert (Schwarz):** Eine komprimierte Datei ist noch 'gezippt'.
+- **Entpackt (Blau):** Eine entpackte Datei wurde erfolgreich in den Arbeitsspeicher geladen.
+- **Leeres Modell (Grau):** Eine entpackte Datei, welche kein Stadtmodell oder ein Stadtmodell ohne Features beinhaltet.
+- **Fehlerhafte Datei (Dunkelrot):** Eine Datei, welche nicht erfolgreich entpackt werden konnte. Mögliche Ursachen sind fehlerhafte CityGml Dateien, Modelle die zu groß für den verfügbaren Arbeitsspeicher sind oder Probleme beim Einlesen der Datei. Der genaue Grund wird in den Metadaten angezeigt.
+- **Validierte Dateien mit / ohne Fehlern (Hellrot bzw. Grün)**
+
+!!! note
+    Das originale Zip-Archiv wird nicht verändert, entpackte Dateien sind Kopien.
+
+
+## Validierung
+
+### Validierung einzelner Dateien
+
+Entpackte Dateien können über das CityDoctor Hauptfenster validiert werden. Das jeweils letzte Ergebnis der Validierung von jeder Datei wird hierbei im Arbeitsspeicher behalten, bis CityDoctor geschlossen oder ein neues Zip-Archiv geladen wird.
+### Batch Validierung
+
+![Batch Validierung](img/zip_validation.png)
+
+Die "Alle Dateien prüfen" Schaltfläche öffnet die Einstellungen für die Batch-Validierung. Sie kann ohne vorheriges entpacken der Dateien durchgeführt werden und verfügt über zwei Vorgehensweisen:
+
+### Standardmodus 
+Der Standardmodus führt die Validierung über alle Dateien im Archiv aus. Komprimierte Dateien werden hierbei automatisch entpackt. Wie bei der Individuellen Validierung werden die Ergebnisse im Arbeitsspeicher gehalten und können mit dem CityDoctor inspiziert werden.
+### Niedriger Arbeitsspeicherverbrauchsmodus (Datenstream Modus)
+In diesem Modus werden Datenstreams genutzt, um die Features der Stadtmodelle einzeln einzulesen und zu validieren. Dies reduziert den benötigten Arbeitsspeicher, da die Dateien zur überprüfung nicht entpackt werden müssen. Dies bedeutet jedoch auch, dass der Status der Dateien unverändert bleibt. Die Ergebnisse werden in Validierungsberichten gespeichert und können nicht in CityDoctor inspiziert werden.

docs/en/zipFiles.md

+# Zip Archives
+
+CityDoctor is capable of parsing zip archives to enable the validation of contained CityGML files.
+
+## Loading a zip archive
+
+![Load archive](img/archive_load.png)
+
+To load a zip archive, select a zip file using file loading dialoge. CityDoctor will analyze the zip file for potential
+CityGml files.
+
+## Zip entry manager
+
+![Zip entry manager](img/archive_imported.png)
+
+CityDoctor will show the zip entry manager after successfully loading a zip archive. The zip entry manager has the following buttons:  
+
+1. **Show model:** Shows the city model of the selected entry in the main window of CityDoctor, giving access to the normal CityDoctor functionality. Only available for decompressed entries.
+2. **Decompress entry:** Decompresses the selected entry.
+3. **Error statistics:** Shows the error statistics of the selected entry. Only available for validated entries.
+4. **Decompress all entries:** Decompresses all entries of the archive.
+5. **Check all:** Opens the checking dialoge, allowing batch validation of all entries. See [validation](#validation) for more details.
+6. **Save reports:** Allows saving of validation reports. Available after at least one entry has been validated.
+
+![Color coding](img/color_coding.png)
+
+Entries display their current state via color coding. Possible states are:
+
+- **compressed(black):** A compressed entry is still 'zipped'.
+- **decompressed(blue):** A decompressed entry has been successfully 'unzipped' into the memory.
+- **empty model(gray):** A decompressed entry containing no city model or a model without any city objects.
+- **erroneous entry(dark red):** An entry which could not be successfully decompressed, due to either having an invalid CityGML file, being too big to be held in memory or encountering a problem while reading the file. The respective reason will be shown in the entry's metadata.
+- **validated with / without errors (bright red / green respectively)**
+
+!!! note
+    The original zip file or its entries will not be changed. Decompressed data is a copy of the source entry.
+
+
+## Validation
+
+### Validation of individual entries
+
+Decompressed entries can be validated individually through the CityDoctor main window. CityDoctor will retain the validation results for each entry in memory until the application is closed or a new zip archive is loaded.
+### Batch validation
+
+![Zip validation](img/zip_validation.png)
+
+The "Check all" button in the zip entry manager opens the option window for the batch validation. This process does not require prior decompression of the entries and offers two modes of operation:
+### Default mode 
+The default batch validation mode validates each entry within the archive. Compressed entries will be automatically decompressed during this process. Like with the individual validation, the results are held in memory and can be inspected in CityDoctor.
+### Low memory mode (stream mode)
+Low memory mode utilizes datastreams to read and check the city model features individually. This significantly decreases memory overhead and usage by eliminating the need for entry decompression. However, this also means that the state of entries remains unchanged. As a result, the results of the validation cannot be inspected within CityDoctor and will be recorded in report files at the designated output location.
\ No newline at end of file