API: Tuning
The cross-validation specification. The schema is described in The [tuning] schema.
Public names
VisualGeometryToolkitEval.Tuning — Module
TuningThe cross-validation (CV) specification. It holds the grid spacings and the grid constructor grid, the window rules, the persisted grid specs and their extension (extend), the objectives (TuningCriterion), the scene splits and unit samplings of a CrossValidation, the validation-budget draws (BudgetSampling), the schemes that bundle them (TuningScheme), the [tuning] TOML parser and writer (tuning_spec, tuning_table), the tuning-artifact writer and reader (save_tuning_artifact, load_tuning_artifact), the scale-prior strategies (PriorSpec) and the deployment corruption of the miscalibration protocol (corrupt_native).
Every strategy is a type whose fields are its complete parameter set, and its defaults live in configs/tuning.toml.
VisualGeometryToolkitEval.Tuning.ALL_PRIOR_SPECS — Constant
ALL_PRIOR_SPECS :: Tuple of canonical (family, fitting) specs probed + evaluated.Single source of truth for the prior specs a sweep iterates.
VisualGeometryToolkitEval.Tuning.RNG_ALGORITHMS — Constant
RNG_ALGORITHMSThe RNG algorithms a spec may name (rng = "StableRNG"): StableRNGs' StableRNG only — its streams are fixed across Julia versions, which Julia's own MersenneTwister/Xoshiro are not, so a persisted sample or stream reproduces on any Julia. (MersenneTwister and Xoshiro were accepted until tuning format v4.)
VisualGeometryToolkitEval.Tuning.SPLIT_REGISTRY — Constant
The scene-split registry of record: every scene list of the stack (configs/splits.toml, parsed at precompile).
VisualGeometryToolkitEval.Tuning.SPLIT_REGISTRY_PATH — Constant
The path of the scene-split registry of record, configs/splits.toml.
VisualGeometryToolkitEval.Tuning.TUNING_DEFAULTS — Constant
The shipped tuning defaults of record (configs/tuning.toml, parsed at precompile).
VisualGeometryToolkitEval.Tuning.TUNING_DEFAULTS_PATH — Constant
The path of the shipped tuning defaults of record, configs/tuning.toml.
VisualGeometryToolkitEval.Tuning.TUNING_TAGS — Constant
TUNING_TAGSEvery tagged strategy family of a [tuning] spec and its tag registry (VisualGeometryToolkitCore's TagRegistry: TOML tag → type, the tag snake_case of the type's name minus the family's suffix; retired tags name their successor). A tagged table names its type with the key type.
VisualGeometryToolkitEval.Tuning.BudgetSampling — Type
BudgetSampling(sizes, n_draws, seed, rng)The validation-budget draws: for each budget n ∈ sizes, n_draws simple random samples of n validation units (budget_units), draw r from budget_rng(b, n, r); the confidence interval over a budget's draws resamples from resampling_rng(b, n).
VisualGeometryToolkitEval.Tuning.CenteredWindow — Type
CenteredWindow(factor)[center / factor, center · factor] about a center the caller supplies: a transferred operating point centres on itself. TOML tag "centered".
VisualGeometryToolkitEval.Tuning.CoarseFine — Type
CoarseFine(coarse, extension, edge_margin, fine, criterion, cross_validation)The coarse-fine search of one scalar (Evaluation cvprobe.jl): the one-axis case of JointCoarseFine, its axis spelled flat — sweep the coarse axis, extend it by extension.npts points on a side whenever the argmin lies within `edgemarginpoints of that edge (at mostextension.maxroundsper side), then sweepfineover the coarse argmin's bracketing neighbours and take the free argmin.criterionaggregates a candidate's validation errors over the validation units ofcrossvalidation. TOML tag"coarse_fine"`.
VisualGeometryToolkitEval.Tuning.CoarseFineAxis — Type
CoarseFineAxis(coarse, extension, fine, expensive)One axis of a JointCoarseFine search: its coarse axis (window rule
- spacing), its expand-on-boundary rule, the
finespacing over the coarse
argmin's bracket, and whether it is expensive — a value of an expensive axis costs a run the cheap axes reuse (a detection run, say), so the search asks for the grid points one expensive value at a time. Untagged; defaults [types.coarse_fine_axis].
VisualGeometryToolkitEval.Tuning.CoverageWindow — Type
CoverageWindow(q_lo, q_hi, log_margin, zeta_octaves)The COVERAGE window of a native axis (outlier half-width, loss width): every native the efficiency-constant window can request at any reference scale the validation pool can produce, [native(lo, ŝ_min/ζ)·e^{-m}, native(hi, ŝ_max·ζ)·e^{m}] with [lo, hi] the efficiency-constant window, (ŝ_min, ŝ_max) = scale_bounds(s2, (q_lo, q_hi)), ζ = 2^zeta_octaves (the scale corruptions the run reads out at, 0 for none) and m = log_margin (log headroom so a request at the bounds sits strictly inside). TOML tag "coverage".
The name is the GUARANTEE, not the mechanism: the realized grid contains every native the window can request at any scale the pool produces, so a windowed free argmin provably cannot leave its grid. That is what the validation-budget mode needs, where 3500 draws share one sweep and each has its own ŝ(n).
q_lo == q_hi is legal and is the ONE-ANCHOR case: both sides anchor on the same √quantile(σ̂², q), and at q = 0.5 that is reference_scale(s2), so coverage { q_lo = 0.5, q_hi = 0.5, zeta_octaves = 0.0 } is the WINDOW-MATCHED grid — the native image of the efficiency-constant window and nothing more. A tune has one reference scale, so this is the tuning case; a spread band is for the modes that have many. (It replaced a separate StandardizedNativeWindow rule, which was this rule with its band collapsed and was a distinct type only because the constructor forbade q_lo == q_hi.)
VisualGeometryToolkitEval.Tuning.CrossValidation — Type
CrossValidation(scene_split::SceneSplit, validation::UnitSampling, test::UnitSampling)The data side of a tuning: the scenes it tunes on and reports on (scene_split), and the units of each side it reads (validation, test). A driver states which samplings it supports by the signature of the method it calls (say cv::CrossValidation{<:SceneSplit, StratifiedSampling}), so an unsupported spec is a MethodError. Applied by validation_units and test_units.
VisualGeometryToolkitEval.Tuning.EfficiencyConstantWindow — Type
EfficiencyConstantWindow(lo, hi)The standardized window [lo, hi] of efficiency constants (a width as a multiple of the estimated inlier scale, σ-units) of a tuning run: the dimensionless window every windowed free argmin searches, mapped to a native axis at the supplied scale (window_columns), and the window of the efficiency-constant axis itself (StandardizedWindow). It carries no grid: the grids are built by the spacings.
VisualGeometryToolkitEval.Tuning.ExhaustiveSampling — Type
ExhaustiveSampling()Every unit of every scene. TOML tag "exhaustive" (retired: "all").
VisualGeometryToolkitEval.Tuning.Factorial — Type
Factorial(axes, criterion, cross_validation)Every combination of the named axes (hand-chosen settings of a method's configuration keys), scored by criterion over the validation units of cross_validation. TOML tag "factorial".
NOT a windowed scheme: there is no reference scale and no standardized window, and nothing about it is extended on a boundary. Its consumers live outside this package: a downstream product-grid spec reads its axes through it, and a joint operating-point search is one. Deleting it on the strength of a grep over src/ and test/ alone breaks them.
VisualGeometryToolkitEval.Tuning.FiniteMedian — Type
FiniteMedian()The median over the FINITE validation errors, +Inf when there are none (so an all-failed column loses every argmin). TOML tag "finite_median".
VisualGeometryToolkitEval.Tuning.FixedWindow — Type
FixedWindow(lo, hi)A window stated in the axis's native units. TOML tag "fixed".
VisualGeometryToolkitEval.Tuning.GridExtension — Type
GridExtension(npts, max_rounds)The expand-on-boundary rule of a GRID axis: on a boundary argmin, extend the grid by npts points on the clipped side, at most max_rounds rounds (a still-clipped argmin is then recorded and refused by the readers).
VisualGeometryToolkitEval.Tuning.GridSpacing — Type
GridSpacingHow the points of a tuning grid are spaced over a window [lo, hi]: LogPerDecade, LogPerOctave, LogCount, LinearCount. grid builds the grid; extend continues a spaced grid past either end at the same step.
VisualGeometryToolkitEval.Tuning.GridSpec — Type
GridSpecThe persisted, reproducible description of one realized tuning grid: SpacedGrid (a window, a spacing and its extension) or ListedGrid (explicit values). grid(spec) realizes it.
VisualGeometryToolkitEval.Tuning.Incumbent — Type
Incumbent(values, confidence, n_resamples, seed)The setting in force before a search (values: axis name → value). The search's selection replaces it only when a paired bootstrap of the units (n_resamples draws, StableRNG(seed)) puts the selection's objective below the incumbent's with probability at least confidence. Untagged; defaults [types.incumbent].
VisualGeometryToolkitEval.Tuning.InverseGamma — Type
InverseGamma()Proper inverse-gamma prior IG(α₀, β₀); hyperparameters come from a fitting.
VisualGeometryToolkitEval.Tuning.Jeffreys — Type
Jeffreys()Improper Jeffreys prior — parameterless, equivalent to IGPrior(0, 0).
VisualGeometryToolkitEval.Tuning.JointCoarseFine — Type
JointCoarseFine(axes, edge_margin, criterion, cross_validation, incumbent = nothing)The coarse-fine search over the product of named axes (CoarseFineAxis), jointly: the coarse product grid, each axis extended on a side while the joint argmin lies within edge_margin points of that face, then the product of each axis's fine bracket about the joint argmin and its free argmin. CoarseFine is its one-axis case. An optional Incumbent is kept unless the selection beats it (Evaluation fine_search). TOML tag "joint_coarse_fine".
VisualGeometryToolkitEval.Tuning.LinearCount — Type
LinearCount(n)n ≥ 2 linearly spaced points over the window. TOML tag "linear_count".
VisualGeometryToolkitEval.Tuning.ListedAxis — Type
ListedAxis(values)An axis of hand-chosen settings (a factorial tuning's axis). TOML tag "listed".
VisualGeometryToolkitEval.Tuning.ListedGrid — Type
ListedGrid(values)A grid given by its values (finite, strictly increasing): the factorial tunings whose axes are hand-chosen settings. It has no spacing, so it cannot be extended. TOML tag "listed".
VisualGeometryToolkitEval.Tuning.LogCount — Type
LogCount(n)n ≥ 2 log-spaced points over the window (a COUNT, whatever the window's width in decades). TOML tag "log_count".
VisualGeometryToolkitEval.Tuning.LogPerDecade — Type
LogPerDecade(per_decade)Log spacing at a DENSITY: d = log10(hi / lo) decades hold d·per_decade intervals, so the grid has round(Int, d·per_decade) + 1 points (at least 2) and its log10 step is d / (n - 1) — 1 / per_decade when d·per_decade is an integer. (d·per_decade POINTS would space them coarser than advertised: the fencepost.) TOML tag "log_per_decade".
VisualGeometryToolkitEval.Tuning.LogPerOctave — Type
LogPerOctave(per_octave)Log spacing at a density per factor of two: round(Int, log2(hi / lo)·per_octave) + 1 points (at least 2) — the half-octave ladders (per_octave = 2) of the PnP and detector tunings. TOML tag "log_per_octave".
VisualGeometryToolkitEval.Tuning.MLE — Type
MLE()Closed-form MLE on the inverse-gamma family via the Gamma reparameterisation 1/X ~ Gamma(α, 1/β). Requires length(σ²s) ≥ 2.
VisualGeometryToolkitEval.Tuning.MeanAverageAccuracy — Type
MeanAverageAccuracy(max_error)The continuous mAA@max_error of the validation errors (VisualGeometryToolkitCore Synthetic.mean_average_accuracy; a non-finite error is a failure that stays in the denominator), MAXIMISED (the objective is its negative). TOML tag "mean_average_accuracy".
UNITS-NEUTRAL: max_error is in the errors' own unit — degrees on a pose error, mm for BlobBoards' bmvc2026 inter-board invariance. The one mAA criterion: a second spelling MAA(max_error_deg) carried the identical statistic under a field name that asserted degrees, which a criterion handed millimetres cannot. It is retired (2026-10-03) along with its "maa" tag; the [schemes.factorial] default that named it now names this one. The statistic itself is VisualGeometryToolkitCore's, the stack's one definition.
VisualGeometryToolkitEval.Tuning.MedianError — Type
MedianError()The median validation pose error with every failure (a non-finite error) counted as +Inf. TOML tag "median_error".
VisualGeometryToolkitEval.Tuning.PairUnit — Type
An image pair of a two-view dataset.
VisualGeometryToolkitEval.Tuning.PriorFitting — Type
PriorFittingAbstract supertype for "how do we derive (α₀, β₀) from the per-pair σ̂² data?" Concrete subtypes implement fit_prior for one or more ScalePriorFamily values.
VisualGeometryToolkitEval.Tuning.PriorSpec — Type
PriorSpec(family::ScalePriorFamily, fitting::PriorFitting)Compound spec: the prior family + the algorithm that turns σ̂² data into its parameters. The named specs are the constructor functions JeffreysPriorSpec and IGRobustSpec; the set a sweep iterates is ALL_PRIOR_SPECS.
VisualGeometryToolkitEval.Tuning.QueryUnit — Type
A query image of an absolute-pose dataset.
VisualGeometryToolkitEval.Tuning.RegisteredSceneSplit — Type
RegisteredSceneSplit(name, validation_scenes, test_scenes)A scene split registered under name in configs/splits.toml (the one file of record of every scene list). A config names it (scene_split = { type = "registered", name = "..." }); the parser fills in the lists from the registry, so the complete table — and with it the spec hash and every artifact — carries the lists the run used. Both lists are nonempty, free of duplicates and DISJOINT; they are kept sorted. TOML tag "registered".
VisualGeometryToolkitEval.Tuning.RobustFit — Type
RobustFit(alpha0 = 1.0)Robust median-based fitting of an inverse-gamma prior: β₀ = α₀ · median(σ²s) with fixed shape α₀ (default 1.0). Median is robust to heavy-tailed σ̂² distributions (HEB).
VisualGeometryToolkitEval.Tuning.SamplingUnit — Type
SamplingUnitWhat one unit of a dataset is — what a UnitSampling draws: PairUnit (an image pair of a two-view dataset) or QueryUnit (a query image of an absolute-pose dataset). A dataset declares its own with sampling_unit.
VisualGeometryToolkitEval.Tuning.ScalePriorFamily — Type
ScalePriorFamilyAbstract supertype for the scale-prior distribution family. Concrete subtypes identify the kind of prior (its parameter shape and admissible values); the values come from a PriorFitting applied to σ̂² data.
VisualGeometryToolkitEval.Tuning.SceneMeanLowerMedian — Type
SceneMeanLowerMedian()The mean over scenes of each scene's lower_median validation error (scenes without a finite median are left out; NaN when none is left). errors is one error vector per scene. TOML tag "scene_mean_lower_median".
VisualGeometryToolkitEval.Tuning.SceneMeanMedian — Type
SceneMeanMedian()The mean over scenes of each scene's median FINITE validation error (Stats scene_mean_median: scenes without a finite error are left out; NaN when none is left). errors is one error vector per scene. TOML tag "scene_mean_median".
VisualGeometryToolkitEval.Tuning.SceneSplit — Type
SceneSplitWhich scenes a cross-validation tunes on and which it reports on: RegisteredSceneSplit.
VisualGeometryToolkitEval.Tuning.SpacedAxis — Type
SpacedAxis(window::WindowRule, spacing::GridSpacing)An axis whose grid is spacing over the window window evaluates to. TOML tag "spaced".
VisualGeometryToolkitEval.Tuning.SpacedGrid — Type
SpacedGrid(lo, hi, spacing, n_lo = 0, n_hi = 0)The grid grid(lo, hi, spacing) extended by n_lo points below lo and n_hi above hi at the same step (log or linear). TOML tag "spaced".
VisualGeometryToolkitEval.Tuning.StandardizedWindow — Type
StandardizedWindow()The run's EfficiencyConstantWindow itself: the window of the dimensionless efficiency-constant axis. TOML tag "standardized".
VisualGeometryToolkitEval.Tuning.StratifiedSampling — Type
StratifiedSampling(fraction, cap_per_scene, seed, rng)A uniform random sample of each scene (the stratum) separately, so the scene mix is preserved: of a scene's n units, max(1, round(fraction·n)) drawn without replacement, then at most cap_per_scene of those (0 = no cap), returned in the scene's own order. Scene s draws from rng(stable_seed(seed, s)) — its NAME, so adding or reordering other scenes leaves its sample unchanged. TOML tag "stratified".
VisualGeometryToolkitEval.Tuning.TuningArtifact — Type
TuningArtifactA loaded tuning artifact (load_tuning_artifact): spec (the TuningSpec it ran under), hash, grid_specs and the realized grids (Dict{Symbol,…}, rebuilt from the specs), unit (the SamplingUnit its cross-validation drew), code (the code identity) and data (the run's own keys). Indexing with a string reads data: art["arms"]. format is the :tuning format the FILE was written in: an earlier one was carried over in memory by its version steps (load_tuning_artifact), and recorded_hash is the hash the file records (hash is the current table's; the two differ only for such a file).
VisualGeometryToolkitEval.Tuning.TuningAxis — Type
TuningAxisOne tuning axis of a spec: SpacedAxis (a window rule and a spacing) or ListedAxis (explicit values). grid_spec(axis; context...) realizes it as the persisted GridSpec.
VisualGeometryToolkitEval.Tuning.TuningCriterion — Type
TuningCriterionThe objective a cross-validation minimizes over the validation errors of a candidate (tune_objective(criterion, errors)); each concrete criterion is named in TOML by its tag.
VisualGeometryToolkitEval.Tuning.TuningScheme — Type
TuningSchemeA family of cross-validation, with every parameter it runs under: CoarseFine and JointCoarseFine (the one coarse-fine search of Evaluation cv_probe.jl, in one and in N dimensions), WindowedBootstrap, Factorial.
A new search backend (a surrogate model over the same axes, say) is a new TuningScheme whose search returns the record of Evaluation coarse_search / fine_search — selected, boundary_hit, evaluated — so the artifact, its gated reader and the bootstrap serve it unchanged.
VisualGeometryToolkitEval.Tuning.TuningSpec — Type
TuningSpec(name, scheme)One named cross-validation of record: the [tuning.<name>] table of a config, parsed (tuning_spec). Persisted with every artifact the run writes (save_tuning_artifact), with its tuning_hash.
VisualGeometryToolkitEval.Tuning.Unfitted — Type
Unfitted()Parameterless families take Unfitted — there's nothing to fit.
VisualGeometryToolkitEval.Tuning.UniformSampling — Type
UniformSampling(fraction, cap, seed, rng)A uniform random sample of the units of all the side's scenes POOLED: of the N units, max(1, round(fraction·N)) drawn without replacement, then at most cap of those (0 = no cap), returned in the data's order (scenes by name, each scene's units in its own order). The draw is rng(stable_seed(seed, "simple_random")) over that order — the salt keeps its historical spelling, so a sample is unchanged by the type's rename. TOML tag "uniform" (retired: "simple_random").
VisualGeometryToolkitEval.Tuning.UnitSampling — Type
UnitSamplingWhich units of a side's scenes a cross-validation reads: ExhaustiveSampling, StratifiedSampling (per scene) or UniformSampling (pooled over the scenes). Applied by sample_units.
VisualGeometryToolkitEval.Tuning.WindowExtension — Type
WindowExtension(factor, max_rounds)The expand-on-boundary rule of a WINDOW (a continuous search window, an EfficiencyConstantWindow): on a boundary argmin, extend the window by factor on the clipped side (its lo divided, its hi multiplied), at most max_rounds rounds. GridExtension's twin for a window, which has no points to add.
VisualGeometryToolkitEval.Tuning.WindowRule — Type
WindowRuleHow an axis's window (lo, hi) is found: FixedWindow, StandardizedWindow, CoverageWindow, CenteredWindow. window_bounds(rule; context...) evaluates it; each rule takes only the context it needs and refuses a missing one.
Factored, a window is STATED or PLACED, and the placed ones differ only in their ANCHOR and how their endpoints leave it:
| rule | anchor | endpoints |
|---|---|---|
FixedWindow | — | its own two native numbers |
StandardizedWindow | — | the efficiency-constant window verbatim |
CoverageWindow | (ŝ_min/ζ, ŝ_max·ζ), per side | the window through native, ± margin |
CenteredWindow | a supplied native point | ÷/× factor |
Note where ζ sits: it scales the ANCHOR, never the endpoints. A window whose anchor spreads is asserting that the scale could be anywhere in that spread — right for a ζ ladder or a budget sweep, wrong for a tune, which has one reference scale. Anchor spread is bought with the grid's resolution.
VisualGeometryToolkitEval.Tuning.WindowedBootstrap — Type
WindowedBootstrap(efficiency_constant_window, outlier_halfwidth, loss_width,
efficiency_constant, criterion, cross_validation, budget_sampling)The bootstrap tuning harness (Evaluation WindowedGridMethod): per draw of budget_sampling from the validation units of cross_validation, the free argmin of criterion over the native-grid columns inside the efficiency-constant window at the draw's reference scale. outlier_halfwidth and loss_width are the native grids, efficiency_constant the standardized display axis. TOML tag "windowed_bootstrap".
VisualGeometryToolkitEval.Tuning.IGRobustSpec — Function
Robust IG prior with shape α₀ and scale fit from median(σ̂²).
VisualGeometryToolkitEval.Tuning.JeffreysPriorSpec — Method
Improper Jeffreys prior — equivalent to PriorSpec(Jeffreys(), Unfitted()).
VisualGeometryToolkitEval.Tuning.bootstrap_argmin — Method
bootstrap_argmin(criterion::TuningCriterion, stats, rng; n_resamples) -> Vector{Int}The sampling distribution of a cross-validation's selection: stats[c] is candidate c's unit_statistics (one row per sampling unit — a frame, a pair, a scene). Each of n_resamples resamples draws the units WITH replacement (rand(rng, 1:n, n), n the number of units) and returns the candidate whose criterion objective over the resampled rows is smallest (the first such candidate on a tie). The candidates are any flat set — the cells of an N-dimensional search included; the caller maps the indices to their coordinates and reads the interval it wants (per-axis quantiles, say).
This is the bootstrap of the SELECTION over a fixed candidate set. The windowed budget bootstrap (Evaluation bootstrap_trials) differs in what it resamples — budget draws of n validation units for a tuner, each draw evaluated on the test side — and is not a special case of it.
VisualGeometryToolkitEval.Tuning.budget_rng — Method
The RNG of draw r at budget n: rng(stable_seed(seed, "budget", n, r)).
VisualGeometryToolkitEval.Tuning.budget_units — Method
budget_units(b::BudgetSampling, n_units) -> Vector{(n, r, units)}Every draw: min(n, n_units) distinct indices of 1:n_units without replacement from budget_rng(b, n, r), sorted. Callers supply the ELIGIBLE unit count and map the indices back.
VisualGeometryToolkitEval.Tuning.code_identity — Method
code_identity(code) -> Dict{String,Any}The code a tuning result came from: for this package and every module of code (the caller's packages whose code determines the result — the estimator and scorer packages it ran, say), version (the loaded package version); and the julia version with the RNG algorithms the run may draw from (rng, RNG_ALGORITHMS) — the streams are StableRNG's, but a bootstrap CI resamples from Julia's own default stream (Stats bootstrap_ci), which only the Julia version pins. The code's git state is the run's record, not this one: the code_trees (code_trees) its run records and _provenance.toml keep, the one rule a stored result is reused by.
VisualGeometryToolkitEval.Tuning.corrupt_native — Method
corrupt_native(native::Real, ζ::Real) -> Float64The deployment-corruption map (docs/src/protocol.md §3, miscalibration): a tuned-at-CALIBRATION native width (selection outlier half-width, loss width, or the oracle supplied scale a native is formed from) scaled by the deployment error ζ — the model of a mis-estimated inlier scale at deployment time. Every ζ-scaling of a calibrated native goes through this one function so the corruption sites are greppable.
PARTITION-ANCHORED quantities never go through it: a tuned efficiency constant, a seed-partition Student-t ŝ², or any quantity re-derived from the deployed data's own partition is immune to calibration error by construction — that immunity IS the claim the miscal experiment measures.
VisualGeometryToolkitEval.Tuning.extend — Method
extend(w::EfficiencyConstantWindow, sides; factor) -> EfficiencyConstantWindowThe expand-on-boundary widening of a window (WindowExtension): its lo divided by factor if :lo in sides, its hi multiplied if :hi in sides (sides ⊆ (:lo, :hi), factor > 1); the grid's twin is extend(::SpacedGrid, sides; npts).
VisualGeometryToolkitEval.Tuning.extend — Method
extend(spec::SpacedGrid, sides; npts) -> (spec′, n_lo)The expand-on-boundary extension of a grid: npts more points on each side in sides ⊆ (:lo, :hi), continuing the base step. Every point of grid(spec) reappears (to rounding) in grid(spec′) at index + n_lo, the count prepended, so already-computed columns stay valid by index (see extension_offset). A ListedGrid has no spacing to continue and refuses.
VisualGeometryToolkitEval.Tuning.extension_offset — Method
extension_offset(base::GridSpec, sup::GridSpec) -> Int | nothingThe offset n_lo ≥ 0 at which grid(base) sits inside grid(sup) when sup is base or an extension of it — same window and spacing, at least as many points on each side — else nothing. The compatibility test of a resumed checkpoint, a merged sidecar and a pinned grid: specs are compared, never realized values.
VisualGeometryToolkitEval.Tuning.family_tag — Method
family_tag(family::ScalePriorFamily) -> SymbolCompact symbol identifying the prior family. :jeffreys (parameterless) or :ig (inverse-gamma). Used in display + sidecar-key construction.
VisualGeometryToolkitEval.Tuning.fit_prior — Method
fit_prior(::InverseGamma, ::MLE, σ²s) -> IGPriorMLE of the inverse-gamma shape/scale (α, β). Distributions.jl does not implement fit_mle(InverseGamma, ·) directly, so we use the closed-form transformation
X ~ InverseGamma(α, β) ⇔ 1/X ~ Gamma(shape = α, scale = 1/β)and call fit_mle(Gamma, 1 ./ x). Returns nothing for n < 2.
VisualGeometryToolkitEval.Tuning.fit_prior — Method
fit_prior(::InverseGamma, fit::RobustFit, σ²s) -> IGPriorRobust empirical prior: fixed shape α₀ = fit.alpha0, scale β₀ = α₀ · median(σ̂²). The IG prior mean is β₀/(α₀−1); with α₀=1 the mean is undefined but the mode β₀/(α₀+1) = α₀ · median(σ̂²) / 2 anchors near the data median.
Used for HEB-like datasets where per-pair σ̂² estimates are heavy-tailed (low-n_in pairs and non-planar GT-inlier sets contaminate MLE Gamma fits). The median is unaffected by individual outlier σ̂² values, so the prior location stays stable even with single-digit val-pool sizes.
VisualGeometryToolkitEval.Tuning.fitting_tag — Method
fitting_tag(fitting::PriorFitting) -> SymbolCompact symbol identifying the fitting algorithm. :none for parameterless families, :robust for median-based, :mle for closed-form MLE.
VisualGeometryToolkitEval.Tuning.grid — Method
grid(lo, hi, spacing::GridSpacing) -> AbstractRange{Float64}
grid(spec::GridSpec) -> AbstractVector{Float64}The tuning-grid constructor: npoints(lo, hi, spacing) points of spacing over [lo, hi] — Base range(lo, hi; length) for a linear spacing, Base logrange(lo, hi, n) for a log one (both hit lo and hi exactly). The second form realizes a persisted GridSpec, its extension included.
VisualGeometryToolkitEval.Tuning.grid_spec — Method
grid_spec(axis::TuningAxis; context...) -> GridSpecThe realized, persistable grid spec of axis: the window its rule evaluates to under context (window_bounds) with its spacing, unextended; or the listed values.
VisualGeometryToolkitEval.Tuning.layer_tuning — Method
layer_tuning(lower, upper) -> Dictupper's [tuning.<name>] table layered over lower's, the way the parser layers a config over the defaults: a key of upper wins; a nested table merges key by key — unless both name a type and the types differ, when upper's table replaces lower's (a different strategy does not inherit another's parameters). The one way a paper's protocol-level tuning table and a cell's overrides are combined before tuning_spec / resolve_tuning! read them.
VisualGeometryToolkitEval.Tuning.layered_tuning_entry — Method
layered_tuning_entry(cfg, name; under = Dict(), over = Dict()) -> Dict{String,Any}
layered_tuning_entry(path::AbstractString, name; under, over) -> Dict{String,Any}The [tuning.<name>] entry of a config (a parsed TOML Dict or a file path) with a campaign's protocol layered around it, as tuning_spec reads it but before it is read: no shipped defaults filled in, no key checked beyond the entry's scheme type. under is layered beneath the entry, keeping only the keys that are TOML keys of the entry's scheme (VgtkCore.allowed_keys: a Greek field by its ASCII spelling, skipped fields left out); over is layered above it, unfiltered; an over that names another scheme type replaces the entry, and under is filtered against the new scheme. With both empty it is the entry as it is. The result is always a fresh Dict, a deep copy: editing it never edits cfg, under or over. A project that folds the layered entry into a run key, or writes it as a config of its own, reads it here.
VisualGeometryToolkitEval.Tuning.load_tuning_artifact — Method
load_tuning_artifact(path) -> TuningArtifactThe reader of a tuning artifact: refuses another format first (an ArgumentError naming the file: regenerate it by re-running its tuning), then reads the spec (complete — nothing inherited), checks its hash, and rebuilds every grid from its spec.
A format-6 file (before the efficiency-constant names) is read through its version step, in memory (VisualGeometryToolkitIO's migrate_record); the file is never rewritten. Its efficiency constants are stored as the value each arm's ctor took then: an arm's is read through its roster-declared format6_constant hook (Evaluation.tuned_width; the identity by default). format and recorded_hash of the result say which file it was.
VisualGeometryToolkitEval.Tuning.nearest_column — Method
nearest_column(grid, x) -> IntIndex of the grid column nearest x in LOG space — the deployment evaluation helper (e.g. the column of the ζ-scaled tuned native). Evaluation only; tuning is always a windowed free argmin, never nearest-column selection.
VisualGeometryToolkitEval.Tuning.npoints — Method
The number of points grid(lo, hi, s) has.
VisualGeometryToolkitEval.Tuning.prior_label — Function
prior_label(spec::PriorSpec) -> StringThe display label of a legal prior spec: "Jeffreys", "IG-Robust", "IG-MLE".
VisualGeometryToolkitEval.Tuning.read_tuning — Method
read_tuning(::Type{T}, table) -> TA persisted COMPLETE table back to its type (no defaults inherited: a missing key is an error). The reader of every spec and grid spec stored in an artifact.
VisualGeometryToolkitEval.Tuning.registered_split — Method
registered_split(name) -> RegisteredSceneSplitThe split [splits.<name>] of configs/splits.toml. An unknown name, an unknown key or a split violating RegisteredSceneSplit's invariants is an ArgumentError.
VisualGeometryToolkitEval.Tuning.resampling_rng — Method
The RNG of the resampled confidence interval over budget n's draws: rng(stable_seed(seed, "resampling", n)).
VisualGeometryToolkitEval.Tuning.resolve_tuning! — Method
resolve_tuning!(cfg) -> cfgReplace every [tuning.<name>] entry of a parsed config by its COMPLETE table (every parameter, defaults resolved — tuning_spec then tuning_table), in place. Experiments' run_key and write_run_records key and record a config resolved, so its run key and its recorded _config.toml cover every tuning parameter, including the ones it inherits from this package's defaults.
VisualGeometryToolkitEval.Tuning.sample_units — Method
sample_units(sampling::UnitSampling, units_by_scene) -> Dict{String,Vector}The units sampling keeps of each scene of units_by_scene (an AbstractDict scene name ⇒ that scene's units, in the data's order): a Dict with every scene of the input, each holding its kept units in their original order (possibly none, for a pooled sample).
VisualGeometryToolkitEval.Tuning.sampling_unit — Function
sampling_unit(::Type{D}) -> SamplingUnitThe unit a cross-validation samples from a dataset of type D (its SamplingUnit). A property of the data: every dataset type defines its own method, and there is no fallback.
VisualGeometryToolkitEval.Tuning.save_tuning_artifact — Method
save_tuning_artifact(path, spec::TuningSpec; grids, unit, code, data...) -> pathThe writer of a tuning artifact: the spec (complete table — its cross-validation's scene lists included — name, hash), the grids (Dict{Symbol,<:GridSpec}, one per axis the run tuned on), the sampling unit its cross-validation drew (the data's sampling_unit), the code_identity of code (the caller's modules whose code determines the result; this package is always recorded) and the run's data (keyword values: arms, tuned indices, validation matrices, …), stamped with the :tuning format.
VisualGeometryToolkitEval.Tuning.stats_objective — Function
stats_objective(criterion, stats) -> RealThe criterion's objective (minimised) over unit_statistics rows.
VisualGeometryToolkitEval.Tuning.test_scenes — Method
The test scenes of a cross-validation (sorted).
VisualGeometryToolkitEval.Tuning.test_units — Method
test_units(cv::CrossValidation, units_by_scene) -> Vector{Pair{String,Vector}}The units an evaluation reads: the test scenes of cv.scene_split (sorted) ⇒ the units cv.test keeps of each (see validation_units).
VisualGeometryToolkitEval.Tuning.tune_objective — Method
tune_objective(criterion::TuningCriterion, errors) -> RealThe value a cross-validation MINIMIZES for one candidate: criterion applied to its validation errors (one vector per scene for a per-scene criterion).
VisualGeometryToolkitEval.Tuning.tuning_criterion_label — Method
tuning_criterion_label(criterion) -> StringThe display label of a criterion, as persisted in result rows.
VisualGeometryToolkitEval.Tuning.tuning_hash — Method
tuning_hash(spec) -> StringThe identity of a tuning protocol: the SHA-256 (hex, first 16) of its complete scheme table's canonical JSON (_content_key). Two specs with equal parameters hash equal whatever their names or how their configs spelled them; any parameter change moves it.
VisualGeometryToolkitEval.Tuning.tuning_spec — Method
tuning_spec(cfg, name; under = Dict(), over = Dict()) -> TuningSpec
tuning_spec(path::AbstractString, name; under, over) -> TuningSpecThe [tuning.<name>] entry of a config (a parsed TOML Dict or a file path), its absent keys inherited from the shipped defaults (configs/tuning.toml of this package). The entry must name its scheme (type); unknown keys and tags are an ArgumentError naming the key path.
under and over layer a campaign's protocol around the entry (layer_tuning): under (a protocol-level table of parameters shared by every entry, such as a cross_validation) is layered beneath the entry, keeping only the keys that are fields of the entry's scheme, so one table serves entries of different schemes; over (a cell's overrides) is layered above it, unfiltered. An over that names another scheme type replaces the entry, as layer_tuning replaces a nested table: the new scheme keeps none of the entry's keys (not even those both schemes have, such as cross_validation or criterion), and under is filtered against the new scheme's fields. With both empty (the default) the entry is read as it is. The layered entry itself, before it is read, is layered_tuning_entry.
VisualGeometryToolkitEval.Tuning.tuning_specs — Method
tuning_specs(cfg) -> Dict{String,TuningSpec}Every [tuning.<name>] entry of a config, parsed (tuning_spec).
VisualGeometryToolkitEval.Tuning.tuning_table — Method
tuning_table(x) -> Dict{String,Any}The COMPLETE TOML table of a tuning strategy, scheme, grid spec or TuningSpec (whose table is its scheme's): every field under its own name (VisualGeometryToolkitCore toml_key), a tagged type's tag under type. Reading it back (tuning_spec, read_tuning) gives an == value.
VisualGeometryToolkitEval.Tuning.tuning_toml — Method
tuning_toml(specs::TuningSpec...) -> Dict{String,Any}The [tuning] table holding specs under their names (write_toml-ready).
VisualGeometryToolkitEval.Tuning.unit_statistics — Method
unit_statistics(criterion::TuningCriterion, errors::AbstractMatrix) -> Matrix{Float64}What the bootstrap of a selection needs of one candidate's validation errors (a units × items matrix, one row per sampling unit): one row per unit, from which the criterion's objective over ANY multiset of units is exact (bootstrap_argmin). For MeanAverageAccuracy — a mean of per-item scores — the row is the unit's score sum and item count (VisualGeometryToolkitCore maa_score), two numbers in place of items; for any other criterion it is the errors themselves.
VisualGeometryToolkitEval.Tuning.validation_scenes — Method
The validation scenes of a cross-validation (sorted).
VisualGeometryToolkitEval.Tuning.validation_units — Method
validation_units(cv::CrossValidation, units_by_scene) -> Vector{Pair{String,Vector}}The units a tuning reads: the validation scenes of cv.scene_split (sorted) ⇒ the units cv.validation keeps of each. units_by_scene maps scene names to their units in the data's order and must hold every validation scene (other scenes are ignored).
VisualGeometryToolkitEval.Tuning.window_bounds — Method
window_bounds(rule::WindowRule; efficiency_constant_window = nothing, native = nothing,
s2 = nothing, center = nothing) -> (lo, hi)Evaluate a window rule. efficiency_constant_window is the run's EfficiencyConstantWindow, native(efficiency_constant, scale) the axis's native map (the caller's native_map(axis; d_g)), s2 the validation pool's per-pair σ̂², center the axis's centre; a rule refuses a context it needs and is not given.
Internals
These names are not public; they are listed for contributors.