API: Pools

Scoring-pool input and output.

Public names

VisualGeometryToolkitEval.Pools — Module
Pools

Scoring-pool input and output. A pool (ScoringPool) holds VisualGeometryToolkitCore PoolPair records; its residual matrices (PoolResiduals) are bound to it by the content key pool_key. The module has one writer and one reader of each (save_pool, load_pool), the per-scene loaders (scene_loaders), the scene-pool producer (write_scene_pool), the perspective-n-point (PnP) pool file (save_pnp_pool) and the minimal-sample boundaries of a pool (sample_starts).

A scoring pool is stored in NormalizedImageFrame (frame) and a PnP pool in ImageFrame. Nothing here converts a frame.

source
VisualGeometryToolkitEval.Pools.PoolResiduals — Type
PoolResiduals

The residual matrices of a pool, bound to its light file by pool_key.

Fields:

  • pool_key::String: the pool_key of the pool they belong to.
  • kind::Symbol: the residual they hold — :sampson (the plane Sampson distance of the pool-frame model; F and H pools) or :tangent_sampson (the tangent Sampson of the metric essential on the pool-frame E problem; E pools).
  • matrices::Vector{Matrix{Float32}}: one (num_points, num_models) matrix per held pair, |r| in NormalizedImageFrame units.
  • pairs::Vector{Int}: the pool indices of the held pairs, in the order of matrices — every pair (1:n) unless the residuals were read for a subset (load_pool_residuals(path, pool; pairs)).
source
VisualGeometryToolkitEval.Pools.ScoringPool — Type
ScoringPool{M}

One scene's scoring pool in memory: the light records, without their residual matrices (PoolResiduals).

Fields:

  • pairs::Vector{PoolPair{M}}: the records (VisualGeometryToolkitCore PoolPair), in NormalizedImageFrame — frame(pool) === NormalizedImageFrame.

  • problem::Symbol: :E, :F or :H (E and F pools store FundMat, H pools HomographyMat).

  • scene::String: the scene the file holds.

  • scene_names::Vector{String}: each pair's source-scene label (a raw reader's pair_scene, else scene).

  • pool_key::String: pool_key(pairs), computed at construction.

  • stamps::NamedTuple: gt_convention, pool_rng, julia_version, total_samples, total_solutions, mean_solutions_per_sample, provenance (a Dict{String,Any} of plain values).

    ScoringPool(pairs, problem, scene; scene_names, stamps)

builds one from records and computes its key; the model class must be the problem's.

source
VisualGeometryToolkitEval.Pools.derive_sample_starts — Method
derive_sample_starts(pool::ScoringPool, stream; max_trials = 10^7) -> Vector{Vector{Int}}

The exact sample_starts of pool by REPLAYING each pair's seeded draw stream: stream(i) returns a zero-argument function yielding the next minimal sample (an AbstractVector{Int}, the sampler's own order) that pair i's generator drew, every trial included. For each run of identical columns the replay counts the draws of that sample before the next stored sample is drawn; the last run of a pair (nothing follows it in the stream) takes its structural count. Every pair's result must be admissible for the record and the total must equal the total_samples stamp, or an ArgumentError names what failed. Pairs are replayed under Threads.@threads.

Only the pool's own generator knows its stream; the caller supplies it (seed, sampler and stream index).

source
VisualGeometryToolkitEval.Pools.export_pixel_inputs — Method
export_pixel_inputs(path, pool, idx; scene = pool.scene, created = string(Dates.now())) -> path

Write the raw-pixel inputs of the pairs idx (strictly increasing pool indices) of pool to the JLD2 file path, in the layout the external estimators' workers read: per pair matches (an N×4 [x₁ y₁ x₂ y₂] matrix of pixel correspondences, back through the record's own maps, VisualGeometryToolkitCore.Pools.pixel_correspondences), the stored Lowe ratios snn, the pixel calibrations K1 and K2 and the ground-truth R_gt and t_gt; plus scene, n_pairs, pair_indices, pool_size, the pool_key the slice was read from, a provenance string and created. The parent directory is created and an existing file is overwritten. A pair without stored Lowe ratios (snn === nothing) is an ArgumentError naming it — the external baselines need them — and nothing is written; a pair without correspondences exports a 0×4 matches.

source
VisualGeometryToolkitEval.Pools.frame — Method
frame(pool::ScoringPool) -> Type{NormalizedImageFrame}

The frame a pool's data is stored in: NormalizedImageFrame (image centre, half diagonal, corners at unit radius), per view through each record's maps.

source
VisualGeometryToolkitEval.Pools.load_pool — Method
load_pool(path) -> ScoringPool

The reader of a light pool file (save_pool is the format). Refuses, with an ArgumentError naming the file: another pool_format (an older pool is migrated, never read: the error says how — migrate_pool for a format-4 or -5 file), missing or unknown keys, a frame other than NormalizedImageFrame, a ground-truth convention other than GT_CONVENTION, a model class that is not the problem's, and a stored pool_key that the loaded pairs do not reproduce.

source
VisualGeometryToolkitEval.Pools.load_pool_residuals — Method
load_pool_residuals(path, pool::ScoringPool; pairs = nothing) -> PoolResiduals

The reader of a residuals file (save_pool_residuals is the format), checked against the light pool it serves: refused (an ArgumentError naming the file) unless its pool_key is the pool's — the error names both keys — and it holds one matrix per pair, each (num_points, num_models) of that pair.

pairs (pool indices) reads only those pairs' matrices, sliced from the file without reading the rest; residual_matrix still takes pool indices.

source
VisualGeometryToolkitEval.Pools.load_sample_starts — Method
load_sample_starts(path, pool::ScoringPool) -> Vector{Vector{Int}}

The reader of a sample-starts file (save_sample_starts is the format), checked against pool: refused (an ArgumentError naming the file) unless its pool_key is the pool's, every pair's starts are admissible for its record and their total is the total_samples stamp.

source
VisualGeometryToolkitEval.Pools.migrate_pool — Method
migrate_pool(path; out, dry_run = false) -> NamedTuple

Carry a format-4 or -5 light pool file over to format 6, whose pair keys for the destination map and the correspondences are destination_map and correspondences. The format-6 file goes to joinpath(out, basename(path)); out must be another directory than the original's, which is never touched. The pool's residuals file (residuals_path), when present, is copied beside it unchanged: it is bound to the pool by pool_key, which hashes no map, so it stays valid. A sample-starts file (save_sample_starts) is NOT copied: it is derived data kept in a writable tree, never beside the pool, so the pool's path does not name it; it is bound by the same unchanged pool_key and reads against the migrated pool where it is. Both destinations, the pool's and its residuals', are checked before anything is written: an existing one is an ArgumentError, and a migration that fails leaves out as it was: a residuals file already renamed into it is removed, and so is an out the migration created.

The migration is verified before anything is written to out: the format-6 file, written through save_pool to a staging directory beside out (a dry run's: a temporary one), must read back through load_pool's checks, hold the same keys, and store every value of the original bit for bit; only then are the residuals copy and the pool renamed into out, the pool last. With dry_run nothing is written. A file of another format is refused with an ArgumentError: a format-6 one needs nothing, an older one is converted first (see load_pool's refusal). Returns (; path, residuals, n_pairs), the output paths nothing in a dry run.

source
VisualGeometryToolkitEval.Pools.pool_key — Method
pool_key(pairs) -> String

The content key of a pool: the lower-case hex SHA-256 of, for each pair in order,

  1. n = num_points(pair) and m = num_models(pair), each an Int64;
  2. the correspondences as the stored (4, n)Float64 matrix (rows x₁ y₁ x₂ y₂, column-major);
  3. the models, each its 9 Float64 entries column-major;
  4. size(sample_indices, 1) as an Int64, then sample_indices (Int64, column-major);

every number little-endian. These are exactly the quantities that index a residual matrix's rows and columns, so a residuals file written for other models, another pair order or other correspondences carries another key and is refused (load_pool_residuals). The residuals themselves are never read to compute it.

source
VisualGeometryToolkitEval.Pools.pool_size — Method
pool_size(path) -> Int

The number of pairs in a light pool file — length(load_pool(path)) — read from its header (one per-pair key) without loading the pairs. The file's pool_format is checked as load_pool checks it (another format is an ArgumentError naming the file); the pairs themselves are not.

source
VisualGeometryToolkitEval.Pools.residual_matrix — Method
residual_matrix(res::PoolResiduals, i) -> Matrix{Float32}

Pool pair i's residual matrix, (num_points, num_models). i is the pair's index in its POOL, also for residuals read for a subset; a pair that was not read is refused.

source
VisualGeometryToolkitEval.Pools.sample_starts — Method
sample_starts(pool::ScoringPool; derived = nothing) -> Vector{Vector{Int}}

The minimal-sample boundaries of every pair of pool: starts[i] holds the first model column of each minimal sample of pair i, in draw order, so pair i's sample s owns columns starts[i][s]:(starts[i][s+1] - 1) (the last sample runs to num_models). sample_ids turns them into a per-model sample number. Every count of minimal samples in the stack goes through this function.

Sibling solutions of one draw share a sample_indices column, and a REPEATED draw of the same sample stores the same column again, adjacent when no other sample was accepted in between. A run of identical columns therefore holds r draws, each storing the same block of siblings (a solve is deterministic): the record admits every r whose block repeats. Without derived, each run takes its largest admissible r, and the result is CERTIFIED: its total must equal the pool's total_samples stamp. Since every run's choice is an upper bound on its true draw count, equal totals make every run exact; a mismatch (a solve that returned a duplicated root) is an ArgumentError.

derived is the path of a sample-starts file of this pool (derive_sample_starts, save_sample_starts), read and checked by load_sample_starts instead.

source
VisualGeometryToolkitEval.Pools.save_pnp_pool — Method
save_pnp_pool(path, pools, misses; score) -> path

The writer of a PnP pool file (artifact kind :pnp_pool, format 2), JLD2, plain data:

keymeaning
pnp_pool_format2
frame"ImageFrame" — the 2-D observations are pixels
poolsper-query plain records: name, camera_model, width, height, camera_params, u (n×2 px), X (n×3), snn, p3d, nobs [+ gt_R, gt_t, gt_variance (px², NaN: untrusted)]
missesthe listed queries with no pool
scorewhat snn holds: "snn" (raw Lowe ratio), "one_minus_lg" or "none"
source
VisualGeometryToolkitEval.Pools.save_pool — Method
save_pool(path, pool::ScoringPool) -> path

The writer of a light pool file (artifact kind :pool, format 6). The file is JLD2 and holds PLAIN data only — no VisualGeometryToolkitCore type:

keytypemeaning
pool_formatInt6
problemString"E", "F" or "H"
sceneStringthe scene the file holds
model_classString"FundMat" (E, F) or "HomographyMat" (H)
frameString"NormalizedImageFrame"
gt_conventionString"extrinsic" (x₂ = R·x₁ + t, source → target)
pool_keyStringpool_key of the pairs (hex SHA-256)
scene_namesVector{String}per-pair source-scene label
pool_rngStringRNG algorithm of the pool streams ("LehmerRNG", the type of StableRNGs' StableRNG)
julia_versionStringthe Julia that generated the pool
total_samples, total_solutionsIntaccepted minimal samples and real solutions over the scene
mean_solutions_per_sampleFloat64their ratio (0 when no sample)
provenanceDict{String,Any}the generating run's record (plain values)
pairsVector of NamedTuplesone per pair, below

Each pair is a NamedTuple with exactly these fields (n correspondences, m models, s the minimal sample size), every point datum and model in NormalizedImageFrame:

fieldtypemeaning
correspondencesMatrix{Float64} (4, n)rows x₁ y₁ x₂ y₂
K1, K2SMatrix{3,3,Float64,9}PIXEL calibrations
R_gtSMatrix{3,3,Float64,9}GT rotation, source → target
t_gtSVector{3,Float64}GT translation (unnormalized)
modelsVector{SMatrix{3,3,Float64,9}} (m)pool-frame model matrices of class model_class
sample_indicesMatrix{Int} (s, m)1-based minimal sample of each model
errors_r, errors_tVector{Float64} (m)rotation / translation error [deg] vs GT
gt_inliersBitVector (n)GT inlier mask
gt_varianceFloat64σ̂² in pool units² (NaN: none)
source_map, destination_mapSMatrix{3,3,Float64,9}pixel → NormalizedImageFrame affine maps (last row [0 0 1])
snnVector{Float32} (n) or nothingper-correspondence SNN the hypotheses were sampled by

The residual matrices are a separate file (save_pool_residuals).

source
VisualGeometryToolkitEval.Pools.save_pool_residuals — Method
save_pool_residuals(path, res::PoolResiduals) -> path

The writer of a residuals file (artifact kind :pool_residuals, format 1), JLD2, PLAIN data only:

keytypemeaning
pool_residuals_formatInt1
pool_keyStringthe pool_key of the light file it belongs to
residual_kindString"sampson" (F, H) or "tangent_sampson" (E)
residualsVector{Matrix{Float32}}per pair, (n, m): `

By convention the file of <scene>.jld2 is <scene>.residuals.jld2 (residuals_path).

source
VisualGeometryToolkitEval.Pools.save_sample_starts — Method
save_sample_starts(path, pool::ScoringPool, starts; derivation, provenance = Dict()) -> path

The writer of a sample-starts file (artifact kind :pool_samples, format 1), JLD2, plain data: pool_key (the pool it belongs to), scene, total_samples, starts (Vector{Vector{Int}}, per pair, as sample_starts returns them), derivation (how they were obtained, e.g. the replayed stream) and provenance. The starts are checked admissible and certified against the stamp before writing. It is DERIVED data: it lives in a writable tree, never beside the pool it describes (pool trees are inputs).

source
VisualGeometryToolkitEval.Pools.scene_loaders — Method
scene_loaders(pool_dir, scenes; residuals = false) -> Vector{Function}

Zero-argument scene loaders over <pool_dir>/<scene>.jld2 — the loader constructor shared by every streaming driver. Each returns every pair of its scene (a subset is a cross-validation's units, Tuning validation_units / test_units, never a prefix): the ScoringPool, or with residuals = true the tuple (pool, residuals::PoolResiduals) read from <scene>.residuals.jld2 and checked against it.

source
VisualGeometryToolkitEval.Pools.synthetic_e_pool_pair — Function
synthetic_e_pool_pair(rng = MersenneTwister(7); n = 30, sibling_counts = vcat([2, 2], fill(1, 23)),
                      noise = 0.0, δ_rot = 0.1, t_jitter = 0.05, gt_variance = 1.0e-4)
    -> (pair::PoolPair{FundMat{Float64}}, residuals::Matrix{Float32})

A calibrated two-view pool pair in the pool frame (K = I, identity maps): n correspondences of points 3–5 units ahead under the fixed GT motion (rotation 0.15 rad about y, unit translation along (0.8, 0.1, 0.3)), target coordinates jittered by noise·N(0, 1) when noise > 0. One minimal sample (5 indices) per entry of sibling_counts, carrying that many sibling models: each the GT rotated by U(−δrot/2, δrot/2) about z, the translation jittered by t_jitter·N(0, I₃) and renormalized. Every model's optimistic (Δr, Δt), all-inlier GT and the stated gt_variance; the residual matrix holds every model's Sampson distances.

source
VisualGeometryToolkitEval.Pools.write_scene_pool — Method
write_scene_pool(path, raws, build; problem, residual_kind, seed,
                 skip_existing = true, provenance = Dict{String,Any}(),
                 scene = <basename of path>) -> path | nothing

Build one scene's pool from its raw pairs raws (VisualGeometryToolkitCore StereoRawPairs, in pixels) and write it: the light file path (save_pool) and its residuals (save_pool_residuals at residuals_path(path)).

build(rng, raw) builds one pair and returns either nothing — the pair is refused (e.g. fewer correspondences than the problem's minimal sample) and dropped — or a NamedTuple (; pair::PoolPair, residuals::Matrix{Float32}, samples::Integer, solutions::Integer): the record, its (num_points, num_models) residual matrix, and the accepted minimal samples and real solutions its draw counted. Pair i of raws draws from its OWN stream StableRNG(stable_seed(seed, i)) (StableRNGs, fixed across Julia versions) — keyed by its index in raws, not by the thread — so the pool is a pure function of (seed, raws), independent of thread count, scheduling and Julia version. Pairs are built under Threads.@threads.

problem (:E, :F, :H) and residual_kind (:sampson | :tangent_sampson, what build's matrices hold) are stamped into the files, with the scene, the per-pair pair_scene labels (else scene), the sample and solution totals, pool_rng, the Julia version and the caller's provenance. With skip_existing (the default: a pool is hours of compute) a scene whose two files both exist is skipped. Returns path, or nothing when no pair survives.

source

Internals

These names are not public; they are listed for contributors.