RANSAC

Main Function

VisualGeometryToolkitEstimation.ransac — Function
ransac(problem, scoring; local_optimization_strategy, config, workspace, rng) -> RansacEstimate

RANSAC 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's MsacScoring/RansacScoring at 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 (default nothing, no local optimization); dispatched in the loop's Phase 2 via locally_optimize!, or — a TerminalLO (lo_placement) — once on the final incumbent of a raw race
  • config::RansacConfig=RansacConfig(): maxtrials, successprob η, min_trials
  • workspace::Union{Nothing,RansacWorkspace}=nothing: Pre-allocated workspace
  • rng::Random.AbstractRNG=Random.default_rng(): source of every random draw the loop makes (sample selection through draw_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 as on_improvement(trial::Int, score, ws::RansacWorkspace) exactly when the tracked best (the acceptance that also re-arms the adaptive trial count) is replaced — read ws.best_model / ws.best_lo_retcode (and ws.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 of locally_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 rule SeedKept (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}())
source
VisualGeometryToolkitEstimation.ransac! — Function
ransac!(result::RansacResultBuffers, ws::RansacWorkspace, problem, scoring;
        local_optimization_strategy, config, on_improvement, on_hypothesis, score_guard, rng) -> RansacEstimate

The 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.

source
VisualGeometryToolkitEstimation.locally_optimize — Function
locally_optimize(problem, θ₀; local_optimization_strategy, scoring,
                 workspace=nothing, score_guard=false) -> RansacEstimate

Refine 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.

source
locally_optimize(problem, models::FixedModels; local_optimization_strategy,
                 scoring, workspace=nothing) -> RansacEstimate

Entry 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.

source

Problem Interface

VisualGeometryToolkitEstimation.AbstractRansacProblem — Type
AbstractRansacProblem

Abstract 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 solve
  • data_size(p)::Int — total number of data points
  • codimension(p)::Int — constraint codimension d_g
  • model_type(::Type{<:P})::Type — concrete model type M (for workspace pre-allocation; defined on the TYPE, so RansacWorkspace(P, n) can read it)
  • solve(p, indices) — fit model(s) from sample indices; returns FixedModels{N,M} with count ∈ 0..N (0 means failure)
  • constraint_with_jacobians(p, model, i) — (g, ∂ₓg, ∂_θg) at data point i

Derived Automatically

  • mahalanobis_distances!(r, p, model) — Mahalanobis distance √(gᵀ Σ̃_g⁻¹ g) from constraint_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; nothing for 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)
end
source
VisualGeometryToolkitEstimation.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.

source
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.

source
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.

source
VisualGeometryToolkitCore.minimal_sample_size — Function
minimal_sample_size(problem::AbstractRansacProblem{K}) -> K

Return 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.

source
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.

source
VisualGeometryToolkitEstimation.fit_hypothesis — Function
fit_hypothesis(problem, θ, sample_indices) -> model | nothing

The 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.

source
VisualGeometryToolkitCore.test_sample — Function
test_sample(problem::AbstractRansacProblem, indices::AbstractVector{Int}) -> Bool

Check whether a sample is non-degenerate (e.g., points not collinear).

Default: true (no degeneracy check). Override for problem-specific checks.

source
test_sample(p::AbsolutePoseProblem, idx) -> Bool

Reject 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, which find_absolute_pose strips 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 a Pinhole that is exactly collinear pixels (the pixel plane is an affine image of the z = 1 chart), so the test is thin_ratio on 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_ratio on the context's back-projected rays — thin_ratio in 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.

source
test_sample(p, idx) -> Bool

Reject 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.)

source
VisualGeometryToolkitCore.test_model — Function
test_model(problem::AbstractRansacProblem, model, sample_indices::AbstractVector{Int}) -> Bool

Check 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.

source
VisualGeometryToolkitCore.test_consensus — Function
test_consensus(problem::AbstractRansacProblem, model, mask::BitVector) -> Bool

Validate 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.

source
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().

source
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 block

The 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‖.

source
VisualGeometryToolkitCore.solver_covariance — Function
solver_covariance(p, θ, idx) -> SMatrix or nothing

UNIT-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.

source

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) -> Int

Residual degrees of freedom on a fitted model with n_in inliers:

ν = (n_in − m) · d_g

where 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.

source
VisualGeometryToolkitEstimation.oracle_residual_dof — Function
oracle_residual_dof(problem_or_type, n::Int) -> Int

Residual 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.

source

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++ binding

The 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 backends
  • NativeSolver — pure-Julia implementations of homography_4pt, fundamental_7pt, p3p, etc.
  • PoseLibSolver — bindings to the PoseLib C++ library
  • essential_5pt(x1, x2) — five-point essential matrix solver (native pure-Julia by default; essential_5pt(PoseLibSolver(), x1, x2) with using PoseLib)
  • essential_dlt(x1, x2) — eight-point essential matrix solver (PoseLib only)

Samplers

VisualGeometryToolkitEstimation.AbstractSampler — Type
AbstractSampler

Abstract 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 from rng. Every random decision a sampler makes MUST go through rng — this is what makes a seeded ransac(...; 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 across ransac() calls

Optional

  • reset!(sampler, budget::Int) — reset, and take the run's trial budget (ransac supplies config.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 trials ransac allows, and whether the incumbent may shorten it. The defaults are config.max_trials and true (adaptive RANSAC).

Built-in Samplers

  • UniformSampler: Stateless uniform random sampling
  • ProsacSampler: Progressive sampling from high-quality matches
  • GaussianSampler: Weighted sampling without replacement
  • ExhaustiveSampler: Every minimal sample exactly once, no adaptive stop
source
VisualGeometryToolkitEstimation.ProsacSampler — Type
ProsacSampler

Mutable 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; ransac sets it to config.max_trials when it prepares the sampler
  • n::Int — current pool size (grows from m to N)
  • t::Int — current trial count
  • T_n::Float64 — current T_n value (recurrence relation)
  • T_n_prime::Int — discretized cumulative threshold

See also: reset!, _draw_prosac!

source
VisualGeometryToolkitEstimation.GaussianSampler — Type
GaussianSampler <: AbstractSampler

Weighted 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 weights
  • inv_weights::Vector{Float64} — cached 1.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 sort
  • sort_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).

source
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.

source
VisualGeometryToolkitEstimation.sampler — Function
sampler(problem::AbstractRansacProblem) -> AbstractSampler

Return the sampler used by this problem.

Default: UniformSampler(data_size(p)). Override for problems with a stored sampler field:

sampler(p::MyProblem) = p._sampler
source
VisualGeometryToolkitEstimation.draw! — Function
draw!(rng::Random.AbstractRNG, indices::AbstractVector{Int}, sampler::AbstractSampler) -> nothing

Fill 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.

source

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) -> BoundedProblem

Wrap 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.

source
VisualGeometryToolkitEstimation.with_extent — Function
with_extent(problem, extent) -> problem or BoundedProblem

The 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).

source
VisualGeometryToolkitEstimation.WithExtent — Type
WithExtent(extent) <: ExtentTrait

Marker 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).

source
VisualGeometryToolkitEstimation.extent_trait — Function
extent_trait(p) -> ExtentTrait

Declare 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(...).

source

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).

source
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)).

source

Configuration and Results

VisualGeometryToolkitEstimation.RansacConfig — Type
RansacConfig

Configuration 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] (1 runs the full max_trials budget once a model is found)
  • max_trials::Int: Maximum number of random trials, ≥ 1
  • min_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)
source
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:

stopretcodestop_ruleretcode_symbol
no hypothesis held a consensus (no estimate)FailureTrialBudget:no_model
the adaptive trial count drawn (the confidence success_prob reached)SuccessAdaptiveCount:converged
an exhaustive sampler drew every sampleSuccessTrialBudget:converged
max_trials drawn without reaching the confidenceMaxItersTrialBudget:max_iterations
a selection among fixed candidates, or a seed kept unrefinedSuccessClosedForm:solved
a seed refined by a local optimizationthat 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.

source
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 by weights(result): the consensus membership 1/0 for a threshold scorer, the posterior inlier probability for the Student-t + uniform scorer (a value below eps(T) is stored as an exact 0). inlier_mask(result) cuts them by the scorer's kind (w > 0; the MAP rule w > ½)
  • quality::Float64: total model quality (higher = better) — the marginal score
  • scale::Float64: the scale the scorer ORIGINATES, read by noise_scale(result): √(fit_scale(prior, RSS, ν)) of the consensus partition — the inverse-gamma MAP (VisualGeometryToolkitCore's consensus_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. NaN when there is no partition to scale (dof == 0, or no model)
  • scale_source::ScaleSource: ScaleEstimated (the scorer's partition), or ScaleNone with a NaN scale, which noise_scale refuses
  • dof::Int: residual degrees of freedom ν = d_g·(n_in − p) of the consensus partition (n_in its size, p the minimal-sample dof); 0 when it is too thin
  • sample_acceptance_rate::Float64: fraction of trials that succeeded at test_sample (effective trials / iterations); low values mean frequent sample degeneracy
  • lo_retcode::ReturnCode.T, lo_stop_rule::StopRule: the termination record of the best model's local optimization, the core of its lo_estimate result (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 rule SeedKept when 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, dof the partition's. An estimated scale is finite: ScaleEstimated never 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.

source

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 (L a Triggs strategy) the loss weight ρ′(r²)/ρ′(0), maximum 1, exactly 0 below eps (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); NaN and ScaleNone for 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 times scale; NaN for 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 is noise_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.

source

Inlier Ratio

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.

source
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.

source

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 type
  • T: Per-point STORAGE element type (default Float32). Residuals and soft weights only — the per-point scores and every statistic accumulated from them stay Float64 regardless of T.
  • 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.

source
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.

source
VisualGeometryToolkitCore.refine_workspace — Function
refine_workspace(::Type{P}, n_data) -> ManifoldLmWorkspace | nothing

The 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).

source
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)
source

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 buffers
  • svd_nullvec!(ws, A, m, Val(N)) — compute null-space vector of first m rows

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) -> Hypotheses

Draw 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.

Against the retired pool generator (pool format ≤ 3)

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).

source
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's test_model accepted, 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 before fit_hypothesis/test_model.
source
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.

source
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.

source

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.optimization_strategy_from_toml — Function
optimization_strategy_from_toml(table; class::Symbol, section = "optimization_strategy", tags = OPTIMIZATION_STRATEGY_TAGS) -> AbstractOptimizationStrategy

Build 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.

source
VisualGeometryToolkitEstimation.lo_from_toml — Function
lo_from_toml(T, table; class::Symbol, section = "optimization_strategy", tags = OPTIMIZATION_STRATEGY_TAGS) -> AbstractOptimizationStrategy

The 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.

source
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.

source
VisualGeometryToolkitEstimation.default_student_t_uniform_scoring — Function
default_student_t_uniform_scoring(P, outlier_halfwidth) -> StudentTUniformScoring

The 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.

source
VisualGeometryToolkitEstimation.config_dict — Function
config_dict(c) -> Dict

The 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.

source
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).

source
VisualGeometryToolkitEstimation.OPTIMIZATION_STRATEGY_TAGS — Constant
OPTIMIZATION_STRATEGY_TAGS

The 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.

source
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.

source
VisualGeometryToolkitEstimation.lo_resolve_efficiency_constant — Function
lo_resolve_efficiency_constant(T, K, value; class::Symbol) -> Float64

A 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.

source
VisualGeometryToolkitEstimation.NUISANCE_TAGS — Constant
NUISANCE_TAGS

The 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").

source
VisualGeometryToolkitEstimation.CONTRACT_GENERICS — Constant
CONTRACT_GENERICS

The 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!).

source

Synthetic test scenes

The scenes every stack package's tests draw from (loaded with Test, the Test extension):

VisualGeometryToolkitEstimation.synthetic_scenes — Function
synthetic_scenes() -> Module

The 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.

source