181 lines
5.8 KiB
Markdown
181 lines
5.8 KiB
Markdown
# Calibration Workflow
|
|
|
|
## Status
|
|
|
|
```text
|
|
CALIBRATION_WORKFLOW=IN_PROGRESS
|
|
CALIBRATION_WORKFLOW_INPUT_BOUNDARY_V1=PASS/FROZEN
|
|
CALIBRATION_WORKFLOW_EVIDENCE_MATERIALIZATION_V1=PASS/FROZEN
|
|
CURRENT_WORKFLOW_NEXT=SELECTED_EXECUTION_BINDING_V1
|
|
```
|
|
|
|
## Authority
|
|
|
|
Calibration Science v1, Calibration Tooling v1 and Calibration Bootstrap v1
|
|
remain FROZEN scientific and import authorities.
|
|
|
|
This workflow is bounded orchestration only. It does not introduce a solver,
|
|
Project DB schema version, Task kind, Sparse SfM execution or reconstructed
|
|
scientific evidence.
|
|
|
|
## Frozen flow
|
|
|
|
```text
|
|
physical calibration acquisition
|
|
-> session.l3dcal
|
|
-> external Calibration Evidence Solver v1
|
|
-> immutable solver bundle
|
|
-> campaign-state evidence
|
|
-> Calibration Workflow
|
|
-> Calibration Tooling v1
|
|
-> L3DCALB1 v1
|
|
-> Calibration Bootstrap v1
|
|
-> selected execution READY
|
|
```
|
|
|
|
## Input Boundary v1
|
|
|
|
`CALIBRATION_WORKFLOW_INPUT_BOUNDARY_V1=PASS/FROZEN`.
|
|
|
|
The implementation is exposed through:
|
|
|
|
```text
|
|
include/lardon3d/calibration_workflow.h
|
|
src/calibration_workflow.cpp
|
|
```
|
|
|
|
Input Boundary v1 performs no Project DB mutation.
|
|
|
|
It accepts only bounded regular files and rejects special files and symlinks
|
|
before potentially blocking reads. File access follows the nonblocking,
|
|
close-on-exec regular-file discipline.
|
|
|
|
The bounded input set is:
|
|
|
|
```text
|
|
session.l3dcal
|
|
session.l3dcal.bundle/detection.json
|
|
session.l3dcal.bundle/solve.json
|
|
session.l3dcal.bundle/evidence.json
|
|
session.l3dcal.bundle/producer.json
|
|
L3DCAL_CAMPAIGN_STATE_V1
|
|
```
|
|
|
|
It verifies:
|
|
|
|
- regular bounded files;
|
|
- SHA-256 identities;
|
|
- strict session syntax;
|
|
- structurally valid canonical JSON bundle members;
|
|
- exact session SHA binding through `producer.json`;
|
|
- decoder/version consistency;
|
|
- exact optical-state SHA equality;
|
|
- exact optical-state token equality;
|
|
- campaign-state identity consistency.
|
|
|
|
Malformed JSON, oversize files, symlinks, FIFOs, session digest mismatch and
|
|
optical-state mismatch are rejected.
|
|
|
|
Input Boundary v1 does not:
|
|
|
|
- open or mutate Project DB;
|
|
- construct `Lardon3DCalibrationToolingEvidence`;
|
|
- call Calibration Tooling;
|
|
- produce `L3DCALB1`;
|
|
- invoke Calibration Bootstrap;
|
|
- change selected-execution state.
|
|
|
|
## Evidence Materialization v1
|
|
|
|
`CALIBRATION_WORKFLOW_EVIDENCE_MATERIALIZATION_V1=PASS/FROZEN`.
|
|
|
|
The implementation is additive:
|
|
|
|
```text
|
|
src/calibration_workflow_materialize.cpp
|
|
tests/test_calibration_workflow_materialize.cpp
|
|
```
|
|
|
|
It consumes only inputs that first pass Input Boundary v1 and performs no
|
|
Project DB access or mutation.
|
|
|
|
The caller owns bounded arrays for materialized views and coordinate checks.
|
|
On success the output borrows those arrays and retains:
|
|
|
|
- exact target generator SHA-256 and physical target measurements;
|
|
- measured white border and categorical planarity evidence;
|
|
- exact optical-state SHA-256;
|
|
- exact solver executable and configuration SHA-256;
|
|
- exact accepted/rejected per-view classifications and rejection reasons;
|
|
- hold-out assignment, frame region, distance band and target coverage;
|
|
- retained per-view residual counts and metrics;
|
|
- coordinate-equivalence checks derived from the retained session points;
|
|
- all three exact full-solve parameter vectors;
|
|
- exact fit parameter vector;
|
|
- support image/observation counts;
|
|
- global RMSE, maximum residual and high-residual fraction;
|
|
- hold-out RMSE and maximum residual;
|
|
- maximum parameter delta and `validation_flags=0x0f`.
|
|
|
|
The stage consumes published solver evidence; it does not reclassify views,
|
|
rerun calibration, average repeated solves or manufacture missing values.
|
|
|
|
`initialization_evidence_sha256` is the exact `session.l3dcal` SHA-256.
|
|
|
|
`validation_evidence_sha256` is deterministic and domain separated:
|
|
|
|
```text
|
|
SHA256(
|
|
ASCII("L3DCAL_WORKFLOW_VALIDATION_V1\n")
|
|
|| detection_sha256_raw32
|
|
|| solve_sha256_raw32
|
|
|| evidence_sha256_raw32
|
|
|| producer_sha256_raw32
|
|
)
|
|
```
|
|
|
|
This boundary deliberately does not construct per-campaign
|
|
`Lardon3DCalibrationToolingEntry` rows. Those rows require Project DB proof of
|
|
the selected image identities, representation bytes/dimensions and explicit
|
|
Capture optical assignments, which belongs to Selected Execution Binding v1.
|
|
|
|
## Campaign optical-state evidence
|
|
|
|
Project DB v23 retains exact explicit optical configuration identity, including
|
|
body, objective and focal state, but Calibration Science v1 requires a broader
|
|
scientific key including focus, stabilization and processing/decode state.
|
|
|
|
No equality may be inferred between those domains.
|
|
|
|
`L3DCAL_CAMPAIGN_STATE_V1` therefore provides immutable external evidence for
|
|
the complete Science v1 optical state. A later coordinator stage must verify
|
|
this evidence against both the calibration session and each selected Capture's
|
|
explicit Project DB optical configuration.
|
|
|
|
Absence or disagreement remains `CALIBRATION_UNAVAILABLE`.
|
|
|
|
## Current next boundary
|
|
|
|
```text
|
|
CALIBRATION_WORKFLOW_SELECTED_EXECUTION_BINDING_V1
|
|
```
|
|
|
|
The next stage may read Project DB, but must not mutate it. It must:
|
|
|
|
- load the exact selected execution and require the calibration/ready stage
|
|
appropriate to the existing FROZEN contract;
|
|
- require exact selected item count and order;
|
|
- match every campaign-state Capture row to the selected item;
|
|
- load each Capture's explicit v23 optical assignment and require the exact
|
|
declared optical configuration;
|
|
- load every selected image/asset identity;
|
|
- read the exact managed representation as a bounded regular file;
|
|
- require asset byte size and SHA-256 equality;
|
|
- decode the exact geometric representation and require oriented dimensions
|
|
compatible with the calibration evidence;
|
|
- construct the per-image `Lardon3DCalibrationToolingEntry` rows without
|
|
changing any scientific value.
|
|
|
|
Only after that read-only binding passes may a final workflow boundary invoke
|
|
the FROZEN Tooling/Bootstrap path and transition the selected execution to
|
|
truthful `READY`.
|