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.MM_PX — Constant
The stack-canonical contract: world in millimeters (image values are pixels).
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.
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.
VisualGeometryToolkitIO.role_unit — Function
role_unit(contract::UnitContract, role::Symbol = :world) -> UnitsThe 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).
VisualGeometryToolkitIO.ColmapCamera — Type
ColmapCameraOne 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).
VisualGeometryToolkitIO.ColmapImage — Type
ColmapImageOne 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.
VisualGeometryToolkitIO.ColmapModel — Type
ColmapModelA COLMAP model directory's contents plus the unit contract its magnitudes are expressed in: a UnitContract, or UnknownScale for a structure-from-motion model whose world has no unit.
VisualGeometryToolkitIO.ColmapPoint3D — Type
ColmapPoint3DOne row of COLMAP's points3D table. track holds (image_id, point2D_idx) pairs.
VisualGeometryToolkitIO.load — Method
load(ColmapModel, dir; contract = nothing) -> ColmapModelRead 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.
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.
VisualGeometryToolkitIO.ColmapDatabase — Type
ColmapDatabase(path) -> ColmapDatabaseOpen 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.
VisualGeometryToolkitIO.descriptors — Method
descriptors(cdb, image_id) -> Matrix{UInt8} (n × 128)Row i is the descriptor of detection i (same order as detections).
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)).
VisualGeometryToolkitIO.image_id — Method
image_id(db::ColmapDatabase, name) -> IntThe COLMAP image_id of the image called name. An ArgumentError when no image has that name.
VisualGeometryToolkitIO.image_name — Method
image_name(db::ColmapDatabase, image_id) -> StringThe name of the image with COLMAP id image_id. An ArgumentError when no image has that id.
VisualGeometryToolkitIO.image_names — Method
Image names ordered by image_id.
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.
VisualGeometryToolkitIO.n_images — Method
n_images(db::ColmapDatabase) -> IntThe number of rows in the database's images table.
VisualGeometryToolkitIO.pair_id — Method
pair_id(image_id1, image_id2) -> Int64COLMAP'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).
VisualGeometryToolkitIO.pair_image_ids — Method
pair_image_ids(pair_id) -> (image_id1, image_id2)Inverse of pair_id; image_id1 ≤ image_id2 by construction.
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.
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.
VisualGeometryToolkitIO.camera_model — Method
camera_model([T = Float64,] c::ColmapCamera) -> CameraModelAssemble 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.
VisualGeometryToolkitIO.colmap_camera — Method
colmap_camera(cm::CameraModel, camera_id, width, height) -> ColmapCameraSerialize 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.
VisualGeometryToolkitIO.colmap_image — Method
colmap_image(pose::EuclideanMap{3}, image_id, camera_id, name; contract = MM_PX) -> ColmapImageCOLMAP 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.
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).
VisualGeometryToolkitIO.colmap_params — Method
colmap_params(lens, fx, fy, cx, cy) -> Vector{Float64}The parameter vector of colmap_model(lens), in COLMAP's documented order for that model.
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.