Coordinate Frames
VisualGeometryToolkitCore records which coordinate frame a map consumes and produces at the type level (since 0.7). A frame tag is a singleton type — zero fields, zero runtime cost — carried by EuclideanMap and HomographyMap as trailing Src/Dst type parameters. Composition and inversion are then frame-checked by dispatch: the pose-vs-extrinsics direction becomes a dispatch fact instead of a docstring convention.
The Frame{N} hierarchy
Frame{N} is the abstract supertype of frame tags of dimension N. The hierarchy is open: downstream packages declare their own frames
struct LidarFrame <: Frame{3} endand participate in frame-checked composition with no changes to VisualGeometryToolkitCore. The tags shipped here:
| tag | dim | meaning |
|---|---|---|
UnlabeledFrame{N} | N | "no frame recorded" — the gradual-typing wildcard |
WorldFrame | 3 | the world (scene) frame |
CameraFrame | 3 | the camera-centered frame (+Z along the optical axis) |
ViewFrame{id} | 3 | the camera frame of a specific view (since 0.8) |
TargetFrame{id} | 3 | the body frame of a specific calibration target |
BodyFrame{id} | 3 | the frame of a specific rigid body (a tracked or mounted rig) |
TargetPlaneFrame | 2 | calibration-target plane frame |
PixelFrame{Origin} | 2 | pixel frame tagged by origin convention (:colmap, :julia, :opencv) |
ImageFrame{id} | 2 | canonical pixel frame of view id |
RetinalFrame{id} and subtypes | 2 | ray frames of the viewing sphere (see The Framed Imaging Chain) |
DistortedFrame{id} | 2 | post-lens, pre-calibration frame |
The monogram bridge
The Drake monogram symbol X_AB — "pose of frame B expressed in frame A", which maps B-coordinates to A-coordinates — corresponds to EuclideanMap{..., Src = B, Dst = A}. This bridge is stated once and used throughout: a camera pose is X_WC (Src = CameraFrame, Dst = WorldFrame), camera extrinsics are X_CW, and a two-view relative transform is X_{V₂V₁} (Src = ViewFrame{id₁}, Dst = ViewFrame{id₂}).
The typed algebra follows: inv swaps the frame tags (X_AB⁻¹ = X_BA), so inv(::CameraPose)is a CameraExtrinsics — the frame-pair aliases CameraPose, CameraExtrinsics, and the concrete solver currency Extrinsics3 are plain EuclideanMaps under labeled frames, not wrappers.
The wildcard truth table
A ∘ B applies B first; the junction is B's Dst meeting A's Src. The result always keeps B's Src and A's Dst. UnlabeledFrame is the composition wildcard:
B.Dst | A.Src | junction | result |
|---|---|---|---|
F (labeled) | F (same) | checked | composes |
F (labeled) | G ≠ F | rejected | MethodError |
| any | UnlabeledFrame | unchecked | composes |
UnlabeledFrame | any | unchecked | composes |
The same table governs every frame-checked junction in the package: EuclideanMap/HomographyMap composition, the imaging-chain stages (FramedStage), the slots of an EpipolarMap under ∘, and frame-labeled propagate. A labeled-labeled mismatch is always an explicit MethodError — never a silent fall-through to an unchecked composition.
This rule is deliberately anti-viral: every constructor that does not state frames produces Src = Dst = UnlabeledFrame{N}, so pre-frame code compiles and behaves unchanged, and labels never force themselves onto code that does not opt in.
Escape hatches: relabel and unlabel
relabel replaces the frame tags of a map (zero-cost, unchecked — a deliberate override for trust boundaries such as dataset loaders and solver outputs); unlabel erases them, making the map compose with anything under the wildcard rule. Both verbs are house-wide: they apply to maps, epipolar forms (slot tags), statistical forms (CovMat/PrecMat frame tags, one tag rather than two), and batched stages.
E = EuclideanMap(R, t) # UnlabeledFrame both ends
X_CW = relabel(WorldFrame, CameraFrame, E) # now checked as extrinsics
X_WC = inv(X_CW) # frames swap: a pose
unlabel(X_WC) # back to the wildcardView-identity symbol frames
Since 0.8, Symbol type parameters distinguish instances, not just conventions: ViewFrame{:left} is a different frame than ViewFrame{:right}, so a labeled junction between two cameras' frames is a MethodError instead of a silent CameraFrame collision. The 2D counterpart ImageFrame{id} tags which view an image point belongs to; origin conventions remain the orthogonal PixelFrame{Origin} axis (convert origins first, then label the view — an ImageFrame{id} point is always read in the canonical :colmap convention).
StereoRig mints per-view identities on request (see Stereo Rigs and Uncertainty); the reserved symbol :_ is the designated anonymous view identity used by the imaging-chain mints when no rig is in play — a real label (junctions still check by frame kind), not a wildcard.
Pixel-origin conversion
Origin conversion is a labeled rigid map between two pixel frames, built by the constructor-as-factory on the frame types:
T = EuclideanMap(PixelFrame{:colmap}, PixelFrame{:julia})
T.t == Vec2(0.5, 0.5) # true
pt_julia = T(pt_colmap)This is the only origin-conversion API; it composes (frame-checked) with other labeled 2D maps and fuses in image_warp chains like any EuclideanMap{2}.
Frames and units
A frame tag says which coordinates a map consumes and produces. A unit says what the numbers measure, and the two are independent. A pose between two 3D frames holds its translation in metres (see Coordinate Transforms), while pixel coordinates carry no unit at all: their PixelFrame tag is their unit. A pixel is dimensionless in FlexUnits, so px quantities are used only for sizes and densities. Both leave a value at the same place. An estimator strips the unit and normalizes the frame once at entry, and it restores both once at exit.
See also
- Epipolar Forms — frame tags on the slots of a bilinear form
- Stereo Rigs and Uncertainty — frames-native rigs, frame-labeled covariance
- The Framed Imaging Chain — the frame-to-frame stages of one camera
- Frames API