lardon3d/docs/concepts/reconstruction_layers.md

Reconstruction Layers

Définition

Les reconstruction layers (couches de reconstruction) organisent le processus de reconstruction 3D en étapes séquentielles et indépendantes. Chaque couche traite un sous-ensemble du problème, produit un résultat validé, et passe le relais à la couche suivante. Cette approche séquentielle garantit la stabilité, l'observabilité et la reprise après interruption.

L'idée centrale est de décomposer la reconstruction en couches de complexité croissante, chaque couche étant atomique : elle lit un état d'entrée validé, calcule, et écrit un nouvel état validé.

Statut

ARCHIVE / PLANNED POUR CETTE ABSTRACTION GÉNÉRIQUE. Le type de snapshot et les cinq layers proposés ci-dessous ne sont pas une API implémentée. Les jalons réels Track, Sparse SfM, BA, Phase H et MVS-M1 ont depuis été acquis par leurs contrats canoniques distincts ; ils ne valident ni ce modèle générique de layers, ni Dense complet, mesh, texturing ou viewer.

Place dans le pipeline

Tracks ( entrée )
    ↓
Layer 0: Initial Reconstruction (triangulation basique)
    ↓
Layer 1: Bundle Adjustment (optimisation locale)
    ↓
Layer 2: Dense Reconstruction (dense matching)
    ↓
Layer 3: Mesh Generation (mailllage)
    ↓
Layer 4: Texturing (texture mapping)
    ↓
Résultat final validé

Chaque couche constitue une frontière de séquence : en cas d'interruption, la reprise se fait à la dernière frontière validée.

Concepts clés

Principes fondamentaux

1. Atomicité : chaque couche produit un résultat entièrement validé ou entièrement rejeté.
2. Immutabilité : une couche ne modifie jamais les résultats des couches précédentes.
3. Idempotence : relancer une couche avec les mêmes entrées produit le même résultat.
4. Bornage : chaque couche a un budget mémoire et temporel maximum.

Couche 0 — Initial Reconstruction

Aspect	Description
Entrée	Tracks, caméras intrinsèques, co-visibilité
Traitement	Triangulation SVD, initialisation P3P, sélection du paire initial
Sortie	Nuage de points sparse, poses de caméras initiales
Budget	O(N²) dans le pire cas, typiquement O(N·K) où K = nombre moyen de tracks

Étapes :

1. Sélection du paire initial (meilleure baseline angulaire + co-visibilité)
2. Triangulation des tracks du paire initial
3. Rétro-projection progressive des caméras adjacentes (grow)
4. Filtrage des points rejetés (erreur de reprojection > seuil)

Couche 1 — Bundle Adjustment

Aspect	Description
Entrée	Nuage sparse, poses caméras, tracks
Traitement	Optimisation non-linéaire (LM ou Ceres-like), minimisation de l'erreur de reprojection
Sortie	Poses optimisées, points 3D affinés, historique de convergence
Budget	O(N·M) où N = points, M = observations

Variantes :

• Local BA : optimisation d'un sous-ensemble de caméras voisines
• Global BA : optimisation simultanée de toutes les caméras et points
• Incremental BA : ajout progressif de caméras avec optimisation partielle

Couche 2 — Dense Reconstruction

Aspect	Description
Entrée	Poses optimisées, images originales
Traitement	Semi-Global Matching (SGM), stereo matching, depth maps
Sortie	Depth maps par image, nuage de points dense
Budget	Très élevé en RAM : images × profondeur de recherche

Approches :

• Multi-View Stereo (MVS) : matching dense entre paires de views
• Patch-Based MVS : regroupement de patches pour robustesse
• Depth Map Fusion : fusion des depth maps en nuage unifié

Couche 3 — Mesh Generation

Aspect	Description
Entrée	Nuage de points dense
Traitement	Poisson reconstruction, Delaunay, ball pivoting
Sortie	Maillage triangulaire orienté
Budget	CPU intensif, mémoire proportionnelle au nombre de points

Couche 4 — Texturing

Aspect	Description
Entrée	Maillage, images originales, poses caméras
Traitement	Projection UV, visibilité caméra par face, blending
Sortie	Maillage texturé, atlas de texture
Budget	GPU intensif pour le rendu, RAM pour les textures

Frontières de séquence

Chaque couche produit un snapshot atomique :

typedef struct {
    uint64_t layer_id;
    uint64_t sequence_id;
    int64_t  timestamp;
    uint32_t status;      // VALIDATED | REJECTED | PARTIAL
    size_t   data_size;
    void*    data;         // Pointeur vers le résultat sérialisé
} LayerSnapshot;

Les snapshots sont persistés sur disque et consultables par le viewer.

Relations avec les autres modules

Module	Relation
Matching & Tracks	Fournissent l'entrée de la couche 0.
Geometric Constraints	Utilisées dans toutes les couches pour filtrer et valider.
Resource Governor	Le gouverneur alloue les budgets pour chaque couche et contrôle la taille des lots.
Task	Chaque couche est une tâche candidate. Les couches sont séquencées par le runtime/Queue.
Hardware Profile	Les couches 2-4 peuvent exploiter le GPU si disponible.
Image Catalog	Les couches 2-4 lisent les images originales pour le dense matching et texturing.
Viewer	Le viewer affiche les snapshots des couches validées.

Contraintes de conception

• Une couche ne démarre que si la couche précédente a produit un snapshot VALIDATED.
• Les snapshots intermédiaires sont persistés permettant la reprise après crash.
• Chaque couche a un budget mémoire maximum imposé par le Resource Governor.
• La couche 1 (BA) est la plus critique : elle doit converger de manière déterministe.
• Les couches 2-4 peuvent être exécutées par lots (tiles) pour limiter la RAM.
• Le pipeline complet doit pouvoir être interrompu à n'importe quelle frontière.

Terminologie

Terme	Définition
Layer	Étape séquentielle et atomique de la reconstruction
Frontière de séquence	Point de reprise garanti entre deux couches
Snapshot	État persisté du résultat d'une couche
Sparse reconstruction	Nuage de points issu du matching (peu de points)
Dense reconstruction	Nuage de points issu du stereo matching (beaucoup de points)
Bundle Adjustment	Optimisation jointe des poses caméras et des points 3D
Reprojection error	Distance entre un point 3D projeté et son observation 2D
Grow	Ajout progressif de caméras à la reconstruction