Native Kinds

load, save and validate for the vgio/<kind> files, the decimal-exact length pair read_length and write_length, the serialization style every embedded VGC value — a quantity, a Size2, a feature frame — is written and read on (VgioStyle, JSON.lower/JSON.lift), the frame grammar, content identities, and the building blocks other packages reuse for kinds of their own.

VisualGeometryToolkitIO.VisualGeometryToolkitIO — Module
VisualGeometryToolkitIO

File formats for the VisualGeometryToolkit stack. Each vgio/<kind> JSON file is the serialization of one VisualGeometryToolkitCore type: load(T, path) returns a value of type T, and save(path, value) writes one. Both verbs are public but not exported, so call them qualified (import VisualGeometryToolkitIO as VgtkIO; VgtkIO.load(...)).

The package also reads and writes COLMAP models, reads COLMAP databases and OpenCV/MATLAB calibration exports, and exports to TUM, EuRoC, BOP and TRC.

source
VisualGeometryToolkitIO.CONTRACT_GENERICS — Constant
CONTRACT_GENERICS

VisualGeometryToolkitIO's declared extension points: the functions another stack package may add methods to (VisualGeometryToolkitCore's contract_generic_violations checks it). migrate_schema: the owner of a schema adds the step of each of its old versions, so its reader reads them (migrate_record), and the file form, so vgio_migrate rewrites its files. load and save, the two verbs: a package whose own kinds are files (BlobBoards' boards and patterns) adds load(::Type{<:ItsType}, path) and save(path, x::ItsType) methods, so a reader reaches every kind of the stack through the same two verbs.

source
VisualGeometryToolkitIO.read_length — Method
read_length(x::Real, u::Units) -> Quantity

The file number x, written in the length unit u, as a base-form quantity in metres. For a power-of-ten unit (mm, cm, μm, m, km) the conversion shifts the decimal exponent of x, so read_length(62.8, mm) is the metre value nearest the decimal 0.0628 and write_length returns 62.8 exactly; other units (inch, ft, pt) multiply by the unit's scale. Any Float64 crosses — negative, ±0 with its sign, NaN, ±Inf; an integer is read as its Float64. An ArgumentError for a unit that is not a length.

This is the stack's one hand-rolled unit conversion: FlexUnits' own x * u of a float x multiplies by the Float64 of the unit's exact rational scale, one ulp off the decimal for about one number in seven. It is removed — read_length(x, u) becoming base_quantity(x * u) — when FlexUnits applies a rational scale to a float as x * num / den, rounded once (Deduction42/FlexUnits.jl#131).

source
VisualGeometryToolkitIO.write_length — Method
write_length(q::Quantity, u::Units) -> Float64

The number a file holds for the length q in the unit u, the inverse of read_length: write_length(read_length(x, u), u) prints as x for every x of at most 15 significant digits, and read_length of the result is q itself whenever any file number reads back to it. When none does (a full-precision metre value computed in code, about one in eight in millimetres), the number written reads back as q's PERSISTED value, its metre value at 15 significant digits (the value content_id hashes): either way the length, the file written from it and the length loaded back have one identity, and a rewrite is byte for byte (IO 0.10.1; 0.10.0 wrote the nearest number, an ulp off, whose identity could differ). A power-of-ten unit (mm, cm, μm, m, km) shifts the decimal exponent of the metre value, and its last resort is the decimal of the persisted value. Any other unit (inch, ft, pt) takes the fewest significant digits (1 to 17) that read_length maps back to the identical q, else a neighbouring number that does; its last resort is the number that reads back to q's persisted value exactly when one does, else the fewest digits whose value read back has q's identity, and when no number of the unit has it (a unit in which the length's numbers are subnormal; no length unit) an ArgumentError naming the length and the unit (IO 0.10.3; 0.10.2 returned the nearest number). The rule is VisualGeometryToolkitCore's conventions/units.md ("What is exact"). NaN and ±Inf are written as they are. An ArgumentError for a unit that is not a length, or a quantity that is not one.

The search is not a conversion and stays: FlexUnits' ustrip(u, q), even correctly rounded, gives back the file's own number for only about three quarters of decimal file numbers, since the stored metre value is on a different grid; write_length returns the number that reads back to q.

source
StructUtils.lower — Function
JSON.lower(s::VgioStyle, f::FeatureFrame[, tags])
JSON.lower(s::VgioStyle, u::Uncertain{<:FeatureFrame})
JSON.lift(s::VgioStyle, F::Type{<:FeatureFrame}, x[, tags])
JSON.lift(s::VgioStyle, Uncertain{F}, x)

THE frame codec, one over VisualGeometryToolkitCore's FeatureFrame interface: a frame is {"center": [x, y]} and its shape — a PointFrame nothing, a Disc"sigma", an OrientedDisc"sigma" and "angle" (radians), an EllipticFrame"shape_matrix" and an AffineFrame"affine_matrix", each in rows. Its numbers are plain (pixel coordinates in the file's pixel frame) or quantities under the field's tags ((; quantity = :length[, role])). The lift builds F's element type (PointFrame{Float32} reads Float32; a type without one plain Float64).

An uncertain frame adds its "covariance": the frame's frame_dof × frame_dof covariance over its parameters, the centre (x, y) first, in the storage it holds (rows, {"diagonal": […]}, {"isotropic": λ}); a PointFrame's is the uncertain point's 2×2. Its entries are the frame's own numbers' (px², never converted): an uncertain frame holds plain numbers. A covariance of another size, a non-finite one (a detection states why it has none: vgio/detection's covariance_status) and a labeled one are an ArgumentError. A precision form is written as its covariance and reads back as one.

julia> import JSON

julia> s = VgtkIO.VgioStyle();

julia> JSON.json(OrientedDisc(1.0, 2.0, 3.0, 0.5); style = s)
"{\"center\":[1.0,2.0],\"sigma\":3.0,\"angle\":0.5}"

julia> u = Uncertain(PointFrame(10.5, 20.25), CovMat{2, Float64}(0.5, 0.0, 0.0, 0.25));

julia> JSON.json(u; style = s)
"{\"center\":[10.5,20.25],\"covariance\":[[0.5,0.0],[0.0,0.25]]}"

julia> JSON.lift(s, Uncertain{PointFrame{Float64}}, JSON.parse(JSON.json(u; style = s))) == u
true
source
StructUtils.lower — Method
JSON.lower(s::VgioStyle, r::Union{PolygonRegion, RegionIntersection, WholePlane})
JSON.lower(s::VgioStyle, r, (; region = true))
JSON.lift(s::VgioStyle, T, x)

THE region body: a 2-D region of VisualGeometryToolkitCore's — a Rect2, an Ellipse, a Circle, a PolygonRegion (the valid domain of a lens that is not radially symmetric), their RegionIntersection (nested to any depth) or the WholePlane — as one tagged object,

{"rect": [x, y, w, h]} | {"ellipse": [cx, cy, a, b, θ]} | {"circle": [cx, cy, r]}
  | {"polygon": {"centre": [cx, cy], "vertices": [[x, y], …]}}
  | {"intersection": [<region>, <region>]} | {"whole_plane": {}}

its leaves the positional records a Rect2, Ellipse and Circle are written as everywhere (extents positive, an ellipse's major semi-axis first, θ in radians), an intersection Core's binary one with its two parts in order (nest one for more), a polygon its star centre and its vertex ring (at least 3 vertices, star-shaped about the centre: Core's constructor checks it on read). The numbers are PIXELS in the file's units.pixel frame: the writer moves the region from Core's canonical frame into the style's pixel frame and the reader back, by Core's action of the pixel-frame map on every region. A camera's lens_coverage is this body restricted to its leaves.

A polygon, an intersection or the whole plane is lowered by the two-argument form; a leaf lowers to its positional record there, so a field that holds any region asks for the region body by the tag (; region = true) (which an intersection and the whole plane take too). The lift reads the body from an object (a leaf's positional record is an array) into T, a region type or a Union of them (Union{Rect2, RegionIntersection}, …); a region of another type is an ArgumentError. A parsed record is checked first (an unknown tag, an intersection of other than two regions, a degenerate leaf: an ArgumentError naming its place), and an intersection is read as stored, through RegionIntersection's constructor (never ∩, which folds two rectangles into one), so the value reads back with its type.

s = VgtkIO.VgioStyle()
r = RegionIntersection(Rect2(0.0, 0.0, 1920.0, 1200.0), Ellipse(Point2(960.0, 600.0), 700.0, 650.0, 0.0))
JSON.json((initial_region = r,); style = s)
# {"initial_region":{"intersection":[{"rect":[0.0,0.0,1920.0,1200.0]},{"ellipse":[960.0,600.0,700.0,650.0,0.0]}]}}
JSON.lift(s, typeof(r), JSON.parse(JSON.json(r; style = s))) == r     # true
source
VisualGeometryToolkitIO.migrate_units — Method
migrate_units(declaration) -> Dict{String, Any}

The IO 0.10 units object (the envelope's: length, time, angle, pixel, density, radiance, length_roles) of a record that declared its units in the retired UnitContract layout, {"world": "mm", "density": "dpi", "lengths": {"pattern": "pt"}} (a BlobBoards board before IO 0.10): world is length, the further roles length_roles, a missing density dpi (the layout's own rule), and what the layout never declared is what its records meant — colmap pixels, seconds, radians, a relative radiance. For an owner's version step (migrate_schema); a 0.10 record states no units of its own (write_record writes the style's). An ArgumentError for a unit name that is not registered or of the wrong dimension, and for world named again under lengths.

source
VisualGeometryToolkitIO.snap_integer — Method
snap_integer(v) -> Real

A file number as a record writes it: an integral value as an Int (640, 300: a pixel count or a density), anything else as it is — a float that is not integral or lies past Float64's exact integers, an integer past Int's range, a Bool (a flag is not a number: true stays true), a Rational that is not integral as its Float64. A length is the Float64 write_length returns and is not snapped.

source
VisualGeometryToolkitIO.Record — Type
Record

What a lift reads (JSON.lift(::VgioStyle, T, record)): a record whose fields are read by property access — a parsed JSON object (JSON.jl's Object, String keys as every reader hands it, or Symbol keys) or a NamedTuple (a record built in memory, camera_from_json(camera_json(…))). A Dict has no property access. Another package's lifts of its own kinds (BlobBoards') take it too.

source
VisualGeometryToolkitIO.VgioStyle — Type
VgioStyle(; length_unit = mm, pixel_frame = PixelFrame{:colmap}, density = dpi, length_roles = (;)) <: JSON.JSONStyle
VgioStyle(contract::UnitContract; pixel_frame = PixelFrame{:colmap})
VgioStyle(record) -> VgioStyle

VisualGeometryToolkitIO's serialization style: every VGC value a vgio/<kind> record embeds is written by a JSON.lower(::VgioStyle, x) method and read by a JSON.lift(::VgioStyle, T, record) method (StructUtils' lower and lift, the JSON.JSONStyle hooks), on this style only. It carries the file's units declaration: a UnitContract (its length unit, every lengths in decimal-exact through write_length and read_length, its further length roles and its density) and the pixel_frame its pixel coordinates are written in. The writer takes it as JSON.json(x; style = VgioStyle(…)); every file's units object is the style's (length the contract's world unit, length_roles its further roles, density, and pixel the pixel frame), which write_record writes into the envelope.

VgioStyle(record) is the style a parsed record's units object declares (the reader's: a record a package of its own reads with read_record), the record read by property access (a JSON.Object or a NamedTuple).

A package serializing a kind of its own embeds VGC values the same way (a pose, a CameraModel, a target with its calibration, a layout, an Ellipse); a lift reads a parsed JSON.Object or a NamedTuple:

julia> import JSON

julia> s = VgtkIO.VgioStyle(; length_unit = mm);

julia> e = Ellipse(Point2(1.0, 2.0), 3.0, 1.0, 0.5);

julia> JSON.json((domain = e,); style = s)
"{\"domain\":[1.0,2.0,3.0,1.0,0.5]}"

julia> JSON.lift(s, Ellipse, JSON.parse(JSON.json(e; style = s))) == e
true
source
VisualGeometryToolkitIO.lattice_from_json — Method
lattice_from_json(record, ::Val{K}; name, length_unit = nothing) -> (; spline::ChartSpline{K}, present)

The lattice a lattice record states (the inverse of lattice_json): spline the ChartSpline of its K-vector controls name over its area, NaN in the nodes the record does not hold (no evaluation reads one), and present its presence mask ([gy, gx]), or nothing when the record holds every node. With length_unit the controls are lengths in that unit, read as plain metres, decimal-exactly. record is a Record or a parsed AbstractDict; it is validated first — exactly its keys, a finite area of positive widths, at least 4 × 4 nodes, the runs inside the lattice and apart, one K-vector control per held node — each problem an ArgumentError naming it (what, the record's name in the message).

source
VisualGeometryToolkitIO.lattice_json — Method
lattice_json(spline::ChartSpline; name, present = nothing, length_unit = nothing) -> NamedTuple

A uniform cubic B-spline lattice — VisualGeometryToolkitCore's ChartSpline, its K-vector controls over a rectangle of a chart — as THE lattice record, the one every spline is stored in (a SplineLens's backward and forward splines, a non-central model's, RadiometricCamera's aperture spline):

{"area": [x, y, w, h], "grid_size": {"width": gw, "height": gh},
 "present": [[row, [[col_lo, col_hi], …]], …],     (optional) the held nodes; absent = every node
 "controls": {"<name>": [[c₁, …, c_K], …]}}        the held nodes' controls, row by row

area is the spline's rectangle, grid_size its lattice (columns, rows). present (a Bool matrix of the lattice's size, [gy, gx], Core's presence mask; nothing: every node) is written as runs per lattice row, 1-based (the file's index_base) and inclusive, and only the held nodes' controls are written, under name (:direction, :point, :radius, …). The controls are written as they are (JSON's shortest round-trip floats, so a Float64 spline reads back bit for bit), or, with length_unit, as lengths: plain metres in memory, the file's numbers in that unit through write_length's decimal shift. lattice_from_json reads it back.

julia> rec = (area = [0.0, 0.0, 1.0, 1.0], grid_size = (width = 4, height = 4), controls = (radius = fill([2.0], 16),));   # radii, in mm

julia> L = VgtkIO.lattice_from_json(rec, Val(1); name = :radius, length_unit = mm); L.spline.controls[1, 1][1]   # metres
0.002

julia> VgtkIO.lattice_json(L.spline; name = :radius, length_unit = mm) == rec
true
source
VisualGeometryToolkitIO.pixel_frame — Method
pixel_frame(style::VgioStyle) -> Type{<:PixelFrame}

The pixel frame style declares (a file's units.pixel): the frame every pixel coordinate of a record written or read on it is in. A lower or lift method of a value that holds pixel positions in a frame of its own (VGC's values hold COLMAP pixels) moves them by pixel_frame_offset.

source
VisualGeometryToolkitIO.pixel_frame_offset — Method
pixel_frame_offset(F, G) -> SVector{2, Float64}

The offset of a position written in the pixel frame G for one held in the pixel frame F (pixel frames differ by a translation): x_G = x_F + offset. pixel_frame_offset(PixelFrame{:colmap}, PixelFrame{:opencv}) is [-0.5, -0.5].

julia> VgtkIO.pixel_frame_offset(PixelFrame{:colmap}, PixelFrame{:julia}) == [0.5, 0.5]
true
source
VisualGeometryToolkitIO.MATRIX_LAYOUT — Constant
MATRIX_LAYOUT

How a vgio record lays out a matrix: "rows", a list of its rows (the matrix_layout every file's conventions declare). Another package's record that holds matrices (CaliBlobs' session record) declares the same.

source
VisualGeometryToolkitIO.fit_record_json — Method
fit_record_json(r::FitResult) -> NamedTuple

The termination record of a fit, the one every kind that stores a fit's outcome embeds: (; retcode, stop_rule, iterations, rms, n) — VisualGeometryToolkitCore's ReturnCode and StopRule by name, the loop count, the RMS of the residuals (in their own unit) and their number. The estimate and the metadata of r are not part of it (they are the embedding kind's own fields). Its table is body_spec(FitResult); fit_record_from_json reads it back.

source
VisualGeometryToolkitIO.read_record — Method
read_record(path; allownan = false) -> JSON.Object
read_record(io::IO; allownan = false) -> JSON.Object

The record a JSON file (or the JSON text io holds) is, as its kind's CURRENT record: parsed (a JSON.Object, read by property access — the form JSON.lift(::VgioStyle, T, record) takes) and, when its schema is an earlier version that a schema owner's version steps read (migrate_schema), run through them by migrate_record in memory; the file is not rewritten. A step's refusal (an ArgumentError, or a key its version always held missing) is an ArgumentError naming the file and its schema. A NaN or ±Infinity is refused naming its field; allownan = true reads one (and then reads every number as a Float64, JSON.jl's rule), for a file write_record wrote with allownan = true.

source
VisualGeometryToolkitIO.validate — Method
validate(path) -> String

Check a vgio file — or a COLMAP model directory's vgio_units.json, when path is the directory — against its kind's table (the envelope's schema, generator, units and conventions, then the body), the check every reader runs before using a field and every writer runs before writing, and return the kind ("cameras", "rig", …). An ArgumentError names the file, the offending key and the problem. A file of an earlier version is checked as the current record its version steps give (as load reads it); a version no step reads is refused by name, a retired kind with its successor. Semantic checks that need more than the one file — that observations resolve in their targets — are the exporters'.

A kind that moved to its owner (vignetting, environment_light and radial_profile: VisualRadiometryToolkitIO's; panorama: PanoramaStitching's) has no table here. Its file is checked by its owner's validate_record method when that package is loaded, and is otherwise an ArgumentError naming the kind and its owner.

source
VisualGeometryToolkitIO.with_caller — Method
with_caller(f, caller::Module)

Run f() with caller named as the calling package in the generator of every vgio file written inside it: "generator": {"name": "VisualGeometryToolkitIO", "version": …, "caller": {"name": "<caller>", "version": "<its pkgversion>"}}. A package that writes vgio files (or its own kinds through write_record) wraps its writers in it, so a file records the software that wrote it.

source
VisualGeometryToolkitIO.with_provenance — Method
with_provenance(body::NamedTuple, provenance::NamedTuple) -> NamedTuple

A record's body with the writer's free-form provenance (the provenance keyword of every save), as the writers store it: body itself when provenance is empty, else body with the field provenance appended (the last key). Provenance is about the file, never part of the value, and no reader reads it back. A package writing a kind of its own through write_record stores its provenance the same way.

source
VisualGeometryToolkitIO.write_record — Method
write_record(path, record; style = VgioStyle(), allownan = false)

Write record — a NamedTuple or AbstractDict, the record of a kind a package owns, its VisualGeometryToolkitCore values left for style to lower — as a JSON file in the shape every vgio file has (pretty-printed, a four-space indent, no trailing newline), with the envelope every vgio file has: its schema first ("<owner>/<kind>/v<major>.<minor>", the record's own), then the generator (VisualGeometryToolkitIO and the calling package, with_caller), the units object style declares (its length unit and roles, density and pixel frame) and the fixed conventions, then the record's other keys in their order. The record states none of the envelope keys itself (an ArgumentError). Every VGC value in it is written by its JSON.lower(::VgioStyle, x) method on style. The text is parsed back before it is written, and a NaN or ±Infinity is refused naming its field, as a vgio file's is; allownan = true writes one as JSON.jl's NaN / Infinity instead (a run report's statistic over nothing), for read_record(path; allownan = true).

A kind's owner writes its records with this and reads them with read_record (VgioStyle(record) is the style its units declare); this function checks no kind's fields.

source
VisualGeometryToolkitIO.frame_from_name — Method
frame_from_name(s::AbstractString) -> Type{<:Frame}

Parse a serialized frame name back to the VGC frame type; the id becomes a Symbol (a board uid that happens to look numeric is still an identity, not a number). An unknown name is an ArgumentError listing the grammar.

julia> frame_from_name("target:b89")
TargetFrame{:b89}
source
VisualGeometryToolkitIO.frame_name — Method
frame_name(F::Type{<:Frame}) -> String

The serialized name of a VGC 3D frame type: "world", "camera" (VGC's CameraFrame, a single camera's optical frame), "view:<id>", "target:<id>", "body:<id>" (VGC's BodyFrame{id}, a rigid body tracked or mounted as a unit — a board rig, a camera rig). Inverse of frame_from_name.

source
VisualGeometryToolkitIO.load_units_sidecar — Method
load_units_sidecar(dir) -> Union{UnitContract, UnknownScale, Nothing}

Read the vgio_units.json sidecar of a COLMAP model directory; nothing if absent (a model produced by other tools — the caller must then declare units explicitly). "length": "unknown" is an UnknownScale model. A v2 sidecar (world, an optional density: dpi when absent, as v2 read it) is read through its version step; a v1 one is refused by name.

source
VisualGeometryToolkitIO.load — Method
load(Vector{EuclideanMap}, path) -> Vector{Union{EuclideanMap{3}, Uncertain{<:EuclideanMap{3}}}}

Read a vgio/transforms/v5.0 file: each record a pose labeled with its from/to frames (frame_from_name), its translation lengths in metres (read in the file's units.length), Uncertain iff the file states a covariance. Type-unstable by nature (the labels come from the file). An earlier version reads through its version steps. A v2 file names its frames by free strings and is refused, but for the 2026-09 hand-eye record (camera_rig → camera_optical, then printed_board_<id> or scene_<c> → board_rig), read as the frames the current writer names (body:camera_rig, camera, target:<id>, target:scene_<c>, body:board_rig); a v1 file is refused.

source
VisualGeometryToolkitIO.pose_from_json — Method
pose_from_json(p, unit::AbstractString) -> EuclideanMap{3} | Uncertain

pose_json's inverse: an embedded {rotation, translation[, covariance]} read in the file's length unit (a unit name), returned UNLABELED, its translation lengths in metres (read_length) — Uncertain iff a covariance is stated, its translation block in m² and its cross block in m·rad. The rotation is the stored quaternion itself, a QuatRotation (not renormalized, not converted to a matrix), so the value writes back to the same numbers. The quaternion must be unit-norm to 1e-6 and have w ≥ 0, the declared encoding (refused otherwise, never normalized or flipped silently).

source
VisualGeometryToolkitIO.pose_json — Function
pose_json(X, unit = mm) -> NamedTuple

A physical pose — a VGC EuclideanMap{3} whose translation is lengths, or an Uncertain one, any labels — as the embedded {rotation, translation[, covariance]} of every pose-carrying kind: the rotation a w-x-y-z quaternion with w ≥ 0 (a QuatRotation's own, exactly; any other rotation converted, reading back as a QuatRotation), the translation in the length unit (write_length), the 6×6 covariance (over [δω; δt], rad and unit) iff Uncertain. Its frames are not written: they are given by where it sits, and its conventions (the quaternion's, the transform's, the unit) are the enclosing file's envelope (write_record writes it from the style). A plain translation is an ArgumentError (attach its unit, EuclideanMap(rotation(X), t .* m)). The inverse is pose_from_json.

source
VisualGeometryToolkitIO.save — Method
save(path, poses::AbstractVector; length_unit = mm, provenance = (;))

Write labeled physical rigid poses — EuclideanMap{…, S, D} or Uncertain ones, their translations lengths — as a vgio/transforms/v5.0 file: each record's from/to are its labels' frame names (frame_name), its translation in length_unit (declared in units), a covariance iff Uncertain. An unlabeled or half-labeled pose is refused (relabel it with the frames it maps between), and so is a plain translation (attach its unit, t .* m). provenance is the file's free-form object.

source
VisualGeometryToolkitIO.camera_from_json — Method
camera_from_json(body, frame; length_unit = mm) -> (model, extent)

Read a camera body (the inverse of camera_json of a model) whose principal point is in the pixel frame the enclosing file declares: a CameraModel, or a NoncentralSplineModel (a body with a type, its line points in length_unit), in VGC's canonical pixel frame, and its extent.

A body of an earlier shape, as another package's record of an earlier version embeds it, reads as the camera it migrates to: an IO 0.9 body (width, height, 0-based lattice runs) through the body's 0.10 step, and an old grid body (the body of a vgio/generic_camera/v2/v3 record — RadiometricCamera's rc/calibration_state/v1 camera) through the same conversion as an old grid file: a central one as a CameraModel with a SplineLens, a non-central one as a NoncentralSplineModel (its line points in length_unit). An old grid body is read in the colmap pixel frame (CANONICAL_PIXEL_FRAME), whatever frame is given: the old grid code reads every old grid body's numbers in that frame.

source
VisualGeometryToolkitIO.camera_from_json — Method
camera_from_json(::Type{BoundedCamera}, body, frame; length_unit = mm) -> BoundedCamera

Read a bounded camera's body (the inverse of camera_json of a BoundedCamera), a parsed JSON object: checked against the body's table first (an ArgumentError naming the field otherwise), then its model, its bound (a pitch, in length_unit: the physical Sensor; none: the pixel extent) and its lens coverage (none: the whole sensor), in VGC's canonical pixel frame. A body of an earlier shape reads as camera_from_json(body, frame) says.

source
VisualGeometryToolkitIO.camera_json — Function
camera_json(model::CameraModel, extent, frame = CANONICAL_PIXEL_FRAME) -> NamedTuple
camera_from_json(body, frame; length_unit = mm) -> (model, extent)

The camera body every camera-carrying kind embeds — image_size ({width, height}), K (fx, fy, cx, cy, skew) and the lens record — written with its principal point in the pixel frame the enclosing file declares, and read back into VGC's canonical frame. Building blocks for a package serializing its own kind; a bounded camera's body (its pitch and lens coverage too) is camera_json(camera::BoundedCamera, frame).

source
VisualGeometryToolkitIO.camera_json — Function
camera_json(model::NoncentralSplineModel, extent, frame = CANONICAL_PIXEL_FRAME; length_unit = mm) -> NamedTuple

A non-central grid camera's body, a camera store's and a rig sensor's: type = "noncentral_spline", image_size, the gauge K in the pixel frame and the spline lattice record (the held nodes, the direction and point controls, the line points — plain metres in memory — in length_unit). camera_from_json reads it back (it tells the two bodies apart by type).

source
VisualGeometryToolkitIO.camera_json — Function
camera_json(camera::BoundedCamera, frame = CANONICAL_PIXEL_FRAME; length_unit = mm) -> NamedTuple

A bounded camera's body — the one a camera store's entry and a rig sensor embed: its model's body (a CameraModel's of any lens, or a NoncentralSplineModel's), the sensor's pitch in length_unit when it is bounded by a physical Sensor, and its lens_coverage in the pixel frame when the lens does not cover the whole sensor. camera_from_json(BoundedCamera, body, frame; length_unit) reads it back.

source
VisualGeometryToolkitIO.colmap_cameras — Method
colmap_cameras(cameras::AbstractDict{Symbol}) -> (cameras::Vector{ColmapCamera}, ids::Dict{Symbol, Int})

Project a camera store onto COLMAP camera rows, for feeding a ColmapModel. Ids are assigned 1..n in name order.

TWO LOSSES, both deliberate and both surfaced rather than papered over:

  1. Names do not survive. COLMAP has no camera name field, so the identity a config refers to is gone on the far side. The returned ids map is the remainder — persist it beside the model if anything downstream needs to get back to a name.
  2. Inexpressible cameras throw. A lens no COLMAP model computes has no colmap_model, and that ArgumentError is the correct outcome — a silently dropped or approximated lens model is worse than a failed export. Filter first if a partial export is what you want: filter(p -> colmap_model(lens(last(p))) !== nothing, cameras).
source
VisualGeometryToolkitIO.load — Method
load(Dict{Symbol, BoundedCamera}, path; intrinsics = nothing) -> Dict{Symbol, Union{BoundedCamera, Attributed{<:BoundedCamera}}}

Read a vgio/cameras/v6.0 store: name → BoundedCamera (its K moved from the file's declared pixel frame into the canonical one), an Attributed one where the file states the camera's calibration_record. An earlier store is read through its version steps (migrate_record); a vgio/noncentral_spline/v1 record, and an old grid file (vgio/generic_camera/v2 or v3, central or not), as the store of its one camera, named after the file's basename (fisheye_14mm.json → :fisheye_14mm).

intrinsics (a CameraCalibrationMat, in the canonical pixel frame) supplies K to an old grid file that stores no nominal pinhole — one whose lattice has no complete 4 × 4 window at the gauge's pixel is refused without it — read as if the file held it (the file is never edited); a record that holds a K refuses it.

source
VisualGeometryToolkitIO.load — Method
load(BoundedCamera, path; name = nothing, file_unit = nothing, intrinsics = nothing) -> BoundedCamera
load(CameraModel,  path; name = nothing) -> CameraModel

Read ONE camera from a vgio/cameras/v6.0 store — the bounded camera, or just its model (its calibration_record, if any, is the store's to read). Without name the store must hold exactly one camera: a multi-camera store is REFUSED with the available names rather than defaulting to the first — which camera a run uses is an identity, and silently guessing it is how a config ends up calibrated for the wrong lens while reporting success.

The grid cameras of Schöps et al. read through the same call, by the file's content: an old grid file (vgio/generic_camera/v2 or v3) or a vgio/noncentral_spline/v1 record as its one camera — a central one with a SplineLens (its nominal pinhole the K, else the lattice's gauge; its domain the lens coverage), a non-central one a BoundedCamera{<:NoncentralSplineModel} — and the reference implementation's intrinsics0.yaml as either (schoeps.jl; a non-central YAML's point_grid unit is the caller's file_unit). Old files are read, never rewritten.

load(CameraModel, path) refuses a camera whose lens coverage is not its whole sensor (an image circle, an old grid file's domain) rather than drop it: load the BoundedCamera.

source
VisualGeometryToolkitIO.pixel_frame_from_name — Method
pixel_frame_from_name(name) -> Type{<:PixelFrame}

The pixel frame a file names ("colmap", "opencv", "julia"), the inverse of pixel_frame_name. VGC decides which pixel frames exist: the name is checked by constructing the conversion to the canonical pixel frame (colmap), and a name VGC does not know is an ArgumentError that quotes VGC's list of registered frames.

julia> VgtkIO.pixel_frame_from_name("julia")
PixelFrame{:julia}
source
VisualGeometryToolkitIO.pixel_frame_name — Method
pixel_frame_name(::Type{<:PixelFrame}) -> String

The serialized spelling of a pixel frame (PixelFrame{:colmap} → "colmap"); pixel_frame_from_name is its inverse. Parallel to frame_name/frame_from_name for 3D frames, deliberately separate because the grammars differ: a 3D frame serializes prefixed ("view:cam1"), a pixel frame bare ("colmap").

julia> VgtkIO.pixel_frame_name(PixelFrame{:opencv})
"opencv"
source
VisualGeometryToolkitIO.save — Method
save(path, cameras::AbstractDict{Symbol}; length_unit = mm, provenance = (;))

Write a camera store — name → BoundedCamera (of a CameraModel, any lens, or of a NoncentralSplineModel), or an Attributed one carrying its calibration_record — as a vgio/cameras/v6.0 file, cameras sorted by name. A camera bounded by its physical Sensor carries the sensor's pitch, and a non-central camera its line points, in length_unit (the file's units.length). provenance is the file's one free-form object, which VGIo never reads back.

JSON only, deliberately: cameras are configuration-adjacent (referenced by name from a TOML, hand-inspected, diffed on recalibration), the payload is kilobytes at rig scale, and Julia prints Float64 in its shortest round-trippable form so nothing is lost.

source
VisualGeometryToolkitIO.save — Method
save(path, camera::BoundedCamera; name, length_unit = mm, provenance = (;))

Write one bounded camera as a camera store of that camera under name (save(path, Dict(name => camera))).

source
VisualGeometryToolkitIO.content_id — Method
content_id(targets) -> String

The identity an observations file (vgio/observations, target_homographies) names a target definition by — targets a Rig, a single unposed AbstractTarget (Attributed ones by their target), or a vgio/rig or vgio/target path (any version that reads): the SHA-256 (lowercase hex) of the RFC 8785 (JCS) serialization (VisualGeometryToolkitCore's canonical_json) of its IDENTITY TREE.

The identity tree is specified once, in the docs ("Content identity"), and is the writer's own record of the value with no envelope: a rig's is {"frame", "sensors"?, "targets"?} — its body as vgio/rig holds it, under the current names (the targets sorted by id, each {"id", "target", "pose"}, each sensor {"id", "camera", "extrinsics"}) — and a single target's its target body alone (so it differs from every rig's, which has frame). Every number is in BASE UNITS: a length in metres, a covariance entry in m^k, a pixel in the canonical (colmap) pixel frame, an angle in radians. Each length is normalised to the Float64 nearest to its value rounded to 15 significant decimal digits in metres (_persisted): every decimal file number of at most 15 digits, in any decimal unit, reads back as exactly such a value, so a rig, the file written from it in any decimal units.length, the rig loaded back from that file, and a value built in code from the same decimals (14.2mm, an ulp off) have one identity. No schema version, envelope or provenance is hashed: the identity does not change when the file format does, except by a deliberate re-id (IO 0.10's, from the 0.9 tree; vgio_migrate_tree repoints a tree's observation files and keeps the id map). A planar target built from a layout enters by its nominal points, as a target given by its points does (the layout is not hashed). A pose's rotation enters as the quaternion the writer stores (w-x-y-z, w ≥ 0; a QuatRotation as held, any other rotation converted once): mint an identity from what you save. A PosedTarget is an ArgumentError.

source
VisualGeometryToolkitIO.load — Method
load(AbstractTarget, path; resolve = nothing) -> AbstractTarget | Attributed{<:AbstractTarget}

Read a vgio/target/v6.0 file: the target, Attributed with its calibration_record where the file states one. resolve(reference) supplies a referenced design's nominal points (else the target is returned unresolved). An earlier version (target v1–v5) is read through its version steps (migrate_record). A Schöps pattern YAML or a Kalibr aprilgrid YAML is read as its layout's PlanarTarget (see load(PlanarTarget, path)); the form is decided by the file's content.

source
VisualGeometryToolkitIO.load — Method
load(Rig, path; resolve = nothing, intrinsics = nothing) -> Rig

Read a vgio/rig/v10.0 file back into a fully labeled VGC Rig of the storage it holds, its lengths in metres: sensors (each a BoundedCamera labeled frame → ViewFrame{id}), targets (each a PosedTarget, minted TargetFrame{id} → frame on access), or both. resolve(design) supplies a referenced planar design's nominal points (see target_from_json). Type-unstable by nature (frame types are minted from file data) — load once, dispatch after. An earlier version (rig v4–v9) is read through its version steps (migrate_record): a v8 sensor's old grid body as its spline camera. intrinsics (sensor id → CameraCalibrationMat, in the canonical pixel frame) supplies K to an old grid sensor that stores no nominal pinhole — one whose lattice has no complete 4 × 4 window at the gauge's pixel is refused without it — read as if the file held it (the file is never edited); a sensor that holds its K, or an unknown id, refuses it.

source
VisualGeometryToolkitIO.metres — Method
metres(x::Real, u::Units) -> Float64

The file number x, a length in the unit u, as plain metres: read_length(x, u) stripped (decimal-exact for a power-of-ten unit), what a record's reader hands a kind built on plain numbers (a thin-plate kind's nodes and values, a non-central aperture's radii). A number of a placed target's chart (no unit) is returned as it is.

source
VisualGeometryToolkitIO.save — Method
save(path, target::AbstractTarget; length_unit = mm, provenance = (;))
save(path, Attributed(target, (; calibration_record)); length_unit = mm, provenance = (;))

Write one physical target as a vgio/target/v6.0 file — its body (rigschema.jl: its points — a planar target's by its reference, its layout when it records one (layout(t)), or its nominal points — and a planar target's calibration with its parameters and, when Uncertain, their covariance) in `lengthunitand, for anAttributedone, itscalibrationrecord: who calibrated it, when, from what (the keys of a camera'scalibrationrecord). Plain points are anArgumentError, and so is aPosedTarget: the file holds an unposed target, so save itsmodel, or the posed one inside aRig`.

The calibration record is not the target's calibration: calibration(t) is the TargetCalibration, x.calibration_record the record of how it was obtained.

source
VisualGeometryToolkitIO.save — Method
save(path, rig::Rig; length_unit = mm, provenance = (;))

Write a physical VGC Rig — sensors, targets, or both — as a vgio/rig/v10.0 file in length_unit: each sensor (a BoundedCamera of a CameraModel — a SplineLens one included — or of a NoncentralSplineModel, with its lens coverage) with its extrinsics frame → view:<id>, each target (sorted by id) with its body and its pose target:<id> → frame (a covariance iff Uncertain). A rig of plain translations or points is an ArgumentError (attach the unit, t .* m). A rig's name, if it has one worth keeping, belongs in provenance.

source
VisualGeometryToolkitIO.target_calibration_from_json — Method
target_calibration_from_json(s::VgioStyle, record) -> TargetCalibration | Uncertain

The calibration a target-calibration record states (the inverse of target_calibration_json), its lengths read in the style's length_unit as lengths in metres, decimal-exactly: the kind its tag names in Core's TARGET_CALIBRATION_TAGS (a composition right-associated, Core's one association), Uncertain iff the record states a covariance. record is a Record (a parsed JSON.Object or a NamedTuple); it is validated first, as a calibration in a vgio file is — an unknown kind, a retired one (affine, calibration_chain) by name, a parameter count that is not the kind's, a composition out of Core's order, a thin-plate kind that is not pure bending — each an ArgumentError naming the problem. On a style that declares the length roles node and height, a height field is read in them (its per-field units, target_calibration_json): over "chart" nodes a plain HeightField (the chart's numbers, its heights plain metres), over length nodes a physical one.

source
VisualGeometryToolkitIO.target_calibration_json — Method
target_calibration_json(s::VgioStyle, c) -> NamedTuple

A planar target's calibration c — VisualGeometryToolkitCore's TargetCalibration (Rigid, a planar EuclideanMap, Scale, Aspect, Skew, ThinPlateSpline, HeightField or a composition of them in Core's canonical order), or an Uncertain one — as the calibration record every target body embeds (its calibration), on IO's style s: the PARAMETRIC RECORD {"type", ["nodes"], ["parameters"]}, its kind's tag in Core's TARGET_CALIBRATION_TAGS, its parameter_vector with every length (by length_mask) in the style's length_unit through write_length's decimal shift, a thin-plate kind's nodes beside them (lengths too); a composition {"type": "composition", "compose": [outer, …, inner]}; an Uncertain one its covariance beside, covariance, each entry in the unit raised to its length dimension. target_calibration_from_json reads it back ==.

A calibration with lengths is stored physical: one of plain numbers is an ArgumentError (attach the unit, as a target's points; a placed target's calibration, which acts in its board's dimensionless chart, is written by the target's own record). A thin-plate kind that is pure bending neither in metres nor in s's unit would not read back and is refused. A package embedding a calibration in a kind of its own (RadiometricCamera's in-plane print error) writes it with this.

A HeightField (bare or Uncertain) is written with PER-FIELD UNITS when the style declares the length roles node and height (both, or neither): its nodes in node's unit or, node = :chart, as plain numbers of a chart the caller defines (page fractions: a plain field over plain nodes, its heights plain metres), its heights in height's unit — the file's units.length_roles say so, {"node": "chart" | <length>, "height": <length>}, and the record states no unit of its own. Pure bending depends on the nodes' unit, never on the heights', so the field is pure bending on its nodes as written; its bending energy is in height² · node⁻² (over chart nodes, height²). target_calibration_from_json reads it back on a style that declares the same roles: == with heights in metres (height = m, RadiometricCamera's board warping); in a decimal unit (mm) a computed height reads back as its persisted form, within the decimal codec's 2 ulp (write_length), and that form is fixed. On a style without the roles, every length is in its length_unit, as before.

A named function, not a JSON.lower method: Core's TargetCalibration union holds every planar EuclideanMap and every composition, so a lower on it would write any such map left in a record as a target calibration.

julia> import JSON

julia> s = VgtkIO.VgioStyle(; length_unit = mm);

julia> text = JSON.json(VgtkIO.target_calibration_json(s, Aspect(0.01) ∘ Skew(-0.002)))
"{\"type\":\"composition\",\"compose\":[{\"type\":\"aspect\",\"parameters\":[0.01]},{\"type\":\"skew\",\"parameters\":[-0.002]}]}"

julia> VgtkIO.target_calibration_from_json(s, JSON.parse(text)) == Aspect(0.01) ∘ Skew(-0.002)
true
source
VisualGeometryToolkitIO.target_from_json — Method
target_from_json(body, unit; resolve = nothing) -> AbstractTarget

Read a target body (the inverse of target_json) whose lengths are in unit, a unit name such as "mm", as lengths in metres, its calibration Uncertain iff the body states a covariance. A planar target that names its reference is returned unresolved unless resolve(reference::Symbol) returns its nominal points — lengths, as the design's owner holds them; plain points are an ArgumentError.

source
VisualGeometryToolkitIO.target_json — Function
target_json(target, unit = mm) -> NamedTuple

The target body every target-carrying kind embeds (see rigschema.jl), its points (lengths) and its calibration's lengths written in the length unit; [`targetfrom_json](@ref) reads it back. A target of plain points, or a plain calibration with lengths, is anArgumentError(attach the unit,p .* m). APlanarTarget` of a referenced design is written by its reference alone. Building blocks for a package serializing its own kind.

source
VisualGeometryToolkitIO.load — Method
load(TargetHomographies, path) -> TargetHomographies{F}
load(TargetHomographies{F}, path) -> TargetHomographies{F}

Read a vgio/target_homographies/v2.0 file: the value it was written from, typed in the pixel frame F the file declares (units.pixel), per frame index every target's HomographyMap (stored unlabeled; homography(th, t, id) labels it TargetPlaneFrame{id} → F) with its canonical parameters exactly as stored, Uncertain where the record states a covariance, with the frames' images, sensors and times and the targets identities. H maps the target's plane (millimetres) to a pixel of F, before the lens of the camera the frame's sensor names (pair them with VGC's radial_homography(camera, H); see save).

The second form asserts the frame: a file declaring another is an ArgumentError. So are parameters that are not canonical or are singular.

source
VisualGeometryToolkitIO.load — Method
load(TargetObservations, path; target = nothing) -> TargetObservations{F}

Read a vgio/observations/v3.0 file of target_point observations: per frame index, per target, its observations typed in the frame F the file declares — pixels exactly as stored, 3D points in metres — Uncertain where it states covariances, with their weights column where stated, the frames' stamps and the targets identities. An IO 0.9 vgio/target_detections, vgio/target_points2d or vgio/target_points3d file (any version that reads) is read through its version steps into this kind; one holding what a TargetObservations cannot (a (target, index) observed twice in one frame, plain and Uncertain points in one file) is refused naming the path, frame, target and index. A file of landmark observations is refused: no VGC container holds them yet.

A Schöps et al. cameracalibration dataset.bin (recognized by its `calibdatamagic, schoeps.jl) is read too: frametis the file'st-th image (its name inimages), each detection a point oftarget— which the file does not name, so the caller states it — its index the feature id + 1 (the reference's ids are 0-based; this importer converts), typed in [SCHOEPSPIXELFRAME](@ref). Atarget` beside a vgio file is refused (it names its own).

source
VisualGeometryToolkitIO.load — Method
load(TargetPoses, path) -> TargetPoses{F}

Read a vgio/target_poses/v3.0 file: F the frame its poses map into, every pose's lengths in metres, Uncertain where the file states a covariance.

source
VisualGeometryToolkitIO.load — Method
load(Trajectory, path) -> Trajectory{S, D}

Read a vgio/trajectory/v5.0 file: its frames as types (S, D from from/to), each pose labeled S → D, lengths in metres — Uncertain where the file states a covariance — with the images, times and recovered flags it records. Type-unstable by nature (the frame types come from the file): load once, dispatch after. An earlier version reads through its version steps; of v2 (free frame names) only CaliBlobs' 2026-09 track segment (track:<s> → camera), read as target:scene_<c> → camera (src/migrate.jl).

source
VisualGeometryToolkitIO.save — Method
save(path, tr::Trajectory{S, D}; length_unit = mm, provenance = (;))

Write a physical VGC Trajectory as a vgio/trajectory/v5.0 file: its frames from = frame_name(S), to = frame_name(D), one record per frame index (sorted) — the pose (a covariance iff Uncertain), and its image, time and recovered flag where the trajectory has them — in length_unit. A trajectory of plain poses is an ArgumentError (attach the unit, t .* m), and so is a time_origin without its UTC offset.

source
VisualGeometryToolkitIO.save — Method
save(path, th::TargetHomographies{F}; provenance = (;))

Write a VGC TargetHomographies as a vgio/target_homographies/v2.0 file whose declared pixel frame (units.pixel) is F, the value's own type — no pixel is converted and none can be written under another frame's label — and whose targets are the value's th.targets: the content_ids of the definitions its target ids resolve in, each the identity of a rig of boards or of a single unposed target. Per frame index (sorted) it writes the image and sensor (both required), the time, and every target's homography (ids sorted) as the homography record:

{"target": "a1f2", "type": "homography_map", "parameters": [h11, h12, h13, h21, h22, h23, h31, h32, h33]}

— VGC's parameter protocol of the HomographyMap: its nine entries row-major, canonical (unit Frobenius norm, h33 ≥ 0, VGC sign_normalize), so one placement always writes the same bytes and a stored H seeds HomographyManifold8(H) directly; an H already canonical is written as it is. An Uncertain homography adds its 8×8 covariance in that chart.

H maps the target's plane — its design frame, millimetres — to a pixel of F, BEFORE the lens of the camera the frame's sensor names, about that camera's centre: exactly RadialHomography's H. An H is paired with that camera by VGC's radial_homography(camera, H): for a projective camera the camera itself is the model; for a metric one (fx == fy, no skew) it converts the division coefficients kₚ of K's normalized chart to λₚ = kₚ / f^(2p) about the principal point — equivalently, a plane point X lands on the pixel project(camera, K⁻¹·H·[X; 1]).

A degenerate H (negligible norm, or non-finite), a value naming no targets, and a frame with no image or sensor are an ArgumentError, and no file is written.

source
VisualGeometryToolkitIO.save — Method
save(path, x::TargetObservations{F}; length_unit = mm, provenance = (;))

Write a VGC TargetObservations as a vgio/observations/v3.0 file of target_point observations: per frame index (sorted), its stamps, and per target (ids sorted) its point indices, its points (each {"xy"} or {"xyz"}, its covariance iff Uncertain), and its weights column where it has one (the only column the kind holds). Pixels declare the value's pixel frame F (units.pixel) and are written as they are; every frame must name its image and sensor, and the value its targets identities: the content_ids of the definitions its ids resolve in, each a rig of targets or a single unposed target (its observations named by its design reference, or by its content id when it has none). 3D points declare frame = frame_name(F) and are written in length_unit (covariances in its square); every frame must name its sensor, and plain points are an ArgumentError (attach the unit, p .* m).

source
VisualGeometryToolkitIO.save — Method
save(path, tp::TargetPoses{F}; length_unit = mm, provenance = (;))

Write a physical VGC TargetPoses as a vgio/target_poses/v3.0 file declaring to = frame_name(F): per frame index (sorted), its image and sensor (both required) and time, and every target's pose (ids sorted; a covariance iff Uncertain), in length_unit. Plain poses are an ArgumentError.

source
VisualGeometryToolkitIO.load — Method
load(CaptureSettings, path) -> Attributed{CaptureSettings}

Read a vgio/capture_settings/v2.0 file: the VGC CaptureSettings (exposure times in seconds, lengths in metres), Attributed with its identity_sources and, where the file states them, exif_lens and sensor — exactly the value save wrote. A v1 file is read through its version step.

source
VisualGeometryToolkitIO.save — Method
save(path, x::Attributed{CaptureSettings}; length_unit = mm, provenance = (;))

Write a VGC CaptureSettings as a vgio/capture_settings/v2.0 file: per frame index (sorted) its exposure time (seconds), f-number and ISO, its nominal focal length and its focus distance where known, in length_unit; and the body and lens identities (device). The value is Attributed with where each identity came from, (; identity_sources = (body = "exif" | "config", lens = …)), optionally exif_lens, the EXIF claim a config-stated lens overrode, and optionally sensor, the camera these settings are of. A bare CaptureSettings is an ArgumentError: an identity's source is not guessed.

source
VisualGeometryToolkitIO.load — Method
load(Dict{Symbol, GaussianBlur}, path) -> Dict{Symbol, GaussianBlur}

Read a vgio/blur/v2.0 file: name → GaussianBlur, each in the storage its block states, labeled with its plane (a pixel frame's px², a target plane's m² quantities).

source
VisualGeometryToolkitIO.save — Method
save(path, blurs::AbstractDict{Symbol, <:GaussianBlur}; length_unit = mm, provenance = (;))

Write named Gaussian blurs (a camera's in-focus blur per channel, :R, :G, :B; a print's blur) as a vgio/blur/v2.0 file: each one's covariance in the storage it holds ({"isotropic": λ} for a round one, {"diagonal": […]}, or rows) and the plane it lives on, its covariance's frame — a pixel frame (PixelFrame{O}, an ImageFrame{id}: px², plain numbers or px quantities) or a target's plane (TargetPlaneFrame{id}, the target named: m² quantities, written in length_unit²). An unlabeled blur is an ArgumentError (name the plane it lives on: GaussianBlur(CovMat{2, …, F}(Σ))), and so is a plain one on a target's plane (its lengths need units). load gives the blurs back with their frames, in their storage, each entry as the file's length rule reads it: a decimal variance exactly, a variance computed in code (σ² of a σ) to within an ulp, as for every file length (units.md).

source
VisualGeometryToolkitIO.json_schema — Function
json_schema(kind::AbstractString[, version::Tuple{Int, Int}]) -> JSON.Object

The JSON Schema (draft 2020-12) of a vgio/<kind> file at the version this package writes (by default the kind's current one; version another version a writer still emits, _written_versions(kind): an ArgumentError for any other), generated from the kind's validator table — the shape validate and every reader check. Its $id is https://visualgeometrytoolkit.github.io/schemas/vgio/<kind>/v<major>.<minor>.json. A cross-field check JSON Schema cannot state is the description of the object it constrains, so the Julia validator may refuse a file the schema accepts, never the reverse. An unknown kind is an ArgumentError listing the kinds. JSON.json(json_schema("rig"); pretty = 4) is the published file.

julia> VgtkIO.json_schema("transforms")["title"]
"vgio/transforms/v5.0"
source
VisualGeometryToolkitIO.append_jsonl — Method
append_jsonl(path, row)

Append row (anything JSON.json serializes — a NamedTuple, Dict, …) to path as one JSON line. Thread-safe within the process (per-path lock) and process-append-safe (the line is written with a single write call on an append-mode handle, so concurrent writers interleave at line boundaries). Read the file back with JSON.parse per line.

source
VisualGeometryToolkitIO.load_manifest — Method
load_manifest(dir) -> NamedTuple

Read dir/calibration.json, a vgio/calibration/v3.0 manifest (an earlier one read through its version steps), and check the set it binds: every listed file exists, holds the record schema the manifest lists and hashes to the recorded SHA-256 — an ArgumentError naming the file otherwise — whatever its owner; a file of VGIo's kinds is validated, and one of another owner's when that owner has a reader (validate_record). The targets resolve: every target and rig file listed is loaded, and an observations or target_homographies file naming a targets identity (content_id) none of them has, or a target name not inside the targets it references, is refused naming that file. A rig's targets are named by their ids; a single target by its design reference (a planar body's) or, when it has none, by its content_id. A listed file of an earlier schema version is read through its version steps.

Returns (; dir, result_kind, model, files, metrics, provenance): result_kind the manifest's "metric", "projective" or "image"; model the VGC CameraModelSpec or nothing; files a vector of (; path, sha256, schema, role, derived_from), paths relative to dir; metrics and provenance the parsed objects or nothing. Read a file with load(T, joinpath(dir, path)).

source
VisualGeometryToolkitIO.save_manifest — Method
save_manifest(dir, files; result_kind, model = nothing, metrics = nothing, provenance = (;)) -> String

Write dir/calibration.json, a vgio/calibration/v3.0 manifest binding a calibration result's record files, and return its path. files lists the record files beside it — VGIo's kinds and any other owner's (rc/…, caliblobs/…) — each a path relative to dir (an authority) or (; path, role = "authority", derived_from = String[]), where role is "authority" or "derived" and a derived file names, in derived_from, the listed files it is computed from (target_poses from the trajectory and the targets). Each entry records the file's SHA-256 and its record schema.

result_kind is "metric", "projective" or "image" (an image-based result with no placement in space). model is an optional VGC CameraModelSpec (written through its toml_value; its intrinsics must be the result_kind's); metrics an optional NamedTuple or Dict of the result's numbers (name → finite number, a closed object); provenance a free-form NamedTuple no reader interprets.

The manifest is checked as load_manifest checks it, before anything is written: an ArgumentError for a missing file or one with no record schema, a derived file without derived_from (or an authority with one), a derived_from naming a file that is not listed or forming a cycle, a file its owner's reader refuses, and an observation file (observations, target_homographies) naming a target the listed target and rig files do not hold.

source
VisualGeometryToolkitIO.validate_record — Function
validate_record(::Val{owner}, path, schema) -> Any

The check of a record of another owner's kind (owner a Symbol, the first part of its schema, <owner>/<kind>/v<major>.<minor>): a declared extension point (CONTRACT_GENERICS). An owner that adds a method for its owner has a reader load_manifest runs on every listed file of its kinds (after the hash check every listed file gets); the method throws an ArgumentError naming what is wrong. VGIo's own kinds are checked by validate.

A vgio kind that moved to its owner (vignetting, environment_light, radial_profile, panorama) keeps its schema name, so its owner is keyed by the kind: validate_record(::Val{Symbol("vgio/<kind>")}, path, schema), the method VisualRadiometryToolkitIO adds for each of its kinds. validate and load_manifest run it when the owner is loaded.

source
VisualGeometryToolkitIO.load — Method
load(Dict{String, <:AbstractVector{<:AbstractDetection}}, path) -> Dict{String, Vector{D}}

Read a vgio/detection/v1.0 file (save's): per image name, its detections as a Vector{D}, D the detection type the file declares (a StructArray written reads back as a Vector of its element type), centres in colmap pixels (a file in another pixel frame moved into it). A detection the file holds without a covariance (its covariance_status stated) reads back with the NaN covariance in the declared storage.

source
VisualGeometryToolkitIO.save — Method
save(path, detections::AbstractDict{<:AbstractString, <:AbstractVector{<:AbstractDetection}}; provenance = (;))

Write detections per image — a detector's output, image name => detections (VisualGeometryToolkitFeatures' detect_foerstner, ASIFT's; a StructArray or a Vector) — as a vgio/detection/v1.0 file, images sorted by name, pixels in colmap (the detectors' convention). Every detection is of one concrete type Attributed{F, A} or Attributed{Uncertain{F, C}, A}, F a feature frame of Float64 or Float32, A a NamedTuple of attributes of the types Float64, Float32, Int, Bool, String, Symbol and Point2{Float64}; the file declares that type once. An uncertain frame's covariance is over its frame_dof parameters, centre first; a detection whose covariance is not finite (every entry NaN: its producer has none) is written without one and must carry the attribute covariance_status, the producer's reason. Anything else is an ArgumentError, nothing written.

source
VisualGeometryToolkitIO.load — Method
load(SensorCharacterisation, path) -> SensorCharacterisation

Read a vgio/sensor_characterisation/v2.0 file (save's; a v1.0 file through its step): the SensorCharacterisation exactly as written — per ISO each present slot's component with its source and standard error, an absent slot its absent type (FileBlack, NoNoise, NoDefects); a Dark's maps (Matrix{Float32}, each of a Darks' too) read from the rasters beside it, each checked against its SHA-256, the raster profile and its size.

source
VisualGeometryToolkitIO.save — Method
save(path, characterisation::SensorCharacterisation; provenance = (;))

Write a VGC SensorCharacterisation as a vgio/sensor_characterisation file — v2.0 when an entry's black is a Darks, else v1.0, byte for byte IO 0.10.1's (so its readers read it): the body's identity (device.body) and one entry per ISO (in increasing ISO), each present slot as its component's body with its source and standard error, an absent slot (FileBlack, NoNoise, NoDefects) absent. A Dark's offset and variance maps are written beside path as rasters, the raster payload body (<stem>.iso<ISO>.dark_offset.tiff, <stem>.iso<ISO>.dark_variance.tiff, float32 TIFFs of the raster profile, row 1 on top) bound by their SHA-256; a Darks' maps one pair per band, <stem>.iso<ISO>.band<k>.dark_offset.tiff and ….dark_variance.tiff, k the band's place in increasing exposure.

source
VisualGeometryToolkitIO.read_tiff — Method
read_tiff(T, path) -> Matrix{T}

The grey image of the TIFF at path (its first image), as (rows, columns), the first row on top, read through libtiff: T is UInt8 for an 8-bit unsigned image and Float32 for a 32-bit IEEE floating-point one (every value bit for bit, NaN included). The file holds one sample per pixel, min-is-black or — an 8-bit image only, as pdftocairo -gray may write it — min-is-white, which is returned inverted (0xff - v), so a value is always the grey level with black

  1. Any compression and predictor libtiff decodes is read. A file of another

sample type, more than one sample per pixel, or a min-is-white Float32 image is an ArgumentError naming it; a libtiff failure an error. The reader of write_tiff's files and of load_raster's payload.

source
VisualGeometryToolkitIO.write_tiff — Method
write_tiff(path, image::AbstractMatrix{T}; compression = :none, predictor = :none, rows_per_strip = 64,
           density = nothing, software = nothing, icc = nothing) -> path

Write a grey image — T is UInt8 (8 bits, unsigned) or Float32 (32 bits, IEEE floating point, every value bit for bit, NaN included) — as a little-endian TIFF of one image, one sample per pixel (min-is-black), in strips of rows_per_strip rows, through libtiff. image is (rows, columns), the first row on top. compression is :none, :lzw or :deflate (zlib), all lossless; predictor:none or :horizontal (row differences, which make a smooth image compress; a compression's, so not with :none). Optional tags: density, a pixel density (300dpi), in the resolution tags (pixels per inch); software, a string; icc, an ICC profile's bytes, embedded. Nothing else is written.

The stack's one TIFF writer: BlobBoards' board TIFFs (8-bit, LZW with the horizontal predictor, its density and profile) and the payload of a vgio/raster/v1 file (save_raster: Float32, uncompressed or Deflate, no tag that means anything) are written by it. A libtiff failure — a path it cannot open, a full disk — is an error naming the file; read_tiff reads the image back.

source
VisualGeometryToolkitIO.load_raster — Method
load_raster(path) -> (; values::Matrix{Float32 | UInt8}, frame, nan::Symbol)

Read a vgio/raster/v2.0 file (save_raster's; a v1 file through its step): the header is validated, the TIFF it names (beside it) must hash to the header's SHA-256 — a corrupted or replaced payload is an ArgumentError naming it, before it is decoded — and must be of the raster profile for its element type and of the header's size. values is (rows, columns), every value as stored, NaN bit for bit; frame the header's, (chart, area) with area a Rect2{Float64} in plain metres, or the PixelFrame type the file declares; nan:unobserved or :none (a NaN in a :none raster is refused).

source
VisualGeometryToolkitIO.save_raster — Method
save_raster(path, values::AbstractMatrix{Float32 | UInt8}; frame, nan, length_unit = mm, compression = :deflate,
            provenance = (;)) -> path

Write a raster as a vgio/raster/v2.0 file: the JSON header at path and the values beside it, <name>.tiff (path's name with its extension replaced), a TIFF of the raster profile (one image, one sample per pixel — a 32-bit IEEE float or an unsigned byte —, little-endian, in strips, compression:deflate or :none, both lossless, and no predictor), so every value — NaN included — reads back bit for bit. The header states the raster's size ({width, height}: its columns and rows), its element type, its frame, what a NaN means and the SHA-256 of the TIFF's bytes; nothing the values mean is in the TIFF's tags. values is (rows, columns), row 1 on top.

  • frame, required: a chart rectangle, (chart = :page, area = Rect2(x, y, w, h)) (or chart = :texture; the design chart, x right and y up, area its lower-left corner and widths in plain metres, written in length_unit) — row 1 its top edge — or a pixel frame, PixelFrame{:colmap} — values[r, c] the image's pixel at row r, column c (the file's units.pixel).
  • nan, required: :unobserved (a NaN is a value nothing observed) or :none (the raster holds no NaN: one is refused; a UInt8 raster's).

Both files are written through a staging directory beside them and renamed into place once the TIFF has been checked against the profile and the header validated (write_staged); load_raster reads them back.

source
VisualGeometryToolkitIO.KindSpec — Type
KindSpec(schema, required, optional = []; package, check = nothing, rule = "", schema_keywords = [])

A file kind of another package: its schema string, "<owner>/<kind>/v<major>.<minor>" (the version its writer writes), and the table of its files — the envelope every vgio file has (schema, generator, units, conventions), then the body's required and optional keys (each a vector of name => spec, built by object_spec and the other combinators), then the free-form provenance. package names the owning package (the JSON Schema says whose kind it is). check(record) is a cross-field check of the whole record (nothing, or the refusal's message), rule that check in words and schema_keywords the JSON Schema keywords that state it (as checked_spec's rule and schema).

The owner writes its files with write_kind and reads them with read_kind; json_schema(kind) is the kind's JSON Schema and schema_versions(kind) the versions it reads. Its earlier versions are its migrate_schema steps.

julia> kind = VgtkIO.KindSpec("toy/gains/v1.0", [:gains => VgtkIO.array_spec(VgtkIO.real_spec())]; package = "Toy");

julia> path = joinpath(mktempdir(), "gains.json");

julia> VgtkIO.write_kind(path, kind, (gains = [1.0, 0.5],))

julia> VgtkIO.read_kind(path, kind).gains == [1.0, 0.5]
true
source
VisualGeometryToolkitIO.array_spec — Method
array_spec(element; length = nothing) -> spec

The table of an array whose every entry is element (a spec), of exactly length entries when one is given.

source
VisualGeometryToolkitIO.body_spec — Method
body_spec(T) -> spec

The table of a body VisualGeometryToolkitIO writes, for a kind of another package that embeds it:

  • body_spec(BoundedCamera): the bounded camera body, a camera store's entry without its name (camera_json(camera::BoundedCamera, frame; length_unit), camera_from_json(BoundedCamera, body, frame; length_unit));
  • body_spec(Trajectory): the trajectory body, a vgio/trajectory file without its envelope (JSON.lower(style, trajectory), JSON.lift(style, Trajectory, body));
  • body_spec(FitResult): a fit's termination record (fit_record_json, fit_record_from_json);
  • body_spec(PixelFrame): a pair of pixel coordinates [x, y], in the file's units.pixel.
source
VisualGeometryToolkitIO.checked_spec — Method
checked_spec(spec, check; rule = "", schema = []) -> spec

spec, then the cross-field check check(x) of the value it accepted, which returns nothing or the refusal's message. rule states the check in words (the JSON Schema's description of the object) and schema the JSON Schema keywords that state it where JSON Schema can (one subschema, a Dict, or a vector of them: all hold).

source
VisualGeometryToolkitIO.if_key_spec — Method
if_key_spec(key::Symbol, then, otherwise) -> spec

The table of an object of one of two shapes, told apart by whether it holds key: then (a spec) if it does, otherwise if not. JSON Schema: if/then/else.

source
VisualGeometryToolkitIO.json_schema — Method
json_schema(kind::KindSpec; id_base = "https://visualgeometrytoolkit.github.io/schemas/") -> JSON.Object

The JSON Schema (draft 2020-12) of another package's kind, generated from its table as this package's own are: its $id is id_base followed by the kind's schema string and .json. JSON.json(json_schema(kind); pretty = 4) is the file an owner publishes.

source
VisualGeometryToolkitIO.matrix_rows — Method
matrix_rows(A::AbstractMatrix) -> Vector{Vector{Float64}}
rows_matrix(rows) -> Matrix{Float64}

A matrix as a record holds it, its rows (each a Vector{Float64}, row 1 first), and the matrix read back from such rows: the one form of a matrix body (a surface's control points, a map's coefficients per channel) for a kind of this package or of another.

source
VisualGeometryToolkitIO.migrate_body — Method
migrate_body(T, body::AbstractDict) -> Dict{String, Any}

A body VisualGeometryToolkitIO 0.9 wrote, embedded in another package's record, as the body IO 0.10 writes — the part of that package's version step (migrate_schema) that is this package's to state, beside migrate_envelope:

  • migrate_body(BoundedCamera, body): a bounded camera body (its width and height as image_size, its pitch an object, its lens and lattice records); a body already in the 0.10 form comes back as it is;
  • migrate_body(Trajectory, body): a trajectory body (each frame's t as frame_index, the frame name camera_optical as camera).

body is the parsed record with String keys, as a step holds it.

source
VisualGeometryToolkitIO.migrate_file — Method
migrate_file(T, kind::KindSpec, src, dst; what = "the value", length_unit = true) -> NamedTuple

The file form of a version step (migrate_schema(::Val{schema}, src, dst)) of a kind whose files are one value of type T, read by the owner's load(T, path) and written by its save(path, value): the file at src is loaded (through the version steps), saved to dst with the provenance the migrated record holds (and, with length_unit, in the length unit it declares: a save that takes no length_unit states false), read back and compared with the value loaded (same_value), its unit and provenance with the record's. A difference is an ArgumentError naming src and what. Returns (; to = kind.schema), the summary vgio_migrate reports.

VisualGeometryToolkitIO.migrate_schema(::Val{Symbol("toy/gains/v1")}, src::AbstractString, dst::AbstractString) =
    VisualGeometryToolkitIO.migrate_file(Gains, GAINS_KIND, src, dst; what = "the gains", length_unit = false)
source
VisualGeometryToolkitIO.named_spec — Method
named_spec(ok, what::AbstractString) -> spec

The table of a string the predicate ok accepts, what saying in words what it is (the refusal reads "x is not what"). A predicate that is a set membership, an equality or a pattern is stated in the JSON Schema too: in(values) as enum, ==(value) as const, Base.Fix1(occursin, regex) as pattern; any other is the schema's description alone.

source
VisualGeometryToolkitIO.object_spec — Method
object_spec(required::Pair{Symbol}...; optional = ()) -> spec

The table of an object with EXACTLY these keys, each name => spec: a missing required key and an unknown key are refused alike, by name (an unknown key is tolerated only in a file of a higher minor version than the reader's). optional lists the keys that may be absent. The combinators of a KindSpec table are this one and token_spec, integer_spec, real_spec, array_spec, named_spec, checked_spec, if_key_spec, tagged_spec and body_spec.

source
VisualGeometryToolkitIO.read_kind — Method
read_kind(path, kind::KindSpec) -> JSON.Object

Read a file of kind as its current record, checked against kind's table before any field is used: parsed (a JSON.Object, read by property access — the form JSON.lift(::VgioStyle, T, record) takes; VgioStyle(record) is the style its units declare). A file of an earlier version of the kind is read through the owner's version steps (migrate_schema, run by migrate_record) in memory; a file of the kind's major at a higher minor is read with the keys that minor added tolerated. Any other schema is an ArgumentError naming the file, its schema and the one expected, and so is a record the table refuses (naming the key and the problem).

source
VisualGeometryToolkitIO.rows_matrix — Function
matrix_rows(A::AbstractMatrix) -> Vector{Vector{Float64}}
rows_matrix(rows) -> Matrix{Float64}

A matrix as a record holds it, its rows (each a Vector{Float64}, row 1 first), and the matrix read back from such rows: the one form of a matrix body (a surface's control points, a map's coefficients per channel) for a kind of this package or of another.

source
VisualGeometryToolkitIO.schema_versions — Method
schema_versions(kind::KindSpec) -> Vector{String}

The schema versions the owner of kind reads, derived from its version steps (the migrate_schema methods of a record of an earlier version of the kind), in version order, then the kind's current one.

source
VisualGeometryToolkitIO.tagged_spec — Method
tagged_spec(what, alternatives::Pair{<:AbstractString}...; def = "", unknown = nothing) -> spec
tagged_spec(build, what; def, unknown = nothing) -> spec

The table of a body told by its type: alternatives are tag => spec, the spec of the whole body of that tag (its type key included, a token_spec of the tag). what names the body in the refusals ("a vignetting"). A type none of them has is refused listing the tags, or with unknown(tag)'s message when unknown is given (a tag registry's: a retired tag with its successor).

A body that holds a body of its own kind (a log field's spline) is built by the second form: build(self) returns the alternatives, self being the spec under construction. Such a spec states def, its name among the JSON Schema's $defs, where it is defined once and referenced; with no def the alternatives are stated in place (oneOf).

source
VisualGeometryToolkitIO.write_kind — Method
write_kind(path, kind::KindSpec, body::NamedTuple; style = VgioStyle(), provenance = (;))

Write body — the body of a kind file, without its envelope; its VisualGeometryToolkitCore values (and the owner's own) left for style to lower — as a file of kind: the envelope (kind's schema, the generator, the units object style declares and the fixed conventions), the body's keys in their order, then provenance when it is not empty. The very bytes that land on disk are checked against kind's table first, so a writer cannot produce a file its reader refuses (an ArgumentError naming the file, the key and the problem; nothing is written). read_kind reads the file.

source
VisualGeometryToolkitIO.edited_copy — Function
edited_copy(f, src, dst = joinpath(dirname(src), "edited.json")) -> String

The record file src parsed into mutable dictionaries, edited by f(t) (a key removed, a value changed) and written to dst, which is returned: a record a reader is to refuse, made from a valid file — @test_throws ArgumentError load(T, edited_copy(t -> delete!(t, "units"), path)).

source
VisualGeometryToolkitIO.nested_roundtrip — Method
nested_roundtrip(T, x; style = VgioStyle(), kw...) -> T

x as the body of another record ({"body": x}), lowered on style, written, parsed and lifted back as a T (kw to JSON.lift): the value a record of another kind that embeds x reads. A kind's test checks that its body nests: nested_roundtrip(AbstractVignetting, v; style) == v.

source
VisualGeometryToolkitIO.MOVED_NAMES — Constant
MOVED_NAMES

The names this package retired by moving them to another package (save_panorama and load_panorama: PanoramaStitching's), each a refusal here. The stack's duplication check reads it (VisualGeometryToolkitCore's MOVED_NAMES convention): the package that took a name over is not reported for defining it.

source