Core Types API

The core composition and uncertainty types (Attributed, Uncertain, CovMat/PrecMat), the conic and epipolar matrix types, interface stubs, and traits. See the Design: Attributed{V,A} and Stereo Rigs and Uncertainty guides.

Core Types

VisualGeometryToolkitCore.AbstractDetection — Type
AbstractDetection

Type alias for Attributed{<:Union{FeatureFrame, Uncertain{<:FeatureFrame}}} — any Attributed value whose wrapped value is a FeatureFrame, or a FeatureFrame with its covariance or precision (Uncertain).

This replaces the former abstract type. d isa AbstractDetection is true for any Attributed{V,A} where V <: FeatureFrame or V <: Uncertain{<:FeatureFrame}. Methods on it read the geometry through feature_frame, never d.value, so both kinds behave alike.

source
VisualGeometryToolkitCore.Attributed — Type
Attributed{V,A}

Generic container composing a value with attributes. Used as the single composition primitive for scored correspondences, detections, deployed losses, uncertain values (Uncertain is the alias Attributed{V, <:Union{CovMat, PrecMat}}) and any "value with metadata" pattern.

Type Parameters

  • V: The value (EllipticFrame, Homography, camera pose, correspondence, etc.)
  • A: Attributes type (a score Float64, a covariance, a struct of attributes, …)

Fields

  • value::V: The wrapped value
  • attributes::A: Associated attributes

Property Access (via @generated getproperty)

  • r.value, r.attributes → direct field access
  • Named fields of A → forwarded from attributes; when A is a statistical form (CovMat/PrecMat, i.e. r is an Uncertain) its storage is not a record: r.matrix names the form itself and nothing else is forwarded from it
  • Other symbols → forwarded to value

Example

sc = Attributed(src => dst, 0.83)   # a scored correspondence
sc.value            # the Pair
sc.attributes       # 0.83
sc.first            # forwarded to value (the Pair)
source
VisualGeometryToolkitCore.BoundedRange — Type
BoundedRange{T}

A validated range with min ≤ max constraint. Useful for detector parameters.

Example

scale_range = BoundedRange(1.0, 100.0)
x in scale_range  # true if 1.0 ≤ x ≤ 100.0
clamp(x, scale_range)  # clamps to [1.0, 100.0]
source
VisualGeometryToolkitCore.Conic — Type
Conic{T} <: AbstractHomConicMat{T}

A 2D conic section of any class (ellipse, hyperbola, parabola or degenerate), stored and constructed as HomEllipseMat is, with no class check. What a HomographyMap makes of a circle or an ellipse: classify_conic names its class and Ellipse(c) (checked: an ArgumentError for another class) reads the ellipse back; to map a shape and get its ellipse or nothing in one non-throwing call, use transfer_ellipse(H, shape) on the map and the shape instead.

Q = HomographyMap(M)(circle)   # a Conic
is_ellipse(Q) && Ellipse(Q)
source
VisualGeometryToolkitCore.Correspondence — Type
Correspondence{S,T} = Pair{S,T}

A correspondence between a source element of type S and a target of type T. This is a type alias — correspondences are plain Pairs.

Correspondences are stored in columnar layout via StructArray{Correspondence{S,T}}, accessed as cs.first (sources) and cs.second (targets).

source
VisualGeometryToolkitCore.CovMat — Type
CovMat{N,T,M,F} <: StaticMatrix{N,N,T}

N×N covariance matrix Σ = Λ⁻¹ — the covariance counterpart to PrecMat.

Use when the upstream source emits covariance natively (Gaussian process regressors, MVN priors, Kalman-filter outputs). The two forms are interconvertible: inv(Λ) and inv(Σ) (frame-preserving — the representation swaps, the frame does not).

Tensor character and transformation law

Covariance is a (2,0) tensor — both slots contravariant (it PAIRS with two covectors: Σ = E[δx δxᵀ] is built from displacement components). Under a change of coordinates with Jacobian J it pushes forward:

Σ ↦ J Σ Jᵀ

This is the OPPOSITE variance of PrecMat's pullback Λ ↦ J⁻ᵀ Λ J⁻¹, and this covariant/contravariant law pair is exactly the bug surface the frame label exists to check: conjugating with the wrong factor produces a plausible-looking, silently wrong matrix. With labeled frames, propagate through a framed map dispatches to the correct law per type and records the destination frame on the result.

Frame parameter (0.9)

The trailing F <: Frame{N} names the frame the matrix's coordinates live in; every historically-shaped constructor defaults it to UnlabeledFrame{N} (the gradual-typing wildcard — see PrecMat). Storage (the held matrix M, parent(Σ): an SMatrix, SDiagonal or ScaledIdentity) and the StaticArrays interface mirror PrecMat.

Example

Σ = CovMat{2,Float32}(4.0f0, 1.0f0, 1.0f0, 9.0f0)   # 2×2 covariance
e = Ellipse(Uncertain(Point2(100.0, 200.0), Σ); sigma=3)
source
VisualGeometryToolkitCore.DiagonalCovMat — Type
FullCovMat{N, T, C}, DiagonalCovMat{N, T, C}, IsotropicCovMat{N, T, C}
FullPrecMat{N, T, C}, DiagonalPrecMat{N, T, C}, IsotropicPrecMat{N, T, C}

A covariance (precision) by the matrix it holds: an SMatrix (full), an SDiagonal (CovMat(SDiagonal(σ₁², σ₂²))) or a ScaledIdentity (CovMat(ScaledIdentity{2}(σ²)), CovMat{2}(σ = …)). The storages order isotropic ⊂ diagonal ⊂ full. A form keeps its storage under inv and relabel; convert and promote give the coarser of two storages, never a finer one (a container of mixed storage is one concrete type); propagate through a map gives the full form; a unit change gives the diagonal form of an isotropic one (lengths and angles scale apart). Arithmetic on the structure is the matrix's own, parent(Σ); on the form itself it sees the full N × N entries and gives an SMatrix.

source
VisualGeometryToolkitCore.DiagonalPrecMat — Type
FullCovMat{N, T, C}, DiagonalCovMat{N, T, C}, IsotropicCovMat{N, T, C}
FullPrecMat{N, T, C}, DiagonalPrecMat{N, T, C}, IsotropicPrecMat{N, T, C}

A covariance (precision) by the matrix it holds: an SMatrix (full), an SDiagonal (CovMat(SDiagonal(σ₁², σ₂²))) or a ScaledIdentity (CovMat(ScaledIdentity{2}(σ²)), CovMat{2}(σ = …)). The storages order isotropic ⊂ diagonal ⊂ full. A form keeps its storage under inv and relabel; convert and promote give the coarser of two storages, never a finer one (a container of mixed storage is one concrete type); propagate through a map gives the full form; a unit change gives the diagonal form of an isotropic one (lengths and angles scale apart). Arithmetic on the structure is the matrix's own, parent(Σ); on the form itself it sees the full N × N entries and gives an SMatrix.

source
VisualGeometryToolkitCore.EssentialMat — Type
EssentialMat{T} <: AbstractFundMat{T}

Typed wrapper for a 3×3 essential matrix encoding the calibrated epipolar constraint x̂₂ᵀ E x̂₁ = 0, where x̂ᵢ = Kᵢ⁻¹ uᵢ.

Distinguished from FundMat by the additional E-manifold constraint (σ₁ = σ₂, σ₃ = 0) and by operating on calibrated (K⁻¹-mapped) points. Minimal sample size: 5 (Nistér 2004).

source
VisualGeometryToolkitCore.FeatureFrame — Type
FeatureFrame{T}

Abstract type for geometric feature frames.

A feature frame defines a transformation from canonical space (unit circle/square) to image space. The transformation encodes the feature's position, scale, and shape.

Concrete subtypes:

  • Disc{T}: 3 DOF - isotropic (translation + uniform scale)
  • OrientedDisc{T}: 4 DOF - isotropic with orientation
  • EllipticFrame{T}: 5 DOF - anisotropic (symmetric shape factor)
  • AffineFrame{T}: 6 DOF - full affine (general shape factor)

Interface

All frames implement:

  • AffineMap(frame) → AffineMap from canonical to image coordinates
  • region(frame, k=1.0) → unitless Circle or Ellipse at the k·σ contour
  • centroid(frame) → Point2{T} center position
  • Base.inv(frame) → frame with inverted transformation
source
VisualGeometryToolkitCore.FixedModels — Type
FixedModels{N, M}

Stack-allocated container for up to N candidate models of type M.

Supports for model in solutions iteration and length(solutions). Used by multi-solution solvers (e.g., 7-point F-matrix) to return 1–3 results without heap allocation.

isbitstype(FixedModels{N,M}) == true when isbitstype(M) == true.

source
VisualGeometryToolkitCore.FullCovMat — Type
FullCovMat{N, T, C}, DiagonalCovMat{N, T, C}, IsotropicCovMat{N, T, C}
FullPrecMat{N, T, C}, DiagonalPrecMat{N, T, C}, IsotropicPrecMat{N, T, C}

A covariance (precision) by the matrix it holds: an SMatrix (full), an SDiagonal (CovMat(SDiagonal(σ₁², σ₂²))) or a ScaledIdentity (CovMat(ScaledIdentity{2}(σ²)), CovMat{2}(σ = …)). The storages order isotropic ⊂ diagonal ⊂ full. A form keeps its storage under inv and relabel; convert and promote give the coarser of two storages, never a finer one (a container of mixed storage is one concrete type); propagate through a map gives the full form; a unit change gives the diagonal form of an isotropic one (lengths and angles scale apart). Arithmetic on the structure is the matrix's own, parent(Σ); on the form itself it sees the full N × N entries and gives an SMatrix.

source
VisualGeometryToolkitCore.FullPrecMat — Type
FullCovMat{N, T, C}, DiagonalCovMat{N, T, C}, IsotropicCovMat{N, T, C}
FullPrecMat{N, T, C}, DiagonalPrecMat{N, T, C}, IsotropicPrecMat{N, T, C}

A covariance (precision) by the matrix it holds: an SMatrix (full), an SDiagonal (CovMat(SDiagonal(σ₁², σ₂²))) or a ScaledIdentity (CovMat(ScaledIdentity{2}(σ²)), CovMat{2}(σ = …)). The storages order isotropic ⊂ diagonal ⊂ full. A form keeps its storage under inv and relabel; convert and promote give the coarser of two storages, never a finer one (a container of mixed storage is one concrete type); propagate through a map gives the full form; a unit change gives the diagonal form of an isotropic one (lengths and angles scale apart). Arithmetic on the structure is the matrix's own, parent(Σ); on the form itself it sees the full N × N entries and gives an SMatrix.

source
VisualGeometryToolkitCore.FundMat — Type
FundMat{T} <: AbstractFundMat{T}

Typed wrapper for a 3×3 fundamental matrix encoding the epipolar constraint u₂ᵀ F u₁ = 0 between two views.

Not a geometric transform — maps points to epipolar lines, not points to points.

source
VisualGeometryToolkitCore.HomEllipseMat — Type
HomEllipseMat{T} <: AbstractHomConicMat{T}

The homogeneous 3×3 matrix of a real, non-degenerate ellipse x̃ᵀ Q x̃ = 0, x̃ = (x, y, 1), stored as its six unique coefficients (Q₁₁, Q₁₂, Q₂₂, Q₁₃, Q₂₃, Q₃₃) — exactly symmetric by storage; indexing returns the full symmetric matrix, and arithmetic on it gives an SMatrix. Built from an Ellipse, a symmetric 3×3 matrix (or its nine entries, column-major) or the six coefficients. A matrix is checked for symmetry (isapprox(Q, Qᵀ; rtol = √eps), its off-diagonal pairs averaged), and check = true checks the class — classify_conic answering EllipseTrait, the same test — with an ArgumentError naming what it is instead; a general conic is a Conic.

source
VisualGeometryToolkitCore.IsotropicCovMat — Type
FullCovMat{N, T, C}, DiagonalCovMat{N, T, C}, IsotropicCovMat{N, T, C}
FullPrecMat{N, T, C}, DiagonalPrecMat{N, T, C}, IsotropicPrecMat{N, T, C}

A covariance (precision) by the matrix it holds: an SMatrix (full), an SDiagonal (CovMat(SDiagonal(σ₁², σ₂²))) or a ScaledIdentity (CovMat(ScaledIdentity{2}(σ²)), CovMat{2}(σ = …)). The storages order isotropic ⊂ diagonal ⊂ full. A form keeps its storage under inv and relabel; convert and promote give the coarser of two storages, never a finer one (a container of mixed storage is one concrete type); propagate through a map gives the full form; a unit change gives the diagonal form of an isotropic one (lengths and angles scale apart). Arithmetic on the structure is the matrix's own, parent(Σ); on the form itself it sees the full N × N entries and gives an SMatrix.

source
VisualGeometryToolkitCore.IsotropicPrecMat — Type
FullCovMat{N, T, C}, DiagonalCovMat{N, T, C}, IsotropicCovMat{N, T, C}
FullPrecMat{N, T, C}, DiagonalPrecMat{N, T, C}, IsotropicPrecMat{N, T, C}

A covariance (precision) by the matrix it holds: an SMatrix (full), an SDiagonal (CovMat(SDiagonal(σ₁², σ₂²))) or a ScaledIdentity (CovMat(ScaledIdentity{2}(σ²)), CovMat{2}(σ = …)). The storages order isotropic ⊂ diagonal ⊂ full. A form keeps its storage under inv and relabel; convert and promote give the coarser of two storages, never a finer one (a container of mixed storage is one concrete type); propagate through a map gives the full form; a unit change gives the diagonal form of an isotropic one (lengths and angles scale apart). Arithmetic on the structure is the matrix's own, parent(Σ); on the form itself it sees the full N × N entries and gives an SMatrix.

source
VisualGeometryToolkitCore.PrecMat — Type
PrecMat{N,T,M,F} <: StaticMatrix{N,N,T}

N×N information (precision) matrix Λ = Σ⁻¹ for per-observation residual uncertainty. Parametric in N so it sizes to the value dof for any geometric value: 2 for Point2, 3 for Disc, 5 for EllipticFrame, M for Hyperplane{M}, etc. M is the static matrix it holds (parent(Λ)), and its type is the storage: an SMatrix (full), an SDiagonal (diagonal) or a ScaledIdentity (isotropic) — see DiagonalCovMat.

Used as the storage form for sources that emit precision natively (e.g., RoMa v2 dense matcher, factor-graph SLAM backends, any EIV estimator that propagates observation noise to the constraint).

Tensor character and transformation law

Precision is a (0,2) tensor — a bilinear form with two covariant argument slots (it EATS a pair of displacement vectors: the Mahalanobis quadratic rᵀ Λ r). Under a change of coordinates with Jacobian J it pulls back:

Λ ↦ J⁻ᵀ Λ J⁻¹

This is the OPPOSITE variance of CovMat's pushforward Σ ↦ JΣJᵀ, and this covariant/contravariant law pair is exactly the bug surface the frame label exists to check: applying the covariance law to a precision matrix (or vice versa) produces a plausible-looking, silently wrong matrix. With labeled frames, propagate through a framed map dispatches to the correct law per type and records the destination frame on the result.

Frame parameter (0.9)

The trailing F <: Frame{N} names the frame the matrix's coordinates live in (e.g. ImageFrame{:left} for a per-detection pixel precision). Every historically-shaped constructor defaults it to UnlabeledFrame{N} — the gradual-typing wildcard, so pre-0.9 code compiles unchanged and unlabeled matrices propagate uncheckedly. Label with relabel; propagate through a framed map checks the frame against the map's Src and stamps the result with Dst.

Precision vs. covariance

This is distinct from Uncertain's model-side covariance role, which stores parameter uncertainty in covariance form because that case is dominated by Jacobian propagation (J Σ Jᵀ). Per-observation uncertainty on the residual side is dominated by Mahalanobis-style weighting (rᵀΛr), so storing Λ directly avoids inversions on the scoring hot path.

Example

Λ = PrecMat{2,Float32}(1.0f0, 0.0f0, 0.0f0, 1.0f0)   # identity precision
r = SVector(0.3f0, -0.1f0)
maha_sq = dot(r, Λ * r)                              # Mahalanobis²

See also: CovMat, Uncertain, propagate.

source
VisualGeometryToolkitCore.ScaledIdentity — Type
ScaledIdentity{N}(λ)

The N × N matrix λ·I, stored as the one number λ: the static, sized counterpart of LinearAlgebra.UniformScaling (which has no size), beside StaticArrays' SDiagonal (one number per axis) and SMatrix (every entry). Isotropic: a rotation leaves it unchanged. Isbits; reads as its full matrix. It stays a ScaledIdentity under inv, a scalar factor and a sum with another; a sum with an SDiagonal is an SDiagonal; every other operation gives an SMatrix. The isotropic storage of CovMat / PrecMat and the round GaussianBlur.

source
VisualGeometryToolkitCore.Uncertain — Type
Uncertain{V, M} = Attributed{V, M}   (M <: Union{CovMat, PrecMat})

A geometric value V with its 2nd-order uncertainty: an Attributed whose attributes are one of the typed matrix wrappers —

  • CovMat{N,T,M} — covariance Σ in parameter space
  • PrecMat{N,T,M} — precision Λ = Σ⁻¹ in parameter/residual space

Uncertain is an alias, not a second struct: one value-with-attributes type carries every value-plus-metadata pattern, and an uncertain value is the one whose attributes are a statistical form. It is constructed ONLY from a CovMat or a PrecMat — a bare matrix or a scalar σ does not say which form is stored, so Uncertain(v, m) with any other m is a MethodError; wrap it as what it is, CovMat(Σ) or PrecMat(Λ). Everything Attributed does it does (u.value, u.attributes, centroid, StructArrays decomposition, index and length forwarding to a vector value), and everything written against Uncertain — cov, prec, geom, propagate, Ellipse — dispatches on exactly these attributes. u.matrix reads the form (getfield(u, :attributes) is the raw field).

The matrix's nominal type tells consumers which form is stored; accessors cov and prec return whichever form the caller asks for, inverting on demand. Each consumer constructs Uncertain with the form it expects to be queried most so the inverse is paid at most once at the boundary, never in the inner loop.

Two roles, one wrapper

  • Observation-side: Uncertain{Point2, PrecMat{2,T,SMatrix{2,2,T,4}}} — a feature detection (e.g. RoMa-v2 dense match) carrying its per-observation precision. Consumed by heteroscedastic Sampson, weighted DLT, IRLS.
  • Model-side: Uncertain{HomographyMat{T}, CovMat{8,T,SMatrix{8,8,T,64}}} — a fitted model carrying its parameter covariance. Consumed by predictive scoring and downstream propagation.

Type Parameters

  • V: The wrapped geometric value (Point2, HomographyMat, Disc, …)
  • M: The matrix wrapper (CovMat{N,T,M} or PrecMat{N,T,M})

Example

# Covariance-side (e.g. propagated parameter uncertainty)
p = Uncertain(Point2(100.0, 200.0), CovMat{2,Float64}(0.1, 0.0, 0.0, 0.2))
cov(p)        # CovMat — stored form, no inversion
prec(p)       # PrecMat — computed via inv(matrix)

# Precision-side (e.g. RoMa per-detection PrecMat)
Λ = PrecMat{2,Float32}(2.0f0, 0.1f0, 0.1f0, 3.0f0)
d = Uncertain(Point2(123.4, 56.7), Λ)
prec(d)       # PrecMat — stored form, no inversion
cov(d)        # CovMat — computed via inv(matrix)
d isa Attributed   # true: the same type as Attributed(Point2(123.4, 56.7), Λ)

# A bare matrix states nothing: wrap it as the form it is
p2 = Uncertain(Point2(100.0, 200.0), CovMat(@SMatrix [0.1 0.0; 0.0 0.2]))
# An isotropic standard deviation σ: the keyword constructor of the form
p3 = Uncertain(Point2(100.0, 200.0), CovMat{2}(σ = 0.5))   # Σ = 0.25·I
Uncertain(Point2(100.0, 200.0), 0.5)   # MethodError: neither a CovMat nor a PrecMat

See also: CovMat, PrecMat, cov, prec.

source
VisualGeometryToolkitCore.classify_conic — Method
classify_conic(Q::Union{Conic, HomEllipseMat, HomCircleMat}) -> ConicTrait

Classify a conic matrix and return the appropriate Holy Trait.

Returns one of:

  • EllipseTrait(): Valid ellipse (bounded, non-degenerate)
  • HyperbolaTrait(): Hyperbola (indefinite quadratic form)
  • ParabolaTrait(): Parabola (singular quadratic form)
  • DegenerateTrait(): a point ellipse, an imaginary ellipse, or a conic with no quadratic part (a line). Intersecting line pairs classify as HyperbolaTrait and parallel pairs as ParabolaTrait (their quadratic forms).

Invariant to the conic's scale and sign (a homogeneous conic is defined only up to a nonzero multiplier). A point ellipse is told from a real one by γ, the constant term at the centre, against the rounding of the terms that produce it (|c| + 2|b||centre| + |λ|·|centre|²) magnified by the quadratic block's condition number κ — never against an absolute threshold, which called large or distant ellipses degenerate. The bound was measured: on 20,000 elongated point ellipses (κ up to 1e6) the computed |γ| stays below 0.55·κ·eps of those terms, and the test allows 2·(1 + κ)·eps. The test runs in at least Float64 on the coefficients divided by the largest, so a Float32 conic is classified as its stored coefficients define it (a 3 px Float32 ellipse at (1000, 800) is an ellipse; in Float32 arithmetic its γ sank below the noise floor), and neither a huge nor a tiny multiple of a conic overflows or underflows. An ellipse whose γ is within that noise — thin and very far along its minor axis — reads degenerate, because the arithmetic cannot tell it from a point. The checked HomEllipseMat constructor runs this same test, and Ellipse(Q) reads the centre and γ in the same precision.

source
VisualGeometryToolkitCore.correspondences — Method
correspondences(sources, targets) -> StructArray{Correspondence{S,T}}

Construct a columnar correspondence array from parallel source and target vectors.

Examples

src = [SA[1.0, 2.0], SA[3.0, 4.0]]
dst = [SA[5.0, 6.0], SA[7.0, 8.0]]
cs = correspondences(src, dst)
cs.first   # sources
cs.second  # targets
cs[1]      # first correspondence as Pair
source
VisualGeometryToolkitCore.is_valid_solution — Method
is_valid_solution(x) -> Bool

Predicate that decides whether a single solver output should be retained when packing into FixedModels. Defaults rule out non-finite results (PoseLib emits NaN/Inf for numerically degenerate samples).

Add a method for any new model type that needs a stricter check.

source
VisualGeometryToolkitCore.prec — Method
prec(u::Uncertain) -> PrecMat
prec(x) -> LinearAlgebra.I

The precision (information) form of an observation's uncertainty: returns the stored PrecMat directly, or inv of a stored CovMat (paying the inversion once at the boundary). The fallback for plain values is the identity LinearAlgebra.I — an unweighted observation — so call sites that mix plain points and Uncertain inputs need no special case for the no-weighting branch. Counterpart of cov (the Statistics.cov extension below); see Uncertain.

source
VisualGeometryToolkitCore.weight_of — Method
weight_of(x) -> Float64

The weight a stage reads off a datum: the weight attribute of an Attributed value (Attributed(R, (; weight))), as Float64, and 1.0 for an Attributed without one or a bare value. Weights travel with their data this way, never as a parallel vector (data-arguments.md).

source
VisualGeometryToolkitCore.AbstractCamera — Type
AbstractCamera

The one camera type: every camera — an unposed model (CameraModel, a NoncentralSplineModel), a posed camera (PosedCamera) and a bounded one (BoundedCamera) — subtypes it. Whether a camera carries a pose is a trait, is_posed (shared with the targets), not a second type root.

Every camera implements, in the COLMAP pixel frame:

  • project(camera, X) — a 3D point (camera frame for a model, world frame for a posed camera) to its pixel
  • backproject(camera, u) — a pixel to its ray

A posed camera (is_posed(camera) == true) also implements pose(camera) and extrinsics(camera); on an unposed one they are an ArgumentError.

Example

# Code that works with any camera type:
function process(cam::AbstractCamera, points::Vector{Point3})
    pixels = [project(cam, p) for p in points]
    # ...
end
source
VisualGeometryToolkitCore.backproject — Function
backproject(camera_or_model, pixel::StaticVector{2}) -> SVector{3}

Backproject a 2D pixel coordinate to a 3D ray direction. The return is a 1-parameter family of 3D points (depth unknown) represented as a direction vector.

source
VisualGeometryToolkitCore.extent — Function
extent(camera) -> Size2{Int}

Return the pixel-space image extent (width × height) of a camera.

Trait-dispatched via bounds_trait(camera): errors at compile time for cameras that don't carry bounds (default NoBounds()). Cameras that do carry bounds (e.g. BoundedCamera) opt in via bounds_trait(::Type{...}) = HasBounds().

source
VisualGeometryToolkitCore.feature_frame — Function
feature_frame(d) -> FeatureFrame

Return the feature frame (the detected local frame: Disc, EllipticFrame, …) of a detection or a bare FeatureFrame. Named for what it returns, so it cannot be read as "which coordinate frame".

Unified accessor: works on both FeatureFrame (returns itself) and any AbstractDetection (returns the wrapped frame; for a detection of an Uncertain frame, the bare frame without its covariance).

source
VisualGeometryToolkitCore.focal_length — Function
focal_length(camera_or_model)

Return the focal length of a camera or camera model.

For physical cameras, returns a length with units (e.g., mm). For logical cameras, returns focal length in pixels.

source
VisualGeometryToolkitCore.is_posed — Method
is_posed(camera::AbstractCamera) -> Bool
is_posed(target::AbstractTarget) -> Bool

Whether a rig member kind carries a pose — the one placement trait of both kinds. For a camera: true for a PosedCamera (a model and its extrinsics), false for an unposed model (CameraModel, NoncentralSplineModel), and the wrapped camera's answer for a BoundedCamera. For a target: true for a PosedTarget, false for an unposed one (PlanarTarget, PointTarget). It is decided by the type, so a branch on it compiles away.

The posed-only verbs — pose, extrinsics, rig membership, the StereoRig constructors that read poses — refuse an unposed camera with an ArgumentError, as pose and extrinsics refuse an unposed target (an unposed member of either kind is its own model), and PosedCamera(model, X) and PosedTarget(target, X) refuse a member that is already posed. A camera or target type of another package that carries a pose adds a method returning true.

source
VisualGeometryToolkitCore.lens — Function
lens(camera_or_model)

Return the lens model (e.g. Pinhole, a Lens, or any user-defined <: AbstractLensModel). Use this for dispatch in downstream packages.

source
VisualGeometryToolkitCore.pose — Function
pose(camera::AbstractCamera) -> EuclideanMap

Return the pose (position and orientation) of a camera in world coordinates.

The pose is the inverse of the extrinsics: it transforms from camera frame to world frame.

source
VisualGeometryToolkitCore.transfer — Function
transfer(operator, observation)

Transfer an observation from one view to another via a known multi-view geometry operator (e.g. a StereoRig, a homography, or an explicit (src_model, extrinsics, tgt_model) triple).

The operator comes first, as in the multi-view analogs project / unproject. Concrete dispatches live with the operator they consume.

source
VisualGeometryToolkitCore.unproject — Function
unproject(camera_or_model, pixel, depth) -> SVector{3}

Unproject a 2D pixel coordinate at the given depth to a 3D point. Unlike backproject (which returns a ray direction), unproject collapses the ray to a specific point using the supplied depth.

source
VisualGeometryToolkitCore.area — Function
area(primitive)

Return the area of a 2D geometric primitive.

Accessor convention (single argument).

Methods:

  • area(::Ellipse) → T (π * a * b)
  • area(::Circle) → T (π * r²)
source
VisualGeometryToolkitCore.aspect_ratio — Function
aspect_ratio(g)

Return the aspect ratio (a/b) of an ellipse-like shape.

For shape-matrix-based types (MvNormal, EllipticFrame): sqrt(λmax / λmin). For geometric types (Ellipse): a/b (semi-major / semi-minor).

A value of 1.0 indicates isotropy (circular shape).

Methods:

  • aspect_ratio(::Ellipse) → T
  • aspect_ratio(::Circle) → T (always 1.0)
  • aspect_ratio(::EllipticFrame) → T
  • aspect_ratio(::AffineFrame) → T
source
VisualGeometryToolkitCore.boundary_point — Function
boundary_point(primitive, θ)

Return a point on the boundary of a primitive at parameter θ.

Requires has_boundary(primitive) == HasBoundary().

Methods:

  • boundary_point(::Ellipse, θ) → Point2
  • boundary_point(::Rect, θ) → Point2 (constant arc length around the perimeter)
  • boundary_point(::Ellipse3D, θ) → Point3
source
VisualGeometryToolkitCore.boundary_points — Function
boundary_points(primitive, n=64)

Return n points sampled uniformly around the boundary of a primitive.

Unlike GeometryBasics.coordinates (which returns mesh/face vertices for rendering filled shapes), boundary_points samples the outline at equispaced angles θ ∈ [0, 2π). Returns n distinct points (no closing point duplication).

Requires has_boundary(primitive) == HasBoundary() and a corresponding boundary_point(primitive, θ) method.

Example

pts = boundary_points(ellipse, 32)  # 32 outline points
source
VisualGeometryToolkitCore.centroid — Function
centroid(primitive)

Return the centroid (geometric center) of a primitive.

Note: Use centroid for the geometric center/midpoint. This is distinct from GeometryBasics.origin which returns the corner/origin of a primitive.

Methods:

  • centroid(::Ellipse) → Point2{T}
  • centroid(::Circle) → Point2{T}
  • centroid(::Disc) → Point2{T}
  • centroid(::Ellipse3D) → Point3{T}
  • centroid(::Rect) → Vec{N} (midpoint, not origin)
  • centroid(::FeatureFrame) → Point2{T}
source
VisualGeometryToolkitCore.characteristic_scale — Function
characteristic_scale(g)

Return the equivalent isotropic scale of a Gaussian: σ = det(Σ)^(1/4).

This is the geometric mean of the standard deviations along the principal axes.

Methods:

  • characteristic_scale(::EllipticFrame) → T
  • characteristic_scale(::AffineFrame) → T
source
VisualGeometryToolkitCore.closest_point — Function
closest_point(geometry, p)

Return the point on geometry closest to p.

Methods:

  • closest_point(hyperplane, point): Orthogonal projection onto hyperplane

See also: signed_distance (for a hyperplane, p - closest_point(h, p) = signed_distance(h, p) · normal(h)).

source
VisualGeometryToolkitCore.coverage — Function
coverage(subject, reference)

Fraction of subject's area covered by reference: the measured shape first, the covering shape as its parameter.

Derived from overlap_area: coverage = overlap_area(subject, reference) / area(subject).

Returns a value in [0, 1] where:

  • 0 indicates no overlap
  • 1 indicates subject is fully covered by reference

Example

small = Ellipse(Point2(0.0, 0.0), 1.0, 0.5, 0.0)
large = Ellipse(Point2(0.0, 0.0), 3.0, 2.0, 0.0)
coverage(small, large)  # 1.0 (small is inside large)
coverage(large, small)  # ~0.08 (only small portion of large is covered)
source
VisualGeometryToolkitCore.dilate — Function
dilate(primitive, factor)

Dilate (scale) a geometric primitive by a factor.

Methods:

  • dilate(::Circle, factor) → Circle with scaled radius
  • dilate(::Ellipse, factor) → Ellipse with scaled semi-axes
source
VisualGeometryToolkitCore.distance — Function
distance(geometry, p)

Distance from the point p to geometry, non-negative. A signed distance is signed_distance, never this name.

Methods: none in VisualGeometryToolkitCore. A hyperplane's distance is signed: signed_distance(hyperplane, point) (abs of it for the unsigned value).

source
VisualGeometryToolkitCore.geom_rank — Method
geom_rank(::Type) -> Int

Canonical ordering rank of a geometric primitive type, used to symmetrize binary predicates (intersects, overlap_area, iou): when a pair arrives in non-canonical order (geom_rank(T1) > geom_rank(T2)), the arguments are swapped and re-dispatched, so each unordered pair needs only one method.

Unranked types return typemax(Int); a pair of unranked types is never swapped and falls through to a MethodError.

source
VisualGeometryToolkitCore.iou — Function
iou(a, b)

Compute Intersection over Union between two geometric primitives.

Symmetric convention (order doesn't matter).

Derived from overlap_area and area: iou = overlap / (area(a) + area(b) - overlap). Returns a value in [0, 1] where 1 indicates identical shapes.

source
VisualGeometryToolkitCore.normal — Function
normal(primitive)

Return the normal vector of a geometric primitive.

Methods:

  • normal(::Hyperplane) → unit normal vector
  • normal(::Ellipse3D) → unit normal of the ellipse's plane
  • normal(s, x) → unit normal of the surface s at its point x (Quad, MappedSurface)
source
VisualGeometryToolkitCore.offset — Function
offset(hyperplane)

Return the signed distance from the origin to the hyperplane.

For a hyperplane with coefficients [n₁, n₂, ..., nₘ, d]:

  • offset(h) = -d (signed distance along normal)
source
VisualGeometryToolkitCore.overlap_area — Function
overlap_area(a, b)

Compute the area of intersection between two geometric primitives.

Symmetric convention (order doesn't matter): arguments are put into canonical order via geom_rank before dispatch.

Returns the area in squared units of the input coordinates. Returns 0.0 if the shapes do not intersect.

Analytic methods (exact):

  • overlap_area(::Ellipse, ::Ellipse) → Float64 (GTE port)
  • overlap_area(::Circle, ::Circle) → Float64 (lens formula)
  • overlap_area(::Circle, ::Ellipse) → Float64 (via GTE)
  • overlap_area(::Ellipse, ::Rect) → Float64 (circle-polygon)
  • overlap_area(::Circle, ::Rect) → Float64 (circle-polygon)
  • overlap_area(::Circle/::Ellipse, ::Polygon) → Float64 (convex polygon)
  • overlap_area(::Rect, ::Rect) → Float64

Pairs without an analytic method fall back to the BoundarySampled overlap method (deterministic boundary polygonization + convex clipping); see overlap_method.

source
VisualGeometryToolkitCore.overlap_method — Function
overlap_method(a, b) -> OverlapMethod

Report how overlap_area computes the intersection area for this pair of primitives: AnalyticOverlap() for pairs with an exact closed-form method, BoundarySampled() for the deterministic polygonization fallback.

source
VisualGeometryToolkitCore.project — Function
project(operator, geometry)

Project geometry via an operator.

Methods:

  • project(camera, point3d): Camera projection (3D → 2D)

See also: closest_point(hyperplane, p), the orthogonal projection onto a hyperplane.

source
VisualGeometryToolkitCore.region — Function
region(frame, k=1.0)

THE detection → primitive gate: the image region supported by a feature frame at the k·σ contour, returned as a plain UNITLESS primitive (units are stripped here, once, instead of ad-hoc ustrip calls in algorithms).

Arguments

  • frame: A FeatureFrame (Disc, OrientedDisc, EllipticFrame, AffineFrame)
  • k::Real=1.0: Sigma multiplier (1.0 = 1σ contour)

Returns

  • Circle for Disc and OrientedDisc
  • Ellipse for EllipticFrame and AffineFrame

Methods:

  • region(::Disc, k) → Circle
  • region(::EllipticFrame, k) → Ellipse
  • region(::AffineFrame, k) → Ellipse
source
VisualGeometryToolkitCore.scale — Function
scale(frame)

Return the characteristic scale of a feature frame.

For isotropic frames (Disc, OrientedDisc), this is the σ parameter. For anisotropic frames, use characteristic_scale instead.

Methods:

  • scale(::Disc) → T
  • scale(::OrientedDisc) → T
source
VisualGeometryToolkitCore.shape_factor — Function
shape_factor(g)

The factor F of an elliptical region's matrix M = F·Fᵀ (shape_matrix): the linear part of the affine map that takes the unit disc onto the region, {c + F u : ‖u‖ ≤ 1}.

For EllipticFrame, the symmetric factor S (M = S²); for AffineFrame, the general factor A (M = A·Aᵀ, A keeping the in-plane rotation that M loses); for Ellipse, R(θ)·diag(a, b).

Methods:

  • shape_factor(::EllipticFrame) → SMatrix{2,2}
  • shape_factor(::AffineFrame) → SMatrix{2,2}
  • shape_factor(::Ellipse) → SMatrix{2,2}
source
VisualGeometryToolkitCore.shape_matrix — Function
shape_matrix(g)

The shape matrix M of an elliptical region {x : (x-c)ᵀ M⁻¹ (x-c) ≤ 1} (the ellipsoidal-calculus E(c, M)), symmetric positive-definite: M = F·Fᵀ with F its shape_factor (S² for an EllipticFrame, A·Aᵀ for an AffineFrame).

It is the region's shape, not its second moment: the uniform density on the region has covariance M/4, and in affine feature detection the "second-moment matrix" is the structure tensor μ ≈ M⁻¹. A frame built from a Gaussian N(c, Σ) takes its 1σ contour, M = Σ (EllipticFrame of an MvNormal, a Paraboloid3D's equivalent Gaussian).

Methods:

  • shape_matrix(::EllipticFrame) → SMatrix{2,2,T,4}
  • shape_matrix(::AffineFrame) → SMatrix{2,2,T,4}
  • shape_matrix(::Ellipse) → SMatrix{2,2,T,4}
  • shape_matrix(::Paraboloid3D) → SMatrix{2,2,T,4}
  • shape_matrix(::Disc), shape_matrix(::OrientedDisc) → σ² I, SMatrix{2,2,T,4}
source
VisualGeometryToolkitCore.signed_distance — Function
signed_distance(geometry, p)

Signed distance from the point p to an oriented geometry: its sign says which side p is on.

Methods:

  • signed_distance(hyperplane, point): n·p + d, positive on the normal's side
source
VisualGeometryToolkitCore.AbstractSolverBackend — Type
AbstractSolverBackend

Holy trait for selecting which implementation of a minimal solver to use.

Concrete subtypes:

  • NativeSolver(): Pure-Julia implementations (default, zero-allocation)
  • PoseLibSolver(): PoseLib C++ library via ccall

Carried as the backend field of the MinimalSolver verb layer (the public solve protocol) and dispatched on by the positional kernels:

solve(Homography4pt(), cs, idx)                # default (NativeSolver)
solve(Homography4pt(PoseLibSolver()), cs, idx) # PoseLib backend
p3p(PoseLibSolver(), rays, X)                  # kernel-level backend call
source
VisualGeometryToolkitCore.BoundsTrait — Type
BoundsTrait

Trait indicating whether a type carries pixel-space image bounds (width × height). Cameras parsed from SfM/MVS exports (COLMAP, ETH3D, ScanNet) typically wrap their intrinsics+lens+pose in a BoundedCamera so downstream geometry code can extent(cam), is_in_image(cam, p), and bound frustum visualizations.

source
VisualGeometryToolkitCore.ConicTrait — Type
ConicTrait

Trait type for dispatch on conic sections.

Subtypes (proper conics):

  • CircleTrait: Circle (equal semi-axes, eccentricity = 0)
  • EllipseTrait: Ellipse (eccentricity < 1)
  • ParabolaTrait: Parabola (eccentricity = 1, tangent to line at infinity)
  • HyperbolaTrait: Hyperbola (eccentricity > 1, crosses line at infinity twice)

Special:

  • DegenerateTrait: Degenerate conic (point, line, or two lines)
source
VisualGeometryToolkitCore.FrameScaleTrait — Type
FrameScaleTrait

Trait distinguishing feature frames by their local shape, the DOF levels of the FeatureFrame interface (conventions: the FeatureFrame interface table):

  • PointShape(): a point, no scale and no shape (PointFrame, 2 DOF)
  • IsotropicScale(): Frames with a single scale σ (Disc, OrientedDisc)
  • ShapeFactorScale(): Frames with a 2×2 shape factor (EllipticFrame, AffineFrame)
source
VisualGeometryToolkitCore.OverlapMethod — Type
OverlapMethod

Trait describing how overlap_area computes the intersection area for a pair of primitives.

  • AnalyticOverlap(): an exact closed-form method exists for the pair
  • BoundarySampled(): deterministic fallback — both boundaries are polygonized at 64 samples and the convex polygons are clipped exactly

Query with overlap_method(a, b).

source
VisualGeometryToolkitCore.classify_conic — Function
classify_conic(Q) -> ConicTrait

Classify a conic matrix and return the appropriate trait.

Returns one of:

  • CircleTrait(): Circle
  • EllipseTrait(): Ellipse
  • ParabolaTrait(): Parabola
  • HyperbolaTrait(): Hyperbola
  • DegenerateTrait(): Degenerate conic (point, line, or two lines)

Implementations are provided for HomEllipseMat and HomCircleMat.

source

Uncertainty Accessors

prec is documented above with the core types; cov extends Statistics.cov (unexported — reachable as Statistics.cov):

Statistics.cov — Function
cov(u::Uncertain) -> CovMat

The covariance form of an observation's uncertainty: returns the stored CovMat directly, or inv of a stored PrecMat (paying the inversion once at the boundary). Extends Statistics.cov for Uncertain only; counterpart of prec.

source

Fit Results

Every estimator returns a FitResult: a fixed core — the estimate, why it stopped (its termination record), how many iterations, the residual RMS over n — plus solver-specific metadata selected by type parameter. Read it through the accessors below (estimate(r), retcode(r), …, and the metadata's own such as weights(r)), never by field name. A property spelling still forwards to the metadata for older call sites; a name on neither is an error, never nothing.

VisualGeometryToolkitCore.FitResult — Type
FitResult{P, M}

Result of a fit: estimate::P, its termination record — retcode::ReturnCode.T (why it stopped, the verdict: ReturnCode) and stop_rule::StopRule (which rule fired: StopRule) — iterations (0 for a closed-form solve), rms over n residuals, and solver-specific metadata::M (nothing for the lean default; see BundleMetadata).

FitResult(estimate, code::ReturnCode.T, rule::StopRule, iterations, rms, n, metadata)

Every producer records the code and the rule; a loop that reports a legacy Symbol records retcode_from_symbol(retcode, rule)... (its success rule rule), the one map from a Symbol.

For a RANSAC the loop count iterations is its trials — the hypotheses drawn.

Read a result through its accessors, which are the API: estimate, retcode, stop_rule, converged, iterations, rms, metadata, and the metadata's own (weights, dof, …). Field and property names are an implementation detail.

(A property spelling still resolves, so older call sites keep working: the core fields, the derived converged, and metadata fields forwarded from metadata. A property that exists on none of them is an error; a metadata type with a field named like a core accessor (estimate, retcode, stop_rule, iterations, rms, n, metadata, converged) is rejected at construction.)

source
VisualGeometryToolkitCore.BundleMetadata — Type
BundleMetadata(weights, residuals, fixed_frames, dof, loss_width, before, after; scale, scale_source)

Diagnostics of a bundle refinement: the final per-observation weights its robust loss left and residuals (each observation's residual NORM, in the bundle's order — what an inlier classification of the refined model reads; a weight is the loss's guide to its optimizer, never inverted back into a residual), the gauge-fixing fixed_frames, the degrees of freedom dof, the robust loss's frozen loss_width (NaN under plain least squares — a LOSS WIDTH, not a noise scale), and before/after residual summaries as concrete (; rms, median, p90) NamedTuples — the FitResult's own rms mirrors after.rms first-class.

The bundle's scale record (the robust-estimation contract), required: scale, the noise scale it ran with (a LINEAR scale; NaN with ScaleNone, plain least squares), and scale_source (ScaleSource), read by noise_scale and scale_source. Its termination record is the FitResult's core (retcode, stop_rule): build the result as FitResult(estimate, code, rule, iterations, rms, n, metadata).

source
VisualGeometryToolkitCore.converged — Function
converged(r::FitResult) -> Bool

Whether the fit succeeded — STRICT: successful_retcode of its retcode, for every producer. A run that hit its iteration (or RANSAC trial) cap, its time cap or a stall did not converge, and a closed-form solve did. For a RANSAC, whether it FOUND a model is found_model. Also reachable as the property r.converged.

source
VisualGeometryToolkitCore.rms — Function
rms(r::FitResult) -> Float64

Root-mean-square residual over the n residuals the fit reports on (r.n) — for a robust fit, the accepted set, so the number is not outlier-dominated.

source
rms(residuals::AbstractVector, n::Integer = length(residuals)) -> Float64

The root-mean-square residual √(Σ rᵢ² / n) a fit reports (its rms): over n points, so a point's stacked residual rows (two per pixel point) enter as its squared residual norm — rms(rows, n_points) — and scalar errors as themselves, rms(errors). The one place it is computed.

source
VisualGeometryToolkitCore.metadata — Function
metadata(r::FitResult{P, M}) -> M

The solver-specific diagnostics; nothing for a lean result. Its fields are also reachable directly on r as properties.

source
VisualGeometryToolkitCore.weights — Function
weights(r::FitResult) -> AbstractVector

Per-datum weights in [0, 1] from the metadata (r.metadata.weights): a plain vector in the data's order (a lazy all-ones unit_weights for an L2 result). What they mean is the producer's weight_kind, and inlier_mask(r) cuts them by it. Errors on a metadata type that carries none — including the lean nothing. A contract generic: a metadata that stores its weights otherwise adds a method.

source
VisualGeometryToolkitCore.dof — Function
dof(r::FitResult) -> Int

Residual degrees of freedom from the metadata (r.metadata.dof). Errors on a metadata type that carries none.

source
VisualGeometryToolkitCore.nested_metadata — Function
nested_metadata(::Type{M}) -> Tuple{Vararg{Symbol}}

The fields of the metadata type M that are themselves metadata records whose fields a FitResult should forward too: for each listed field g, r.f reaches r.metadata.g.f for every field f of g's type, beside the outer fields. Default (). A method is added once per metadata type, next to its definition (nested_metadata(::Type{<:MyMeta}) = (:calibration,)).

The listed fields stay reachable under their own name. A nested field named like a core field of the result, an outer field or another nested field is refused when the result is built, exactly as an outer one is.

source
VisualGeometryToolkitCore.map_estimate — Function
map_estimate(f, r::FitResult) -> FitResult

r with f applied to its estimate, everything else as it was (the termination record, iterations, rms, n, the metadata): the one way a stage hands on a result whose model it re-expresses (a unit attached, frame labels restored). A RANSAC result's estimate is Union{M, Nothing}: f maps a present model, an absent one stays nothing, and the result keeps the union over f's image of M (f needs no method for nothing). Any other result's estimate is concrete and simply mapped.

source

A robust result records ONE scale — the one it ran with, or the one it estimated — and where it came from: its metadata's scale and scale_source, read by noise_scale and scale_source. A downstream stage takes the hand-off as scale = result; scale_input parses a stage's scale/width keywords, exactly one of which it requires.

VisualGeometryToolkitCore.ScaleSource — Type
ScaleSource

Where a robust result's scale came from — one of:

  • ScaleGiven: a number the caller gave (scale = σ);
  • ScaleUpstream: an earlier stage's result (scale = result, its noise_scale);
  • ScaleEstimated: estimated by this stage — a RANSAC scorer's consensus partition, an EM fit's E-step;
  • ScaleNone: no scale — a plain least-squares stage given none, or a stage given only a width (never backed out into a scale); the scale is NaN.

An @enum (isbits): a metadata that carries it stays concretely typed.

source
VisualGeometryToolkitCore.noise_scale — Function
noise_scale(result) -> T

The scale a robust result recorded — the one it ran with, or the one it estimated (its metadata's scale; scale_source says which). The hand-off: a downstream stage takes it as scale = result. An ArgumentError for a result whose source is ScaleNone (a plain least-squares stage given no scale, or a stage given only a width), so its NaN is never handed on.

A metadata type answers through its fields scale and scale_source; one that records the scale otherwise adds a method on its metadata type. A stage's parsed scale_input answers too: the scale it was given (refused for a width, whose source is ScaleNone).

source
VisualGeometryToolkitCore.ScaleInput — Type
ScaleInput

The scale input of one robust stage, parsed once by scale_input: scale (the noise scale σ, NaN when a width was given) or width (the loss width, NaN when a scale was given) — exactly one is finite, in the caller's float type — and the ScaleSource the stage records.

source
VisualGeometryToolkitCore.scale_input — Function
scale_input(scale, width) -> ScaleInput

The scale input of a robust estimator, from its two keywords — EXACTLY ONE of:

  • scale = σ: a positive, finite noise scale (ScaleGiven);
  • scale = result: an earlier robust result, read by noise_scale (ScaleUpstream; a result that recorded no scale is refused);
  • width = w: a positive, finite loss width. The stage records ScaleNone (its scale is NaN) and the width itself: a width may be cross-validated rather than generative, so no scale is ever backed out of it (w / c), and a downstream stage needs its own scale or width.

Neither, or both, is an ArgumentError naming both keywords. A stage with no robust loss (plain least squares) takes neither, and refuses one it would ignore — that check is the stage's, which knows its loss.

source

Why a fit stopped is its termination record, a ReturnCode and a StopRule in the result's core: see the Termination Record page.

Its per-datum weights in [0, 1] are weights(result), a plain vector; what they mean — and so where inlier_mask(result) cuts them — is the producer type's WeightKind, read by weight_kind (Estimation Interfaces).

Index