This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
VisualGeometryToolkitIO: serialization for transforms and cameras across the
VisualGeometry stack: a COLMAP model reader/writer and the self-describing
vgio/<kind>/v<major>.<minor> JSON kinds (one envelope: generator, one
units object, one conventions object), with a unit-contract boundary and
quaternion rotations.
ReTestItems: Pkg.test() runs every item; Pkg.test(; test_args = ["migrate|v1"]) filters items by name; RETESTITEMS_NWORKERS=0 runs serially
for debugging. Check the reported total.
Every earlier schema version a published file holds is READ; only the current version is written (the one rule for an earlier version a writer still emits is below). Reason: a schema change must never force the published data (Zenodo, Hugging Face; multi-GB archives at ~100 KB/s) to be uploaded again, so a published file keeps loading forever.
- Each old version has ONE step,
migrate_schema(::Val{schema}, tree)(a parsed record → the next version's record), insrc/migrate.jl(the IO 0.10 steps insrc/migrate_v010.jl). The versions read are derived from the steps (schema_versions()); no list is kept by hand. The readers run the steps on load (_read_store→migrate_record), silently (an@debugnames the version);vgio_migraterewrites a file with the same steps (the file formmigrate_schema(::Val{schema}, src, dst)). - A minor version adds optional keys only (a reader reads any minor of its major); a renamed, removed or re-meant key is a major version.
- A schema change adds a step for the version it replaces (and its file
form, and a fixture under
test/fixtures/old/or built inschema_versions_tests.jl). Never delete a step whose version a published file holds, and never make a writer write an old version — with ONE rule for a kind whose new major version only ADDS a form (owner ruling (a), IO 0.10.2): its writer may write the earlier version for a record that version can hold, the earlier version's very bytes, so a reader of that version keeps reading every such file. The choice dispatches on what the record holds (sensor_characterisation: v2.0 iff an entry's black is aDarks, else v1.0;_written_version), and the versions a writer can emit are ONE table,_written_versions(kind)(validate.jl), which the writer's_write_kind(...; version)checks and the JSON Schema generator publishes (one schema per written version, none other: json_schema_tests.jl). Such an earlier version keeps its read step but needs no file form: it is still written, so no file of it needs rewriting. - A version no published file holds, and one that lacks what the current record needs (transforms v1's free-form frame names), keeps a refusal by name. Transforms and trajectory v2 have a version step for the one layout a published file holds (the 2026-09 hand-eye record, CaliBlobs' 2026-09 track segment); any other v2 layout is refused in that step.
- A schema owner (BlobBoards' boards) adds its own steps and calls
migrate_recordin its reader.
A kind whose type another package owns is NOT written here. Its owner states
it with the public hook in src/kind_spec.jl — a KindSpec (its schema
string and its body's table, built from the *_spec combinators and
body_spec(T)), write_kind and read_kind (the two file boundaries), its
version steps as methods of migrate_schema — and adds its load/save
methods to this package's two verbs.
Moved in IO 0.11.0, each keeping its schema name: vgio/vignetting,
vgio/environment_light and vgio/radial_profile are
VisualRadiometryToolkitIO's (their types are VisualRadiometryToolkitCore's);
vgio/panorama is PanoramaStitching's. A file or name of one is refused here
by name with its owner (_MOVED_KINDS in src/validate.jl; save_panorama
and load_panorama in src/retired.jl, listed in MOVED_NAMES). Do not add
a table, a reader or a schema for them back, and do not make this package
depend on their owners.
- NEVER add "Co-Authored-By: Claude" or similar AI attribution to commit messages
- NEVER add "🤖 Generated with Claude Code" or similar footers
- Write clean, concise commit messages focused on the change itself
The conventions every stack package follows — naming and the estimator verbs,
signatures, data arguments, coordinate frames and normalization ("frame in =
frame out"), pixel origins, bearings, Jacobians, units and the stack
contracts — live ONCE, in VisualGeometryToolkitCore's conventions/ folder
(conventions/README.md indexes it). Read them before changing code here.
This file carries no copy of them, only how they land in this package. Where
the folder is:
- in a checkout of the stack's monorepo:
../VisualGeometryToolkitCore/conventions/(the root CLAUDE.md imports it); - in VisualGeometryToolkitCore's own repository:
conventions/; - from Julia, the installed copy:
VisualGeometryToolkitCore.conventions_dir(), i.e.joinpath(pkgdir(VisualGeometryToolkitCore), "conventions").
The agent-docs test checks that this file points there and holds no copy.
The rule is the stack's (conventions/frames.md); how it lands here:
Persisted labels (pixel frame, length unit, pose from/to) are DERIVED FROM
THE DATA'S TYPES: the writer writes the type's frame and never converts. Readers
return typed frames (VGC's TargetObservations{F}, labelled
EuclideanMaps); moving the numbers is convert_frame, explicitly. Third-party
readers state the file's convention (file_frame, file_unit). Nothing here
normalizes.