# PointCab Renamer - Benutzerhandbuch

**Version 4.1** | Datum: 14. Januar 2026

---

## Inhaltsverzeichnis

1. [Einführung](#einführung)
2. [Installation](#installation)
3. [Programmstart](#programmstart)
4. [Die drei Modi](#die-drei-modi)
   - [Einzelprojekt-Modus](#einzelprojekt-modus)
   - [Batch-Modus](#batch-modus)
   - [Projekt-Merger](#projekt-merger)
5. [Konfiguration](#konfiguration)
6. [Troubleshooting](#troubleshooting)
7. [FAQ](#faq)

---

## Einführung

### Was ist der PointCab Renamer?

Der **PointCab Renamer** ist ein Werkzeug zur automatischen Umbenennung von PointCab-Projektdateien. Es löst das Problem, dass PointCab-Scandateien oft kryptische Namen haben (z.B. `1.lsd`, `2.lsd`) und benennt diese nach einem einheitlichen Schema um:

**Format:** `[ClusterName]_[ScanName].[Erweiterung]`

**Beispiel:** `EG_Flur_scan001.lsd`

### Hauptfunktionen

- **Einzelprojekt-Modus**: Ein einzelnes PointCab-Projekt umbenennen
- **Batch-Modus**: Mehrere Projekte gleichzeitig verarbeiten
- **Projekt-Merger**: Mehrere Projekte in ein Zielprojekt zusammenführen
- **Cluster-Bereinigung**: Automatische Entfernung von Suffixen wie `_re`, `_li` aus Clusternamen
- **Detailliertes Logging**: Vollständige Protokollierung aller Änderungen

---

## Installation

### Windows

1. Laden Sie die Datei `pointcab_renamer.exe` herunter
2. Speichern Sie die Datei in einem beliebigen Ordner (z.B. `C:\Tools\`)
3. Kopieren Sie die `cluster_cleanup.txt` in denselben Ordner
4. Starten Sie das Programm mit Doppelklick auf die `.exe`

### Ubuntu/Linux

1. Laden Sie die Datei `pointcab_renamer` herunter
2. Speichern Sie die Datei in einem beliebigen Ordner (z.B. `/home/benutzer/tools/`)
3. Kopieren Sie die `cluster_cleanup.txt` in denselben Ordner
4. Machen Sie die Datei ausführbar:
   ```bash
   chmod +x pointcab_renamer
   ```
5. Starten Sie das Programm:
   ```bash
   ./pointcab_renamer
   ```

### Aus dem Quellcode (für Entwickler)

1. Stellen Sie sicher, dass Python 3.8+ installiert ist
2. Laden Sie den Quellcode herunter
3. Starten Sie mit:
   ```bash
   python pointcab_renamer.py
   ```

---

## Programmstart

### Hauptmenü

Nach dem Start erscheint das Hauptmenü mit drei Optionen:

```
╔═══════════════════════════════════════════╗
║        PointCab Renamer v4.1              ║
╠═══════════════════════════════════════════╣
║                                           ║
║   [Einzelprojekt umbenennen]              ║
║                                           ║
║   [Batch-Verarbeitung]                    ║
║                                           ║
║   [Projekt Merger]                        ║
║                                           ║
╚═══════════════════════════════════════════╝
```

---

## Die drei Modi

### Einzelprojekt-Modus

**Verwendung:** Wenn Sie ein einzelnes PointCab-Projekt umbenennen möchten.

#### Schritt-für-Schritt-Anleitung

1. Klicken Sie auf **"Einzelprojekt umbenennen"**
2. Wählen Sie die **LSDX-Projektdatei** aus (z.B. `Am_Upstall_4.lsdx`)
3. Wählen Sie den **PointCloud-Ordner** aus (enthält die `.lsd` Dateien)
4. Das Programm zeigt eine **Vorschau** der Änderungen:
   ```
   Vorschau der Umbenennung:
   ─────────────────────────
   1.lsd → EG_Flur_scan001.lsd
   2.lsd → EG_Flur_scan002.lsd
   3.lsd → OG_Bad_scan001.lsd
   ...
   ```
5. Klicken Sie auf **"Umbenennen starten"**
6. Nach Abschluss wird ein Protokoll angezeigt

#### Dateistruktur (Vorher → Nachher)

**Vorher:**
```
Am_Upstall_4_PointCloud/
├── 1.lsd
├── 2.lsd
├── 3.lsd
└── ...
```

**Nachher:**
```
Am_Upstall_4_PointCloud/
├── EG_Flur_scan001.lsd
├── EG_Flur_scan002.lsd
├── OG_Bad_scan001.lsd
└── ...
```

---

### Batch-Modus

**Verwendung:** Wenn Sie mehrere PointCab-Projekte auf einmal verarbeiten möchten.

#### Schritt-für-Schritt-Anleitung

1. Klicken Sie auf **"Batch-Verarbeitung"**
2. Wählen Sie den **Basisordner** aus, der alle Projekte enthält
3. Das Programm erkennt automatisch alle PointCab-Projekte:
   ```
   Gefundene Projekte:
   ─────────────────────
   ☑ Projekt_A (15 Scans)
   ☑ Projekt_B (22 Scans)
   ☑ Projekt_C (8 Scans)
   ```
4. Wählen Sie die gewünschten Projekte aus (oder behalten Sie alle ausgewählt)
5. Klicken Sie auf **"Batch-Verarbeitung starten"**
6. Der Fortschritt wird angezeigt:
   ```
   Verarbeite Projekt 1/3: Projekt_A
   [████████████░░░░░░░░] 60%
   ```
7. Nach Abschluss wird eine Zusammenfassung angezeigt

#### Erwartete Ordnerstruktur

```
Basisordner/
├── Projekt_A/
│   ├── Projekt_A.lsdx
│   └── Projekt_A_PointCloud/
│       ├── 1.lsd
│       └── ...
├── Projekt_B/
│   ├── Projekt_B.lsdx
│   └── Projekt_B_PointCloud/
└── Projekt_C/
    ├── Projekt_C.lsdx
    └── Projekt_C_PointCloud/
```

---

### Projekt-Merger

**Verwendung:** Wenn Sie mehrere PointCab-Projekte in ein einziges Projekt zusammenführen möchten.

#### Schritt-für-Schritt-Anleitung

1. Klicken Sie auf **"Projekt Merger"**
2. Wählen Sie den **Modus**:
   - **Einzelprojekt zusammenführen**: Ein Quellprojekt → Zielprojekt
   - **Batch-Merge**: Mehrere Quellprojekte → Zielprojekt
3. Wählen Sie das **Zielprojekt** (in das zusammengeführt wird)
4. Wählen Sie das/die **Quellprojekt(e)**
5. Das Programm zeigt eine **Vorschau** mit Konfliktauflösung:
   ```
   Merge-Vorschau:
   ─────────────────────
   Zielprojekt: Haupt_Projekt (5 Cluster, 25 Scans)
   Quellprojekt: Teil_A (2 Cluster, 10 Scans)
   
   Zu übertragende Dateien:
   - EG_Flur_scan001.lsd
   - EG_Flur_scan002.lsd (Konflikt → EG_Flur_scan002_merged_1.lsd)
   - ...
   ```
6. Klicken Sie auf **"Merge starten"**
7. Nach Abschluss werden die Statistiken angezeigt:
   ```
   Merge abgeschlossen!
   ─────────────────────
   Cluster vorher: 5 → nachher: 7
   Scans vorher: 25 → nachher: 35
   Dateien kopiert: 10
   Konflikte gelöst: 1
   ```

#### Konfliktauflösung

Wenn eine Datei im Zielprojekt bereits existiert:
- Die neue Datei wird umbenannt: `dateiname_merged_1.lsd`
- Bei weiteren Konflikten: `dateiname_merged_2.lsd`, etc.
- Die LSDX-Datei wird entsprechend aktualisiert

#### Wichtige Hinweise

- **Backup**: Das Zielprojekt wird vor dem Merge gesichert (`.lsdx.backup`)
- **UUID-Regenerierung**: Alle übertragenen Elemente erhalten neue eindeutige IDs
- **Cluster-Duplikate**: Gleichnamige Cluster werden zusammengeführt

---

## Konfiguration

### Die Datei cluster_cleanup.txt

Diese Konfigurationsdatei definiert, welche Suffixe aus Clusternamen entfernt werden sollen.

#### Speicherort

- **Windows**: Im selben Ordner wie `pointcab_renamer.exe`
- **Linux**: Im selben Ordner wie `pointcab_renamer`

#### Format

```
# Dies ist ein Kommentar
_re
_li
_mi
_mi-li
_mi-re
```

- Jede Zeile = ein zu entfernender String
- Zeilen mit `#` am Anfang sind Kommentare
- Leere Zeilen werden ignoriert

#### Beispiel

Mit der obigen Konfiguration:
- `Flur_re` → `Flur`
- `Bad_mi-li` → `Bad`
- `Küche_li` → `Küche`

#### Konfiguration neu laden

Änderungen an `cluster_cleanup.txt` werden nach einem Neustart oder über den Button **"Konfiguration neu laden"** übernommen.

---

## Troubleshooting

### Häufige Fehler und Lösungen

#### "LSDX-Datei nicht gefunden"

**Problem**: Das Programm kann die Projektdatei nicht finden.

**Lösung**:
- Stellen Sie sicher, dass die `.lsdx`-Datei im Projektordner existiert
- Prüfen Sie, ob Sie Leserechte für die Datei haben
- Der Dateiname sollte mit `.lsdx` enden (nicht `.LSDX`)

#### "PointCloud-Ordner nicht gefunden"

**Problem**: Der Ordner mit den Scandaten fehlt.

**Lösung**:
- Der Ordner muss `_PointCloud` im Namen haben
- Beispiel: `Projekt_A_PointCloud`
- Prüfen Sie die Ordnerstruktur

#### "Keine Projekte gefunden" (Batch-Modus)

**Problem**: Im Basisordner werden keine Projekte erkannt.

**Lösung**:
- Jedes Projekt muss eine `.lsdx`-Datei und einen `_PointCloud`-Ordner haben
- Der Projektname in der LSDX muss mit dem Ordnernamen übereinstimmen

#### "Zugriff verweigert"

**Problem**: Dateien können nicht umbenannt werden.

**Lösung**:
- Schließen Sie PointCab
- Prüfen Sie, ob andere Programme die Dateien verwenden
- Unter Windows: Als Administrator ausführen
- Unter Linux: Prüfen Sie die Dateiberechtigungen

#### "GUI startet nicht" (Linux)

**Problem**: Keine grafische Oberfläche unter Linux.

**Lösung**:
- Installieren Sie tkinter: `sudo apt install python3-tk`
- Stellen Sie sicher, dass ein Display verfügbar ist

---

## FAQ

### Allgemeine Fragen

**F: Werden die Originaldateien gelöscht?**

A: Nein, die Dateien werden nur umbenannt. Es werden keine Daten gelöscht.

**F: Kann ich die Umbenennung rückgängig machen?**

A: Die ursprünglichen Namen werden im Log-Datei protokolliert. Eine automatische Rückgängig-Funktion gibt es nicht.

**F: Funktioniert das Tool auch mit älteren PointCab-Versionen?**

A: Das Tool wurde für PointCab-Projekte mit LSDX-Format entwickelt. Ältere Formate werden möglicherweise nicht unterstützt.

**F: Wie viele Projekte kann ich im Batch-Modus verarbeiten?**

A: Es gibt keine feste Grenze. Die Verarbeitungszeit hängt von der Anzahl der Scans ab.

### Technische Fragen

**F: Wo werden die Log-Dateien gespeichert?**

A: Im Projektordner, mit dem Format:
- Einzelprojekt: `rename_YYYYMMDD_HHMMSS.log`
- Batch: `batch_YYYYMMDD_HHMMSS.log`
- Merger: `merge_YYYYMMDD_HHMMSS.log`

**F: Was passiert bei einem Stromausfall während der Verarbeitung?**

A: Die bereits umbenannten Dateien bleiben umbenannt. Die LSDX-Datei wird erst nach erfolgreicher Umbenennung aktualisiert.

**F: Kann ich das Tool über die Kommandozeile nutzen?**

A: Aktuell nur mit grafischer Oberfläche. Kommandozeilen-Unterstützung ist für eine zukünftige Version geplant.

### Merger-Fragen

**F: Was passiert mit den Originalprojekten beim Merge?**

A: Die Quellprojekte werden nicht verändert. Dateien werden kopiert, nicht verschoben.

**F: Kann ich den Merge rückgängig machen?**

A: Die ursprüngliche LSDX wird als `.backup` gespeichert. Die kopierten Dateien müssen manuell gelöscht werden.

**F: Werden alle Unterordner (Previews, etc.) auch gemergt?**

A: Ja, alle relevanten Unterordner werden übertragen.

---

## Support

Bei Fragen oder Problemen wenden Sie sich an Ihren Administrator.

---

*PointCab Renamer v4.1 - © 2026*
