From 31827a043d0fd1750a0ac90edc531b791c531a56 Mon Sep 17 00:00:00 2001 From: fy59 Date: Thu, 27 Aug 2026 18:02:38 +0200 Subject: [PATCH] docs: refresh architecture and roadmap --- README.md | 28 +-- docs/architecture/project_database.md | 18 +- docs/roadmap/roadmap.md | 284 ++++++++++++++++---------- 3 files changed, 203 insertions(+), 127 deletions(-) diff --git a/README.md b/README.md index afab6b6..b93a647 100644 --- a/README.md +++ b/README.md @@ -20,16 +20,16 @@ persistante, enrichissable et versionnable. ## État actuel -### Briques implémentées (IMPLEMENTED) +### Briques validées - **Project** : cycle de vie persistant, identité stable et Project Database ouverte - **Import** : premier task kind de production, exécuté par la file générique en lots bornés et reprenables - **ScanSet / Image Catalog v1** : acquisitions, images logiques, provenance et assets SHA-256 persistants et paginés - **Capture / Asset Provenance v1** : Captures par ScanSet, associations source/dérivé - et sélection explicite d'une image logique — IMPLEMENTED / VALIDATION PENDING + et sélection explicite d'une image logique — PASS / FROZEN - **Découverte et planification de campagne bornées** : racines explicites, - plan metadata-only et exécution par groupes via S3-E — IMPLEMENTED / - VALIDATION PENDING + plan metadata-only et exécution par groupes via S3-E — PASS / FROZEN ; campagne + A6000 réelle validée sur 953 ARW + 953 JPEG MPF - **Feature Store v1/v2** : ORB U8×32, SIFT/RootSIFT F32×128 et lecture typée bornée - **Image View** : vues triées et filtrées pour la TUI - **Task** : moteur de tâches avec pause/reprise, annulation et séquences @@ -60,19 +60,19 @@ persistante, enrichissable et versionnable. - **Resource Snapshot** : capture instantanée des ressources - **Resource Governor** : arbitrage centralisé des budgets et réservations -### Briques en cours de consolidation +### Prochaine tranche -- Intégration scheduler ↔ governor avec séquences adaptatives -- Documentation architecture -- **Visual Index v1** : LSH ORB persistant, incrémental et validé, avec recherche top-K bornée +- **Exécution durable de campagne d'acquisition** : confirmations et progression + persistantes, matérialisation S3-E incrémentale, reprise par `capture_id` retenu + et admission par les Task/Scheduler/Governor existants. Voir la + [roadmap canonique](docs/roadmap/roadmap.md). -### Briques prévues (PLANNED) +### Plus tard / différé -- Graphe de dépendances pour ordonner les futures reprises interdépendantes -- DAG de dépendances -- Pools de workers multiples (CPU/GPU/IO) -- Publication live validée -- Viewer intégré +- publication durable dense/mesh et scratch SSD externe optionnel gouverné ; +- workflow TUI de confirmation/progression et sources mixtes multi-ScanSet ; +- vidéo/keyframes, coverage assistance, viewer et exports ; +- DAG général, pools multiples et parallélisme inter-tâches restent différés. ## Architecture diff --git a/docs/architecture/project_database.md b/docs/architecture/project_database.md index 4fe9712..8f03e00 100644 --- a/docs/architecture/project_database.md +++ b/docs/architecture/project_database.md @@ -2,7 +2,7 @@ ## Capture / Asset Provenance v1 — Project DB v19 -**IMPLEMENTED / VALIDATION PENDING.** La migration transactionnelle v18→v19 +**PASS / FROZEN.** La migration transactionnelle v18→v19 ajoute seulement une fondation de catalogue : `captures`, `capture_images`, `capture_assets`, `capture_selections` et `asset_derivations`. Un `Capture` appartient à un seul ScanSet ; il n'est ni un `image_id` ni une nouvelle identité @@ -19,7 +19,7 @@ automatique. ### S3-E — Orchestration d'ingestion multi-source v1 -**IMPLEMENTED / VALIDATION PENDING.** S3-E reçoit un ScanSet explicite et au +**PASS / FROZEN.** S3-E reçoit un ScanSet explicite et au plus 64 chemins source explicitement fournis par l'appelant ; il ne parcourt jamais un répertoire. Chaque fichier est d'abord publié comme asset immuable géré, puis son évidence S3-D est extraite depuis ces octets publiés. Le @@ -58,7 +58,7 @@ interprété ; les IDs et la sémantique v18 restent inchangés. ### Couche finale bornée de découverte et de planification de campagne -**IMPLEMENTED / VALIDATION PENDING.** Cette couche reçoit de 1 à 64 racines +**PASS / FROZEN.** Cette couche reçoit de 1 à 64 racines absolues, lexicalement normalisées et explicitement fournies par l'appelant. Elle ne parcourt pas récursivement : chaque racine et chacune de ses entrées immédiates régulières est inspectée sans suivre de lien symbolique. Seuls les @@ -116,7 +116,7 @@ sont applicables. ### S3-D — Acquisition Pairing Evidence v1 -**IMPLEMENTED / VALIDATION PENDING — non FROZEN.** S3-D extrait, depuis des +**PASS / FROZEN.** S3-D extrait, depuis des assets source immuables, un ensemble fixe et borné de métadonnées d'évidence d'appariement. Pour les RAW, l'extraction est metadata-only avec LibRaw ; pour les JPEG, elle utilise libexif. Cette évidence n'est pas une identité @@ -946,7 +946,7 @@ ouvert. ## Statut -**IMPLEMENTED / VALIDATION PENDING** — SQLite système, schéma v19 et migrations séquentielles +**PASS / FROZEN** — SQLite système, schéma v19 et migrations séquentielles v1→v2→v3→v4→v5→v6→v7→v8→v9→v10→v11→v12→v13→v14→v15→v16→v17→v18→v19, identité projet, transactions tâche+checkpoint, pagination de reprise et artefacts génériques. @@ -967,11 +967,11 @@ bornée à 256. Les identités sont des `INTEGER PRIMARY KEY AUTOINCREMENT` SQLi allouées sous transaction ; aucun `SELECT MAX()+1` n'est utilisé en fonctionnement normal et une identité validée n'est jamais réutilisée. -**IMPLEMENTED / VALIDATION PENDING** — Capture / Asset Provenance v1 : +**PASS / FROZEN** — Capture / Asset Provenance v1 : Capture borné par ScanSet, associations explicites asset/image, sélection -courante optionnelle et dérivation asset à parent unique. RAW, vidéo, -appariement automatique et toute exécution de dérivation restent hors de cette -fondation. +courante optionnelle et dérivation asset à parent unique. S3-B1/S3-D/S3-E et la +campagne bornée réutilisent cette fondation sans redéfinir ses identités ; la +vidéo reste hors de S3. La migration v3→v4 ne lit pas `manifest.tsv`. Elle crée le ScanSet legacy et positionne `metadata.legacy_image_catalog_pending=1` dès qu'une ancienne tâche diff --git a/docs/roadmap/roadmap.md b/docs/roadmap/roadmap.md index b73af8a..043ede7 100644 --- a/docs/roadmap/roadmap.md +++ b/docs/roadmap/roadmap.md @@ -1,125 +1,201 @@ -# Roadmap Lardon3D +# Roadmap canonique Lardon3D -## Precision features +Cette feuille de route décrit l'ordre de dépendance actuel. Les contrats détaillés +restent dans `docs/architecture/`; ce document indique ce qui est fermé, ce qui +vient immédiatement ensuite et ce qui demeure volontairement différé. -- **IMPLEMENTED v1A** : ORB coarse stable, SIFT/RootSIFT OpenCV 5, Feature File - v2 F32×128, grille/coverage, tâches récupérables et consolidation intra-image. -- **IMPLEMENTED** : Candidate Pair Generator, matching précis et vérification géométrique. -- **PLANNED / BLOCKED** : ALIKED, en attente de provenance modèle et d'un export - ONNX reproductible validé contre un oracle upstream. +## Situation actuelle -## Direction générale +Lardon3D possède une chaîne scientifique persistante allant des acquisitions +explicites aux frontières Sparse SfM et MVS validées. Les travaux volumineux +doivent rester incrémentaux, bornés, reprenables, durables et admis par l'unique +Resource Governor : aucune étape ne peut supposer qu'une campagne entière tient +en RAM ou termine dans une seule vie de processus. -Lardon3D suit une feuille de route ordonnée qui privilégie la stabilité et la consolidation avant l'ajout de fonctionnalités complexes. +### Fondations PASS / FROZEN -## Étapes terminées (DONE) +- Gates A–G Sparse SfM, dont F0, orchestration Task/Project DB et politique + Governor : [Sparse SfM](../architecture/sparse_sfm.md) et + [frontière ressource](../architecture/resource_boundary.md). +- Track Model / Track Builder v1 : [Track Model](../architecture/tracks.md) et + [Track Builder](../architecture/track_builder.md). +- Phase H v1 d'enrichissement incrémental multi-snapshot : + [Project DB](../architecture/project_database.md). +- MVS-M1, frontière OpenMVS v2.4.0, identité dense et export COLMAP/PLY borné : + [pipeline de reconstruction](../architecture/reconstruction_pipeline.md). +- Task Runtime, checkpoints atomiques, Queue, Scheduler et Resource Governor : + [Task](../architecture/task_system.md), [Queue](../architecture/task_queue.md) + et [Governor](../architecture/resource_governor.md). +- Project DB v19 et S1–S3 Capture / Acquisition Ingestion : provenance + Capture/Asset, import capture-safe, publication dérivée, développement RAW, + siblings multi-source, évidence S3-D, orchestration S3-E et campagne bornée : + [Project DB et ingestion](../architecture/project_database.md). -### Phase 1 : Fondations -- ✅ TUI modulaire avec ncursesw -- ✅ Gestion persistante des projets -- ✅ Import d'images migré vers le scheduler générique, borné et reconstructible -- ✅ Catalogue d'images et vues -- ✅ Moteur de tâches avec pause/reprise, annulation, checkpoints -- ✅ File FIFO avec sélection adaptative et backpressure -- ✅ Profil matériel et snapshots de ressources -- ✅ Resource Governor avec réservations opaques -- ✅ Intégration scheduler ↔ governor -- ✅ Sélection de la première tâche admissible +### S3 Capture / Acquisition Ingestion — PASS / FROZEN -## Travaux d'infrastructure en cours (CURRENT FOUNDATION) +```text +S3-A Derived Image Publication PASS / FROZEN +S3-B1 Deterministic RAW Development PASS / FROZEN +S3-C Multi-Source Capture Association PASS / FROZEN +S3-D Acquisition Pairing Evidence v1 PASS / FROZEN +S3-E Multi-Source Ingestion v1 PASS / FROZEN + Bounded Campaign Ingestion PASS / FROZEN +Project DB v19 +``` -### Phase 2 : Consolidation -- 🔄 Documentation architecturale -- 🔄 Tests et validation -- 🔄 Optimisations mémoire +```text +entrées d'acquisition explicites +→ publication SOURCE immuable +→ provenance Capture/Asset +→ métadonnées RAW/JPEG et évidence d'acquisition +→ propositions de campagne déterministes +→ regroupement fort ou explicitement confirmé +→ un Capture par observation physique résolue et siblings SOURCE +→ développement RAW déterministe si demandé +→ image_id scientifique immuable +→ pipeline aval existant +``` -## Prochaines étapes décidées (NEXT) +Les identités restent distinctes : `Capture != fichier`, `Capture != asset`, +`Capture != image_id`, `Capture != SHA-256` et `Capture != basename`. -### Phase 3 : Persistance -- ✅ Fondation versionnée des checkpoints de tâches -- ✅ Project Database v7 (tâches, catalogue, Feature Store, Visual Index et precision features) -- ✅ Branchement Project Database au cycle de vie projet et inventaire de reprise -- ✅ Registry durable des types métier de tâches -- ✅ Premier type métier reconstructible (`import.images`) -- ✅ Resoumission automatique contrôlée et bornée des tâches récupérables -- ✅ ScanSet v1 et Image Catalog persistant v1 +### Validation réelle Sony A6000 -### Phase 4 : Pipeline avancé -- ✅ Feature Store v1/v2, ORB, SIFT/RootSIFT et consolidation intra-image -- ✅ Visual Index v1 segmenté et persistant -- ✅ Candidate Pair Generator -- ✅ Matching et vérification géométrique -- ✅ Track Model / Track Builder v1 -- ✅ Sparse SfM : primitives géométriques Gate C et noyau incrémental Gate D - implémentés -- ✅ Sparse SfM Gate E : Bundle Adjustment final par composante PASS / FROZEN -- ✅ Sparse SfM Gate F : orchestration durable et publication atomique PASS / FROZEN -- ✅ Sparse SfM Gate G : politique et cœur **PASS / FROZEN** +Campagne `Photogrammetrie/2026-08-26_Baie_Moteur_A6000` : -### Phase 5 : Reconstruction -- ✅ Orchestration de reconstruction incrémentale H v1 — **PASS / FROZEN** -- 🔄 Capture / Asset Provenance v1 — **IMPLEMENTED / VALIDATION PENDING** : - Project DB v19 ajoute les Captures par ScanSet, les associations source/dérivé - et la sélection explicite d'une image logique, sans changer le pipeline - scientifique. L'ingestion RAW et vidéo reste PLANNED. -- ✅ MVS-M1 — **PASS / FROZEN** : identité dense `L3DMDID2` - v2 (220 octets) liant reconstruction de base, jeu d'images source, - `calibration_scope_identity` historique, binding numérique exact `L3DMCAL1` v1, - backend et paramètres ; les octets source restent liés séparément ; frontière - OpenMVS v2.4.0 externe - `InterfaceCOLMAP`/`DensifyPointCloud` ; export COLMAP déterministe avec - undistortion OpenCV, observations transformées et tracks réels ; texte COLMAP - exporté en flux et tracks déterministes indexés sans rescan quadratique des - observations. Le binding de calibration trie les `image_id`, encode des champs - little-endian explicites à largeur fixe, rejette NaN/Inf et canonise `-0`. Chaque - invocation crée sous le staging appelant un espace de travail privé neuf, sans - réemployer scène, profondeur, cache ou sortie antérieure. Le PLY par défaut - OpenMVS v2.4.0, binaire little-endian, est validé avec listes - `view_indices`/`view_weights` bornées, nombres indépendants de la locale, - en-tête <= 1 MiB en octets bruts (CRLF = deux octets), lignes <= 64 KiB, - LF/CRLF acceptés et CR seul malformé rejeté ; le PLY fusionné est requis en mode - de fusion 0. Une coordonnée source undistordue - non finie est `INVALID_SOURCE_IMAGE`, une pose snapshot invalide reste - `INVALID_SNAPSHOT`. Capacité CPU-only conditionnelle et `--max-threads` - supporté ; bornes locales. Le SHA-256 source est complet et borné à 1 GiB par - fichier régulier, sans budget agrégé du jeu de sources ; le hashage des deux - binaires backend relève d'un budget partagé distinct. Sans nouveau sous-système. - Restent différés : publication Project DB/durable, Task Runtime, - Queue/Governor, `ResourceEstimate`, annulation, mesh, texturing, viewer, - scratch/SSD et infrastructure backend généralisée. -- 📋 Mesh -- 📋 Contraintes externes -- 📋 Consolidation +- 953 ARW et 953 JPEG, soit 1906 sources ; +- métadonnées : ARW 953/953 OK, JPEG 953/953 OK ; +- JPEG Sony reconnus comme conteneurs MPF valides : APP2 `MPF\0`, images JPEG + secondaires validées, remplissage inter-image/final nul, maximum privé huit ; +- `STRONG_GROUPS=0`, `CANDIDATE_PAIRS=953`, ambiguïtés 0, contradictions 0 ; +- plan identique après inversion de l'ordre des racines. -## Étapes futures (LATER) +Le stem commun ne prouve jamais une acquisition. Les 953 propositions doivent +être confirmées et deviennent `CALLER_EXPLICIT`, jamais `STRONG`. La campagne +complète n'a pas encore été matérialisée. -### Phase 6 : Production -- ⏳ Viewer intégré -- ⏳ Publication live validée -- ⏳ Export multi-formats -- ⏳ Optimisations performances +### Limite de reprise DB v19 -### Phase 7 : Avancé -- ⏳ Priorités entre tâches -- ⏳ Pools de workers multiples (CPU/GPU/IO) -- ⏳ DAG de dépendances complet -- ⏳ Parallélisme inter-tâches +S3-E reprend une matérialisation connue par `resume_capture_id`. Une campagne +peut reconstruire son plan et conserver côté appelant le `capture_id` de chaque +groupe. Si le processus meurt après création du Capture mais avant rétention +durable de cet ID, DB v19 ne peut le redécouvrir sans inventer une identité +interdite. Il n'existe donc pas de garantie whole-campaign exactly-once. Une +future identité durable de requête/campagne pourra fermer cette fenêtre ; elle +ne sera jamais déduite d'un chemin, SHA, basename, timestamp, métadonnée ou +`image_id`. -## Sujets exploratoires (RESEARCH) +## NEXT — exécution durable de campagne d'acquisition -- 🔬 Intégration avec des sources de données externes -- 🔬 Support de formats d'entrée variés -- 🔬 Optimisation pour machines à très faible mémoire -- 🔬 Distribution de calcul +La prochaine tranche architecturale unique est l'exécution opérationnelle du +plan S3 gelé en réutilisant Task, Scheduler et Governor existants : -## Principes directeurs +1. identité durable de requête et payload Task borné ; +2. persistance/rechargement des confirmations, du curseur et des `capture_id` ; +3. matérialisation incrémentale d'un groupe S3-E par unité sûre ; +4. checkpoint après rétention durable, pause/reprise/annulation aux frontières ; +5. admission et budgets par l'unique Resource Governor ; +6. progression et échecs sans runtime, queue ou persistence parallèle. -1. **Stabilité avant performance** : ne jamais saturer le système hôte -2. **Séquençage avant parallélisme** : lots adaptatifs et workers uniques d'abord -3. **Réservation atomique** : aucune exécution sans contrat valide -4. **Persistance progressive** : chaque résultat doit pouvoir être repris -5. **Documentation vivante** : la documentation suit le code, pas l'inverse +Cette tranche décidera explicitement si une évolution additive après DB v19 est +nécessaire. Elle ne peut ni changer les identités S3 ni fusionner des Captures. -## Vérification +## NEXT REAL-DATA MILESTONE — A6000 ENGINE BAY END-TO-END -Cette roadmap est vérifiée contre l'état réel du code. Les fonctionnalités déjà implémentées ne sont pas marquées comme NEXT ou LATER. +1. confirmer explicitement les 953 propositions ARW/JPEG ; +2. matérialiser progressivement environ 953 Captures ; +3. produire les représentations scientifiques par lots gouvernés ; +4. exécuter features, candidats, matching, vérification, tracks et Sparse SfM ; +5. évaluer la qualité de la reconstruction sparse ; +6. exécuter MVS/dense avec budgets et scratch contrôlés ; +7. publier durablement nuage dense et mesh ; +8. comparer le résultat aux tentatives photogrammétriques antérieures. + +Ce milestone est une intégration réelle, pas une nouvelle série de micro-gates +S3. Les antécédents d'OOM/SIGSEGV OpenMVS, pression swap, grands intermédiaires +et temps longs imposent reprise, progression et contrôle de ressources. + +## NEAR TERM + +### Scratch SSD externe et swap optionnel + +Matériel envisagé : SSD externe d'environ 500 Go dans un boîtier USB-C 10 Gb/s. +La capacité planifiée est : détecter un disque externe adapté, le présenter dans +la configuration TUI/projet et demander si ce projet doit l'utiliser. + +Usages possibles : workspace/scratch, intermédiaires dense/mesh/texturing et, +sur activation explicite, swap de sécurité. Le contrat devra être possédé par +l'exécution Task, le Resource Governor et la politique temporaire du projet ; +il ne doit pas devenir un gestionnaire de stockage ad hoc. + +- le scratch déplace les gros intermédiaires hors de la RAM et du disque système ; +- il peut permettre des jobs bornés plus grands ; +- SSD/swap ne sont jamais de la RAM ni une extension du budget scientifique ; +- latence et débit USB restent distincts de la mémoire ; +- l'utilisation reste optionnelle et Governor-controlled ; +- retrait, déconnexion, ownership, nettoyage et publication atomique exigent + des sémantiques explicites ; +- aucun montage, formatage, `swapon` ou nettoyage destructif automatique n'est + actuellement implémenté ou autorisé. + +### Publication durable dense / mesh + +MVS-M1 reste la frontière scientifique gelée. Les prochaines étapes portent sur +exécution, reprise, budgets mémoire/stockage et publication atomique : + +```text +dense → mesh → refinement → texturing → consolidation → export +``` + +Le scratch devient particulièrement pertinent à cette frontière. + +### Workflow TUI-first + +La TUI exposera état projet, découverte de campagne, confirmation des candidats, +progression, pause/reprise/annulation disponible, Governor, choix du scratch et +étapes aval. ncurses reste au thread principal. Aucun projet GUI général n'est +introduit. + +### Sources mixtes et multi-ScanSet + +Sony A6000, Samsung S21 et futures sources peuvent varier en device, objectif, +résolution et format. Elles réutilisent le même modèle Capture/Asset/Image, sans +fork par caméra. Plusieurs ScanSets et représentations sélectionnées alimentent +l'enrichissement Phase H existant vers un modèle consolidé ; Phase H n'est pas +redéfini ici. + +## LATER + +- **Vidéo/keyframes** : asset vidéo, timeline, extraction déterministe, + provenance frame↔vidéo, espacement, blur/qualité, redondance et couverture. + Ces politiques restent séparées des contrats photo gelés. +- **Maintenance projet** : vérification de provenance, assets orphelins, + scrub/réconciliation et réclamation sûre du scratch. Aucun asset immuable + partagé n'est supprimé silencieusement. +- **Coverage/capture assistance** : overlap, zones faibles, photos ou ScanSets + supplémentaires et comparaison de points de vue ; jamais une identité. +- **Viewer** : frontière passive et optionnelle pour sparse, dense, mesh, poses, + provenance, couverture et overlays qualité. Le projet reste TUI-first. +- **Exports/publication live** : snapshots validés et consommation sans accès + aux buffers workers mutables. + +## DEFERRED / OPTIONAL + +- pools multiples CPU/GPU/IO, parallélisme inter-tâches et multi-GPU ; +- DAG général de dépendances et priorités complexes ; +- infrastructure backend générique et distribution de calcul ; +- ALIKED tant que provenance modèle, export ONNX et oracle upstream ne sont pas + reproductibles. + +Ces idées ne doivent pas devancer l'exécution durable de campagne ni créer un +second runtime, Governor ou système de persistance. + +## Principes de séquencement + +1. stabilité et intégrité scientifique avant débit ; +2. résultats atomiques et durables avant parallélisme ; +3. lots bornés et reprise avant taille de campagne ; +4. un Task Runtime, un Scheduler et un Resource Governor ; +5. scratch optionnel sans élargissement implicite des budgets RAM ; +6. TUI de contrôle avant visualisation riche ; +7. documentation canonique alignée sur le code validé.