Scoring API
The RANSAC loop scores through VisualGeometryToolkitCore's scoring contract. The contract, its derived verbs and the baseline scorers are VisualGeometryToolkitCore's and documented in its manual; this page lists them because the loop is built on them. Paper scorers (the Student-t + uniform marginal StudentTUniformScoring) are RANSACScoringDoneRight's and are documented there.
The scoring contract
A scorer implements the required verbs; the optional ones default in VisualGeometryToolkitCore: AbstractScoring, scoring_workspace, score!, consensus_order, is_predictive, scored_model, scale_prior, outlier_halfwidth (each with one method per scorer family: VisualGeometryToolkitCore's Robust Estimation API), decision_boundary, has_decision_boundary and check_workspace.
Derived verbs and buffers
Stated once in VisualGeometryToolkitCore for every scorer: the loop's one scoring path (ScoreBuffers, score_model!), the consensus set the local optimization starts from (ConsensusSet, inlier_count, consensus_set), its scale (consensus_s2), and the result's soft weights (inlier_probabilities!).
Baseline scorers
MSAC and RANSAC at a threshold, MsacScoring and RansacScoring, with their residual_quality. MSAC ([pipelines.<class>] scoring) is the default scorer of every find_* pipeline.
SIMFIT++ loss-width estimation
A step-for-step port of SIMFIT++ (Edstedt (2025); the reference implementation is Parskatt/simfitpp): the noise scale of a robust fit, hence the loss width it runs at, estimated from held-out residuals so that the fit's own bias does not shrink it. The geometry estimator is a pair of callbacks, so the same loop runs on a full RANSAC refit (simfitpp_loss_width) or on a fixed hypothesis pool (simfitpp_select, the paper's protocol: the MSAC-best pool model on the train split). SimFitPP holds the reference's defaults (coverage alpha = 0.99, loss-width bounds 0.25–8 in the residuals' unit, pixels in the reference); the pair method of simfitpp_select therefore runs on the pool's pixel residuals (VisualGeometryToolkitCore's Pools.pixel_residuals).
VisualGeometryToolkitEstimation.SimFitPP — Type
SimFitPP(; alpha, max_iter, ftol, train_fraction, min_loss_width, max_loss_width, dg)SIMFIT++ configuration (Edstedt (2025); the reference calls the loss width its threshold). Every keyword defaults to configs/default.toml's [simfitpp] table, which holds the reference's constructor defaults. alpha is the inlier coverage the loss width targets (losswidth² = ppf{χ²dg}(alpha)·σ²); `minlosswidthandmaxloss_widthbound an acceptable loss width in the residual unit of the residuals handed to the estimator (pixels in the reference);dg` is the residual codimension (the χ² degrees of freedom).
VisualGeometryToolkitEstimation.simfitpp_loss_width — Function
simfitpp_loss_width(fit, residuals_sq, n, initial_loss_width, cfg = SimFitPP();
num_previous_est = 0, rng = Random.default_rng())
-> (loss_width, success::Bool)The reference's SIMFITPP.__call__ (Edstedt (2025)) over n correspondences. fit(loss_width, train) estimates the geometry from the correspondences indexed by train at loss_width and returns a model handle (or nothing on failure); residuals_sq(model, val) returns the squared residuals of that model on the held-out indices val (or nothing). initial_loss_width seeds the iteration and is returned unchanged when the estimate fails (success == false); with num_previous_est = p > 0 earlier estimates behind initial_loss_width, the successful estimate is filtered as exp(log(loss_width)/(p+1) + p·log(initial_loss_width)/(p+1)).
VisualGeometryToolkitEstimation.simfitpp_select — Function
simfitpp_select(residuals::AbstractMatrix, initial_loss_width, cfg = SimFitPP();
num_previous_est = 0, rng = default_rng())
-> (best_idx, loss_width, success)
simfitpp_select(pair::PoolPair, initial_loss_width_px, cfg = SimFitPP(); ...)SIMFIT++ (Edstedt (2025)) on a fixed hypothesis pool: residuals is the pool's n×M residual matrix (points × models) in the unit initial_loss_width and the bounds of cfg are expressed in. The geometry "estimator" is the MSAC-best pool hypothesis on the train split at the current loss width, scored by its validation-split residuals; the returned index is the MSAC argmax over ALL points at the final loss width (0 for an empty pool).
The pair method is PIXELS in, pixels out: it runs on VisualGeometryToolkitCore's Pools.pixel_residuals(pair), the pool models' residuals in pixels, so initial_loss_width_px, the bounds of cfg (the reference's pixel defaults, 0.25–8 px) and the returned loss width are all pixels. To work in the pool frame's unit instead, call the matrix method on the pair's stored residual matrix with bounds in that unit (with_residual_unit).
VisualGeometryToolkitEstimation.unbiased_median_variance — Function
unbiased_median_variance(residuals_sq, sq_loss_width; dg = 1) -> σ²The reference's UnbiasedMed (Edstedt (2025)): the noise variance from the squared residuals below sq_loss_width, corrected for the truncation. With med the median of the kept residuals and ratio = sq_loss_width / med, the quantile q that the truncated median corresponds to under χ²dg solves q = F(ratio · F⁻¹(q)) / 2, iterated five times from q = 1/2; the estimate is med / F⁻¹(q). For dg == 1 a ratio below 5 has no useful fixed point and the naive med / F⁻¹(1/2) is returned (the reference's `minratio). ReturnsNaN` when no residual lies below the loss width.
It returns σ², not σ, as its name says (VisualGeometryToolkitCore's s2 convention: a squared scale is named as one).
VisualGeometryToolkitEstimation.with_residual_unit — Function
with_residual_unit(cfg::SimFitPP, unit_scale) -> SimFitPPThe same configuration with the loss-width bounds expressed in another residual unit. min_loss_width/max_loss_width are multiplied by unit_scale (e.g. VisualGeometryToolkitCore's Pools.pool_pixel_scale(pair) to carry the reference's pixel bounds into a pool stored in the pool frame).
Scale priors
The prior a scorer's consensus scale is computed under (scale_prior, Jeffreys by default): IGPrior and JeffreysPrior.
Weight policies
AbstractWeightPolicy and NormalizedWeightPolicy are VisualGeometryToolkitCore's.
Local Optimization
A strategy implements VisualGeometryToolkitCore's local-optimization contract (lo_workspace, locally_optimize!, returning lo_estimate). The core strategies are nothing (no local optimization), Irls and Triggs — the robustified chart LM: one NLLSsolver solve under a loss, through NLLSsolver's robustified Hessian, its width efficiency_constant·ŝ at the hypothesis's Student-t scale, for every chart problem; every other strategy is LocalOptimizationDoneRight's. A width-carrying strategy's loss is resolved by loss_at from its width mode (lo_width, set by with_width): no width follows the scorer's decision_boundary, EfficiencyConstant(m) anchors it at the consensus scale, LossWidth(w) fixes it.
The contract is VisualGeometryToolkitCore's: AbstractOptimizationStrategy, lo_workspace, lo_width, with_width, loss_at, check_composition, EfficiencyConstant and LossWidth. The methods of locally_optimize! for this package's strategies are documented here.
VisualGeometryToolkitCore.locally_optimize! — Function
locally_optimize!(L, lo::Irls, problem, model, cs, buf, scoring) -> FitResultStatic M-estimation on the posterior-weight iteration (posterior_irls!): VGC's weight on the loss the width mode deploys (lo_loss), frozen (LossPlainWeights). The seed state's outlier model is the scorer's when it has one; any finite value serves otherwise (MSAC), since the frozen weights replace the seed's before the first solve.
A datum whose squared residual is not finite weighs 0 under every shape. Irls{GaussianShape} (least squares, which no outlier may enter) weighs only the scorer's consensus set cs — consensus_mask!(buf, scoring), the first inlier_count(cs) of the scorer's consensus_order — at unit weight: the LO-RANSAC refit on the inliers. The robust shapes weigh every datum.
locally_optimize!(L, lo::Triggs, problem::MinimalSolveProblem, model, cs, buf, scoring) -> FitResultThe robustified chart LM: the loss the width mode deploys (lo_loss: efficiency_constant·ŝ at θ's Student-t scale), frozen, as VisualGeometryToolkitCore's loss_robustifier, and ONE lmsolve_chart! from model over every datum at unit weight, on the chart-LM refit's own chart and state (_chart, _refit_state: the rows refine! descends) in its workspace (L.refine, the one reuse policy) at Core's LM stop settings (LmStops, [lm]). NLLSsolver's Triggs correction carries the loss; nothing is reweighted during the LM and no inlier set is formed (the loop's re-score decides the inliers). The model comes back through the chart's recenter and _model_at, as from refine!.
The two weight rules of Irls{K}'s locally_optimize! fix the one LM's per-datum weights, 0 or 1 (unit weight on every row when neither excludes a datum): a datum whose residual at model (buf.residuals on entry) is not finite weighs 0 under every shape — its row would make the LM's cost infinite at its start and hand back the seed — and Triggs{GaussianShape} weighs only the scorer's consensus set cs. The weights are fixed at the seed for the whole LM (a datum an LM increment puts out of reach keeps its weight; the increment's cost is non-finite and it is rejected). A zero weight gives an exactly zero row whatever the problem's row is (_chart_refit's zero-weight row rule).
VisualGeometryToolkitEstimation.default_local_optimization_strategy — Function
default_local_optimization_strategy(scoring::AbstractScoring) -> AbstractOptimizationStrategyDefault local-optimization strategy for a scoring function: nothing (no local optimization).
Placement and instrumentation
A strategy runs inside the loop, on every candidate that enters the local-optimization gate, unless it is placed at the end: TerminalLO runs its inner strategy once on the final incumbent of a race decided on raw hypothesis scores. CountedLO counts a strategy's calls in either placement, and records each call's iterations, ReturnCode and StopRule (call_records).
VisualGeometryToolkitEstimation.TerminalLO — Type
TerminalLO(inner::AbstractOptimizationStrategy) <: AbstractOptimizationStrategy
TerminalLO(; inner)The TERMINAL placement of a local optimization: ransac decides its incumbent race on raw-hypothesis scores alone, exactly as with no local optimization (nothing; same trials, scores and on_improvement events on the same rng), and after the loop runs inner ONCE on the final incumbent through the seeded path of locally_optimize — the same scorer, inside ransac's wall time. The result is that seeded refine's:
estimate: the refined model, or the raw incumbent when the refined model failstest_consensus(aslocally_optimizekeeps its seed) or the incumbent's consensus set is too thin to refine (its refit's record(InitialFailure, NoRule)). The refined model is kept even if it scores below the raw incumbent (there is noscore_guardat the terminal placement);lo_retcode,lo_stop_rule: the inner strategy's record ((ReturnCode.Default, NoRule)when no local optimization ran for the reported model);residuals,weights,quality,scale,dof,n,rms: the reported model re-scored under the scorer;iterationsandsample_acceptance_rate: the raw race's.
A race that keeps no hypothesis returns its :no_model result unrefined, and an incumbent the scorer cannot score as a seed (a predictive scorer with no covariance on its consensus set) the raw race's result. score_guard = true is an ArgumentError: the guard is a per-candidate acceptance rule and the terminal placement has no candidate to accept. A seeded locally_optimize with a TerminalLO runs inner (a seed has no race).
Every hook the loop, the composition check, the reporting and an external refit read answers as inner's (width, scale interface, loss family, path, marker, workspace, RefitFamily and the external-refit bracket), except the label, "<inner label> (terminal)", so result records tell the placements apart. TOML: { type = "terminal_lo", inner = { … } }, the inner table any registered strategy's. Counting: CountedLO(TerminalLO(inner)) and TerminalLO(CountedLO(inner)) both count the one terminal call per run that keeps a hypothesis (no LO runs inside the race). A wrapper of TerminalLO must forward lo_placement, or ransac runs it in the loop.
VisualGeometryToolkitEstimation.lo_placement — Function
lo_placement(lo) -> InLoopPlacement() | TerminalPlacement()Where ransac runs the strategy lo, dispatched statically in the loop: InLoopPlacement() by default, TerminalPlacement() for a TerminalLO. A wrapper must forward it to the strategy it wraps (as CountedLO does): a wrapper of a TerminalLO that does not runs it in the loop's placement.
VisualGeometryToolkitEstimation.InLoopPlacement — Type
InLoopPlacement()The placement (lo_placement) of a strategy ransac runs on every candidate that enters the local-optimization gate: every strategy's default.
VisualGeometryToolkitEstimation.TerminalPlacement — Type
TerminalPlacement()The placement (lo_placement) of a strategy ransac runs once, on the final incumbent of a raw race: TerminalLO.
VisualGeometryToolkitEstimation.CountedLO — Type
CountedLO(inner::AbstractOptimizationStrategy)Instrumentation wrapper: counts the locally_optimize! invocations (calls[]) and the iterations they report (iterations[], the sum of iterations(result)), and records each invocation's termination in call_records, a Vector of (; iterations, retcode, stop_rule) (the call's iterations(result), its ReturnCode and its StopRule), one entry per call. It answers every hook the RANSAC loop, the scorer composition check, the reporting and an external refit read on a strategy exactly as inner does — its RefitFamily, placement and external-refit bracket included — so a run with CountedLO(inner) returns the model a run with inner returns. An external refit (refine_external!) is forwarded uncounted. It is not a registered strategy (no TOML tag): it carries counters, not configuration. A counter is shared by every run that is handed the same wrapper — the counters are Threads.Atomic{Int} and call_records is appended under a lock, so runs on several threads (a threaded sweep over pairs) add up exactly (the records then in the threads' order); build a fresh one per experiment, and read call_records once its runs have returned.
Loss resolution
The core strategies resolve the loss they deploy through VisualGeometryToolkitCore's helpers — lo_loss, strategy_loss, fixed_width and lo_width_value; a downstream strategy can use them to follow the same width rules. This package adds the rescored local optimization:
VisualGeometryToolkitEstimation.locally_optimize_rescored! — Function
locally_optimize_rescored!(L, lo, problem, θ, buf::ScoreBuffers, scoring) -> FitResultThe loop's Phase-2 step from a score under ANOTHER scoring: re-score θ under scoring on the buffers buf (score_model!), then — when its consensus set is stable (more than m + 1 points; otherwise θ comes back unrefined, :thin_partition) — run lo on its workspace L from that consensus set. The building block of a strategy that refits at a scoring of its own inside a loop (VisualGeometryToolkitEval's RefitHalfwidth).
Lifted local optimization
The chart problems provide VisualGeometryToolkitCore's chart-rows contract, which the half-quadratic lifts of LocalOptimizationDoneRight consume; a lifted strategy's locally_optimize! methods dispatch on the MinimalSolveProblem family.
VisualGeometryToolkitEstimation.ManifoldLiftProvider — Type
ManifoldLiftProvider{P, D, C, X}The chart-rows provider (VisualGeometryToolkitCore's rows_provider) of a problem P on a D-dof chart with codimension-C residuals: the problem, its rows (VGC RowsWorkspace{D, C}, one per (task, size)), the point count, and the problem's frozen per-run data aux (nothing unless the problem has some — PnP's pixel block).