# Geometric Verifier v1 / v2 / v3 ## Status ```text HISTORICAL_GEOMETRIC_VERIFIER_V1=FROZEN HISTORICAL_GEOMETRIC_VERIFIER_V2=FROZEN CURRENT_GEOMETRIC_VERIFIER_V3=PASS/FROZEN CURRENT_VERIFIER_KIND=FUNDAMENTAL CURRENT_VERIFIER_VERSION=3 CURRENT_VERIFIER_FINGERPRINT=6944a471d611d8ffc59dac7cf15a5b79b97e2371d4c51785c477d68c1577f74c GEOMETRIC_VERIFIER_GPU=NOT_JUSTIFIED REAL_S21_GV_V3=PASS/FROZEN REAL_A6000_PRE_SFM=PASS/FROZEN ``` This document owns the scientific execution that turns one valid `MATCHED` Match Result into one completed Fundamental Geometric Verification Result. The persistent row model is owned by `geometric_verification.md`. Tracks, Essential pose, triangulation and Sparse SfM are downstream. ## Version lineage ### v1 Verifier v1 is a frozen historical scientific identity. Its existing fingerprints and GVR rows remain immutable. ### v2 Verifier v2 preserves the v1 estimator/acceptance path but adds a bounded preflight requiring enough distinct canonical observations on both sides before estimator execution. It has its own version/fingerprint. ### v3 Verifier v3 is the current production policy. It preserves v2 validation and additionally rejects estimator-ineligible parents when: ```text match_count < min_inlier_count ``` because acceptance is mathematically impossible in that case. At equality, the parent remains estimator-eligible. V3 does not relabel or mutate v1/v2 rows. Project DB v12 already stores verifier version/fingerprint, so no GVR schema migration is needed. Current project schema head is v25. ## Inputs The exact Match Result supplies: - Candidate Pair relation; - Feature Set A/B identities; - Match File path/size/SHA; - `match_count`. Feature readers provide keypoints for the two immutable Feature Sets. The verifier does not need descriptor blocks in its normal geometry path. Feature coordinates are persistent binary32 decoded-image pixels with top-left origin. They are converted to binary64 `Point2d` for geometric computation. ## Input ordering Estimator row `i` corresponds exactly to Match File entry `i`. The verifier does not reorder or deduplicate Match File rows. The published inlier bit `i` always maps back to Match File entry `i`. Out-of-range Feature indices or corrupt assets are runtime/input failure, not scientific rejection. ## Canonical observation identity For preflight counting: ```text A = (feature_set_id_a, feature_index_a) B = (feature_set_id_b, feature_index_b) ``` V2/v3 require at least seven distinct A observations and seven distinct B observations. Failure publishes a zero-inlier `GEOMETRIC_REJECTED` result with a correctly sized all-zero mask and no Fundamental model. This preflight does not: - rewrite Matcher evidence; - enforce one-to-one matching; - deduplicate coordinates; - perform a rank test; - perform collinearity analysis; - run Homography competition. Distinct Feature IDs with identical coordinates remain distinct observations. ## v3 acceptance-feasibility preflight V3 additionally checks the durable configured `min_inlier_count`. When: ```text match_count < min_inlier_count ``` the maximum possible support cannot satisfy acceptance, so V3 publishes the canonical zero rejection without calling USAC. The threshold comes from configuration, never a hidden constant. ## Scientific model The only production model is a 3x3 Fundamental matrix. Accepted output must be finite, non-zero and canonical. The current verifier does not add Essential/Homography model competition. ## Production algorithm The production estimator uses explicit OpenCV USAC/MAGSAC parameters rather than a hidden preset. Scientific choices include: ```text model FUNDAMENTAL algorithm USAC_MAGSAC point representation Point2d threshold 1.5 px confidence 0.999 max iterations 5000 minimum inlier count 16 minimum inlier ratio 0.20 sampler uniform score MAGSAC isParallel false LO iterations 5 LO sample size 14 polisher COV polisher iterations 3 ``` The internal scientific estimator remains serial: ```text UsacParams::isParallel=false ``` Outer Task-level concurrency is separate. ## Random seed The seed is derived locally from immutable scientific input. The frozen seed domain is based on: ```text L3DGVSE1 Match File SHA-256 verifier parameter fingerprint ``` The resulting seed is supplied to the per-call USAC parameter object. Global `cv::theRNG()` mutation is forbidden. ## Parameter fingerprint The verifier fingerprint is SHA-256 over the frozen canonical 84-byte encoding. Domain: ```text L3DGVFP1 ``` It explicitly encodes: - verifier kind; - verifier version; - algorithm; - threshold; - confidence; - iteration bound; - minimum inlier count; - minimum inlier ratio; - seed-policy version; - canonicalization version; - Point2d selection; - sampler; - score; - `isParallel`; - LO settings; - neighbor mode; - polisher settings; - reserved zero byte. Integers are little-endian. Binary64 values use explicit IEEE-754 bits encoded little-endian. No C struct dump participates. Current v3 production fingerprint: ```text 6944a471d611d8ffc59dac7cf15a5b79b97e2371d4c51785c477d68c1577f74c ``` Historical v1/v2 fingerprints remain distinct and valid. ## Acceptance A candidate is verified only when the frozen support policy is satisfied: ```text inlier_count >= 16 inlier_count / match_count >= 0.20 ``` Otherwise the result is scientific `GEOMETRIC_REJECTED`. A scientific rejection is a completed valid result. Runtime failure publishes no scientific GVR. ## Fundamental canonicalization The nine coefficients must be finite. Frobenius norm is computed robustly; zero norm is rejected. The pivot is the first row-major coefficient having the strictly greatest absolute value. The matrix is normalized and signed so that pivot is positive. Signed zeros are normalized to `+0.0`. No production SVD/rank-2 post-projection is performed by this verifier version. ## Inlier mask OpenCV output mask is validated for type, length and values. It is converted without reordering to the persistent LSB-first GVR bitset. Padding bits are zero and popcount matches `inlier_count`. ## Runtime failure versus rejection Scientific rejection includes valid cases such as: - insufficient canonical support; - v3 impossible acceptance support; - estimator returns no acceptable model; - inlier support below frozen acceptance. Runtime/input failure includes: - missing/corrupt Match or Feature asset; - out-of-range Feature index; - malformed estimator mask; - non-finite invalid model; - OOM; - unexpected OpenCV exception; - Project DB publication failure. Runtime failure publishes no fake rejected result. ## Resource bounds One scientific atomic item is one Match Result with at most 8192 correspondences. Current outer-parallel Task reservation uses approximately: ```text 8 MiB per admitted parent batch/window <= 16 useful CPU participants <= 8 GPU 0 ``` The window is safe to 16; CPU8 is the retained useful maximum from measurement. These are operational resource values, not fingerprint fields. No descriptors or dense A-by-B matrix are loaded by the normal verifier. ## Outer parallel execution Current validated shape: ```text one admitted owner Task -> bounded independent Match Result preparation -> up to admitted CPU participants -> join -> owner publishes canonical contiguous prefix -> owner advances cursor -> checkpoint -> sequence_break ``` Participant preparation writes no GVR rows. Only the owner publishes after join. This preserves deterministic parent ordering and restart semantics. The inner USAC solver remains scientifically serial. ## GPU policy Current classification: ```text GEOMETRIC_VERIFIER_GPU=NOT_JUSTIFIED ``` Measured CPU units remained small enough that no production GPU backend was justified. No Vulkan/OpenCL/CUDA verifier backend is currently part of the production identity. CPU outer parallelism remains valid and should not be disabled merely because GPU is rejected. ## Durable Task Task Kind: ```text geometric_verifier.run/1 ``` Project DB v13 adds the typed task payload required because generic checkpoint v1 does not contain the scientific verifier parameters/cursor. Durable payload includes the immutable scientific configuration and: ```text after_match_result_id ``` The fingerprint is revalidated on reconstruction. The durable payload does not contain: - `cv::Mat`; - RNG engine state; - Governor feedback; - hardware identity; - CPU mask; - transient buffers. ## Restart Pagination follows increasing `match_result_id` and does not assume contiguous IDs. A GVR is published before the durable cursor advances. Crash after publication but before checkpoint may replay that parent. Restart finds/revalidates the exact GVR identity and reuses it. No overwrite is performed. ## Historical resource normalization The exact historical serial resource shape remains accepted only for restart compatibility. It may be normalized ephemerally to the current outer-parallel capability. The original checkpoint is not rewritten. Neighboring resource shapes are rejected rather than guessed. ## Real S21 GV v3 Retained S21 proof: ```text REAL_S21_GV_V3=PASS/FROZEN Match Results 172,741 Applicable MATCHED 172,275 Verified 24,065 Rejected 148,210 non-applicable 466 duplicate mapping 0 ``` The v3 fingerprint is the current production fingerprint. A complete replay produced zero new GVRs. A SIGKILL/restart proof resumed the same Task and converged to the same complete GVR set. The run stopped before Track Builder at the original GV-only checkpoint. Later S21 Track evidence exists separately. ## Real A6000 v3 The retained A6000 pre-SfM continuation contains: ```text Match Results 38,420 Applicable GVRs 37,805 Verified GVRs 10,952 Rejected GVRs 26,853 duplicate mappings 0 ``` Current fingerprint: ```text 6944a471d611d8ffc59dac7cf15a5b79b97e2371d4c51785c477d68c1577f74c ``` The Task completed the full cursor. Restart traversed the cursor and created zero new GVRs. The continuation then reused/built the frozen Track Set and stopped before real Sparse SfM. ```text REAL_A6000_PRE_SFM=PASS/FROZEN ``` ## Validation boundaries The scientific verifier validation covers: - canonical fingerprint/seed; - bit-exact mask mapping; - acceptance boundaries; - corruption; - publication/reuse; - maximum Match File cardinality; - restart; - deterministic canonicalization; - outer-parallel owner publication. TSan qualification must preserve the external OpenCV/TBB boundary described by the concurrency/global maintenance documents. Do not claim Vulkan verifier validation: there is no production Vulkan verifier backend. ## Summary ```text CURRENT_GEOMETRIC_VERIFIER=FUNDAMENTAL_V3 CURRENT_VERIFIER_VERSION=3 CURRENT_VERIFIER_FINGERPRINT=6944a471d611d8ffc59dac7cf15a5b79b97e2371d4c51785c477d68c1577f74c GEOMETRIC_VERIFIER_TASK=geometric_verifier.run/1 PROJECT_DB_GEOMETRIC_VERIFICATION=v12 PROJECT_DB_GEOMETRIC_VERIFIER_TASK=v13 INNER_USAC_PARALLEL=false OUTER_PARALLEL=VALIDATED USEFUL_CPU_MAX=8 SAFE_WINDOW_MAX=16 PER_ITEM_RAM=8_MiB GPU=NOT_JUSTIFIED REAL_S21_GV_V3=PASS/FROZEN REAL_A6000_PRE_SFM=PASS/FROZEN CURRENT_PROJECT_DB_SCHEMA=v25 ```