225 lines
6.5 KiB
Markdown
225 lines
6.5 KiB
Markdown
# Calibration AF Study Evidence v1
|
|
|
|
**Status: PASS / FROZEN.**
|
|
|
|
This boundary is an offline scientific-evidence helper for Calibration Science
|
|
v2. It does not perform camera calibration, Project DB mutation, autofocus
|
|
control, calibration selection, or physical-validity decisions.
|
|
|
|
## Purpose
|
|
|
|
Project DB v27 can persist a physically validated exact-token focus domain, but
|
|
it deliberately does not decide whether a set of focus observations is
|
|
physically compatible.
|
|
|
|
`Calibration AF Study Evidence v1` supplies the missing measurement artifact:
|
|
|
|
```text
|
|
independent calibration results at observed focus states
|
|
-> deterministic pairwise image-space projection deltas
|
|
-> L3DAFST1 artifact
|
|
-> SHA-256 retained evidence
|
|
-> later human/scientific applicability decision
|
|
-> v27 focus-domain creation only after that decision
|
|
```
|
|
|
|
The real A6000 + E PZ 16-50 autofocus applicability remains:
|
|
|
|
```text
|
|
A6000_E_PZ_16_50_AF_APPLICABILITY=BLOCKED_BY_PHYSICAL_VALIDATION
|
|
```
|
|
|
|
This tool cannot change that state by itself.
|
|
|
|
## Input contract
|
|
|
|
The caller supplies one exact study context:
|
|
|
|
- nonzero SHA-256 of the retained body/lens/focal/non-focus geometric context;
|
|
- decoded/oriented width and height;
|
|
- 2..64 already acquired calibration samples.
|
|
|
|
Each sample contains:
|
|
|
|
- `FIT` or `HOLDOUT` role;
|
|
- one bounded, nonempty opaque exact focus token;
|
|
- nonzero SHA-256 of that calibration's retained evidence;
|
|
- exact binary64 `fx, fy, cx, cy, k1, k2, p1, p2`.
|
|
|
|
Repeated samples at one focus token are allowed only when they identify distinct
|
|
calibration evidence. Repeating the exact same `(focus token, calibration
|
|
evidence SHA-256)` is rejected and cannot masquerade as repeatability evidence.
|
|
|
|
The API performs no metadata interpretation. A Sony MakerNote value, for
|
|
example, must first be converted by the future acquisition/evidence layer into
|
|
the exact retained token policy selected for that study.
|
|
|
|
## Probe model
|
|
|
|
Version 1 measures the same frozen pinhole + `k1/k2/p1/p2` forward projection
|
|
model used by calibration/Sparse SfM.
|
|
|
|
Nine normalized ideal rays are evaluated:
|
|
|
|
```text
|
|
centre
|
|
(0, 0)
|
|
|
|
edge probes
|
|
(-0.7, 0) (+0.7, 0) (0, -0.7) (0, +0.7)
|
|
|
|
corner probes
|
|
(-0.7, -0.7) (+0.7, -0.7)
|
|
(-0.7, +0.7) (+0.7, +0.7)
|
|
```
|
|
|
|
For every pair of calibration samples, the artifact stores:
|
|
|
|
- centre delta in pixels;
|
|
- maximum cardinal edge-probe delta;
|
|
- maximum corner-probe delta;
|
|
- maximum over all nine probes;
|
|
- whether both samples use the same focus token;
|
|
- whether the pair crosses FIT/HOLDOUT roles.
|
|
|
|
These are measurements, not acceptance thresholds.
|
|
|
|
## L3DAFST1
|
|
|
|
The binary artifact is little-endian and bounded to 128 KiB.
|
|
|
|
It contains:
|
|
|
|
```text
|
|
magic = L3DAFST1
|
|
artifact version
|
|
probe-model version
|
|
study-context SHA-256
|
|
width / height
|
|
sample / pair / role counts
|
|
canonical sample records
|
|
all canonical pair records and projection metrics
|
|
```
|
|
|
|
Sample order is canonicalized by:
|
|
|
|
```text
|
|
focus-token bytes
|
|
calibration-evidence SHA-256
|
|
sample role
|
|
```
|
|
|
|
Therefore caller input order does not change artifact bytes or SHA-256.
|
|
|
|
Every floating value is finite binary64. Negative zero is normalized to positive
|
|
zero before serialization.
|
|
|
|
The artifact SHA-256 is suitable as retained evidence for a later v27
|
|
`lardon3d_optical_focus_domain_v2_create(...)` call only after the physical
|
|
study has been reviewed and its scientific applicability decision has been made.
|
|
|
|
## Summary output
|
|
|
|
The API also returns bounded aggregate measurements:
|
|
|
|
- FIT/HOLDOUT/sample/pair counts;
|
|
- same-focus / cross-focus / FIT-HOLDOUT pair counts;
|
|
- maximum centre, edge-probe, corner-probe and global pairwise delta;
|
|
- maximum same-focus global delta;
|
|
- maximum cross-focus global delta;
|
|
- maximum FIT/HOLDOUT global delta.
|
|
|
|
The summary is for inspection and orchestration. It does not encode PASS/FAIL.
|
|
|
|
## Non-goals
|
|
|
|
This v1 boundary does not:
|
|
|
|
- solve ChArUco calibration;
|
|
- parse EXIF/MakerNotes;
|
|
- invent physical focus distances;
|
|
- derive autofocus envelopes;
|
|
- define an acceptance pixel threshold;
|
|
- interpolate or extrapolate focus;
|
|
- open Project DB;
|
|
- create a v27 focus domain;
|
|
- make an execution READY.
|
|
|
|
The future physical study supplies the evidence needed to decide whether the
|
|
A6000 + E PZ 16-50 supports one domain, discrete domains, or exact focus only.
|
|
|
|
## Materialized Workflow bridge v1
|
|
|
|
**Status: PASS / FROZEN.**
|
|
|
|
`CALIBRATION_AF_STUDY_WORKFLOW_BRIDGE_V1` is the additive conversion boundary
|
|
between the already-FROZEN Calibration Workflow materializer and AF-study
|
|
samples.
|
|
|
|
It accepts a `Lardon3DCalibrationWorkflowExternalEvidence` that has already
|
|
passed the existing immutable-file, solver-bundle and provenance checks. It
|
|
does not parse `solve.json` or any other solver file again.
|
|
|
|
The bridge:
|
|
|
|
```text
|
|
materialized Calibration Workflow evidence
|
|
+ caller-supplied exact focus token
|
|
+ caller-supplied FIT/HOLDOUT role
|
|
-> Lardon3DCalibrationAfStudySample
|
|
```
|
|
|
|
The sample publishes `repeated_parameters[0]` only after checking that all three
|
|
retained full solves remain exactly equal.
|
|
|
|
Its `calibration_evidence_sha256` is independent of the focus token and
|
|
FIT/HOLDOUT role and binds:
|
|
|
|
- target identity;
|
|
- optical-state identity;
|
|
- solver executable/configuration identity;
|
|
- initialization evidence;
|
|
- validation evidence;
|
|
- exact oriented dimensions;
|
|
- exact published binary64 intrinsics.
|
|
|
|
Therefore relabelling one calibration result cannot manufacture independent
|
|
calibration evidence.
|
|
|
|
The bridge performs no DB access, metadata interpretation, physical AF decision,
|
|
thresholding, interpolation or extrapolation.
|
|
|
|
## Materialized study assembly v1
|
|
|
|
**Status: PASS / FROZEN.**
|
|
|
|
`CALIBRATION_AF_STUDY_ASSEMBLY_V1` composes the frozen Workflow bridge and
|
|
`L3DAFST1` producer so a physical AF study does not need caller-written sample
|
|
arrays.
|
|
|
|
The caller supplies:
|
|
|
|
```text
|
|
study_context_sha256
|
|
2..64 entries {
|
|
materialized Calibration Workflow evidence
|
|
exact opaque focus token
|
|
FIT or HOLDOUT role
|
|
}
|
|
```
|
|
|
|
The assembly:
|
|
|
|
1. converts every entry through the frozen Workflow bridge;
|
|
2. requires one exact oriented width/height for the whole study;
|
|
3. rejects a repeated `calibration_evidence_sha256` even when the caller changes
|
|
focus token or FIT/HOLDOUT role;
|
|
4. passes the resulting bounded samples to the frozen AF-study producer;
|
|
5. returns deterministic `L3DAFST1`, artifact SHA-256 and summary.
|
|
|
|
`study_context_sha256` remains caller-retained and explicit. This layer does not
|
|
derive body/lens/focal/non-focus state from solver metadata and does not decide
|
|
whether different focus observations belong to one physically valid domain.
|
|
|
|
No Project DB access, solver execution, metadata inference, thresholding,
|
|
interpolation or extrapolation is introduced.
|