Robust Losses API

The robust-loss family and the width axes a scorer or a local optimizer is built at. The contracts that use them are on the Robust Estimation API page.

Robust Losses

VisualGeometryToolkitCore.AnyLoss — Type
AnyLoss

A loss that KNOWS ITS OWN WIDTH — deployed, or deployed and annealed.

The one-argument verbs below are written against this, ONCE. Every one of them is <shape math>(loss_shape(loss), …, sq_loss_width(loss)), and both members answer those two accessors, so nothing in a verb body is per-type.

A future wrapper (censored, per-point-scaled) joins the family by defining loss_shape and sq_loss_width, not by copying nine one-liners.

source
VisualGeometryToolkitCore.AbstractLossShape — Type
AbstractLossShape

Tag-type root of the unified robust-loss family: a normalized scale family ρ_w(r) = w²·ρ₁(r/w) whose scale parameter w is the loss_width, the residual scale at which the loss leaves the shared quadratic regime (see LOSSES.md and the header of robust/losses.jl). A shape carries no width; deploy gives it one.

source
VisualGeometryToolkitCore.AbstractMEstimator — Type
AbstractMEstimator <: AbstractLossShape

A robust loss whose WIDTH is set by asymptotic efficiency at the Gaussian. Subtyping this is a promise, and the promise costs exactly one method.

Interface

A subtype MUST define one method:

efficiency_constant(::Type{MyShape}) -> Float64

its tuning constant at codimension 1 — the solution of eff(m, 1) = 0.95 for that shape's psi. It takes the TYPE, not an instance: the constant is a property of the shape, and a deployment is built FROM it. Failing to define it is a MethodError on the first call, deliberately NOT caught by a catch-all, so hasmethod(efficiency_constant, (Type{MyShape},)) answers honestly.

From that single number every other method is inherited and guaranteed:

inheritedwhat it gives
efficiency_constant(K, d)the constant at codimension d
codimension_factor(K, d)its ratio to the d = 1 constant
sq_loss_width(loss)efficiency_constant^2 * s2, the squared width it runs at
loss_width(loss)efficiency_constant * sqrt(s2), derived

Note sq_loss_width/loss_width are methods of a DEPLOYMENT (deploy(shape, s2; efficiency_constant)), not of the shape: a bare shape has no width.

The noise level is an INPUT. This interface turns one into a width; it does not estimate the noise, and nothing here should. How a strategy obtains its scale is a separate axis with its own vocabulary — see ScaleInterface (ConsensusAnchored, FixedScale, FollowsScorer, SelfScaling, NoScale) in robust/estimation.jl — and the estimator is a real choice (MAD, RMS, median-of-norms, Qn, …) that belongs to the caller, not to the loss.

A subtype MAY also define _solved_constants(::Type{MyShape}), a tuple of the constants for d = 1, 2, … (entry 1 equal to its efficiency_constant) at each codimension where eff(m, d) = 0.95 has actually been SOLVED, replacing the generic chi lift sqrt((d+2)/3) with those solved numbers. It is an optimisation of accuracy, never a requirement — see the note under codimension_factor.

Who is deliberately NOT here

Losses that efficiency does not parameterise stay directly under AbstractLossShape, and calling loss_width on one is a MethodError by design: GaussianShape has no width to set, TLSShape is a hard truncation with no influence function, and BarronShape's shape is itself fitted — deriving a fixed constant for it would contradict the fit.

SmoothTLSShape is the one shape that sits outside this hierarchy yet DOES carry constants. It is a truncation, so it ships no default efficiency_constant and subtyping AbstractMEstimator would wrongly promise one — but eff(m, d) = 0.95 is genuinely solvable for its psi, so efficiency_constant(SmoothTLSShape) and its whole solved column exist and are supported. Read the subtype relation as "has a default efficiency_constant", NOT as "has a constant": a caller wanting the efficiency-matched truncation asks efficiency_constant directly. This is why efficiency_constant(K, d) and codimension_factor(K, d) below take Type{<:AbstractLossShape} and not Type{<:AbstractMEstimator}.

source
VisualGeometryToolkitCore.BarronShape — Type
BarronShape(α) <: AbstractLossShape

Barron's general robust loss at fixed shape α < 2 (facet-B convention above). α is the retirement-steepness dial: −∞ = Welsch, −2 = GM, 0 = Cauchy, 2 = L2 (excluded — not liftable). Bounded (redescending to a floor) iff α < 0.

source
VisualGeometryToolkitCore.DeployedLoss — Type
DeployedLoss

A shape together with the width it runs at: Attributed(shape, (efficiency_constant, s2)), the multiple of the noise scale and the noise VARIANCE. This is the homotopy's TARGET — anneal wraps one to move along the path, and target_loss unwraps back to it.

isbits and 16 bytes: the shape is a zero-byte tag, so a deployment is two Float64s and costs a stack write.

source
VisualGeometryToolkitCore.HuberShape — Type
HuberShape <: AbstractLossShape

Huber tag: quadratic core with a LINEAR tail past the elbow — monotone ψ (influence constant, never vanishing, beyond the elbow), hence unbounded and not redescending; not liftable (w_max is finite but the GR dual adds nothing over plain IRLS). Facet tag only — names the objective of the static-IRLS strategy vocabulary (Irls{HuberShape}).

source
VisualGeometryToolkitCore.MuScaled — Type
MuScaled <: GncSurrogate

The families whose μ multiplies the squared width (c²_μ = μ·c̄²). They differ in what μ MEANS — a width for Welsch, convexity for Geman–McClure — and so in gnc_mu0 and gnc_target, but not in how it enters the weight, so that half of the trait is written once against this supertype.

An ABSTRACT TYPE, not a Union: a downstream shape whose μ scales the squared width joins by subtyping this, the way a downstream M-estimator joins by subtyping AbstractMEstimator. A Union would have made the new extension point closed — joining would mean editing a Union inside VGC.

source
VisualGeometryToolkitCore.TLSShape — Type
TLSShape <: AbstractLossShape

HARD truncated-least-squares tag: ρ(r) = min(r², c²) — the discontinuous-influence truncation (shape g(u) = min(u, 1)). Facet tag only: NOT liftable (the truncated quadratic has no Geman–Reynolds dual — its graduation is the Black–Rangarajan outer bound, gnc_tls_weight below, not a width anneal), so it ships no lift_* closed forms. Names the objective of the truncated/GNC-TLS strategy vocabulary (e.g. Gnc{Irls{TLSShape}} in VisualGeometryToolkitEstimation).

source
VisualGeometryToolkitCore.band_signal — Method
band_signal(surrogate, w) -> Int

The per-residual rung-advance signal a GNC engine counts: 1 when the weight lies in the OPEN band 0 < w < 1, 0 otherwise — and identically 0 for every family whose graduation has no band.

A TRAIT VERB rather than an isa BandAnnealed test inside the accumulation loops (LocalOptimizationDoneRight's lift core). Those loops are generic over the family, so they name no family: a new surrogate family declares its own signal instead of editing the loop.

Returns an Int so the loops accumulate unconditionally; where the answer is the constant 0 the whole term folds away.

source
VisualGeometryToolkitCore.bounded — Method
bounded(shape::AbstractLossShape) -> Bool

Whether the shape is bounded (sup g = 1, so ρ(∞) = Δ): the potential redescends to a positive density floor e^{−Δ} and is therefore NOT normalizable on an unbounded domain — usable as evidence only through a truncated normalizer Z̃, and never likelihood-grade at frozen scale (aligns with the NormalizedWeightPolicy boundary in robust/estimation.jl).

source
VisualGeometryToolkitCore.codimension_factor — Method
codimension_factor(K::Type{<:AbstractLossShape}, codim::Integer) -> Float64

How much wider the width must be for a codim-dimensional residual than for a scalar one, at equal efficiency: efficiency_constant(K, d) / efficiency_constant(K), and 1.0 at codimension 1 by construction.

DERIVED, not stored — efficiency_constant(K, d) is the primitive, because the constant is what gets solved. Where eff(m, d) = 0.95 has actually been solved the ratio comes out of that solved number; everywhere else it is the chi-distribution rule sqrt((d+2)/3), which is exact at d = 1, a good approximation elsewhere, and makes a new loss work from its 1-D constant alone. The solved values run 3.8-7.5% under the generic 1.1547 at d = 2 (Huber 1.1109, GM 1.0814, Welsch 1.0893, Cauchy 1.0686).

source
VisualGeometryToolkitCore.conjugate — Method
conjugate(loss, w, sq_loss_width) -> Float64

Geman–Reynolds penalty conjugate(w) on the UNNORMALIZED weight w ∈ (0, w_max], so that ρ(r) = min_w [w·r² + conjugate(w)] (verified numerically in the RVG tests).

Two psis, and this is not the one

The half-quadratic literature (Geman–Reynolds, Black–Rangarajan) writes this penalty ψ; M-estimation writes ψ for the INFLUENCE FUNCTION ρ′(r). This package needs both, so the influence function keeps the symbol — it is the one efficiency_constant is solved against — and the penalty is named for what it IS: the Legendre conjugate of ρ in w.

Tell them apart by the argument: conjugate(shape, w, sq_loss_width) takes a WEIGHT, ψ and weight take a residual and a squared residual.

source
VisualGeometryToolkitCore.conjugate_curvature — Method
conjugate_curvature(loss, w, sq_loss_width) -> Float64

w·κ²″(w), the scaled second derivative of the Geman–Reynolds conjugateκ²(w) in the unnormalized weight w — the z-block curvature of a Newton lift in w = z². Since κ²′(w) = −s(w) (s the squared residual whose weight is w), it is −w/ω′(s(w)). Closed forms, each pinned against a central difference of conjugate:

shapeκ²(w)w·κ²″(w)
Welschc²(w ln w − w + 1)c²
Geman–McClurec²(√w − 1)²c²/(2√w)
Cauchyc²(w − 1 − ln w)c²/w
smooth TLSc²(1 − w/2)²c²w/2
Barron(α)see BarronShape2c²·w^{2/(α−2)}

Defined for the liftable shapes only, as conjugate is.

source
VisualGeometryToolkitCore.cost — Method
cost(loss, r, sq_loss_width, n) -> Float64

Loss M-estimator cost Σᵢ ρ(rᵢ; c) over r[1:n] — the best-tracking objective of the lifted LO, scaled by the shape's cost_scale.

ONE loop for every shape; Welsch's ½ comes from cost_scale, so the Welsch ρ closed form is written once.

source
VisualGeometryToolkitCore.cost_scale — Method
cost_scale(shape) -> Float64

The shape's historical COST CONVENTION: the constant its tracked objective is scaled by, 1.0 for everything but Welsch, whose tracker carries a ½.

A pure rescaling — monotone-equivalent, so it cannot change which model wins — and therefore a property of the SHAPE's history, not of its math. It is a trait of its own precisely because it is not deducible from anything else, and it is per-SHAPE so that no graduation family inherits Welsch's ½: a future width-annealed shape carries its own convention, not Welsch's.

Multiplying by ½ is exact in binary floating point.

source
VisualGeometryToolkitCore.decision_boundary — Method
decision_boundary(shape::AbstractLossShape, loss_width) -> Float64

The inverse of decision_width for a loss shape: the residual at which the shape's normalized IRLS weight at loss_width is exactly ½ (its half-weight decision), with the same closed forms read the other way — Welsch t = √(ln 2)·w, Geman–McClure t = √(√2 − 1)·w, Cauchy and TLS t = w, smooth-TLS t = w/√2, Barron t = w·√(b·(2^{2/(2−α)} − 1)). decision_boundary(shape, decision_width(shape, t)) ≈ t. The mixture's method, decision_boundary(::GauInlier, outlier_halfwidth), is the same inverse for the Gaussian-uniform pair.

source
VisualGeometryToolkitCore.decision_width — Function
decision_width(m, boundary) -> Float64

The native width of m whose inlier/outlier decision flips at the residual boundary (a decision_boundary) — THE one conversion behind every "same decision point" comparison across methods (the evaluation's fairness axis, where boundary = efficiency_constant · ŝ). Each owner defines its own method:

  • a loss shape: the loss_width at which the shape's NORMALIZED IRLS weight at boundary is exactly ½, ω(t²; w²)/w_max = ½ (the half-weight decision of a reweighting loss);
  • TLSShape: the identity — a hard truncation decides at its own width;
  • RANSACScoringDoneRight's GauInlier: the Student-t marginal's outlier half-width whose MAP boundary sits at boundary.

Closed forms for the shapes (t the decision boundary, w the loss width):

  • Welsch: e^{−t²/w²} = ½ ⇒ w = t/√(ln 2)
  • Geman–McClure: (1+t²/w²)^{−2} = ½ ⇒ w = t/√(√2 − 1)
  • Cauchy: (1+t²/w²)^{−1} = ½ ⇒ w = t
  • smooth-TLS: 1 − t²/w² = ½ ⇒ w = √2·t (hard cutoff at √2·t)
  • TLS: w = t
source
VisualGeometryToolkitCore.deploy — Method
deploy(shape, s2; codim = 1, efficiency_constant = efficiency_constant(shape, codim))

A SHAPE at the width it runs at — the pairing every consumer was assembling by hand. Returns a DeployedLoss whose loss_width is efficiency_constant * sqrt(s2).

s2 is the noise VARIANCE (sigma squared), not sigma. The whole robust layer speaks squared scale — LossWidth(m, s2), FixedS2(s2), scale_s2(cs), and every shape closed form takes a squared width — so storing the square is what makes sq_loss_width exact: efficiency_constant^2 * s2 is the arithmetic the call sites already do, bit for bit. Storing a linear sigma instead would force a sqrt in and a square out, and the two disagree in the last ulps on 61% of inputs.

It is the CALLER's: this package does not estimate it (see ScaleInterface in robust/estimation.jl for the axis that decides how). From a linear sigma, square it at the call: deploy(shape, mad_scale(residuals)^2; codim = 2).

efficiency_constant is the width as a dimensionless multiple of the noise scale, defaulting to the shape's efficiency constant at codim and overridden by a caller that cross-validates its own operating point.

The two are kept APART, never multiplied into a stored width: a SelfScaling strategy re-estimates the variance every iteration while efficiency_constant is fixed, so rescale replaces one and leaves the other.

deploy(WelschShape(), 0.37^2; codim = 2)                         # from efficiency -> 3.2510
deploy(WelschShape(), 0.37^2; codim = 2, efficiency_constant = 1.597) # a CV'd operating point
source
VisualGeometryToolkitCore.efficiency_constant — Function
efficiency_constant(K::Type{<:AbstractMEstimator}) -> Float64
efficiency_constant(K::Type{<:AbstractLossShape}, codim::Integer) -> Float64
efficiency_constant(shape::AbstractLossShape, codim::Integer) -> Float64

The loss's width as a MULTIPLE OF THE NOISE SIGMA. The one-argument form is the shape's own constant at codimension 1 — a property of its psi, like its influence function — and is what a loss must define to join this interface. The two-argument form lifts it to codimension d through codimension_factor.

A shape type defines it; the instance form efficiency_constant(shape, d) — THE entry point every deployment calls, on the SHAPE it deploys (never on a deployed loss, which carries its multiple as a field) — reads the shape's type. A shape whose instance carries a parameter (BarronShape's α) has no constant: a MethodError.

The DEFAULT for a deployed efficiency_constant, not the only legitimate value. It solves eff(m, d) = 0.95 at the GAUSSIAN — the width that minimises variance inflation on CLEAN data. A stage running under real contamination may legitimately cross-validate its own operating point, and will land tighter: VisualGeometryToolkitEstimation deploys an efficiency constant ≈ 1.6 per model class where this returns ≈ 3.25, trading efficiency for breakdown. Both are right for their stage.

Defined only for losses that efficiency parameterises: GaussianShape has no width and BarronShape's shape is itself fitted, so neither has one; those raise a MethodError by design. TLSShape likewise. SmoothTLSShape is a truncation rather than an influence function and ships no default efficiency_constant in its constructor, but eff(m, d) = 0.95 IS solvable for its psi, so it does carry a tabulated constant for a caller that wants the efficiency-matched truncation.

source
VisualGeometryToolkitCore.gnc_entry_mu0 — Method
gnc_entry_mu0(loss, r2max, entry) -> Float64

Entry-breadth policy (smooth-and-lift dose axis 1): entry = NaN is the seed-extreme Yang–Carlone init (gnc_mu0 — the rmax entry); a numeric entry = m starts the anneal at m× the TARGET WIDTH, i.e. μ₀ = max(m², 1) (μ multiplies the SQUARED scale c²μ = μ·c̄²). m = 1 is the static limit. Only WidthAnnealed consumes numeric entries — for the other families μ is a convexity or band parameter, not a width.

source
VisualGeometryToolkitCore.gnc_mu0 — Method
gnc_mu0(loss, r2max) -> Float64

Yang–Carlone μ₀ from the SEED residual extreme r2max = r²_max: ConvexityAnnealed (GM) μ₀ = max(2r²max/c̄², 1) (convex start; already ≤ 1 ⇒ true GM); WidthAnnealed (Welsch) μ₀ = max(r²max/c̄², 1) (c₀² = r²max ⇒ min weight e^{−1}); BandAnnealed (TLS) μ₀ = c̄²/(2r²max − c̄²), guarded to the μ cap when r²_max ≤ c̄²/2 (no graduation needed — start effectively hard).

source
VisualGeometryToolkitCore.gnc_target — Method
gnc_target(loss, x) -> Float64

TARGET (non-surrogate) loss the GNC engine best-tracks on: the shape's own ρ at the terminal width c̄², scaled by its cost_scale — which is 1.0 for every shape but Welsch, whose tracker carries a ½ (exact; the ×½ scaling is bitwise).

ONE expression for all three families. The ½ is Welsch's cost convention, a property of the shape (cost_scale), not of its graduation family; TLS routes through ρ like every other shape.

The dispatch exists ONLY to refuse: a NoSurrogate shape gets no method and raises a MethodError, like every other gnc_* verb, rather than best-tracking a graduation it does not have.

source
VisualGeometryToolkitCore.gnc_tls_weight — Method
gnc_tls_weight(x, sq_loss_width, μ) -> Float64

The Black–Rangarajan GNC-TLS surrogate weight at squared residual x = r², truncation bound sq_loss_width = c̄², continuation parameter μ:

w = 1                          x ≤ (μ/(μ+1))·c̄²
w = c̄·√(μ(μ+1))/|r| − μ        in the middle band
w = 0                          x ≥ ((μ+1)/μ)·c̄²

Continuous across the band edges (w → 1 below, w → 0 above). μ → ∞ recovers hard truncated least squares; the middle band is the graduation. Points with 0 < w < 1 are the OPEN band — a GNC engine keeps graduating only while the band is populated (the open observation of the LoSchedule contract).

source
VisualGeometryToolkitCore.lift_weight — Method
lift_weight(loss, s) -> Float64

IRLS weight ω(s) = ρ′(s) at the loss's own width — the factor multiplying a residual in the weighted normal equations, for EVERY shape. For the liftable shapes it is additionally the argmin of the Geman–Reynolds envelope at squared residual s; for Huber and Gaussian it is just the derivative.

The single deployed-width weight verb.

source
VisualGeometryToolkitCore.lift_wmax — Method
lift_wmax(loss) -> Float64

Inlier-limit weight w_max = ω(0) of the loss's IRLS weight function — the upper end of the Geman–Reynolds domain w ∈ (0, w_max]. The lifting variable is normalized: w̄ = z² = w/w_max ∈ (0, 1].

source
VisualGeometryToolkitCore.lift_zblock — Method
lift_zblock(loss, w̄) -> (rinv2, hreg)

The joint-(θ,z) Gauss–Newton z-block at the loss's own width. The one closed form the lift core (LocalOptimizationDoneRight) consumes.

source
VisualGeometryToolkitCore.liftable — Method
liftable(shape::AbstractLossShape) -> Bool

Whether the loss has a finite inlier-limit weight w_max = ω(0) and ships the closed-form Geman–Reynolds dual (lift_conjugate/lift_zblock) — i.e. the joint-(θ,z) half-quadratic lift machinery applies. NOT the same axis as bounded: Cauchy is liftable but unbounded.

source
VisualGeometryToolkitCore.loss_width — Method
loss_width(loss) -> Float64

The loss's scale parameter in the residual's own units, efficiency_constant * sqrt(s2): the residual scale at which the loss leaves the quadratic regime (see AbstractLossShape). DERIVED; prefer sq_loss_width, which is what every closed form consumes and which needs no square root.

source
VisualGeometryToolkitCore.mad_scale — Method
mad_scale(residuals) -> Float64

The robust noise scale σ̂ of residual VECTORS residuals (StaticVector{d}s, d read from their type): the median of their norms over the median of χ_d, median(‖rᵢ‖) / √quantile(Chisq(d), 0.5) (the median of χ²_d, Distributions'). If r ~ N(0, σ²I_d) then ‖r‖/σ ~ χ_d, so dividing the median norm by that distribution's median inverts to σ; the median gives it 50% breakdown, so the gross errors a loss exists to reject do not inflate it as they would an RMS.

It centres on ZERO — the model — not on the residuals' own median: residuals are already deviations from a fitted model, and a norm has no centre to subtract. So it measures a BIAS AS NOISE (residuals centred at 0.9 with σ = 0.37 give 1.33): feed it residuals of a model that fits.

The codimension is part of the estimator: a 2-D residual's norm is Rayleigh, its median 1.1774σ, a scalar residual's 0.6745σ; reading 2-D norms as d = 1 returns 1.745× the true σ, and every downstream width inherits it. A scalar residual is a StaticVector{1}.

There is no public norms form: a reader of mad_scale(norms, d) could not tell whether the norms are re-centred. A kernel that truly holds only the norms (an angle residual, a lift workspace's norms) calls the stack-internal _mad_scale_norms(; norms, codimension) (the owner's ruling, 2026-11-11).

source
VisualGeometryToolkitCore.rescale — Method
rescale(loss, s2) -> DeployedLoss

The same shape and efficiency constant at a new noise VARIANCE — the SelfScaling update, and what a moving-scale lift arm calls once per iteration. efficiency_constant is not a function of the data and does not move.

Goes through deploy rather than rebuilding the attribute tuple, so the (efficiency_constant, s2) schema is written in exactly one place.

source
VisualGeometryToolkitCore.retune — Method
retune(loss, efficiency_constant) -> DeployedLoss

The same shape and noise variance at a new efficiency constant — a caller replacing the derived efficiency constant with a cross-validated operating point.

source
VisualGeometryToolkitCore.weight — Method
weight(loss, s, sq_loss_width) -> Float64

IRLS weight ω(s) = dρ/ds (unnormalized; ω(0) = w_max). TOTAL over the family, like ρ it differentiates. For the LIFTABLE shapes it is additionally the argmin of the Geman–Reynolds envelope at s, and the weight-from-z map of the lift is w = w_max·z²; for the other three there is no envelope, only the derivative.

source
VisualGeometryToolkitCore.zblock — Method
zblock(shape, w̄, sq_loss_width) -> (rinv2, hreg)

The two z-block quantities of the joint-(θ,z) Gauss-Newton step at normalized weight w̄ = z² (the lift keeps w̄ ∈ (0, 1]; the forms are also valid on the continuation w̄ > 1), scale sq_loss_width = c²:

  • rinv2 = −κ̄²′(w̄) — the inverse-weight map r²(w̄) (≥ 0 on w̄ ≤ 1), where κ̄²(w̄) = conjugate(w_max·w̄)/w_max is the normalized conjugate; enters the z-gradient gz = z(r² − rinv2).
  • hreg = w̄·rinv2²/κ̄²(w̄) — the GN z-block Hessian (dκ/dz)²; enters the Schur pivot dᵢ = 1/(r² + hreg + μ).

Losses with a cancelling ratio return the simplified closed form (Geman–McClure: hreg = c² constant; smooth-TLS: hreg = 2c²w̄). For Welsch, Cauchy and Barron both rinv2 and κ̄² vanish at w̄ = 1 while hreg tends to a POSITIVE limit, 2κ̄²″(1) (2c² for Welsch and Cauchy, 4c²·b/(2 − α) for Barron); near w̄ = 1 they evaluate the ratio from its series, so hreg is accurate there and exact at w̄ = 1, where the lift's z clamp puts every confident inlier. That value is Zach & Bourmaud's Taylor limit 2γ″(1) of the lifted Gauss-Newton block (ECCV 2018, Eq. 10; γ = κ̄²/2), the same for every shape, so Barron's anchors (α → −∞ ≡ Welsch, α = −2 ≡ Geman–McClure, α = 0 ≡ Cauchy) hold for zblock at the clamp as everywhere else.

source
VisualGeometryToolkitCore.ρ — Method
ρ(loss, s, sq_loss_width) -> Float64

Loss value ρ at squared residual s = r², scale sq_loss_width = c² — the LOSS a residual pays, in the convention ρ′(0) = w_max.

TOTAL over the family. For the liftable shapes ρ is also the Geman–Reynolds envelope min_w [w·s + conjugate(w)], but nothing about a loss REQUIRES a lift — GaussianShape is s, HuberShape is the monotone elbow, TLSShape is the hard truncation min(s, sq_loss_width). Scoping ρ to the liftable ones made ρ(GaussianShape(), …) throw while ψ(GaussianShape(), …) answered, which is incoherent: ψ is ρ′. Only conjugate and zblock stay lift-only, because only they need the auxiliary variable to exist.

The bounded shapes saturate at sq_loss_width — the well depth — so 1 - ρ/sq_loss_width is a normalised quality in [0, 1]. GaussianShape and HuberShape are unbounded and have no depth.

source
VisualGeometryToolkitCore.ψ — Method
ψ(loss, r, sq_loss_width) -> Float64

INFLUENCE FUNCTION ρ′(r) at residual r (NOT squared) and scale sq_loss_width = c² — ψ in the M-estimation sense (Huber, Hampel, Maronna–Martin–Yohai).

This is the function the width contract is defined against: a shape's efficiency_constant is the c solving eff(m, 1) = 0.95 for

eff(m, d) = E[ψ′ + (d-1)ψ/r]² / (d · E[ψ²]),   r ~ chi_d

so the solved table (Welsch 2.9846, Geman-McClure 3.7874, Cauchy 2.3849, …) is a claim ABOUT THIS FUNCTION, and exposing it is what makes that claim checkable rather than a comment.

Derived, never a second closed form per shape, via the defining relation of IRLS: the weight IS w(r) = ψ(r)/r, so ψ(r) = r·w(r). Built directly on weight, which covers the whole family.

Constant factors do not matter here: eff is invariant under ψ → αψ (the numerator is squared, the denominator is E[ψ²]), which is why the table holds despite ρ carrying this package's depth convention rather than the classical one.

Not to be confused with conjugate, the half-quadratic penalty that the Geman–Reynolds literature also calls ψ — that one takes a WEIGHT.

source

Width Axes

VisualGeometryToolkitCore.EfficiencyConstant — Type
EfficiencyConstant()
EfficiencyConstant(m::Real)

A width as a multiple of the estimated scale (see WidthAxis). Bare, it is the AXIS (EfficiencyConstant() === EfficiencyConstant(nothing)); with a value it is a local optimizer's width MODE: the loss width m·ŝ, ŝ the scorer's consensus scale — m the plain multiple for every loss shape. m must be positive and finite: a strategy that follows the scorer takes no width.

source
VisualGeometryToolkitCore.LossWidth — Type
LossWidth()
LossWidth(w::Real)
LossWidth(efficiency_constant::Real, s2::Real)

A robust loss's scale parameter, its loss_width (see WidthAxis). Bare, it is the AXIS; with a value it is a local optimizer's ABSOLUTE width mode, stored FACTORED as (efficiency_constant, s2) so that the loss deploys at exactly deploy(shape, s2; efficiency_constant) — LossWidth(w) is (1.0, w²) (sq_loss_width = 1.0²·w² === w²), and LossWidth(m, s2) keeps the two factors apart for a reader of s2 alone (a GNC entry, Barron's α fit).

source
VisualGeometryToolkitCore.OutlierHalfwidth — Type
OutlierHalfwidth()
OutlierHalfwidth(a::Real)

The Student-t marginal's uniform outlier half-width (see WidthAxis). Bare, it is the AXIS; with a value it is the width a scoring is built at (with_width(scoring, OutlierHalfwidth(a))). Never a local optimizer's width.

source
VisualGeometryToolkitCore.WidthAxis — Type
WidthAxis

The width quantity a value is expressed in — the axis it is tuned on and persisted under:

  • EfficiencyConstant: a width as a multiple of the estimated scale ŝ, dimensionless (width = efficiency_constant · ŝ), partition-anchored;
  • LossWidth: a robust loss's scale parameter (loss_width), the residual scale where the loss leaves its quadratic regime — a threshold score's threshold is its truncated loss's width;
  • OutlierHalfwidth: the Student-t marginal's uniform outlier half-width.

width_axis reads one from its persisted name and width_axis_name writes it; to_native maps an efficiency constant onto a native axis.

source
VisualGeometryToolkitCore.loss_width — Method
loss_width(w::LossWidth) -> Float64

The absolute loss width a LossWidth value carries, efficiency_constant·√s2 of its factored (efficiency_constant, s2) — w itself for LossWidth(w) (1.0·√(w²) == w in IEEE arithmetic).

source
VisualGeometryToolkitCore.native_map — Method
native_map(axis::Union{LossWidth, OutlierHalfwidth}; d_g) -> (efficiency_constant, scale) -> Float64

Curried to_native on axis at codimension d_g — THE per-axis map closure every window and coverage grid is cut with. d_g is required for both axes (the loss-width axis ignores it), so a grid and the window cut inside it are always cut at the same codimension.

source
VisualGeometryToolkitCore.outlier_halfwidth_to_loss_width — Method
outlier_halfwidth_to_loss_width(outlier_halfwidth; operating_efficiency_constant, d_g) -> Float64

The truncation loss width at the SAME effective decision boundary as the Student-t marginal's outlier_halfwidth, holding the operating efficiency constant fixed: ŝ_implied = outlier_halfwidth / _unit_halfwidth(operating_efficiency_constant, d_g), then loss_width = operating_efficiency_constant·ŝ_implied. d_g is required (the crossover moves with it). operating_efficiency_constant is caller policy — a PROTOCOL choice (compare methods, not parameterisations).

source
VisualGeometryToolkitCore.to_native — Function
to_native(axis::WidthAxis, efficiency_constant, scale; d_g) -> Float64

An efficiency constant as a method's NATIVE width at the estimated scale: the width on axis whose inlier/outlier decision flips at the residual efficiency_constant · scale — one conversion, decision_width, of the axis's decision model. Each native axis's method lives with its model:

  • LossWidth (here): the truncated loss TLSShape(), which flips at its width, so the native width is efficiency_constant · scale itself (MSAC, RANSAC, GaU, MAGSAC++, PoseLib's truncation);
  • OutlierHalfwidth: through GauInlier (the Student-t marginal's crossover).

d_g is the residual codimension of the problem (1 for E and F, 2 for H). It has NO default: a native grid and the window cut inside it must be cut at the same d_g, so every caller states it. The loss-width axis does not depend on it; the outlier half-width does.

source
VisualGeometryToolkitCore.to_native — Method
to_native(::OutlierHalfwidth, efficiency_constant, scale; d_g) -> Float64

An efficiency constant as the Student-t marginal's native width: the outlier half-width whose MAP inlier/outlier decision flips at the residual efficiency_constant · scale — decision_width of the Gaussian-uniform mixture GauInlier(scale²; d_g), the stack-wide definition of the crossover (moved from RANSACScoringDoneRight). scale is the estimated inlier scale (linear, in the units of the residuals), and the result is in those units.

d_g is the residual codimension (1 for E and F, 2 for H) and has no default: it is the EXPONENT of the outlier density, so it moves the outlier half-width by decades (at scale = 1, an efficiency constant of 6 maps to 8.2293e7 at d_g = 1 and to 1.0156e4 at d_g = 2).

source
VisualGeometryToolkitCore.width_axis_name — Method
width_axis_name(axis::WidthAxis) -> Symbol

The persisted name of a width axis — the key of its grid, its sidecar kind, its TOML and CLI value: :efficiency_constant, :loss_width, :outlier_halfwidth (String of it where a string is written), whatever value the width carries. The inverse of width_axis on a bare axis: width_axis(width_axis_name(a)) === a.

source

Index