trimble_geodesy/README.md

# Trimble Geodesy Tool

Ein vollständiges Python-Programm mit grafischer Benutzeroberfläche (GUI) für geodätische Vermessungsarbeiten mit Trimble JXL-Dateien.

## Funktionen

### 1. JXL-Datei Analyse und Bearbeitung
- Trimble JXL-Dateien einlesen und analysieren
- Übersicht über Punkte, Stationen und Messungen
- Passpunkte entfernen
- Prismenkonstanten ändern
- Parameter bearbeiten

### 2. COR-Datei Generierung
- Aus JXL-Dateien Punktdateien im COR-Format berechnen
- Unterstützt zwei Stationierungsarten:
  - Erste Stationierung über eine Referenzlinie
  - Alle anderen als freie Stationierungen
- Export in verschiedene Formate (COR, CSV, TXT, DXF)

### 3. Koordinatensystem-Transformation
- Rotation um einen wählbaren Punkt
- Verschiebung in XY-Richtung
- Verschiebung in Z-Richtung
- Zwei Eingabemodi:
  - Manuelle Eingabe von Transformationsparametern
  - Definition über 2 Punkte (Ursprung und Y-Richtung)
- **Keine Maßstabsänderung** (wie gefordert)

### 4. Georeferenzierung
- Mindestens 3 Passpunkte für Transformation
- Rotation und Translation des Koordinatensystems
- **Keine Maßstabsänderung** (keine Helmert-Transformation)
- Restfehler ausgleichen und anzeigen
- Detaillierte Qualitätsparameter (RMSE, Residuen)

### 5. Netzausgleichung
- Methode der kleinsten Quadrate
- Basierend auf Beobachtungen der JXL-Datei
- Automatische Festpunkterkennung
- Ausgabe von:
  - Ausgeglichenen Koordinaten
  - Standardabweichungen
  - Residuen
  - Qualitätsparametern (Sigma-0, Chi-Quadrat, RMSE)

### 6. Referenzpunkt-Anpassung (NEU)
- Anpassung des Referenzpunktes 5001 (bei Referenzlinien-Stationierung)
- Eingabe neuer Koordinaten (X, Y, Z) für den Referenzpunkt
- Automatische Neuberechnung aller abhängigen Punkte
- Vorschau der Transformation mit allen betroffenen Punkten
- Export der transformierten JXL-Datei
- Validierung der Eingaben mit Warnungen bei problematischen Werten

## Installation und Start

### Voraussetzungen
- Python 3.8 oder höher
- PyQt5, NumPy, SciPy, lxml

### Wichtiger Hinweis: Externally-Managed-Environment (PEP 668)

Moderne Linux-Distributionen (Ubuntu 23.04+, Debian 12+, Fedora 38+) verwenden ein "externally-managed-environment". Das bedeutet, dass `pip install` ohne Virtual Environment folgenden Fehler erzeugt:

```
error: externally-managed-environment
× This environment is externally managed
```

**Lösung:** Verwenden Sie ein Virtual Environment (empfohlen) oder die automatischen Setup-Scripts.

---

### Methode 1: Automatische Installation (empfohlen)

#### Linux / macOS

```bash
cd /home/ubuntu/trimble_geodesy

# 1. Setup ausführen (einmalig)
./setup.sh

# 2. Programm starten
./run.sh
```

Falls `./setup.sh` nicht ausführbar ist:
```bash
chmod +x setup.sh run.sh
./setup.sh
```

#### Windows

```cmd
cd C:\Pfad\zum\trimble_geodesy

REM 1. Setup ausführen (einmalig)
setup.bat

REM 2. Programm starten
run.bat
```

---

### Methode 2: Manuelle Installation mit Virtual Environment

#### Linux / macOS

```bash
cd /home/ubuntu/trimble_geodesy

# Virtual Environment erstellen
python3 -m venv venv

# Virtual Environment aktivieren
source venv/bin/activate

# Abhängigkeiten installieren
pip install -r requirements.txt

# Programm starten
python3 main.py
```

#### Windows

```cmd
cd C:\Pfad\zum\trimble_geodesy

REM Virtual Environment erstellen
python -m venv venv

REM Virtual Environment aktivieren
venv\Scripts\activate.bat

REM Abhängigkeiten installieren
pip install -r requirements.txt

REM Programm starten
python main.py
```

---

### Fehlerbehebung

**Fehler: `python3-venv` nicht installiert (Linux)**
```bash
sudo apt install python3-venv   # Ubuntu/Debian
sudo dnf install python3-venv   # Fedora
```

**Fehler: Permission denied bei setup.sh**
```bash
chmod +x setup.sh run.sh
```

**Fehler: Qt-Plattform nicht gefunden**
```bash
sudo apt install libxcb-xinerama0 libxcb-cursor0  # Ubuntu/Debian
```

## Verwendung

### Workflow
1. **JXL-Analyse Tab**: JXL-Datei laden und analysieren
2. **COR-Generator Tab**: Koordinaten generieren und exportieren
3. **Transformation Tab**: Koordinatensystem rotieren/verschieben
4. **Georeferenzierung Tab**: Mit Passpunkten transformieren
5. **Netzausgleichung Tab**: Netzausgleichung durchführen
6. **Referenzpunkt anpassen Tab**: Referenzpunkt 5001 ändern und JXL neu berechnen

## Dateistruktur

```
trimble_geodesy/
├── main.py                     # Hauptprogramm mit GUI
├── requirements.txt            # Python-Abhängigkeiten
├── modules/
│   ├── __init__.py
│   ├── jxl_parser.py           # JXL-Datei Parser
│   ├── cor_generator.py        # COR-Datei Generator
│   ├── transformation.py       # Koordinatentransformation
│   ├── georeferencing.py       # Georeferenzierung
│   ├── network_adjustment.py   # Netzausgleichung
│   └── reference_point_adjuster.py  # Referenzpunkt-Anpassung (NEU)
├── output/                     # Ausgabeverzeichnis
└── README.md
```

## Technische Details

### JXL-Format
Das JXL-Format (Trimble JobXML) ist ein XML-basiertes Format für Vermessungsdaten:
- `<PointRecord>`: Punktdaten mit Koordinaten und Messungen
- `<StationRecord>`: Stationsinformationen
- `<TargetRecord>`: Prismeneinstellungen
- `<BackBearingRecord>`: Orientierungsdaten

### COR-Format
Das COR-Format ist ein einfaches Textformat für Koordinaten:
```
|Punkt |X |Y |Z |
|5001 |0.000 |0.000 |0.000 |
|5002 |0 | 11.407 | -0.035 |
```

### Transformation
Die Transformation verwendet eine 4-Parameter-Transformation:
- Translation X, Y, Z
- Rotation um die Z-Achse
- **Kein Maßstabsfaktor** (Maßstab = 1.0)

### Netzausgleichung
Die Netzausgleichung verwendet:
- Gauß-Markov-Modell
- Beobachtungsgleichungen für Richtungen und Strecken
- Iterative Lösung nach Gauß-Newton
- Varianzfortpflanzung für Genauigkeitsmaße

## Lizenz

Dieses Programm wurde für geodätische Vermessungsarbeiten entwickelt.

## Autor

Entwickelt für geodätische Vermessungsarbeiten mit Trimble-Instrumenten.