Intrinsics and Sensors API

A camera's intrinsics (the logical, projective and pixel forms) and its sensor. The cameras that hold them are on the Cameras API page.

VisualGeometryToolkitCore.Cameras.CameraCalibrationMat — Type
CameraCalibrationMat{T} <: StaticMatrix{3, 3, T}

The pinhole calibration matrix

[fx  s  cx]
[ 0 fy  cy]
[ 0  0   1]

stored as its five parameters (fx, fy, s, cx, cy): indexing returns the full matrix, its structural entries exactly 0 and 1. Every constructor from a 3×3 matrix checks that structure (row 3 = 0 0 1 and K[2, 1] = 0, within atol = 1e-6; the transpose named as the likely fix) — the storage cannot hold anything else; check = false skips only the positive-focal check. Arithmetic on it gives an SMatrix; inv(K) is analytic, an SMatrix with exact structural zeros (K⁻¹ is not a calibration matrix). Isbits and eltype-generic (Float32, ForwardDiff Dual).

source
VisualGeometryToolkitCore.Cameras.CameraCalibrationMat — Method
CameraCalibrationMat(f::Quantity, pp::AbstractVector{<:Quantity}) -> CameraCalibrationMat{Float64}
CameraCalibrationMat(f::Tuple{T,T}, pp::AbstractVector{<:Quantity}) where T<:Quantity -> CameraCalibrationMat{Float64}

Construct camera intrinsics matrix K from focal length(s) and principal point in pixel units.

Units are enforced at construction but stored internally as unitless Float64 for performance. A pixel is dimensionless, so f and pp are dimensionless quantities (800.0px); a length (16.0mm, a metric focal length without its pitch) is a DimensionError.

Arguments

  • f: Focal length in pixels - either scalar for isotropic or tuple (fx, fy) for anisotropic
  • pp: Principal point in pixels as 2D vector [cx, cy]

Returns

3×3 unitless Float64 camera intrinsics matrix in column-major order:

[fx  0  cx]
[ 0 fy  cy]
[ 0  0   1]

Examples

# Isotropic focal length (fx = fy)
K = CameraCalibrationMat(800.0px, [320.0px, 240.0px])

# Anisotropic focal length (fx ≠ fy)
K = CameraCalibrationMat((800.0px, 805.0px), [320.0px, 240.0px])
source
VisualGeometryToolkitCore.Cameras.CameraCalibrationMat — Method
CameraCalibrationMat(f::Quantity, pitch::Size2{<:Quantity}, pp::AbstractVector{<:Quantity}) -> CameraCalibrationMat{Float64}

Construct camera intrinsics matrix K from physical focal length, pixel pitch, and principal point.

Units are enforced at construction but stored internally as unitless Float64 for performance.

This constructor converts from metric units to pixel units using the factorization:

K = [1  0  cx] [1/px   0   0] [f  0  0]
    [0  1  cy] [0   1/py  0] [0  f  0]
    [0  0   1] [0    0    1] [0  0  1]

where f is in mm, px/py are pixel pitch in mm/px, and (cx,cy) are in pixels.

Arguments

  • f::Quantity: Focal length in physical units (e.g., mm)
  • pitch::Size2{<:Quantity}: Pixel pitch (e.g., Size2(width=5.86μm/px, height=5.86μm/px))
  • pp::AbstractVector{<:Quantity}: Principal point in pixels [cx, cy]

Returns

3×3 unitless Float64 camera intrinsics matrix with focal length in pixels:

[αx  0  cx]
[ 0  αy cy]   where αx = f/px, αy = f/py
[ 0  0   1]

Examples

# From sensor datasheet and lens specification
f = 16.0mm                                    # Lens focal length
pitch = Size2(width=5.86μm/px, height=5.86μm/px)  # Sensor pixel pitch
pp = [320.0px, 240.0px]                       # Principal point (image center)
K = CameraCalibrationMat(f, pitch, pp)
# K[1,1] ≈ 2730.38 (focal length in pixels)
source
VisualGeometryToolkitCore.Cameras.CameraCalibrationMat — Method
CameraCalibrationMat(f, pp::AbstractVector{<:Real}; check = true) -> CameraCalibrationMat
CameraCalibrationMat(f, r::Rect2{<:Real}; check = true) -> CameraCalibrationMat
CameraCalibrationMat(f, sz::Size2{<:Real}; check = true) -> CameraCalibrationMat

The zero-skew calibration matrix of focal length f in pixels and a principal point given by plain numbers, which are pixels (a pixel is dimensionless):

  • pp, the principal point (cx, cy): a Point2, an SVector or any 2-vector;
  • r, an image rectangle: the principal point is its centroid;
  • sz, an image size: the principal point is the centre of Rect(sz), the image [0, W] × [0, H] in Core's COLMAP convention (pixel centres at 0.5, 1.5, …), so (W/2, H/2).

f is a real (isotropic, fx = fy), an (fx, fy) tuple, or the same as px quantities (412.0px, a length is a DimensionError). The element type is the floating-point promotion of the inputs (Float32 stays Float32, integers give Float64). These are the 9-entry constructor's matrix [fx 0 cx; 0 fy cy; 0 0 1], checked like it: check refuses a non-positive focal length (ArgumentError).

Examples

julia> sz = Size2(320, 240);

julia> K = CameraCalibrationMat(412.0, sz);   # principal point at the image centre

julia> (K[1, 1], K[2, 2], K[1, 3], K[2, 3])
(412.0, 412.0, 160.0, 120.0)

julia> K == CameraCalibrationMat(412.0, Rect(sz)) == CameraCalibrationMat(412.0, centroid(Rect(sz)))
true

julia> CameraCalibrationMat((412.0, 410.0), Point2(161.5, 119.0))[2, 2]
410.0

julia> CameraCalibrationMat(412.0px, sz) == K
true
source
VisualGeometryToolkitCore.Cameras.CameraCalibrationMat — Method
CameraCalibrationMat(M::AbstractMatrix{<:Real}; check=true) -> CameraCalibrationMat

Construct from a 3×3 matrix (e.g., from OpenCV calibration JSON).

Values are stored unitless (COLMAP convention: pixel centers at 0.5). An integer, rational or irrational matrix is promoted to Float64; any other concrete real element type is kept, so a matrix of ForwardDiff Duals gives a Dual calibration matrix that automatic differentiation runs through. The pinhole structure (upper-triangular, last row [0, 0, 1]) is always checked, and names the transpose when the rows are swapped; check adds the positive focals.

Example

# From OpenCV JSON (row-major nested arrays)
Km = [[800, 0, 320], [0, 800, 240], [0, 0, 1]]
K = CameraCalibrationMat(stack(Km)')
source
VisualGeometryToolkitCore.Cameras.CameraCalibrationMat — Method
CameraCalibrationMat(s::LinearAlgebra.UniformScaling)
    -> CameraCalibrationMat

Identity shortcut: CameraCalibrationMat(I) returns CameraCalibrationMat{Float64} with K = SMatrix{3,3,Float64}(I). Supply Float32(1)*I to choose the eltype. Only the identity: α·I with α ≠ 1 has K₃₃ = α, not a calibration matrix's structure (ArgumentError; the calibration of focal α is CameraCalibrationMat(Diagonal(SVector(α, α, 1)))).

source
VisualGeometryToolkitCore.Cameras.LogicalIntrinsics — Type
LogicalIntrinsics{T}

Camera intrinsics containing only the calibration matrix K (dimensionless), parametric in storage element type T <: Real. Defaults to Float64 for all existing call sites; supply a Float32 CameraCalibrationMat to get single-precision storage end-to-end (useful for GPU pipelines).

Used when physical parameters cannot be disentangled from K, such as when K is recovered from autocalibration, Zhang's method, or other calibration techniques that don't provide metric information about the sensor.

Fields

  • K::CameraCalibrationMat{T}: 3×3 calibration matrix
  • K_inv::SMatrix{3,3,T,9}: Precomputed inverse of K for efficient backprojection

Examples

# From autocalibration (defaults to Float64 storage)
K = CameraCalibrationMat(800.0px, [320.0px, 240.0px])
intrinsics = LogicalIntrinsics(K)              # LogicalIntrinsics{Float64}

# Float32 path for GPU pipelines
K32 = CameraCalibrationMat(Float32[1 0 0; 0 1 0; 0 0 1])
intrinsics32 = LogicalIntrinsics(K32)          # LogicalIntrinsics{Float32}
source
VisualGeometryToolkitCore.Cameras.LogicalIntrinsics — Method
LogicalIntrinsics(f::Quantity, pp::AbstractVector{<:Quantity}) -> LogicalIntrinsics

Convenience constructor for LogicalIntrinsics from focal length and principal point (both in pixels).

This constructor builds the calibration matrix K internally. Use this when you have calibrated intrinsics but no physical sensor parameters.

Example

logical = LogicalIntrinsics(800.0px, [320.0px, 240.0px])
source
VisualGeometryToolkitCore.Cameras.LogicalIntrinsics — Method
LogicalIntrinsics(f::Quantity, pitch::Size2{<:Quantity}, pp::AbstractVector{<:Quantity}) -> LogicalIntrinsics

Physical-spec construction: build the calibration matrix from a metric focal length and pixel pitch, then store ONLY K. The physical scale is construction-boundary metadata — it belongs to the Sensor record, not the intrinsics (the former PhysicalIntrinsics carried it redundantly and doubled the camera dispatch table; demoted 2026-07, audit #15).

Example

f = 16.0mm
pitch = Size2(width=5.86μm/px, height=5.86μm/px)
pp = [320.0px, 240.0px]
intrinsics = LogicalIntrinsics(f, pitch, pp)
source
VisualGeometryToolkitCore.Cameras.LogicalIntrinsics — Method
LogicalIntrinsics(f::Tuple{T,T}, pp::AbstractVector{<:Quantity}) where T<:Quantity -> LogicalIntrinsics

Convenience constructor for LogicalIntrinsics with anisotropic focal lengths (fx ≠ fy).

Example

# Different focal lengths in x and y
logical = LogicalIntrinsics((800.0px, 805.0px), [320.0px, 240.0px])
source
VisualGeometryToolkitCore.focal_length — Method
focal_length(intrinsics::LogicalIntrinsics) -> Tuple{Float64, Float64}

Get focal lengths (fx, fy) from LogicalIntrinsics K matrix (unitless, in pixels).

Returns a tuple (fx, fy) extracted from the calibration matrix K. For square pixels, fx ≈ fy.

The other forms answer the focal length a FULL field of view θ implies: focal_length(resolution::Size2, θ; dimension = :horizontal) in pixels and focal_length(sensor::Sensor, θ; dimension = :horizontal) as a length (see their docstrings); angle_of_view is their inverse for a camera.

Example

intrinsics = LogicalIntrinsics(K)
fx, fy = focal_length(intrinsics)  # Returns (Float64, Float64) in pixels
source
VisualGeometryToolkitCore.Cameras.ProjectiveIntrinsics — Type
ProjectiveIntrinsics{T <: Real}(center)
ProjectiveIntrinsics(center)

The intrinsics of a projective ("partially calibrated") camera: the principal point center (Point2, COLMAP pixels) and nothing else. Its ray frame is PROJECTIVE: centred pixels u − center, defined only up to the plane homography that absorbs the focal length. There is no focal-length field, and none is implied — in particular it is not f = 1. Anything that needs a metric ray has no method and raises a MethodError (focal_length, calibration_matrix, unproject, P3P, absolute pose), except the field of view, which is refused with an ArgumentError: angle_of_view and fov_radius, and a finite max_fov in undistorted_rect (use max_fov = Inf).

CameraModel(ProjectiveIntrinsics(c), lens) projects, back-projects and undistorts exactly as CameraModel(LogicalIntrinsics(K), lens) with the unit focal K = [1 0 cx; 0 1 cy; 0 0 1] does: both go through the same code, which reads the pixel matrix at _K / _K_inv.

ProjectiveIntrinsics{T}(center) stores the centre in T (a floating-point or AD eltype; an integer or rational T is an ArgumentError); ProjectiveIntrinsics(center) takes T from center (integers become Float64). See principal_point, parameter_names ((:cx, :cy)), convert_eltype and convert_frame.

julia> using VisualGeometryToolkitCore

julia> ProjectiveIntrinsics(Point2(2120.0, 1416.0))
ProjectiveIntrinsics(cx = 2120.0, cy = 1416.0)
source
VisualGeometryToolkitCore.Cameras.principal_point — Method
principal_point(intrinsics::ProjectiveIntrinsics{T}) -> Point2{T}
principal_point(intrinsics::LogicalIntrinsics{T}) -> Point2{T}

The principal point, in COLMAP pixels: a projective camera's center, a logical camera's (K[1, 3], K[2, 3]) — the one accessor for both kinds of intrinsics.

source
VisualGeometryToolkitCore.Cameras.CMOS_SENSORS — Constant
CMOS_SENSORS

Database of common CMOS image sensors indexed by manufacturer and model.

CMOS_SENSORS["Sony"]["IMX174"]      # 1920×1200 @ 5.86μm
CMOS_SENSORS["Sony"]["IMX250"]      # 2448×2048 @ 3.45μm
CMOS_SENSORS["OmniVision"]["OV9281"] # 1280×800 @ 3.0μm
source
VisualGeometryToolkitCore.Cameras.Sensor — Type
Sensor{TR, TP}

Image sensor specification with resolution and pixel pitch.

Fields

  • resolution::Size2{TR}: Pixel count (width × height in px; dimensionless, a length is a DimensionError)
  • pitch::Size2{TP}: Pixel pitch (physical size per pixel, e.g., μm/px; a length, px being dimensionless)

Constructors

Sensor(Size2(width=1920px, height=1200px), 5.86μm)
Sensor(Size2(width=1920, height=1200), 5.86μm)  # Integers → px

See Also

source

Index