Robust Estimation API

Division of labor

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.AbstractScoring — Type
AbstractScoring

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

source
VisualGeometryToolkitCore.AbstractWeightPolicy — Type
AbstractWeightPolicy

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

source
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 — the epoch stamp, which is only ever meaningful compared against a current epoch, and so is exposed as that comparison rather than as a raw number.
source
VisualGeometryToolkitCore.FrozenNuisance — Type
FrozenNuisance() <: AbstractWeightPolicy

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

source
VisualGeometryToolkitCore.NormalizedWeightPolicy — Type
NormalizedWeightPolicy <: AbstractWeightPolicy

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

source
VisualGeometryToolkitCore.RefitFamily — Type
RefitFamily(lo::AbstractOptimizationStrategy) -> RefitFamily

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

source
VisualGeometryToolkitCore.ScaleInterface — Type
ScaleInterface

The 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 sets loss_width = efficiency_constant·ŝ (the EfficiencyConstant width mode), cross-validating only the dimensionless efficiency_constant.
  • FixedScale — one ABSOLUTE loss width for every hypothesis (the LossWidth width 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, ℓ₂).
source
VisualGeometryToolkitCore.check_fresh — Method
check_fresh(cs::ConsensusSet, epoch::Integer) -> nothing

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

source
VisualGeometryToolkitCore.consensus_score — Method
consensus_score(cs::ConsensusSet) -> Float64

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

source
VisualGeometryToolkitCore.inlier_count — Method
inlier_count(cs::ConsensusSet) -> Int
inlier_count(scoring, W) -> Int

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

source
VisualGeometryToolkitCore.inlier_weight — Function
inlier_weight(policy) -> AbstractVector

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

source
VisualGeometryToolkitCore.is_fresh — Method
is_fresh(cs::ConsensusSet, epoch::Integer) -> Bool

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

source
VisualGeometryToolkitCore.is_inlier — Function
is_inlier(policy, i::Integer) -> Bool

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

source
VisualGeometryToolkitCore.is_map_inlier — Method
is_map_inlier(posterior_weight) -> Bool

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

source
VisualGeometryToolkitCore.lo_label — Method
lo_label(lo::AbstractOptimizationStrategy) -> String

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

source
VisualGeometryToolkitCore.loss_family — Method
loss_family(lo::AbstractOptimizationStrategy) -> Symbol

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

source
VisualGeometryToolkitCore.optimization_path — Method
optimization_path(lo::AbstractOptimizationStrategy) -> Symbol

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

source
VisualGeometryToolkitCore.robust_weight — Function
robust_weight(policy) -> AbstractVector

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

source
VisualGeometryToolkitCore.scale_interface — Method
scale_interface(lo::AbstractOptimizationStrategy) -> ScaleInterface

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

source
VisualGeometryToolkitCore.update_nuisance! — Function
update_nuisance!(policy::AbstractWeightPolicy) -> policy

Refresh 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! → check

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

source
VisualGeometryToolkitCore.weight_kind — Function
weight_kind(result) -> WeightKind
weight_kind(::Type{P}) -> WeightKind

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

source

Problem Protocol

VisualGeometryToolkitCore.AbstractConstraintProblem — Type
AbstractConstraintProblem

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

source
VisualGeometryToolkitCore.codimension — Function
codimension(problem) -> Int

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

source
VisualGeometryToolkitCore.mahalanobis_distance — Method
mahalanobis_distance(problem, ctx, i) -> Real

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

source
VisualGeometryToolkitCore.observation_covariance — Method
observation_covariance(problem, i) -> Σ̃_x

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

source
VisualGeometryToolkitCore.refine! — Function
refine!(R, problem, θ, w) -> θ′ | nothing

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

source
VisualGeometryToolkitCore.refine_workspace — Function
refine_workspace(::Type{P}, n::Int) -> R

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

source
VisualGeometryToolkitCore.residual_context — Method
residual_context(problem, model) -> ctx

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

source
VisualGeometryToolkitCore.solver_covariance — Method
solver_covariance(problem, model, sample_indices) -> SMatrix or nothing

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

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

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

source
VisualGeometryToolkitCore.whitened_residuals! — Method
whitened_residuals!(r, problem, model) -> r

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

source

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

source
VisualGeometryToolkitCore.check_workspace — Method
check_workspace(scoring, W) -> nothing

Refuse, 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.

source
VisualGeometryToolkitCore.decision_boundary — Function
decision_boundary(scoring, buf::ScoreBuffers) -> Float64

The 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 whatever buf holds;
  • 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-width h, 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)).

source
VisualGeometryToolkitCore.outlier_halfwidth — Method
outlier_halfwidth(scoring) -> Float64 | nothing

The half-width of the scorer's uniform outlier model, if it has one (the Student-t + uniform posterior weights read it); nothing otherwise (default).

source
VisualGeometryToolkitCore.sample_point_held — Method
sample_point_held(x) -> Bool

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

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

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

source
VisualGeometryToolkitCore.score_bound — Method
score_bound(scoring) -> Float64 | nothing

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

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

source
VisualGeometryToolkitCore.scored_model — Method
scored_model(scoring, problem, θ, sample) -> θ′ | nothing

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

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

source
VisualGeometryToolkitCore.AbstractThresholdScoring — Type
AbstractThresholdScoring{T} <: AbstractScoring

A 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 a ThresholdScoringWorkspace: the one threshold loop. Σ quality over every point in index order, a non-finite squared residual an outlier (quality 0; a finite d whose square overflows too), then each of the minimal sample's points corrected to zero residual; the consensus set is d² < τ² (strict) with the sample's points in it.
  • scoring_workspace, inlier_count, consensus_order, decision_boundary (τ) and has_decision_boundary (true).
  • score_bound: nothing (no early exit) by default. A subtype states a bound b only where it holds 0 ≤ residual_quality(scoring, d², τ) ≤ b for every finite d² ≥ 0, to within a few ulps of b (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.

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

source
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.
source
VisualGeometryToolkitCore.residual_quality — Function
residual_quality(scoring, d2::Float64, loss_width::Float64) -> Float64

The 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's weight);
  • 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.

source
VisualGeometryToolkitCore.@threshold_scoring_constructors — Macro
@threshold_scoring_constructors S

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

source

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