From 2a045a6b8ade9e3bf28ca3fba2e6b206341ed260 Mon Sep 17 00:00:00 2001
From: Doc <Doctor_Luigi@aol.com>
Date: Sun, 28 Sep 2025 12:57:54 +0200
Subject: [PATCH] big readme update to better explain what this project does

---
 README.md | 67 +++++++++++++++++++++++++++++++++++++++++++++++++++----
 1 file changed, 63 insertions(+), 4 deletions(-)

diff --git a/README.md b/README.md
index fc4b93c..de23dca 100644
--- a/README.md
+++ b/README.md
@@ -1,6 +1,65 @@
 ## BSPViz
-Mein BSP Node builder und renderer für meine Seminararbeit
 
-# Todo:
-- [x] Implement geom utils
-- [x] Implement BSP
\ No newline at end of file
+BSPViz ist ein kompaktes Go-Tool zum Analysieren von Doom-WAD-Dateien. Es lädt
+Maps, inspiziert Geometriedaten und baut daraus BSP-Bäume samt Statistiken oder
+Visualisierungen. Das Projekt entstand im Rahmen einer Seminararbeit und dient
+als Baukasten, um verschiedene BSP-Build-Heuristiken auszuprobieren.
+
+### Features
+- Lädt klassische Doom-WADs und listet die enthaltenen Lumps
+- Extrahiert einzelne Lumps als Dateien zum Debuggen
+- Führt Geometrie-Diagnosen (Segment-Splits, Bounding Boxes) durch
+- Baut BSP-Bäume mit konfigurierbaren Parametern und misst resultierende Metriken
+- Exportiert BSP-Strukturen als DOT, optional weiterverarbeitbar zu PNG
+
+### Voraussetzungen
+- Go >= 1.25 (siehe `go.mod`)
+- Graphviz (nur nötig, wenn DOT-Dateien gerendert werden sollen)
+- Eine Doom-kompatible WAD-Datei als Eingabe
+
+#### Graphviz installieren
+- **Linux (Debian/Ubuntu):** `sudo apt install graphviz`
+- **macOS (Homebrew):** `brew install graphviz`
+- **Windows (Chocolatey):** `choco install graphviz`
+
+Alternativ stehen aktuelle Pakete und Installationshinweise auch auf der offiziellen Seite:
+<https://graphviz.org/download/>
+
+### Installation
+```bash
+git clone <dein-repo-url>
+cd bspviz
+go build ./...
+```
+
+Alternativ lässt sich das Tool ohne vorherigen Build direkt ausführen:
+
+```bash
+go run ./main.go -wad MYMAP.wad -map MAP01 -info
+```
+
+### Verwendung
+Wichtige Flags (vollständige Übersicht mit `-h`):
+- `-wad <pfad>` (Pflicht): Pfad zur WAD-Datei.
+- `-map <name>`: Map-Marker wie `MAP01`, `E1M1` oder benutzerdefinierte Namen.
+- `-list`: WAD-Verzeichnis anzeigen und beenden.
+- `-info`: Basisstatistiken zu Vertices und Linedefs ausgeben.
+- `-extract <L1,L2>`: Angegebene Lumps (z. B. `VERTEXES,LINEDEFS`) nach `-out` speichern.
+- `-geomtest`: Segment- und Split-Diagnose für die gewählte Map ausgeben.
+- `-buildbsp`: BSP-Baum erzeugen; Parameter wie `-alpha`, `-beta`, `-leafmax`,
+  `-maxdepth`, `-cands` und `-seed` steuern das Verhalten.
+- `-dot <datei.dot>`: Gebauten BSP als DOT exportieren (setzt `-buildbsp` voraus;
+  benötigt ein installiertes Graphviz für die weitere Verarbeitung).
+
+Beispiel: BSP bauen und als PNG visualisieren (Graphviz vorausgesetzt):
+```bash
+go run ./main.go -wad MYMAP.wad -map MAP01 -buildbsp -dot tree.dot
+dot -Tpng tree.dot -o tree.png
+```
+
+### Entwicklung
+- Code formatieren: `gofmt -w .`
+- Tests ausführen: `go test ./...`
+- Temporäre Artefakte (DOT/PNG) sind über `.gitignore` bereits ausgeschlossen.
+
+Beiträge, Erweiterungen oder neue Heuristiken sind willkommen.