lardon3d/docs/architecture/overview.md

Vue d'ensemble de l'architecture Lardon3D

Finalité et flux global

Lardon3D est un moteur de reconstruction géométrique persistante et incrémentale, piloté par une TUI ncursesw. Le terminal reste le centre de contrôle : il gère les projets, lance les opérations, présente leur progression et permet leur annulation. Le viewer sera un composant graphique séparé mais intégré à l'interface pour un usage confortable sur un seul écran.

TUI / Projet
    ↓
Task
    ↓
Estimate
    ↓
Task Queue
    ↓
Resource Governor / Reservation
    ↓
callback worker admis
    ↓
Résultat atomique
    ↓
Viewer live

Composants actuels

Project

Gestion persistante des projets : création, ouverture, fermeture, structure de répertoires. Chaque projet regroupe configuration, images originales, manifeste, résultats, exports et journaux.

Statut : IMPLEMENTED

Import

Import asynchrone et annulable d'images dans un projet. Copie individuelle des fichiers admissibles et maintenance d'un manifeste cohérent.

Statut : IMPLEMENTED

Import Task

Premier type métier persistant. Il s'exécute par lots bornés dans le runtime et la Queue génériques, cible explicitement un ScanSet et peut être reconstruit puis repris.

Statut : IMPLEMENTED

ScanSet et Image Catalog

Catalogue SQLite persistant séparant acquisition, image logique et asset physique SHA-256. Les parcours persistants sont paginés ; l'ancien catalogue mémoire depuis manifest.tsv reste une façade legacy pour la TUI.

Statut : IMPLEMENTED

Profils optiques et calibrations

Project DB v23 ajoute un overlay générique distinct pour profils de boîtiers, objectifs électroniques ou manuels, configurations optiques, affectations aux campagnes/Captures et calibrations explicitement compatibles. La migration n'infère ni ne backfill aucune donnée S21/A6000 ; ces appareils restent des preuves de validation, pas des identités produit.

Statut : IMPLEMENTED — OVERLAY ADDITIF v23

Image View

Vues triées et filtrées du catalogue pour la TUI. Ne modifie pas le catalogue, le manifeste ou les images.

Statut : IMPLEMENTED

TUI observatoire / centre de contrôle

Le thread principal possède ncurses, l'entrée et le rendu. Un modèle pur reçoit des copies bornées de l'unique Queue et du Governor, coalescées autour d'une seconde, et présente progression durable, ETA honnête, pipeline, ressources, profils optiques et SSD. Les dimensions validées sont full ≥100×30, compact de référence 72×20, minimum 60×15, puis le fallback Terminal trop petit. Les couleurs s'accompagnent toujours de libellés textuels et F10 SSD reste visible au minimum supporté.

Ouvrir, fermer ou changer de projet détruit/joint l'unique Queue avant de fermer Project DB, puis recrée une Queue vide et rebranche l'observation. Les ABI historiques Task/Resource/AppState/layout restent inchangées ; les vues riches utilisent des structures et fonctions additives décrites dans Runtime.

Statut : CURRENT / VALIDATED OPERATIONAL

Feature Store

Extraction ORB réelle par tâche persistante, Feature Sets logiques et assets binaires content-addressed lisibles par plages bornées.

Statut : IMPLEMENTED

Visual Index

Index de retrieval ORB LSH persistant en segments immuables. Il indexe les Feature Sets par lots bornés et retourne des candidats inter-ScanSets sans matching géométrique.

Statut : IMPLEMENTED

Task

Moteur de tâches avec états, progression, pause/reprise coopérative, annulation, checkpoints et estimations de ressources.

Statut : IMPLEMENTED

Task Queue

File FIFO avec worker unique, sélection de la première tâche admissible, backpressure et bornage du nombre de tâches en attente.

Statut : IMPLEMENTED

Hardware Profile

Détection des capacités matérielles statiques : cœurs CPU, RAM, GPU/VRAM.

Statut : IMPLEMENTED

Resource Snapshot

Capture instantanée des ressources disponibles : RAM libre, charge CPU, VRAM disponible.

Statut : IMPLEMENTED

Resource Governor

Arbitrage centralisé des budgets (RAM, GPU, CPU, IO), calcul de lots adaptatifs, réservations opaques et historique borné de métriques.

Statut : IMPLEMENTED

Contrôleur SSD externe optionnel

Frontière physique UDisks2 pour la paire de labels LARDON_SWAP et LARDON_SCRATCH, avec identité Drive+UUID stable, état borné, leases scratch et drain sûr. Il ne formate, ne répare ni ne force jamais l'hôte et ne remplace pas le Resource Governor. La TUI exécute ses actions dans un seul thread joinable et le Governor enregistre l'état physique puis orchestre seul les leases scratch de production. Les seize Task kinds courants n'en consomment aucun ; capacité visible ne signifie donc pas usage.

Statut : CURRENT / VALIDATED OPERATIONAL

Candidate Pair

Sous-système de génération et persistance de paires d'images candidates pour le matching géométrique. Répond uniquement à « quelles paires valent la peine d'être explorées ? » sans validation géométrique.

Statut : IMPLEMENTED

Match Result

Persistance d'un calcul descriptor-level réussi entre deux Feature Sets liés à une Candidate Pair. Identité déterministe par (candidate_pair_id, feature_set_id_a, feature_set_id_b, matcher_kind, matcher_version, parameter_fingerprint). Validation d'appartenance Feature Set → image. Les correspondances vivent dans le Match Store v1 content-addressed; les échecs restent dans le Task Runtime.

Statut : IMPLEMENTED

Matcher

Matching de descripteurs entre deux Feature Sets via BFMatcher OpenCV (ORB Hamming, SIFT/RootSIFT L2) avec Lowe ratio test. Produit un Match File content-addressed et un Match Result dans Project DB. Déterministe, idempotent, borné.

Statut : IMPLEMENTED

Sparse SfM

Les primitives géométriques calibrées Gate C, le noyau incrémental synchrone Gate D et le Bundle Adjustment final par composante Gate E sont implémentés. Gate E traite en mémoire une copie du résultat Gate D immutable, sur CPU avec un thread Ceres, et publie atomiquement chaque candidate acceptée. Il n'intègre ni persistance, ni Task Runtime, ni Resource Governor.

Statut : GATES C/D/E — PASS / FROZEN

Gate F relie ces noyaux au Task Runtime durable, à la Queue/Governor/Reservation et à la publication Project DB v17 atomique et idempotente.

Statut : GATE F — PASS / FROZEN. Gate G est PASS / FROZEN.

La phase de pipeline H incremental_reconstruction.run v1 enrichit un snapshot publié et produit un nouveau snapshot complet avec provenance prédécesseur dans Project DB v18. Elle reste scientifiquement distincte de Gate F et ne modifie ni F0 ni les contrats Gate D/E.

Statut : PHASE H V1 — PASS / FROZEN.

Résultats et publication live

Les traitements fonctionnent par séquences adaptatives : lire un lot borné, calculer, écrire un résultat atomique, libérer la mémoire, puis traiter le lot suivant. La stabilité du système hôte et la réactivité de la TUI ont priorité sur le débit maximal.

Le viewer consomme des snapshots de résultats validés et publiés atomiquement. Il ne lit jamais un fichier intermédiaire et ne partage pas directement les buffers de travail d'un worker. Une interruption doit laisser le dernier snapshot validé exploitable et permettre la reprise à une frontière de séquence connue.

Invariants fondamentaux

• Aucun callback de tâche n'est lancé sans réservation active validée.
• La Queue ne décide jamais des ressources.
• Le Resource Governor est l'unique propriétaire des budgets.
• Les réservations sont libérées exactement une fois.
• ncurses appartient exclusivement au thread principal.
• Les estimations de ressources sont immuables.
• Les buffers et files sont strictement bornés.

Limites actuelles

• File à worker unique avec FIFO stable et bypass des seuls WAIT ressources.
• Absence de DAG de dépendances.
• Absence de priorités.
• Absence de pools de workers multiples (CPU/GPU/IO).
• La TUI legacy ne sélectionne pas encore explicitement ses ScanSets.
• La réconciliation globale des assets/checkpoints orphelins n'est pas implémentée.
• La compaction des segments Visual Index n'est pas implémentée.
• Viewer et publication live non implémentés.