Solvers API

Projective solver kernels (homography, fundamental, essential, P3P), model-validity tests, the zero-allocation SVD workspace, and the total-least-squares line. The slot-labeled epipolar forms have their own page, the Epipolar Forms API. The solve protocol and the solver registry are documented with the Correspondence API; see the Epipolar Forms guide.

Normalization

One scheme serves every solver. A normalization STRATEGY is a type named <Method>Normalization, applied as a coordinate map with AffineMap(strategy, points[, mask, weights]):

  • HartleyNormalization(; center) — translate to the (weighted) centroid, or to a known center, and scale to mean distance √2. Estimation uses it: the centroid for H, F and E; the known distortion centre for the radial models, whose solvers are written about the origin.
  • DiagonalNormalization(size; center) — the image centre and the half-diagonal (corners at unit radius, NormalizedImageFrame coordinates). For storage only: the benchmark pools, where one noise level and one threshold must mean the same across resolutions.

A correspondence set's normalization is one value, CorrespondenceNormalization: both sides' maps and their inverses, built from two strategies or by model type (CorrespondenceNormalization(M, cs; center)), with normalize and the side accessors, whose composition moves a model (D ∘ M ∘ inv(S) into the normalized frame, inv(D) ∘ M ∘ S back). An estimator normalizes once at its entry and returns results in its inputs' frame; the DLT kernels take the enclosing normalization as normalization.

Homography Solvers

CoordinateTransformations.AffineMap — Type
AffineMap(s::HartleyNormalization, points, mask = nothing, weights = nothing) -> AffineMap
AffineMap(s::HartleyNormalization, points3d, weights = nothing) -> AffineMap
AffineMap(s::DiagonalNormalization) -> AffineMap

Apply a normalization strategy: the affine map x ↦ σ·(x − c) it prescribes (a Diagonal linear part, uniform scale). For Hartley the centre and scale come from points — mask (a BitVector) and weights restrict and weight the statistics, an empty selection gives the identity; the diagonal strategy needs no data. Hartley applies to image points (mean distance √2) and to 3-D points (StaticVector{3}: about their centroid, mean distance √3 — the normalization of a least squares over lengths, such as translations); the diagonal strategy is 2-D.

source
VisualGeometryToolkitCore.CorrespondenceNormalization — Type
CorrespondenceNormalization(T_src::AffineMap, T_dst::AffineMap)
CorrespondenceNormalization(src::Normalization, dst::Normalization, cs[, mask, weights])
CorrespondenceNormalization(M::Type, cs; center)

The normalization of a correspondence set as a first-class value: the forward homogeneous maps of the source and target sides AND their analytic inverses, computed once at construction (never per candidate model). Build it from two affine maps, from a normalization strategy per side (HartleyNormalization, DiagonalNormalization) applied to the correspondences' sources and targets, or by MODEL TYPE — the strategy each model class needs:

  • HomographyMat / AbstractFundMat (F and E): Hartley at the centroid on both sides (the classic DLT data normalization), over the mask's correspondences and weighted by the weights column when there is one;
  • RadialHomography: Hartley at the centroid on the sources, Hartley about the known distortion center (required) on the targets — the origin the 5-point kernel is written about.

Verbs:

  • normalize(normalization, cs) — materialized normalized correspondence set
  • source_map / destination_map — its two sides as affine maps
  • a model moves by composition with the two sides: destination_map(N) ∘ M ∘ inv(source_map(N)) carries a data-frame model M into the normalized frame and inv(destination_map(N)) ∘ M ∘ source_map(N) back (M a HomographyMat, a FundMat/EssentialMat, a HomographyMap, an EpipolarMap, a RadialHomography, a RadialCamera).

The pose family builds none (bearings are already metric).

source
VisualGeometryToolkitCore.DiagonalNormalization — Type
DiagonalNormalization(size; center = (width/2, height/2))

The image-size normalization as a STRATEGY: translate to center (the image centre by default; size in pixels, plain numbers or px quantities — a length is a DimensionError) and divide by the half-diagonal hypot(width, height)/2, so the image corners land at unit radius — the coordinates of a NormalizedImageFrame. For STORAGE only (the benchmark pools, where one noise level and one threshold must mean the same across resolutions); estimation normalizes by HartleyNormalization. Apply it with AffineMap(DiagonalNormalization(size)).

source
VisualGeometryToolkitCore.HartleyNormalization — Type
HartleyNormalization(; center = nothing)

Hartley's data normalization as a STRATEGY (Hartley & Zisserman §4.4): translate to the (weighted) centroid of the points — or to a KNOWN center — and scale isotropically so that the mean distance from it is √2. Apply it with AffineMap(HartleyNormalization(...), points[, mask, weights]).

The known centre is the radial models' frame: their distortion centre must land on the origin the minimal solvers are written about, and the isotropic scale keeps the division model in its class (k′ = k/s²); a centroid translation would move the centre off the origin.

source
CoordinateTransformations.transform_deriv_params — Method
transform_deriv_params(H::HomographyMat, u::StaticVector{2}) -> SMatrix{2,9}

The derivative of the point a homography transfers, π(H·ũ), along its parameters vec(H) (column-major): Jπ·(ũᵀ ⊗ I₃), Jπ the perspective derivative at H·ũ. The Gθ of the transfer form (`constraintwithjacobians(TransferForm(H), …)); the transferred point's model covariance ispropagate(transformderivparams(H, u), Σθ)for an ambient covarianceΣθ, and a chart'sactionjacobianis this through itsretract_jacobian`.

source
VisualGeometryToolkitCore.constraint_with_jacobians — Method
constraint_with_jacobians(H::HomographyMat, u₁::SVector{2}, u₂::SVector{2})
    -> (g::SVector{2}, G_x::SMatrix{2,4}, G_θ::SMatrix{2,9})

Compute the algebraic constraint g and its derivatives for the homography.

The constraint g = 0 encodes ũ₂ ∝ H·ũ₁ (2 equations): g₁ = h₁ᵀũ₁ − x'·h₃ᵀũ₁ g₂ = h₂ᵀũ₁ − y'·h₃ᵀũ₁

Returns:

  • g::SVector{2,T} — constraint vector
  • G_x::SMatrix{2,4,T} — ∂g/∂(x,y,x',y') (observation Jacobian)
  • G_θ::SMatrix{2,9,T} — ∂g/∂vec(H) (model Jacobian, column-major)
source
VisualGeometryToolkitCore.homography_4pt — Method
homography_4pt(s₁, s₂, s₃, s₄, d₁, d₂, d₃, d₄) -> SMatrix{3,3} or nothing

Compute a homography from exactly 4 point correspondences using the inhomogeneous method (two 3×3 LU solves, zero heap allocation).

Returns a Frobenius-normalized SMatrix{3,3} with H[3,3] >= 0, or nothing if the points are degenerate (collinear).

Algorithm

From "An Algebraic Derivation of the Inhomogeneous Homography":

  1. Build U3 = [u1|u2|u3], solve U3*c = -u4 for projective depths
  2. Build U3' = [u1'|u2'|u3'], solve U3'*c' = -u4' for target depths
  3. λi = c'i / c_i (projective depth ratios)
  4. H = U3' * diag(λ) * inv(U3)

Example

s = [SA[0.0,0.0], SA[1.0,0.0], SA[1.0,1.0], SA[0.0,1.0]]
d = [SA[0.1,0.1], SA[1.1,0.0], SA[1.0,1.1], SA[0.0,1.0]]
H = homography_4pt(s[1], s[2], s[3], s[4], d[1], d[2], d[3], d[4])
source
VisualGeometryToolkitCore.homography_dlt! — Method
homography_dlt!(A, N::CorrespondenceNormalization, cs; mask = nothing, svd_ws = nothing) -> HomographyMat or nothing

In-place N-point DLT of the correspondences cs using the pre-allocated buffer A (2N × 9). Weights are the container's weights column, as for homography_dlt; inside an LO/IRLS loop set them per iteration with withattrs(cs; weights = w) (no allocation beyond the caller's w).

When mask::BitVector is provided, only masked points are used and rows are compacted into the top of A. The inner-loop form: N is the enclosing estimator's CorrespondenceNormalization, built once at its entry (the public form builds it from the data); this form applies it row by row and composes the model back into the data frame (inv(D) ∘ H ∘ S), and never normalizes on its own.

If svd_ws::SvdWorkspace is provided and A is Float64, uses pre-allocated LAPACK workspace for the SVD (zero allocations). Note: A is overwritten when using svd_ws.

No covariance is returned. The DLT minimizes ALGEBRAIC residuals, whose noise is heteroscedastic under pixel noise, so the SVD's own resolvent covariance is not this estimator's (measured overconfident against Monte Carlo). Its first-order covariance, if ever needed, is implicit_covariance's block form with the DLT's identity weighting.

source
VisualGeometryToolkitCore.homography_dlt — Method
homography_dlt(cs; mask = nothing, svd_ws = nothing) -> HomographyMat or nothing

Compute a homography from N >= 4 correspondences cs (u₁ => u₂ pairs; any sources/targets container, a Correspondences preferred) by the Direct Linear Transform with Hartley normalization.

Per-correspondence weights are the container's weights column (set with withattrs), never a keyword: each weight multiplies its rows' squared algebraic residual and the Hartley normalization. When mask (a BitVector or an index list) is given, only those correspondences are used.

Example

cs = Correspondences(src_pts, dst_pts)
H = homography_dlt(cs)
H = homography_dlt(withattrs(cs; weights = [1.0, 0.5, 1.0, 0.8]))
H = homography_dlt(cs; mask = inlier_mask)
source
VisualGeometryToolkitCore.is_convex_quad — Method
is_convex_quad(q::NTuple{4, <:StaticVector{2}}) -> Bool

True iff the closed polygon q[1] → q[2] → q[3] → q[4] is a simple, convex, consistently-wound quadrilateral: every edge cross-product around the boundary shares one non-zero sign. Mixed signs (a self-intersecting "bow-tie") and the all-zero degenerate case are false.

source
VisualGeometryToolkitCore.is_orientation_preserving — Method
is_orientation_preserving(h::HomographyMap{3}, rect::HyperRectangle{2}) -> Bool

True iff the four corners of rect map through h to a simple (non-self-intersecting) convex quadrilateral. Catches "bow-tie" homographies that the per-correspondence checks (test_cheirality, test_conditioning) miss — these come from H fits that are well-behaved over the inlier cluster but extrapolate to fold the rectangle's corners across each other.

Returns true when consecutive edge cross-products along the projected boundary share a non-zero sign (consistent winding); false when signs are mixed (the projected quad self-intersects). A purely degenerate projection (all crosses zero) also returns false, since it can't be a valid extent map.

This is an extent-aware check that complements the per-point predicates in RANSAC: caller supplies the rectangle over which the homography is supposed to be valid (e.g. a calibration board's Rect(bundle, :world)).

Example

H_fit = HomographyMap(matrix_from_ransac)
rect  = Rect2(SA[0.0, 0.0], SA[100.0, 60.0])   # board extent in world coords
is_orientation_preserving(H_fit, rect) || @warn "Bow-tie fit"
source
VisualGeometryToolkitCore.sign_normalize — Method
sign_normalize(H::StaticMatrix{3,3,T}) -> typeof(H) or nothing

Frobenius-normalize a 3×3 matrix and ensure H[3,3] >= 0. Returns nothing if the matrix norm is negligible. Preserves the input type (HomographyMat, FundMat, SMatrix, etc.).

source
VisualGeometryToolkitCore.source_map — Method
source_map(f::CorrespondenceNormalization) -> AffineMap

The forward normalization of the source side, as a 2D affine map (source_map(f)(x) is the normalized source point); its inverse is inv of it. The destination side is destination_map.

source
VisualGeometryToolkitCore.test_cheirality — Method
test_cheirality(H, cs, idx) -> Bool

Projective cheirality check, uniform-sign variant. For each correspondence (uᵢ, u′ᵢ) at the sample indices, compute the projective scale factor λᵢ such that ũ′ᵢ = λᵢ · H · ũᵢ in homogeneous coordinates, where ũ = [u; 1]. Accept iff all λᵢ share a sign.

Rationale — H is only defined up to a nonzero scalar (H and −H are the same mapping). Under H → −H, every λᵢ flips sign, so requiring a specific sign (e.g. the original Shekhovtsov rule: sign-normalize to det(H) > 0, then require λ > 0) amounts to picking a matrix representative by convention. That convention matches the image-to-image case (where both frames share 2D handedness) but fails for object-to-image homographies (e.g. a world y-up calibration board mapped to a y-down image), where the "in front" representative has det(H) < 0 — the strict rule then rejects every correct fit.

The mapping-level invariant is uniform sign across the λᵢ: mixed signs signal a bow-tie in projective depth (a real pathology that cannot be repaired by a matrix sign flip), while a shared sign — positive or negative — signals a consistent mapping (with the overall sign absorbed into the free scalar of H).

For each i: compute Hu = H · ũᵢ, pick the component k with the largest absolute value (numerical robustness), and set λᵢ = ũ′ᵢ[k] / Hu[k] (with ũ′[3] = 1). Reject the sample the moment a sign disagreement is seen. An inner-loop gate: H and cs in the same frame (sign-based, so any positive-scale normalization, or none, gives the same answer).

source
VisualGeometryToolkitCore.test_conditioning — Method
test_conditioning(H; max_cond=100) -> Bool

Reject homographies whose SVD condition number κ = σ₁/σ₃ exceeds max_cond.

Catches near-rank-deficient H — the same pathology PoseLib's post-solve |det(H_normalized)| < 1e-8 check rejects (since after Frobenius normalization det(H) = σ₁σ₂σ₃ and one vanishing singular value makes both κ → ∞ and det → 0), plus a broader class of numerically unstable but non-singular H's.

Matches Shekhovtsov's is_homography_ill_conditioned (decompose_homography.py:244) with the same default threshold κ = 100.

κ is a property of the frame H is written in, not of the map: the bound is calibrated for H between Hartley-normalized frames (both sides, as CorrespondenceNormalization builds them), so evaluate it on the normalized H, never on a pixel-frame one.

source
VisualGeometryToolkitCore.unit_normalize — Method
unit_normalize(H::StaticMatrix{3,3}) -> SMatrix{3,3}

H / ‖H‖ with NO degenerate guard and NO sign convention — the hot-loop sibling of sign_normalize for chart lifts and retractions, where a Union{Nothing,...} return is unacceptable and the H[3,3] ≥ 0 flip would break retraction continuity mid-iteration.

source
VisualGeometryToolkitCore.OUT_OF_FIELD_RESIDUAL — Constant
OUT_OF_FIELD_RESIDUAL = 1.0e6

The residual of an observation a model cannot place — a ray outside a lens's or division model's field, a point behind the camera — in the caller's units: the ONE constant for such rows. In an LM row it is a CONSTANT (with a zero Jacobian row), so a step that pushes observations out is charged for it and rejected — never a zero residual, which would reward exactly that step; in a scoring residual it is finite (not Inf/NaN), so sorting and squaring stay defined while the point lands among the outliers. 1e6 rather than larger: its square (1e12) leaves Float64 cost sums a resolution of ~1e-4, so the in-field rows stay visible to LM next to a constant out-of-field one.

source
VisualGeometryToolkitCore.CorrespondenceNormalization — Method
CorrespondenceNormalization(::Type{<:AbstractRadialModel}, cs; center, mask = nothing)

The radial family's normalization of plane_point => pixel correspondences (a RadialHomography, a RadialCamera; the H/F one lives in homography_solvers.jl): Hartley at the centroid on the plane side, Hartley about the REQUIRED center (the distortion centre, the pencil's centre) on the image side — the origin the minimal kernels are written about, with an isotropic scale that keeps a division model in its class (k′ = k/s²) — over mask's correspondences and weighted by the weights column when there is one. A centroid image-side frame would move the centre off the origin (measured: 1.4 px misfit against 4e-13 px).

source
VisualGeometryToolkitCore.RadialHomography — Type
RadialHomography{T, N}

Radially distorted homography model: a HomographyMatH (plane point → undistorted pixel) and a PROJECTIVE division camera on the TARGET side — the N division coefficients λ = (λ₁, …, λ_N) (in squared pixel units, λₚ multiplying ρ²ᵖ) about the distortion centre c (the camera's principal point, COLMAP pixels). A correspondence (s, d) is explained when the division-model RAY LIFT of the observation is proportional to the recentered H ray:

(d − c ; 1 + Σₚ λₚ‖d − c‖²ᵖ) ≃ λ · T₋c · H s̃

The camera is CameraModel(m) = CameraModel(ProjectiveIntrinsics(c), Division(λ...)), built on demand: the struct stores its primitives (H, λ, center), so it is isbits and runs on a device. RadialHomography{T} (any N) stays a valid partial type; N = 1 is the one-coefficient model of homography_5pt_radial, for which division_coeff and the property m.k read λ₁ (both throw an ArgumentError for N > 1 — never a silent λ₁).

The division model is an uncalibrated projection/back-projection model (project/backproject) — the lift's signed third component represents rays beyond 90° (omnidirectional lenses), which no image-space "undistortion" can. The solver frame is origin-centered (c = 0 — homography_5pt_radial constructs it that way); composing back through a fixed-center normalization produces the pixel-frame model with the center carried along, so consumers (radial_transfer, quad projection) need no side-channel frame data.

Constructors: RadialHomography(H, camera) (a CameraModel{<:ProjectiveIntrinsics, <:Division}), and for N = 1RadialHomography(H, k, c), RadialHomography(H, k) and RadialHomography{T}(H, k[, c]) (the centre defaults to the origin). Produced by homography_5pt_radial / Homography5ptRadial.

source
CoordinateTransformations.transform_deriv — Method
transform_deriv(m::RadialHomography, ray::StaticVector{3}) -> SMatrix{2,3}
transform_deriv_params(m::RadialHomography{T, N}, ray::StaticVector{3}) -> SMatrix{2,N}

The derivatives of project(m, ray): along the (centred) ray, and along the division coefficients λ₁ … λ_N (the model's lens parameters; H and the centre act before the ray). Closed form for one coefficient; for N > 1 the Division{N} lens's own (ForwardDiff through its project). NaN where project returns nothing — the same edge rule, as for the lens models beyond their field.

source
VisualGeometryToolkitCore.backproject — Method
backproject(m::RadialHomography, d) -> SVector{3}

Back-project an observed target point to its (unnormalized) ray in the model's CENTERED frame: (d − c ; 1 + Σₚ λₚ‖d − c‖²ᵖ) — the division-model lift (1 + k‖d − c‖² for one coefficient). Total; the third component's sign carries front/back hemisphere (zero at exactly 90°, negative beyond — valid for omnidirectional lenses). The H part of the model relates source points to these rays: backproject(m, d) ≃ λ · T₋c · H s̃ (with T₋c the recentering translation).

source
VisualGeometryToolkitCore.homography_5pt_radial — Method
homography_5pt_radial(s₁, …, s₅, d₁, …, d₅; extra_check=false)
    -> FixedModels{3, RadialHomography}

Minimal 5-point solver for a homography with one-sided one-parameter division-model radial distortion on the TARGET side (Wadenbäck et al. (2026) — port of HomLib's get_one_sided). Sources sᵢ are distortion-free; targets dᵢ are observed (distorted). Each candidate (H, k) satisfies

dᵢ / (1 + k‖dᵢ‖²) ≃ π(H s̃ᵢ)

exactly for i = 1…4, plus ONE scalar equation of the fifth correspondence: the problem is "4.5-point" overdetermined (9 DOF vs 10 constraints), so only the true root also satisfies the redundant remaining equation and interpolates all five points. The distortion coefficient solves a cubic, so up to 3 candidates are returned (count == 0 on degenerate samples). With extra_check = true only the root minimizing the redundant-equation residual is kept (at most 1 candidate) — the reference enables this in its RANSAC wrapper.

Coordinates are used raw: supply roughly unit-scale, centered coordinates (k lives in squared target units and rescales as k/s²).

source
VisualGeometryToolkitCore.project — Method
project(m::RadialHomography, ray::StaticVector{3}) -> SVector{2} or nothing

Project a ray (in the model's CENTERED frame, as produced by the H part) to the observed image point whose backproject lift is proportional to it. One coefficient, in closed form: c + μ·(x, y) with μ = 2 / (z + √(z² − 4k ρ²)), ρ² = x² + y² (the branch continuous with k → 0, where it reduces to perspective division μ = 1/z). For k < 0 (fisheye/omni) this is total over front AND back rays; for k > 0 it returns nothing when z² − 4kρ² < 0 (the ray lies outside the model's representable field). N > 1 coefficients: c + project(Division(λ...), ray), the lens's own solve on its monotone branch, nothing where the lens images nothing (past its fold).

source
VisualGeometryToolkitCore.radial_in_front — Method
radial_in_front(m::RadialHomography, s) -> Bool

Whether source point s lands in m's field (project's edge rule) AND in its FRONT hemisphere: the observed point's division lift has a positive third component (one coefficient: μ·z > 0, the ray within 90° of the axis; N > 1: the ray's z > 0, the lift on the lens's branch pointing the ray's way). For k ≥ 0 every in-field ray is in front (the lift's third component 1 + kρ² is positive), so this adds z > 0 for k < 0 only — where project is total over back rays too (omnidirectional lenses). The extent gate of a planar target: a board corner at or past 90° means the hypothesis spans ≥ 180° across a plane, which no camera images.

source
VisualGeometryToolkitCore.radial_outline — Method
radial_outline(m::RadialHomography, rect::HyperRectangle{2}; samples = 20) -> Vector{Point2{Float64}}

Boundary of a world-plane rect transferred through the radial model: each edge sampled samples times (_rect_edge_samples) and pushed through radial_transfer; samples whose ray leaves the representable field are DROPPED — the polygon shortens, it never carries a nothing. PER EDGE, not at constant arc length (boundary_point(::Rect, θ)): every corner is sampled exactly, because this outline is a board's image-plane QUAD and a quad whose corners are missed is a different polygon. The one sampler behind a board's image-plane quad and its Makie overlay (hoisted from BlobBoards, 2026-09).

source
VisualGeometryToolkitCore.radial_transfer — Method
radial_transfer(m::RadialHomography, s) -> SVector{2} or nothing

Predicted OBSERVED target of source s through m: recenter the ray H s̃ and project it. Ray-based — no intermediate perspective point, so it stays defined through and beyond 90° for k < 0.

source
VisualGeometryToolkitCore.radial_transfer_rows! — Method
radial_transfer_rows!(r, m::RadialHomography, u₁, u₂, sqrtw) -> r
radial_transfer_jacobian_rows!(J, m::RadialHomography, dH, u₁, sqrtw) -> J

The √w-weighted observation-space transfer rows of m over u₁[i] => u₂[i], two per correspondence (r[2i-1:2i] = sqrtw[2i-1:2i] .* (radial_transfer(m, u₁[i]) − u₂[i])), and their Jacobian: columns 1:M along the directions dH = (∂H/∂θ₁, …, ∂H/∂θ_M) of H (e.g. the reshaped columns of retract_jacobian(HomographyManifold8(H₀), v)), columns M + 1 … M + N along the division coefficients λ₁ … λ_N (transform_deriv_params). A ray outside the model's field (project's edge rule) is a constant residual with a ZERO Jacobian row, so LM rejects a step that pushes rays out rather than being rewarded for it. One KernelAbstractions kernel each, on every backend (the CPU's included).

source
VisualGeometryToolkitCore.test_model — Method
test_model(m::RadialHomography, cs, idx) -> Bool

Feasibility of a radial-homography candidate: SVD conditioning of the H part plus ray-space cheirality — the recentered H s̃ᵢ must be proportional to backproject(m, dᵢ) with a UNIFORM sign across the sample (m and cs in the same frame). Ray-based, so front/back hemisphere consistency is checked without any perspective division.

The conditioning bound (test_conditioning, κ ≤ 100) is a property of the frame m is written in, and it is calibrated for Hartley frames — the H/F convention. m and cs are therefore meant to be in the normalization of CorrespondenceNormalization(RadialHomography, cs; center): Hartley on both sides, the target about the distortion centre. (In a smaller-scale frame, e.g. the earlier full-diagonal target frame, κ rejected true-model candidates: measured 1 of 124.)

source
VisualGeometryToolkitCore.test_sample — Method
test_sample(::Type{<:RadialHomography}, cs, idx; target_tol = 1.0e-3) -> Bool

Degeneracy gate for the 5-point radial sample: the homography checks of the four fully-used correspondences (orientation, coincidence, collinearity — run on the distorted targets, an adequate proxy since the division model is locally orientation-preserving) plus pairwise distinctness of all five. Orientation and collinearity are scale-free; the SOURCE distinctness is a fixed separation 1e-3 in cs's units, and the TARGET distinctness is an absolute separation target_tol in cs's units — a caller holding the normalization converts a pixel separation through its scale (target_tol = τ_px * similarity_scale(destination_map(normalization))), so the gate does not move with the frame.

source
VisualGeometryToolkitCore.AbstractRadialModel — Type
AbstractRadialModel

Plane→image models whose image side is a pencil of rays about a known centre: RadialHomography (plane point → pixel, the division lens carried explicitly) and RadialCamera (plane point → the image LINE the pixel lies on, invariant to focal length and to any radially symmetric distortion).

The family contract is deliberately narrow — center, and movement between coordinate frames by composition (D ∘ m ∘ inv(S) with an image-side D and a plane-side S). project is NOT part of it: the members differ in arity there, which is exactly why both exist.

source
VisualGeometryToolkitCore.center — Method
center(m::AbstractRadialModel) -> Point2

The model's centre of radial symmetry — the pencil's vertex, and the principal point when the model is a calibration one. A radial model's matrix predicts a DIRECTION; the centre is what turns that direction into a locus in the image, which is why every member carries one.

source
VisualGeometryToolkitCore.direction — Function
direction(m, X) -> Vec2

The bare algebraic prediction of a radial model: the DIRECTION of the image ray a plane point maps to, before the centre turns it into a locus. Defined for RadialCamera in cameras/calibration.jl, where it is P·X̃.

Declared here so the family owns the name; the method lives with the model.

source

Fundamental and Essential Matrix Solvers

VisualGeometryToolkitCore.AbstractFundMat — Method
(F::FundMat)(u::SVector{2})    -> Line2D
(E::EssentialMat)(x̂::SVector{2}) -> Line2D

The epipolar CORRELATION, applied: the epipolar line in image 2 of the input point in image 1 (ℓ₂ = F ũ₁ — a point-to-hyperplane action, one-way by rank 2; contrast the collineation action of HomographyMap). Pixel input for FundMat, gnomonic (GnomonicFrame-coordinate) input for EssentialMat. Use F'(u) / E'(x̂) for the reverse direction.

The Mat callable is the frame-free surface; the slot-labeled equivalent is epipolar_map on an EpipolarForm, whose frame tags make the direction checkable. The degenerate directions are epipoles.

source
VisualGeometryToolkitCore.EssentialMat — Method
EssentialMat(R::AbstractMatrix, t::AbstractVector) -> EssentialMat
EssentialMat(X::EuclideanMap{3})                   -> EssentialMat

Construct the calibrated epipolar matrix E = [t]× R from the relative rigid transform (R, t) in the EXTRINSIC direction, x₂ = R·x₁ + t (monogram X_{V₂V₁} — view 1 coordinates in, view 2 coordinates out). Returns an EssentialMat{T} (typed wrapper) so that downstream dispatch can distinguish E from F by type, not by comment.

The EuclideanMap form reads .R/.t directly — labeled maps are welcome (e.g. a CameraExtrinsics or a rig's ViewFrame{id₁} → ViewFrame{id₂} transform); the frame tags are irrelevant to the algebra here and are simply dropped. This is the constructor behind essential_form(rig), which additionally labels the resulting form's slots with the rig's GnomonicFrame tags.

t is treated as a direction (no normalization here — caller can scale for sign or rescale to unit norm if desired).

source
VisualGeometryToolkitCore.EssentialMat — Method
EssentialMat(F::FundMat, K1::AbstractMatrix, K2::AbstractMatrix) -> EssentialMat
EssentialMat(F::FundMat, K::AbstractMatrix)                      -> EssentialMat

Construct the calibrated epipolar matrix E = K₂ᵀ F K₁ from a fundamental matrix and per-view intrinsics. Inverse of FundMat(E, K1, K2). Replaces the older essential_from_fundamental helper which returned a raw SMatrix and hence lost the F→E type distinction at the call site.

This is the frame-free algebra; the checked, frame-labeled counterpart is composition on an EpipolarMap — the pixel → gnomonic frame change per argument slot, with the slot labels verifying that each K met the view it was meant for (see GnomonicFrame).

K1, K2 may be supplied as raw SMatrix{3,3}, CameraCalibrationMat (any T<:Real), or any AbstractMatrix of size 3×3.

source
VisualGeometryToolkitCore.FundMat — Method
FundMat(E::EssentialMat, K1::AbstractMatrix, K2::AbstractMatrix) -> FundMat
FundMat(E::EssentialMat, K::AbstractMatrix)                      -> FundMat

Construct the (uncalibrated) epipolar matrix F = K₂⁻ᵀ E K₁⁻¹ from an essential matrix and per-view intrinsic matrices. The shared-K overload assumes K₁ = K₂ = K (e.g. PhotoTourism scenes captured by one camera).

Inverse of EssentialMat(F, K1, K2). Strongly-typed in both input (EssentialMat) and output (FundMat) so the calibrated / uncalibrated distinction is enforced at compile time.

This is the frame-free algebra of the gnomonic → pixel frame change; the checked, slot-labeled form of the same law is composition (∘) of an EpipolarMap with the HomographyMap{GnomonicFrame{id}, ImageFrame{id}}(K) lifts, as minted by EpipolarForm(rig) on a StereoRig (see essential_form).

K1, K2 may be supplied as raw SMatrix{3,3}, CameraCalibrationMat (any T<:Real), or any AbstractMatrix of size 3×3.

source
VisualGeometryToolkitCore.cheiral_pose_fast — Method
cheiral_pose_fast(E, f₁, f₂) -> (R::SMatrix{3,3}, t::SVector{3})

The cheirality vote: of motion(E)'s four (R, t) candidates, the one with the most bearing pairs in front of BOTH cameras by the ray-domain test_cheirality (ties go to the earlier candidate). f₁, f₂ are equal-length vectors of unit bearings — the caller back-projects with its own camera; the z = 1 chart this used to build through K⁻¹ does not exist for a ray at 90°. t is unit (the essential's translation direction).

Ray depth is right in meaning and camera-general, not a rate fix: see triangulate's recorded negative result before re-attempting it as one. Moved here from VisualGeometryToolkitEstimation's relative-pose bundle, which the evaluation protocol's cheirality also called.

source
VisualGeometryToolkitCore.constraint_rounding_scale — Method
constraint_rounding_scale(F::AbstractFundMat, u₁, u₂)
constraint_rounding_scale(E::EssentialMat, f₁, f₂; M₁, M₂)

The epipolar constraint's rounding scales (see the generic method): the point-gradient bound |F|·|s|, |F|ᵀ·|d| and the value bound |d|ᵀ·|F|·|s| at the homogeneous points, loose by a constant and relative to the model's own entries, so its homogeneous scale never decides. On bearings the gradient carries the backprojection Jacobians into pixels, so its scale carries their 1-norm too.

source
VisualGeometryToolkitCore.constraint_with_jacobians — Method
constraint_with_jacobians(F::FundMat, u₁::SVector{2}, u₂::SVector{2})
constraint_with_jacobians(E::EssentialMat, x̂₁::SVector{2}, x̂₂::SVector{2})
    -> (g::T, G_x::SVector{4,T}, G_θ::SVector{9,T})

Compute the epipolar constraint g and its derivatives.

The scalar constraint g = ũ₂ᵀ F ũ₁ (one equation, d_g = 1). Identical algebra for F and E — the wrapper type signals input coordinate space (pixels for FundMat, gnomonic points for EssentialMat).

Returns:

  • g::T — epipolar constraint value
  • G_x::SVector{4,T} — ∂g/∂(x₁,y₁,x₂,y₂) (observation Jacobian)
  • G_θ::SVector{9,T} — ∂g/∂vec(F) (model Jacobian, column-major)
source
VisualGeometryToolkitCore.constraint_with_jacobians — Method
constraint_with_jacobians(E::EssentialMat, f₁, f₂; M₁, M₂) -> (g, G_x, G_θ)

The epipolar constraint on UNIT BEARINGS and its Jacobians: g = f₂ᵀ E f₁, with

  • G_x = (f₂ᵀE·M₁, f₁ᵀEᵀ·M₂) — 1×4, in PIXEL coordinates, because M is the backprojection Jacobian ∂f/∂u from backproject_with_jacobian;
  • G_θ = vec(f₂ f₁ᵀ) — ∂g/∂vec(E), column-major, unchanged from the plane form and feeding the same covariance machinery.

M is TANGENT (fᵀM = 0), so no explicit projection onto the tangent plane is needed here or downstream — that is the property backproject_with_jacobian is built to guarantee.

Why the Jacobians are arguments rather than recomputed: they are per-point data, so they ride as attribute COLUMNS on the correspondence set (withattrs(cs; M₁, M₂)), per the correspondence standard. Recomputing them per residual would repeat a camera backprojection in the inner loop.

The plane sibling constraint_with_jacobians(F, u₁, u₂) is the same question in the z = 1 chart. Use that one for FundMat and this one for EssentialMat: F is a pixel-plane model, E is not.

source
VisualGeometryToolkitCore.fundamental_7pt — Method
fundamental_7pt(s₁..s₇, d₁..d₇) -> FixedModels{3,FundMat{T}} | nothing

Compute fundamental matrices from exactly 7 point correspondences; T is the points' element type.

Returns FixedModels{3,FundMat{T}} with 1–3 Frobenius-normalized solutions (F[3,3] >= 0), or nothing if the system is degenerate. Zero heap allocations.

Algorithm

  1. Build 7×9 DLT matrix from Kronecker products
  2. Partitioned A\B solve for 2D null space (zero-allocation)
  3. Cubic determinant constraint: det(λ f₁ + f₂) = 0
  4. 1 or 3 real roots → 1 or 3 F matrices

Example

result = fundamental_7pt(s₁, s₂, s₃, s₄, s₅, s₆, s₇,
                         d₁, d₂, d₃, d₄, d₅, d₆, d₇)
if result !== nothing
    for F in result  # iterates 1–3 FundMat solutions
        # use F...
    end
end
source
VisualGeometryToolkitCore.fundamental_dlt! — Method
fundamental_dlt!(A, N::CorrespondenceNormalization, cs; mask = nothing, svd_ws = nothing) -> FundMat or nothing

In-place N-point DLT for the fundamental matrix of the correspondences cs using the pre-allocated buffer A (N × 9). Weights are the container's weights column, as for fundamental_dlt.

When mask::BitVector is provided, only masked points are used and rows are compacted into the top of A. The inner-loop form: N is the enclosing estimator's CorrespondenceNormalization, built once at its entry (the public form builds it from the data); this form applies it row by row and composes the model back into the data frame (inv(D) ∘ F ∘ S), and never normalizes on its own.

No covariance is returned — as for homography_dlt!: the SVD's resolvent covariance is not this estimator's under pixel noise (algebraic rows are heteroscedastic); its first-order covariance, if ever needed, is implicit_covariance's block form with the DLT's identity weighting.

source
VisualGeometryToolkitCore.fundamental_dlt — Method
fundamental_dlt(cs; mask = nothing, svd_ws = nothing) -> FundMat or nothing

Compute a fundamental matrix from N >= 8 correspondences cs (u₁ => u₂ pairs; any sources/targets container, a Correspondences preferred) by the Direct Linear Transform with Hartley normalization and rank-2 enforcement.

Per-correspondence weights are the container's weights column (set with withattrs), never a keyword. When mask (a BitVector or an index list) is given, only those correspondences are used.

Example

cs = Correspondences(pts1, pts2)
F = fundamental_dlt(cs)
F = fundamental_dlt(cs; mask = inlier_mask)
source
VisualGeometryToolkitCore.motion — Method
motion(E::AbstractMatrix) -> NTuple{4, Tuple{SMatrix{3,3}, Vec3{Float64}}}

Extract candidate (R, t) motion tuples from an essential matrix E.

Returns all 4 combinations of the two possible rotations and two possible translation directions. Only one is physically valid (positive depth for both cameras), but for pose error evaluation we take the minimum over all 4.

Parallels motion(::HomographyMat) (Malis-Vargas decomposition for homographies — same shape, multi-candidate).

source
VisualGeometryToolkitCore.motion — Method
motion(H::HomographyMat) -> Vector{Tuple{RotMatrix{3,Float64}, Vec3{Float64}, Vec3{Float64}}}

Malis–Vargas decomposition (Malis and Vargas, 2007) of a calibrated homography into up to 4 candidate (R, t, n) motions: rotation R, translation t = t_phys / d_phys, and unit plane normal n (sign fixed so n₃ ≥ 0). Native port of PoseLib's motion_from_homography (single-SVD variant); the candidate order matches PoseLib exactly: (R₁,t₁,n₁), (R₁,−t₁,−n₁), (R₂,t₂,n₂), (R₂,−t₂,−n₂).

For the degenerate near-equal-outer-singular-value case (planar / pure rotation) it returns the 1-element list [(H̄, 0, 0)] (normalized homography, zero t/n), as PoseLib does. Parallels motion(E) for essential matrices.

source
VisualGeometryToolkitCore.observation_gradient_jacobian — Method
observation_gradient_jacobian(F::AbstractFundMat, u₁, u₂) -> SMatrix{4, 9}
observation_gradient_jacobian(E::EssentialMat, f₁, f₂; M₁, M₂) -> SMatrix{4, 9}

∂G_x/∂vec(F) of the epipolar constraint (column-major vec, the coordinates of its G_θ). The constraint is bilinear, so each entry is one coordinate of a point: on the plane G_x = ((Fᵀd)₁,₂, (Fs)₁,₂) and ∂(Fs)_k/∂F_ij = δ_ki·s_j, ∂(Fᵀd)_k/∂F_ij = δ_jk·d_i; on bearings the two pixel gradients are those carried by M₁, M₂ (per-point data, constant in the model).

source
VisualGeometryToolkitCore.test_cheirality — Method
test_cheirality(pose::EuclideanMap{3}, f₁, f₂) -> Bool

Ray-domain cheirality: triangulate the bearing pair and require BOTH depths positive. The plane-free replacement for X[3] > 0, which assumes a forward hemisphere that a fisheye or omnidirectional camera does not have.

Parallel rays (no parallax) are rejected — NaN > 0 is false — which is the honest answer: nothing was triangulated.

source
VisualGeometryToolkitCore.test_model — Method
test_model(F::FundMat, u₁_sample, u₂_sample) -> Bool

Oriented epipolar constraint (Chum et al., 2004). For an exact correspondence, the epipolar line l₁ = Fᵀũ₂ and the line e₁ × ũ₁ are the same line in image 1 (both go through e₁ and ũ₁), so Fᵀũ₂ = μᵢ(e₁ × ũ₁) for some scalar μᵢ. The signum uses the dot product of all three components:

sᵢ = (Fᵀũ₂ⁱ) · (e₁ × ũ₁ⁱ) = μᵢ · ‖e₁ × ũ₁ⁱ‖²

Since ‖e₁ × ũ₁ⁱ‖² ≥ 0, sign(sᵢ) = sign(μᵢ). The code checks sᵢ · sⱼ > 0 for all pairs, i.e., that all μᵢ share the same sign. Using the full dot product (rather than a single component) avoids numerical instability when one component happens to be near zero.

This is a chirality parity check. The absolute sign of μᵢ is meaningless (F and e₁ are projective, defined up to scale), but if two correspondences give different signs, they cannot both be in front of both cameras. The test rejects F matrices that are algebraically valid (u₂ᵀFu₁ = 0) but geometrically inconsistent. An inner-loop gate: F and the points in the same frame, the estimator's normalization (sign-based, so any positive-scale normalization gives the same answer).

source
VisualGeometryToolkitCore.triangulate — Method
triangulate(pose::EuclideanMap{3}, f₁, f₂) -> (X, λ₁, λ₂)

Triangulate a correspondence of UNIT BEARINGS: the midpoint of the mutual perpendicular between the two rays, in VIEW 1's frame, together with both ray depths. pose maps view 1 to view 2 (X₂ = R·X₁ + t).

The depths are the point of returning them. Cheirality on rays is `λ₁ > 0 && λ₂

0` — the point is in front of both cameras along their own rays — which is

the plane-free replacement for testing X[3] > 0. A z-depth test silently assumes a forward hemisphere the ray domain does not have, so it is wrong for any camera that sees past 90°.

Returns λ₁ = λ₂ = NaN for parallel rays (|f₁·R'f₂| → 1), which is degenerate rather than exceptional: it is what zero parallax looks like, and the caller decides. Never throws.

Why this form, and what it costs

It is the only form that GENERALISES. The pixel-domain DLT (uᵢ × Pᵢ X̃ = 0) builds P = K[I|0] — pinhole by construction — and calibrated geometry in this stack must work for fisheye and omnidirectional cameras, where that matrix does not exist. That is the deciding argument, and it is not a number.

MEASURED against that DLT rather than assumed better, paired (identical scenes, points and noise draws), binned by parallax, on relative 3-D error. Reprojection error cannot discriminate the two — it sits at the noise level even where the 3-D error reaches 363 — so it is reported only as a sanity check. The trade is real and mixed:

apex anglemed DLT → rayq99 DLT → rayray wins (paired)
[0, 0.1°)0.488 → 0.56721.9 → 1.7343.3%
[0.1, 0.3°)0.170 → 0.1743.69 → 1.3845.4%
[0.3, 1°)0.0592 → 0.05850.354 → 0.33648.0%
[1, 3°)0.0202 → 0.02010.092 → 0.092547.8%
[3, 90°)0.00597 → 0.005950.0279 → 0.027947.6%

So: it WINS ONLY IN THE TAIL, and decisively there — a q99 of 21.9 is a point placed at 22× its true distance, and those are what corrupt a bundle or a cheirality vote downstream. It is slightly WORSE on the median below 0.1° (43.3% of paired points, i.e. it loses more often than it wins), in a regime where both answers are already about half the true distance. Above 0.3° the two are indistinguishable to three significant figures. Noise-free both are exact to 1e-13–1e-16, so the entire difference is noise propagation near degeneracy, not conditioning.

A NEGATIVE RESULT worth keeping: ray-depth cheirality does NOT reduce the behind-camera rate. Below 0.1° parallax it is 20.1% for the DLT's z-test and 20.4% here; in [0.1, 0.3°) both are 0.23%. That was predicted to improve and measured not to — at that parallax the noisy rays genuinely cross behind a camera, so it is the geometry, not the test. Ray depth is still the right statement (a z-test assumes a forward hemisphere the ray domain lacks), but it buys correctness of MEANING, not accuracy.

source
VisualGeometryToolkitCore.essential_5pt — Function
essential_5pt(x1, x2) -> FixedModels{10, EssentialMat{Float64}}

5-point essential-matrix solver (Nistér 2004). The bare form routes to NativeSolver (see essential_5pt_native.jl, a port of PoseLib's relpose_5pt.cc); essential_5pt(PoseLibSolver(), …) dispatches to the compiled PoseLib backend when PoseLib is loaded.

source
VisualGeometryToolkitCore.essential_dlt — Function
essential_dlt(cs) -> EssentialMat{Float64} or nothing
essential_dlt(backend, cs)

8-point linear DLT for the essential matrix from N >= 8 correspondences cs (x1 => x2 bearing pairs, StaticVector{3} each side; any sources/targets container, a Correspondences preferred), the same correspondence currency as homography_dlt and fundamental_dlt. Only the PoseLib backend exists; load using PoseLib to make this callable (essential_dlt(PoseLibSolver(), cs), and the bare form routes to it).

source
VisualGeometryToolkitCore.p3p — Function
p3p(rays, points_3d) -> FixedModels{4, Extrinsics3}

Perspective-3-Point solver. The bare form routes to NativeSolver (see p3p_native.jl, a port of PoseLib's p3p.cc); p3p(PoseLibSolver(), …) dispatches to the compiled PoseLib backend when PoseLib is loaded.

source
VisualGeometryToolkitCore.essential_5pt — Method
essential_5pt(::NativeSolver, x1, x2) -> FixedModels{10, EssentialMat{Float64}}

Nistér 5-point relative pose (essential matrices only), a native Julia port of PoseLib's relpose_5pt. x1 and x2 hold five calibrated bearings each, as a tuple or a static vector of 3-vectors.

Typed to 3-vectors so a 2-vector (a point on the z = 1 plane) is a MethodError rather than a DimensionMismatch from inside the kernel, the same refusal solve(::Essential5pt, …) and PoseLib's backend give. The type is a necessary condition, not a guarantee: a 3-vector still ON the z = 1 plane is accepted and, the epipolar algebra being scale-invariant per endpoint, even gives the right answer for rays the chart can represent. Bearings must come from the camera's back-projection (backproject_with_jacobian), where they are built.

source
VisualGeometryToolkitCore.p3p — Method
p3p(::NativeSolver, x, X) -> FixedModels{4, Extrinsics3}

Perspective-3-Point, native Julia (port of PoseLib's p3p.cc). x must be three unit bearing vectors; X the corresponding 3D points. Up to four poses with x_cam = R·X + t.

source

Lines

VisualGeometryToolkitCore.tls_line — Method
tls_line(points) -> Uncertain{Line2D{T}}
tls_line(points, weights) -> Uncertain{Line2D{T}}

Total least squares (orthogonal distance regression) line through points (2-vectors): the centroid, and the scatter matrix's smallest-eigenvalue eigenvector as the normal — one closed-form step. The line is in Hesse form n⊤p + d = 0, n = (cos φ, sin φ), and carries the covariance of θ = (φ, d): s² (JᵀWJ)⁻¹, with s² = Σwᵢrᵢ²/(n₊−2) the residual variance, n₊ the number of points with positive weight and J the residual Jacobian — calibrated against Monte Carlo.

weights are FIXED non-negative per-point weights (wᵢ = 1/σᵢ² for known isotropic variances): the weighted centroid, the weighted scatter, and a zero weight drops the point. Without them every point weighs 1. Throws ArgumentError for fewer than 3 points of positive weight, a negative or non-finite weight, or a weights whose length differs from points'.

For points carrying their own covariances, VisualGeometryToolkitEstimation's fit_line (an iterative weighted fit) applies.

source
VisualGeometryToolkitCore.tls_line_statistics — Function
tls_line_statistics(points, weights[, normal]) -> (line, S, JᵀWJ)

The weighted total-least-squares line of tls_line(points, weights) with the two statistics its covariance is made of, both at the returned line: the weighted residual sum S = Σwᵢrᵢ² and the (φ, d) information JᵀWJ (J's rows (tᵀpᵢ, 1), t the line's direction). The residual variance is S/(n₊ − 2) and the covariance S/(n₊ − 2)·(JᵀWJ)⁻¹; a caller that owns its own variance model reads the pieces instead.

With normal given (a 2-vector, taken as is), the step estimates the offset only: the line with that normal through the weighted centroid — the least-squares offset for a known normal.

weights as for tls_line: FIXED and non-negative, a zero weight drops the point; there is no minimum count here (the covariance's is the caller's), but weights that sum to zero throw ArgumentError.

source
VisualGeometryToolkitCore.nearest_point — Method
nearest_point(lines) -> SVector{N}

The point x nearest to the lines in the least-squares sense: the minimizer of Σᵢ wᵢ ‖(I − dᵢdᵢᵀ)(x − oᵢ)‖², the weighted sum of squared distances from x to each line, by one closed-form solve of the normal equations (Σ wᵢPᵢ) x = Σ wᵢPᵢoᵢ, Pᵢ = I − dᵢdᵢᵀ (the projector onto the line's normal space).

lines is a vector of origin => direction pairs (a Correspondences by correspondences(origins, directions), or a plain vector of Pairs): oᵢ any point on the line, dᵢ its direction, normalized inside (any nonzero length). N-dimensional: 3-D lines and 2-D lines alike. Per-line weights are the weights attribute column (withattrs(lines; weights = w)): FIXED, non-negative, a zero weight drops the line; without it every line weighs 1.

Units: origins that are lengths (SVector(1.0, 2.0, 3.0) .* mm) are stripped in metres at entry and the point comes back in metres; plain origins give a plain point in the caller's own unit. The solve runs about the weighted centroid of the origins, so translating every line by t translates the point by t to rounding.

Throws ArgumentError for fewer than two lines of positive weight, a zero or non-finite direction, or lines that do not determine a point — all parallel, the normal matrix singular to 1e-12 of its largest eigenvalue.

lines = correspondences([SVector(0.0, 0.0, 0.0), SVector(1.0, 0.0, 0.0)], [SVector(0.0, 0.0, 1.0), SVector(-1.0, 0.0, 1.0)])
nearest_point(lines)   # [0.0, 0.0, 1.0]: where the two lines meet
source

Circles

VisualGeometryToolkitCore.Circle3pt — Type
Circle3pt()

Minimal 3-point circle solver: the circle through three 2D points (the circumcircle; solve(Circle3pt(), points, idx)), sample_size 3, max_solutions 1. Its data are POINTS on the curve, an AbstractVector of StaticVector{2} — a circle has no second view, so there is no correspondence to form, as for tls_line and direct_ellipse. The solve is closed form and frame-covariant (pixels in, a circle in pixels out), computed about the sample's first point so it needs no normalization.

A (near-)collinear sample is the sample gate's to refuse, before the solve (test_sample(Circle, points, idx), the homography's collinearity ratio). The solver keeps only the last line of defence: exactly collinear points (a zero determinant) or a non-finite circle give count == 0.

Deliberately NOT entered in the minimal_solvers registry: that registry answers correspondence element-type pairs.

source

Ellipses

VisualGeometryToolkitCore.Ellipse5pt — Type
Ellipse5pt()

Minimal 5-point ellipse solver: the conic through five 2D points (solve(Ellipse5pt(), points, idx)), sample_size 5, max_solutions 1, returned only when it is a real, non-degenerate ELLIPSE (is_ellipse: a hyperbola, a parabola, a line pair or a point/imaginary ellipse gives count == 0). Its data are POINTS on the curve, an AbstractVector of StaticVector{2}, as for Circle3pt and direct_ellipse. The conic is the null vector of the 4×5 design matrix of the other four points taken about the sample's first point (through which the conic has no constant term), by cofactors: closed form, allocation-free and frame-covariant (pixels in, an ellipse in pixels out), with no normalization.

A sample with three (near-)collinear points — whose conic is a line pair — is the sample gate's to refuse, before the solve (test_sample(Ellipse, points, idx), the homography's collinearity ratio). The solver keeps only the conic classification and a non-finite guard.

Deliberately NOT entered in the minimal_solvers registry: that registry answers correspondence element-type pairs.

source
VisualGeometryToolkitCore.direct_ellipse — Method
direct_ellipse(points) -> Ellipse{T} | nothing

The ellipse through the 2-D points minimizing the summed squared algebraic residual Σᵢ (xᵢᵀ C xᵢ)² under the ellipse constraint 4AC − B² = 1 (Fitzgibbon, Pilu & Fisher 1999, in the numerically stable form of Halir & Flusser 1998), computed in Hartley-normalized coordinates: one closed-form step whose solution is always an ellipse. nothing when the points admit none (too few in general position, e.g. collinear). Throws ArgumentError for fewer than 5 points.

A start value: the algebraic residual weighs points by where they sit on the curve. VisualGeometryToolkitEstimation's refine_ellipse minimizes the orthogonal distance from it.

source
VisualGeometryToolkitCore.ellipse_log_shape — Method
ellipse_log_shape(e::Ellipse) -> SVector{5}

The log-shape chart of e: (cx, cy, S₁₁, S₁₂, S₂₂), the centre and the symmetric S = R·diag(log a, log b)·Rᵀ (R the rotation by e.θ), so that the boundary is {c + exp(S)·u : ‖u‖ = 1}. Minimal, unable to leave the ellipse cone (the exponential of every symmetric S is positive definite) and smooth at a circle, where (a, b, θ) swaps its axes. Inverse of ellipse_from_log_shape.

source

Model Validity

VisualGeometryToolkitCore.assert_unit_bearings — Method
assert_unit_bearings(bearings, which, who; remedy) -> nothing

The entry gate of an estimator that takes BEARINGS (unit rays, StaticVector{3}): every one finite, then every one of unit norm, else an ArgumentError from who (the estimator) naming the first non-finite, or the worst-normed, entry of the which column ("source", "target") and the remedy (how to back-project).

StaticVector{3} is a necessary condition, not a guarantee: a z = 1 chart point has three coordinates and gives the right answer for every ray the chart can represent, so its exclusion of rays at and past 90° survives the type unseen. The finite check comes first: NaN > worst is false, so a NaN bearing (a pixel the camera cannot back-project, past a fisheye's fold) would get through the norm test.

The norm tolerance is the gap between the two kinds of input, not a rounding bound: a chart point's norm is sqrt(1 + x² + y²), 1 only on the optical axis (where the two are the same vector) and 1.0185 already at a narrow lens's 11°, while a normalized ray is unit to a few ulps. 1e-6 lies between, with room for a bearing computed in Float32.

source
VisualGeometryToolkitCore.test_consensus — Method
test_consensus(model, cs, mask) -> Bool

Validate a model against its consensus (inlier) set mask. For homography this re-runs cheirality on the full inlier set (catches bow-ties that a sample-only check misses). F/E have no consensus-set gate today and return true. An inner-loop gate: model and cs in the same frame (cheirality is sign-based, so any positive-scale normalization gives the same answer).

source
VisualGeometryToolkitCore.test_dlt_conditioning — Method
test_dlt_conditioning(ws::SvdWorkspace; max_cond = 100.0, null_dim = 1) -> Bool

Is the DLT design matrix of the solve that filled ws well enough conditioned to trust? dlt_conditioning(ws; null_dim) <= max_cond. An inner-loop gate: true succeeds, like every other test_* here.

NOT test_conditioning, and the difference is the point. test_conditioning(H) measures the MODEL matrix; this measures the DESIGN matrix's null-space gap — whether the solution direction is isolated. A degenerate configuration can hand back a perfectly well-conditioned H from a design matrix whose null space is not, which is exactly what a collinear correspondence set does. The two thresholds are both 100.0 by default, on different matrices, so a wrong-matrix gate looks plausibly calibrated: the name has to carry which matrix is meant, because the number does not.

The defaults (max_cond, null_dim) = (100.0, 1) are the one threshold: VisualGeometryToolkitEstimation's DLT refit calls this at them for the relative families. max_cond = Inf never refuses. The refusal is a STRICT >, so a ratio of exactly max_cond succeeds.

The threshold is only comparable across callers that solve in the same frame — see dlt_conditioning.

source
VisualGeometryToolkitCore.test_model — Method
test_model(H::HomographyMat, cs, idx) -> Bool

Homography feasibility: SVD conditioning (κ ≤ 100) AND projective cheirality (uniform-sign λ) over the sample. Composes test_conditioning and test_cheirality. An inner-loop gate: H and cs are both in the estimator's normalization, CorrespondenceNormalization(HomographyMat, cs) — where the κ bound is calibrated.

(test_model(F::FundMat, cs, idx) — the oriented epipolar check — is defined in geometry/solvers/fundmat.jl.)

source
VisualGeometryToolkitCore.test_sample — Method
test_sample(::Type{<:Circle}, points, idx) -> Bool

Reject a degenerate 3-point circle sample: three (near-)collinear points — a repeated point among them — whose circle does not exist or runs off to an unbounded radius. The test is the homography gate's collinearity ratio (thin_ratio(p₁, p₂, p₃) above the same ≈ 0.1% of the longest side), a ratio and so frame-free. An inner-loop gate, run before Circle3pt's solve.

source
VisualGeometryToolkitCore.test_sample — Method
test_sample(::Type{<:Ellipse}, points, idx) -> Bool

Reject a degenerate 5-point ellipse sample: three (near-)collinear points among the five — a repeated point among them — whose conic is a line pair. The test is the homography and circle gates' collinearity ratio (thin_ratio of every triple above the same ≈ 0.1% of its longest side), a ratio and so frame-free. An inner-loop gate, run before Ellipse5pt's solve.

source
VisualGeometryToolkitCore.test_sample — Method
test_sample(::Type{<:EssentialMat}, cs, idx; tol_px = COINCIDENT_PX) -> Bool

The same coincidence question for E on UNIT BEARINGS: are any two of the sample's bearings the same detection? Bearings are directions, so the comparison cannot be a distance between them — it is the angle, converted to pixels through each point's backprojection Jacobian.

cs carries M₁/M₂ as attribute COLUMNS (withattrs(cs; M₁, M₂)), the 3×2 Jacobians from backproject_with_jacobian; the pair's separation in pixels is estimated as angle(fₐ, f_b) / σ_max(M). Without those columns (any container without them, a plain Pair vector included) this takes the shared bearing-free path of the F method, because there is then no way to convert an angle into the caller's units — and guessing one would be a threshold with nothing behind it.

The estimate is CONSERVATIVE, and by how much

M is generally anisotropic: a pixel step produces a different angle along its major and minor singular directions. Dividing by σ_max therefore UNDER-states the separation of a pair displaced along the minor direction, by exactly the factor 1/aniso (aniso = σ_max/σ_min) — measured to five digits across a fisheye field. Rejection happens when the estimate falls below tol_px, so the gate actually rejects true separations up to tol_px × aniso: the effective threshold is tol_px along M's major axis and tol_px × aniso along its minor.

Larger, not smaller — so it never UNDER-rejects, which is the failure a deduplication backstop must not have. It begins over-rejecting genuinely DISTINCT features only when tol_px × aniso > d_min, i.e. aniso > d_min / tol_px — aniso > 10 for the default 0.1 px and features no closer than 1 px. A moderate KannalaBrandt fisheye (f = 300, k1 = −0.02) reaches aniso 1.48 at field radius 386 px, an effective 0.148 px: about 7× below where distinct features live. Stated because this stack exists for strongly distorted lenses, and a field-varying threshold is otherwise the kind of thing that resurfaces as unexplained behaviour at the periphery.

The tangency contract

M is tangent to its bearing — fᵀM = 0, measured to 4e-20 across the field — which is why no explicit projection onto the tangent plane appears here or in any consumer. It is a CONTRACT, not an observation: a violation would show up as slow drift rather than an error, so it is pinned at backproject_with_jacobian and depended on here.

source
VisualGeometryToolkitCore.test_sample — Method
test_sample(::Type{<:FundMat}, cs, idx) -> Bool

Reject minimal F samples with coincident points — the only degeneracy gated pre-solve for the epipolar solvers, and unlike homography there is NO other check here, so this one carries the whole gate. Arity-agnostic (a 7- or 8-point sample alike); E has its own method below.

cs is in PIXELS and the tolerance is COINCIDENT_PX (see the note above COINCIDENT_PX). With no collinearity check behind it, a duplicate detection this gate admits goes straight into the solver.

source
VisualGeometryToolkitCore.test_sample — Method
test_sample(::Type{<:HomographyMat}, cs, idx) -> Bool

Reject degenerate 4-point homography samples: bow-tie (mixed orientation), coincident points, or any 3-of-4 (near-)collinear. An inner-loop gate.

UNITS ARE MIXED HERE, AND DELIBERATELY SO. The coincidence part takes cs in PIXELS and its tolerance is COINCIDENT_PX. The other two parts are frame-independent and take whatever frame they are given: _orientation_preserving is a SIGN, and _not_collinear is a RATIO (thin_ratio, ≈ 0.1% of the longest side), so neither has a unit to get wrong.

_not_collinear STAYS, although coincidence catches duplicate detections and it can look redundant: two near-identical points make every triangle through them thin, so it also rejects duplicates, incidentally. Genuine collinearity is a DIFFERENT degeneracy, the one it is for: a 3-of-4 collinear sample makes the homography's 3×3 LU systems rank-deficient regardless of how distinct the points are.

source

SVD Workspace

VisualGeometryToolkitCore.SvdWorkspace — Type
SvdWorkspace{T}(max_rows, ncols)

Pre-allocated workspace for in-place SVD via LAPACK gesdd! (divide-and-conquer). Eliminates all heap allocations from repeated SVD calls on matrices up to max_rows × ncols.

Float64 only: the workspace calls the double-precision dgesdd directly, so SvdWorkspace{Float64} is the one constructible instance (the type parameter stays so that a caller's SvdWorkspace{T} field type still reads).

source
VisualGeometryToolkitCore.dlt_conditioning — Method
dlt_conditioning(ws::SvdWorkspace; null_dim::Int = 1) -> Float64

The DLT design matrix's null-space gap from the solve that filled ws: S[1] / max(S[n - null_dim], eps()), the largest singular value over the smallest NON-null one (n = length(ws.S); for the 9-column homography and fundamental systems, S[1]/S[8]). The eps() floor is load-bearing: an exactly rank-deficient design matrix returns an enormous ratio rather than dividing by zero, which is how a collinear correspondence set announces itself.

A OBSERVATION, not a policy: it neither rejects nor alters the solve. Pair it with test_dlt_conditioning, whose default 100.0 is the one threshold: VisualGeometryToolkitEstimation's refine!(::DltWorkspace, …) refuses a relative-family hypothesis by calling it at that default.

ONLY MEANINGFUL IN THE COORDINATES THE SOLVE USED. The ratio is a property of the design matrix as built, so it depends on the normalization AND on the weights column that went into it. VGC's public DLT forms build a HartleyNormalization, which is what makes a threshold of 100.0 mean the same thing here as in VisualGeometryToolkitEstimation — a caller that solves in another frame must recalibrate its threshold rather than carry this one across.

REFLECTS THE LAST SOLVE that filled this workspace, and nothing checks that for you: read it immediately after the homography_dlt!/fundamental_dlt! call whose matrix you mean. There is deliberately no staleness flag — adding one means a field on SvdWorkspace, which VisualGeometryToolkitEstimation constructs too, so it would turn a local guard into a cross-repo API change and a lockstep window, to protect against a mistake this sentence prevents.

source
VisualGeometryToolkitCore.svd_nullvec! — Method
svd_nullvec!(ws::SvdWorkspace, A, m, Val(N)) -> SVector{N}

Compute null space vector (last row of Vt) of the first m rows of A (with N columns) using pre-allocated workspace. Zero allocations. A is overwritten by LAPACK. N must be a compile-time constant via Val.

A wide system (m < N, e.g. the 8 × 9 design matrix of a 4-point homography or an 8-point fundamental DLT) is factored in full (JOBZ = 'A'): its thin factorization has only m right singular vectors, none of them the null vector. The singular values it does not have are zeroed, so dlt_conditioning reads such a system as rank-deficient only when it is. A LAPACK failure throws LAPACKException.

Example

ws = SvdWorkspace{Float64}(100, 9)
v = svd_nullvec!(ws, A, size(A,1), Val(9))  # -> SVector{9,Float64}
source

Index