API: the top module

The driver command line, the artifact formats and the path of the defaults of record.

Public names

VisualGeometryToolkitEval.ARTIFACT_FORMATS — Constant
ARTIFACT_FORMATS

The format version this package writes and reads, per artifact kind (:pool, :pool_residuals, :pool_samples, :pnp_pool, :tuning), with the change the version introduced and the remedy for an older file. A kind that reads an earlier version through its version steps names the oldest it reads, read_from, and what that version introduced (read_from_change, quoted when an even older file is refused). The file key is "<kind>_format"; an absent key is version 1.

source
VisualGeometryToolkitEval.catalog_results_mount — Method
catalog_results_mount(catalog) -> Union{Nothing, Function}

The results_mount of tier_data_root: each tier the project's data catalog catalog (configs/data_artifacts.toml) lists with mount = "results" (a run of record published as a tier) mounts at its entry's mount_dir under the results root ("" without one); nothing for any other tier, and without a catalog.

source
VisualGeometryToolkitEval.catalog_view_mount — Method
catalog_view_mount(data_root, catalog) -> Union{Nothing, Function}

The view_mount of tier_data_root for a data root read without the package (the runner): when data_root is an artifact view (its marker file), each tier the project's data catalog catalog (configs/data_artifacts.toml) lists mounts at its entry's mount_dir ("" without one); nothing when the root is no view or there is no catalog. A project builds its view from the same catalog (DataArtifacts.catalog_view), so the runner and the drivers resolve a view tier to the same directory.

source
VisualGeometryToolkitEval.cli_option — Method
cli_option(args, key[, default])

The string value of --key=value in args. With default, the default when the option is absent; without it, the option is REQUIRED and its absence throws.

source
VisualGeometryToolkitEval.code_tree_changes — Method
code_tree_changes(recorded, current) -> Vector{String}

THE reuse rule of a stored result, for every project: the result stands for the current code only when this is empty. recorded is the code trees stored with the result (nothing when it has none: a result from before code identity was kept, which is computed once more and then records them), current the code's now (code_trees's trees). Each entry names what changed: "VisualGeometryToolkitCore: src 3fa29c01e2 → b71d0e44a9", "src: 18c2… → 9e0a…", "<name>: new" (loaded now, not then), "<name>: no longer loaded".

A result recorded with uncommitted code (a scratch run's: a tree marked +uncommitted, "uncommitted", or in no git checkout) is never reused, even for the same marked trees: the mark names HEAD, not the edits, so two runs under different uncommitted edits carry the same value. Each such tree is a change, "<name>: uncommitted when recorded".

source
VisualGeometryToolkitEval.code_trees — Method
code_trees(workdir; code = nothing, julia_project = workdir) -> (; trees, dirty, project_paths)

The code identity of a run in the git checkout workdir: trees, by name, the git tree hash of each of the project's code paths (relative to workdir: git rev-parse HEAD:<path>; by default src when there is one) and of every stack package julia_project's environment loads (its [deps] and what they reach in its Manifest, found in it or above it, a workspace's): a package loaded from a path ([sources], Pkg.develop) by the trees of its src, ext and Project.toml in its own repository ("src:<tree> ext:<tree> Project.toml:<blob>"), a released stack package by its Manifest git-tree-sha1. dirty names each of them whose files differ from HEAD (an edit, a staged or deleted file, an untracked one), or that is in no git checkout: a run of record refuses to run with it (refuse_uncommitted_code). Such a tree's value carries +uncommitted (or is "uncommitted"), so a result recorded with it is never reused (the mark names HEAD, not the edits). project_paths lists the project's own paths recorded (none: nothing identifies the project's code).

A workdir that is a REGISTERED install (a package's source in a depot, no git checkout: a registered package's example run with gitpath = pkgdir(Pkg)) is committed code, content-addressed and immutable: it is identified, by its name, by the tree hash the active environment records for it ("<git-tree-sha1> <name> <version> <uuid>", from Pkg.dependencies()), and the environment searched for stack packages is the active project's. Only a git checkout with uncommitted changes, or a path that is neither, is refused.

A tree moves only when a file under it changes: a commit that touches only docs, tests or the paper changes no tree. Compare two records with code_tree_changes.

The answer is kept in this process (git runs several times per path), and given again while nothing git reads has changed: every file under the code paths and under each path-loaded package's src, ext and Project.toml (by path, size, modification and change time and inode: an edit, a new, deleted or replaced file), the project's Project.toml and Manifest, and per repository its HEAD, the ref HEAD names, packed-refs, the index and the ignore files (a commit, a checkout, a staged or unstaged change). A file rewritten within the file system's time resolution with the same size and inode keeps the kept answer, as file_sha256's cache does; so does a change to the index alone made while code_trees runs git (whose own status run rewrites the index).

source
VisualGeometryToolkitEval.digest_cache_dir — Function
digest_cache_dir(env = ENV) -> Union{String, Nothing}

The directory of the digest cache, where file_sha256 keeps a large file's hash across processes: VGTK_DIGEST_CACHE in env (an absolute path; off, 0, false or no for none: every process hashes every input in full), else $XDG_CACHE_HOME/vgtk/input-digests, else ~/.cache/vgtk/input-digests. A site sets it in its profile's [env] (VGTK_DIGEST_CACHE = "…"), which the runner's input check and every stage get. The cache is per user: whoever can write it can make a changed input match its pin, so it is created private (0700), an entry another user owns is ignored, and it is never inside a data tree (data may be read-only). A home on network storage serves every node.

source
VisualGeometryToolkitEval.engine_fixtures — Function
engine_fixtures() -> Module

The evaluation engine's shared test fixtures, the module EngineFixtures of the Test extension (using Test loads it): epair (THE synthetic E pool pair, EPAIR_GT_VARIANCE), starts_pool, subpair (a pair restricted to some of its stored models), engine_scene (a scene of the selection stream), roster_tuning and write_roster_sidecar (the tuning record the roster readers are tested on). This package's engine tests and the paper projects' engine-integration tests build their fixtures from it.

source
VisualGeometryToolkitEval.file_sha256 — Method
file_sha256(path) -> String

The SHA-256 (64 hex digits) of the file at path, read in blocks (a file of any size costs its read, never its size in memory) and kept by its real path and stat (size, mtime, ctime, inode): in this process, so a second call on an unchanged file costs a stat; and, for a file of 64 MiB or more, across processes in the digest cache (digest_cache_dir), so the many jobs of a launch read a large input once. A cache entry is a small file per path, written to a temporary file and renamed (processes that hash the same file at once each read a whole entry, and agree); an entry whose stat differs is rehashed and rewritten, and a cache that cannot be read or written is no cache. A file changed within the last 3 s is not kept (on a file system whose times have a resolution of seconds, a same-size rewrite in the same tick would keep its stat); within one process, a file rewritten in place within that resolution with the same size and inode keeps its hash. A check of record that must exclude even that sets VGTK_DIGEST_CACHE=off and runs in a fresh process. An ArgumentError for a directory or a missing path.

source
VisualGeometryToolkitEval.inspect_input — Method
inspect_input(id, table, root; root_source = "data root", root_name = "", allow_scratch = false)
    -> (; state, path, problem)

THE check of one [inputs.<id>] table under its tier's root (tier_data_root), for the runner's missing_inputs and a driver's verify_inputs alike. state is :present; :root_missing (a tier root other than the data root, named by root_name, that is not there); :missing (no path under root); or :refused (another content than its sha256 — a file's file_sha256, a directory's tree_sha256 with the table's sha256_exclude globs — or a scratch run's output, scratch_record, unless allow_scratch). problem says what, without the input's id. A sha256 that is no 64 hex digits, or a sha256_exclude on a file, is an ArgumentError (a config error).

source
VisualGeometryToolkitEval.product_input — Method
product_input(id, t; env = ENV, prefix = "VGTK_RESULTS_ROOT", site_results = project -> nothing,
              tier_root = () -> "", allow_scratch = false) -> (; state, path, problem, root, source, rel)

The one check of a product input [inputs.<id>] (project, product, key, … : product_input_path), the runner's missing_inputs and Experiments' input_path alike. Its candidate roots, in order: the environment's <prefix>_<PROJECT> (tier_variable; VGTK_RESULTS_ROOT_BMVC2026), site_results(project) (the active site profile's results_root for that project; nothing without one), and tier_root() (the consuming project's results-mount tier that publishes the producer's results, when the input names one; resolved only when the others do not hold it). The first that holds the product is checked by inspect_input (its sha256, never a scratch run's output) and its record's run_key must be key; state = :missing when none holds it, naming every candidate. rel is product_input_path(t).

source
VisualGeometryToolkitEval.product_input_path — Method
product_input_path(t) -> String

Where a product input lives under its project's results root: <product>/<key>[/<file>] (the producing project's Product directory, <experiment>/<name>/<run key>, and a file in it), checked for its keys: project (the producing project's name), product (<experiment>/<name>, relative segments), key (the run key of record) and optionally file, sha256, sha256_exclude and tier (a results-mount tier of the consuming project's catalog that publishes the producer's results: the fresh-machine form). Anything else, or a path, is an ArgumentError.

source
VisualGeometryToolkitEval.refuse_uncommitted_code — Method
refuse_uncommitted_code(identity; what = "a run of record") -> nothing

The refusal of a run of record whose code is not committed, the same for the runner and a driver's records: identity is code_trees's result. An ArgumentError when any of its trees has uncommitted changes, or is in no git checkout (its results could not name the code they ran), or when it identifies none of the project's own code (no src, no code path).

source
VisualGeometryToolkitEval.scratch_record — Method
scratch_record(path) -> Bool

Whether path (a run directory, or anything at any depth inside one: run/sub/x.csv) is the output of a scratch run: the nearest _provenance.toml at or above it, the record of the run it belongs to, says scratch = true (Experiments.scratch_run). A scratch output is never an input of record, an upstream run of record, or a promoted run. A path under no record is no scratch output.

source
VisualGeometryToolkitEval.start_output_flush! — Method
start_output_flush!(; interval = 2) -> Timer

Flush stdout and stderr every interval seconds for the rest of the session (idempotent: a second call returns the running timer). The one flusher of every driver, GPU drivers included — it installs no logger type.

source
VisualGeometryToolkitEval.tier_data_root — Method
tier_data_root(tier, data_root; env = ENV, tiers = nothing, workdir = "", prefix = "VGTK_DATA_ROOT",
               view_mount = nothing, results_mount = nothing, results_root = "", write = false) -> (root, source)

THE root of an input tier: the one resolver of every tier lookup, read and write — the runner's missing_inputs, and Experiments.data_root(; tier), input_path, verify_inputs, promote_run and tier_path. In order:

  1. the environment's tier_variable(tier) (source = "env");
  2. the machine's table tiers (a stage graph's [sites.<site>.tiers]: tier = "<root>", a relative root relative to workdir; source = "site");
  3. a tier the project's catalog mounts under its RESULTS (mount = "results": a run of record published as a tier, which DataArtifacts' fetch_artifacts! links into the results root) — results_mount(tier) returns its mount_dir ("" the top), nothing for another tier (catalog_results_mount) — <results_root>/<mount> (source = "results"; results_root a path, or a function read only here);
  4. when data_root is an artifact view that publishes the tier — view_mount(tier) returns where the view mounts it ("" its top), nothing for a tier it does not publish — <data_root>/<mount> (source = "view"). The mount applies only there: never to a data root set by VGTK_DATA_ROOT, an author's own data/exp_raw or a fallback;
  5. the one data_root (source = "data root").

An [inputs.<id>] path is relative to its tier's root, so a config names no machine path whichever disk a tier lives on. With write = true (a producer's root) a view tier is refused: an artifact view is read-only, and a producer never installs one; it binds the tier's root (the environment or the site table) to produce it.

source
VisualGeometryToolkitEval.tier_variable — Method
tier_variable(tier; prefix = "VGTK_DATA_ROOT") -> String

The environment variable that gives the root of the input tier tier: <prefix>_<TIER>, the tier upper-cased with every character other than a letter or a digit made _ (blobcalib_202609 → VGTK_DATA_ROOT_BLOBCALIB_202609).

source
VisualGeometryToolkitEval.tree_sha256 — Method
tree_sha256(dir; exclude = String[]) -> String

THE content digest of a directory, for an input that is one: the SHA-256 of the lines <relative path> <file sha256>, one per regular file under dir (links followed to their files, not into linked directories), sorted by relative path (/-separated); a path holding a tab or a newline is refused. A relative path matching a glob of exclude (* within a segment, ** across, **/ any directories including none, ?) is left out, so a declared scratch file (a log, an index the reader rebuilds) does not move it. Empty directories do not count. Each file's hash is file_sha256's: streamed, and cached by path and stat, in the process and (a large file) in the digest cache, so a second digest of an unchanged tree costs a stat per file, and a changed file is the only one read again.

source

Internals

These names are not public; they are listed for contributors.

VisualGeometryToolkitEval._check_artifact_format — Method
_check_artifact_format(path, kind) -> Int

Refuse path unless it declares a kind format this package reads (ARTIFACT_FORMATS: the current one, or one from the kind's read_from on, which its reader carries over through its version steps): an ArgumentError naming the file. Returns the format the file declares. Every reader of a kind artifact calls this before reading anything else.

source
VisualGeometryToolkitEval._content_key — Method
_content_key(tree) -> String

The content key of the evaluation stack: the SHA-256 (hex, first 16) of tree's canonical JSON (VisualGeometryToolkitCore's canonical_json, the stack's one canonical encoding; tree a TOML config's tree: nothing, Bool, integers, Float64, strings, vectors and string-keyed dicts). Key order does not move it, nor a number's spelling: an integral float is the integer (3 and 3.0 key alike, as do 1.0 and 1e0), and an integer of any type is its value (TOML's hex 0x0b10b5eed, an unsigned integer, keys as 2970312429). An integer past ±2^53 (not exactly a double: Core's bound) is an ArgumentError naming its key path (arm.seeds[2]). Fixed across Julia versions (unlike Base.hash). Behind Experiments run_key, Tuning tuning_hash and the runner's stage key.

source
VisualGeometryToolkitEval._save_artifact — Method
_save_artifact(path, kind; keys...) -> path

The writer of a kind artifact: keys to path (JLD2), stamped <kind>_format at the current version. A key named like the stamp is refused.

source
VisualGeometryToolkitEval.scratch_run — Function
scratch_run(env = ENV) -> Bool

Whether this process runs scratch work rather than runs of record: VGTK_SCRATCH=1 in the environment (env: the runner gives its launch's environment). A run of record (the default) refuses to record a result of uncommitted code (refuse_uncommitted_code, the runner's refusal); a scratch run records it with a warning, its trees marked +uncommitted, so it is never reused (the mark names HEAD, not the edits).

A scratch run is kept apart from the runs of record: its record says scratch = true (write_provenance, produce); its keys fold scratch (run_key), so it never shares a step's directory with a run of record; and its output is refused as an input of record (verify_inputs, input_path, missing_inputs), an upstream run of record (run_key's upstream), an input of a run of record (write_provenance's inputs) and a promoted run (promote_run).

source