COLMAP

The COLMAP adapter: the wire records, the unit contract, the model directory reader and writer, the database handle, and the conversion to and from VGC types.

VisualGeometryToolkitIO.UnitContract — Type
UnitContract(world, density = dpi; lengths = (;))
UnitContract(; world = mm, density = dpi, lengths = (;))
UnitContract(density, lengths::NamedTuple)

world, density and every role's unit are FlexUnits dynamic units (mm, pt, dpi, or parse_unit of a name).

Declares the units a file's magnitudes are expressed in: lengths, a table of LENGTH ROLES, each a named length unit; and density, a unit of pixels per length (dimension 1/length, since a pixel is dimensionless), for print and sensor densities. The role world is REQUIRED and is the default role: the unit of translations, 3D points and every other length. Further roles (pattern = pt) serve a record whose lengths are declared in more than one unit — a board's canvas in mm and its pattern in pt, each written decimal-exactly in its own unit. A field read or written in a role names it in its field tags (JSON.lift(style, Quantity, x, (; quantity = :length, role = :pattern))). Pixel counts need no declaration: pixels are the only image unit.

In memory the contract is that table, world first: UnitContract(mm, dpi; lengths = (pattern = pt,)).lengths == (world = mm, pattern = pt). The first two forms are conveniences that merge world into the table (the keyword form also reads a world already in lengths; naming it twice is an error); the third is the canonical one and refuses a table without world.

The FILE form is the envelope's units object ("length", "length_roles", "density", …; a VgioStyle carries the contract and writes it); a vgio_units.json sidecar for COLMAP model directories holds world and density only. The contract's own layout of IO before 0.10 ({"world", "density", "lengths"}) is retired (migrate_units). The roles are a CLOSED set, the ones the contract declares: an ArgumentError for a missing world, a role that is not a length, a role named density, a role name that is not snake_case, a density that is not pixels per length, and (on use) a role the contract does not declare.

source
VisualGeometryToolkitIO.UnknownScale — Type
UnknownScale()

The contract of a model whose world has NO unit: a structure-from-motion reconstruction without metric control (PhotoTourism, any plain COLMAP run) is fixed only up to a similarity, so its translations and 3D points are numbers in the reconstruction's own arbitrary scale. Declaring mm or m for them would be false, and nothing declares this either unless someone says so: the caller states it (load(ColmapModel, dir; contract = UnknownScale())), or the model's vgio_units.json sidecar does ("world": "unknown", written by save for such a model). It is never a default.

Under it the wire values stay what they are, plain numbers (ColmapImage.tvec, ColmapPoint3D.xyz), and anything that needs a length unit refuses: rigid_transform(image, contract) (a metric EuclideanMap) and colmap_image(pose, …; contract) (a metric pose written into the model) throw an ArgumentError. What does not depend on scale is read from the wire as usual: the rotation qvec, and translation directions.

source
VisualGeometryToolkitIO.role_unit — Function
role_unit(contract::UnitContract, role::Symbol = :world) -> Units

The unit contract declares for the lengths of role: contract.lengths[role]; an ArgumentError listing the declared roles for a role it does not declare. Every read of a contract's length unit goes through it (the unit of :world, the default, included).

source
VisualGeometryToolkitIO.ColmapCamera — Type
ColmapCamera

One row of COLMAP's cameras table: intrinsics in COLMAP's pixel convention (pixel centers at 0.5), params ordered per the model zoo. Unit-free wire type — magnitudes are px by COLMAP's definition, the only image unit (the contract declares the world unit alone).

source
VisualGeometryToolkitIO.ColmapImage — Type
ColmapImage

One row of COLMAP's images table: the world→camera pose as a wxyz quaternion qvec + translation tvec (world units per contract; plain numbers in the reconstruction's own scale under UnknownScale), plus observed 2D points (x, y, point3D_id) with point3D_id == -1 when untracked.

source
VisualGeometryToolkitIO.load — Method
load(ColmapModel, dir; contract = nothing) -> ColmapModel

Read a COLMAP model directory (binary preferred, text fallback). The unit contract comes from the vgio_units.json sidecar when present; for models produced by other tools supply contract explicitly — refusing to guess units is the point of the sidecar. A structure-from-motion model with no metric scale (PhotoTourism) is contract = UnknownScale(): its translations stay unitless, and metric assembly refuses (see UnknownScale). A caller contract that contradicts the sidecar is refused.

source
VisualGeometryToolkitIO.save — Method
save(dir, model::ColmapModel; format = :binary)

Write a COLMAP model directory (cameras/images/points3D in .bin or .txt) plus the vgio_units.json sidecar declaring the unit contract.

source
VisualGeometryToolkitIO.ColmapDatabase — Type
ColmapDatabase(path) -> ColmapDatabase

Open a lazy read handle on a COLMAP sqlite database. Close with close(db).

Accessors (unexported — qualify with the module): n_images, image_names, image_id, image_name, detections, descriptors, raw_matches, matched_pairs, verified_matches, pair_id, pair_image_ids.

source
VisualGeometryToolkitIO.detections — Method
detections(cdb, image_id) -> Matrix{Float32}   (n × cols)

The image's detections, COLMAP's keypoints table: row i is detection i-1 in COLMAP's 0-based match indexing. Columns are x, y[, scale, orientation | affine params] in pixels (COLMAP convention: the origin is the upper-left corner of the upper-left pixel, so the CENTER of the first pixel is (0.5, 0.5)).

source
VisualGeometryToolkitIO.matched_pairs — Method
matched_pairs(cdb, image_id) -> Vector{Int}

Ids of the images that share a NONEMPTY raw-match row with image_id (either stored order of the pair), ascending. The per-query fan-out primitive: partners are enumerated from the pair-id index, not by probing every image.

source
VisualGeometryToolkitIO.pair_id — Method
pair_id(image_id1, image_id2) -> Int64

COLMAP's pair key: ids are put in ascending order first, so the codec is order-insensitive (as in COLMAP's image_pair_to_pair_id).

source
VisualGeometryToolkitIO.raw_matches — Method
raw_matches(cdb, image_id1, image_id2) -> Matrix{UInt32}   (n × 2)

Raw (unverified) detection-index match pairs, 0-BASED, column 1 indexing image_id1's detections and column 2 image_id2's — in the CALLER's argument order regardless of how COLMAP stored the pair. No entry ⇒ 0×2.

source
VisualGeometryToolkitIO.verified_matches — Method
verified_matches(cdb, image_id1, image_id2) -> Matrix{UInt32}   (n × 2)

Geometrically verified match pairs, from two_view_geometries (current COLMAP) or inlier_matches (pre-3.x databases). Same conventions as raw_matches. Errors if the database has neither table.

source
VisualGeometryToolkitIO.camera_model — Method
camera_model([T = Float64,] c::ColmapCamera) -> CameraModel

Assemble a VGC camera from a COLMAP row. T = Float32 gives single-precision storage end-to-end (GPU pipelines); the wire stays Float64 regardless — precision is an in-memory concern, not a storage one.

source
VisualGeometryToolkitIO.colmap_camera — Method
colmap_camera(cm::CameraModel, camera_id, width, height) -> ColmapCamera

Serialize a VGC camera as the COLMAP model computing its lens's function (colmap_model). A lens no COLMAP model computes, and a K with nonzero skew, are refused rather than approximated.

source
VisualGeometryToolkitIO.colmap_image — Method
colmap_image(pose::EuclideanMap{3}, image_id, camera_id, name; contract = MM_PX) -> ColmapImage

COLMAP images hold world→camera poses; a detected object→camera pose is the same direction, with "world" = the object frame. The pose is metric — its translation lengths, written in the contract's world unit (write_length); a plain translation is refused — so an UnknownScale contract, which has no length unit to write it in, is refused.

source
VisualGeometryToolkitIO.colmap_model — Method
colmap_model(lens) -> Union{Symbol, Nothing}

The COLMAP camera model whose function the lens computes — the one colmap_camera writes — or nothing when no COLMAP model computes it (a double sphere, a lift with a numerator, a thin prism on a perspective view). Always a two-focal model; reading a single-focal one (SIMPLE_RADIAL) and writing it back gives the two-focal model of the same function (OPENCV).

source
VisualGeometryToolkitIO.rigid_transform — Method
rigid_transform(im::ColmapImage, contract) -> EuclideanMap{3}

Assemble the world→camera pose of a COLMAP image row under the model's unit contract: its translation lengths in metres, read in the contract's world unit (read_length). An EuclideanMap is metric, so under UnknownScale this refuses; the row's qvec and unitless tvec are the pose up to scale.

source