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.
RadiometricCamera.RAW_EXTENSIONS — Constant
The RAW extensions a session's frames are looked up by (raw_file), compared case-insensitively.
RadiometricCamera.PhotoSet — Type
PhotoSetThe 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.
RadiometricCamera.check_geometry_image — Method
check_geometry_image(t, where) -> StringThe 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).
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.
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.
RadiometricCamera.load_photo — Method
load_photo(path; linearize = false) -> RawMosaic | AbstractArrayTHE 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).
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 itsSensor(sensor_widthover the record's extent) and moved to the scene's pixels when the photographs are box-averaged bydownsample(K re-expressed under the box downsample: Core'sCameras.reframed_calibrationby the similarity x ↦ x / f):lens = :camerathat pixel camera,:gridthe generic grid model ofgrid_sizesampled 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_imageand box-averaged bytexture_downsample— as theTexturedTargetof 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 distanced_c, the lens equation's image distanced_s = f·d_c/(d_c − f), the start planet̂ᵢ = 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_distanceoverridesd_s(nothing: fromfocus_init,:boardthe conjugate of the board distance, or a number); - the targets: the photographs
image_dir/<image>in frame order (sRGB-decoded whenlinearize, box-averaged bydownsample); withload_targets = falseonly the first is read, for the image size; - the capture's camera settings (
settings): withraw_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'sCaptureSettings, frame index → exposure and lens settings, with the body and the lens (lens_identitywhere the caller states it: an adapted lens EXIF misnames);nothingwithoutraw_dir. Reading the RAW files is Features' decoder (its LibRaw extension, loaded with this package).
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'slinearview: 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
Decodedstates it) under the mask; an image whose size is not the mask's is refused.
RadiometricCamera.photo_file — Method
photo_file(dir, name) -> pathThe 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.
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.
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) -> PhotoSetTHE 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;characterisationrequired and its file's sha256 equal to the record's — another file is refused naming both. Each photograph's model is Core's resolversensor_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, reasonNoCharacterisation); acharacterisationis refused: the camera was calibrated without one.NoSensorRecord,Decoded: decoded images only, the absent model each; a RAW photograph is refused, so is acharacterisation.
RadiometricCamera.photosite_mask — Method
photosite_mask(m::RawMosaic, channel::Symbol) -> BitMatrixThe 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.
RadiometricCamera.raw_file — Method
raw_file(raw_dir, image) -> pathThe 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.
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.
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.
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.
RadiometricCamera.settings_line — Method
settings_line(cs::CaptureSettings; lens_stated = false) -> StringOne 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.
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.
Options
RadiometricCamera.BACKEND_TAGS — Constant
The backend registry: compute.backend tag → AbstractComputeBackend type. The tag cuda is retired (2026-11-13: a GPU is any KernelAbstractions GPU backend, not CUDA's): it refuses, naming gpu.
RadiometricCamera.AbstractComputeBackend — Type
The device a driver runs the refinement on: CPUCompute or GPUCompute (tags in BACKEND_TAGS). A driver maps it to a KernelAbstractions backend with rc_backend, which loads the GPU vendor packages for GPUCompute.
RadiometricCamera.CPUCompute — Type
The CPU (KernelAbstractions' CPU()). Tag cpu.
RadiometricCamera.GPUCompute — Type
A GPU, when one is functional (any KernelAbstractions GPU backend: VisualGeometryToolkitCore's default_device). Tag gpu.
RadiometricCamera.rc_backend — Method
rc_backend(backend; inline = true, fallback = true) -> KernelAbstractions.BackendTHE 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.
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.
RadiometricCamera.FRONTEND_TAGS — Constant
The front-end registry: frontend.type tag → AbstractFrontend type.
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.
RadiometricCamera.SENSOR_LENS_COVERAGE — Constant
The camera.lens_coverage that states a lens lighting the whole sensor: the coverage is the sensor's rectangle (Core's default lens coverage), nothing is measured.
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.
RadiometricCamera.AbstractFrontend — Type
The start geometry of a refinement: BlobFrontend or SchoepsFrontend (tags in FRONTEND_TAGS).
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.
RadiometricCamera.CameraOptions — Type
[camera]: the nominal camera, the aperture bounds, the lens coverage and the sensor characterisation.
RadiometricCamera.ComputeOptions — Type
[compute]: the device and the GPU Jacobian's batch.
RadiometricCamera.EdgeOptions — Type
[edge]: the printed-edge albedo.
RadiometricCamera.FocusOptions — Type
[focus]: the focus surface, the sensor-grid thin plate spline — its nodes, their data support and its smoothness.
RadiometricCamera.FrontendOptions — Type
[frontend]: the start geometry (type a tag of FRONTEND_TAGS) and its inputs.
RadiometricCamera.GridOptions — Type
[grid]: the grid model's control directions, the smoothness of its interior nodes and the start's perturbation (grid_smoothness.jl).
RadiometricCamera.IOOptions — Type
[io]: the photographs, the output directory, the start model, the RAW files and the diagnostic modes that write files and return.
RadiometricCamera.LMOptions — Type
[lm]: the Levenberg–Marquardt over Θ̄.
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).
RadiometricCamera.LightingOptions — Type
[lighting]: the lighting model L^SVSH.
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.
RadiometricCamera.MaterialOptions — Type
[material]: the start of Θ_m and its handling.
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.
RadiometricCamera.RenderingOptions — Type
[rendering]: the quadrature of the image formation (RenderSettings).
RadiometricCamera.ResumeOptions — Type
[resume]: continuing a finished run.
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.
RadiometricCamera.SelfcheckOptions — Type
[selfcheck]: the bearing self-check of the detections through the start model.
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.
RadiometricCamera.SweepOptions — Type
[sweep]: the closed-form (lighting, vignetting, μ) sweep between LM chunks.
RadiometricCamera.VignettingOptions — Type
[vignetting]: the vignetting field, the radial profile about the principal point (model: Core's tag radial).
RadiometricCamera.WarpingOptions — Type
[warping]: the board warping h (thin plate spline through nodal heights) and the in-plane print error (Core's Aspect ∘ Skew).
RadiometricCamera.INAPPLICABLE_KEYS — Constant
INAPPLICABLE_KEYSThe 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.
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.
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.
RadiometricCamera.inapplicable_reason — Method
Why the option table.key cannot act in a run of opts (INAPPLICABLE_KEYS), or nothing where it applies.
RadiometricCamera.names_input_path — Method
names_input_path(key, value) -> BoolWhether 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.
RadiometricCamera.pipeline_options — Method
pipeline_options(path::AbstractString; set = ()) -> PipelineOptions
pipeline_options(table::AbstractDict; set = ()) -> PipelineOptionsThe 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"]).
RadiometricCamera.read_switch — Function
read_switch(v, key, cases = SWITCH_SPELLINGS) -> valueThe 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.
RadiometricCamera.switch_spelling — Function
The config spelling of the switch value x among cases (read_switch's inverse; the writer's): "on" / "off" for a Bool.
RadiometricCamera.write_pipeline_config — Method
write_pipeline_config(dir, opts; header = "") -> pathThe 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.
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.
The pipeline
RadiometricCamera.measure_image_region — Method
measure_image_region(files; image, outlier_halfwidth_px, seed, device = default_device(), detect = detect_image_circle) -> NamedTupleThe 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).
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.
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).
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.
RadiometricCamera.load_calibration_start — Method
load_calibration_start(dir; options, device = default_device(), observations = nothing, photographs) -> CalibrationStateThe 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).
RadiometricCamera.save_calibration_start — Method
save_calibration_start(dir, state; options) -> dirThe 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.
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.
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) -> CalibrationStateThe 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.
RadiometricCamera.start_geometry — Method
start_geometry(options; record = nothing) -> StartGeometryThe 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.
RadiometricCamera.start_photographs — Method
The photographs of the views names of the run options (io.images; a RAW file by its stem, photo_file).
RadiometricCamera.start_is_grid — Method
start_is_grid(opts) -> BoolWhether 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.
RadiometricCamera.REFINE_ONLY_KEYS — Constant
REFINE_ONLY_KEYSThe 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.
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.
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.
RadiometricCamera.start_options — Method
start_options(opts) -> PipelineOptionsThe options a start is computed from and keyed by: opts with REFINE_ONLY_KEYS and the output keys (PIPELINE_OUTPUT_KEYS: io.out, lm.log) at their defaults (split_refine_only).
RadiometricCamera.start_pipeline_table — Method
start_pipeline_table(table) -> DictThe [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.
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.
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.
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).
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.
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.
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).
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.
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, itsrc/run_parameters/v1record,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 VisualGeometryToolkitCoreReturnCode) andstop_rule(of itsStopRule); - a
selfcheck.onlyrun (selfcheck.json):selfcheckwithn,median,p90andmeanof 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.
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.
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.
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.CHANNEL_NAMES — Constant
The colour channels by name, in the photographs' and every per-channel quantity's order (the lighting rows, the η's, io.channel).
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).
RadiometricCamera.SENSOR_MODEL_TAGS — Constant
The values of camera.sensor_model, each the mode it parses to.
RadiometricCamera.AutoSensorModel — Type
sensor_model = "auto" (the default): a sensor record present is used; with none the run reads the file's black (one info line).
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.
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.
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.
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).
RadiometricCamera.OffSensorModel — Type
sensor_model = "off": a sensor record present is NOT used (the file's black, no noise law, no defects), with the loud warning warn_sensor_model_off; with none the run reads the file's black.
RadiometricCamera.OnSensorModel — Type
sensor_model = "on": the run requires a sensor model — a sensor record present is used; with none the run is refused.
RadiometricCamera.PhotoKind — Type
The kind of the photographs a camera was calibrated on: Photosites or Decoded.
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).
RadiometricCamera.SensorModelMode — Type
Whether a run uses the sensor model (camera.sensor_model, parsed once by sensor_model_mode): AutoSensorModel, OnSensorModel or OffSensorModel. Every decision on it is a dispatch on these types.
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.
RadiometricCamera.SensorStatement — Type
The sensor statement of a calibration: SensorRecord or NoSensorRecord.
RadiometricCamera._channel_symbol — Method
The observation model's channel of a state's channel index (0: :RGB; 1–3: :R, :G, :B).
RadiometricCamera._characterisation_path — Method
The location photo_set reads the run's photographs with: the named record's path when the run's observation model uses one.
RadiometricCamera._named_record — Method
The named record of spec: nothing (empty), else (; path, record) (sensor_statement's refusals).
RadiometricCamera.calibrated_camera — Method
calibrated_camera(state) -> CalibratedCameraThe calibrated camera of a state: a load_state record's (its camera, observation and settings) or a CalibrationState's (observation_model(s)).
RadiometricCamera.mode_name — Method
The TOML value of a mode (the run's records).
RadiometricCamera.observation_line — Method
One line of an observation model for a message or a log: its sensor statement, the photographs' kind and the channel.
RadiometricCamera.observation_model — Method
observation_model(files, spec; linearize = false, channel = "G", sensor_model = AutoSensorModel(), stated = NoSensorRecord()) -> ObservationModelThe 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):
AutoSensorModel: the named record'sSensorRecord; none named —NoSensorRecord(one info line), or, when the camera states a record, refused (its location is needed);OnSensorModel: the named record's; none named — refused;OffSensorModel:NoSensorRecord, withwarn_sensor_model_offwhen a record is present.
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.
RadiometricCamera.sensor_model_mode — Method
sensor_model_mode(value) -> SensorModelModeThe mode of camera.sensor_model = value (SENSOR_MODEL_TAGS): another value is an ArgumentError naming the three.
RadiometricCamera.sensor_model_record — Method
sensor_model_record(mode, spec, stated, om) -> NamedTupleWhat 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).
RadiometricCamera.sensor_statement — Method
sensor_statement(spec) -> SensorRecordThe 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.
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).
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.
RadiometricCamera.PRINT_PLANE — Type
The plane a radiometric target's print blur is recorded on: the printed board's (TargetPlaneFrame{:board}; RC's one target).
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.
RadiometricCamera.load_radiometric_camera — Method
load_radiometric_camera(path) -> CalibratedCameraThe 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.
RadiometricCamera.load_radiometric_target — Method
load_radiometric_target(path) -> RadiometricTargetThe radiometric target of an rc/radiometric_target/v2.0 record (save_radiometric_target): its geometric target as IO reads a target body (nothing when the record holds none), the warping in metres; another schema is an ArgumentError.
RadiometricCamera.load_run_parameters — Method
load_run_parameters(path) -> recordThe rc/run_parameters/v3.0 record of a refinement (save_run_parameters) as IO's read_record reads it (a v2.0 record through its version step, _run_parameters_v3); another schema is an ArgumentError.
RadiometricCamera.load_state — Method
load_state(path) -> NamedTupleThe 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.
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).
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).
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.
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.
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.
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.
RadiometricCamera.stored_initialization_region — Method
stored_initialization_region(grid_path) -> regionThe 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.