| docs | ||
| include/lardon3d | ||
| prompt | ||
| scan3d | ||
| shaders | ||
| src | ||
| tests | ||
| tools | ||
| .clangd | ||
| .gitignore | ||
| .goosehints | ||
| AGENTS.md | ||
| LICENSE | ||
| meson.build | ||
| meson_options.txt | ||
| prompt.md | ||
| README.md | ||
Lardon3D
Lardon3D is a generic, persistent, incremental, resource-aware photogrammetry engine for Linux, controlled through an ncursesw TUI.
Vision
Lardon3D is designed around the following principles:
- Scientific traceability: results, identities, parameters and provenance are explicit.
- Determinism: equivalent inputs and contracts produce reproducible, auditable outputs.
- Persistent progress: long-running work is checkpointed and restartable.
- Bounded execution: memory, CPU, GPU, I/O and temporary-storage use are explicitly bounded.
- Maximum safe useful throughput: after preserving the interactive host reserve, available resources should be used whenever they provide useful throughput.
- Incremental reconstruction: new observations can extend previous results without silently rewriting validated history.
- Atomic publication: partially produced scientific outputs never masquerade as complete ones.
Lardon3D is not simply a "folder of photos -> 3D object" tool. Its target model is:
progressive observations and constraints
-> persistent geometric reconstruction
-> validated incremental enrichment
-> dense geometry / mesh / texture / export
Current repository state
Current Project Database
The current Project DB schema is v25.
The current head is additive:
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 own documentation says so. No migration silently reinterprets historical scientific identities.
Current production task inventory
The production registry currently contains 16 Task kinds.
All production Tasks pass through the existing Task -> Queue -> Resource Governor execution model. The Queue has one active callback at a time; Tasks may use bounded internal participants when their contract and measured scaling justify it.
Resource policy
The canonical operational objective is:
MAXIMUM SAFE USEFUL THROUGHPUT
SERIALISM_REQUIRES_PROOF
Lardon3D first preserves the interactive host reserve required for the desktop, Firefox, audio and light interactive use. Safe and useful resources beyond that reserve belong to the active workload.
On the current validation host, the normal observed outcome is approximately:
16 logical CPUs total
4 logical CPUs reserved for interactive host use
12 logical CPUs available to the compute pool
~3 GiB MemAvailable preserved as the hard RAM reserve
Radeon 780M UMA available to validated and useful GPU backends
These are reference-host observations, not portable product constants. The Resource Governor derives usable capacity from the current host, affinity, topology, memory and pressure state.
A long-running CPU1 or batch1 path is acceptable only when serialism, a measured scaling knee, memory, I/O, GPU execution or another concrete constraint justifies it. Per-item atomicity does not imply cross-item serialization.
Validated foundations
The following major foundations are implemented and validated at their documented boundaries:
- Project / persistent lifecycle
- Import and ScanSet / Image Catalog
- Capture / Asset Provenance v1 — PASS / FROZEN
- Bounded acquisition discovery and campaign execution — PASS / FROZEN
- Photo Quality Triage / Acquisition Selection — PASS / FROZEN
- Selected Scientific Execution — PASS / FROZEN
- Feature Store v1/v2
- ORB U8x32
- SIFT / RootSIFT F32x128
- bounded typed readers
- Visual Index v1
- Candidate Pair generation
- Matcher v1
- ORB CPU / validated Vulkan hot path
- SIFT / RootSIFT CPU
- Geometric Verification Model
- Geometric Verifier v3
- Track Model / Track Builder v1 — PASS / FROZEN
- Sparse SfM Gates C/D/E/F/G — PASS / FROZEN
- Phase H v1 incremental reconstruction — PASS / FROZEN
- MVS-M1 external OpenMVS boundary — PASS / FROZEN
- Task Runtime / checkpoints / recovery
- Task Queue
- Task Kind Registry
- Resource Governor / Compute Governor v2
- Bounded internal parallelism — PASS / FROZEN
- ORB Vulkan asynchronous execution — PASS / FROZEN
- TUI runtime observatory / control center — CURRENT / VALIDATED OPERATIONAL
- Optional external SSD controller — CURRENT / VALIDATED OPERATIONAL
- Calibration Bootstrap v1 — PASS / FROZEN
- Calibration Science v1 — PASS / FROZEN
- Calibration Tooling v1 — PASS / FROZEN
- Calibration Solver Preflight v1 — PASS
- Calibration Evidence Solver v1 — IMPLEMENTED / VALIDATED
- Calibration Tooling planarity alignment — PASS / FROZEN
- Project DB v24/v25 operational overlays — IMPLEMENTED / VALIDATED
- raw.develop.batch/1 durable selected-execution path
- features.extract.batch/1 durable selected-execution path
Real-data validation
Sony A6000 and Samsung S21 FE campaigns are validation evidence for the generic pipeline. They are not product identities, hardcoded camera profiles, CPU limits or dataset-size limits.
Real S21 Tracks
REAL_S21_TRACKS=PASS/FROZEN
The retained real S21 proof validated the complete pre-SfM chain through Track Builder with the compact Track memory model and deterministic restart semantics.
Real A6000 pre-SfM
REAL_A6000_PRE_SFM=PASS/FROZEN
The retained real A6000 proof uses the selected RAW-derived deterministic representation and completed the pipeline through Geometric Verification and Tracks without replaying already acquired upstream work.
Final retained counts:
Selected images 689
Feature Sets 689
Candidate Pairs 38,420
Match Results 38,420
Applicable GVRs 37,805
Verified GVRs 10,952
Rejected GVRs 26,853
Track Sets 1
Tracks 130,714
Track observations 318,944
The restart proof reused the existing Track Set without duplicating GVR mappings, Track observations or Tracks.
The real A6000 proof intentionally stopped before:
Sparse SfM
Sparse reconstruction
Dense / MVS
multi-campaign fusion
Calibration status of the historical real campaigns
The historical S21 and A6000 Engine Bay campaigns currently remain CALIBRATION_UNAVAILABLE for
the known-calibration Sparse SfM contract.
This is not a source failure, a quality rejection or permission to infer calibration from metadata. No pseudo-calibration, silent interpolation or inferred calibration identity is allowed.
Therefore real Sparse SfM for those historical campaigns remains:
BLOCKED_BY_KNOWN_CALIBRATION_DATA
Calibration Science v1 defines the protocol for future physically controlled calibration acquisitions. The external Calibration Evidence Solver v1 implements the qualified OpenCV 5.x evidence path. Calibration Tooling v1 validates bounded Science v1 evidence and produces the L3DCALB1 artifact; Calibration Bootstrap v1 imports that artifact. None of these stages turns EXIF into scientific calibration.
The current missing product boundary is the workflow coordinator that binds the immutable physical
session and solver bundle to one exact selected execution and drives Tooling/Bootstrap to READY.
Architecture
TUI / Project
|
v
bounded Task Queue
(one active callback)
|
v
Resource Governor
(admission and reservation)
|
v
admitted Task callback
(bounded internal participants when justified)
|
v
atomic / persistent scientific publication
|
v
passive snapshot consumers
(viewer remains future work)
Core invariants:
- no Task callback starts without a valid active reservation;
- the Queue does not own resource policy;
- the Resource Governor is the sole production resource authority;
- ncurses remains owned by the main thread;
- Task estimates and installed sequence contracts remain immutable for their defined lifetime;
- buffers, queues, files, threads, participants and temporary work remain bounded;
- owner-only durable publication does not imply serial preparation;
- swap, zram and external scratch never become admitted RAM;
- UMA GPU memory is charged exactly once against host memory.
Current TUI
The TUI is a validated operational observatory and control center.
It provides bounded observation of:
- Project state;
- Tasks and durable progress;
- Resource Governor state;
- CPU / RAM / swap / GPU information;
- optical profiles and explicit calibration selection;
- optional SSD state and safe control actions.
The ncurses renderer and input handling remain on the main thread. Runtime observation is bounded
and coalesced; the renderer does not scan Project DB or /proc extensively per frame.
The validated layout supports:
full layout >= 100x30
reference compact 72x20
minimum supported 60x15
Below the minimum, only the bounded terminal-too-small fallback is rendered.
The optical workflow supports electronic metadata aliases and manual lenses without EXIF. Missing, ambiguous or incompatible calibration remains visible and is never silently guessed.
Target pipeline
acquisition
-> catalog / Capture / provenance
-> quality selection
-> selected scientific representation
-> features
-> visual index
-> candidate pairs
-> matching
-> geometric verification
-> tracks
-> Sparse SfM
-> incremental / multi-campaign reconstruction
-> dense / MVS
-> mesh
-> refinement
-> texturing
-> consolidation
-> export
Planned product areas
The following areas remain future work and must not be confused with current implementation:
- durable dense / mesh publication;
- full Dense/MVS orchestration;
- mesh refinement and texturing;
- final export workflow;
- viewer;
- offline coverage analysis;
- suggested supplementary viewpoints;
- live camera localization;
- live coverage overlay;
- A6000 live acquisition integration;
- S21 live acquisition integration;
- capture guidance;
- video ingestion and deterministic keyframe extraction;
- explicit Task-owned scratch consumers;
- general DAG / dependency scheduling.
The final product contracts for these areas are being defined separately before implementation.
Documentation
Architecture
- Architecture overview
- Runtime
- Task system
- Task Kind Registry
- Task Queue
- Resource Governor
- Bounded internal parallelism
- Resource-aware pipeline
- Queue / runtime / Governor integration
- Reconstruction pipeline
- Persistence
- Project Database
- Feature Store
- Precision Feature Pipeline v1A
- Visual Index
- Candidate Pair
- Match Result
- Matcher
- Geometric Verification
- Geometric Verifier
- Track Model
- Track Builder
- Sparse SfM
- Calibration Bootstrap v1
- Calibration Science v1
- Calibration Solver Preflight v1
- Photo Quality Triage
- Vulkan ORB Matcher
- Viewer
- Resource Boundary
Historical audit records
Historical audit records preserve the state and evidence of their checkpoint. Older schema versions, Task counts or resource measurements inside them must not be mechanically modernized.
Concepts
Some concept documents are explicitly historical or superseded. Their status header determines whether they are current authority.
Development
Roadmap and audits
Build
Meson and Ninja are the canonical build path.
CC=clang meson setup build
meson compile -C build
Build parallelism should use safe host capacity. Do not treat a historical -j8 or the current
reference-host result of approximately -j12 as a portable constant.
Tests
meson test -C build --print-errorlogs
git diff --check
For memory-, lifetime- or concurrency-sensitive changes, use the applicable ASan/UBSan and TSan validation described in Testing and preserve documented third-party sanitizer qualifications.
Repository language
The canonical language for repository documentation, agent contracts and production source comments is English.
User-interface language is a separate product/localization concern.
Status
Lardon3D is under active development.
The persistent pre-SfM pipeline is implemented through Tracks, the Sparse SfM C-G capability is implemented and frozen at its documented boundaries, Phase H v1 is frozen, and MVS-M1 provides the validated external OpenMVS boundary. Full real known-calibration Sparse SfM, dense publication, mesh, texturing, viewer and live capture guidance remain future work.
The global maintenance checkpoint remains:
global-maintenance-2026-09-01
The later real A6000 pre-SfM checkpoint is:
real-a6000-pre-sfm-2026-09-02
Future reviews should preserve historical checkpoint meaning and review only the relevant delta unless concrete evidence requires reopening an unchanged FROZEN boundary.
License
Lardon3D is licensed under the MIT License.