117 lines
5.6 KiB
Markdown
117 lines
5.6 KiB
Markdown
# Calibration Publication v2
|
|
|
|
**PASS / FROZEN — additive heterogeneous calibration publication boundary.**
|
|
|
|
## Authority and scope
|
|
|
|
Calibration Science v2 is the frozen scientific authority. This document
|
|
defines only the additive heterogeneous publication bridge:
|
|
|
|
```text
|
|
caller-owned validated group evidence
|
|
-> Calibration Tooling v2
|
|
-> L3DCALB2
|
|
-> Calibration Bootstrap v2
|
|
-> existing SparseCalibrationScope(image_id -> calibration_id)
|
|
```
|
|
|
|
It does not change `L3DCALB1`, Calibration Tooling v1, or Calibration Bootstrap
|
|
v1. It does not run a solver, define optical applicability thresholds, resolve
|
|
READY outside publication, or add persistence schema.
|
|
|
|
## L3DCALB2 format
|
|
|
|
The artifact is deterministic, fixed-width, and little-endian. Integers use
|
|
the stated unsigned width. Binary64 fields contain IEEE-754 bits; producers
|
|
canonicalize negative zero and importers reject non-finite values. Native
|
|
structures, padding, locale text, and trailing bytes are forbidden. The whole
|
|
artifact is at most 600,000 bytes, with 1..4,096 groups and 1..4,096 entries;
|
|
the byte-size bound may impose a lower combined maximum. SHA-256 fields must be
|
|
nonzero.
|
|
|
|
```text
|
|
magic 8 bytes = ASCII "L3DCALB2"
|
|
format_version u32 = 2
|
|
model_kind u32 = PINHOLE(1)
|
|
model_version u32 = 1
|
|
group_count u32, 1..4096
|
|
entry_count u32, 1..4096
|
|
|
|
for each group in strictly increasing
|
|
(group_identity_sha256, group_version) order:
|
|
group_identity_sha256 32 bytes
|
|
group_version u32, nonzero
|
|
optical_state_sha256 32 bytes
|
|
target_sha256 32 bytes
|
|
solver_executable_sha256 32 bytes
|
|
solver_configuration_sha256 32 bytes
|
|
initialization_evidence_sha256 32 bytes
|
|
validation_evidence_sha256 32 bytes
|
|
member_count u32, nonzero
|
|
|
|
for each member in strictly increasing selected_item_index order:
|
|
selected_item_index u32
|
|
image_id u64, nonzero
|
|
representation_sha256 32 bytes
|
|
width, height u32, u32, nonzero
|
|
fx, fy, cx, cy f64, f64, f64, f64
|
|
k1, k2, p1, p2 f64, f64, f64, f64
|
|
support_images u32, nonzero
|
|
support_observations u32, nonzero
|
|
reprojection_rmse_px finite nonnegative f64
|
|
maximum_parameter_delta finite nonnegative f64
|
|
validation_flags u32 = 0x0f
|
|
```
|
|
|
|
The pinhole parameters and four validation bits have exactly the v1 meaning.
|
|
V2 introduces no new solver threshold. Positive focal lengths and principal
|
|
points inside the declared dimensions are required. Every selected item index
|
|
from zero through `entry_count - 1` occurs exactly once across the artifact,
|
|
and every `image_id` occurs exactly once. Group order and member order are
|
|
validated, not silently normalized.
|
|
|
|
## Provenance and publication
|
|
|
|
Each complete serialized group record, including its exact membership and all
|
|
group-local evidence, is independently SHA-256 hashed. That group digest is the
|
|
`IMPORTED_TRUSTED` provenance fingerprint for each calibration in that group.
|
|
The independently supplied whole-artifact SHA-256 protects transport and binds
|
|
the combined publication without replacing group-local provenance.
|
|
|
|
Bootstrap validates the whole artifact and then verifies every entry against
|
|
the immutable selected execution's exact item index, `image_id`, and current
|
|
representation asset SHA-256 before its first write. It creates or reuses the
|
|
existing content-addressed Sparse calibrations per entry, creates or reuses one
|
|
scope over every selected image across all groups. The original Bootstrap v2
|
|
import attaches that complete scope and retains its existing public behavior.
|
|
The separately named `publish_unattached` primitive returns the exact
|
|
selected-item/image/calibration mapping without attaching the scope; it exists
|
|
only so Workflow v2 can establish v26 compatibility before READY. A
|
|
pre-publication error attaches no scope. A later failure may retain immutable
|
|
calibration evidence but cannot make the execution READY. Exact retries reuse
|
|
calibrations and the scope and converge on the same attachment.
|
|
|
|
## Heterogeneous Workflow v2 composition
|
|
|
|
Workflow v2 consumes the L3DCALB2 artifact and a complete caller-owned binding
|
|
for every selected item. Each binding repeats the selected execution's durable
|
|
`item_index -> capture_id` relation. Capture identity is never recovered from
|
|
an image ID, path, SHA-256, filename, artifact group identity, or numeric group
|
|
ID.
|
|
|
|
Before unattached publication, Workflow v2 requires complete observed v26
|
|
geometric state for every selected Capture. Automatic resolution reports zero
|
|
exact candidates as `CALIBRATION_REQUIRED` and multiple exact candidates as
|
|
`SELECTION_REQUIRED`. Explicit existing applicability must be exactly
|
|
compatible. Explicit publication creates/reuses deterministic profile metadata
|
|
from the immutable artifact calibration and its group-local provenance, then
|
|
creates/reuses applicability from the declared exact-state exemplar. It does
|
|
not create scientific Capture identity or authorize interpolation.
|
|
|
|
For every selected item, the final resolved v26 sparse `calibration_id` must
|
|
equal that image's calibration member in the complete unattached scope. Only
|
|
after all items pass that equality does Workflow v2 attach the scope and return
|
|
`READY`. Invalid evidence or a wrong assignment is a distinct non-ready error.
|
|
Any earlier failure leaves the selected execution unattached; exact retries are
|
|
deterministic and converge through the immutable Bootstrap/profile/
|
|
applicability/selection APIs. No Project DB schema change is required.
|