Third-Party Calibrations
The OpenCV and Kalibr lens conventions, the OpenCV and MATLAB calibration readers, the Schöps cameracalibration readers, the OpenCV-shaped writer, the conversions to native files, and the migration of an earlier schema version: the version steps every reader runs (`migrateschema,migraterecord,schemaversions,migrateenvelope), the rewrite of a file (vgiomigrate,vgiomigratetree) and the comparison that verifies one (same_value`).
VisualGeometryToolkitIO.kalibr_lens — Method
kalibr_lens(camera_model, intrinsics, distortion_model, distortion_coeffs) -> (fx, fy, cx, cy, lens)A Kalibr camchain camera (camera_model ∈ pinhole, omni, ds, eucm; distortion_model ∈ radtan, equidistant, fov, none) as its focal lengths, principal point and the VGC lens computing Kalibr's projection.
VisualGeometryToolkitIO.opencv_camera — Method
opencv_camera([file_frame = PixelFrame{:opencv},] K, dist) -> CameraModelOpenCV's calibration — the camera matrix K (pixels, cx, cy in file_frame, OpenCV's own frame by default; no skew) and the distortion vector dist (opencv_lens: 4, 5, 8, 12 or 14 entries) — as a VGC CameraModel(LogicalIntrinsics(K′), lens) with K′'s principal point in the canonical COLMAP frame, moved by EuclideanMap(file_frame, PixelFrame{:colmap}). Inverse of opencv_parameters.
The round trip opencv_parameters(opencv_camera(K, dist)) returns K and dist bit for bit, with one exception that floating point forces: a principal point coordinate c ≥ ½ in [2ᵏ − ½, 2ᵏ) whose last mantissa bit is set (such as 511.75000000000006 or 2047.5000000000002) has no exact c + ½ (the sum needs one bit more than its binade holds), and comes back within one ulp of c (abs(c′ − c) == eps(c)). Every other c ≥ ½ — 511.5, 2047.5, any c with its last bit clear — comes back exactly. A file in another frame (PixelFrame{:julia}, whose map shifts by −½) round-trips exactly.
VisualGeometryToolkitIO.opencv_coefficients — Method
opencv_coefficients(lens) -> Vector{Float64}OpenCV's distortion vector for a lens it computes: a perspective lens whose distortion is OpenCV's — a radial factor of at most three numerator and three denominator coefficients, tangential terms, a thin prism of at most two coefficients per axis, then a tilt — written as the shortest vector (4, 5, 8, 12 or 14 entries) holding all of it. Any other lens is refused.
VisualGeometryToolkitIO.opencv_lens — Method
opencv_lens(c::AbstractVector) -> LensThe lens computing OpenCV's projectPoints distortion for the coefficient vector c = (k1, k2, p1, p2[, k3[, k4, k5, k6[, s1, s2, s3, s4[, τx, τy]]]]) — 4, 5, 8, 12 or 14 entries, the terms that length evaluates. Inverse of opencv_coefficients.
VisualGeometryToolkitIO.opencv_parameters — Method
opencv_parameters([to_frame = PixelFrame{:opencv},] camera) -> (; K, dist)OpenCV's camera matrix K (cx, cy in to_frame, OpenCV's own by default) and distortion vector dist (opencv_coefficients) of a VGC camera whose lens OpenCV computes. Inverse of opencv_camera; a skewed K or a lens OpenCV does not compute is refused.
VisualGeometryToolkitIO.pose_covariance_from_ros — Method
pose_covariance_from_ros(Σ_ros) -> CovMat{6}A ROS PoseWithCovariance covariance (x, y, z, rot X, rot Y, rot Z; a 6×6, or the message's row-major float64[36]) in the stack's order, rotation first — the covariance an Uncertain pose carries. Inverse of ros_pose_covariance.
VisualGeometryToolkitIO.ros_pose_covariance — Method
ros_pose_covariance(Σ) -> SMatrix{6, 6, Float64}A pose covariance in the stack's order ([δω; δt], rotation first) as ROS PoseWithCovariance.covariance orders it (x, y, z, rot X, rot Y, rot Z): P·Σ·Pᵀ with P = [0 I; I 0]. Flatten row-major (vec(permutedims(Σ_ros))) for the message's float64[36]. Inverse of pose_covariance_from_ros.
VisualGeometryToolkitIO.ExternalCalibration — Type
ExternalCalibration{C <: CameraModel}One third-party calibration file as read by load_opencv_calibration or load_matlab_calibration: source (:opencv or :matlab), camera (a VGC CameraModel, in the canonical frame by construction), poses (one VGC EuclideanMap labeled TargetFrame{target} → CameraFrame, its translation lengths in metres, per image; nothing where the file has null), the file's reprojection_error in pixels together with the statistic it is (error_statistic: :rms for OpenCV, :mean for MATLAB), path, and images: the image name of every pose when the file names them — this package's writer does — or nothing for a third-party export, whose positional join with the images is then the caller's.
A FOREIGN-FORMAT ADAPTER — the in-memory image of a third-party file, which VGIo reads and does not own — so it keeps its own type; everything it holds is a VGC value.
VisualGeometryToolkitIO.load_kalibr_camchain — Method
load_kalibr_camchain([file_frame = PixelFrame{:opencv},] path; camera = "cam0") -> BoundedCameraOne camera of a Kalibr camchain (camchain.yaml of kalibr_calibrate_cameras): its camera_model × distortion_model as kalibr_lens maps them, its intrinsics (focal lengths and principal point) and its resolution, as a BoundedCamera in VGC's canonical (COLMAP) pixel frame. file_frame is the pixel frame of the file's principal point, which Kalibr does not write: its projection is OpenCV's, PixelFrame{:opencv}, the default. The extrinsics of a multi-camera chain (T_cn_cnm1) are not read.
VisualGeometryToolkitIO.load_matlab_calibration — Method
load_matlab_calibration([file_frame = PixelFrame{:julia},] path; file_unit, target = "calibration_target")
-> ExternalCalibrationRead a MATLAB Computer Vision Toolbox calibration export. The radial/tangential files (fx, fy, cx, cy, r1, r2, r3, t1, t2) state OpenCV's polynomial term for term, so the camera is OpenCV's five-coefficient model, opencv_lens([r1, r2, t1, t2, r3]). The fisheye file (mapping_coeffs, distortion_center, stretch_matrix, MATLAB's fisheyeIntrinsics) is Scaramuzza's model: the sensor-plane point (u′, v′) reaches the image as stretch_matrix · (u′, v′) + distortion_center and back-projects to the ray (u′, v′, a0 + a2·ρ² + a3·ρ³ + a4·ρ⁴) in the sensor-plane pixel radius ρ, so a0 is the focal length, the stretch and the centre are K, and the polynomial normalized by a0 is VGC's Scaramuzza (aᵢ ↦ aᵢ·a0^(i−1)). K must be upper triangular and the stretch matrix is not: its RQ factorization S = U·Q puts a0·U in K and Q, a rotation of the sensor plane, into the camera frame — a rotation about the optical axis (a fraction of a degree on this capture) that every returned pose carries, so the camera and its poses stay one consistent model. That rotation is part of the difference between this camera's frame and an OpenCV fit's, and shows in a mount compared across the two. mean_error is the file's statistic — a MEAN reprojection error, not an rms (error_statistic == :mean).
file_frame is the pixel frame of the file's centre and principal point: MATLAB's documented convention, PixelFrame{:julia} (top-left pixel centre at (1, 1)), by default — a fitted principal point cannot tell it from an exporter's shift to OpenCV's, so override it only for a file verified to be in another frame. file_unit is the world unit the toolbox was given the pattern in (mm for a pattern typed in millimetres) — tvec is in it; there is no default. MATLAB's board frame has x and y exchanged relative to OpenCV's for the same pattern: the poses are returned in MATLAB's own board frame, so name its target apart from an OpenCV calibration's. target names the pattern in the pose records (target → camera).
VisualGeometryToolkitIO.load_opencv_calibration — Method
load_opencv_calibration([file_frame = PixelFrame{:opencv},] path; file_unit, target = "calibration_target")
-> ExternalCalibrationRead an OpenCV calibration export: fx, fy, cx, cy; the distortion vector by name — k1, k2, p1, p2 required, k3–k6, s1–s4 and the tilt tilt_x, tilt_y (OpenCV's τx, τy) as the file names them — read as the lens computing OpenCV's model for the shortest distortion vector holding every named coefficient (opencv_lens), the unnamed ones zero; an unknown key is refused, never ignored (a dropped tilt would be a different camera); rms in pixels; poses, one {rvec, tvec} per image (null allowed); and images, the name of each pose's image, when the file names them (this package's writer does; a third-party export does not, and its join with the images is positional and the caller's).
The two arguments are statements about the FILE — what a third-party export does not declare — never labels on data: file_unit is the length unit of tvec (the object points' unit, m or mm), and file_frame the pixel frame of cx, cy, OpenCV's own PixelFrame{:opencv} by default (a type, it leads). The camera returned is in VGC's canonical frame by construction and the poses' translations lengths (metres), so nothing downstream restates either. target names the pattern in the pose records (target → camera).
Most third-party exports declare neither and are read as stated; some declare tvec_unit. A file written by save_opencv_calibration declares both (unit, pixel_frame; a file written before 0.9 declares its pixel frame under the legacy key of earlier releases, read the same way, never both), and a declaration that differs from the caller's is an ArgumentError, never a silent rescale: a metre file read as millimetres puts every target a thousand times too near.
VisualGeometryToolkitIO.save_opencv_calibration — Method
save_opencv_calibration([to_frame = PixelFrame{:opencv},] path, camera, poses; rms, to_unit, images)
save_opencv_calibration([to_frame = PixelFrame{:opencv},] path, cal::ExternalCalibration; to_unit, images = cal.images)Write an OpenCV-shaped calibration export — THE INVERSE of load_opencv_calibration, and the only writer for that shape, so the two cannot drift: fx, fy, cx, cy, the twelve distortion coefficients by name (k1–k6, p1, p2, s1–s4, each written even when zero, which is what makes a default, rational or thin-prism fit one file shape), rms in pixels, one {rvec, tvec} per image — null for an image with no pose — and images, the name of each pose's image, REQUIRED: a positional join with an image list kept elsewhere is exactly the out-of-band knowledge a file must not need.
The shape is a THIRD-PARTY one, so its conventions are its consumer's, and the two arguments are CONVERSION TARGETS applied to data whose own conventions its types fix — the camera's K is canonical by VGC's construction, the poses' translations are lengths — never labels for it:
to_frame the pixel frame cx, cy are written in; OpenCV's own, PixelFrame{:opencv}, by default. A type, it leads. to_unit the length unit tvec is written in (write_length: a pose 1.39719 m from the target is tvec 1.39719 in m, 1397.19 in mm). A plain translation is an ArgumentError.
Both are also written into the file, under pixel_frame and unit, and the reader refuses a caller who states different ones.
camera must carry a lens OpenCV's distortion model computes (opencv_coefficients); the file names the coefficients of the shortest OpenCV vector holding it. A K with nonzero skew is refused: the shape has no field for it.
VisualGeometryToolkitIO.SCHOEPS_PIXEL_FRAME — Type
SCHOEPS_PIXEL_FRAMEThe pixel frame of Schöps et al.'s camera_calibration files: origin at the top-left corner of the top-left pixel, so pixel (i, j)'s centre is (i + ½, j + ½) — PixelFrame{:colmap} exactly (the identity EuclideanMap(PixelFrame{:colmap}, PixelFrame{:colmap})).
VisualGeometryToolkitIO.load — Method
load(PlanarTarget, path; resolve = nothing) -> PlanarTarget | Attributed{<:PlanarTarget}A planar target from a vgio/target file (as load(AbstractTarget, path), refusing a points target), or from the layout file of the tool that generated it, decided by its content:
- Schöps et al.'s pattern YAML (
create_calibration_pattern.py:squares_x, …,apriltags,page) —PlanarTarget(SchoepsPattern(…); canvas), the page its canvas; - Kalibr's target YAML of an
aprilgrid(target_type: aprilgrid,tagCols,tagRows,tagSizein metres,tagSpacingthe gap over the tag size) —PlanarTarget(AprilGrid(…)), the gaptagSize · tagSpacing.
Either way the target records its layout, so save writes it as one.
VisualGeometryToolkitIO._calibration_v1_to_v2 — Method
_calibration_v1_to_v2(tree) -> Dict{String, Any}The version step vgio/calibration/v1 → v2 (the owner's ruling, 2026-11-11: the stack's one parameter-holding keyword is fixed). A v1 manifest's model lens table named the coefficients a calibrator MOVES ("free"); v2 names those it HOLDS ("fixed"), the complement within the lens's parameter_names, in their order — the same LensSpec. A model without "free" (every coefficient moving) is unchanged. Read on load only, never rewritten on disk; saving writes v2.
VisualGeometryToolkitIO._migrate_cli — Method
_migrate_cli(args; io = stdout) -> IntThe bin/vgio_migrate.jl command: opencv|matlab [options] FILE (a third-party calibration), target|rig|file [options] FILE, tree [options] DIR and repoint [options] FILE (earlier schema versions), each a dry run unless --apply. Returns the process exit code: 0 on success, 1 when the conversion failed, 2 on a usage error.
VisualGeometryToolkitIO._track_segment_trajectory_v2_to_v3 — Method
_track_segment_trajectory_v2_to_v3(tree) -> Dict{String, Any}The version step vgio/trajectory/v2 → v3 for CaliBlobs' track segment of 2026-09 (owner ruling 2026-11-11, Option A), the one v2 trajectory layout read: the track_segment_<s>.json CaliBlobs icra2026's motion-capture runs wrote — from = "track:<s>", to = "camera", each frame {t, pose}, the frames' images and the segment's component in its provenance. Any other v2 trajectory is refused (its names are free strings), as before; saving writes only the current version.
THE GAUGE. The current writer names a segment's gauge by its poses' destination frame (CaliBlobs icra2026/src/trajectory.jl:1172, gauge = _dst_frame(first(sg.poses))), which is the component's gauge board frame target:<uid> (trajectory.jl:304, G = VgtkCore.reference_frame(comp.targets)). The v2 file does not record that uid, so the gauge is named by its COMPONENT, as the same run's hand-eye record names the component's frame: target:scene_<c> (trajectory.jl:491, the hand-eye fit's marker "scene_$(s.component)"; its mount file, trajectory.jl:1123; the v2 hand-eye step reads scene_<c> the same). camera is camera_optical; each frame takes its image from the provenance; every pose as it stands. (Line numbers at CaliBlobs 72a6dba.)
VisualGeometryToolkitIO.convert_matlab_calibration — Method
convert_matlab_calibration([file_frame = PixelFrame{:julia},] path; images, image_size, file_unit = nothing,
target = "calibration_target", out = dirname(path), dry_run = false) -> NamedTupleConvert a third-party MATLAB calibration export (calibration_matlab_*.json: the radial/tangential camera fx, fy, cx, cy, r1…r3, t1, t2, or the fisheye mapping_coeffs, distortion_center, stretch_matrix; mean_error; one {rvec, tvec} per image) into the same native files as convert_opencv_calibration, which it mirrors: <stem>_cameras.json (the camera as load_matlab_calibration reads it — MATLAB's polynomial lens, or the fisheye as Scaramuzza with its stretch in K; provenance records the reprojection_error with error_statistic = "mean", MATLAB's statistic, not an rms) and <stem>_poses.json (target:<target> → view:<image> per posed image, in the export's tvec unit — the fisheye's frame twist applied, as the reader applies it). The original is never touched, and the round trip is verified before anything is written.
file_frame defaults to MATLAB's documented pixel convention, the top-left pixel's centre at (1, 1) (PixelFrame{:julia}); override it only for a calibration VERIFIED to be in another frame. file_unit is REQUIRED unless the file declares its tvec unit (the toolbox's exports do not; its tvec is in the unit the pattern was given in — millimetres for this stack's captures). MATLAB's board frame has x and y exchanged relative to OpenCV's for the same pattern, and the poses are carried in MATLAB's own board frame, unchanged: give target a name that keeps them apart from an OpenCV calibration's.
VisualGeometryToolkitIO.convert_opencv_calibration — Method
convert_opencv_calibration([file_frame = PixelFrame{:opencv},] path; images, image_size,
file_unit = nothing, target = "calibration_target",
out = dirname(path), dry_run = false) -> NamedTupleConvert a third-party OpenCV calibration export (calibration_opencv_*.json: fx, fy, cx, cy, named distortion coefficients, rms, one {rvec, tvec} per image) into native files (a vgio/cameras store, a vgio/transforms file), where everything the export leaves implicit is declared. The original is never touched. Written to out:
<stem>_cameras.json— avgio/camerasstore holding one camera named<stem>: itsimage_sizefromimage_size,Kin the canonical pixel frame, and the lens record ofopencv_lensfor the export's distortion vector (the terms its length evaluates). The export's reprojection statistic is itsprovenance(reprojection_error,error_statistic = "rms",source = "opencv",migrated_from).<stem>_poses.json— avgio/transformsfile, one record per image the solver posed, NAMED by that image:from = "target:<target>",to = "view:<image>"— the target in the camera frame of that view,x_view = R x_target + t, in the export's tvec unit (declared as itsunits.length). An image whose pose the export has asnullhas no record.
images is REQUIRED — one unique, non-empty name per entry of the export's poses, in the export's order — and replaces the positional join the export leaves to its reader. image_size (width, height) is required because a camera is not sufficient without its extent and an OpenCV export does not record it.
file_unit is the unit of tvec: taken from the file's tvec_unit (or this package's own unit) when it declares one — and then a stated file_unit must agree — and otherwise REQUIRED; there is no default.
file_frame is the pixel frame of cx, cy, and the ONLY place a pixel frame is stated by hand: by the user's rule OpenCV's own, the top-left pixel's centre at (0, 0) (PixelFrame{:opencv}). Override it only for a calibration VERIFIED to be in another frame. A type, it leads, as a type does in a non-mutating call. Everything downstream carries the frame in its type: the camera read is canonical by construction, and the files declare what their types say.
The conversion is verified before anything is written to out: the files, written to a staging directory beside out (a dry run's: a temporary one) and renamed into place only once verified, must read back equal to the OpenCV read — the camera ==, every pose's translation bit for bit (a file-born value; a computed one within the length conversion's 2 ulp or with its persisted identity) and its rotation to the quaternion encoding's precision (_qvec). With dry_run nothing is written to out. Returns (; path, cameras, poses, n_posed, n_unposed), the output paths nothing in a dry run.
VisualGeometryToolkitIO.migrate_record — Method
migrate_record(tree) -> Dict{String, Any}A parsed record (tree, an AbstractDict as JSON parsed it) of an earlier schema version as its kind's current record, in memory: each version's step, migrate_schema(::Val{schema}, tree), in turn, until no step is left for the record's schema. A current record comes back as it is (its keys Strings). VisualGeometryToolkitIO's readers call it on every file of an earlier version; the reader of a schema owner's kind calls it before it reads a file, so an old file loads as the current version. An ArgumentError for a step that does not move the version, and whatever a step refuses.
A vgio/cameras/v1 record, carried to the current version by the v1 … v5 steps:
julia> v1 = Dict("schema" => "vgio/cameras/v1", "cameras" => [Dict(
"schema" => "vgio/camera/v1", "name" => "left", "pixel_chart" => "colmap",
"size" => Dict("unit" => "px", "width" => 1280, "height" => 960),
"intrinsics" => Dict("unit" => "px", "fx" => 900.0, "fy" => 900.0,
"cx" => 640.0, "cy" => 480.0, "skew" => 0),
"lens" => Dict("model" => "KannalaBrandt", "params" => [0.1, -0.02, 0.003, -0.0004]))]);
julia> VgtkIO.migrate_record(v1)["schema"]
"vgio/cameras/v6.0"VisualGeometryToolkitIO.migrate_schema — Function
migrate_schema(::Val{schema}, tree::AbstractDict) -> AbstractDict
migrate_schema(::Val{schema}, src, dst) -> NamedTupleThe migration of a record of the (old) schema — a Symbol, Val(Symbol("vgio/rig/v5")) — in two forms.
The STEP, migrate_schema(::Val{schema}, tree): the parsed record tree (a Dict{String, Any} of that schema) as the record of the next version, its "schema" that version's. One step per version, and the one implementation of it: migrate_record runs the steps until the record is current, the readers run that on load, and the file form runs it too. A step refuses (ArgumentError) a record it cannot carry over exactly.
The FILE form, migrate_schema(::Val{schema}, src, dst): the file at src in its kind's current schema, written to dst (a path in the staging directory vgio_migrate owns). A method reads src (through the steps), writes the current file to dst through its writer, reads dst back with the current reader and compares every number with src's value (a length as its value, within the length conversion's 2-ulp guarantee or with its persisted identity), throwing an ArgumentError on any difference; it returns a summary NamedTuple with at least to, the schema written (and whatever the owner reports: a rig's or a target's old_ids and new_id).
A declared extension point (VisualGeometryToolkitIO's CONTRACT_GENERICS): the owner of a schema adds both forms for each of its old versions. VisualGeometryToolkitIO's own are listed by schema_versions: every kind's earlier versions up to its IO 0.9 one, each with one step, and IO 0.9's version of each kind with its step to the 0.10 major (migratev010.jl); a renamed or folded kind's into its successor (`genericcamera→noncentralspline→cameras;targetpoints2d,targetpoints3d,targetdetections→observations`). An old grid file is read, never rewritten: its file form writes its camera store to a new file.
VisualGeometryToolkitIO.same_value — Function
same_value(a, b; length_ulps = 2) -> BoolWhether two TYPED values are the same record: the same type at every level, compared field by field, an array element by element, a dict key by key, an Uncertain value (VisualGeometryToolkitCore's) with its covariance and a correspondence set through its endpoints and attribute columns. A LENGTH — a quantity of dimension length or length², a covariance entry whose two parameters' length powers add up to 1 or 2, a non-central model's points — is compared as its metre value within length_ulps ulp or with the same persisted identity (its metre value at 15 significant digits, the value content_id hashes), the sign of a zero kept; every other number (a rotation, a focal length, a pixel, a time, a dimensionless quantity) and every string, symbol or type must be identical (===, isequal).
The default, 2 ulp, is the decimal-exact length conversion's guarantee (read_length/write_length): a full-precision file number has no metre value that writes back to its own text, so a migration that reads an old file and the file it wrote compares within it; and a computed length no file number reads back to is written as its persisted value (IO 0.10.1), which reads back up to ~22 ulp off with the length's identity (VisualGeometryToolkitCore's conventions/units.md, "What is exact"). length_ulps = 0 is exact everywhere (the persisted identity not accepted), for a schema whose lengths read back bit for bit (a product codec's).
VisualGeometryToolkitIO.schema_versions — Method
schema_versions() -> Vector{NamedTuple}
schema_versions(kind) -> Vector{String}The schema versions VisualGeometryToolkitIO reads, DERIVED from its version steps (the migrate_schema methods of a record: every schema with a step, and each kind's current one), never kept by hand: per current kind, its earlier schemas (a former kind's among them: generic_camera and noncentral_spline for cameras; target_points2d, target_points3d, target_detections for observations) in version order, then its current one. The docs table of the versions read is generated from it. A kind that moved to its owner ("vignetting", …: VisualRadiometryToolkitIO's) is an ArgumentError naming that owner, whose own table is schema_versions(::KindSpec).
VisualGeometryToolkitIO.vgio_migrate — Method
vgio_migrate(path; out = <stem>.migrated.json beside path (an old grid file: <stem>.camera.json or <stem>.noncentral.json), dry_run = false) -> NamedTupleAn old grid file (vgio/generic_camera/v2 or v3) is never rewritten: its camera store — the vgio/cameras record of its one camera, named after the file — is written to a NEW file, by default <stem>.camera.json beside a central one, <stem>.noncentral.json beside a non-central one (an existing one refused, out == path refused).
Rewrite the file at path, of the earlier schema version it declares, in its kind's current one, by the file form of migrate_schema for that schema (every earlier version schema_versions lists that a published file holds, and any a schema owner adds), which runs the same version steps a reader runs on load: an old file need not be rewritten to be read, and this is how it is rewritten once. The migration is written through the current writer to a staging directory BESIDE out (the same filesystem), read back with the current reader and compared with the original, number for number; only then is it renamed to out, one atomic rename. Every number comes back bit for bit except a length (or a covariance entry of lengths) the file holds at full precision, 16 or 17 digits: no metre value writes back to every such number, so the migrated file may hold one that differs by at most 2 ulp — reading back as the same metre value, within the length conversion's 2-ulp guarantee (read_length) — or, for a computed value no file number reads back to, its persisted form, with the same identity (same_value). A number of at most 15 significant digits is rewritten as its own text. The original is untouched unless out == path (an in-place migration, replaced by that rename only once verified); an existing out is otherwise refused. With dry_run the migration is verified and nothing is written. Returns (; path, out, from, to, …), outnothing in a dry run, with whatever the schema's migration reports — a rig's or a target's old_ids (the identities observation files may name it by: the ones its own version minted, and IO 0.9's identity of its value) and its new_id, its identity from IO 0.10 on.
A .toml record whose schema has a step but no file form (a schema owner's TOML config) is rewritten by the generic file form: parse, migrate_record, TOML.print to the staging directory, re-parse and require the very tree back (types included: an Int stays an Int, a 1.0 a Float64, a date a Date), an ArgumentError otherwise. The rewrite drops the file's comments: the result's comments_dropped is true, and a @warn says so, when the file has any # (a comment line or a trailing comment; a # inside a string also counts, conservatively). The result is (; path, out, from, to, comments_dropped).
VisualGeometryToolkitIO.vgio_migrate_tree — Method
vgio_migrate_tree(dir; in_place = false, dry_run = false, io = stdout) -> Vector{NamedTuple}Migrate every .json file under dir of an earlier schema version whose schema has a migrate_schema file form (every vgio kind's earlier versions that a published file holds, and any schema whose owner added one), then re-point the files naming target definitions — vgio/observations (IO 0.9's target_points2d, target_points3d, target_detections among them) and vgio/target_homographies — at the current rigs and single targets of the tree, rewriting them as their kind's current version; each by the guarded pattern of vgio_migrate (a full-precision length may be rewritten within 2 ulp, or as its persisted form), with one line per file to io — a file left as it is says why (current; SKIPPED: no schema, or a schema nothing here migrates, another owner's record whose owner is not loaded among them). Written beside each original as <stem>.migrated.json, or over it with in_place; an old grid file is never rewritten, in place or not: its current record goes to a new <stem>.camera.json (central) or <stem>.noncentral.json (non-central), and a rerun finds it current.
THE RE-ID. IO 0.10 re-minted every rig's and target's content_id once (JCS over the 0.10 identity tree), and earlier versions' identities differed too (a rig v4 file's hashed its record). Each migrated rig or target file's old identities — the ones its own version minted, and IO 0.9's identity of its value — map to its new one. The map is PERSISTED in dir/vgio_migrate_ids.json ({"identities": {old: new, …}, "definitions": {new: path relative to dir, …}, "rewritten": {old path: {"path": its current file, "sha256": the old bytes'}, …}}, paths relative to dir) before a file is put in place, and read by a later run, so a run that fails after its definitions were migrated in place re-points correctly when rerun, and an observation file kept outside the tree can be re-pointed later from the map (the command's repoint); a rerun of a migrated tree is idempotent (every file current, logged so).
A calibration manifest of the tree (vgio/calibration) is migrated last: each listed file the run rewrote is bound again — its path, sha256 and schema its current file's, every derived_from naming it renamed with it — and the manifest is written as the current version and checked as load_manifest checks it before it is put in place; a current manifest none of whose files moved is left as it is.
A file the migration refuses — its migration does not read back, its <stem>.migrated.json exists and is not current, an observation file names an identity that is neither mapped nor a current definition's of the tree, or an observation does not resolve in its definitions — is logged FAILED with the reason, nothing is written for it, and the run goes on with the other files; it then ends in ONE ArgumentError listing every refusal.
VisualGeometryToolkitIO.write_staged — Method
write_staged(f, out => name, …; dry_run) -> f's resultWrite files through a staging directory, the guarded pattern of every migration: f(staged...) is called with one path per out => name (each named name, in a fresh directory BESIDE the destinations, so on their filesystem) and builds and verifies the files there; then, unless a dry_run, each is put at its out by one rename, in the order given — atomic on POSIX, so an original at out is untouched until its rename, and nothing is moved across filesystems. The destinations share one directory, created if missing (an ArgumentError otherwise, before anything is written). A dry run stages in a temporary directory and puts nothing anywhere. The staging directory goes when this returns, whatever happened. On a failure — f throws, or a rename does — the destinations are left as they were: a destination that did not exist and was already renamed into place is removed again (one that existed was replaced by its rename and stays so), and a directory this call created for them is removed.
VisualGeometryToolkitIO._v09_id — Method
_v09_id(x) -> StringThe content identity IO 0.9 minted for a rig or an unposed target (x a Rig, an AbstractTarget, an Attributed one by its target): FROZEN (see above). An observation file written before IO 0.10 names its definitions by it.
VisualGeometryToolkitIO.migrate_envelope — Method
migrate_envelope(old::AbstractDict, schema; length = get(old, "length_unit", "mm"), pixel = get(old, "pixel_frame", "colmap"),
density = "dpi") -> Dict{String, Any}The IO 0.10 envelope of a record written before IO 0.10, for a version step: old (a parsed record, string keys) with its schema set to schema (the next version's, "<owner>/<kind>/v<major>.<minor>"), its top-level declarations (length_unit, pixel_frame, rotation_encoding, transform_convention, point_index_base, time_unit) moved into the units and conventions objects, the generator this package's, every other key kept, and every stored rotation [w, x, y, z] with w < 0 written as its 0.9 reader read it, -q. length and pixel are what the record declares, or — absent — what its version meant ("mm": it held no length; "colmap": every 0.9 record without a pixel frame); density the record's print density unit ("dpi", the only one a 0.9 record meant). The steps of VisualGeometryToolkitIO's own kinds use it, and a schema's owner calls it in the step of its own kinds' 0.9 versions (a caliblobs/session record), then moves its body's own keys. A height field's IO 0.9.5 per-field units (node_unit, height_unit) become the length roles node and height.
VisualGeometryToolkitIO.renamed_key — Method
renamed_key(d::AbstractDict, from, to) -> Dict{String, Any}The record d with its key from named to (a copy with String keys; a record without the key comes back as that copy unchanged): the one move of a version step that renames a field, in this package's steps and in an owner's (migrate_schema).