# Lardon3D — Product Definition v1 ## Status ```text PRODUCT_DEFINITION_V1=PASS/FROZEN PRODUCT_NAME=Lardon3D PRIMARY_PLATFORM=Linux PRIMARY_CONTROL_SURFACE=TUI OPTIONAL_GRAPHICAL_VIEWER=REQUIRED IMPLEMENTATION_AUTHORIZATION=NO PROMPT_TREE=NEXT ``` This document defines the target product. It is product authority for intended user-visible capability and end-to-end workflow. It does not reopen existing FROZEN scientific contracts, authorize a schema migration, authorize a new Task Kind, or authorize implementation by itself. Existing specialized architecture documents remain authoritative for already implemented/FROZEN scientific, persistence, runtime and resource contracts. When a future implementation choice conflicts with this product definition, the implementation must stop for explicit contract reconciliation rather than silently weakening the product requirement. ## Product statement Lardon3D is a persistent, incremental, resource-aware photogrammetry system that lets a user build, inspect, improve and export a 3D reconstruction from photographs, future video keyframes and device-assisted supplementary captures without losing scientific provenance or previously validated work. The final user workflow is not merely: ```text folder of photos -> model ``` It is: ```text project -> explicit acquisition / provenance -> optics and calibration readiness -> quality selection -> deterministic scientific representation -> Features -> Visual Index -> Candidate Pairs -> Matcher -> Geometric Verification -> Tracks -> Sparse SfM -> incremental / multi-campaign registration where required -> Dense / MVS -> mesh -> refinement -> texture -> coverage analysis -> viewer / capture guidance -> export ``` The system must remain restartable and inspectable throughout that lifecycle. ## Product principles ```text SCIENTIFIC_TRACEABILITY=REQUIRED DETERMINISTIC_IDENTITIES=REQUIRED PERSISTENT_PROGRESS=REQUIRED ATOMIC_PUBLICATION=REQUIRED BOUNDED_EXECUTION=REQUIRED MAXIMUM_SAFE_USEFUL_THROUGHPUT=REQUIRED SERIALISM_REQUIRES_PROOF=REQUIRED NO_SILENT_SCIENTIFIC_SUBSTITUTION=REQUIRED NO_DESTRUCTIVE_AUTOMATION=REQUIRED ``` The user should not have to understand internal CPU widths, batch sizes, task cursors or backend details to obtain correct execution. The product must make uncertainty visible rather than replacing it with a guess. ## Lifecycle vocabulary Product and implementation work use these states: ```text IDEA RESEARCH PLANNED AUTHORIZED IMPLEMENTING VALIDATED PASS/FROZEN REJECTED ``` `PASS/FROZEN` means the defined boundary is acquired and is not reopened without explicit evidence. `PLANNED` means the capability belongs to the target product but implementation is not yet authorized. `AUTHORIZED` means the human has explicitly authorized implementation of that scoped capability. This document may freeze a product requirement while its implementation remains only `PLANNED`. ## Current acquired foundation The following existing boundaries are consumed as-is: ```text Project DB head v25 Production Task kinds 16 Capture / Asset Provenance PASS/FROZEN Acquisition / campaign execution PASS/FROZEN Photo Quality Triage PASS/FROZEN Selected Scientific Execution PASS/FROZEN Feature Store v1/v2 IMPLEMENTED Visual Index v1 IMPLEMENTED Candidate Pair IMPLEMENTED Matcher v1 IMPLEMENTED Geometric Verifier v3 PASS/FROZEN Track Model / Track Builder v1 PASS/FROZEN Sparse SfM Gates A-G PASS/FROZEN Phase H v1 incremental reconstruction PASS/FROZEN MVS-M1 external OpenMVS boundary PASS/FROZEN Calibration Science v1 PASS/FROZEN Calibration Tooling v1 PASS/FROZEN Calibration Bootstrap v1 PASS/FROZEN Calibration Solver Preflight v1 PASS Resource Governor / Compute Governor PASS/FROZEN Bounded internal parallelism PASS/FROZEN ORB Vulkan backend PASS/FROZEN TUI runtime observatory VALIDATED External SSD controller VALIDATED ``` The final product extends these boundaries; it does not replace them merely for architectural uniformity. ## Real-data reference checkpoints Current retained real evidence includes: ```text REAL_S21_TRACKS=PASS/FROZEN REAL_A6000_PRE_SFM=PASS/FROZEN ``` The retained A6000 pre-SfM checkpoint contains: ```text 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 Sparse SfM Tasks 0 Sparse Reconstructions 0 Dense/MVS 0 ``` These campaigns are evidence, not product-size limits. They remain blocked from real known-calibration Sparse SfM by their historical calibration status. ## Project model ### Product requirement A project is the durable user-owned reconstruction workspace. The project must contain or reference all scientific identities required to understand what has been done, what is reusable, what is blocked and what is still pending. Reopening a project after a crash or reboot must not require the user to remember hidden transient state. ### Portability The durable project must not depend on: - absolute temporary paths; - current CPU topology; - current GPU device; - current external-scratch mount path; - a live camera connection; - a previous process ID; - a specific Task worker instance. Hardware-specific operational state is rediscovered. Scientific identities remain stable. ### Non-destructive history Valid immutable generations remain available unless explicitly deleted through a future supported cleanup operation. A new scientific result does not silently overwrite a previous result with a different identity. ## Primary user interface ```text TUI=PRIMARY_CONTROL_SURFACE GUI_CONTROL_REPLACEMENT=NO ``` The ncurses TUI remains the primary control plane. It owns workflow navigation and explicit user actions. The graphical viewer is an optional companion visualization surface, not a replacement for project control, resource ownership or durable task orchestration. Final TUI language: ```text USER_INTERFACE_LANGUAGE=ENGLISH ``` Remaining legacy non-English executable strings must converge to English in an explicitly scoped implementation pass. ## Required TUI product areas The final TUI must provide coherent access to: - project creation/open/close; - acquisition/import; - camera/lens/optical configuration; - calibration readiness and calibration workflow; - quality triage and selection; - pipeline stages and durable progress; - Tasks; - Resource Governor state; - external SSD/scratch state; - reconstruction generations; - viewer launch/control; - coverage analysis; - capture guidance state; - export; - diagnostics/help. Exact key bindings may evolve, but displayed actions and actual handlers must remain consistent. ## Optics onboarding Status: ```text OPTICS_ONBOARDING=PLANNED NEW_CAMERA_REQUIRES_CODE_CHANGE=NO NEW_LENS_REQUIRES_CODE_CHANGE=NO ELECTRONIC_LENS_WITH_METADATA=SUPPORTED MANUAL_LENS_WITHOUT_EXIF=SUPPORTED MULTIPLE_LENSES_PER_CAMERA=SUPPORTED ZOOM_MULTIPLE_FOCALS=SUPPORTED MULTIPLE_OPTICAL_CONFIGURATIONS_PER_PROJECT=SUPPORTED SILENT_CALIBRATION_SUBSTITUTION=FORBIDDEN SILENT_LENS_IDENTITY_INFERENCE=FORBIDDEN OPTICS_TUI_WORKFLOW=REQUIRED PROFILE_IMPORT_EXPORT=REQUIRED ``` ### Data-driven equipment Adding a normal supported camera body or lens must be a data operation. Source-code modification is required only when the equipment introduces a genuinely unsupported transport, file format, camera model or scientific model. A new brand/model name is not itself a reason for source changes. ### Camera body profile The user can create a body profile from: - exact electronic metadata when available; - manual make/model entry when unavailable; - explicit aliases for metadata variants. Aliases must be exact and reviewable. No fuzzy match may silently create scientific identity. ### Lens profile The user can create a lens profile with electronic metadata or manually. A manual lens without EXIF is a normal product path. The user must be able to assign the exact lens explicitly when metadata cannot identify it. ### Zoom lenses and focal configurations A zoom lens may own multiple optical configurations. The active scientific configuration includes the relevant focal configuration. Electronic focal metadata may select an exact known configuration only when the compatibility contract permits it. Manual focal selection is supported. Calibration must not be silently interpolated between focal configurations unless a future scientific contract explicitly validates such interpolation. ### Onboarding speed Target: ```text OPTICS_PROFILE_ONBOARDING_TARGET<=5_MINUTES ``` This target excludes the time required to perform a physical calibration acquisition. It includes creating/selecting body, lens, aliases and optical configuration. ### Profile import/export The final product must provide bounded, versioned profile import/export suitable for moving equipment profiles between Lardon3D installations. The portable representation must: - carry an explicit format version; - validate all bounds before database mutation; - preserve scientific/profile identity fields; - reject unknown required semantics; - never be a raw SQLite dump; - never silently merge conflicting profiles; - provide a dry-run/preview before import commit. The exact file encoding is an implementation-contract decision in the prompt tree. ## Calibration user experience Status: ```text CALIBRATION_WORKFLOW=PLANNED CALIBRATION_SCIENCE_V1=PASS/FROZEN ``` Sparse SfM v1 remains known-calibration only. ### User-visible readiness The optics/calibration workflow must expose at least: ```text READY CALIBRATION_REQUIRED SELECTION_REQUIRED ``` Meaning: - `READY`: one exact compatible calibration is explicitly selected and valid; - `CALIBRATION_REQUIRED`: no valid compatible calibration exists; - `SELECTION_REQUIRED`: multiple or otherwise unresolved valid choices require explicit user choice. A diagnostic may further explain incompatibility/corruption, but these core states must remain clear. ### No silent fallback The product must never silently use: - EXIF focal length as scientific calibration; - another lens's calibration; - a nearby focal calibration; - a calibration from another optical configuration; - an inferred "unknown lens"; - an interpolated calibration not authorized by science. ### Physical calibration assistant The final TUI must guide the user through the physical acquisition required by Calibration Science v1. The assistant must tell the user: - what target/setup is required; - which optical configuration is being calibrated; - which captures are accepted/rejected for evidence; - whether the evidence bundle is sufficient; - what remains to capture. It must not weaken Calibration Science v1 to make a session pass. ### External solver The selected external OpenCV 5.x solver remains outside the reconstruction scientific core. The final product should automate its invocation from the calibration workflow so the user does not need to manually construct solver evidence. Its output must still pass: ```text external solver -> Calibration Tooling validation -> deterministic L3DCALB1 v1 -> Calibration Bootstrap import -> explicit optical compatibility/selection ``` A solver success code alone is not calibration acceptance. ## Acquisition sources The final product accepts multiple acquisition-source classes through the same Capture/provenance model. ### Still-image import Status: ```text STILL_IMAGE_IMPORT=PASS/FROZEN_FOUNDATION ``` Supported product paths include: - standalone JPEG/PNG/TIFF-like decoded still images supported by the current decoder stack; - RAW sources through explicit RAW representation policy; - RAW+JPEG paired acquisitions; - mixed campaigns when their identities remain explicit. The selected scientific representation is never silently changed after selection. ### Live camera source Status: ```text LIVE_CAMERA_SOURCE=PLANNED ``` Live transport is a device-adapter concern at the acquisition boundary. It must not change Feature, Match, GVR, Track or reconstruction identity rules. Live preview frames are ephemeral observation frames unless explicitly promoted through a supported Capture/import path. ### Video source Status: ```text VIDEO_INGESTION=PLANNED ``` Video is an acquisition source, not a second reconstruction pipeline. Required flow: ```text SOURCE video asset -> exact timeline/frame identity -> deterministic bounded keyframe extraction -> quality / blur / redundancy analysis -> explicit selected frame representations -> normal Capture / provenance path -> existing scientific pipeline ``` Every retained keyframe must be traceable to: - source video asset identity; - exact frame/timestamp identity; - extraction algorithm/version; - extraction parameter fingerprint. No retained frame may exist only as an anonymous temporary bitmap. ### Keyframe science Keyframe scoring/threshold science is not frozen by this product document. The prompt/implementation process must create a versioned deterministic contract before implementation. ## Sony A6000 product integration Status: ```text A6000_LIVE_INTEGRATION=PLANNED A6000_FIRMWARE_MODIFICATION=REJECTED A6000_HARDWARE_MODIFICATION=REJECTED ``` The Sony A6000 must remain stock. No PMCA modification, custom firmware, camera-side hack or hardware modification belongs to the product. ### Live view Primary live path: ```text A6000 native HDMI -> external capture device -> Linux V4L2/UVC-class adapter where available -> Lardon3D live acquisition adapter -> viewer / localization / guidance ``` The product should discover capture-device capabilities rather than hard-code one USB card model. ### Camera control and transfer USB may be used for shutter/control/metadata/file transfer only through capabilities supported by the camera and verified by the adapter. USB control is not required for live preview correctness. If remote shutter is unavailable, the operator may capture on-camera and Lardon3D can ingest the resulting files through the normal acquisition path. ### Compute location ```text A6000_HEAVY_COMPUTE=PC_SIDE_ONLY ``` The camera is not a compute node. ## Samsung S21 product integration Status: ```text S21_LIVE_INTEGRATION=PLANNED S21_ROOT_REQUIRED=NO ``` The S21/mobile path uses a device-specific acquisition adapter while reusing the same Capture, provenance, optics, quality and scientific pipeline. The transport may differ from A6000. The product contract requires: - no root requirement; - no scientific core fork; - explicit full-resolution Capture ingestion; - live-preview frames treated as ephemeral until promoted; - graceful disconnect/reconnect; - exact optical/calibration configuration for scientific use. The exact Android transport mechanism remains an implementation decision. ## Device adapter boundary Device-specific code belongs at the acquisition/control edge. A device adapter may own: - discovery; - connection; - preview transport; - shutter/control when supported; - metadata retrieval; - file transfer; - reconnect semantics. It may not redefine: - Capture identity; - image scientific identity; - calibration science; - Feature identity; - Track identity; - reconstruction identity; - resource accounting. ## Quality workflow Automated quality analysis remains explainable and non-destructive. The product displays: ```text GOOD SUSPECT REJECT ``` as recommendations. The user may explicitly override a recommendation where the existing selection contract permits it. An override must be durable and visible; it must not rewrite the measured quality evidence. Live capture guidance should reuse the same quality concepts where practical so the operator can see blur/exposure/quality issues before relying on a capture. ## Sparse reconstruction Status: ```text SPARSE_SFM_CAPABILITY=PASS/FROZEN REAL_KNOWN_CALIBRATION_EXECUTION=PLANNED ``` The product must expose Sparse SfM as a normal pipeline stage once optics/calibration state is `READY`. A blocked known-calibration requirement must be shown explicitly. The user must never be offered a "continue anyway with guessed calibration" path. ### Sparse viewer evidence Sparse results should expose: - registered/unregistered cameras; - camera frustums; - sparse landmarks; - Track support; - reprojection diagnostics; - component structure; - arbitrary-vs-metric scale status. Physical distance tools must not label arbitrary monocular gauge units as millimetres/metres. ## Incremental reconstruction Status: ```text PHASE_H_V1=PASS/FROZEN ``` The final product uses existing incremental reconstruction when its lineage prerequisites are satisfied. Phase H is not a generic multi-campaign fusion mechanism. A scientifically unrelated or independently reconstructed campaign must not be forced through Phase H merely because it belongs to the same user project. ## Multi-campaign reconstruction Status: ```text MULTI_CAMPAIGN_REGISTRATION=PLANNED MULTI_CAMPAIGN_FUSION=PLANNED RAW_PROJECT_MERGE_WITHOUT_REGISTRATION=REJECTED ``` Multiple campaigns may exist in one logical project. Each campaign is reconstructed under its own exact optics/calibration context. Independent reconstructions are combined only after an explicit registration stage establishes their relationship. ### Registration product contract Registration must produce an explicit durable transform with provenance and quality evidence. Depending on scale knowledge, the accepted transform may be: - rigid when metric scales are compatible; - similarity when relative scale must be solved. The product may use automatic overlap evidence and may offer manual control-point assistance as a fallback. The exact registration algorithm is a future scientific contract. ### Fusion rule Fusion occurs only after registration is accepted. The product must preserve per-campaign provenance so a user can inspect which campaign contributed to a region/result. The S21 and A6000 historical projects must not be casually merged at raw Feature/Track level. ## Dense / MVS Status: ```text MVS_M1_EXTERNAL_BOUNDARY=PASS/FROZEN DURABLE_DENSE_PIPELINE=PLANNED INITIAL_DENSE_BACKEND=OpenMVS GENERIC_BACKEND_FRAMEWORK=REJECTED_FOR_V1 ``` The first final-product dense path should build on the validated OpenMVS boundary rather than invent a generic backend framework first. ### Dense Task requirements Dense execution must become: - durable; - restartable at explicit boundaries; - resource-governed; - scratch-aware; - failure-atomic for published scientific outputs; - inspectable through TUI progress/diagnostics. External process exit status is not sufficient by itself; expected output assets must validate before publication. ### Dense failure behavior OOM, process crash, invalid output or missing asset must fail the Task cleanly. The project must remain reopenable. A failed dense attempt must not corrupt or invalidate the upstream Sparse Reconstruction. ## External SSD, scratch and swap Status: ```text EXTERNAL_SSD_CONTROLLER=VALIDATED TASK_SCRATCH_CONSUMPTION=PLANNED PROJECT_SCRATCH_OPT_IN=REQUIRED SWAP_OPT_IN=REQUIRED SCRATCH_COUNTS_AS_RAM=NO SWAP_COUNTS_AS_RAM=NO ``` ### Discovery The TUI should detect the validated external SSD pairing and show: - physical identity; - mount state; - scratch state; - swap state; - capacity/usage when known; - active leases; - drain/safe-to-unplug state. ### Project scratch The user explicitly chooses whether an eligible external scratch volume may be used by the project. No project silently adopts a newly connected disk. Future dense/mesh/refine/texture Tasks may acquire scratch only through the established Governor lease boundary. ### Swap Swap is a host safety mechanism. The product may offer explicit enable/disable control when supported by the validated SSD controller. Swap never increases RAM admission. ### Destructive operations The product must not automatically: - repartition; - format; - fsck destructively; - overwrite an unknown filesystem; - force-unmount an active lease. ## Mesh Status: ```text MESH_PIPELINE=PLANNED ``` The product must support generation of a surface mesh from a validated dense result. The mesh is a distinct immutable result with exact provenance. A failed mesh attempt does not alter the dense source. ## Mesh refinement Status: ```text MESH_REFINEMENT=PLANNED ``` Refinement is an explicit stage and result identity. It must not silently mutate the source mesh. Resource-heavy refinement may use external scratch through a Task-owned lease. ## Texturing Status: ```text TEXTURING=PLANNED ``` Texturing consumes an explicit mesh/reconstruction/image scope. Texture provenance must retain the source image/campaign relationship. A user must be able to inspect an untextured mesh even if texturing fails. ## Consolidation Status: ```text FINAL_CONSOLIDATION=PLANNED ``` Consolidation creates a final user-facing selected result from explicit upstream generations. It does not delete those upstream generations. Selection is explicit and reversible until the user deliberately performs cleanup. ## Export Status: ```text EXPORT_WORKFLOW=PLANNED ``` The final product must support practical interoperable outputs. Minimum target formats: ```text sparse/dense point cloud: PLY mesh: PLY and OBJ textured mesh: OBJ + MTL + texture assets portable viewer asset: GLB/GLTF geometry-only exchange: STL optional ``` The exact exporter set may grow, but proprietary-format lock-in is not acceptable. Exports must carry a manifest or sidecar metadata sufficient to identify the source reconstruction, mesh/texture generation and scale status. If scale is arbitrary, the export must not claim a metric unit. ## Graphical viewer Status: ```text VIEWER=PLANNED VIEWER_IS_PASSIVE_CONSUMER=REQUIRED VIEWER_CAN_BE_DISABLED=REQUIRED VIEWER_BLOCKS_ENGINE=NO ``` The TUI remains the control surface. The viewer is a graphical companion that can be launched/closed without stopping reconstruction. Functional isolation is mandatory; process isolation is optional. ### Snapshot boundary The viewer consumes coherent validated snapshots. It must not borrow mutable engine internals. If it falls behind, it drops obsolete visual snapshots rather than creating an unbounded backlog. ### Required visualization modes The final viewer must support, when the corresponding data exists: - sparse landmarks; - dense point cloud; - mesh; - textured mesh; - registered cameras/frustums; - reconstruction components; - selected ScanSet/campaign contribution; - Track/observation support; - reprojection/quality diagnostics; - coverage heatmap; - weak regions; - unseen regions; - likely holes; - live camera pose/frustum; - suggested capture targets. ### Interaction Required interaction includes: - orbit/pan/zoom; - reset/focus; - element/region selection; - camera selection; - visibility toggles; - diagnostic inspection; - measurement when scale is valid; - region-of-interest selection for coverage/guidance. Viewer annotation must not silently become scientific input unless the user explicitly invokes a supported operation such as future control-point registration. ## Coverage Analysis Status: ```text OFFLINE_COVERAGE_ANALYSIS=PLANNED ``` Coverage Analysis answers: ```text Where is the reconstruction well supported? Where is evidence weak? Where is the object likely unseen? Where would another photograph provide useful information? ``` ### Coverage evidence The product must be able to use, where available: - observation/view count; - distinct camera count; - angular diversity; - incidence/viewing angle; - parallax; - camera distance; - projected resolution; - image quality; - Feature/Track support; - reprojection/triangulation quality; - visibility/occlusion; - mesh/dense support; - hole/boundary evidence; - ScanSet/campaign provenance. ### Coverage states The UI must distinguish at least: ```text UNKNOWN UNSEEN WEAK ADEQUATE ``` `UNKNOWN` is required when the available reconstruction cannot support a truthful classification. Thresholds/weights are scientific policy and must be versioned before implementation. ### Region of interest Coverage can operate over: - the complete current reconstructed surface; - an explicit user-selected region of interest. A global "complete" claim is invalid when no meaningful target surface/ROI is defined. ### Sparse versus mesh coverage Sparse-only analysis is allowed but must identify its lower-confidence/support boundary. Mesh/dense availability may provide stronger visibility/hole reasoning. The product must not fabricate a closed surface from sparse points merely to claim coverage. ## Suggested supplementary viewpoints Status: ```text VIEWPOINT_SUGGESTION=PLANNED ``` Coverage weaknesses can be converted into ranked capture suggestions. Each suggestion must expose: - target region; - suggested viewing direction; - suggested camera-position zone or relative viewpoint; - distance/range guidance; - angle/incidence guidance; - baseline/parallax relationship to existing views; - expected coverage/evidence improvement; - confidence/feasibility; - reason. The user should receive an actionable instruction, not only a red heatmap. The exact optimization/scoring policy must be versioned and validated before implementation. ## Live camera localization Status: ```text LIVE_CAMERA_LOCALIZATION=PLANNED ``` The live camera may be localized against an existing compatible reconstruction. Required high-level path: ```text live frame -> bounded Features -> correspondence to existing reconstruction -> calibrated pose -> confidence / diagnostics -> viewer snapshot ``` ### Preconditions Precise localization requires: - compatible exact camera calibration; - a reconstruction with usable 3D reference; - enough valid correspondence support; - acceptable geometric confidence. When those prerequisites are not satisfied, the product reports the reason. ### Tracking loss The live system must have explicit states such as: ```text UNAVAILABLE SEARCHING LOCALIZED LOW_CONFIDENCE LOST ``` A stale last-good pose must not be displayed as current localization without a visible stale/lost indicator. ## Live Coverage / Capture Guidance Status: ```text LIVE_COVERAGE_OVERLAY=PLANNED CAPTURE_GUIDANCE=PLANNED AUTO_CAPTURE=IDEA ``` Target loop: ```text existing reconstruction -> offline/current coverage model -> weak/unseen target -> live camera localization -> project target into live view -> guide operator -> acquire full-resolution photograph -> normal ingestion/quality/scientific pipeline -> incremental/re-registration update -> coverage refresh ``` ### Overlay The live viewer should make weak/unseen regions visually obvious. Exact color theme is UI policy, but the semantic distinction must be readable without relying solely on color. ### Guidance Guidance should tell the operator how to move: - left/right/up/down; - closer/farther; - rotate toward/away from target; - increase/decrease incidence angle; - increase/decrease baseline where appropriate. The product should display the reason and confidence. ### Safety against false certainty When localization or coverage confidence is insufficient: - no precise overlay is asserted; - no "capture here" instruction is presented as certain; - the UI falls back to a clear diagnostic/search state. ### Capture action Initial product requirement is operator-confirmed capture. Automatic shutter release is not required for v1 capture guidance. `AUTO_CAPTURE=IDEA` may be revisited only after live localization, guidance and device control are validated. ## Reconstruction update after guided capture A guided photograph becomes normal project evidence only after full-resolution ingestion and normal validation. The live preview bitmap itself is not silently promoted. The project must reuse already valid upstream work and process only the scientifically affected delta whenever the existing frozen contracts permit it. ## Resource behavior The canonical objective remains: ```text MAXIMUM_SAFE_USEFUL_THROUGHPUT SERIALISM_REQUIRES_PROOF ``` ### Automatic execution Normal product operation automatically chooses: - CPU width; - batch/window; - GPU backend when validated/useful; - inflight depth; - internal participant count; - scratch use for Tasks that own a scratch contract. The user may observe these choices but is not required to tune them. ### Interactive reserve The Resource Governor preserves the defined interactive host reserve and then uses the maximum remaining safe useful resources. Reference-host values are not product constants. ### GPU A validated useful GPU backend is preferred automatically. A GPU backend is not required when profiling says it is not useful. Backend failure must have a defined failure/fallback contract where the scientific stage supports one. ### Memory No Task treats swap, zram or scratch as RAM. UMA GPU memory is charged once. No unbounded whole-project load is allowed merely for convenience. ## Persistence and recovery product requirement Every user-visible long-running stage must have an explicit durable/restart contract before it is considered final-product complete. The product must support clean recovery from: - application close; - system reboot; - Task cancellation; - process crash; - external-process failure; - external scratch disconnect after safe drain; - partial physical asset publication where the existing orphan semantics allow it. Restart must never require guessing the scientific input from a filename or timestamp. ## Determinism Scientific identity is independent of: - CPU thread count; - worker scheduling; - host model; - GPU model unless the backend is scientifically non-transparent; - temporary path; - wall-clock duration. Where exact bit identity cannot be promised across dependency/hardware versions, the relevant scientific contract must define the reproducibility boundary honestly. ## Diagnostics The product must distinguish: - scientific rejection; - invalid input; - missing prerequisite; - resource wait/throttle; - runtime failure; - corruption; - unsupported version/backend; - user cancellation. A generic "failed" message without the owning layer/reason is insufficient for final-product workflows. ## No silent inference Across the product, the following are forbidden unless a specific scientific contract explicitly says otherwise: - selecting "latest" scientific result by timestamp; - calibration substitution; - lens identity guessing; - focal interpolation; - physical scale invention; - cross-campaign alignment by filename/time alone; - treating a preview frame as a scientific capture; - treating a GPU/CPU implementation choice as scientific identity without reason; - pretending unknown coverage is adequate. ## Product security and privacy boundary The core reconstruction workflow is local-first. No cloud service is required for: - project operation; - reconstruction; - calibration processing; - viewer; - coverage analysis; - capture guidance; - export. Future optional network/device adapters must make network use explicit. User project imagery is not uploaded merely to operate the product. ## Cleanup and storage management Project cleanup is explicit. The product may identify: - orphan temporary assets; - superseded immutable generations; - export caches; - stale scratch. It must show what will be removed before destructive cleanup. FROZEN/historical evidence is never deleted automatically because a newer generation exists. ## Performance product requirement Performance is judged by useful end-to-end throughput while maintaining: - scientific correctness; - deterministic publication; - memory bounds; - host responsiveness; - restartability. A stage that leaves safe useful CPU/GPU capacity idle without a measured/contractual reason is a performance defect. A stage that saturates the host beyond its safety reserve is also a defect. ## Final end-to-end user journey A normal future still-image project should support: ```text 1. Create/open project. 2. Select/create camera body and lens profile. 3. Resolve exact optical configuration. 4. If needed, complete calibration workflow until READY. 5. Import/capture images. 6. Review quality recommendations and explicit selection. 7. Run selected scientific pipeline through Tracks. 8. Run Sparse SfM. 9. Inspect sparse reconstruction in viewer. 10. Add another campaign or supplementary images if useful. 11. Register/enrich according to the correct scientific relationship. 12. Run Dense/MVS. 13. Build/refine mesh. 14. Texture. 15. Run coverage analysis. 16. Inspect weak/unseen regions. 17. Optionally use live capture guidance to acquire missing evidence. 18. Reprocess only the affected delta. 19. Consolidate a desired result. 20. Export interoperable outputs. ``` The user can stop/restart between long stages without invalidating completed durable work. ## Final A6000 guided-capture journey Target: ```text stock Sony A6000 -> native HDMI live view -> capture card -> Lardon3D viewer -> calibrated live localization -> weak/unseen overlay -> actionable viewpoint guidance -> operator capture -> RAW+JPEG/full-resolution transfer/import -> quality/selection -> normal incremental scientific update -> refreshed coverage ``` No camera modification is required. ## Final S21 guided-capture journey Target: ```text stock/non-rooted S21 -> device acquisition adapter -> live preview -> calibrated live localization -> coverage/guidance -> full-resolution capture/import -> normal scientific update ``` The exact mobile transport is not part of the scientific core. ## Definition of Done — product Lardon3D is product-complete for this definition only when all `PLANNED` required capabilities in this document have reached at least `VALIDATED`, with the relevant scientific boundaries `PASS/FROZEN` where appropriate. Minimum end-product proof requires all of the following: ### Core workflow - new project can reach calibrated real Sparse SfM; - durable Dense/MVS can run and restart; - mesh/refine/texture can publish validated immutable results; - exports are usable and traceable. ### Optics - a new normal camera profile requires no source change; - a new normal lens profile requires no source change; - manual lens works without EXIF; - zoom/multiple focal configurations work explicitly; - profile import/export works; - calibration ambiguity blocks rather than guesses. ### Viewer - sparse, dense, mesh and textured result visualization works; - cameras and diagnostics are inspectable; - viewer can close/crash/lag without corrupting or blocking the engine. ### Coverage and guidance - offline weak/unseen analysis works with explicit confidence; - a recommended supplementary viewpoint is actionable; - live localization reports loss/uncertainty truthfully; - A6000 native-HDMI guidance path is demonstrated without modifying the camera; - captured supplementary evidence returns through the normal durable pipeline. ### Recovery/resources - representative long stages survive restart at their documented durable boundary; - no unsafe use of swap/scratch as RAM; - external scratch can be drained and safely disconnected; - safe useful CPU/GPU capacity is used automatically. ### Scientific integrity - no silent calibration/lens/scale/campaign inference; - FROZEN historical identities remain interpretable; - result provenance is sufficient to explain which inputs/configuration produced an output. ## Explicitly not required for Product Definition v1 The following are not prerequisites for product completion unless later explicitly promoted: ```text AUTO_CAPTURE MULTI_GPU DISTRIBUTED_COMPUTE GENERAL_INTER_TASK_DAG GENERAL_BACKEND_FRAMEWORK CAMERA_FIRMWARE_MODIFICATION CAMERA_HARDWARE_MODIFICATION CLOUD_RECONSTRUCTION ``` ## Implementation sequencing constraint This document does not choose file-by-file implementation order. The next phase is the canonical `prompt.md` plus numbered `prompt/` execution tree. That tree must: - preserve all existing FROZEN contracts; - encode this product definition without weakening it; - separate current facts from future requirements; - define explicit STOP conditions; - define allowed implementation order; - define schema/Task/scientific authorization boundaries; - require delta-based validation; - keep Git closure under human ownership unless explicitly delegated. Until that tree is frozen: ```text IMPLEMENTATION_AUTHORIZATION=NO PROMPT_TREE=NEXT ```