RANSAC
Main Function
VisualGeometryToolkitEstimation.ransac — Function
ransac(problem, scoring; local_optimization_strategy, config, workspace, rng) -> RansacEstimateRANSAC on VisualGeometryToolkitCore's scoring and local-optimization contracts: the loop calls only the contract verbs, so any scorer composes with any local optimizer and any problem. The allocating convenience of ransac! (fresh result buffers, and a fresh workspace unless one is supplied).
For each minimal sample, fits θₜ, scores it, and takes the scorer's consensus set. Two independent best-so-far scores are maintained: Sgl gates entry into local optimization; Slo tracks the best locally optimized score. The adaptive trial count uses the hypergeometric distribution (the stopping criterion).
Arguments
problem::AbstractRansacProblem: Problem definition (data, solver, residuals)scoring::AbstractScoring: any scorer of the contract — VisualGeometryToolkitCore'sMsacScoring/RansacScoringat a threshold, or a scorer from another package (a paper's: RANSACScoringDoneRight's Student-t + uniform marginal)
Keyword Arguments
local_optimization_strategy::Union{Nothing, AbstractOptimizationStrategy}=default_local_optimization_strategy(scoring): the LO-RANSAC refinement strategy (defaultnothing, no local optimization); dispatched in the loop's Phase 2 vialocally_optimize!, or — aTerminalLO(lo_placement) — once on the final incumbent of a raw raceconfig::RansacConfig=RansacConfig(): maxtrials, successprob η, min_trialsworkspace::Union{Nothing,RansacWorkspace}=nothing: Pre-allocated workspacerng::Random.AbstractRNG=Random.default_rng(): source of every random draw the loop makes (sample selection throughdraw_sample!). Supply a seeded rng (e.g.Xoshiro(seed)) for a bit-reproducible run that is independent of ambient RNG state; the default preserves the historical task-local behavior.on_improvement=nothing: optional anytime-trace hook, called ason_improvement(trial::Int, score, ws::RansacWorkspace)exactly when the tracked best (the acceptance that also re-arms the adaptive trial count) is replaced — readws.best_model/ws.best_lo_retcode(andws.best_lo_stop_rule) inside the callback. Improvements are rare (≈ log-many per run), so a cheap callback keeps overhead negligible;nothing(production default) is specialized away at compile time.score_guard::Bool=false: per-candidate ScoreGuarded acceptance — the in-loop analogue oflocally_optimize(...; score_guard=true)(the review-requested LO-RANSAC score-monotone variant). When the refined model of a gate-satisfying candidate scores BELOW its own seed under the same scorer, the candidate re-enters the incumbent race as the RAW hypothesis (at its Phase-1 score) instead of the refined model; the race itself stays the standard monotone best-so-far comparison. A raw hypothesis kept this way records its refit's code with the ruleSeedKept(lo_retcode,lo_stop_rule) on the result.
Returns
A RansacEstimate; iterations(result) is the number of trials (hypotheses drawn). Why the loop ended is its termination record (retcode(result), stop_rule(result); the table on RansacMetadata): the adaptive count drawn (ReturnCode.Success, AdaptiveCount), every sample of an exhaustive sampler (Success, TrialBudget), or max_trials drawn without reaching the confidence (ReturnCode.MaxIters, TrialBudget: not converged, but a model was found; a confidence count equal to max_trials was reached at the cap: AdaptiveCount). Test VisualGeometryToolkitCore's found_model(result) before reading the model: found_model(result) == false (retcode(result) == ReturnCode.Failure) means NO hypothesis survived — there is no estimate: its estimate is nothing (with quality = -Inf, all-zero weights — an all-false inlier_mask(result) —, rms NaN and a ScaleNone scale).
Examples
result = ransac(problem, MsacScoring(problem; threshold = 2.0); local_optimization_strategy = Irls{TLSShape}())VisualGeometryToolkitEstimation.ransac! — Function
ransac!(result::RansacResultBuffers, ws::RansacWorkspace, problem, scoring;
local_optimization_strategy, config, on_improvement, on_hypothesis, score_guard, rng) -> RansacEstimateThe zero-allocation form of ransac: RANSAC on the preallocated workspace ws (trimmed to the problem's data size), its result written into the preallocated result buffers — the returned estimate's residuals and weights ARE those buffers.
VisualGeometryToolkitEstimation.locally_optimize — Function
locally_optimize(problem, θ₀; local_optimization_strategy, scoring,
workspace=nothing, score_guard=false) -> RansacEstimateRefine a caller-supplied seed model θ₀ with one local-optimization run — the same score → locally_optimize! → re-score → test_consensus → _finalize machinery a RANSAC trial runs in _try_model!, driven by θ₀ instead of a minimal sample (no draw_sample!, no consensus search). Generic over the problem type. local_optimization_strategy is REQUIRED (no default: the strategy is the experiment's decision; the settled formulations live in the find_* pipelines). If the refined model fails test_consensus the seed is returned. scoring is REQUIRED too (a scorer object: MSAC or RANSAC at its threshold, MsacScoring(problem; threshold); the Student-t + uniform scorer at its outlier half-width, StudentTUniformScoring(problem, outlier_halfwidth; …); …): there is no class here to default it from, and a bare threshold or outlier_halfwidth keyword is refused (ArgumentError, naming scoring). When score_guard=true the refined model is only accepted if it does not lower the seed's score (the seed is kept otherwise).
The local optimizer receives its loss width through its width mode (VGC loss_at): a consensus-anchored strategy (EfficiencyConstant(m)) reads the consensus set's ŝ², an absolute one (LossWidth, see with_width) runs at the caller's width with the scoring untouched — the role-isolated validation controls (solo CV, oracle-scale) deploy the strategy that way — and a strategy with no width follows the scorer's decision_boundary.
locally_optimize(problem, models::FixedModels; local_optimization_strategy,
scoring, workspace=nothing) -> RansacEstimateEntry for solvers that return several candidate models (e.g. the two planar-pose ambiguity solutions). Each candidate is scored against the consensus set; the single highest-scoring one that succeeds at test_consensus is kept, and only that one is locally optimized. The candidates are never all optimized — selection is by consensus score, optimization is on the winner alone. Returns a result with no model (found_model false, ReturnCode.Failure) if no candidate clears consensus. The winner's termination record is the selection's (Success, ClosedForm), or — when its refined model is kept — its local optimization's (as in the single-seed method). scoring is required, as in the single-seed method.
Problem Interface
VisualGeometryToolkitEstimation.AbstractRansacProblem — Type
AbstractRansacProblemAbstract type for RANSAC problem definitions.
A concrete subtype encapsulates the data, sampling strategy, minimal solver, and constraint derivatives for a specific estimation task.
Required Methods
minimal_sample_size(p)::Int— minimum data points for a minimal solvedata_size(p)::Int— total number of data pointscodimension(p)::Int— constraint codimension d_gmodel_type(::Type{<:P})::Type— concrete model typeM(for workspace pre-allocation; defined on the TYPE, soRansacWorkspace(P, n)can read it)solve(p, indices)— fit model(s) from sample indices; returnsFixedModels{N,M}withcount∈ 0..N (0 means failure)constraint_with_jacobians(p, model, i)—(g, ∂ₓg, ∂_θg)at data pointi
Derived Automatically
mahalanobis_distances!(r, p, model)— Mahalanobis distance√(gᵀ Σ̃_g⁻¹ g)fromconstraint_with_jacobians
Optional Methods
draw_sample!(rng, indices, p)— custom sampling (default: uniform without replacement)test_sample(p, indices)— degeneracy check (default:true)test_model(p, model, indices)— feasibility check at sample points (default:true)test_consensus(p, model, mask)— consensus set validation (default:true)refine!(ws, p, θ, weights)— the local optimization's one weighted step from the current model θ (default:nothing)solver_covariance(p, model, indices)+provides_solver_covariance(::Type{<:P}) = true— model parameter covariance for predictive scoring;nothingfor a degenerate sample (the hypothesis is skipped). A problem without a provider is refused by a predictive scorer.mahalanobis_distances!(r, p, model)— override the default if a faster batch implementation exists
Example
struct MyLineProblem <: AbstractRansacProblem
points::Vector{SVector{2,Float64}}
end
minimal_sample_size(::MyLineProblem) = 2
data_size(p::MyLineProblem) = length(p.points)
codimension(::MyLineProblem) = 1
model_type(::Type{MyLineProblem}) = SVector{2,Float64} # (a, b) for y = a + bx
function solve(p::MyLineProblem, idx)
p1, p2 = p.points[idx[1]], p.points[idx[2]]
b = (p2[2] - p1[2]) / (p2[1] - p1[1])
a = p1[2] - b * p1[1]
model = SVector(a, b)
FixedModels{1, typeof(model)}(1, (model,))
end
@inline function constraint_with_jacobians(p::MyLineProblem, model, i)
pt = p.points[i]; a, b = model
g = pt[2] - a - b * pt[1] # scalar constraint
∂ₓg = SA[one(eltype(pt))] # ∂g/∂y = 1 (only y has noise)
∂_θg = SA[-one(eltype(pt)), -pt[1]] # ∂g/∂(a,b)
return (g, ∂ₓg, ∂_θg)
endVisualGeometryToolkitEstimation.AbstractCorrespondenceProblem — Type
AbstractCorrespondenceProblem{K} <: AbstractRansacProblem{K}Base type for RANSAC problems defined by correspondences.
Subtypes must have fields cs (a correspondence container satisfying the sources/targets protocol) and _sampler (an AbstractSampler). Provides default implementations of data_size(p) = length(p.cs) and sampler(p) = p._sampler.
VisualGeometryToolkitEstimation.MinimalSolveProblem — Type
MinimalSolveProblem{M, K, T, ...} <: AbstractCorrespondenceProblem{K}The one parametric correspondence problem behind HomographyProblem, FundMatProblem, EssentialProblem and AbsolutePoseProblem, which are partial applications of it: M is the model type, K the minimal sample size and T the scalar type. The model type selects the per-model behaviour (codimension, minimal solver, residual whitening). The problem holds the correspondences in the caller's frame, its private normalization, the minimal solver, the sampler and, for absolute pose, a PoseContext. Construct one through its aliases.
VisualGeometryToolkitEstimation.PoseContext — Type
PoseContext{F}Absolute-pose problem context: the backprojected unit ray directions (one per correspondence, precomputed at construction) and the imaging transform used by the pixel-reprojection residuals.
VisualGeometryToolkitCore.minimal_sample_size — Function
minimal_sample_size(problem::AbstractRansacProblem{K}) -> KReturn the minimum number of data points needed for a minimal solve. Derived from the type parameter K of AbstractRansacProblem{K}.
E.g., 2 for line fitting, 4 for homography, 7 for fundamental matrix.
VisualGeometryToolkitCore.solve — Function
solve(p::HandEyeProblem, idx) -> FixedModels{1, Rigid3}Closed-form Tsai-Lenz solver on the two minimal-sample relative motions. Returns FixedModels{1, Rigid3} with count = 0 (no valid solution) or count = 1.
VisualGeometryToolkitEstimation.fit_hypothesis — Function
fit_hypothesis(problem, θ, sample_indices) -> model | nothingThe hypothesis a minimal sample contributes, given a minimal solution θ of it (solve). For a problem whose minimal sample exactly determines the model this is θ itself (the default). A problem whose minimal sample OVER-determines it (hand-eye: two motions, 12 rows for 6 dof) fits the sample, seeded by θ, so the hypothesis is the sample's least-squares model — the estimator its solver_covariance describes. solve stays the pure minimal solver; nothing skips the hypothesis, as a failed solve does.
VisualGeometryToolkitCore.test_sample — Function
test_sample(problem::AbstractRansacProblem, indices::AbstractVector{Int}) -> BoolCheck whether a sample is non-degenerate (e.g., points not collinear).
Default: true (no degeneracy check). Override for problem-specific checks.
test_sample(p::AbsolutePoseProblem, idx) -> BoolReject degenerate P3P minimal samples. Four checks, distinctness and collinearity in each of the two spaces:
- world: the 3 control points distinct (
_P3P_COINCIDENT_WORLD= 1e-3 in the problem's world unit: 1 mm for physical input, whichfind_absolute_posestrips in metres, and 1e-3 of the caller's own unit for plain input — 1 μm for plain millimetres; the two forms of one millimetre dataset can therefore reject different samples, but only samples with two control points within 1 mm, which a fixture spread over metres never draws) and non-collinear (thin_ratio>_P3P_DEGENERACY_TOL). Collinear control points ⇒ no unique P3P solution; this one earns its place. - image: the 3 image points distinct (
_P3P_COINCIDENT_IMAGE, pixels) and their RAYS not coplanar (thinness >_P3P_DEGENERACY_TOL). P3P degenerates when the three rays lie in one plane through the centre. For aPinholethat is exactly collinear pixels (the pixel plane is an affine image of the z = 1 chart), so the test isthin_ratioon the pixels, as it always was. For a DISTORTING lens it is not: a line of rays images as a curve, so pixel collinearity admitted coplanar rays and rejected well-spread rim rays that the lens had pulled into a line. There the test is_ray_thin_ratioon the context's back-projected rays —thin_ratioin the gnomonic chart tangent at their mean direction.
The image DISTINCTNESS check guards a premise that does not reproduce
It used to be justified here as "two detections at ~the same pixel (distinct world points projecting together) force a grazing, near-degenerate pose". That was constructed, not measured, and the experiment does not support it. Sweeping image separation for two genuinely distinct world points (common ray, ≥0.5 world units apart): noise-free, median error stays at 0° and q95 under 6e-5° from 0 px to 40 px; at σ = 0.5 px, the median is 0.181° at EVERY separation from 0 to 150 px, q95 0.655–0.702°, with no failure to return a solution.
Flat at both noise levels including at separation zero, which is geometrically sensible: two world points at different depths along one ray is a well-posed P3P configuration. The second point adds no independent constraint, but the remaining correspondences still determine the pose. Two points projecting together is not by itself a degeneracy.
It is also UNREACHABLE. A near-duplicate pair makes every triangle through it thin, so the image collinearity check rejects first: measured, at any separation small enough for the distinctness check to fire (<1e-3 px) the image thin_ratio is already 3.1e-5, far under its 1e-2 bound; at 0.2 px, where thin_ratio is healthy at 0.0125, distinctness admits. There is no separation at which the image distinctness verdict decides anything.
So it is redundant against a premise that does not reproduce — vestigial, or guarding a configuration nobody has constructed. Note that "a nearly-collinear triple produces a grazing pose" is NOT the missing case: that is exactly what thin_ratio(u…) tests, one line below.
The tolerance was deliberately NOT raised. At 1e-3 px — sixty times below VisualGeometryToolkitFeatures' pinned 0.06 px worst-case refinement bound — its measured duplicate capture is 0%, flat across spreads. That is the same symptom B7 fixed for F, E and H but a different disease: those were frame-COUPLED, their threshold moving with the data's spread, while this one is correctly framed in pixels and simply too small. Raising it would make a dead gate live across six repos on an unreproduced premise. If it is ever revisited, do NOT borrow COINCIDENT_PX: 0.1 px answers "is this the same detection twice?", anchored on a refinement bound, and this check asks a different question — the constant does not transfer even though the units match.
What would settle it is a construction that produces the failure, or a decision that it is vestigial. Not a threshold.
Mirrors test_sample(::HomographyProblem, …), which had the same structure: its coincidence check sat inoperative while _not_collinear caught duplicates incidentally.
test_sample(p, idx) -> BoolReject the minimal sample when its two rig motions have nearly parallel rotation axes, which ill-conditions X. (Every motion already rotates at least p.min_rel_angle — the constructor's gate.)
VisualGeometryToolkitCore.test_model — Function
test_model(problem::AbstractRansacProblem, model, sample_indices::AbstractVector{Int}) -> BoolCheck whether a fitted model is feasible (e.g., positive focal length, non-degenerate local geometry at the sample points).
The sample_indices are the minimal sample indices used to fit the model, enabling point-specific validation (e.g., Jacobian determinant bounds at sample locations).
Default: true (no feasibility check). Override for problem-specific checks.
VisualGeometryToolkitCore.test_consensus — Function
test_consensus(problem::AbstractRansacProblem, model, mask::BitVector) -> BoolValidate a model against its consensus (inlier) set. Called after scoring and mask computation, before accepting a candidate as the new best model.
Use this for checks that require the inlier set, e.g., the oriented epipolar constraint for fundamental matrices. The mask is a BitVector where true entries are classified inliers.
Default: true (no consensus check). Override for problem-specific checks.
VisualGeometryToolkitEstimation.draw_sample! — Function
draw_sample!(rng::Random.AbstractRNG, indices::AbstractVector{Int},
problem::AbstractRansacProblem)Fill indices with a random sample of data point indices (without replacement), drawn from rng.
Default: delegates to draw!(rng, indices, sampler(problem)). Problems with a stored sampler just need to define sampler(p::MyProblem) = p._sampler. The rng-leading form is the only form, and a problem overriding draw_sample! must define it: routing every draw through an explicit rng is what makes a seeded ransac(...; rng = Xoshiro(seed)) run bit-reproducible, and what keeps a threaded caller off the task-local Random.default_rng().
VisualGeometryToolkitCore.constraint_with_jacobians — Function
constraint_with_jacobians(p::HandEyeProblem, X::Rigid3, i::Int)
-> (g::SVector{6}, ∂ₓg::SMatrix{6,6}, ∂_θg::SMatrix{6,6})Decoupled SE(3) hand-eye constraint and its derivatives.
For motion pair (A_ij, B_ij) = p.motions[i]:
g = [ L · Log(R_A R_X R_B^T R_X^T)
R_A t_X + t_A − R_X t_B − t_X ] ∈ ℝ⁶(L = p.char_length, balancing rotation rad and translation length units.)
The model Jacobian ∂_θg uses the decoupled left-perturbation parameterization (δω, δt) ∈ ℝ⁶ matching AbsolutePoseProblem: RX ← R(δω) · RX, tX ← tX + δt. Under that convention, near the optimum:
∂_θg = [ L · (R_A − I) 0 ] ← rotation block
[ [R_X t_B]_× (R_A − I) ] ← translation blockThe observation Jacobian ∂ₓg = I_6 reports the noise model directly on the constraint (the per-pair 6-vector is already in unit-balanced form), so the default mahalanobis_distances! produces ‖g‖.
VisualGeometryToolkitCore.solver_covariance — Function
solver_covariance(p, θ, idx) -> SMatrix or nothingUNIT-SCALE covariance of the model θ from the constraint rows constraint_with_jacobians(p, θ, i), i ∈ idx: VGC's implicit_covariance, (AᵀW₀A)⁻¹·AᵀW₀·BΣₓBᵀ·W₀A·(AᵀW₀A)⁻¹ with the estimator's own whitening W₀ = blockdiag((BᵢΣ̃ₓBᵢᵀ)⁻¹). On a minimal sample (square) it is the implicit-function covariance of the minimal solve; on an overdetermined set (the local optimization's inlier set, a seed's consensus set) the covariance of the whitened-constraint estimator on it.
Coordinates are those of G_θ — vec(M) for H/F/E (the covariance of the minimal chart minimal_manifold(θ), propagated through its differential; rank ≤ its dof), the chart coordinates for the pose (LeftRigidManifold6), hand-eye (RigidExpManifold6) and line. Unit noise in the data frame the rows are in, so the MULTIPLICATIVE convention holds: physical Σ = s²·Σ̃, s profiled by the scale marginal. nothing for fewer points than a minimal sample or a singular system — a degenerate sample, skipped. Monte Carlo calibration: test/ransacmccalibration_tests.jl.
The rest of the problem protocol is VisualGeometryToolkitCore's, documented in its manual: data_size, refine! (the local-optimization step this package's problems implement), model_type, codimension, mahalanobis_distances!, provides_solver_covariance, test_conditioning and test_cheirality.
Solver + correspondence protocol
The minimal-solver and correspondence verbs the problem layer is built on are VisualGeometryToolkitCore's: MinimalSolver, RefitFamily, sources and targets.
Residual protocol
The per-point protocol that mahalanobis_distances! runs is VisualGeometryToolkitCore's (mahalanobis_distance(problem, ctx, i), the signed whitened_residual, residual_context); the residual degrees of freedom are this package's.
VisualGeometryToolkitEstimation.residual_dof — Function
residual_dof(problem_or_type, n_in::Int) -> IntResidual degrees of freedom on a fitted model with n_in inliers:
ν = (n_in − m) · d_gwhere m = minimal_sample_size(P) and d_g = codimension(P).
Single source of truth for the per-pair scale-estimate denominator σ̂²_p = RSS / ν and for the score-equation ν. Use this anywhere the residual DOF appears so that the model class drives the formula rather than scattered magic constants (which historically drifted: an earlier Union{E, F} σ̂²p dispatch hard-coded m = 5, biasing F-matrix σ̂²p down by factor (nin − 7)/(nin − 5)).
Returns 0 when n_in ≤ m so callers can ν > 0 || return NaN cleanly.
VisualGeometryToolkitEstimation.oracle_residual_dof — Function
oracle_residual_dof(problem_or_type, n::Int) -> IntResidual DOF when residuals are measured against an oracle model that was NOT fitted to these n points (e.g. the COLMAP ground-truth pose evaluated on a pair's SfM-track observations): no parameters are consumed, so
ν = n · d_g (vs `residual_dof`'s `(n − m)·d_g` for a *fitted* model)Use this for σ̂²p = RSS/ν under the GT geometry. Subtracting the model DOF (as a fit would) biases σ̂²p up by n/(n−m) — a DLT remnant, not warranted for the oracle.
Local-optimization result
RansacEstimate, RansacMetadata, RansacWorkspace and inlier_ratio are documented under "Result Types" and "Workspaces" below. The LO half of the result record is VisualGeometryToolkitCore's lo_estimate.
Solver Backends
The minimal-sample solver used by HomographyProblem, FundMatProblem, and AbsolutePoseProblem is selected by supplying a backend to the constructor:
using VisualGeometryToolkitCore: NativeSolver, PoseLibSolver
HomographyProblem(pairs; backend=NativeSolver()) # default — pure-Julia
HomographyProblem(pairs; backend=PoseLibSolver()) # PoseLib C++ bindingThe following names are defined and exported by VisualGeometryToolkitCore (RVG re-exports nothing; import them from there). See the VisualGeometryToolkitCore docs for their full API.
AbstractSolverBackend— abstract supertype for backendsNativeSolver— pure-Julia implementations ofhomography_4pt,fundamental_7pt,p3p, etc.PoseLibSolver— bindings to the PoseLib C++ libraryessential_5pt(x1, x2)— five-point essential matrix solver (native pure-Julia by default;essential_5pt(PoseLibSolver(), x1, x2)withusing PoseLib)essential_dlt(x1, x2)— eight-point essential matrix solver (PoseLib only)
Samplers
VisualGeometryToolkitEstimation.AbstractSampler — Type
AbstractSamplerAbstract type for RANSAC sampling strategies.
Subtypes implement draw! and reset! to provide different sampling behaviors (uniform, PROSAC, NAPSAC, etc.). Problems store a sampler as a type-parameterized field for compile-time dispatch.
Required Methods
draw!(rng::Random.AbstractRNG, indices::AbstractVector{Int}, sampler)— fill indices with a random sample drawn fromrng. Every random decision a sampler makes MUST go throughrng— this is what makes a seededransac(...; rng = Xoshiro(seed))run bit-reproducible. There is no two-argument form: the rng is named at every call site, so reaching for ambient task-local state stays visible in the source.reset!(sampler)— reset mutable state for reuse acrossransac()calls
Optional
reset!(sampler, budget::Int)— reset, and take the run's trial budget (ransacsuppliesconfig.max_trials). The default ignores the budget; PROSAC schedules its pool growth over it.trial_budget(sampler, config)/adapts(sampler)— the run's schedule: how many trialsransacallows, and whether the incumbent may shorten it. The defaults areconfig.max_trialsandtrue(adaptive RANSAC).
Built-in Samplers
UniformSampler: Stateless uniform random samplingProsacSampler: Progressive sampling from high-quality matchesGaussianSampler: Weighted sampling without replacementExhaustiveSampler: Every minimal sample exactly once, no adaptive stop
VisualGeometryToolkitEstimation.UniformSampler — Type
UniformSampler <: AbstractSamplerStateless uniform random sampling without replacement.
Stores the data size n for sampling from 1:n.
VisualGeometryToolkitEstimation.ProsacSampler — Type
ProsacSamplerMutable state for PROSAC progressive sampling.
Maintains a pool of correspondences sorted by quality score. Sampling starts from the top-m highest-scored matches and progressively expands the pool.
Fields
sorted_indices::AbstractVector{Int}— data indices sorted by score (best first)m::Int— sample size (constant, e.g. 4 for homography)N::Int— total data size (constant)T_N::Int— the trial budget the pool grows over;ransacsets it toconfig.max_trialswhen it prepares the samplern::Int— current pool size (grows from m to N)t::Int— current trial countT_n::Float64— current T_n value (recurrence relation)T_n_prime::Int— discretized cumulative threshold
See also: reset!, _draw_prosac!
VisualGeometryToolkitEstimation.GaussianSampler — Type
GaussianSampler <: AbstractSamplerWeighted sampling where each correspondence's weight is a Gaussian in its SNN score. Stateless (no progressive expansion). Matches Shekhovtsov's sample_subsets (RANSAC-Scoring functional.py:71).
Fields
weights::Vector{Float64}— precomputed normalized weightsinv_weights::Vector{Float64}— cached1.0 ./ weights(the Gumbel-Max exponent; caching skips n divisions per draw — bitwise identical keys)keys_buf::Vector{Float64}— scratch for Gumbel-Max keys (draw-local)perm_buf::Vector{Int}— scratch index vector for the top-k partial sortsort_scratch::Vector{Int}— quicksort scratch for the top-k partial sort
The three scratch buffers make draw! allocation-free (the hot RANSAC loop draws once per hypothesis); a GaussianSampler is therefore NOT safe to share across concurrent ransac() calls (one sampler per problem instance, which is how every constructor site builds it).
VisualGeometryToolkitEstimation.ExhaustiveSampler — Type
ExhaustiveSampler(n, k)Every k-subset of 1:n exactly once, in lexicographic order: binomial(n, k) draws, after which draw! throws an ArgumentError. Deterministic: the rng a draw! is handed is not used, so a run is the same under every seed.
Under ransac it draws exactly binomial(n, k) samples whatever the RansacConfig (trial_budget), and an incumbent never shortens the run (adapts): success_prob, max_trials and min_trials do not apply.
VisualGeometryToolkitEstimation.trial_budget — Function
trial_budget(sampler, config::RansacConfig) -> IntThe number of trials ransac starts out allowing. config.max_trials for a random sampler (the default); binomial(n, k), every sample, for the ExhaustiveSampler, whatever the config.
VisualGeometryToolkitEstimation.adapts — Function
adapts(sampler) -> BoolWhether ransac may shorten the run from the incumbent's consensus (the hypergeometric adaptive trial count). true for a random sampler (the default); false for the ExhaustiveSampler, whose run is every sample.
VisualGeometryToolkitEstimation.sampler — Function
sampler(problem::AbstractRansacProblem) -> AbstractSamplerReturn the sampler used by this problem.
Default: UniformSampler(data_size(p)). Override for problems with a stored sampler field:
sampler(p::MyProblem) = p._samplerVisualGeometryToolkitEstimation.draw! — Function
draw!(rng::Random.AbstractRNG, indices::AbstractVector{Int}, sampler::AbstractSampler) -> nothingFill indices with one minimal sample drawn by sampler, taking every random decision from rng. The sample's size is length(indices). A sampler with a schedule (PROSAC) advances it, and that state is RNG state in the sense of the stack's mutation rule. See AbstractSampler for the protocol.
VisualGeometryToolkitEstimation.reset! — Function
reset!(ps::ProsacSampler)Reset PROSAC sampler state for reuse (e.g., across multiple ransac() calls).
Validity regions
A problem can declare a region of validity, such as the image extent. The consensus check then counts only the points inside it.
VisualGeometryToolkitEstimation.BoundedProblem — Type
BoundedProblem(inner::AbstractRansacProblem, extent) -> BoundedProblemWrap an existing RANSAC problem with a known validity extent. The wrap forwards all RANSAC interface methods (solve, mahalanobis_distances!, test_sample, test_model, test_consensus, ...) to inner, but declares extent_trait(::BoundedProblem) = WithExtent(extent) so the post-IRLS extent-consensus check fires.
extent is typically a HyperRectangle{2} (board world-coords); support for other extent shapes can be added by defining more _check_extent(::WithExtent, p, model, mask) methods.
VisualGeometryToolkitEstimation.with_extent — Function
with_extent(problem, extent) -> problem or BoundedProblemThe extent keyword of a find_* pipeline (and of a caller's own locally_optimize) applied to problem: unchanged for extent = nothing, else BoundedProblem(problem, extent), whose extent_trait makes RANSAC's post-IRLS extent-consensus hook validate the fitted model over the region (the _check_extent method for the model class).
VisualGeometryToolkitEstimation.ExtentTrait — Type
ExtentTraitWhether a RANSAC problem declares a validity region: NoExtent (the default) or WithExtent. extent_trait returns a problem's trait, and BoundedProblem adds a region to any problem.
VisualGeometryToolkitEstimation.NoExtent — Type
NoExtent() <: ExtentTraitMarker that the problem has no associated validity region. The default for all problem types; consensus-extent checks short-circuit to true.
VisualGeometryToolkitEstimation.WithExtent — Type
WithExtent(extent) <: ExtentTraitMarker that the problem's fitted model is supposed to be a well-behaved mapping over extent. The post-IRLS consensus check then dispatches on (model, extent) to verify (e.g. for HomographyMat + HyperRectangle{2}, the projected rectangle must be a simple convex quadrilateral — VisualGeometryToolkitCore.is_orientation_preserving).
VisualGeometryToolkitEstimation.extent_trait — Function
extent_trait(p) -> ExtentTraitDeclare the extent (or absence thereof) for a RANSAC problem. Default is NoExtent(). Problems that hold an extent (e.g. BoundedProblem) override this to return WithExtent(...).
Relative-pose bundle
VisualGeometryToolkitEstimation.RelposeBundleProblem — Type
RelposeBundleProblem(K1, K2, cs)Two-view relative pose scored by exact reprojection (full-3D bundle), refit by robust Schur-reduced BA. K1,K2 are the intrinsics of the observation frame (π(Kᵢ·X)), given models first; cs the u₁ => u₂ correspondences in that frame (canonical image points), any sources/targets container. Same model/constraint as EssentialProblem (epipolar, codimension 1).
VisualGeometryToolkitEstimation.refine_relative_pose — Function
refine_relative_pose(pose::PlainEuclideanMap{3}, K1, K2, cs; max_iter) # default: configs/default.toml [relpose_bundle]
-> Union{EuclideanMap{3}, Nothing}Robust full-3D two-view bundle adjustment of a relative pose: the exact reprojection MLE over the pose and one 3D landmark per correspondence (profiled out through the Schur complement), seeded at pose and returning the refined pose with unit translation, or nothing on failure (fewer than 5 correspondences, a solver failure).
cs are the u₁ => u₂ correspondences in the frame of the intrinsics K1, K2 (reprojection is π(Kᵢ·X)), any sources/targets container; per-point weights are its weights column when it has one (e.g. withattrs(cs; weights = w), the IRLS posterior), unit otherwise.
The seed is a plain pose (a physical one is a MethodError): two views fix a relative pose only up to scale, so its translation is a direction — read unit-normalized, returned with unit norm — and no length enters or leaves. A physical seed is stripped by the caller in any unit (ustrip(m, pose)).
Configuration and Results
VisualGeometryToolkitEstimation.RansacConfig — Type
RansacConfigConfiguration parameters for the RANSAC algorithm.
Field names match posebench conventions.
RansacConfig() IS configs/default.toml's [ransac] table (see config_defaults.jl); RansacConfig(path) loads another file's [ransac] over it. Keywords override single values.
Fields
success_prob::Float64: Desired probability of finding an all-inlier sample, in(0, 1](1runs the fullmax_trialsbudget once a model is found)max_trials::Int: Maximum number of random trials,≥ 1min_trials::Int: Minimum number of trials (overrides adaptive stopping),≥ 0
Out-of-range values are an ArgumentError at construction, for every sampler alike.
Example
config = RansacConfig(success_prob=0.999, max_trials=50_000)
result = ransac(problem, scoring; config)VisualGeometryToolkitEstimation.RansacEstimate — Type
RansacEstimate{M, T, S} = FitResult{Union{M, Nothing}, RansacMetadata{T, S}}The return type of ransac, locally_optimize and every find_* pipeline: M the model, T the storage precision, S the scorer's type. The model and the core diagnostics are read through VisualGeometryToolkitCore's accessors — estimate(result), found_model(result), retcode(result), stop_rule(result), iterations(result) (for RANSAC the number of trials, hypotheses drawn), rms(result) — the weights through weights(result), weight_kind(result) and inlier_mask(result), the scale through noise_scale(result) and scale_source(result); the other diagnostics of RansacMetadata forward as properties (result.quality, result.dof).
The termination record of the search:
| stop | retcode | stop_rule | retcode_symbol |
|---|---|---|---|
| no hypothesis held a consensus (no estimate) | Failure | TrialBudget | :no_model |
the adaptive trial count drawn (the confidence success_prob reached) | Success | AdaptiveCount | :converged |
| an exhaustive sampler drew every sample | Success | TrialBudget | :converged |
max_trials drawn without reaching the confidence | MaxIters | TrialBudget | :max_iterations |
| a selection among fixed candidates, or a seed kept unrefined | Success | ClosedForm | :solved |
| a seed refined by a local optimization | that refit's record |
found_model(result) is THE "a model was found" predicate; converged(result) is strict (successful_retcode(retcode(result)): false for a search that drew max_trials without reaching its confidence, which still found a model). A failed search — found_model(result) == false, retcode(result) == ReturnCode.Failure — has no estimate: its estimate is nothing (so estimate(result) is Union{M, Nothing}, Base's findfirst idiom), its quality is -Inf, its weights all zero (an all-false inlier_mask), rms NaN and its scale ScaleNone. Every find_* and refine_* pipeline returns this type on every path and inherits the rule.
VisualGeometryToolkitEstimation.RansacMetadata — Type
RansacMetadata{T, S}RANSAC-specific diagnostics, the metadata of a RansacEstimate: T the per-point storage precision, S the SCORER's type — the producer whose weight_kind gives the weights their meaning (a threshold scorer's BinaryWeights, the Student-t + uniform scorer's PosteriorWeights).
The core fields carry the rest: the termination record (retcode(result), stop_rule(result); below), iterations the number of trials (hypotheses drawn — RANSAC's loop count; VGC's shared FitResult field, no second name), and n and rms the weights' support and weighted root-mean-square residual:
n = count(>(0), weights);rms = √(Σᵢ wᵢ rᵢ² / Σᵢ wᵢ).
For a threshold scorer (binary weights) these are the consensus set's size and its rms, so rms is not outlier-dominated. For a posterior scorer they span every point of non-negligible posterior, each counted at its weight.
Fields
residuals::Vector{T}: final residuals for all data points (storage precision)weights::Vector{T}: per-point weights in [0, 1] (storage precision), read byweights(result): the consensus membership 1/0 for a threshold scorer, the posterior inlier probability for the Student-t + uniform scorer (a value beloweps(T)is stored as an exact 0).inlier_mask(result)cuts them by the scorer's kind (w > 0; the MAP rulew > ½)quality::Float64: total model quality (higher = better) — the marginal scorescale::Float64: the scale the scorer ORIGINATES, read bynoise_scale(result):√(fit_scale(prior, RSS, ν))of the consensus partition — the inverse-gamma MAP (VisualGeometryToolkitCore'sconsensus_s2) under the scoring's scale prior,√((RSS + 2β₀)/(ν + 2α₀)), so√(RSS/ν)under the default Jeffreys prior, floored at√eps(a noise-free partition,RSS = 0, gives ≈ 1.49e-8, not 0). A LINEAR scale, not a variance and not a loss width.NaNwhen there is no partition to scale (dof == 0, or no model)scale_source::ScaleSource:ScaleEstimated(the scorer's partition), orScaleNonewith aNaNscale, whichnoise_scalerefusesdof::Int: residual degrees of freedomν = d_g·(n_in − p)of the consensus partition (n_inits size,pthe minimal-sample dof); 0 when it is too thinsample_acceptance_rate::Float64: fraction of trials that succeeded attest_sample(effective trials /iterations); low values mean frequent sample degeneracylo_retcode::ReturnCode.T,lo_stop_rule::StopRule: the termination record of the best model's local optimization, the core of itslo_estimateresult (the same record as every result's):(Success, ClosedForm)for no local optimization (nothing),(InitialFailure, NoRule)for a consensus too thin to refine, an iterative optimizer's own; the refit's code with the ruleSeedKeptwhen the score guard kept the seed;(ReturnCode.Default, NoRule)— SciMLBase's "not run" — when no local optimization ran for the best model (no model, or the seed kept unscored)nonfinite_scale::Bool: the consensus partition's scale came out non-finite (an overflowing RSS) and was dropped:scale_sourceScaleNone,scaleNaN,dofthe partition's. An estimated scale is finite:ScaleEstimatednever carries a non-finite one
quality and scale are Float64 regardless of T: scalars carry no footprint argument, and these are the numbers downstream thresholds compare.
Every RANSAC-class refine_* returns a FitResult with RefineMetadata (the refine contract: no scorer, the caller's scale or width):
VisualGeometryToolkitEstimation.RefineMetadata — Type
RefineMetadata{L, T, W}The metadata of every RANSAC-class refine_* (FitResult{M, RefineMetadata}), read through the accessors — weights, weight_kind, noise_scale, scale_source — or as properties of the result:
weights::W: one per datum at the estimate. For a robust refine (LaTriggsstrategy) the loss weightρ′(r²)/ρ′(0), maximum 1, exactly 0 beloweps(IrlsWeights: no cut of its own,inlier_mask(result, cut)); for plain least squares (L === Nothing) a lazy all-ones vector (BinaryWeights).residuals::Vector{T}: each datum's residual norm at the estimate, in the problem's residual unit.scale::T,scale_source::ScaleSource: the scale the refine ran with, as it was given (ScaleGiven,ScaleUpstream);NaNandScaleNonefor a width given alone and for plain least squares. A refine never estimates one.loss_width::T: the width the loss ran at —width, or the efficiency constant timesscale;NaNfor plain least squares.residual_scale::T: a DIAGNOSTIC, the MAD scale of the residual norms at the problem's codimension (median(‖r‖)/√χ²_d(½)). It is never handed on: the hand-off isnoise_scale, the scale the refine was given.
L is the strategy type (the producer, read by weight_kind), T the float type, W the weights' vector type.
Inlier Ratio
VisualGeometryToolkitEstimation.inlier_ratio — Function
inlier_ratio(result::RansacEstimate) -> Float64Fraction of data points that are inliers, count(inlier_mask(result)) / length(weights(result)).
One noise scale for a set of results
pooled_noise_scale(results) pools the scales several RANSAC results originated (each ScaleEstimated, over its own dof) into one, for a downstream refine of them all (scale = pooled, recorded ScaleUpstream); a result without a scale is left out and counted.
VisualGeometryToolkitEstimation.pooled_noise_scale — Function
pooled_noise_scale(results) -> FitResult{Float64, PooledScaleMetadata}ONE noise scale for a set of RANSAC results that share one noise model (one per view, board or photograph of a set): the degrees-of-freedom-weighted pool of their scales,
σ̂ = √(Σᵢ νᵢ ŝᵢ² / Σᵢ νᵢ), ŝᵢ = noise_scale(rᵢ), νᵢ = rᵢ.dof,the pooled variance of their consensus partitions. A result without a scale (ScaleNone: a failed search) or without degrees of freedom (dof == 0) is left out and counted. The estimate is σ̂, also the metadata's scale (ScaleEstimated), so a downstream stage takes it as scale = result and records ScaleUpstream. Its termination record is a closed form's (ReturnCode.Success, ClosedForm), or (ReturnCode.InitialFailure, NoRule) (estimate and scale NaN, ScaleNone) when no result enters the pool.
pooled_noise_scale(scales::AbstractVector{<:Real}, dofs::AbstractVector{<:Integer}) -> FitResult{Float64, PooledScaleMetadata}The same pool from the numbers a result records — each one's noise scale ŝᵢ and its degrees of freedom νᵢ, index-aligned (a record read back from disk, say, rather than the results themselves): σ̂ = √(Σᵢ νᵢ ŝᵢ² / Σᵢ νᵢ), an entry whose scale is not finite (no scale recorded: NaN) or whose νᵢ ≤ 0 left out and counted. The results method above is this one on noise_scale(rᵢ) (NaN for a ScaleNone result) and rᵢ.dof. A DimensionMismatch when the two lengths differ.
Workspaces
RansacWorkspace{K, M, T, W, L} is the composed workspace of one RANSAC run: the score buffers (VisualGeometryToolkitCore's ScoreBuffers{T, W} — residuals, per-point scores, consensus mask and the scorer's workspace W), the local optimizer's workspace L (lo_workspace(P, T, lo, n)), the incumbent and the minimal sample. Build it from the scorer and the strategy it will run, RansacWorkspace(problem, scoring, local_optimization_strategy); RansacWorkspace(P, n) holds the default MSAC scorer's. The core strategies' workspace is LoBuffers: the refit workspace refine_workspace(P, n) — VisualGeometryToolkitCore's ManifoldLmWorkspace{N} for the chart-LM refits (e.g. N = 8 for HomographyProblem, 7 for FundMatProblem, 6 for AbsolutePoseProblem) — and the posterior-weight buffers. DltWorkspace selects the algebraic DLT step, refine!(ws::DltWorkspace, p, θ, weights) with θ unread, which LO does not call.
VisualGeometryToolkitEstimation.RansacWorkspace — Type
RansacWorkspace{K, M, T, W, L}The composed workspace of one RANSAC run, built once and reused across trials and calls: the scoring buffers buf (VisualGeometryToolkitCore's ScoreBuffers{T, W} — residuals, per-point scores, consensus mask, the scorer's workspace W and the evaluation epoch), the local optimizer's workspace lo_ws::L, the incumbent's buffers (best_*) and the minimal sample's indices. Every parameter is concrete, so the loop, the scorer and the local optimizer are all statically dispatched.
Type Parameters
K: Minimal sample size (compile-time constant)M: Model typeT: Per-point STORAGE element type (defaultFloat32). Residuals and soft weights only — the per-point scores and every statistic accumulated from them stayFloat64regardless ofT.W: the scorer's workspace type (scoring_workspace(scoring, n, d_g))L: the local optimizer's workspace type (lo_workspace(P, T, lo, n))
Constructors
RansacWorkspace([T = Float32,] problem, scoring[, local_optimization_strategy]) and its siblings, documented on the constructor.
Reuse
Supply a workspace to ransac(; workspace = ws) (or ransac!) to avoid allocation across calls; a workspace sized for a larger problem is trimmed to each call's data size.
VisualGeometryToolkitEstimation.RansacResultBuffers — Type
RansacResultBuffers{T}(n)The per-point arrays of a RansacEstimate — its residuals and weights — preallocated, so that ransac! writes its result into them with no allocation. The returned estimate's metadata holds THESE arrays: the next ransac! into the same buffers overwrites it.
VisualGeometryToolkitEstimation.LoBuffers — Type
LoBuffers{R, T, S}The local-optimization workspace of every strategy this package hosts (VisualGeometryToolkitCore's lo_workspace), built once per composed workspace: the problem's refit workspace refine (refine_workspace: a ManifoldLmWorkspace{N} for the chart problems, nothing for a problem whose refit pre-allocates nothing) and the per-point buffers of the posterior-weight iteration (posterior_w, posterior_inlier, posterior_sq_r, Float64) and of the IRLS residual block (lo_residuals, lo_best_residuals, storage T). The per-call states live here too, reset by every call instead of built: posterior, the PosteriorWeightState on the posterior buffers (re-seeded by consensus_posterior), and irls::S, the posterior-weight iteration's PosteriorIrlsState on the residual buffers.
VisualGeometryToolkitCore.refine_workspace — Function
refine_workspace(::Type{P}, n_data) -> ManifoldLmWorkspace | nothingThe scratch of refine! for a RANSAC problem of type P: a sized ManifoldLmWorkspace{N} for every chart problem (from _lm_size, so from its chart_dof), nothing for a problem with no chart (VisualGeometryToolkitCore's problem-protocol verb).
VisualGeometryToolkitEstimation.DltWorkspace — Type
DltWorkspace{C, T}Pre-allocated workspace for SVD-based DLT solvers (the no-θ algebraic refine!(ws::DltWorkspace, p, weights) form — the LO refits are NonlinLsq manifold LM on a ManifoldLmWorkspace since the AlgebraicLsq excision).
Holds the design matrix buffer (buf) and the LAPACK SVD workspace (svd). Sized at construction by the column count C (= 9 for 3×3 homogeneous models like H/F, = 12 for the 3×4 camera matrix case) and the maximum row count.
Type Parameters
C: DLT column count (= number of model parameters, e.g. 9 for 3×3, 12 for 3×4)T: scalar float type
Constructor
ws = DltWorkspace{9, Float64}(n_rows)SVD Workspace
Pre-allocated workspace for zero-allocation SVD computation. Defined in VisualGeometryToolkitCore (import it from there); the RANSAC solvers use it.
SvdWorkspace{T}(max_rows, ncols)— pre-allocate LAPACK bufferssvd_nullvec!(ws, A, m, Val(N))— compute null-space vector of firstmrows
Fixed Models
FixedModels{N, M} — Stack-allocated container holding up to N candidate models of type M. Defined in VisualGeometryToolkitCore (import it from there). Supports iterate, length, eltype, collect.
Used as the return type of all solve() methods:
HomographyProblem→FixedModels{1, HomographyMat{T}}FundMatProblem→FixedModels{3, FundMat{T}}AbsolutePoseProblem→FixedModels{4, Extrinsics3}
Benchmark pools
A scoring pool (VisualGeometryToolkitCore Pools.PoolPair, stored in NormalizedImageFrame) is written here. draw_hypotheses repeats the RANSAC trial — the same draw, sample gate, solve and model gate ransac runs — with no scoring. The record's constructor PoolPair(rng, problem, raw; target, max_trials, variance) draws the hypotheses of a pixel-frame problem on a raw pair, carries them into the pool frame once, and returns the record with its residual matrix; EssentialProblem(pair), FundMatProblem(pair) and HomographyProblem(pair) are the record's pool-frame problems; the essential one's sample gate reads 0.1 px through pool_pixel_scale(pair) (F's and H's read the scale-free tolerance on their normalized view).
VisualGeometryToolkitEstimation.draw_hypotheses — Function
draw_hypotheses(rng, problem; target, max_trials) -> HypothesesDraw minimal samples with the problem's own sampler until target samples have each produced at least one model the problem's test_model accepts, or max_trials draws have been made. Every sibling solution of an accepted sample is kept, the last accepted sample's included. No scoring, no consensus, no local optimization.
Each trial is the RANSAC trial, the one code path: draw_sample!, the problem's test_sample, solve, then per solution fit_hypothesis and test_model. The sampler is prepared for the run as ransac prepares it (reset!(sampler, max_trials): a PROSAC schedule spans max_trials). Every draw comes from rng, so a seeded rng makes the result a pure function of the seed and the problem.
Same stopping rule, sibling layout and sample_indices columns; the one difference is the model gate. The old generator applied test_model to H only, while here every family is gated by its problem's own: F's oriented epipolar gate now applies (measured on a PhotoTourism pair under a uniform sampler, it accepts 76 of 510 F solutions), E has no post-solve gate (an E stream is unchanged), H is unchanged. A pool drawn here therefore differs from an F pool drawn there (accepted with pool format 4). A PROSAC sampler's growth horizon is now the run's max_trials (it was the generator's own prosac_T_N).
VisualGeometryToolkitEstimation.Hypotheses — Type
Hypotheses{M}The minimal-sample hypotheses draw_hypotheses drew, in the problem's model frame:
models::Vector{M}: every solution the problem'stest_modelaccepted, sibling solutions of one sample adjacent and in solver order;sample_indices::Matrix{Int}:(m, length(models)), the minimal sample each model was solved from (repeated across siblings);trials::Int: draws made;samples_accepted::Int: draws that produced at least one model;n_solutions::Int: solver solutions beforefit_hypothesis/test_model.
VisualGeometryToolkitEstimation.PoolVariance — Type
PoolVarianceHow a pool record's gt_variance (σ̂², pool units²) is measured — a dataset fact, chosen by the pool's producer:
InlierVariance(; min_inliers): over the raw pair's GT-inlier correspondences;TrackVariance(source, target): over separate pixel point pairs (SfM-track observations), under the oracle model.
VisualGeometryToolkitEstimation.InlierVariance — Type
InlierVariance(; min_inliers)σ̂² over the raw pair's GT-inlier correspondences, in the pool frame, with the fitted-model residual DOF (residual_dof): for E and F the RSS of the ORACLE model (the GT pose) in the family's own residual (E: tangent Sampson on the record's EssentialProblem; F: plane Sampson); for H, which has no oracle model, the RSS of an unconstrained DLT refit to the GT inliers (NaN when the masked design matrix fails VGC's test_dlt_conditioning). NaN when fewer than min_inliers GT inliers.
VisualGeometryToolkitEstimation.TrackVariance — Type
TrackVariance(source, target)σ̂² over separate pixel point pairs source[i] => target[i] (e.g. SfM-track detections, independent of the matcher's correspondences), carried into the pool frame by the raw pair's normalization: the RSS of the ORACLE model (the GT pose) in the family's own residual, over the ORACLE DOF (oracle_residual_dof, n·d_g: nothing is fitted). E and F only. A minimum point count is the reader's policy (it drops the pair); with no points σ̂² is NaN.
Configuration
configs/default.toml is the config of record: RansacConfig(), every core local-optimization strategy's keyword defaults, and every find_* pipeline's scoring and local_optimization_strategy read it at precompile time, so there is no second set of Julia literals to drift from it. Single values are overridden by keyword. RansacConfig(path) loads another file's [ransac] table over the shipped one and optimization_strategy_from_toml builds a strategy from its table — absent keys inherit, present keys override, unknown keys or tags are refused.
A strategy is selected in TOML by tag:
[pipelines.homography]
scoring = { type = "msac", threshold = 3.0 } # px; a Student-t: { type = "student_t_uniform", outlier_halfwidth = 20.0 }
local_optimization_strategy = { type = "irls", loss = "tls" } # no width key: follow the scorer
# explicit widths: { type = "irls", loss = "welsch", efficiency_constant = 2.5 }
# or { type = "irls", loss = "welsch", loss_width = 2.0 } (both keys: ArgumentError)type is a tag of the strategy registry — the core OPTIMIZATION_STRATEGY_TAGS ("none" for nothing, "irls", "triggs", "terminal_lo"), or its explicit merge with a downstream package's — and loss a tag of LOSS_TAGS. The registries are VisualGeometryToolkitCore TagRegistry values; a retired tag is refused with its successor's name. The paper strategies and their cross-validated operating points (efficiency_constant = "cross_validated") are LocalOptimizationDoneRight's:
using VisualGeometryToolkitEstimation: optimization_strategy_from_toml, OPTIMIZATION_STRATEGY_TAGS
import LocalOptimizationDoneRight
lo = optimization_strategy_from_toml(table; class = :homography,
tags = merge(OPTIMIZATION_STRATEGY_TAGS, LocalOptimizationDoneRight.LODR_STRATEGY_TAGS))The scorer is selected the same way, by one reader through a tag registry (VisualGeometryToolkitCore's SCORING_TAGS, or a downstream merge such as RANSACScoringDoneRight's), every key required:
using VisualGeometryToolkitEstimation: scoring_from_toml
scoring = scoring_from_toml(Dict("type" => "msac", "threshold" => 3.0); problem = HomographyProblem)Registering strategies
The strategy machinery — the registry, the keyword constructor, the TOML reader and the writer — is one public API that any package registers its strategies with. A package states one row per strategy and its defaults table; @lo_registry defines the row facts and the keyword constructors and returns the package's registry:
import VisualGeometryToolkitCore as VgtkCore # the machinery is VisualGeometryToolkitCore's
# type tag path scale family label shape parametric
const ROWS = ((MyArm, "my_arm", :irls, nothing, nothing, "Mine", nothing, false),)
const MY_STRATEGY_TAGS = VgtkCore.@lo_registry ROWS defaults = MY_DEFAULTS["optimization_strategy"]The machinery is VisualGeometryToolkitCore's — @lo_registry, lo_construct, lo_tag, lo_defaults, lo_parametric, lo_admits_shape and the loss registry LOSS_TAGS; this package holds the TOML reader and writer below. A strategy's exceptions are methods of the hooks — lo_admits, lo_key, lo_field, lo_field_from_toml, lo_absent, lo_validate, lo_concrete, lo_efficiency_constant_shape and lo_resolve_efficiency_constant — all of them CONTRACT_GENERICS; the reader and writer are the same for every strategy.
VisualGeometryToolkitEstimation.default_config_path — Function
default_config_path() -> StringPath to configs/default.toml — the configuration of record for every entry point that is not handed an explicit config.
VisualGeometryToolkitEstimation.optimization_strategy_from_toml — Function
optimization_strategy_from_toml(table; class::Symbol, section = "optimization_strategy", tags = OPTIMIZATION_STRATEGY_TAGS) -> AbstractOptimizationStrategyBuild a local-optimization strategy from its TOML table (see the registry comment above). tags is the strategy registry the type is looked up in — OPTIMIZATION_STRATEGY_TAGS, or its merge with a downstream package's (merge(OPTIMIZATION_STRATEGY_TAGS, LocalOptimizationDoneRight.LODR_STRATEGY_TAGS)); the entry is then built by lo_from_toml. class is the pipeline's model class (a downstream efficiency_constant = "cross_validated" resolves through it). Unknown type, loss, or keys are refused.
VisualGeometryToolkitEstimation.lo_from_toml — Function
lo_from_toml(T, table; class::Symbol, section = "optimization_strategy", tags = OPTIMIZATION_STRATEGY_TAGS) -> AbstractOptimizationStrategyThe strategy of registry entry T (a type or a loss-parametric family, registered by any package with @lo_registry) from its TOML table — the half of optimization_strategy_from_toml after the tag lookup. The table's keys are the fields (Greek spelled ASCII), the width as efficiency_constant or loss_width, and lo_concrete's extra keys; an unknown key is refused, a field the owner's defaults have no key for is required, every other absent key inherits the defaults. A efficiency_constant goes through lo_resolve_efficiency_constant at lo_efficiency_constant_shape.
VisualGeometryToolkitEstimation.scoring_from_toml — Function
scoring_from_toml(table; problem, section = "scoring", tags = SCORING_TAGS) -> AbstractScoring
scoring_from_toml(T, table; problem, section)The RANSAC scorer of its TOML table: type looked up in tags (VisualGeometryToolkitCore's SCORING_TAGS, or a downstream merge of it), then the entry T built from the table by its method of the second form, which a downstream scorer adds. problem is the problem type the scorer scores (its codimension). Every threshold scorer (AbstractThresholdScoring: Core's two, and a downstream family built by @threshold_scoring_constructors) takes one key, threshold (required: a loss width in the residual's units, e.g. { type = "msac", threshold = 3.0 }), and is built as T(problem; threshold). Its writer is config_dict(scoring; tags), tags the same registry (a downstream merge for a downstream family). Unknown type or keys, and a missing key, are an ArgumentError. config_dict writes the table back.
VisualGeometryToolkitEstimation.default_student_t_uniform_scoring — Function
default_student_t_uniform_scoring(P, outlier_halfwidth) -> StudentTUniformScoringThe Student-t + uniform scorer of record for problem type P at the uniform outlier half-width outlier_halfwidth (in P's residual units): the table { type = "student_t_uniform", outlier_halfwidth = h } read by scoring_from_toml, so its scale and label priors are the stack's configuration of record (configs/default.toml[scoring.student_t_uniform]), never restated by a caller. Core's StudentTUniformScoring(P, h; scale_prior, label_prior) takes both priors explicitly; this is the one place they default.
VisualGeometryToolkitEstimation.config_dict — Function
config_dict(c) -> DictThe TOML table for a config value (a RansacConfig, a MixtureEmConfig or a local-optimization strategy — lo_config_dict), as a plain Dict. Derived from the structs by walking fieldnames, so it cannot fall out of sync with them; a strategy's table loads back through optimization_strategy_from_toml to an equal value. A strategy whose table carries a key beyond the generic writer's adds a method.
VisualGeometryToolkitEstimation.lo_config_dict — Function
lo_config_dict(lo) -> Dict{String, Any}The TOML table of any registered strategy: VisualGeometryToolkitCore's toml_table field walk (the width skipped, Greek spelled ASCII, a field's own spelling through toml_field), its type (lo_tag), its loss for a loss-parametric family, and its width as efficiency_constant or loss_width (no width writes nothing).
VisualGeometryToolkitEstimation.OPTIMIZATION_STRATEGY_TAGS — Constant
OPTIMIZATION_STRATEGY_TAGSThe optimization-strategy registry (VisualGeometryToolkitCore's TagRegistry): TOML tag → strategy type or loss-parametric family — VisualGeometryToolkitCore's STRATEGY_TAGS ("irls", "triggs") merged with this package's ("terminal_lo", built by @lo_registry) and "none" → nothing (no local optimization). The tag is snake_case of the type's name; retired tags name their successor.
VisualGeometryToolkitEstimation.lo_concrete — Function
lo_concrete(T, table, section; tags) -> (C, extra_keys)The concrete strategy type registry entry T names in its TOML table, and the keys the table may carry beyond C's fields and width. Default: a loss-parametric family is concrete at its loss (LOSS_TAGS; a missing or unknown loss is an ArgumentError listing the loss tags), (T{K}, ("type", "loss")); any other strategy is itself, (T, ("type",)). tags is the strategy registry the table was read through, for a strategy that wraps another named by tag. section names the table in messages.
VisualGeometryToolkitEstimation.lo_resolve_efficiency_constant — Function
lo_resolve_efficiency_constant(T, K, value; class::Symbol) -> Float64A TOML efficiency_constant of strategy T, read for loss shape K (lo_efficiency_constant_shape) in pipeline model class class. A number is the caller's own and claims nothing about provenance, so it is taken as given. A string is refused here: "cross_validated" names the accv2026 operating points, LocalOptimizationDoneRight's tuning constants, which its strategies resolve with a method of this hook.
VisualGeometryToolkitEstimation.MODEL_UPDATE_TAGS — Constant
MODEL_UPDATE_TAGSThe model-update registry of the posterior-weight EM (VisualGeometryToolkitCore's TagRegistry): "weighted_refine" (WeightedRefine) and "keep_model" (KeepModel).
VisualGeometryToolkitEstimation.NUISANCE_TAGS — Constant
NUISANCE_TAGSThe nuisance-policy registries of the posterior-weight EM, one VisualGeometryToolkitCore TagRegistry per nuisance part, as a named tuple: scale ("estimated", "fixed_s2"), inlier_prior ("estimated", "fixed_prior") and nu ("estimated", "fixed_nu", "consensus_dof").
VisualGeometryToolkitEstimation.STOP_TAGS — Constant
STOP_TAGSThe stop-rule registry of the posterior-weight EM (VisualGeometryToolkitCore's TagRegistry): "no_improvement" (NoImprovementStop: the incumbent's cost, returning the incumbent) and "parameter_change" (ParameterChangeStop, { type = "parameter_change", rtol = … }: the relative change of the parameters, returning the last iterate).
VisualGeometryToolkitEstimation.CONTRACT_GENERICS — Constant
CONTRACT_GENERICSThe generic functions of VisualGeometryToolkitEstimation another package may add methods to across a package boundary (VisualGeometryToolkitCore's quality gate, contract_generic_violations): the TOML reader's hooks (lo_concrete, lo_resolve_efficiency_constant), the writer (config_dict, for a strategy whose table carries a key beyond the generic one), a wrapper's placement (lo_placement), the posterior-weight stop rule's counter (iterations_without_improvement), the parameter-change stop's measure of a problem (change_parameters), the sampler / running-best protocol (reset!, draw!).
Synthetic test scenes
The scenes every stack package's tests draw from (loaded with Test, the Test extension):
VisualGeometryToolkitEstimation.synthetic_scenes — Function
synthetic_scenes() -> ModuleThe stack's shared synthetic test scenes: a module whose submodules are the scene families — EpipolarScenes, HomographyScenes, PoseScenes, DivisionBoards, P3PScenes, Cameras and Contamination — each exporting its builders (calibrated_pairs, stereo_pixel_pairs, fundmat_scene (THE two-camera fundamental-matrix scene), homography_pairs, frustum_point, noisy_board_views, p3p_scene, contaminated_pairs, …). Each draws from the caller's RNG in a fixed order (pinned fixtures depend on it). Every stack package's tests draw from these instead of copying them:
using Test, VisualGeometryToolkitEstimation
const EpipolarScenes = VisualGeometryToolkitEstimation.synthetic_scenes().EpipolarScenes
u₁, u₂ = EpipolarScenes.calibrated_pairs(rng, R, t; n = 50, σ = 1.0e-3)Implemented by VisualGeometryToolkitEstimationTestExt: using Test loads it.