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_TAGSThe loss-shape registry (a TagRegistry, family suffix Shape): TOML loss tag → shape type, read off the one loss-identity table (_LOSS_TABLE).
VisualGeometryToolkitCore.STRATEGY_TAGS — Constant
STRATEGY_TAGSThe core optimization strategies' registry (a TagRegistry built by @lo_registry): "irls" → Irls, "triggs" → Triggs. A package with strategies of its own merges it with its registry (VisualGeometryToolkitEstimation's OPTIMIZATION_STRATEGY_TAGS).
VisualGeometryToolkitCore.Irls — Type
Irls{K<:AbstractLossShape} <: AbstractOptimizationStrategySTATIC 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 armIrls{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 noefficiency_constant; supplying one is anArgumentError(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 ŝ —mthe plain multiple, for every loss;loss_width = w(LossWidth(w)): the absolute widthw;- neither (
nothing, the default): the scorer's decision point (decision_boundary) for a shape with a decision width — MSAC withIrls{TLSShape}refits at MSAC's threshold —, and for one without (Huber) the table'sefficiency_constant(K, d)times the consensus scale ŝ,dthe scorer's codimension (a shape with neither is anArgumentError).
Fields
max_iter::Int=25: max IRLS iterations per hypothesiswidth::W: the width mode,nothing|EfficiencyConstant{Float64}|LossWidth{NTuple{2,Float64}}
VisualGeometryToolkitCore.Triggs — Type
Triggs{K<:AbstractLossShape} <: AbstractOptimizationStrategyThe 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 byefficiency_constant = c(EfficiencyConstant), ornothing(no constant stated; always forTriggs{GaussianShape})
VisualGeometryToolkitCore.fixed_width — Method
fixed_width(lo, s2) -> LossWidthThe 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).
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.
VisualGeometryToolkitCore.lo_admits — Method
lo_admits(T, K) -> nothingConstruction-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.
VisualGeometryToolkitCore.lo_admits_shape — Method
lo_admits_shape(T, K) -> nothingConstruction-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.
VisualGeometryToolkitCore.lo_construct — Method
lo_construct(T; defaults = lo_defaults(T), kw...) -> TTHE 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.
VisualGeometryToolkitCore.lo_defaults — Function
lo_defaults(T) -> AbstractDictThe [optimization_strategy] table of the defaults file of the package that registered T (keyed by tag; @lo_registry's defaults): what lo_construct reads an omitted field from.
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.
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.
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).
VisualGeometryToolkitCore.lo_has_default — Method
lo_has_default(T, f::Symbol, defaults::AbstractDict) -> BoolWhether strategy T's table of defaults (keyed by its lo_tag) holds a default for field f (at its key lo_key).
VisualGeometryToolkitCore.lo_key — Method
lo_key(T, Val(f)) -> StringThe 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).
VisualGeometryToolkitCore.lo_loss — Method
lo_loss(lo, cs::ConsensusSet, scoring, buf) -> DeployedLossThe 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).
VisualGeometryToolkitCore.lo_parametric — Method
lo_parametric(T) -> BoolWhether T is a loss-parametric family (Irls{K}): its TOML table names its loss (loss key, LOSS_TAGS) and its type names the loss through strategy_loss. false unless its @lo_registry row says so.
VisualGeometryToolkitCore.lo_tag — Function
lo_tag(T) -> String
lo_tag(lo) -> StringThe 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.
VisualGeometryToolkitCore.lo_takes_width — Method
lo_takes_width(T) -> BoolWhether strategy type T takes a width (the efficiency_constant / loss_width keys): iff it has a width field.
VisualGeometryToolkitCore.lo_validate — Method
lo_validate(lo) -> loCross-field checks on a freshly built strategy; returns it or throws. Default: none.
VisualGeometryToolkitCore.lo_width_value — Method
lo_width_value(w) -> wA 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.
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.
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.
Local-Optimization and External-Refit Contracts
VisualGeometryToolkitCore.LoInfo — Type
LoInfoThe metadata of one local-optimization refit (lo_estimate): residuals_current, whether the optimizer left the refined model's residuals in the scoring buffers.
VisualGeometryToolkitCore.check_composition — Method
check_composition(scoring, lo) -> nothingRefuse, once at entry, a local optimizer that follows the scorer's decision boundary (lo_width(lo) === nothing) composed with a scorer that defines none (has_decision_boundary). A strategy without a width mode is accepted.
VisualGeometryToolkitCore.efficiency_constant — Method
efficiency_constant(lo::AbstractOptimizationStrategy, d::Integer) -> Float64The 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).
VisualGeometryToolkitCore.external_workspace — Method
external_workspace(lo, problem, frame, scoring) -> wsThe 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.
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.
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.
VisualGeometryToolkitCore.lo_workspace — Method
lo_workspace(::Type{P}, ::Type{T}, lo, n::Int) -> LThe 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).
VisualGeometryToolkitCore.locally_optimize! — Function
locally_optimize!(L, lo, problem, θ, cs::ConsensusSet, buf::ScoreBuffers, scoring) -> FitResultRefine 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).
VisualGeometryToolkitCore.loss_at — Method
loss_at(lo, shape, cs::ConsensusSet, scoring, buf::ScoreBuffers) -> DeployedLossTHE 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 adecision_widthmethod (Welsch, Geman–McClure, Cauchy, smooth TLS, TLS, Barron),deploy(shape, w²; efficiency_constant = 1)withw = decision_width(shape, decision_boundary(scoring, buf))— the loss's decision boundary at the scorer's (the identity forTLSShape): 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 anArgumentError;EfficiencyConstant(m):deploy(shape, ŝ²; efficiency_constant = m),ŝ² = max(scale_s2(cs), eps())— the consensus-anchored width,malways the plain multiple (loss_width = m·ŝ) whatever the shape;LossWidth((m₀, s2)):deploy(shape, max(s2, eps()); efficiency_constant = m₀)— the absolute width.
VisualGeometryToolkitCore.prepare_external! — Method
prepare_external!(ws, lo, problem, θ, width::LossWidth, scoring) -> BoolThe 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.
VisualGeometryToolkitCore.refine_external! — Function
refine_external!(ws, lo, problem, θ, width, scoring) -> θ′ | nothingThe 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.
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 (anArgumentErrornames the one given):(NaN, NaN, nothing).- otherwise EXACTLY ONE of them, read by
scale_inputintoinput:scale = σ(or an upstream result):width = c·σwithc =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, whichwwould override, or an absolute width, whichwwould contradict).
The strategy itself is the caller's to admit first (each refiner takes its own set).
VisualGeometryToolkitCore.width_s2 — Method
width_s2(lo, cs::ConsensusSet) -> Float64The 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).
VisualGeometryToolkitCore.width_scale_interface — Method
width_scale_interface(w) -> ScaleInterfaceThe 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.
Index
VisualGeometryToolkitCore.LOSS_TAGSVisualGeometryToolkitCore.STRATEGY_TAGSVisualGeometryToolkitCore.IrlsVisualGeometryToolkitCore.LoInfoVisualGeometryToolkitCore.TriggsVisualGeometryToolkitCore.check_compositionVisualGeometryToolkitCore.efficiency_constantVisualGeometryToolkitCore.external_workspaceVisualGeometryToolkitCore.fixed_widthVisualGeometryToolkitCore.lo_absentVisualGeometryToolkitCore.lo_admitsVisualGeometryToolkitCore.lo_admits_shapeVisualGeometryToolkitCore.lo_constructVisualGeometryToolkitCore.lo_defaultsVisualGeometryToolkitCore.lo_efficiency_constant_shapeVisualGeometryToolkitCore.lo_estimateVisualGeometryToolkitCore.lo_fieldVisualGeometryToolkitCore.lo_field_from_tomlVisualGeometryToolkitCore.lo_has_defaultVisualGeometryToolkitCore.lo_keyVisualGeometryToolkitCore.lo_lossVisualGeometryToolkitCore.lo_parametricVisualGeometryToolkitCore.lo_tagVisualGeometryToolkitCore.lo_takes_widthVisualGeometryToolkitCore.lo_validateVisualGeometryToolkitCore.lo_widthVisualGeometryToolkitCore.lo_width_valueVisualGeometryToolkitCore.lo_workspaceVisualGeometryToolkitCore.locally_optimize!VisualGeometryToolkitCore.loss_atVisualGeometryToolkitCore.prepare_external!VisualGeometryToolkitCore.refine_external!VisualGeometryToolkitCore.refine_widthVisualGeometryToolkitCore.strategy_lossVisualGeometryToolkitCore.width_s2VisualGeometryToolkitCore.width_scale_interfaceVisualGeometryToolkitCore.@lo_registry