# Pipeline LiDAR Archéologique - Docker

Workflow automatisé pour générer des visualisations exploitables à partir de données LiDAR pour la détection de structures archéologiques.

## Visualisations (20 par fichier)

### Visualisations principales
| # | Visualisation | Utilité archéologique |
|---|--------------|----------------------|
| 1 | **Hillshade multidirectionnel** | Murs, terrasses, structures linéaires, routes |
| 2 | **Pente (Slope)** | Murs de soutènement, talus, changements brusques |
| 3 | **Aspect (Orientation)** | Direction des pentes, exposition |
| 4 | **Courbure (Curvature)** | Fossés, terrasses, talus, concavité/convexité |
| 5 | **Éclairage solaire** | Simulation de l'éclairage matinal |
| 6 | **Sky-View Factor** | Structures, tumulus, fondations (ray-tracing 16 azimuts) |
| 7 | **Local Relief Model** | Micro-reliefs, fossés, levées de terrain |
| 8 | **Positive Openness** | Élévations, tumulus, bâtiments (ray-tracing 8 directions) |
| 9 | **Negative Openness** | Cavités, fossés, souterrains (ray-tracing 8 directions) |

### Visualisations avancées
| # | Visualisation | Description | Détection |
|---|--------------|-------------|-----------|
| 10 | **MSRM** | Multi-Scale Relief Model (sigma 5/10/25/50/100m) | Tumulus, fossés, murs à toutes les échelles |
| 11 | **TPI multi-échelle** | Topographic Position Index (5m + 100m) | Crêtes, vallées, plateformes |
| 12 | **Dépressions** | Remplissage cuvettes + différence | Dolines, sinkholes, zones inondables |
| 13 | **SAILORE** | LRM adaptatif (noyau = f(pente)) | Terrain hétérogène, tout relief |
| 14 | **Rugosité** | Écart-type de l'élévation | Surfaces anthropiques vs naturelles |
| 15 | **Anomalies statistiques** | Z-score + Local Moran's I | Anomalies topographiques significatives |
| 16 | **Ondelette Mexican Hat** | CWT 2D multi-échelle | Tumulus, fossés circulaires |
| 17 | **Texture GLCM** | Contraste, entropie, homogénéité | Labour, surfaces archéologiques |
| 18 | **Accumulation de flux** | Algorithme D8 hydrologique | Fossés d'enceinte, routes antiques |

### Cartes de référence IGN
| # | Visualisation | Source |
|---|--------------|--------|
| 19 | **Photographie aérienne IGN** | Orthophotographie WMTS |
| 20 | **Carte topographique IGN** | Plan IGN V2 WMTS |

## Architecture modulaire

```
lidar_pipeline/
├── __init__.py          # Exports publics
├── __main__.py          # Point d'entrée: python -m lidar_pipeline
├── cli.py               # argparse + logging + main()
├── gpu.py               # CuPy/numpy abstraction (HAS_GPU, to_gpu, to_cpu, xp_*)
├── dtm.py               # Classification PDAL + génération DTM
├── visualizations.py    # Fonctions generate_* (20 visualisations)
├── ign.py               # Téléchargement tuiles IGN + overlay
├── rendering.py          # Colormaps, tif_to_png, rapport PDF
└── pipeline.py           # LidarArchaeoPipeline (orchestration + registry)
```

Ajouter une visualisation = 1 fonction + 1 entrée dans `VIZ_STEPS` + 1 entrée dans `COLORMAPS`.

## Installation Docker

```bash
cd /votre/dossier/lidar
mkdir -p input

# Copiez vos fichiers .laz dans input/
cp /chemin/vos/fichiers/*.laz input/

# Build l'image Docker
docker build -t lidar-lidar .
```

## Utilisation

### Traitement complet avec GPU (recommandé)
```bash
./run.sh -g
```

### Traitement standard (CPU seul)
```bash
./run.sh
```

### Options du script run.sh
```
./run.sh [options]
  -r RESOLUTION   Résolution en m/px (défaut: 0.5)
  -w WORKERS      Nombre de workers parallèles (défaut: 1)
  -g              Activer l'accélération GPU
  -v              Mode verbeux (timestamps + niveaux)
  --debug         Mode debug (détails internes fichier:ligne)
  -f / --force    Régénérer tous les fichiers même si les WebP existent
  --file NOM      Traiter un seul fichier LAZ (pour tests)
  -h              Afficher l'aide
```

### Exemples
```bash
# Traitement standard
./run.sh

# Avec accélération GPU
./run.sh -g

# GPU + mode verbeux
./run.sh -g -v

# GPU + 4 workers parallèles
./run.sh -g -w 4

# Haute résolution + GPU + debug
./run.sh -g -v -r 0.2

# Forcer la régénération de tous les fichiers
./run.sh -g --force

# Traiter un seul fichier pour test
./run.sh -g --file 6881
```

### Utilisation directe Docker
```bash
# Traitement standard
docker run --rm -v $(pwd)/input:/data/input:ro -v $(pwd)/output:/data/output lidar-lidar

# Avec GPU
docker run --rm --gpus all -v $(pwd)/input:/data/input:ro -v $(pwd)/output:/data/output lidar-lidar

# Mode verbeux
docker run --rm --gpus all -v $(pwd)/input:/data/input:ro -v $(pwd)/output:/data/output \
  lidar-lidar python3 -m lidar_pipeline /data/input -o /data/output -v

# Un seul fichier (test rapide)
docker run --rm --gpus all -v $(pwd)/input:/data/input:ro -v $(pwd)/output:/data/output \
  lidar-lidar python3 -m lidar_pipeline /data/input -o /data/output --file 6881

# Forcer la régénération
docker run --rm --gpus all -v $(pwd)/input:/data/input:ro -v $(pwd)/output:/data/output \
  lidar-lidar python3 -m lidar_pipeline /data/input -o /data/output --force
```

## Structure des dossiers

```
.
├── input/                    # Fichiers .laz (monté en read-only)
├── output/                   # Résultats générés
│   ├── DTM/                 # Modèles numériques de terrain (GeoTIFF)
│   ├── visualisations/       # Images WebP par fichier LAZ
│   │   ├── fichier_6881/     # Un sous-dossier par fichier LAZ
│   │   │   ├── ..._hillshade_multi.webp
│   │   │   ├── ..._svf.webp
│   │   │   ├── ..._mslrm.webp
│   │   │   └── ... (20 visualisations)
│   │   └── fichier_6882/
│   │       └── ...
│   └── rapports/            # Rapports PDF A3 par fichier
│       ├── fichier_6881_rapport.pdf
│       └── fichier_6882_rapport.pdf
├── lidar_pipeline/          # Package Python modulaire
│   ├── __init__.py
│   ├── cli.py
│   ├── gpu.py
│   ├── dtm.py
│   ├── visualizations.py
│   ├── ign.py
│   ├── rendering.py
│   └── pipeline.py
├── process_lidar.py          # Point d'entrée compatible
├── Dockerfile
├── run.sh
└── README.md
```

## Paramètres

| Paramètre | Option | Défaut | Description |
|-----------|--------|--------|-------------|
| Résolution | `-r` | 0.5 | Résolution en mètres par pixel |
| Workers | `-w` | 1 | Nombre de CPU pour traitement parallèle |
| Output | `-o` | /data/output | Dossier de sortie |
| Force | `-f/--force` | off | Régénérer même si les WebP existent |
| File | `--file` | tous | Traiter un seul fichier (pour tests) |
| Verbose | `-v` | off | Mode verbeux (timestamps + niveaux) |
| Debug | `--debug` | off | Mode debug (détails internes) |

### Résolution recommandée
- `0.2` — Très fine, bâtiments individuels (lent)
- `0.5` — Recommandée archéologie (équilibre vitesse/détail)
- `1.0` — Rapide, grandes structures uniquement

## Interprétation archéologique

### Pour détecter les cavités et souterrains
1. **Negative Openness** — Zones sombres = creux profonds
2. **Dépressions** — Carte spécifique des dolines et sinkholes
3. **Local Relief Model** — Zones bleues = dépressions
4. **Hillshade** — Ombres inhabituelles en forme de trous

### Pour détecter structures et bâtiments anciens
1. **MSRM** — Détection multi-échelle de tous les reliefs
2. **Sky-View Factor** — Structures géométriques claires
3. **SAILORE** — LRM adaptatif pour terrain hétérogène
4. **Anomalies statistiques** — Anomalies topographiques significatives

### Pour hydrologie et fossés
1. **Accumulation de flux** — Fossés d'enceinte, routes antiques
2. **Dépressions** — Zones de collecte d'eau, dolines
3. **Negative Openness** — Fossés et tranchées

## Dépannage

```bash
# Vérifier Docker
docker --version

# Shell dans le conteneur
docker run --rm -it -v $(pwd)/input:/data/input -v $(pwd)/output:/data/output \
  --entrypoint bash lidar-lidar

# Reconstruire l'image
docker build --no-cache -t lidar-lidar .

# Nettoyer
docker system prune -a
```

### Erreur mémoire
Augmenter la mémoire Docker à 16Go+ pour les gros fichiers LiDAR HD.