Pipeline and options

The refinement pipeline of bin/refine.jl: the sessions in, the options from TOML, the stages, the records out.

Loading

RadiometricCamera.GEOMETRY_IMAGES — Constant

The geometry images, the one vocabulary of every geometry stage's image key (the chrome detect, the front ends' decode, the image-region measurement; owner 2026-11-16: ONE geometric image for every detector): "raw_green" a RAW photograph's VisualGeometryToolkitFeatures bilinear green on the raw grid (raw_green_image: full resolution, the raw's COLMAP pixels, no map), "luma" a decoded image read as grey (its own pixels). The half-resolution green cells are no geometry image.

source
RadiometricCamera.PhotoSet — Type
PhotoSet

The photographs of one calibration or prediction, read under ONE ObservationModel (photo_set): the model, the files and each photograph's Core SensorModel (models[k], resolved by its EXIF from the sensor record; the absent model without one). observe reads photograph k into its observations.

source
RadiometricCamera.check_geometry_image — Method
check_geometry_image(t, where) -> String

The image key of the table t (a geometry stage's), REQUIRED (no default: every config of record states its image) and one of GEOMETRY_IMAGES; an ArgumentError naming where otherwise ("green_cells" by name: retired for geometry).

source
RadiometricCamera.is_png_file — Method

Whether path is a PNG image (its extension .png, case-insensitively; never a macOS sidecar, _listable): THE test of every PNG listing.

source
RadiometricCamera.is_raw_file — Method

Whether path is a RAW file (its extension one of RAW_EXTENSIONS, compared case-insensitively; never a macOS sidecar, _listable): THE test of every RAW lookup.

source
RadiometricCamera.load_photo — Method
load_photo(path; linearize = false) -> RawMosaic | AbstractArray

THE loader of a photograph, decided by the file (is_raw_file), never by a flag: a RAW file is Core's RawMosaic through Features' load_raw_mosaic (the one RAW path), a decoded image its linear array (Features' load_linear_image; linearize decodes sRGB). A RAW photograph is linear: linearize with one is an ArgumentError. What a photograph contributes is then decided by its TYPE (the observation model, observe).

source
RadiometricCamera.load_session — Method
load_session(records, image_dir; component = 1, lens = :camera, grid_size = (65, 50), focus_init = :thin_lens,
             image_distance = nothing, downsample = 8, texture_downsample = 8, sensor_width = 7mm, r₀ = 1.7e-3, linearize = true,
             focus_grid = 5, load_targets = true, raw_dir = nothing, lens_identity = nothing)

Board, camera parts and initial poses of a calibration session stored as VisualGeometryToolkitIO records (records: CaliBlobs' save_calibration, or its one-time migration of a BlobBoards session export, scripts/migrate_rc_session.jl):

  • the camera: load(BoundedCamera, camera.json) — K in COLMAP pixels, the image extent, e.g. BlobBoards' division camera — bounded by its Sensor (sensor_width over the record's extent) and moved to the scene's pixels when the photographs are box-averaged by downsample (K re-expressed under the box downsample: Core's Cameras.reframed_calibration by the similarity x ↦ x / f): lens = :camera that pixel camera, :grid the generic grid model of grid_size sampled from it (grid_model);
  • the board: the target of component component, load(Rig, targets_<component>.json) — Core's planar target with its Canvas and the CanvasTexture of the printed image, whose file (textures/<id>.png, beside the records) is read by Features' load_linear_image and box-averaged by texture_downsample — as the TexturedTarget of the scene, whose world frame is the target's (metres);
  • the poses: the frames of trajectory_<component>.json (load(Trajectory, …): target → camera per frame, the frames' image names), each photograph's camera → world pose (poses) its inverse (lengths in metres through FlexUnits);
  • the focus surface: focus_init = :board_center (the board centre is in focus: its mean axial distance d_c, the lens equation's image distance d_s = f·d_c/(d_c − f), the start plane t̂ᵢ = cos αᵢ/d_c), :thin_lens (thin_lens_focus_distance; t̂ ≡ 0 when it is Inf), :board (the mean principal-ray distance to the board plane) or a number (metres); image_distance overrides d_s (nothing: from focus_init, :board the conjugate of the board distance, or a number);
  • the targets: the photographs image_dir/<image> in frame order (sRGB-decoded when linearize, box-averaged by downsample); with load_targets = false only the first is read, for the image size;
  • the capture's camera settings (settings): with raw_dir, each frame's RAW file (raw_file: the image's stem, a RAW extension) read by Features' load_raw_metadata (the EXIF alone) into Features' extract_capture_settings — Core's CaptureSettings, frame index → exposure and lens settings, with the body and the lens (lens_identity where the caller states it: an adapted lens EXIF misnames); nothing without raw_dir. Reading the RAW files is Features' decoder (its LibRaw extension, loaded with this package).
source
RadiometricCamera.observe — Method
observe(set::PhotoSet, k, mask; name = basename(set.files[k])) -> (values, mask)

Photograph k of set (photo_set) under the compute mask, read once (load_photo) under its model:

  • RAW photosites: the photosites of the observation model's channel on the raw grid — the mask restricted to the usable photosites of that colour filter (photosite_mask: uncensored at the ADC floor and the white level) that its sensor model does not list as defects (Core's defect mask: masked, never interpolated); the values its linear view under the model (Core's linearview: the model's black subtracted — the file's, a measured channel black or a dark frame's per photosite). Under a noise with a variance law (a gain: PoissonGaussian, or a RelativeNoise) Core's uncertain image, each value with its variance, whose rows are then whitened (masked_observations); plain values otherwise. A mosaic whose size is not the mask's (the camera's sensor) is refused;
  • decoded images: the image itself (sRGB-decoded when the model's Decoded states it) under the mask; an image whose size is not the mask's is refused.
source
RadiometricCamera.photo_file — Method
photo_file(dir, name) -> path

The file of the photograph name in dir, decided by the file, never by a flag (owner ruling 2026-11-13): its RAW file — name's stem with a RAW extension (is_raw_file) — when dir holds one, else name itself, a decoded image. Both, neither, or more than one RAW file is an ArgumentError naming them: the choice is never guessed.

source
RadiometricCamera.photo_files — Method
photo_files(dir; join = false) -> Vector{String}

The photographs of the directory dir, sorted: its RAW (is_raw_file) and PNG (is_png_file) files, never a macOS sidecar; their paths with join = true (as readdir). THE listing of every photograph set RC and its paper project read.

source
RadiometricCamera.photo_set — Method
photo_set(camera::CalibratedCamera, files; characterisation = nothing, lens = nothing, sensor_model = AutoSensorModel()) -> PhotoSet
photo_set(observation::ObservationModel, files; characterisation = nothing, lens = nothing) -> PhotoSet

THE entry point of photographs (owner 2026-11-15: "if a sensor was estimated with a model, then it must be used to predict the model"): the photographs files read exactly as the camera's — or the calibration's — observation model states, by dispatch on its types, never by a flag. characterisation is a LOCATION only (a path of the vgio/sensor_characterisation record); what it must be is the camera's statement. lens: the lens the config states (an adapted lens EXIF misnames; Features' extract_capture_settings). A camera's prediction reads them under sensor_model (prediction_observation: "off" reads RAW photosites without the record, with the loud warning).

  • SensorRecord, Photosites: RAW photographs only; characterisation required and its file's sha256 equal to the record's — another file is refused naming both. Each photograph's model is Core's resolver sensor_model(characterisation, capture, k) by its EXIF; a frame the record does not describe (another body, OtherBody; an ISO it holds no entry for, UnmatchedISO) is refused by name.
  • NoSensorRecord, Photosites: RAW photographs only, each under the file's black (Core's resolver without a characterisation, reason NoCharacterisation); a characterisation is refused: the camera was calibrated without one.
  • NoSensorRecord, Decoded: decoded images only, the absent model each; a RAW photograph is refused, so is a characterisation.
source
RadiometricCamera.photosite_mask — Method
photosite_mask(m::RawMosaic, channel::Symbol) -> BitMatrix

The usable photosites of ONE colour filter of the mosaic m on the raw grid (a RAW photograph's observations, observe): channel :R, :G or :B by Core's photosite_colors — 0 the red, 1 and 3 the two greens of every Bayer cell, 2 the blue — with the censored photosites dropped at both ends: the ADC floor (raw = 0) and the white level (Core's saturationview, raw ≥ white); a value below the black level is noise, not censored, and stays.

source
RadiometricCamera.raw_file — Method
raw_file(raw_dir, image) -> path

The RAW file of the photograph image in raw_dir: the one file with image's stem and a RAW extension (RAW_EXTENSIONS, any case); an ArgumentError naming the image when there is none or more than one.

source
RadiometricCamera.raw_green_image — Method
raw_green_image([T = Float32], m::RawMosaic; sensor_model::SensorModel, device) -> Matrix{T}

The geometry image "raw_green" of the mosaic m (on the host): VisualGeometryToolkitFeatures' bilinear green on the raw grid under the frame's sensor_model — the image Features' detect_sfop(m::RawMosaic) and the seeded detect_foerstner(m, seeds) detect on (the chrome detect), computed on device by Features' one kernel (_bilinear_green, rawgreen.jl: a green photosite its own value, a red or blue one the mean of its usable green 4-neighbours; defects missing, saturation censored at 1). Linear values (Core's linearview under the model), in the raw's COLMAP pixels (the mosaic's `rawframe_map`: the identity as decoded); NaN where no usable green is in the 3×3 (a defect cluster). No second implementation: Features exports no name for the plane alone (a Features API is the follow-up), so this is the one caller outside its detectors.

source
RadiometricCamera.raw_image_size — Method
raw_image_size(path) -> (W, H)

The image size of the RAW photograph path on the raw grid (its decoded mosaic's columns and rows, Features' load_raw_mosaic): the size of a photosites photograph, the camera's sensor in pixels.

source
RadiometricCamera.sensor_record — Method
sensor_record(names, models) -> Vector{NamedTuple}

The run record's sensor models, one per photograph (names[k], models[k]): Core's component_sources (each slot's source, nothing when absent; the resolver's reason; whether a specified component overrode a measured one), the black component the photograph's values were linearised with (black_component: Dark — per photosite, the photograph's EXIF exposure inside the dark's band —, ChannelBlack — per colour, e.g. reason DarkOutOfBand —, or FileBlack — the RAW's own, e.g. reason NoCharacterisation) and the model's identity (Core's content_digest), as plain strings.

source
RadiometricCamera.settings_line — Method
settings_line(cs::CaptureSettings; lens_stated = false) -> String

One line of a capture's camera settings for a run's log: the frame count, the body, the lens with its source (the config's lens_stated, else EXIF) and the exposure — "constant 1/60 s f/4 ISO 100" when every frame is exposed alike (Core's is_constant), the ranges otherwise.

source
RadiometricCamera.thin_lens_focus_distance — Method
thin_lens_focus_distance(lens, sensor, r₀; d_s = nothing) -> d  (metres; Inf when the rays are parallel)

The thin-lens construction, in the meridional plane (pinhole 𝔭 at the origin, aperture in z = 0, sensor at z = −d_s): from the sensor point under the aperture border (height r₀), intersect the chief ray through 𝔭 with the ray that runs parallel to the axis to the aperture border and from there through the focal point (0, f_m = f_px · pitch, the camera's focal length in pixels times the pixel pitch of VisualGeometryToolkitCore's sensor); with the intersection x, d = ‖x − 𝔭‖ cos α (α the chief ray's incidence) — the thin-lens conjugate d = f_m·d_s/(d_s − f_m). The image distance d_s (metres) is an input: the default (nothing), the pinhole model's sensor distance (= f_m), makes the two rays exactly parallel → d = Inf (focus at infinity, t̂ ≡ 0); any image distance d_s > f_m makes them intersect at a finite d.

source

Options

RadiometricCamera.rc_backend — Method
rc_backend(backend; inline = true, fallback = true) -> KernelAbstractions.Backend

THE device resolution of RC and its drivers: backend a tag of BACKEND_TAGS or its type. CPUCompute is KernelAbstractions' CPU(); GPUCompute loads the GPU vendor packages (GPU_VENDOR_PACKAGES) and takes VisualGeometryToolkitCore's vendor-agnostic resolver afresh (reset_default_device!, then default_device: a functional GPU, else the CPU). With no functional GPU it falls back to the CPU with a loud warning, or refuses (fallback = false). inline: the device backend compiling every call inlined (always_inline), RC's kernels' fast build — Core's resolver's non-inlined Jacobian kernel needs twice the local memory (1.5x slower at jacobian_chunk 4, 4.4x on the flux). Called at top level by a driver, so its later calls run in the world the vendor package's load made.

source
RadiometricCamera.FIXABLE_BLOCKS — Constant

The blocks fixed may hold (the options' top-level fixed): the poses, the camera (the geometric camera's parameters — a grid's lattice or a parametric camera's lens block), the focus surface, the aperture radius, the material ("material": Θm, the 8 nonlinear parameters and μ — the block's free board warping and in-plane print error stay free, `material_rides), the vignetting, the lighting, the in-plane print error."grid"is renamed"camera";"edge"` (never a parameter) is refused.

source
RadiometricCamera.NO_SENSOR_CHARACTERISATION — Constant

The RETIRED value of camera.sensor_characterisation that stated there is none (RC ≤ 0.11.1): refused since 0.11.2, naming camera.sensor_model = "off" (a record present, not used) — a run that names no record leaves the key empty.

source
RadiometricCamera.VIGNETTING_CONFIG_TAGS — Constant

Core's VIGNETTING_TAGS with the key path the pipeline's configs carry its tags at (vignetting.model): Core's tags, retired tensor included, and no tag of the package's own.

source
RadiometricCamera.BlobFrontend — Type

A calibration session's VisualGeometryToolkitIO records (frontend.session: camera.json, targets_1.json, trajectory_1.json, target_poses.json, textures/ — load_session; the board's target and its printed image are among them) and its detections (frontend.session: its records and its observations record observations.json). Tag blob.

source
RadiometricCamera.GridOptions — Type

[grid]: the grid model's control directions, the smoothness of its interior nodes and the start's perturbation (grid_smoothness.jl).

source
RadiometricCamera.IOOptions — Type

[io]: the photographs, the output directory, the start model, the RAW files and the diagnostic modes that write files and return.

source
RadiometricCamera.LensIdentityOptions — Type

io.lens_identity: the lens a capture was taken with, as the config states it (Core's DeviceIdentity; an empty field is unknown, and at least one is stated). It overrides the lens the RAW files' EXIF claims (Features' extract_capture_settings).

source
RadiometricCamera.MaskOptions — Type

[masks]: the samples of the run (the LM's; the closed-form start runs on the same pixels): samples_per_view of each view's usable observations.

source
RadiometricCamera.PipelineOptions — Type
PipelineOptions(; io, frontend, camera, grid, masks, rendering, lighting, material, vignetting, warping, edge, lm, sweep, resume,
                selfcheck, compute)

The options of a refinement, one table each (see the table structs for every key and its default; configs/default.toml lists them). Read from TOML with pipeline_options, written for the run record with config_dict. Required: io.images, io.out and the front-end's inputs (frontend.type = "blob": session; "schoeps": schoeps, texture, texture_features). A selfcheck.only run reads no photograph: it needs no io.images.

source
RadiometricCamera.SchoepsFrontend — Type

A Schöps central-generic run on a printed page (frontend.schoeps: intrinsics0.yaml, dataset.bin; the print from frontend.texture, frontend.texture_features, frontend.page_mm). Tag schoeps.

source
RadiometricCamera.StartPerturbationOptions — Type

grid.start_perturbation: the start grid's direction controls rotated by sigma_px / f px radians RMS per tangent axis, the draws from StableRNG(seed) (perturb_start, grid_smoothness.jl). Both keys are required: there is no default perturbation.

source
RadiometricCamera.INAPPLICABLE_KEYS — Constant
INAPPLICABLE_KEYS

The keys a run's other options make unusable: (table, key) => why, key === nothing for every key of the table, why(opts) the reason the key cannot act (a string) or nothing where it applies. The reader refuses a key a config STATES where its reason holds (pipeline_options: the key and the reason named), and the writer (config_dict) leaves such a key out, so a run's record reads back.

source
RadiometricCamera.PIPELINE_PATH_KEYS — Constant

The keys (table.key) whose values name an INPUT file or directory of a run: what a driver resolves against its data root and records as the run's inputs. io.init is a model spec, lens:<path> or grid:<path>. Every String option of PipelineOptions is here, in PIPELINE_OUTPUT_KEYS or in _NOT_PATH_KEYS (the suite checks the three cover the options): a new string option has to be declared one or the other.

source
RadiometricCamera.boolean_switch_violations — Method
boolean_switch_violations(config_dirs; data = ()) -> Vector{String}

The lint of the switch convention: every .toml under config_dirs (recursively) parsed, each TOML boolean found at a key path (VisualGeometryToolkitCore's leaf paths, table.key, an array's element key[i]) that no regex of data matches whole — a boolean that is a switch, which is spelled "on" | "off" — is a finding "file:path = value". data declares the booleans that are data, not switches (a statement of fact, or a key of another package's schema that package reads). A file that does not parse is a finding.

source
RadiometricCamera.names_input_path — Method
names_input_path(key, value) -> Bool

Whether the option key (table.key) with value names an input path of the run: a key of PIPELINE_PATH_KEYS with a non-empty string, except camera.lens_coverage = "sensor" (SENSOR_LENS_COVERAGE: the whole sensor, nothing measured). THE test a driver reads a run's inputs by.

source
RadiometricCamera.pipeline_options — Method
pipeline_options(path::AbstractString; set = ()) -> PipelineOptions
pipeline_options(table::AbstractDict; set = ()) -> PipelineOptions

The options of a refinement from a TOML file (or its parsed table). Every table and key is optional and takes its struct default when absent; an unknown table or key, a value of the wrong type or length, an unknown or retired tag and an unknown fixed block are refused with an ArgumentError that names them. set holds key.path=value overrides applied before reading (the --set of bin/refine.jl): pipeline_options("run.toml"; set = ["lm.max_iter=2", "io.out=/tmp/x"]).

source
RadiometricCamera.read_switch — Function
read_switch(v, key, cases = SWITCH_SPELLINGS) -> value

The switch key of a config with TOML value v, read through its cases (word => value): a two-way switch "on" → true, "off" → false; a switch whose availability is a condition states its own cases, "auto" among them, each a concrete value (a type: camera.sensor_model's SENSOR_MODEL_TAGS), so "auto" is resolved here and the core code never sees a string. TOML's true/false is refused naming the new spelling (key = true → use key = "on"; RC 0.11.4, no alias), any other value refused naming the cases. THE ONE reader of every switch: the pipeline's options, the sensor model and the paper project's drivers.

source
RadiometricCamera.write_pipeline_config — Method
write_pipeline_config(dir, opts; header = "") -> path

The options opts of a run as dir/pipeline_config.toml (config_dict, with header as its comment), its io.out written as an ABSOLUTE path (resolved against the writer's working directory, the one the run resolved it against): what bin/refine.jl and experiments/scripts/material_grid.jl write, so a record's regeneration hint can tell its own writer's options from another run's in a shared directory.

source
VisualGeometryToolkitEstimation.config_dict — Method
config_dict(opts::PipelineOptions) -> Dict{String, Any}

The options as a TOML document, one table per field (tags as their tag strings): what a run writes as its record. An absent optional table (grid.start_perturbation = nothing) is not written, nor a key the run cannot use (INAPPLICABLE_KEYS). pipeline_options(config_dict(opts)) == opts for options a config can state.

source

The pipeline

RadiometricCamera.measure_image_region — Method
measure_image_region(files; image, outlier_halfwidth_px, seed, device = default_device(), detect = detect_image_circle) -> NamedTuple

The image region of a capture set — where light falls on the sensor (the lens's lit region, an Ellipse in COLMAP pixels of the raw grid) — MEASURED on the set's own photographs files (RAW files, or full-resolution decoded .png), never predicted from a lens (a model's fold says where the model is valid, not where the field stop cuts the light): VisualGeometryToolkitFeatures' detect_image_circle (detect), streamed over the frames — the lens coverage's OUTER edge, the RANSAC ellipse (seeded by StableRNG(seed): the same region every run) through each angle's log-brightness drops on the frames' per-pixel maximum, resampled log-polar about the image centre on device. image is the geometry image measured on (one of GEOMETRY_IMAGES, the config's statement; no default): "raw_green" a RAW frame's bilinear green on the raw grid (raw_green_image, full resolution — the image every geometry detector reads, owner 2026-11-16), "luma" a decoded .png (a synthetic render) as stored, as Rec. 709 luma, on the raw grid. Both are on the raw grid (their frame map onto the raw is the identity), so the ellipse and outlier_halfwidth_px are raw pixels as given, nothing scaled. A "raw_green" set of decoded frames, a "luma" set of RAW frames or a mixed set is refused; no ellipse found is an error (the set's config must then state camera.lens_coverage = "sensor" or name other frames). Returns (; lens_coverage, extent, frames, center_scale, axes_scale, inliers, candidates, rim_gap, cut, seconds), the fields of the record (save_image_region). The measurement is GEOMETRIC (a rim threshold on log-brightness drops): its frames are read under the file's black, no sensor model — exempt from the observation model (RC 0.11.1; every photograph a camera is calibrated on or predicts goes through photo_set).

source
RadiometricCamera.run_lens_coverage — Method
run_lens_coverage(opts, W, H) -> Union{Nothing, Ellipse{Float64}}

The lens coverage of a run on W × H photographs, as its options state it (camera.lens_coverage): nothing for "sensor" (the sensor's rectangle, Core's default: the lens lights the whole sensor; nothing measured), else the measured image region of the rc/image_region/v1.0 record the option names (load_image_region: the capture set's keyed step) — refused when the record is missing or of other photographs (its extent not W × H). No other source: a grid start's stored coverage is not read.

source
RadiometricCamera.dataset_features — Method
dataset_features(path) -> [(image name, [(x, y, id)])]

The detections of a Schöps dataset.bin (a run's, or the texture's own detector run) in file order: COLMAP px (Schöps' pixel-corner convention is COLMAP's, SCHOEPS_PIXEL_FRAME), 0-based feature ids — VisualGeometryToolkitIO's load(TargetObservations, path; target); or a run's import, detections.json (schoeps_run_file: a vgio observations file in COLMAP px — v3.0, or an earlier target_points2d/v1 read through IO's version step — which names its targets itself, so IO's reader takes no target). The ids are one target's point indices: a file holding the detections of more than one target is refused (two targets' ids would collide).

source
RadiometricCamera.StartGeometry — Type
StartGeometry(camera, poses, observations, target; names, image_size = extent(camera), init_region = nothing, resample = nothing,
              features_for = _ -> observations, world = "the target's frame", page_flip = 1.0, board_y_sign = 1.0)

The geometric calibration a radiometric calibration starts from: the geometric camera (a BoundedCamera, the start camera), one poses[k] per photograph (camera → world, EuclideanMap), the observations[k] of the target in photograph k ((𝐩, X) pairs: the image point, COLMAP px, and the target point in the world, plain metres) and the printed target (a TexturedTarget). The front end's facts ride along: the photographs' names, the image size, the start camera's initialization region (where it is defined; nothing: its own domain), the record of its exact resample (resample, exact_start's; nothing for a camera that was not resampled), features_for(surface) (the observations under a warped or misprinted surface), the world's name and the front end's frame choices (page_flip, board_y_sign) its records keep.

source
RadiometricCamera.load_calibration_start — Method
load_calibration_start(dir; options, device = default_device(), observations = nothing, photographs) -> CalibrationState

The refinement's state from the start record dir (save_calibration_start; refused when its start options are not start_options(options)): the front end's target and observations, the record's camera, region and poses, the photographs streamed at the record's masks (or the start's own streamed observations, handed over in the process that computed it: no photograph read again), and the closed-form start's state, costs and GCV weights loaded — nothing of the start computed again. photographs: the files of the record's views, by default the run's (io.images, start_photographs).

source
RadiometricCamera.save_calibration_start — Method
save_calibration_start(dir, state; options) -> dir

The start state (start_calibration's, of the start options options) as the start record dir: every value a refinement takes from its start (start/startrecord.jl), so [`loadcalibration_start`](@ref) rebuilds the start's state from the photographs and this record without computing it again.

source
RadiometricCamera.selfcheck — Method
selfcheck(geometry; options)

The diagnostic selfcheck.only: the bearing error of the start geometry's observations through its camera (per view, under its poses or those of the selfcheck.poses state) → selfcheck.json, selfcheck_vectors.json in io.out. No photograph is read.

source
RadiometricCamera.start_calibration — Method
start_calibration(geometry::StartGeometry, photographs; options, device = default_device()) -> CalibrationState
start_calibration(camera, poses, observations, photographs; target, options, device = default_device(), names) -> CalibrationState

The start of a radiometric calibration: it lifts the geometric camera of geometry (or of camera, poses, observations and target, the geometric calibration as data) into a radiometric state — the focus surface through the mean target centre, the aperture from the f-number, the image circle measured where the run names its frames, the masks, the photographs' observations streamed (photographs[k] the file of view k: a RAW photograph by its file, its green photosites, or a decoded image), the vignetting and the lighting by the closed-form start, the grid smoothness. options are the start's (start_options). The state's start holds what the refinement and its records read (the start views, the observations, the costs of the start).

Every input is a value: the pipeline's front ends read theirs through VisualGeometryToolkitIO (start_geometry); a caller with a Schöps run, a Kalibr or an OpenCV calibration of its own loads its camera and observations with IO's importers itself (VisualGeometryToolkitIO.load(BoundedCamera, …), load(TargetObservations, …)) — RC reads no foreign format.

source
RadiometricCamera.start_geometry — Method
start_geometry(options; record = nothing) -> StartGeometry

The start geometry of the run options from its front end (frontend.type: a calibration session's records, or a Schöps run's), every input read through VisualGeometryToolkitIO: the start camera (the front end's onto the run's lattice, start_grid; or the stored start io.init), its poses, the observations of the target and the printed target. With a start record (a start record's, load_calibration_start) its camera, initialization region and poses are the record's, nothing fitted again.

source
RadiometricCamera.start_is_grid — Method
start_is_grid(opts) -> Bool

Whether the start of the refinement opts is a grid camera (a bounded SplineLens camera), refined per tile, rather than a parametric one refined in its own parameters: every start is a grid but a parametric record's (io.init = "lens:…") — the blob front end's session camera and the Schöps front end's are resampled into the grid. THE decision of the start's kind: the start takes it (and refuses a front end whose start disagrees); its start record holds grid.json beside its initialization_region.json, else lens.json.

source
RadiometricCamera.REFINE_ONLY_KEYS — Constant
REFINE_ONLY_KEYS

The PipelineOptions keys (table.key) that only the refinement reads (refine_calibration!, after the start): the LM's iteration and time caps and its stop tolerances (RC 0.11.4), the per-iteration checkpoints, the closed-form sweeps between LM chunks, a resumed run's iteration offset and its sweep. A start is computed from start_options, which holds them at their defaults, so a change of one never changes (or recomputes) a start. resume.state is not among them: the front end reads its page frame.

source
RadiometricCamera.check_start_options — Method
check_start_options(start, opts)

Refuses (ArgumentError, naming the differing keys) a start record whose start options are not start_options(opts): a start of other settings is never taken for this run's.

source
RadiometricCamera.split_refine_only — Method
split_refine_only(table; keys = REFINE_ONLY_KEYS) -> (start, refine)

A [pipeline] table (or config_dict) split in two: start, the table without keys (the tables they leave empty dropped), and refine, those of keys it states. THE split of a run's options into its start's and its refinement's: start_options and the paper project's drivers (the start's and the refinement's keys) read it.

source
RadiometricCamera.start_pipeline_table — Method
start_pipeline_table(table) -> Dict

The [pipeline] table table as its start reads it: without the refinement-only keys (REFINE_ONLY_KEYS) and the outputs (PIPELINE_OUTPUT_KEYS: io.out, lm.log) — THE definition of what a start reads, start_options' and a driver's start key's.

source
RadiometricCamera.bearing_px — Method

Bearing error [px] of detections feats = [(𝐩, X)] through lens under pose: the angle between the model's ray of 𝐩 and the direction to the board point X, times the focal length in px.

source
RadiometricCamera.board_hits — Method

The same residual on the BOARD: the detection's ray (lens + pose) intersected with the board plane, in chart units, next to the chart of the board point it was matched to.

source
RadiometricCamera.detection_bearings — Function
detection_bearings(lens, poses, features, fpx = 1.0) -> Vector{Float64}

The bearing errors of every view's detections, features[k] = [(𝐩, X)] under poses[k], through lens (bearing_px per view, concatenated in view order): in radians with fpx = 1, in px with the focal length fpx — the refinement monitor's bearing(detections, own poses) (its px are fpx × the radians, the same product per detection).

source
RadiometricCamera.fpx_of — Method

Focal length in px for the bearing → px conversion and the image-distance start: the f_x of the camera's pinhole (K, or a grid model's nominal) unless the model's angular pixel pitch at the image centre disagrees with it by > 1 % — the (ξ, f) pair of a fitted DoubleSphere is degenerate on the axis (f_eff ≈ f/(1 + ξ)), so there the pitch is the focal length.

source
RadiometricCamera.residual_vectors — Method

Residual VECTORS in image px: from each detection to the model's prediction — the projection of the board point under the pose through the lens (_project_from, Core's projections), started at the detection.

source
RadiometricCamera.state_bearings — Method
state_bearings(geometry::StartGeometry, state) -> Vector{Float64}

The bearing errors [rad] of the start geometry's detections through a refinement state's camera under that state's own poses, the target points placed on the state's own surface (its warping and in-plane print error, the geometry's features_for): the quantity the refinement's monitor prints as bearing(detections, own poses) at the iteration of state (fpx × these, in px). state is a state of load_state — a checkpoint state_it<N>.json (io.checkpoint_each) or a start record's state.json (iteration 0); its views are matched to the geometry's by name (an ArgumentError naming a view it lacks).

source
RadiometricCamera.render_dump! — Method

Render the masked pixels of every view at the state (no fitting): per-view level ratios on ink and paper, Float32 photo / model dumps (green channel, column-major H × W, NaN outside the mask) and Float16 RGB dumps in out.

source
RadiometricCamera.load_pipeline_metrics — Method
load_pipeline_metrics(dir) -> Dict{String, Any}

The metrics a pipeline run wrote in dir, as one TOML-printable table, read from the run's own files:

  • a refinement (parameters.json, its rc/run_parameters/v1 record, load_run_parameters): cost (the photometric cost and its relative RMS at the start, init, after the closed-form solve, after_linear_solve, and after the LM, after_refinement), bearing_error (the bearing error of the detections through the start model, init_*, and through the refined model and poses, refined_*: median and p90, pixels), camera_moved (per view, metres: the record's length unit), iterations, stopped (the LM's termination bits by name) and its termination record: retcode (the name of its VisualGeometryToolkitCore ReturnCode) and stop_rule (of its StopRule);
  • a selfcheck.only run (selfcheck.json): selfcheck with n, median, p90 and mean of the bearing error over every detection (px).

A value the pipeline wrote as null is left out. A directory holding neither file is an ArgumentError.

source
RadiometricCamera.save_poses — Method
save_poses(path, poses, names; world)

The views' poses (camera → world, one per view) as VisualGeometryToolkitIO's trajectory record (vgio/trajectory/v3): world → camera (X_cam = R X_world + t, the inverse of each camera → world pose) per frame k with its image names[k], lengths in mm on disk; world names the scene's world frame in the provenance.

source
RadiometricCamera.save_radiometric_calibration — Method
save_radiometric_calibration(state, result; options)

The records of a radiometric calibration (refine_calibration!'s result of the state state, the run options) in the run's directory io.out, each through VisualGeometryToolkitIO:

grid.json / lens.json (+ grid_init.json / lens_init.json; the model spec of the evaluation scripts is grid:<file> | lens:<file>), state.json, radiometric_camera.json, radiometric_target.json, poses_{init,refined}.json and parameters.json in io.out.

source

Records

RadiometricCamera's kinds, read and written through VisualGeometryToolkitIO (write_record, read_record), each nesting IO's records of the Core values it holds, under IO 0.10's envelope (one units and one conventions object): rc/radiometric_camera/v3.1 (a CalibratedCamera: the model, its observation model and its render settings), rc/radiometric_target/v2.0, rc/calibration_state/v3.1 (the state files state.json, state_it<N>.json and a start record's start state; with the photographs' observation model) and rc/run_parameters/v3.0. A record of an earlier RC version is refused by name — a camera or a state of RC 0.9–0.11.0 (v3.0) too, which states no observation model (RC 0.11.1: refused, never migrated, naming the refinement step that regenerates it) — but an rc/run_parameters/v2.0 (its grid prior* keys renamed to the smoothness vocabulary, RC 0.11.0), which reads through its version step. A camera's or a state's focus surface is the sensor-grid thin plate spline ("type": "sensor_thin_plate_spline"); a record of a removed focus surface (direction_thin_plate_spline, direction_spherical_spline) and a file of the removed kind rc/focus_ab (the focus A/B experiment's report) are refused by name.

The observation model and the one entry point of photographs

A calibrated camera states how its photographs were read (ObservationModel: the sensor characterisation's sha256 or none, RAW photosites or decoded images, the channel); every photograph a camera is calibrated on or predicts is read through photo_set / observe under it, by dispatch on its types (RC 0.11.1).

RadiometricCamera.OBSERVATION_CHANNELS — Constant

The channels an observation model measures: :RGB (the three, decoded images), :R, :G, :B (one; a RAW photograph's photosites are those of one colour filter: one of the three).

source
RadiometricCamera.CalibratedCamera — Type
CalibratedCamera(model, observation, settings)

A COMPLETE calibration: the RadiometricCameraModel model (the kernel type: lens, focus surface, aperture, vignetting), the ObservationModel its photographs were observed under and the RenderSettings its predictions were integrated with. What a prediction of the camera must reproduce; the unit rc/radiometric_camera and rc/calibration_state records save and load (load_radiometric_camera, calibrated_camera(load_state(path))). Photographs it predicts are read through photo_set.

source
RadiometricCamera.Decoded — Type
Decoded(srgb)

Decoded images (PNG, TIFF, the synthetic renders): their pixels, read by Features' load_linear_image — sRGB-decoded when srgb (the calibration's io.linearize), the samples as stored otherwise.

source
RadiometricCamera.NoSensorRecord — Type
NoSensorRecord()

The camera was calibrated without a sensor characterisation (none named, or camera.sensor_model = "off"): RAW photographs under the file's black, no noise law and no defects (Core's absent SensorModel()), or decoded images, which no sensor model describes.

source
RadiometricCamera.ObservationModel — Type
ObservationModel(sensor::SensorStatement, kind::PhotoKind, channel::Symbol)

How a calibration's photographs were observed: the sensor statement, the photographs' kind and the channel measured (OBSERVATION_CHANNELS). RAW photosites are those of one colour filter (:R, :G or :B, never :RGB); a sensor record describes RAW photosites only (a decoded image under a SensorRecord is refused).

source
RadiometricCamera.Photosites — Type

RAW photographs: the photosites of ONE colour filter on the raw grid — the observation model's channel, :R, :G (both greens) or :B — censored at the ADC floor and the white level, a sensor record's defects masked (photosite_mask).

source
RadiometricCamera.SensorRecord — Type
SensorRecord(sha256)

The camera was calibrated on RAW photographs linearised under the sensor characterisation (a vgio/sensor_characterisation record) whose file's sha256 is sha256 (lower-case hex, Core's sha256_hex): its black (a dark per exposure, or the measured channel black), its noise law and its defects. A prediction of the camera reads photographs under exactly that record; any other file is refused.

source
RadiometricCamera.observation_model — Method
observation_model(files, spec; linearize = false, channel = "G", sensor_model = AutoSensorModel(), stated = NoSensorRecord()) -> ObservationModel

The observation model of a calibration reading the photographs files (the producer's: the calibration's start), by the files (is_raw_file), never by a flag: RAW photographs are Photosites under the sensor statement sensor_model decides (sensor_model_mode) from the record present — spec (camera.sensor_characterisation: a named record must exist) or stated, the sensor statement of the camera the run continues (a start or resumed state's):

Decoded images are Decoded(linearize) under NoSensorRecord: a record named for them is refused (no sensor model describes a decoded image), so is sensor_model = "on". RAW and decoded photographs mixed are refused; channel is io.channel.

source
RadiometricCamera.sensor_model_mode — Method
sensor_model_mode(value) -> SensorModelMode

The mode of camera.sensor_model = value (SENSOR_MODEL_TAGS): another value is an ArgumentError naming the three.

source
RadiometricCamera.sensor_model_record — Method
sensor_model_record(mode, spec, stated, om) -> NamedTuple

What a run's records state of its sensor model: the mode (camera.sensor_model), whether the observation model om uses a record (used), and the record present (present: the named one's path and sha256, or the camera's statement's sha256; nothing when none). off with a record present is a run that did not use it (the tables flag it).

source
RadiometricCamera.sensor_statement — Method
sensor_statement(spec) -> SensorRecord

The sensor record of camera.sensor_characterisation = spec: the SensorRecord of the file spec (its sha256, Core's sha256_hex of the file). A spec that names no file, an empty one, and the retired "none" are ArgumentErrors.

source
RadiometricCamera.warn_sensor_model_off — Method
warn_sensor_model_off(record)

THE warning of a run that does not use a sensor record present (camera.sensor_model = "off"): one multi-line @warn banner naming record (its location and sha256, or the camera's statement), that the run does not use it, that estimation and prediction may then disagree, and the TOML line. Emitted once per run (the run's resolution, observation_model; a prediction, photo_set).

source
RadiometricCamera.RECORD_SCHEMAS — Constant

The schema of each RadiometricCamera kind, by its name: the version this package writes and reads (IO 0.10's envelope). An earlier version (RC ≤ 0.8: IO 0.9's envelope) is refused by name: regenerate it.

source
RadiometricCamera.load_image_region — Method
load_image_region(path) -> (; lens_coverage, extent, frames, record)

The rc/image_region/v1.0 record path (save_image_region): its measured lens coverage (an Ellipse or a Circle, COLMAP pixels), the photographs' (W, H), the frames it was measured on, and the record as read. Another schema is an ArgumentError naming it.

source
RadiometricCamera.load_radiometric_camera — Method
load_radiometric_camera(path) -> CalibratedCamera

The calibrated camera of an rc/radiometric_camera/v3.1 record (save_radiometric_camera): the model, its observation model and its render settings. Another schema is an ArgumentError — a v3.0 record (RC 0.9–0.11.0) states no observation model and is refused by name with the step that regenerates it.

source
RadiometricCamera.load_state — Method
load_state(path) -> NamedTuple

The state of a refinement's state file (state.json, state_it<N>.json, a start record's state.json; rc/calibration_state/v3.1, save_state): (; camera, target, poses, names, light, settings, observation, page_flip) — the RadiometricCameraModel, the RadiometricTarget (board_surface(board, target) the board's state on a board of its page's aspect), the poses (camera → world, plain metres) of the photographs names, VisualRadiometryToolkitCore's EnvironmentLight (plain metres), the RenderSettings, the photographs' ObservationModel and the ±y choice (nothing when the state records none); calibrated_camera(load_state(path)) its CalibratedCamera. A v3.0 state (RC 0.9–0.11.0) states no observation model and is refused by name with the step that regenerates it.

source
RadiometricCamera.save_image_region — Method
save_image_region(path, m; provenance = (;))

The measured image region m of a capture set (measure_image_region's result) as an rc/image_region/v1.0 record (IO's write_record): lens_coverage the region (IO's region body, a leaf: the measured Ellipse, COLMAP pixels of the raw grid), extent the photographs' [W, H], frames the photographs it was measured on and the detector's diagnostics (center_scale, axes_scale px, inliers of candidates rim candidates, the largest rim_gap rad, cut by the frame). Read by load_image_region — every consumer's one reader (a run's camera.lens_coverage).

source
RadiometricCamera.save_initialization_region — Method
save_initialization_region(dir, region)

The initialization region region (any of Core's regions, in pixels: a Rect2, an Ellipse, a Circle, their RegionIntersection or the WholePlane) of the grid cameras the pipeline writes in dir — the start's, where every one of them is defined as a start — as dir/initialization_region.json, an rc/initialization_region/v1.0 record (IO 0.10's region body). Written beside every grid the pipeline writes (the saved initialization, the checkpoints, the result), so each is a valid start (load_start).

source
RadiometricCamera.save_radiometric_camera — Method
save_radiometric_camera(path, camera::CalibratedCamera; length_unit = mm, provenance = (;))

A CalibratedCamera as an rc/radiometric_camera/v3.1 record (VisualGeometryToolkitIO's file boundary; see the file header of records.jl for the record): its geometric camera as IO's camera or generic camera body, its aperture, focus surface and vignetting (VisualRadiometryToolkitIO's body), its observation model and its render settings. Lengths in length_unit.

source
RadiometricCamera.save_radiometric_target — Method
save_radiometric_target(path, target; length_unit = mm, provenance = (;))

A RadiometricTarget as an rc/radiometric_target/v2.0 record: the geometric target as IO's target body (its content identity unchanged), the warping's nodal heights, the material, the ink spread and the print's blur. Lengths in length_unit.

source
RadiometricCamera.save_run_parameters — Method
save_run_parameters(path, body; provenance = (;))

A refinement's run as an rc/run_parameters/v3.0 record (VisualGeometryToolkitIO's write_record): body (the pipeline's _run_parameters: ASCII snakecase keys, no unit in a key, never a value the model records hold) under IO's envelope — its lengths are plain metres, the units object's length "m"; its image quantities COLMAP pixels, the units object's pixel; the rest dimensionless. [`loadrun_parameters`](@ref) reads it back.

source
RadiometricCamera.save_state — Method
save_state(path, s::CalibrationState, names; page_flip = nothing, provenance = (;))
save_state(path, state::NamedTuple; length_unit = mm, provenance = (;))

A refinement's state as an rc/calibration_state/v3.1 record (VisualGeometryToolkitIO's file boundary; records.jl's header): the radiometric camera, the radiometric target, the poses of the photographs (names, in order) as IO's trajectory body, the light as VisualRadiometryToolkitIO's environment light body, the render settings, the photographs' observation model (observation_model(s)) and the page's ±y choice (page_flip, the Schöps front end's; omitted when nothing). state holds the fields load_state returns (camera, target, poses, names, light, settings, observation, page_flip). A run's labels (the iteration, the costs) go in provenance.

source
RadiometricCamera.stored_initialization_region — Method
stored_initialization_region(grid_path) -> region

The initialization region of the grid camera record grid_path: the rc/initialization_region/v1.0 record beside it (initialization_region.json, save_initialization_region), any of Core's regions. A grid without one (a run from a parametric start, defined by its own valid domain, records none) is an ArgumentError — a stored grid start never falls back to the whole sensor.

source