API: Pools
Scoring-pool input and output.
Public names
VisualGeometryToolkitEval.Pools — Module
PoolsScoring-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.
VisualGeometryToolkitEval.Pools.GT_CONVENTION — Constant
The ground-truth pose convention every pool declares (gt_convention): the extrinsic relative pose x₂ = R·x₁ + t, source → target.
VisualGeometryToolkitEval.Pools.PoolResiduals — Type
PoolResidualsThe residual matrices of a pool, bound to its light file by pool_key.
Fields:
pool_key::String: thepool_keyof 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|inNormalizedImageFrameunits.pairs::Vector{Int}: the pool indices of the held pairs, in the order ofmatrices— every pair (1:n) unless the residuals were read for a subset (load_pool_residuals(path, pool; pairs)).
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 (VisualGeometryToolkitCorePoolPair), inNormalizedImageFrame—frame(pool) === NormalizedImageFrame.problem::Symbol::E,:For:H(E and F pools storeFundMat, H poolsHomographyMat).scene::String: the scene the file holds.scene_names::Vector{String}: each pair's source-scene label (a raw reader'spair_scene, elsescene).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(aDict{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.
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).
VisualGeometryToolkitEval.Pools.export_pixel_inputs — Method
export_pixel_inputs(path, pool, idx; scene = pool.scene, created = string(Dates.now())) -> pathWrite 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.
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.
VisualGeometryToolkitEval.Pools.load_pnp_pool — Method
load_pnp_pool(path) -> (; pools, misses, score)The reader of a PnP pool file (save_pnp_pool is the format): refuses another pnp_pool_format and a frame other than ImageFrame.
VisualGeometryToolkitEval.Pools.load_pool — Method
load_pool(path) -> ScoringPoolThe 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.
VisualGeometryToolkitEval.Pools.load_pool_residuals — Method
load_pool_residuals(path, pool::ScoringPool; pairs = nothing) -> PoolResidualsThe 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.
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.
VisualGeometryToolkitEval.Pools.migrate_pool — Method
migrate_pool(path; out, dry_run = false) -> NamedTupleCarry 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.
VisualGeometryToolkitEval.Pools.pool_key — Method
pool_key(pairs) -> StringThe content key of a pool: the lower-case hex SHA-256 of, for each pair in order,
n = num_points(pair)andm = num_models(pair), each anInt64;- the correspondences as the stored
(4, n)Float64matrix (rowsx₁ y₁ x₂ y₂, column-major); - the models, each its 9
Float64entries column-major; size(sample_indices, 1)as anInt64, thensample_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.
VisualGeometryToolkitEval.Pools.pool_size — Method
pool_size(path) -> IntThe 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.
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.
VisualGeometryToolkitEval.Pools.residuals_path — Method
residuals_path(path) -> StringThe residuals file of the light pool file path: <scene>.jld2 → <scene>.residuals.jld2.
VisualGeometryToolkitEval.Pools.sample_ids — Method
sample_ids(starts, m) -> Vector{Int}The minimal-sample number (1, 2, …) of each of a pair's m models, from that pair's sample_startsstarts.
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.
VisualGeometryToolkitEval.Pools.save_pnp_pool — Method
save_pnp_pool(path, pools, misses; score) -> pathThe writer of a PnP pool file (artifact kind :pnp_pool, format 2), JLD2, plain data:
| key | meaning |
|---|---|
pnp_pool_format | 2 |
frame | "ImageFrame" — the 2-D observations are pixels |
pools | per-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)] |
misses | the listed queries with no pool |
score | what snn holds: "snn" (raw Lowe ratio), "one_minus_lg" or "none" |
VisualGeometryToolkitEval.Pools.save_pool — Method
save_pool(path, pool::ScoringPool) -> pathThe writer of a light pool file (artifact kind :pool, format 6). The file is JLD2 and holds PLAIN data only — no VisualGeometryToolkitCore type:
| key | type | meaning |
|---|---|---|
pool_format | Int | 6 |
problem | String | "E", "F" or "H" |
scene | String | the scene the file holds |
model_class | String | "FundMat" (E, F) or "HomographyMat" (H) |
frame | String | "NormalizedImageFrame" |
gt_convention | String | "extrinsic" (x₂ = R·x₁ + t, source → target) |
pool_key | String | pool_key of the pairs (hex SHA-256) |
scene_names | Vector{String} | per-pair source-scene label |
pool_rng | String | RNG algorithm of the pool streams ("LehmerRNG", the type of StableRNGs' StableRNG) |
julia_version | String | the Julia that generated the pool |
total_samples, total_solutions | Int | accepted minimal samples and real solutions over the scene |
mean_solutions_per_sample | Float64 | their ratio (0 when no sample) |
provenance | Dict{String,Any} | the generating run's record (plain values) |
pairs | Vector of NamedTuples | one 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:
| field | type | meaning |
|---|---|---|
correspondences | Matrix{Float64} (4, n) | rows x₁ y₁ x₂ y₂ |
K1, K2 | SMatrix{3,3,Float64,9} | PIXEL calibrations |
R_gt | SMatrix{3,3,Float64,9} | GT rotation, source → target |
t_gt | SVector{3,Float64} | GT translation (unnormalized) |
models | Vector{SMatrix{3,3,Float64,9}} (m) | pool-frame model matrices of class model_class |
sample_indices | Matrix{Int} (s, m) | 1-based minimal sample of each model |
errors_r, errors_t | Vector{Float64} (m) | rotation / translation error [deg] vs GT |
gt_inliers | BitVector (n) | GT inlier mask |
gt_variance | Float64 | σ̂² in pool units² (NaN: none) |
source_map, destination_map | SMatrix{3,3,Float64,9} | pixel → NormalizedImageFrame affine maps (last row [0 0 1]) |
snn | Vector{Float32} (n) or nothing | per-correspondence SNN the hypotheses were sampled by |
The residual matrices are a separate file (save_pool_residuals).
VisualGeometryToolkitEval.Pools.save_pool_residuals — Method
save_pool_residuals(path, res::PoolResiduals) -> pathThe writer of a residuals file (artifact kind :pool_residuals, format 1), JLD2, PLAIN data only:
| key | type | meaning |
|---|---|---|
pool_residuals_format | Int | 1 |
pool_key | String | the pool_key of the light file it belongs to |
residual_kind | String | "sampson" (F, H) or "tangent_sampson" (E) |
residuals | Vector{Matrix{Float32}} | per pair, (n, m): ` |
By convention the file of <scene>.jld2 is <scene>.residuals.jld2 (residuals_path).
VisualGeometryToolkitEval.Pools.save_sample_starts — Method
save_sample_starts(path, pool::ScoringPool, starts; derivation, provenance = Dict()) -> pathThe 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).
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.
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.
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 | nothingBuild 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.
Internals
These names are not public; they are listed for contributors.