Robust Estimation API
The RANSAC loop, the problems and the core local optimizations live in VisualGeometryToolkitEstimation.jl. VisualGeometryToolkitCore provides the contracts and shared primitives documented here and on the pages beside it: the problem, scoring and local-optimization contracts with the baseline scorers (this page); the optimization strategies and the local-optimization contract (Optimization Strategies API); the Student-t + uniform scorer (Student-t + Uniform Scoring API); pool selection (Pool Selection API); the robust-loss family and the width axes (Robust Losses API); the robust-statistics toolkit, the generic block-coordinate-descent loop, the chart-rows contract and the chart LM (Chart LM API); the configuration tags, stack contracts and conformance helpers (Configuration Tags and Stack Contracts API). The model manifolds and image-domain confidence regions are on the Model Manifolds and Uncertainty API page.
Estimation Interfaces
VisualGeometryToolkitCore.AbstractOptimizationStrategy — Type
AbstractOptimizationStrategyA local-optimization strategy: refines a seed model on the full observation set. Strategies are routed by RefitFamily; in-loop IRLS-family strategies additionally plug into the solver via a weight policy (AbstractWeightPolicy).
VisualGeometryToolkitCore.AbstractScoring — Type
AbstractScoringA hypothesis score: evaluates a model's residuals and returns a value used for best-so-far gating, the size of the consensus set it implies (for the adaptive stopping rule), and that set's order (for the local optimizer). The contract — scoring_workspace, score!, inlier_count, consensus_order, and the optional verbs with their defaults — is stated in robust/scoring_contract.jl; the RANSAC loop calls only it.
VisualGeometryToolkitCore.AbstractWeightPolicy — Type
AbstractWeightPolicyA reweighting rule: the nuisance and weight blocks of block_coordinate_descent!. The contract is deliberately minimal — a weight policy promises weights, nothing more:
update_nuisance!(policy): refresh whatever nuisance parameters the policy carries — ŝ², ν, the mixing weight π, the Barron shape α — at the current residuals (a no-op for policies that carry none).update_weights!(policy): refresh per-residual weights from the current residuals and those nuisance parameters.
The two run as a pair, in that order, once per outer iteration at a fixed model — see update_nuisance! for the contract.
A weight policy is NOT a likelihood. M-estimation losses with bounded potentials (Welsch, Huber elbows at frozen scale, Barron shape adaptation) have no normalizable density on an unbounded domain — their "objective" is a loss, and only its derivative machinery (ψ(r)/r) is used here. Do not score with a weight policy.
VisualGeometryToolkitCore.ConsensusAnchored — Type
Scale interface: the strategy takes ŝ from the consensus set the score selected (see ScaleInterface).
VisualGeometryToolkitCore.ConsensusSet — Type
ConsensusSet(; count, s2, epoch, score = NaN)The consensus set a local optimizer starts from — the inlier set of the most recent score! on a workspace, as consensus_set returns it: its size k* (count), its scale ŝ² (s2, the Student-t scale of the set under the scorer's prior, consensus_s2), the epoch of the score evaluation that produced it and that evaluation's score (NaN when the producer did not carry it). Construct it by keyword; the field order is not API.
A ConsensusSet describes ONE evaluation: it is valid only while it reflects the MOST RECENT score! on the buffers it was built from. Producers stamp epoch with the buffers' evaluation counter; consumers (local optimizers) must establish that the stamp still equals the current epoch before using it, via check_fresh or is_fresh.
Read it through its accessors, never by field name:
inlier_count—count, the set size k*.scale_s2—s2, the consensus scale ŝ².consensus_score—score, the evaluation's score (NaN: not carried).check_fresh/is_fresh— theepochstamp, which is only ever meaningful compared against a current epoch, and so is exposed as that comparison rather than as a raw number.
VisualGeometryToolkitCore.ExternalRefit — Type
ExternalRefit()The RefitFamily of a strategy whose refit is an external refiner called at an absolute width, through external_workspace, prepare_external! and refine_external!.
VisualGeometryToolkitCore.FixedScale — Type
Scale interface: one absolute loss width for every hypothesis (see ScaleInterface).
VisualGeometryToolkitCore.FollowsScorer — Type
Scale interface: the loss width follows the scorer's decision_boundary (see ScaleInterface).
VisualGeometryToolkitCore.FrozenNuisance — Type
FrozenNuisance() <: AbstractWeightPolicyThe weight policy that holds nothing: update_nuisance! and update_weights! are no-ops that return the policy. For a block_coordinate_descent! whose loss stays at the deployment it was seeded with (a closed-form lift, a fixed-scale reweighting whose weights the model block computes itself): the nuisance and weight blocks are frozen, and the loop still calls them.
VisualGeometryToolkitCore.NativeRefit — Type
NativeRefit()The RefitFamily of a strategy whose refit runs in the in-process solver loop (locally_optimize!); the default.
VisualGeometryToolkitCore.NoScale — Type
Scale interface: the strategy consumes no scale at all — the seed, ℓ₂ (see ScaleInterface).
VisualGeometryToolkitCore.NormalizedWeightPolicy — Type
NormalizedWeightPolicy <: AbstractWeightPolicyA weight policy whose underlying objective IS a proper normalized probability model (e.g. the Student-t/uniform mixture posterior, the Gaussian). Only these support likelihood-grade operations: evaluating a comparable objective value, likelihood-monotonicity statements, and use as evidence in a score. The ρ(∞) = ∞ boundary of the theory, as a type.
VisualGeometryToolkitCore.RefitFamily — Type
RefitFamily(lo::AbstractOptimizationStrategy) -> RefitFamilyHoly trait routing a strategy to its EXECUTION path (where the refit runs — an implementation concern, orthogonal to the paper's two classification axes optimization_path and scale_interface):
NativeRefit()— the in-process solver loop (weight policy / joint lift / continuation schedule / block-coordinate ascent all run here)ExternalRefit()— an external refiner called at an absolute width outside the loop (refine_external!: PoseLib LM/LZ and its adaptive-width arm, RansacLib classical LO)
New strategies declare their family; consumers dispatch on it and never enumerate concrete strategy types.
DESIGN RULE (RVG 2026-07-18 port): all native strategies run through the production locally_optimize port (NativeRefit, the default); the noise scale is ingested ONLY through the strategy's width mode (loss_at) from the scorer's consensus set, never from a deployed plug-in or loss-width-window bootstrap. An external arm that anchors a width (the adaptive PoseLib LM arm) reads its consensus scale through the production scoring machinery too.
VisualGeometryToolkitCore.ScaleInterface — Type
ScaleInterfaceThe paper's scale-interface axis — how a local optimizer obtains the loss_width it needs (§3.6 "Scale supply to local optimization"). A LABEL, derived from the strategy, never a stored policy: a width-carrying strategy's interface is read off its width mode (lo_width).
ConsensusAnchored— takesŝfrom the consensus set the SCORE selected for the hypothesis being refined and setsloss_width = efficiency_constant·ŝ(theEfficiencyConstantwidth mode), cross-validating only the dimensionlessefficiency_constant.FixedScale— one ABSOLUTE loss width for every hypothesis (theLossWidthwidth mode; TLS-LM, TLS-LZ, classical TLS-LO⁺).FollowsScorer— the loss width follows the scorer's decision point,decision_boundary(a strategy with no width of its own).SelfScaling— re-estimatesŝat each iteration; the consensus set only initializes it (Stu-tU-BCD, Stu-tU-IRLS).NoScale— consumes no scale at all (the seed, ℓ₂).
VisualGeometryToolkitCore.SelfScaling — Type
Scale interface: the strategy re-estimates ŝ at each iteration (see ScaleInterface).
VisualGeometryToolkitCore.check_fresh — Method
check_fresh(cs::ConsensusSet, epoch::Integer) -> nothingRefuse a stale ConsensusSet with an ArgumentError naming both stamps. epoch is the CURRENT epoch of the buffers that produced cs. Returns nothing when the set is fresh.
This is the one place the freshness precondition lives. It is a real throw, not an @assert: the failure guarded against is a silent use of an earlier evaluation's set — wrong answers, not a crash — so the check must not be removable.
VisualGeometryToolkitCore.consensus_score — Method
consensus_score(cs::ConsensusSet) -> Float64The score of the evaluation that produced cs (the value score! returned, so a local optimizer that ascends that score need not re-score its seed), or NaN when the producer did not carry it.
VisualGeometryToolkitCore.inlier_count — Method
inlier_count(cs::ConsensusSet) -> Int
inlier_count(scoring, W) -> IntThe size k* of a consensus set; for a scoring and its workspace, the k* of the most recent score! — the statistic that drives the hypergeometric stopping rule.
VisualGeometryToolkitCore.inlier_mask — Method
inlier_mask(policy) -> BitVectoris_inlier over every residual. Generic on purpose: a policy defines the rule, never the loop.
VisualGeometryToolkitCore.inlier_weight — Function
inlier_weight(policy) -> AbstractVectorPer-residual inlier weight in [0, 1]: how much each observation belongs to the inlier component.
Its MEANING is the policy's type. Under a NormalizedWeightPolicy it is a posterior membership probability, so it may be summed (an effective inlier count) and thresholded. Under a plain AbstractWeightPolicy it is a loss weight — orderable, but not a probability: summing it means nothing and > 0.5 is not a decision.
Returns a STORED vector or a view of one — an O(1) accessor, never a computation: is_inlier calls it once per residual, so a freshly broadcast result would make inlier_mask quadratic.
VisualGeometryToolkitCore.is_fresh — Method
is_fresh(cs::ConsensusSet, epoch::Integer) -> BoolWhether cs still reflects the most recent score! on the buffers that produced it, i.e. whether its stamp equals their current epoch.
A stale ConsensusSet describes an earlier evaluation: using it yields a plausible-looking wrong k* and ŝ², not an error — so the stamp must be checked before the set is used. Use check_fresh to enforce it.
VisualGeometryToolkitCore.is_inlier — Function
is_inlier(policy, i::Integer) -> BoolWhether residual i is an inlier UNDER THIS POLICY'S OWN RULE. Every policy answers; they disagree about what the question means, which is why this is the policy's method and not a caller's expression.
A NormalizedWeightPolicy takes the default below — the MAP rule is_map_inlier on its membership. A loss policy must state its own rule (typically a residual multiple of its scale): it has no membership to threshold, and 0.5 on a loss weight is arbitrary.
VisualGeometryToolkitCore.is_map_inlier — Method
is_map_inlier(posterior_weight) -> BoolThe MAP inlier decision on a POSTERIOR inlier probability: inlier iff the posterior exceeds ½, i.e. the inlier label is the more probable one. The ½ is the definition of the MAP decision between two labels, not a tunable.
THE one statement of that rule: every posterior check in the stack calls it (RANSACScoringDoneRight's posterior weighting, VisualGeometryToolkitEstimation, the BlobBoards pipeline). It applies to a posterior membership only — never to an M-estimation loss weight, whose 0.5 has no probabilistic meaning (see is_inlier).
VisualGeometryToolkitCore.lo_label — Method
lo_label(lo::AbstractOptimizationStrategy) -> StringThe single source of truth for a strategy's figure/table DISPLAY NAME: its LaTeX label string, read by every renderer instead of a hand-maintained lookup table, so legends cannot drift. The marker companion is lo_marker. A concrete lo_label returns the BASE name (e.g. raw"Welsch-HQ", i.e. Loss-Path).
VisualGeometryToolkitCore.lo_marker — Method
lo_marker(lo::AbstractOptimizationStrategy) -> SymbolThe strategy's PGFPlots marker symbol — the figure grammar's shape = optimization path rule, derived from optimization_path through path_marker. Override only for a strategy that must stand apart from its path (ℓ₂ uses :x).
VisualGeometryToolkitCore.loss_family — Method
loss_family(lo::AbstractOptimizationStrategy) -> SymbolThe loss ROW of the design table an arm belongs to (:welsch | :tls | :gm | :cauchy | …; the Student-t/uniform mixture arms report :tls — they share the "uniform mixtures" column). Determines the color HUE facet in the paper registry. Default :unspecified so registries can detect a strategy that has not declared its identity.
VisualGeometryToolkitCore.optimization_path — Method
optimization_path(lo::AbstractOptimizationStrategy) -> SymbolThe paper's optimization-path axis — the column of the design table:
:irls— static reweighting: the weight function of a FIXED loss is applied at every iteration (Welsch-IRLS, GM-IRLS, the hard truncated refit TLS-LM, Stu-tU-IRLS):hq— half-quadratic lift: model and lifted weights optimized JOINTLY, no schedule (Welsch-HQ, GM-HQ, TLS-HQ):gnc— explicit continuation: a scheduled sequence of progressively sharper problems (Welsch-GNC, GM-GNC, TLS-GNC, and TLS-LZ — Le–Zach's relaxed TLS tightened by a μ-schedule):bcd— block-coordinate ascent on the scoring objective itself over partition, scale and model (Stu-tU-BCD):triggs— the fixed loss minimized DIRECTLY: one robust Levenberg–Marquardt solve on NLLSsolver's robustified Hessian, no reweighting loop (Cauchy-Triggs):classical_lo— classical LO-RANSAC inner refinement (TLS-LO, TLS-LO⁺):seed— no local optimization (the seed hypothesis is returned)
Default :unspecified, so registries can detect a strategy that has not declared its identity. Drives lo_marker (marker shape = path) and the path half of a composed lo_label.
VisualGeometryToolkitCore.path_marker — Method
The PGFPlots marker of an optimization path — the figure grammar's shape = path rule.
VisualGeometryToolkitCore.path_suffix — Method
The display suffix of an optimization path (the -IRLS / -HQ / -GNC / -BCD / -LO half of a method name).
VisualGeometryToolkitCore.robust_weight — Function
robust_weight(policy) -> AbstractVectorPer-residual factor in the weighted normal equations — psi(r)/r for an M-estimation loss, p_in * u for a Student-t/uniform mixture (membership times the component's own IRLS weight).
EQUALS inlier_weight for a loss policy, where one number does both jobs. The two differ only where the model separates membership from reweighting.
VisualGeometryToolkitCore.scale_interface — Method
scale_interface(lo::AbstractOptimizationStrategy) -> ScaleInterfaceThe strategy's ScaleInterface label. A width-carrying strategy's is DERIVED from its width mode (lo_width): EfficiencyConstant → ConsensusAnchored(), LossWidth → FixedScale(), nothing → FollowsScorer(). Default UnspecifiedScale() so registries can detect an undeclared strategy.
VisualGeometryToolkitCore.scale_s2 — Method
scale_s2(x) -> Float64The squared scale ŝ² x carries: a ConsensusSet's consensus scale, a DeployedLoss's noise variance s2, a FixedS2 policy's held value. The robust layer speaks squared scale throughout.
VisualGeometryToolkitCore.update_nuisance! — Function
update_nuisance!(policy::AbstractWeightPolicy) -> policyRefresh the policy's NUISANCE PARAMETERS at the current residuals and a fixed model. One half of the pair block_coordinate_descent! runs per iteration, always in this order:
update_model! → residuals → update_nuisance! → update_weights! → checkOne sweep, at a fixed model: update_nuisance! may not touch the model, and update_weights! reads whatever it left behind. A policy that carries no nuisance parameters implements this as a no-op — the loop still calls it.
Why not "scale"
The parameters this verb moves are, across the implementing policies: nothing at all, ŝ² alone, ν together with ŝ², the pair (ŝ², π), and — on the Barron arm — only the shape α, with no scale involved. "Scale" names only one of those.
What they share is their ROLE, not their identity. The model (pose, homography, essential matrix) is the parameter of interest; ŝ², ν, π and α exist only because the likelihood cannot be written without them. That is the definition of a nuisance parameter, and it is true of all of them.
Nor is it an EM maximization: two implementations are genuine no-ops and the Barron α update is a direct minimization of the negative log-likelihood over a grid. "Nuisance" describes every implementation.
See AbstractWeightPolicy for the full policy contract.
VisualGeometryToolkitCore.update_weights! — Function
update_weights!(policy::AbstractWeightPolicy) -> policyRefresh the policy's per-residual WEIGHTS from the current residuals and the nuisance parameters update_nuisance! just set, at a fixed model: the weight block of block_coordinate_descent!, run after the nuisance block in every iteration. It writes the weights and nothing else.
VisualGeometryToolkitCore.BinaryWeights — Type
BinaryWeights()A WeightKind: weights in {0, 1} — a threshold scorer's consensus decision (RansacScoring, MsacScoring), or an L2 result's all ones. The inlier mask is w > 0.
VisualGeometryToolkitCore.IrlsWeights — Type
IrlsWeights()A WeightKind: an M-estimator's loss weights ρ′, normalized to a maximum of 1 (Irls, Triggs). They have no inlier cut of their own: inlier_mask needs one given explicitly.
VisualGeometryToolkitCore.PosteriorWeights — Type
PosteriorWeights()A WeightKind: posterior inlier probabilities — the Student-t + uniform scorer's, or an EM fit's E-step. The inlier mask is the MAP rule, is_map_inlier (posterior > ½).
VisualGeometryToolkitCore.WeightKind — Type
WeightKindWhat a robust result's per-datum weights mean, and so where their inlier cut lies: BinaryWeights, PosteriorWeights or IrlsWeights. A trait of the producer's type, read by weight_kind; inlier_mask dispatches on it.
VisualGeometryToolkitCore.inlier_mask — Method
inlier_mask(result) -> BitVector
inlier_mask(result, cut::Real) -> BitVectorThe inliers of a robust result, from its weights by their weight_kind: w > 0 for BinaryWeights, the MAP rule is_map_inlier for PosteriorWeights, and an ArgumentError for IrlsWeights, whose loss weights have no cut of their own. With cut, w > cut for any kind — the cut stated by the caller.
VisualGeometryToolkitCore.unit_weights — Method
unit_weights([T = Float64], n) -> AbstractVector{T}The weights of an L2 result — every datum at weight one — as a lazy FillArrays.Fill(one(T), n): no allocation, and BinaryWeights by kind (their inlier_mask is every datum). What an L2 producer stores as its metadata's weights.
VisualGeometryToolkitCore.weight_kind — Function
weight_kind(result) -> WeightKind
weight_kind(::Type{P}) -> WeightKindThe WeightKind of a robust result's weights: a trait of its metadata's TYPE, which answers from its producer's type (a scorer, a local optimization). A contract generic: a producer or metadata type of another package adds its method on the type.
Problem Protocol
VisualGeometryToolkitCore.AbstractConstraintProblem — Type
AbstractConstraintProblemSupertype of a problem that scoring and local optimization can run on. Implementors provide data_size, codimension, minimal_sample_size, and constraint_with_jacobians; optionally observation_covariance and constraint_rounding_scale (the point's noise and its degeneracy scales), solver_covariance with provides_solver_covariance (predictive scoring), residual_context with mahalanobis_distance (a Jacobian-free distance path), and refine! with refine_workspace (the weighted refit local optimizations call).
VisualGeometryToolkitCore.codimension — Function
codimension(problem) -> IntConstraint codimension d_g: the number of independent constraint equations a true datum satisfies (1 for F/E/line scalar residual, 2 for homography / PnP). A scoring reports the codimension it was built for through the same verb. A problem defines it on its type, codimension(::Type{<:P}); the instance form falls back through it.
VisualGeometryToolkitCore.data_size — Function
data_size(problem) -> IntTotal number of data points the problem scores over.
VisualGeometryToolkitCore.mahalanobis_distance — Method
mahalanobis_distance(problem, ctx, i) -> RealThe Mahalanobis distance of data point i, ≥ 0: the norm of its whitened_residual, so that its square is the squared Mahalanobis distance gᵢᵀ Σ̃_{gᵢ}⁻¹ gᵢ (~ χ²(d_g) under H₀). ctx is residual_context(problem, model), the model by default. What every scorer reads per point: scores take its square, which the residual's sign does not move.
A problem overrides it when a cheaper Jacobian-free route to the SAME distance exists (a reprojection error's norm), or to put a gate before it (a point the lens cannot place: OUT_OF_FIELD_RESIDUAL); an override returns a value ≥ 0. mahalanobis_distances! is this at every point.
VisualGeometryToolkitCore.mahalanobis_distances! — Method
mahalanobis_distances!(d, problem, model) -> dFill d[i] with mahalanobis_distance(problem, ctx, i) for every index of d (1:data_size(problem) in the RANSAC loop), ≥ 0, so that d[i]^2 ~ χ²(d_g) under H₀. The per-model work is residual_context, computed once; a problem overrides that hook and mahalanobis_distance, not this loop. The signed rows are whitened_residuals!.
VisualGeometryToolkitCore.minimal_sample_size — Function
minimal_sample_size(problem) -> IntModel degrees of freedom m used in the residual DOF ν = (k − m)·d_g.
VisualGeometryToolkitCore.observation_covariance — Method
observation_covariance(problem, i) -> Σ̃_xThe covariance of data point i's observations, over the coordinates its constraint's G_x differentiates (a correspondence's pair block): what whitened_residual whitens by. A problem's observations carry their noise (conventions/observation-noise.md) — I for plain points, the default — and a problem that stores covariances (a correspondence set's Σ₁/Σ₂ columns, a line fit's per-point shapes) returns point i's.
VisualGeometryToolkitCore.provides_solver_covariance — Method
provides_solver_covariance(::Type{<:AbstractConstraintProblem}) -> BoolWhether problem type P defines solver_covariance, so that it can be scored predictively. Default false; a provider declares provides_solver_covariance(::Type{<:P}) = true beside its method.
VisualGeometryToolkitCore.refine! — Function
refine!(R, problem, θ, w) -> θ′ | nothingThe weighted refit of problem from θ under per-point weights w (w[1:data_size(problem)]), on the problem's refit workspace R (refine_workspace) — the model block of every IRLS-family local optimization. nothing means the solve failed (an underdetermined or singular system); the caller keeps its incumbent.
VisualGeometryToolkitCore.refine_workspace — Function
refine_workspace(::Type{P}, n::Int) -> RThe scratch of refine! for a problem of type P with up to n data points, built once per composed workspace and reused across calls. nothing for a problem whose refit needs none.
VisualGeometryToolkitCore.residual_context — Method
residual_context(problem, model) -> ctxWhat mahalanobis_distances! and whitened_residuals! compute ONCE per model before their per-point loops, and hand to every mahalanobis_distance(problem, ctx, i) and whitened_residual(problem, ctx, i). The default is the model itself, so a problem that defines neither hook scores exactly as before.
A problem overrides it when part of the residual depends on the model alone and is costly: a relative-pose bundle's cheiral pose decomposition and inverse intrinsics, an essential matrix widened to Float64 once rather than per point. It then defines the per-point hooks it answers for its context type C (constraint_with_jacobians(problem, ctx::C, i), which the defaults read, or mahalanobis_distance(problem, ctx::C, i) directly).
VisualGeometryToolkitCore.solver_covariance — Method
solver_covariance(problem, model, sample_indices) -> SMatrix or nothingModel parameter covariance Σ̃_θ propagated through the minimal solver, for predictive scoring. A provider returns nothing for a DEGENERATE minimal sample, one whose solver Jacobian does not exist, and predictive scoring then SKIPS that hypothesis like a failed solve.
A provider declares itself with provides_solver_covariance. A problem type that defines no provider cannot be scored predictively: the fallback method throws an ArgumentError naming the problem type.
VisualGeometryToolkitCore.whitened_constraint_rows — Method
whitened_constraint_rows(problem, model, i) -> (r, J_w)Data point i's constraint as a least-squares row: its whitened_residual and its model rows L_Σ⁻¹·G_θ under the SAME factor, held fixed (the Gauss–Newton row of a frozen whitening; L_Σ L_Σᵀ = G_x·Σ̃_x·G_xᵀ). In the constraint's shape: a number and an SVector row for a scalar constraint, an SVector and a matrix for a vector one. Degenerate (the gradient vanishes at the rounding scale, or Σ̃_x is singular along the normal): the rule's residual (0 when the constraint vanishes, else ±Inf) and ZERO rows. What a predictive scorer reads per point: the residual and the rows the model covariance is propagated through.
The residual is GTSAM's NoiseModelFactor::whitenedError for this point (its unwhitenedError is the constraint g), with the Sampson residual's noise along the constraint's normal; the rows are the frozen-whitening Gauss–Newton rows (the LM's exact rows are whitened_jacobian_rows!'s).
VisualGeometryToolkitCore.whitened_residual — Method
whitened_residual(problem, ctx, i) -> T | SVector{d_g}Data point i's constraint as a whitened residual, SIGNED and in the constraint's shape: a number for a scalar constraint (d_g = 1, the signed distance gᵢ/√Σ̃_{gᵢ}), an SVector of its d_g components for a vector one (L⁻¹gᵢ, LLᵀ = Σ̃_{gᵢ} = ∂ₓgᵢ·Σ̃_x·∂ₓgᵢᵀ), so that ‖rᵢ‖² is the squared Mahalanobis distance gᵢᵀ Σ̃_{gᵢ}⁻¹ gᵢ (~ χ²(d_g) under H₀). ctx is residual_context(problem, model), the model by default. GTSAM's NoiseModelFactor::whitenedError for this point.
The default is the Sampson residual of constraint_with_jacobians(problem, ctx, i) at the problem's constraint_rounding_scale(problem, ctx, i) (base/sampson.jl's geometry layer, the stack's one Sampson path and its one degeneracy rule: ±Inf for an unsatisfiable degenerate point, 0 for one that vanishes exactly), whitened by the point's observation_covariance (one Cholesky of G_x·Σ̃_x·G_xᵀ). An override returns the same shape: a scalar for a vector constraint is a distance, not a residual, and test_constraint_problem refuses it. The distance is mahalanobis_distance; the rows over every point whitened_residuals!.
VisualGeometryToolkitCore.whitened_residuals! — Method
whitened_residuals!(r, problem, model) -> rThe whitened_residual of every data point, stacked: point i's d_g signed components in rows d_g(i−1)+1 … d_g·i of r, d_g =codimension(problem), unweighted, at ctx =residual_context(problem, model), computed once. r holds every point, d_g·data_size(problem) rows; another length is a DimensionMismatch, and so is a point whose residual is not d_g components (a scalar override of a vector constraint): it fails loudly rather than reading past the data. The problem-level form of the model-level whitened_residuals!(r, M, xs) (unweighted too); its row norms are mahalanobis_distances!'s.
Scoring Contract and Baseline Scorers
VisualGeometryToolkitCore.ScoreBuffers — Type
ScoreBuffers{T, W}(n, scoring_ws)The scoring buffers of one composed workspace, built once and handed to a local optimizer by reference: the residuals (residuals(buf), storage precision T), the per-point scores (scores(buf), Float64 — a derived statistic: squaring a Float32 residual into Float64 is exact), the consensus mask (consensus_mask(buf)), the scorer's workspace (scoring_workspace(buf)) and the evaluation epoch that stamps every ConsensusSet built from them (check_fresh(cs, buf)).
VisualGeometryToolkitCore.check_workspace — Method
check_workspace(scoring, W) -> nothingRefuse, at entry, a workspace built for a different scorer (ArgumentError). The default refuses a workspace the scorer cannot read — no inlier_count(scoring, W) method but the contract's fallback: another scorer's scoring_workspace built it — and names the scorers it was built for. A scorer whose workspace also depends on its configuration (a prior's tables) adds a method that checks that as well. Called once per entry, never in the inner loop.
VisualGeometryToolkitCore.consensus_mask! — Method
consensus_mask!(buf, scoring) -> bufSet consensus_mask(buf) to the consensus set of the most recent score!: the first inlier_count entries of consensus_order.
VisualGeometryToolkitCore.consensus_mask — Method
The consensus mask of a ScoreBuffers: the set of the last scored model.
VisualGeometryToolkitCore.consensus_order — Function
consensus_order(scoring, W) -> AbstractVector{Int}The order of the points after the most recent score!: its first inlier_count(scoring, W) entries are the consensus set. A view of the scorer's buffer, valid until the next score!. A workspace another scorer built is an ArgumentError (the contract's fallback; see check_workspace).
VisualGeometryToolkitCore.consensus_s2 — Method
consensus_s2(scoring, residuals, order, k; model_dof, d_g) -> Float64The Student-t scale ŝ² of the consensus set order[1:k] under the scorer's scale_prior: partition_student_t of its RSS (partition_rss, from the plain residuals). model_dof is the caller's — m + 1 for a local optimizer's consensus set (the scale's extra dof), m for a result's σ̂.
VisualGeometryToolkitCore.consensus_set — Method
consensus_set(scoring, W, residuals; model_dof, d_g, epoch, score = NaN) -> ConsensusSetThe consensus set of the most recent score!: its size inlier_count, its scale consensus_s2 over consensus_order, stamped with epoch, carrying that evaluation's score when the caller has it.
VisualGeometryToolkitCore.decision_boundary — Function
decision_boundary(scoring, buf::ScoreBuffers) -> Float64The scorer's decision boundary for the most recent score! on buf: the residual below which a point is an inlier. Two behaviours, by scorer:
- a threshold scorer (
RansacScoring,MsacScoring, the loss-width families): its thresholdτ, a CONSTANT of the scorer — the same whateverbufholds; - the Student-t + uniform scorer (
StudentTUniformScoring): the MAP inlier/outlier crossover of the Gaussian–uniform pair at the CURRENT consensus scaleŝ(the Student-t scale of the last score's consensus set) and its outlier half-widthh,decision_boundary(GauInlier(ŝ²; d_g), h)— an ESTIMATE, recomputed with every score.
A local optimizer with no width of its own follows it (loss_at). Only scorers with has_decision_boundary define it. The same generic gives a loss shape's half-weight boundary at a loss width and the Gaussian–uniform pair's at an outlier half-width (decision_boundary(shape, loss_width), decision_boundary(::GauInlier, outlier_halfwidth)).
VisualGeometryToolkitCore.has_decision_boundary — Method
has_decision_boundary(::Type{S}) -> BoolWhether scorer type S defines decision_boundary — a static trait, false by default, declared true beside the method.
VisualGeometryToolkitCore.inlier_probabilities! — Method
inlier_probabilities!(w, scoring, scores, order, k; model_dof, d_g) -> wPer-point inlier probabilities of the consensus set order[1:k]: under a scorer with an outlier model (outlier_halfwidth a number) the Student-t + uniform posterior of the set's Student-t (posterior_inlier_probs! on the squared per-point scores, under the scorer's prior); otherwise 0/1 membership of order[1:k].
VisualGeometryToolkitCore.is_predictive — Method
is_predictive(scoring) -> BoolWhether the scorer scores a model WITH its covariance (θ::Uncertain). Default false.
VisualGeometryToolkitCore.outlier_halfwidth — Method
outlier_halfwidth(scoring) -> Float64 | nothingThe half-width of the scorer's uniform outlier model, if it has one (the Student-t + uniform posterior weights read it); nothing otherwise (default).
VisualGeometryToolkitCore.residuals — Method
The residuals of a ScoreBuffers.
VisualGeometryToolkitCore.sample_point_held — Method
sample_point_held(x) -> BoolTHE rule of a minimal sample's points, every scorer's (the threshold families' consensus partition and score correction, the Student-t scorer's zeroed scores, the predictive scorer's scores and penalties — one decision per point, from its score — and the pool staging, through zero_sample!): a sample point is held at zero residual — its model fits it by construction — only where its value x (a residual, its square, a score) is finite. A non-finite one is a point the model does not reach (a lattice detection a pose leaves unassigned, its distance Inf), and it stays an outlier: out of the consensus set, its RSS and its dof.
VisualGeometryToolkitCore.scale_prior — Method
scale_prior(scoring) -> IGPriorThe scale prior the scorer's consensus scale is fit under. Default JeffreysPrior().
VisualGeometryToolkitCore.score! — Function
score!(W, scoring, scores, residuals, n; sample = nothing, bound = -Inf) -> Float64
score!(W, scoring, scores, residuals, problem, θ::Uncertain, n; sample = nothing, bound = -Inf) -> Float64Score a model from its residuals residuals[1:n] (model-certain), or — a predictive scorer only — from the problem and the model with its covariance (filling residuals with the whitened residuals of the same constraint evaluation). Fills scores[1:n] with the per-point score and caches in W what inlier_count and consensus_order read. sample: the minimal sample's indices (or nothing), whose points are exact by construction. Higher is better.
bound: the score a caller must beat (strictly) for the result to matter. A bounded-sum scorer (score_bound) MAY stop early once the candidate provably cannot exceed it; it then returns a value ≤ bound and its cached state is undefined until the next full score!. The default -Inf never stops early.
VisualGeometryToolkitCore.score_bound — Method
score_bound(scoring) -> Float64 | nothingAn upper bound of one point's contribution to a BOUNDED-SUM score (each point adds a quality in [0, b] to the total, to within a few ulps of b), or nothing (default) for a scorer whose score is not such a sum. A bounded-sum scorer may stop a score! early against its bound keyword. The threshold loop of AbstractThresholdScoring corrects the minimal sample's points after the sum, so its exit needs the lower bound 0 as well.
VisualGeometryToolkitCore.score_model! — Method
score_model!(buf, scoring, problem, θ; sample = nothing, reuse_residuals = false,
mask = true, bound = -Inf) -> (S, k)THE one scoring path of a model on a composed workspace: bump the epoch (every ConsensusSet issued before is stale), compute θ's residuals into residuals(buf) (skipped under reuse_residuals — the caller left them there — for a model-certain scorer), score!, and set the consensus mask (mask = false defers it: consensus_mask! sets it when needed). θ is the SCORED form (scored_model): an Uncertain under a predictive scorer, which then fills the residuals itself. Returns the score and inlier_count.
VisualGeometryToolkitCore.scored_model — Method
scored_model(scoring, problem, θ, sample) -> θ′ | nothingThe form in which a model is scored: the plain model (default), or for a predictive scorer Uncertain(θ, Σ̃θ) with the covariance of the model fit on the points sample; nothing when there is none (a degenerate sample, which is skipped like a failed solve).
VisualGeometryToolkitCore.scores — Method
The per-point scores of a ScoreBuffers.
VisualGeometryToolkitCore.scoring_workspace — Function
scoring_workspace(scoring, n::Int, d_g::Int) -> WThe scorer's own scratch for up to n points of codimension d_g, built ONCE per composed workspace and reused by every score!. scoring_workspace(buf) reads it back from a ScoreBuffers.
VisualGeometryToolkitCore.with_width — Function
with_width(x, w::WidthAxis) -> typeof(x) with the width `w`The width setter shared by scorings and local optimizations: a scoring rebuilt at a native width (with_width(scoring, OutlierHalfwidth(a))), a local optimizer given an explicit width mode (with_width(lo, EfficiencyConstant(m)), with_width(lo, LossWidth(w))). The owner of the type implements it.
VisualGeometryToolkitCore.AbstractThresholdScoring — Type
AbstractThresholdScoring{T} <: AbstractScoringA scorer whose score is a sum of per-point qualities at one threshold τ (its loss width): S = Σᵢresidual_quality(scoring, dᵢ², τ), higher is better. T is the threshold's type: Float64 at a threshold (a scorer of the scoring contract), Nothing for the width-free form, a grid family that a loss width is swept over and that implements no scoring contract.
A subtype at a threshold implements residual_quality and holds its threshold in a field threshold (or adds an decision_boundary method), and inherits the rest from AbstractThresholdScoring{Float64}:
score!on aThresholdScoringWorkspace: the one threshold loop. Σ quality over every point in index order, a non-finite squared residual an outlier (quality 0; a finitedwhose square overflows too), then each of the minimal sample's points corrected to zero residual; the consensus set isd² < τ²(strict) with the sample's points in it.scoring_workspace,inlier_count,consensus_order,decision_boundary(τ) andhas_decision_boundary(true).score_bound:nothing(no early exit) by default. A subtype states a boundbonly where it holds0 ≤ residual_quality(scoring, d², τ) ≤ bfor every finited² ≥ 0, to within a few ulps ofb(the exit's margin absorbs those). Both sides matter: the sample's points are corrected after the sum, so a negative quality could let the corrected score exceed the bound the exit tested.
Core's subtypes are RansacScoring and MsacScoring; a downstream package adds its own loss-width families (RANSACScoringDoneRight's paper baselines) the same way.
VisualGeometryToolkitCore.MsacScoring — Type
MsacScoring{DG, T} <: AbstractThresholdScoring{T}MSAC at codimension DG: the truncated quadratic 1 − ρ(d², τ²)/τ² at the threshold τ, summed over the residuals (see residual_quality). Constructors as RansacScoring: width-free MsacScoring() / MsacScoring(dg) / MsacScoring(problem), or the loop scorer MsacScoring(dg; threshold = τ).
VisualGeometryToolkitCore.RansacScoring — Type
RansacScoring{DG, T} <: AbstractThresholdScoring{T}RANSAC inlier counting at codimension DG: a model's score is the number of residuals below the threshold (see residual_quality).
RansacScoring(),RansacScoring(dg),RansacScoring(problem): the width-free grid family (T = Nothing);RansacScoring(dg; threshold = τ),RansacScoring(problem; threshold = τ): the loop scorer at thresholdτ(in the problem's residual unit — pixels for the pixel-data problems),T = Float64.
VisualGeometryToolkitCore.ThresholdScoringWorkspace — Type
ThresholdScoringWorkspaceThe workspace of a threshold scorer (an AbstractThresholdScoring at a threshold): the consensus order of the last score! (inliers first, each part in index order — a stable partition, no sort) and its size.
VisualGeometryToolkitCore.residual_quality — Function
residual_quality(scoring, d2::Float64, loss_width::Float64) -> Float64The score contribution of ONE residual with squared value d2 under a loss-width family scoring at loss_width; a model's score is the sum over its residuals, and higher is better:
- RANSAC: the inlier indicator
d² < loss_width²(TLS'sweight); - MSAC:
1 − ρ(TLSShape(), d², loss_width²)/loss_width².
RANSACScoringDoneRight adds the methods of its paper baselines (MLESAC, MAGSAC++, the loss costs). Plain Float64 functions, callable inside a kernel. A non-finite d2 is an outlier and is skipped by every caller; it is not an input.
VisualGeometryToolkitCore.@threshold_scoring_constructors — Macro
@threshold_scoring_constructors SThe constructors and the width setter of a threshold-scorer family S{DG, T} <:AbstractThresholdScoring{T} (DG its codimension, its threshold in a field threshold, an inner constructor S{DG, T}(threshold)), as RansacScoring and MsacScoring have them: S{DG}() and S() (codimension 1) the width-free form; S(dg; threshold), S(problem; threshold) and S(P; threshold) (a problem, or a problem TYPE, gives the codimension) at a threshold, refused unless positive and finite (ArgumentError), or width-free without one; and with_width(::S{DG}, w::LossWidth), the same family at w's loss width. A downstream family (RANSACScoringDoneRight's loss-width baselines) is given them by this one line after its struct, exactly as Core's two are.
The Student-t + Uniform Marginal Scorer
The scale-free marginal score of "RANSAC Scoring Done Right" is on the Student-t + Uniform Scoring API page.
Optimization Strategies and the Local-Optimization Contract
The optimization strategies (Irls, Triggs and their registry) and the local-optimization and external-refit contracts are on the Optimization Strategies API page.
Pool Selection
The pool-selection contract and its grid kernels are on the Pool Selection API page.
Index
VisualGeometryToolkitCore.AbstractConstraintProblemVisualGeometryToolkitCore.AbstractOptimizationStrategyVisualGeometryToolkitCore.AbstractScoringVisualGeometryToolkitCore.AbstractThresholdScoringVisualGeometryToolkitCore.AbstractWeightPolicyVisualGeometryToolkitCore.BinaryWeightsVisualGeometryToolkitCore.ConsensusAnchoredVisualGeometryToolkitCore.ConsensusSetVisualGeometryToolkitCore.ExternalRefitVisualGeometryToolkitCore.FixedScaleVisualGeometryToolkitCore.FollowsScorerVisualGeometryToolkitCore.FrozenNuisanceVisualGeometryToolkitCore.IrlsWeightsVisualGeometryToolkitCore.MsacScoringVisualGeometryToolkitCore.NativeRefitVisualGeometryToolkitCore.NoScaleVisualGeometryToolkitCore.NormalizedWeightPolicyVisualGeometryToolkitCore.PosteriorWeightsVisualGeometryToolkitCore.RansacScoringVisualGeometryToolkitCore.RefitFamilyVisualGeometryToolkitCore.ScaleInterfaceVisualGeometryToolkitCore.ScoreBuffersVisualGeometryToolkitCore.SelfScalingVisualGeometryToolkitCore.ThresholdScoringWorkspaceVisualGeometryToolkitCore.WeightKindVisualGeometryToolkitCore.check_freshVisualGeometryToolkitCore.check_workspaceVisualGeometryToolkitCore.codimensionVisualGeometryToolkitCore.consensus_maskVisualGeometryToolkitCore.consensus_mask!VisualGeometryToolkitCore.consensus_orderVisualGeometryToolkitCore.consensus_s2VisualGeometryToolkitCore.consensus_scoreVisualGeometryToolkitCore.consensus_setVisualGeometryToolkitCore.data_sizeVisualGeometryToolkitCore.decision_boundaryVisualGeometryToolkitCore.has_decision_boundaryVisualGeometryToolkitCore.inlier_countVisualGeometryToolkitCore.inlier_maskVisualGeometryToolkitCore.inlier_maskVisualGeometryToolkitCore.inlier_probabilities!VisualGeometryToolkitCore.inlier_weightVisualGeometryToolkitCore.is_freshVisualGeometryToolkitCore.is_inlierVisualGeometryToolkitCore.is_map_inlierVisualGeometryToolkitCore.is_predictiveVisualGeometryToolkitCore.lo_labelVisualGeometryToolkitCore.lo_markerVisualGeometryToolkitCore.loss_familyVisualGeometryToolkitCore.mahalanobis_distanceVisualGeometryToolkitCore.mahalanobis_distances!VisualGeometryToolkitCore.minimal_sample_sizeVisualGeometryToolkitCore.observation_covarianceVisualGeometryToolkitCore.optimization_pathVisualGeometryToolkitCore.outlier_halfwidthVisualGeometryToolkitCore.path_markerVisualGeometryToolkitCore.path_suffixVisualGeometryToolkitCore.provides_solver_covarianceVisualGeometryToolkitCore.refine!VisualGeometryToolkitCore.refine_workspaceVisualGeometryToolkitCore.residual_contextVisualGeometryToolkitCore.residual_qualityVisualGeometryToolkitCore.residualsVisualGeometryToolkitCore.robust_weightVisualGeometryToolkitCore.sample_point_heldVisualGeometryToolkitCore.scale_interfaceVisualGeometryToolkitCore.scale_priorVisualGeometryToolkitCore.scale_s2VisualGeometryToolkitCore.score!VisualGeometryToolkitCore.score_boundVisualGeometryToolkitCore.score_model!VisualGeometryToolkitCore.scored_modelVisualGeometryToolkitCore.scoresVisualGeometryToolkitCore.scoring_workspaceVisualGeometryToolkitCore.solver_covarianceVisualGeometryToolkitCore.unit_weightsVisualGeometryToolkitCore.update_nuisance!VisualGeometryToolkitCore.update_weights!VisualGeometryToolkitCore.weight_kindVisualGeometryToolkitCore.whitened_constraint_rowsVisualGeometryToolkitCore.whitened_residualVisualGeometryToolkitCore.whitened_residuals!VisualGeometryToolkitCore.with_widthVisualGeometryToolkitCore.@threshold_scoring_constructors