bspviz/docs/ProjektDokumentation.md

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 <pfad>	Ja	Pfad zu IWAD/PWAD-Datei.
-map <name>	Nein	Map-Marker (Default MAP01).
-list	Nein	Listet Directory und beendet.
-info	Nein	Zeigt Vertex-/Linedef-Statistiken nach Parsing.
-extract <L1,L2>	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 <pfad>	Nein	Speichert DOT-Export (setzt -buildbsp voraus).
-treepng <pfad>	Nein	Erstellt PNG ueber Graphviz (benoetigt installierten dot).
-overlay <pfad>	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 <flags> 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.