diff --git a/docs/ProjektDokumentation.md b/docs/ProjektDokumentation.md new file mode 100644 index 0000000..3aa49b3 --- /dev/null +++ b/docs/ProjektDokumentation.md @@ -0,0 +1,90 @@ +# BSPViz Projektdokumentation + +## 1. Projektueberblick +- **Zielsetzung:** BSPViz ist ein Go-gestuetztes CLI-Tool zum Analysieren klassischer Doom-WAD-Dateien. Es entstand im Rahmen einer Seminararbeit, um Parsing, Geometrieverarbeitung und BSP-Heuristiken prototypisch zu untersuchen. +- **Funktionsumfang:** Lesen von IWAD/PWAD-Archiven, Extraktion einzelner Map-Lumps, Generieren von Geometrie-Statistiken, Aufbau und Bewertung von BSP-Baeumen sowie Export als DOT- oder Overlay-PNG. +- **Technologiestack:** Go 1.25, optionale Nutzung von Graphviz (dot) fuer PNG-Renderings, reine Standardbibliothek ohne externe Abhaengigkeiten. +- **Artefakte im Repository:** Beispiel-WAD-Dateien (`MYMAP*.wad`), Einstiegspunkt `main.go`, modulare Pakete unter `internal/`. + +## 2. Architektur und Codeorganisation +- **CLI (main.go):** Verantwortlich fuer Flag-Parsing, orchestriert WAD-Laden, optionales Listing, Informationsausgabe, Lump-Export und BSP-Erstellung. Triggert Visualisierungen ueber `internal/viz`. +- **WAD-Layer (`internal/wad`):** Kapselt Dateizugriff, Directory-Parsen und sichere Lump-Lesungen. `Open` validiert Header und Directory (Dateigroesse, Grenzen, Marker), `LoadMapLumps` liefert selektierte Rohbytes fuer Map-spezifische Lumps. +- **Map-Parsing (`internal/mapfmt`):** Wandelt Lump-Rohdaten (`VERTEXES`, `LINEDEFS`) in typsichere Strukturen (`MapData`) und erzeugt Segmentlisten fuer BSP-Builds. +- **Geometrie (`internal/geom`):** Stellt Vektor-Operationen, AABB-Berechnung, Seitenklassifikation, Segment-Splitting und Line-Segment-Schnittpunkte bereit. Alle Funktionen operieren auf float64 und nutzen ein globales Epsilon (`EPS`). +- **BSP-Engine (`internal/bsp`):** Implementiert heuristischen Baumaufbau. `Build` rekursiert ueber Segmente, waehlt Splitkandidaten per Kostenfunktion (`evalCost`) und liefert Knoten/Leaf-Strukturen inklusive Metriken (`Measure`). +- **Visualisierung (`internal/viz`):** + - `dot.go`: Serialisiert BSP-Baeume in Graphviz-DOT, optionaler Aufruf von `dot` fuer PNG. + - `png.go`: Rendered Map-Linien, Split-Ebenen und Leaf-Segmente in ein Overlay-Bild (RGB, Bresenham-basierte Linien). + +Die Module folgen einer klaren Einbahn-Abhaengigkeit: `main` -> `wad` -> `mapfmt`/`geom` -> `bsp` -> `viz`. Tests fuer Kernpakete liegen jeweils in `*_test.go`. + +## 3. Ablauf und Datenfluss +1. **CLI-Start:** Flags validieren (`-wad` Pflicht, Default-Map `MAP01`). Bei `-list` erfolgt ein frueher Exit nach Directory-Ausgabe. +2. **Map-Lesen:** `wad.Open` laedt das WAD, `FindMap` bestimmt Marker-Bereich, `LoadMapLumps` liest benoetigte Lumps in Memory. +3. **Parsing:** `mapfmt.LoadMap` interpretiert Rohbytes zu `MapData` (Vertices, Linedefs). `LinedefsToSegs` erstellt Segmentreprasentationen fuer weitere Verarbeitung. +4. **Geometrieanalyse:** Je nach Flag: + - `-info`: Zaehlt Vertex/Linedef-Anzahlen, Pruefung auf Formatabweichungen. + - `-geomtest`: Fuehrt Segment-Split-Probe inklusive Bounding-Box-Analyse aus. + - `-extract`: Schreibt gewuenschte Lumps als `.lmp` in Zielordner. +5. **BSP-Bau (`-buildbsp`):** + - `bsp.Build` waehlt Split-Ebenen anhand von Gewichtung (`alpha` Splits, `beta` Balance). + - Rekursion stoppt kontrolliert via `leafmax`, `maxdepth`. + - `bsp.Measure` liefert Kennzahlen wie Knotenzahl, Leaf-Segmente, Baumtiefe. +6. **Visualisierung:** + - `-dot`: Speichert DOT-Datei; `-treepng` ruft optional Graphviz fuer Renderings. + - `-overlay`: Zeichnet Map und Splits als PNG mit zufaellig gefaerbten Leaves. + +## 4. Kommandozeilenreferenz +| Flag | Pflicht | Beschreibung | +|------|---------|--------------| +| `-wad ` | Ja | Pfad zu IWAD/PWAD-Datei. | +| `-map ` | Nein | Map-Marker (Default `MAP01`). | +| `-list` | Nein | Listet Directory und beendet. | +| `-info` | Nein | Zeigt Vertex-/Linedef-Statistiken nach Parsing. | +| `-extract ` | Nein | Extrahiert benannte Lumps als `.lmp`. Nutzt `-out` als Ziel (Default `.`). | +| `-geomtest` | Nein | Fuehrt Geometriediagnose (Seg-Splits, AABB) durch. | +| `-buildbsp` | Nein | Startet BSP-Aufbau mit Parametern `-alpha`, `-beta`, `-eps`, `-leafmax`, `-maxdepth`, `-cands`, `-seed`. | +| `-dot ` | Nein | Speichert DOT-Export (setzt `-buildbsp` voraus). | +| `-treepng ` | Nein | Erstellt PNG ueber Graphviz (benoetigt installierten `dot`). | +| `-overlay ` | Nein | Zeichnet Map+Splits als PNG ohne Graphviz-Abhaengigkeit. | + +### Beispiel-Workflows +- Map-Verzeichnis einsehen: `go run ./main.go -wad MYMAP.wad -list` +- Statistik-Aufruf: `go run ./main.go -wad MYMAP3.wad -map MAP01 -info` +- Lumps extrahieren: `go run ./main.go -wad MYMAP2.wad -map E1M1 -extract VERTEXES,LINEDEFS -out dumps` +- BSP bauen & visualisieren: + ``` + go run ./main.go -wad MYMAP.wad -map MAP01 -buildbsp -alpha 8 -beta 2 -dot tree.dot -overlay overlay.png + dot -Tpng tree.dot -o tree.png # optionales Rendering + ``` + +## 5. Implementierungsdetails +- **Robustes WAD-Parsen:** Integritaetschecks fuer Header, Directory-Grenzen sowie Lump-Adressen verhindern Out-of-Bounds-Zugriffe. `trimName` normalisiert Lump-Namen auf 8 Zeichen. +- **Geometrie-Splitting:** `geom.SplitSeg` klassifiziert Segmente anhand der orientierten Distanz (`Side`). Schnittpunkte werden nur akzeptiert, falls sie klar innerhalb des Segments liegen (`EPS`-Toleranz). +- **BSP-Heuristik:** `selectSplit` sampelt Segmente in regulierten Schritten (`Cands`). Die Kostenfunktion kombiniert Split-Anzahl und Balance; Parameter koennen zur Evaluierung verschiedener Heuristiken variiert werden. +- **Overlay-Rendering:** Transformation `worldToScreen` skaliert Doom-Koordinaten auf Bildgroesse, invertiert Y-Achse und ergaenzt Rand. Splits erscheinen als gelbe Linien, Leafs werden farblich zufaellig hervorgehoben. +- **Determinismus:** `-seed` beeinflusst den RNG der BSP-Heuristik; `seed=0` wird intern auf `1` gesetzt, um nachvollziehbare Ergebnisse zu erhalten. + +## 6. Entwicklungs- und Testleitfaden +- **Abhaengigkeiten:** Go >= 1.25, optional Graphviz (`dot`) fuer DOT-zu-PNG-Konvertierung. +- **Build:** `go build ./...` erzeugt ein lokales Binary. +- **Direktausfuehrung:** `go run ./main.go ` vermeidet separaten Build. +- **Codeformat:** `gofmt -w .` +- **Tests:** `go test ./internal/...` (Pakete `wad`, `mapfmt`, `geom`, `bsp`, `viz` verfuegen ueber eigenstaendige Test-Suites). Top-Level-`main` enthaelt bewusst keine Tests. +- **Beispieldaten:** Die mitgelieferten `MYMAP*.wad` dienen als kleinskalige Input-Setups fuer manuelle und automatisierte Checks. + +## 7. Grenzen und Erweiterungsideen +- **Nicht abgedeckt:** Parsing weiterer Lumps (SEGS, SSECTORS etc.), 3D-Features moderner Ports, automatisierte DOT->PNG-Pipeline ohne Graphviz-Installation. +- **Moegliche Erweiterungen:** + 1. Zusae tzliche Heuristiken (z.B. zufaellige Kandidatenauswahl, Hybridkosten). + 2. Erweiterte Statistiken (Split-Histogramme, Leaf-Flachenberechnung). + 3. CLI-Subcommands oder Konfigdatei-Unterstuetzung. + 4. Export weiterer Formate (JSON-Serialisierung der BSP-Struktur). + +## 8. Projektressourcen +- **Quellcode:** Einstieg `main.go`, Modulverzeichnis `internal/`. +- **Dokumentation:** Diese Datei, bestehende README.md als Schnellstart. +- **Kontakt & Lizenz:** Nicht im Repository hinterlegt; fuer Seminarzwecke bitte Betreuer bzw. Repository-Inhaber ansprechen. + +> Hinweis: Alle Beschreibungen basieren auf dem Stand der Quelldateien vom 30.09.2025. Aenderungen im Code sollten zeitnah in dieser Dokumentation nachvollzogen werden. +