From c27be7776b2ee24747b0841526e763787dbbbb80 Mon Sep 17 00:00:00 2001 From: fy59 Date: Wed, 2 Sep 2026 21:37:04 +0200 Subject: [PATCH] docs: align architecture overview with current pipeline --- docs/architecture/overview.md | 576 ++++++++++++++++++++++++---------- 1 file changed, 406 insertions(+), 170 deletions(-) diff --git a/docs/architecture/overview.md b/docs/architecture/overview.md index d95b6ba..e05fafb 100644 --- a/docs/architecture/overview.md +++ b/docs/architecture/overview.md @@ -1,223 +1,459 @@ -# Vue d'ensemble de l'architecture Lardon3D +# Lardon3D Architecture Overview -## Finalité et flux global +## Purpose -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. +Lardon3D is a persistent, incremental, resource-aware photogrammetry engine for Linux. + +The TUI is the operational control center for projects, acquisition, Tasks, durable progress, +resource state, optical configuration and optional external-storage control. Rich visualization and +live acquisition remain separate product areas and must consume validated snapshots rather than +mutable worker buffers. + +## Current authority ```text -TUI / Projet - ↓ -Task - ↓ -Estimate - ↓ -Task Queue - ↓ -Resource Governor / Reservation - ↓ -callback worker admis - ↓ -Résultat atomique - ↓ -Viewer live +CURRENT_PROJECT_DB_SCHEMA=v25 +CURRENT_PRODUCTION_TASK_KINDS=16 +RESOURCE_UTILIZATION_POLICY=MAXIMUM_SAFE_USEFUL_THROUGHPUT +SERIALISM_REQUIRES_PROOF=CANONICAL +REAL_S21_TRACKS=PASS/FROZEN +REAL_A6000_PRE_SFM=PASS/FROZEN ``` -## Composants actuels +The current Project DB head is additive: + +```text +v22 Selected scientific execution foundation +v23 Generic optical-context overlay +v24 raw.develop.batch/1 persistence +v25 features.extract.batch/1 persistence +``` + +Earlier schema versions remain valid historical contracts where their documentation says so. Current +documentation must not present an older version as the active head merely because that version owns a +specific historical scientific or persistence boundary. + +## Global execution model + +```text +TUI / Project + | + v +Task + | + v +immutable resource estimate / capability + | + v +bounded Task Queue +(one active callback) + | + v +Resource Governor +(admission + reservation) + | + v +admitted owner callback + | + +--> bounded internal participants when justified + | + v +deterministic owner publication + | + v +durable checkpoint / restart boundary + | + v +validated snapshot consumers +``` + +The Queue owns bounded dispatch and backpressure. The Governor owns production resource admission. +The active Task owns its execution state and any bounded internal participants. Scientific stores own +their own identities and artifact validation. + +No layer may silently absorb another layer's authority. + +## Canonical resource objective + +Lardon3D first preserves the interactive host reserve required for normal workstation use. Safe and +useful capacity beyond that reserve belongs to the active workload. + +The objective is: + +```text +MAXIMUM_SAFE_USEFUL_THROUGHPUT +``` + +This does not mean maximizing utilization percentages for appearance. It means using the largest +currently safe and useful CPU, RAM, I/O and validated accelerator capability while preserving +scientific identity, deterministic publication, host responsiveness and pressure limits. + +The companion rule is: + +```text +SERIALISM_REQUIRES_PROOF +``` + +Per-item atomicity does not imply cross-item serialization. Ordered or owner-only durable publication +does not imply serial preparation. Independent work should expose bounded concurrency when exact +science and persistence semantics can be preserved. + +A CPU1 or batch1 path may remain when serialism, a measured scaling knee, memory, I/O, GPU execution, +exclusive state or another concrete constraint justifies it. Historical conservative descriptors are +not portable performance ceilings. + +On the current validation host, the normal observed outcome is approximately: + +```text +16 logical CPUs total +4 logical CPUs reserved for interactive host use +12 logical CPUs available to the compute pool +~3 GiB MemAvailable hard reserve +Radeon 780M UMA available to validated and useful GPU backends +``` + +These values are reference-host observations, not product constants. + +## Current components ### 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 +Persistent project lifecycle, stable identity, directory layout and Project DB ownership. -### Import -Import asynchrone et annulable d'images dans un projet. Copie individuelle -des fichiers admissibles et maintenance d'un manifeste cohérent. +**Status:** IMPLEMENTED -**Statut :** IMPLEMENTED +### Project Database -### 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. +SQLite owns durable logical identities, relations, typed Task payloads, scientific metadata and +references to external immutable artifacts. -**Statut :** IMPLEMENTED +The current schema head is v25. The scientific meaning of historical rows remains owned by the +versioned contracts that created them. -### 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. +**Status:** CURRENT / v25 -**Statut :** IMPLEMENTED +### Import and ScanSets -### Profils optiques et calibrations +Import materializes managed immutable assets and logical images under explicit ScanSets. Provenance +from external source paths remains distinct from managed asset identity. -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. +**Status:** IMPLEMENTED -**Statut :** IMPLEMENTED — OVERLAY ADDITIF v23 +### Capture / Asset Provenance -### Image View -Vues triées et filtrées du catalogue pour la TUI. Ne modifie pas le -catalogue, le manifeste ou les images. +Capture identity remains distinct from file, Asset, `image_id`, SHA-256, path, Task ID and campaign +group ID. RAW and JPEG siblings may belong to one physical Capture without becoming one file or one +scientific image identity. -**Statut :** IMPLEMENTED +**Status:** PASS / FROZEN -### TUI observatoire / centre de contrôle +### Bounded acquisition discovery and campaign execution -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é. +Discovery and planning are bounded and deterministic. Automatic grouping requires the documented +strong evidence; otherwise explicit caller confirmation remains `CALLER_EXPLICIT`. -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](runtime.md). +Durable campaign execution uses the existing Task, Queue, Governor and Project DB recovery model. -**Statut :** CURRENT / VALIDATED OPERATIONAL +**Status:** PASS / FROZEN + +### Photo Quality Triage + +Quality analysis is an operational selection layer, not a scientific identity. It produces explicit +GOOD / SUSPECT / REJECT recommendations and keeps human overrides distinct. + +**Status:** PASS / FROZEN + +### Selected scientific execution + +The selected-execution snapshot binds the retained acquisition groups to explicit scientific +representations without inferring identity from paths, filenames or metadata. + +**Status:** PASS / FROZEN + +### Optical profiles and calibration selection + +Project DB v23 provides generic camera-body profiles, lens profiles, optical configurations, +campaign/Capture assignments, calibration profiles and explicit compatible calibration selection. + +Electronic metadata aliases are exact. Manual lenses without EXIF are normal. Missing or ambiguous +identity remains unresolved rather than guessed. + +**Status:** IMPLEMENTED / VALIDATED + +### RAW development + +The historical `raw.develop/1` path remains valid. Project DB v24 adds +`raw.develop.batch/1`, allowing bounded independent RAW preparation with deterministic owner-only +publication in selected-item order. + +Per-Capture publication remains atomic while cross-Capture preparation may be concurrent. + +**Status:** IMPLEMENTED / VALIDATED ### 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 +Feature Store publishes immutable content-addressed Feature Files and bounded typed readers for ORB, +SIFT and RootSIFT data. + +The historical `features.extract/1` task remains valid. Project DB v25 adds +`features.extract.batch/1`, which prepares independent selected images with bounded participants and +publishes Feature Sets deterministically through the owner callback. + +**Status:** IMPLEMENTED / VALIDATED ### 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 +The ORB LSH Visual Index is persistent and segmented. It indexes homogeneous Feature Sets in bounded +updates and retrieves candidate relationships without performing geometric validation. -### 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 +**Status:** IMPLEMENTED ### 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 +Candidate Pair generation answers which image pairs are worth exploring. Scientific pair identity and +canonical ordering remain independent from the amount of execution parallelism used to prepare them. -### 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. +Candidate currently uses a bounded coupled CPU/batch ladder because additional CPU cannot exercise +additional independent pair work while the admitted item window remains one. -**Statut :** IMPLEMENTED +**Status:** 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 +Matcher produces deterministic Match Results from Feature Sets. + +ORB supports the validated Vulkan hot path with exact CPU fallback. SIFT and RootSIFT remain CPU +OpenCV L2 paths. GPU use is selected only when a backend is both validated and useful. + +**Status:** IMPLEMENTED + +### Geometric Verification + +Geometric Verifier v3 performs Fundamental USAC/MAGSAC verification with bounded restartable Task +execution. Scientific solver parallelism remains controlled by its contract while cross-parent +preparation can use bounded Governor-admitted participants. + +**Status:** IMPLEMENTED / VALIDATED + +### Track Model and Track Builder + +Track Model v1 and Track Builder publish immutable Track Sets with deterministic identity and bounded +recovery semantics. + +Retained real-data evidence includes: + +```text +REAL_S21_TRACKS=PASS/FROZEN +REAL_A6000_PRE_SFM=PASS/FROZEN +``` + +**Status:** PASS / FROZEN ### 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 +Calibrated Sparse SfM capability is implemented through Gates C-G: -Gate F relie ces noyaux au Task Runtime durable, à la Queue/Governor/Reservation -et à la publication Project DB v17 atomique et idempotente. +- Gate C: calibrated geometric primitives; +- Gate D: incremental reconstruction core; +- Gate E: final per-component Bundle Adjustment; +- Gate F: durable Task orchestration and atomic Project DB publication; +- Gate G: Governor admission and resource integration. -**Statut :** GATE F — PASS / FROZEN. Gate G est **PASS / FROZEN**. +Phase H v1 adds incremental enrichment from immutable predecessor snapshots without redefining Gate F +scientific identity. -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. +**Status:** C-G PASS / FROZEN; PHASE H V1 PASS / FROZEN -**Statut :** PHASE H V1 — PASS / FROZEN. +Implemented capability must remain distinct from execution on a particular real campaign. The +historical S21 and A6000 Engine Bay campaigns remain `CALIBRATION_UNAVAILABLE` for known-calibration +Sparse SfM. The retained A6000 proof intentionally stopped before Sparse SfM and Dense/MVS. -## Résultats et publication live +### MVS boundary -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. +MVS-M1 provides the validated bounded external OpenMVS boundary and deterministic COLMAP/PLY exchange +contracts. -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. +Durable dense publication, full Dense/MVS orchestration, mesh refinement, texturing and export remain +future work. -## Invariants fondamentaux +**Status:** PASS / FROZEN boundary -- 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. +### Task Runtime -## Limites actuelles +Tasks own lifecycle state, progress, cooperative pause/cancel behavior, sequence boundaries, +checkpoints and typed durable reconstruction. -- 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. +**Status:** IMPLEMENTED + +### Task Queue + +The Queue provides bounded FIFO dispatch with one active callback, stable scanning and resource-WAIT +bypass behavior. It does not own resource policy. + +**Status:** IMPLEMENTED + +### Task Kind Registry + +The production registry currently contains 16 Task kinds. Historical documents may legitimately +record smaller inventories at their checkpoint. + +**Status:** IMPLEMENTED + +### Hardware Profile and Resource Snapshot + +Hardware Profile detects static host capability. Resource Snapshot captures current observable +capacity and pressure signals required for admission. + +Unavailable optional telemetry remains unknown; it must not be fabricated. + +**Status:** IMPLEMENTED + +### Resource Governor + +The Governor is the sole production authority for CPU, RAM, GPU, I/O admission and process-local +scratch leases where explicitly supported. + +Pressure may throttle future admission. When pressure clears, useful resources must be eligible to +ramp back up; throttling is not a permanent lower ceiling. + +UMA GPU allocations are charged exactly once against host RAM. Swap, zram and external scratch never +become admitted RAM. + +**Status:** IMPLEMENTED / VALIDATED + +### Optional external SSD controller + +The UDisks2/GDBus controller owns the reviewed physical lifecycle for the exact +`LARDON_SWAP` / `LARDON_SCRATCH` device contract. It is not a second scheduler or Governor. + +The Governor remains the sole production entry for scratch leases. The current 16 production Task +kinds have zero authoritative scratch consumption; visible storage capacity is not fabricated usage. + +**Status:** CURRENT / VALIDATED OPERATIONAL + +### TUI observatory and control center + +ncurses input and rendering remain on the main thread. Runtime observation is bounded and coalesced. +The TUI exposes project state, Tasks, durable progress, resource state, optical configuration and SSD +control. + +Validated layout boundaries are: + +```text +full layout >= 100x30 +reference compact 72x20 +minimum supported 60x15 +``` + +Below the minimum, only the bounded terminal-too-small fallback is rendered. + +Opening, closing or switching a project is a Queue/DB lifetime boundary: destroy and join the sole +Queue first, including finished callbacks, then close Project DB, recreate one empty Queue and rebind +observers. + +**Status:** CURRENT / VALIDATED OPERATIONAL + +## Publication and restart model + +Long-running processing follows bounded sequence boundaries: + +```text +admit bounded work +-> prepare bounded items +-> join participants +-> publish deterministic atomic results +-> persist typed cursor/state +-> checkpoint generic Task progress +-> release transient buffers +-> sequence break / re-admission +``` + +The exact order varies by Task contract, but durable progress must never claim work that has not +reached its authoritative publication boundary. + +A crash may leave generic Task progress behind an already durable immutable result where the +documented retry contract permits exact reuse. Recovery must converge from durable identity; it must +not guess identity from paths, timestamps, basenames or similar metadata. + +## Viewer and live boundaries + +Viewer, coverage analysis, live localization and capture guidance remain future product areas. + +The architecture requirement is already clear: visual consumers use validated immutable snapshots. +They do not access mutable worker buffers, own scientific identity or become a second execution +runtime. + +Device-specific acquisition transports such as A6000 HDMI/USB or S21/mobile integration belong at the +acquisition adapter boundary. Heavy reconstruction remains PC-side. + +## Core invariants + +- No Task callback executes without a valid active reservation. +- Queue/runtime do not own resource policy. +- The Resource Governor is the sole production resource authority. +- ncurses remains owned by the main thread. +- Scientific and operational identities remain distinct. +- Task estimates and installed sequence contracts remain immutable for their defined lifetime. +- Memory, buffers, queues, files, descriptors, processes, threads and internal participants are bounded. +- Per-item atomicity does not imply cross-item serialization. +- Owner-only publication does not imply serial preparation. +- Validated and useful GPU backends are preferred when eligible and Governor-safe. +- UMA GPU memory is charged exactly once against host RAM. +- Swap, zram and scratch do not enlarge RAM admission. +- Failure and cancellation clean operation-owned transient resources. +- Atomic scientific publication never exposes partial results as complete. +- FROZEN scientific decisions are not reopened by resource-policy evolution. + +## Current limitations and future scope + +The following remain outside the current implemented execution model: + +- general dependency DAG scheduling; +- multiple active Task callbacks / inter-Task worker pools; +- general CPU/GPU/I/O worker-pool architecture; +- multi-GPU scheduling; +- global orphan-artifact reconciliation; +- Visual Index compaction / larger-index evolution; +- authoritative Task scratch consumers; +- durable dense / mesh publication; +- full Dense/MVS orchestration; +- mesh refinement, texturing and final export workflow; +- viewer; +- offline coverage analysis; +- suggested supplementary viewpoints; +- live camera localization; +- live coverage overlay; +- A6000/S21 live acquisition integration; +- capture guidance; +- video ingestion and deterministic keyframe extraction. + +Deferring inter-Task parallelism does not authorize accidental serialization inside the one active +Task. Bounded internal concurrency remains the current mechanism for independent work under +`SERIALISM_REQUIRES_PROOF`. + +## Current summary + +```text +CURRENT_PROJECT_DB_SCHEMA=v25 +CURRENT_PRODUCTION_TASK_KINDS=16 + +RESOURCE_UTILIZATION_POLICY=MAXIMUM_SAFE_USEFUL_THROUGHPUT +SERIALISM_REQUIRES_PROOF=CANONICAL + +RAW_BATCH_PATH=raw.develop.batch/1 +FEATURE_BATCH_PATH=features.extract.batch/1 + +REAL_S21_TRACKS=PASS/FROZEN +REAL_A6000_PRE_SFM=PASS/FROZEN + +SPARSE_SFM_CAPABILITY=C_G_PASS_FROZEN +REAL_A6000_SPARSE_SFM_EXECUTED=NO +REAL_A6000_DENSE_MVS_EXECUTED=NO + +TUI=CURRENT_VALIDATED_OPERATIONAL +VIEWER=FUTURE +LIVE_CAPTURE_GUIDANCE=FUTURE +``` + +Detailed contracts remain owned by the specialized architecture documents. This overview summarizes +current repository state and must not replace those normative documents.