Optimization Strategies API

The optimization strategies a fit, a refine and a local optimization take (Irls{K}, Triggs{K}, their efficiency constants and the strategy registry), and the local-optimization and external-refit contracts. The problem and scoring contracts they work with are on the Robust Estimation API page.

Optimization Strategies

VisualGeometryToolkitCore.LOSS_TAGS — Constant
LOSS_TAGS

The loss-shape registry (a TagRegistry, family suffix Shape): TOML loss tag → shape type, read off the one loss-identity table (_LOSS_TABLE).

source
VisualGeometryToolkitCore.Irls — Type
Irls{K<:AbstractLossShape} <: AbstractOptimizationStrategy

STATIC IRLS at a frozen loss width — direct iteratively-reweighted least squares on loss K, no lift, no graduation. Irls{K} is an LO STRATEGY: one instance of VisualGeometryToolkitCore's generic block_coordinate_descent! loop, which is not itself "IRLS" (it also runs EM, the half-quadratic lifts and GNC). Runs the posterior-weight iteration (VisualGeometryToolkitEstimation's posterior_irls!) — the PosteriorIrlsMethod / PosteriorIrlsState, same weighted refine! M-step (the problem's chart LM), same best-cost tracking and stop rule — with only the per-iteration weight functor swapped per loss:

  • Irls{WelschShape}: wᵢ = exp(−rᵢ²/loss_width²), loss_width = efficiency_constant·ŝ (the paper's Welsch-IRLS arm; 1.5 was the pre-anchoring point)
  • Irls{HuberShape}: wᵢ = min(1, loss_width/|rᵢ|), loss_width = efficiency_constant·ŝ (the elbow; 1.345 is the classical value) — the static-tail control (influence constant, never vanishing, past the elbow)
  • Irls{GemanMcclureShape}: wᵢ = (loss_width²/(loss_width²+rᵢ²))², loss_width = efficiency_constant·ŝ — the GM static-reweighting arm
  • Irls{GaussianShape}: unit weights, no scale and NO efficiency constant — plain least squares over the scorer's consensus set (LO-RANSAC's least squares on the inliers; VisualGeometryToolkitEstimation ≥ 0.11.2), a datum outside it or with a non-finite squared residual at weight 0. It takes no efficiency_constant; supplying one is an ArgumentError (a width it would silently ignore)

The loss width is frozen at the start of the call, set by the width mode W (VisualGeometryToolkitCore's loss_at) — no per-iteration scale refit:

  • efficiency_constant = m (EfficiencyConstant(m)): m·ŝ at the consensus set's Student-t scale ŝ — m the plain multiple, for every loss;
  • loss_width = w (LossWidth(w)): the absolute width w;
  • neither (nothing, the default): the scorer's decision point (decision_boundary) for a shape with a decision width — MSAC with Irls{TLSShape} refits at MSAC's threshold —, and for one without (Huber) the table's efficiency_constant(K, d) times the consensus scale ŝ, d the scorer's codimension (a shape with neither is an ArgumentError).

Fields

  • max_iter::Int=25: max IRLS iterations per hypothesis
  • width::W: the width mode, nothing | EfficiencyConstant{Float64} | LossWidth{NTuple{2,Float64}}
source
VisualGeometryToolkitCore.Triggs — Type
Triggs{K<:AbstractLossShape} <: AbstractOptimizationStrategy

The ROBUSTIFIED LEVENBERG–MARQUARDT strategy: from a guess θ, ONE NLLSsolver.jl LM over all the data minimizing Σᵢ ρ(‖rᵢ‖²), robustified per datum by loss K through loss_robustifier (Triggs{GaussianShape} in a RANSAC's local optimization: over the scorer's consensus set, below). A datum whose residual at the hypothesis is not finite weighs 0 under every shape, and the weights are fixed at the hypothesis for the one LM. Triggs{K} is a strategy (configuration) type only: it selects the loss shape and its width; how the robustified LM is formed is NLLSsolver's. There is no reweighting loop and no inlier set inside the solve: θ is the initial guess and the loss decides each datum's influence. A RANSAC problem's implementation (VisualGeometryToolkitEstimation) runs it as the local optimization of every chart problem.

The loss width is loss_width = efficiency_constant·ŝ (the plain multiple, as for Irls), frozen at the start of the call: ŝ is the Student-t marginal scale of θ's residuals — the Sampson errors of all the data — over θ's consensus partition (VisualGeometryToolkitCore's partition_student_t, the scorer's scale_s2), the scale every consensus-anchored strategy reads. With no efficiency_constant (Triggs{K}()) inside a RANSAC the width follows the scorer's decision_boundary, as for Irls; in a refine (VisualGeometryToolkitEstimation's refine_*) it is efficiency_constant(K, d) times the caller's scale: a refine reads its scale from the caller, never from a consensus set. An absolute loss_width is an ArgumentError from a keyword or a TOML table. An absolute width reaches it only through with_width, for fixed_width's freeze — with_width(lo, fixed_width(lo, s2)), the loss the consensus-anchored strategy would deploy at ŝ² = s2 (the role-isolated controls).

K is any shape Irls admits — the zero-argument shape tags: Welsch (the pipelines' default), Geman–McClure, Cauchy, smooth TLS, TLS, Huber and Gaussian; Barron, whose shape carries its α, is refused by both. Triggs{GaussianShape} is the plain chart LM: like Irls{GaussianShape} it has no width and takes no efficiency_constant. As a RANSAC's local optimization (VisualGeometryToolkitEstimation 0.11.3 on) it refits the scorer's consensus set at the hypothesis, not every datum; in a refine, every datum the caller gives.

Fields

  • width: the width mode, set by efficiency_constant = c (EfficiencyConstant), or nothing (no constant stated; always for Triggs{GaussianShape})
source
VisualGeometryToolkitCore.fixed_width — Method
fixed_width(lo, s2) -> LossWidth

The absolute width mode of a strategy deployed at EfficiencyConstant(m) with the consensus scale held at s2: LossWidth(m, s2) — so with_width(lo, fixed_width(lo, s2)) deploys exactly the loss the consensus-anchored strategy would at ŝ² = s2 (the role-isolated controls: solo CV, oracle scale, the anchoring ablation).

source
VisualGeometryToolkitCore.lo_absent — Method
lo_absent(T, Val(f); defaults)

Field f of strategy T when the caller omits it: the strategy's defaults[lo_tag(T)] key lo_key(T, Val(f)), converted by lo_field_from_toml; with no such key the field is required (UndefKeywordError). The width field defaults to nothing (follow the scorer). A downstream method is per field (::Val{:x}): a method on Val{F} for every field of its type is ambiguous with the Val{:width} catch-all below.

source
VisualGeometryToolkitCore.lo_admits — Method
lo_admits(T, K) -> nothing

Construction-time admission of strategy type T, called before any field is read. K is the type parameter of a loss-parametric family — the loss K of Irls{K}, or the inner strategy of a wrapper (LocalOptimizationDoneRight's Gnc{S}) — and nothing for any other strategy. The default admits every non-parametric strategy and checks a family's shape with lo_admits_shape; a family with further conditions adds a method (LocalOptimizationDoneRight's half-quadratic lift and GNC surrogate checks). Throws ArgumentError.

source
VisualGeometryToolkitCore.lo_admits_shape — Method
lo_admits_shape(T, K) -> nothing

Construction-time admission of loss shape K by strategy type T (named in the message): K must be a zero-argument shape tag, so a shape the mechanism cannot run is refused when the strategy is built, rather than surfacing mid-RANSAC as a MethodError from a VisualGeometryToolkitCore internal the caller never wrote (BarronShape() for a shape that carries its α). The admissible set is read off VisualGeometryToolkitCore's own traits, never re-listed. The default of lo_admits for a loss-parametric family; a family with further conditions (a half-quadratic lift, a GNC surrogate) calls it first. An ArgumentError when K is not admitted.

source
VisualGeometryToolkitCore.lo_construct — Method
lo_construct(T; defaults = lo_defaults(T), kw...) -> T

THE keyword constructor of every registered strategy (@lo_registry defines T(; kw...) as this call): each field is its keyword or, omitted, its defaults value (lo_absent); the width is spelled efficiency_constant or loss_width (both is an ArgumentError; neither follows the scorer). The hooks lo_admits, lo_field and lo_validate state the per-strategy exceptions. defaults is the [optimization_strategy] table, keyed by tag. An unknown keyword is an ArgumentError.

source
VisualGeometryToolkitCore.lo_efficiency_constant_shape — Method
lo_efficiency_constant_shape(T) -> Type{<:AbstractLossShape}

The loss shape a TOML efficiency_constant of strategy T is read for (and a named one, "cross_validated", tuned for): a loss-parametric family's strategy_loss, a fixed-loss arm's @lo_registryshape column. An ArgumentError for a strategy that has neither.

source
VisualGeometryToolkitCore.lo_field — Method
lo_field(T, Val(f), v)

Field f of strategy T from a value the caller supplied by keyword. Default: convert(fieldtype(T, f), v); the width field goes through lo_width_value. A downstream method is per field (::Val{:x}): a method on Val{F} for every field of its type is ambiguous with the Val{:width} catch-all below.

source
VisualGeometryToolkitCore.lo_field_from_toml — Method
lo_field_from_toml(T, Val(f), v)

Field f of strategy T from a TOML value — a key of the caller's table or of the defaults table. Default: VisualGeometryToolkitCore's convert_field(fieldtype(T, f), v). A field whose TOML spelling differs from its value adds a method (LocalOptimizationDoneRight's GNC entry, "r_max" for NaN).

source
VisualGeometryToolkitCore.lo_key — Method
lo_key(T, Val(f)) -> String

The key of the defaults table field f of strategy T defaults from. Default: VisualGeometryToolkitCore's toml_key(T, f) (Greek spelled ASCII). A strategy whose field defaults from another key adds a method (LocalOptimizationDoneRight's smooth-TLS lift, max_iter_smooth_tls).

source
VisualGeometryToolkitCore.lo_loss — Method
lo_loss(lo, cs::ConsensusSet, scoring, buf) -> DeployedLoss

The loss a loss-parametric strategy (Irls{K}, and downstream families with a strategy_loss) deploys: its shape at the width its mode resolves to (VisualGeometryToolkitCore's loss_at: the consensus scale times its multiple, an absolute width, or the scorer's decision point). The least-squares arm has no scale and no width: it deploys at s2 = Inf, efficiency_constant = 1 (its weights are unit whatever the width).

source
VisualGeometryToolkitCore.lo_tag — Function
lo_tag(T) -> String
lo_tag(lo) -> String

The TOML tag of a registered strategy type or loss-parametric family (its @lo_registry row): the type a config spells it by and the [optimization_strategy.<tag>] table its keyword defaults read.

source
VisualGeometryToolkitCore.lo_width_value — Method
lo_width_value(w) -> w

A local optimization's width mode, checked: nothing (follow the scorer), EfficiencyConstant(m) or LossWidth(w) — never an outlier half-width (a scorer's). Anything else is an ArgumentError.

source
VisualGeometryToolkitCore.strategy_loss — Method
strategy_loss(lo_or_type) -> Type{<:AbstractLossShape}

The loss-shape tag of a loss-parametric strategy (Irls{K}; downstream families add methods: LocalOptimizationDoneRight's HQ{K}, Gnc{S}). Read off the TYPE, so a wrapper recurses into its inner strategy.

source
VisualGeometryToolkitCore.@lo_registry — Macro
@lo_registry rows defaults = table [retired = (old => new, …)]

Register the local-optimization strategies of rows and return their VisualGeometryToolkitCore TagRegistry (family :optimization_strategy, the TOML path local_optimization_strategy.type): const OPTIMIZATION_STRATEGY_TAGS = @lo_registry ROWS defaults = …. Each row is

(T, tag, path, scale_interface, loss_family, label, shape, parametric)

with nothing for a fact that is derived rather than stated. defaults is an expression evaluated, in the calling module, each time a default is read: the [optimization_strategy] table of the caller's defaults file, keyed by tag. retired lists retired tags with their successors; none = true adds the tag "none" → nothing (no local optimization; this package's registry holds it, so a merge with a downstream one holds it once).

The expansion is one call, made at load time in the calling module. Per row it defines lo_tag, lo_defaults, VisualGeometryToolkitCore's toml_skip_fields and, for a stated path, optimization_path (the width is written as its two keys, never as width); for a parametric row lo_parametric; for a stated scale interface, loss family or label the Core accessor; for a stated shapelo_efficiency_constant_shape and the loss family of that shape; and, for a strategy with fields, the keyword constructor T(; kw...) (T{K}(; kw...) for a parametric family) as lo_construct. A macro rather than a function because it defines methods in the caller's module. Every method it adds is on a declared contract generic.

source

Local-Optimization and External-Refit Contracts

VisualGeometryToolkitCore.efficiency_constant — Method
efficiency_constant(lo::AbstractOptimizationStrategy, d::Integer) -> Float64

The efficiency constant strategy lo multiplies a noise scale by at the residual's codimension d (loss_width = c × scale, c always the plain multiple): the strategy's own (its width mode EfficiencyConstant(c)), else the table's efficiency_constant(K, d) of the shape K a strategy's constant is read for (lo_efficiency_constant_shape: Irls{K}'s and Triggs{K}'s K, a fixed-loss arm's registry shape). An ArgumentError for a shape with no constant (a truncation: TLS, Le–Zach) when the strategy states none, and for an absolute width in the strategy (LossWidth, which no scale multiplies). The one rule of every stage that deploys a strategy at a given scale (Estimation's refines and fits, PoseLib's refiners).

source
VisualGeometryToolkitCore.external_workspace — Method
external_workspace(lo, problem, frame, scoring) -> ws

The per-(pair, arm) workspace of an external refiner lo (see refine_external!): whatever the solver reads beyond the problem — from the two-view frame (frame.Kc1, frame.Kc2, frame.cs; see the contract above) a point matrix, the solver's calibrations, a consensus workspace — built once and reused by every refit of that pair. Default nothing.

source
VisualGeometryToolkitCore.lo_estimate — Method
lo_estimate(model, code::ReturnCode.T, rule::StopRule; iterations = 0, residuals_current = false) -> FitResult{M, LoInfo}
lo_estimate(model, retcode::Symbol, rule::StopRule; iterations = 0, residuals_current = false)

The lean result of one local-optimization refit — what locally_optimize! and a block_coordinate_result return. estimate is the refined model; its termination record (the FitResult core's retcode and stop_rule) is why the refit stopped. No LO ran (the strategy nothing): (Success, ClosedForm), the seed returned as it is; the consensus set has no residual dof, so no LO ran: (InitialFailure, NoRule); a refit that failed (the incumbent returned): (Failure, NonFinite); otherwise the optimizer's record. A loop that reports a legacy Symbol supplies it with its success rule, retcode_from_symbol(retcode, rule) (the one map; the second form). The refit computes no residual summary, so rms is NaN and n is 0. Zero heap allocation when M is isbits.

source
VisualGeometryToolkitCore.lo_width — Method
lo_width(lo) -> nothing | EfficiencyConstant{Float64} | LossWidth{NTuple{2,Float64}}

The width mode of a width-carrying local optimizer: nothing (follow the scorer's decision_boundary), EfficiencyConstant(m) (the loss width m·ŝ at the consensus scale) or LossWidth (an absolute width). The owner of the strategy implements it; a strategy with no width mode (the seed, a self-scaling optimizer) keeps the default missing.

source
VisualGeometryToolkitCore.lo_workspace — Method
lo_workspace(::Type{P}, ::Type{T}, lo, n::Int) -> L

The local optimizer's own scratch and per-call state for problems of type P with up to n points at storage precision T, built ONCE per composed workspace and reset by each call. Default nothing (an optimizer that needs none; also nothing, no local optimization).

source
VisualGeometryToolkitCore.locally_optimize! — Function
locally_optimize!(L, lo, problem, θ, cs::ConsensusSet, buf::ScoreBuffers, scoring) -> FitResult

Refine the hypothesis θ of problem with the strategy lo on its workspace L (lo_workspace), seeded by the consensus set cs of the score that just ran on buf. Returns lo_estimate(θ′, code, rule; iterations, residuals_current): θ′ === θ when nothing was refit; residuals_current when residuals(buf) holds θ′'s residuals on exit (the loop then skips recomputing them).

source
VisualGeometryToolkitCore.loss_at — Method
loss_at(lo, shape, cs::ConsensusSet, scoring, buf::ScoreBuffers) -> DeployedLoss

THE resolution of a width-carrying local optimizer's loss, statically dispatched on its width mode lo_width:

  • nothing (follow the scorer): for a shape with a decision_width method (Welsch, Geman–McClure, Cauchy, smooth TLS, TLS, Barron), deploy(shape, w²; efficiency_constant = 1) with w = decision_width(shape, decision_boundary(scoring, buf)) — the loss's decision boundary at the scorer's (the identity for TLSShape): a threshold scorer's constant threshold, or the Student-t + uniform scorer's MAP crossover at the current consensus scale and its outlier half-width, re-estimated with every score; for a shape without one (Huber), deploy(shape, ŝ²; efficiency_constant = efficiency_constant(shape, codimension(scoring))) — the table's constant at the consensus scale; a shape with neither is an ArgumentError;
  • EfficiencyConstant(m): deploy(shape, ŝ²; efficiency_constant = m), ŝ² = max(scale_s2(cs), eps()) — the consensus-anchored width, m always the plain multiple (loss_width = m·ŝ) whatever the shape;
  • LossWidth((m₀, s2)): deploy(shape, max(s2, eps()); efficiency_constant = m₀) — the absolute width.
source
VisualGeometryToolkitCore.prepare_external! — Method
prepare_external!(ws, lo, problem, θ, width::LossWidth, scoring) -> Bool

The part of an external refit that runs OUTSIDE its timing bracket, before it (a consensus-scale bootstrap). false means no refit is made — the call is neither timed nor counted, and the refit falls back. Default true.

source
VisualGeometryToolkitCore.refine_external! — Function
refine_external!(ws, lo, problem, θ, width, scoring) -> θ′ | nothing

The ExternalRefit member of RefitFamily: refine the model θ of problem with the external solver lo at the absolute loss width width::LossWidth (loss_width(width)), on its workspace ws (external_workspace). A fixed noise scale FixedS2(s2) is the loss width √s2 unless the refiner states otherwise. Returns the refined model (the problem's model type) or nothing when the solver produced none. A pure model → model refine: no seed sweep, no re-score. The owner of the strategy implements it.

source
VisualGeometryToolkitCore.refine_width — Method
refine_width(lo, scale, width, d::Integer) -> (; width, efficiency_constant, input)

The refine contract's loss width, the one rule of every refiner that deploys a strategy from its scale / width keywords (Estimation's refine_*, fit_* and bundles, PoseLib's refiners), at the residual's codimension d:

  • lo === nothing (plain least squares) takes neither keyword (an ArgumentError names the one given): (NaN, NaN, nothing).
  • otherwise EXACTLY ONE of them, read by scale_input into input:
    • scale = σ (or an upstream result): width = c·σ with c =efficiency_constant(lo, d) (the strategy's own, else the table's; refused for a strategy with an absolute width, or a truncation without one);
    • width = w: the width itself, c = 1, refused for a strategy that states its own width mode (an efficiency constant, which w would override, or an absolute width, which w would contradict).

The strategy itself is the caller's to admit first (each refiner takes its own set).

source
VisualGeometryToolkitCore.width_s2 — Method
width_s2(lo, cs::ConsensusSet) -> Float64

The squared scale a width-carrying strategy's mode runs at — the consensus scale under EfficiencyConstant, the absolute s2 under LossWidth, both floored at eps; the INITIAL estimate of a self-scaling strategy is scale_s2(cs).

source
VisualGeometryToolkitCore.width_scale_interface — Method
width_scale_interface(w) -> ScaleInterface

The ScaleInterface label of a width mode: EfficiencyConstant → ConsensusAnchored(), LossWidth → FixedScale(), nothing → FollowsScorer() — what a width-carrying strategy's scale_interface returns, so the label has one source of truth.

source

Index