Calibration

Image formation, the calibration state, the closed-form solves and the joint Levenberg–Marquardt over all blocks, on the CPU or a device.

Image formation

RadiometricCamera.RenderSettings — Type
RenderSettings

Quadrature rules and radiance sampler shared by all renders. Φ is the aperture integral divided by |𝒜| = πr²: the aperture's radius is then no scale of the flux, so it cannot trade against the lighting's.

RenderSettings(; n_𝐩 = 2, n_ρ = 3, n_φ = 8, N = 8, seed = 42, hammersley = false)
source
RadiometricCamera.compute_mask — Method
compute_mask(camera, pose, board, settings; δ = 0.02, external = nothing, backend) -> BitMatrix

Pixel mask of camera (a RadiometricCameraModel) at pose (camera → world): true where the chief ray and every (footprint corner × aperture border sample) ray hits the board inside [δ, 1−δ]² in front of the camera; intersected with external. board_valid over every pixel of external (all of them without one): one kernel on backend, required. A caller that needs only some of the pixels (the start's draw, draw_samples) tests those alone through BoardValidity.

source
RadiometricCamera.masked_vector — Method
masked_vector(img, px; channel = 0) -> Vector{Float64}

The observed vector ϕ of the masked pixels px, in the residual's layout (𝔯 = Φ − ϕ): for channel = 0 the three channels of img (H × W × 3) per pixel, channel fastest (index 3(i−1)+c); for channel = c that channel alone, ONE entry per pixel (fit_channels). A single plane img (H × W: one measurement per pixel, the green photosites) is one entry per pixel and needs a single-channel state (channel 1–3).

source
RadiometricCamera.render_view — Method
render_view(k, camera, pose, mat, light, board, settings, mask; backend = CPU()) -> Array{Float64, 3}

H × W × 3 image of photograph k, camera (a RadiometricCameraModel) at pose (camera → world), zeros outside the mask: the flux kernel (_FluxAt, device/jacobiankernels.jl) on backend (KernelAbstractions' CPU() by default; a device: `rcbackend("gpu")), in the backend's kernel float as a state's kernels (kernelfloat: Float64 on the CPU backend, Float32 on a device, where the image agrees with the CPU's to Float32 rounding).kis the photograph's index: it keys the common random numbers of the radiance, so photographk` of a state renders with its index.

source
RadiometricCamera.Φ_pixel — Method
Φ_pixel(u, v, k, camera, pose, mat, light, board, settings) -> SVector{3}

Radiant flux of pixel (u, v) (column u, row v of the H × W image) of photograph k: camera (a RadiometricCameraModel) at pose (camera → world). k is the photograph's index: it keys the common random numbers of the radiance (SampleKey), so the flux of a state's view k is Φ_pixel(u, v, k, camera, poses[k], …).

source

The state

RadiometricCamera.CalibrationState — Type
CalibrationState

Everything the calibration works on: the fixed data (the board, a TexturedTarget; the quadrature, masks, observed images ϕ; the image size is the camera's) and the current parameters Θ̄ — the camera every view shares (camera, a RadiometricCameraModel), one pose per view (poses, camera → world), the material and the lighting.

source
RadiometricCamera.CalibrationState — Method
CalibrationState(board, settings, camera, poses, mat, light, targets; masks = nothing, δ = 0.02,
                 external_masks = nothing, support_min = 0, region = nothing, boundary_order = 2, backend = CPU(), ϕ = nothing,
                 channel = 0, mu_bounds = (0.0, 1.0), jacobian_chunk = 4,
                 sensor_models = fill(SensorModel(), length(poses)), weights = Unweighted(), quanta = fill(nothing, length(poses)),
                 sensor = NoSensorRecord(), photo_kind = Decoded(false))

channel (0: the three channels; 1–3: that channel alone, ONE residual per measured pixel, fit_channels): a single-channel state ties the other channels' lighting coefficients and refractive indices η to channel channel's (tie_channels), which no residual reads. The focus's bending smoothness rows, focus_smoothness, are set by focus_smoothness! (none at construction). mu_bounds (lo, hi) (material.mu_bounds; e.g. (0.6, 1.0): paper at most 40 % specular): the interval of the diffuse weight μ — the LM steps on the chart μ = lo + (hi − lo) σ(w) (MaterialVar), the closed-form solves clamp to it. jacobian_chunk (compute.jacobian_chunk): the dual partials per Jacobian kernel launch on a device (_jac_chunk; the CPU backend takes every slot in one chunk) — 4, not 15: local memory grows ~1.9 KB per partial, and from about 8 partials the kernel is bound by spill traffic, so 14 re-traces at 4 beat 4 re-traces at 15 by 4.3× (25,564-px view, RTX 4090, 2026-11-04); 4 also cuts the driver's local-memory reservation (bytes per thread × resident threads) ~5×. sensor and photo_kind: the photographs' ObservationModel with channel (observation_model(s), what the state's records state; by default decoded images, no sensor record: a state of synthetic renders). sensor_models: per view, the photograph's Core SensorModel (photo_set; the absent model, SensorModel(), by default: a decoded image, or a RAW photograph of a camera stated to have no characterisation). weights: the rows' weights (weighting.jl, masked_observations): Unweighted() (the default, rows as measured) or one 1/σ vector per view, each of its ϕ's length (whitened rows: the residuals and the Jacobians divided by the measured values' σ). quanta: per view, each row's RAW code step in its units (masked_observations), or nothing (a decoded image): what the data resolve (lm_abstol).

The state of the RadiometricCameraModel camera (one camera: geometric camera, focus surface, aperture radius and vignetting) seen from poses (camera → world, one per photograph). region (the run's imaged region, pixels): a tensor vignetting surface's nodes outside it are dependent (vignetting_rule, extrapolated with a zero boundary_order-th difference), its parameters the interior ones; a radial profile's nodes with less than support_min of the mean data weight are dependent the same way, continuing the supported ones with that order (RadialSupportRule). Builds the masks from the initial views (∩ external_masks) unless masks is given. Float64 targets are kept by reference (no copy). When the masked observation vectors ϕ are given (built one photo at a time from masked_vector, e.g. for full-resolution photos that do not fit in memory together), targets may be empty placeholder arrays.

source
RadiometricCamera.board_surface — Method

The board's own state: its warping h, the print's edge parameters and the in-plane print error (VisualRadiometryToolkitCore's TargetState, the state of the state's TexturedTarget).

source
RadiometricCamera.photometric_residuals — Method

Residual vectors 𝔯_k = Φ_k − ϕ_k in the measured values' units (unweighted). One view at a time, straight from the masked flux vector of the flux kernel on the state's backend (_flux_device, same pixel order as masked_vector): a full-size H × W × 3 image per view (290 MB each at 4256 × 2848) is what pushed the 16-view full-resolution runs over the container cap. The diagnostics' residuals (the model is ϕ + 𝔯); the cost's are residuals(s) (Core's residuals).

source
RadiometricCamera.radiometric_target — Method
radiometric_target(s::CalibrationState) -> RadiometricTarget

The state's calibration target: the board's geometric target (Core's target of its posed target; nothing on a board without one), the warping h with the aspect of the board's page and the target's radiometry (RadiometricTarget).

source
RadiometricCamera.set_pose! — Method
set_pose!(s::CalibrationState, k, pose::EuclideanMap) -> s

Replace the pose Θ_e of photograph k (Core's EuclideanMap, camera → world, metres); the camera is kept.

source
RadiometricCamera.set_radiometric_target! — Method
set_radiometric_target!(s::CalibrationState, t::RadiometricTarget) -> s

The state's material, board warping and the print's edge parameters from t (its geometric target is the run's board's). A warping learned on a page of another aspect than the run's board is an ArgumentError (board_surface).

source

Closed-form solves

RadiometricCamera.PixelParts — Type
PixelParts{J, L3, NS, F}

Per-pixel quantities for the linear solves: for every sensor sample k the aperture-integrated light responses Bd[k], Bs[k] = Σ_l w_l (Bd, Bs) (3 × J each) and the sensor weights w[k] and positions 𝐩[k], in the float type F of the render settings. Everything the solves need follows without re-rendering: I_k(a, μ) = (μ Bd[k] + (1−μ) Bs[k]) a, Md = Σ_k w_k V(𝐩_k) Bd[k], Ms likewise (_linear_rows).

source
RadiometricCamera.RadiometryParts — Type
RadiometryParts

The PixelParts of every masked pixel of every view (view order, then pixel order), the measured values ϕ (the measured channels per pixel, the same order) and their rows' weights w (weighting.jl: Unweighted(), or 1/σ per row), on the state's backend: what all_parts renders once and the closed-form solves read.

source
RadiometricCamera.all_parts — Method
all_parts(s::CalibrationState) -> RadiometryParts

The parts of every masked pixel, rendered once on the state's backend: Core's pointwise! of _PixelPartsAt (device/jacobiankernels.jl) per view, in Float64 on every backend, as the nodal heights' path (`height_float`): the closed-form solves are exact least squares on them.

source
RadiometricCamera.pixel_parts — Method
pixel_parts(u, v, k, camera, pose, mat::Material, light::EnvironmentLight, board::TexturedTarget, settings::RenderSettings) -> PixelParts

THE PixelParts of Julia's 1-based pixel (u, v) of photograph k, camera (a RadiometricCameraModel) at pose (camera → world), in the settings' float type: the sensor and aperture quadratures evaluated once, so the closed-form solves of Θ_l, Θ_v and μ (solve_linear_blocks!) need no re-rendering. The sample keys are k's, so the Monte Carlo radiance matches Φ_pixel's. The vignetting is not applied: it is one of the parts' linear factors.

source
RadiometricCamera.solve_linear_blocks! — Method
solve_linear_blocks!(s; parts = all_parts(s), light = true, vignetting = true, mu = true, sweeps = 1, reltol = 1e-4,
                     verbose = false, joint = false) -> s

Block coordinate descent over the closed-form blocks, Θ_l → Θ_v → μ per sweep (or the joint LM of solve_radiometry_gn! when joint), on parts rendered once (the geometry, material and quadrature are fixed, so every run is exact for the current state; a caller that solves twice on one state gives its parts). The blocks are coupled (the flux is bilinear in V and Θl), hence sweeps > 1 until the parts cost falls by less than reltol of its value. One sweep starts every run. `vignettingsmoothnessandgcvrecordaresolveΘv!'ssmoothnessweightandgcv_record; the joint LM has no smoothness penalty, sojointwith a nonzero weight is anArgumentError`.

source
RadiometricCamera.solve_radiometry_gn! — Method
solve_radiometry_gn!(s, parts; light = true, vignetting = true, mu = true, max_iter = 40, ftol = 1e-12, verbose = false)
    -> (ReturnCode.T, StopRule)

JOINT least squares over the closed-form blocks — lighting Θ_l, vignetting Θ_v (on the null space of the gauge V(𝐜) = 1, always held) and μ — by the stack's Levenberg–Marquardt, Core's chart LM (lmsolve_chart!: NLLSsolver, Levenberg's λ·I, LM_DAMPING), on the precomputed parts (no re-rendering). Its normal equations are one reduction kernel on the state's backend (_radiometry_normal_row!; the precedent of Estimation's refine_camera): only the N × N step is the host's. The flux is BILINEAR in (Θ_v, Θ_l) and affine in μ, so block coordinate descent (solve_Θ_l! → solve_Θ_v! → solve_μ!) creeps along the coupled direction: on synthetic data generated by the model itself it stopped 8 % away from the true V after 10 sweeps (FX3 fisheye, 2026-10-13); the joint step converges quadratically near the minimum. Exact Jacobian rows from the parts (_linear_rows, the parts kernel's): ∂Φ_c/∂P_q = Σ_s w_s B_q(𝐩_s) I_{s,c}, ∂Φ_c/∂a[c,j] = (μ M_d + (1−μ) M_s)[c,j], ∂Φ_c/∂μ = Σ_j a[c,j] (M_d − M_s)[c,j]. μ moves on the LM's bounded chart μ = lo + (hi − lo) σ(w) (material.mu_bounds, _μ_chart). max_iter (accepted iterations) and ftol (relative cost decrease) are Core's LM stop settings (LmStops), the stall postcondition's tolerance Core's of record ([lm] stationarity_tol). Returns the stack's termination record (Core's ReturnCode and StopRule); with nothing free, (ReturnCode.Success, ClosedForm).

source
RadiometricCamera.solve_Θ_l! — Function
solve_Θ_l!(s, parts = all_parts(s)) -> s

Linear least squares for the SH coefficients (per measured channel, fit_channels), all views stacked; a single-channel state's other channels follow the measured one (tie_channels).

source
RadiometricCamera.solve_Θ_v! — Function
solve_Θ_v!(s, parts = all_parts(s); smoothness_weight = 0.0, gcv_record = nothing) -> s

Linear least squares for the vignetting nodes (channels stacked, achromatic V), with the gauge V(𝐜) = 1 held exactly (the centre's direction absent from vignetting_basis(s), gauge_basis). The unknowns are the free directions of vignetting_basis(s): a tensor surface's nodes outside the run's imaged region are dependent (Core's BoundaryRule), not unknowns — a radial profile's below support_min of the data weight likewise (RadialSupportRule) — and a radial profile's first two nodes move together (the pole tie, V′(0) = 0).

smoothness_weight β > 0 adds the P-spline penalty λ ‖D vec(P)‖² over the free nodes (vignetting_smoothness: third differences along the lattice axes, so a field quadratic along each axis costs nothing) with λ = β Σϕ² / N / m̄ (N the free directions, m̄ the mean positive eigenvalue of DᵀD: Core's penalty_scale), so β means what the grid smoothness's does. :gcv selects β by Estimation's generalized cross-validation (gcv_curve, gcv_select) on this solve's own linear system, and pushes the selection to gcv_record (a vector; nothing: not recorded). 0 is the unpenalized solve, unchanged; without a window of 4 free nodes along either axis there is no row and the solve is the unpenalized one.

source
RadiometricCamera.solve_μ! — Function
solve_μ!(s, parts = all_parts(s)) -> s

Affine one-parameter least squares for μ: Φ = S + μ (D − S), clamped to the state's mu_bounds: one Gauss–Newton step (exact: Φ is affine in μ) of the μ-only normal equations, the reduction kernel's (radiometry_normal_equations, the additive chart).

source

Levenberg–Marquardt

RadiometricCamera.ApertureVar — Type
ApertureVar(r)

Θr block: the aperture radius r (metres), one variable on its log chart (the step is d ln r, NLLSsolver.update below). It has no bounds: the chart keeps r > 0 (RC 0.11.0: the inert lo / hi, once `camera.rmin/camera.r_max, are gone; a held aperture isfixed = ["aperture"]`, the block removed from the solve).

source
RadiometricCamera.LightingVar — Type
LightingVar(light; channel = 0)

Θl block: the 3 × J SH coefficient matrix in vec (column-major, a[c, j]) order, parametrised as a = scale · â with scale = max|a| at construction so that the optimiser sees O(1) parameters — NLLSsolver's Levenberg–Marquardt damps with λ·I, which freezes a block whose natural scale is 10⁵ (photographs in linear units against the unnormalised aperture integral). A single-channel state's block (channel = c > 0) is the measured channel's J coefficients alone: every channel's row follows it (`tiechannels`), as no residual reads the others.

source
RadiometricCamera.MaterialVar — Type
MaterialVar(mat, surface, board = nothing; height = 0, inplane = false, fixed = (), mu_bounds = (0.0, 1.0))

Θm block: the 8 nonlinear parameters (`roughnessink, roughnesspaper, refractiveindexink, refractiveindexpaper; boxed bybounds), μ ∈ [0, 1] and the scene'sTargetState` (its printed edge, δ and σprint, is never a parameter): with height > 0 (NH = height_nparams(height)) the board warping h through its HEIGHT_NFREE free parameters (h += B y with B = height_basis(board), the board's page: Core's TargetManifold of that warping's height field — the piston and the two tilts, the poses', are never parameters; dual-number columns), with inplane = true (NI = INPLANE_NC) the in-plane print error (a, u) of TargetState.inplane (Core's Aspect ∘ Skew, inplane_calibration: additive, unbounded, no gauge — a rigid member and a scale are the poses'; dual-number columns). The surface shares the material block because NLLSsolver caps a cost block at ten variable dependencies, which the per-tile blocks already use.

fixed = (:material,) holds Θm (the 8 nonlinear parameters and μ) at its value although the block stays variable (HM = true, the type's last parameter: `materialfixed): its Jacobian columns are zero (no AD scatter, no analytic μ column) andupdateleaves it unchanged, while the block's warping and in-plane parameters remain free — a held material while a surface parameter rides the block (the problem builders'fixed,holdmaterial). The block size and every other column position are unchanged; the LM's λ·I damping gives the zero columns a zero step.mubounds(lo, hi): μ's chartμ = lo + (hi − lo) σ(w)(material.mubounds, the state'smu_bounds`).

valid is false for a block whose update is not finite (a NaN of a singular solve). Every residual of the block checks it (is_valid) and returns NaN, so NLLSsolver rejects the step; an accepted state is always valid.

source
RadiometricCamera.PerViewResidual — Type
PerViewResidual{N}

Cost block of view k: residual Φ_c(𝐮; Θ̄) − ϕ_c(𝐮) over the masked pixels. Depends on (pose_k, distortion, focus, aperture, material, vignetting, lighting) (variable indices idx).

source
RadiometricCamera.build_problem — Method
build_problem(s::CalibrationState; fixed = (), height_degree = 0, inplane = false) -> (problem::LmProblem, idx)

The per-view LM problem at the state s: VisualGeometryToolkitCore's LmProblem (the stack's one LM, lmsolve_chart!) with one pose variable (_PoseBlock) per view, the shared distortion / focus / aperture / material / vignetting / lighting variables and one PerViewResidual per view. fixed is the one holding keyword: the blocks it names (of (:poses, :distortion, :focus, :aperture, :material, :vignetting, :lighting)) are held — the problem's fixed variables, idx.free the free mask; :material holds Θm alone while a free surface parameter rides the block (`holdmaterial) —, the surface parameters it names (SURFACEHOLDS::height,:inplane) are held at their start, and its other entries hold the lens model's parameters by Core's names in the lens block (lensfree;(:cx, :cy, :k3),:aspect` the aspect fy/fx); an entry that is none of these is an ArgumentError. A lens with no free parameter is held. The model's structure (as the grid route's `buildproblemgrid): withheightdegree > 0the material block carries the board warping'sHEIGHTNCnodal heights (MaterialVar{Float64, HEIGHTNC}: HEIGHT_NFREE free parameters, h = h₀ + B y withB = height_basis(s.board)); withinplanethe in-plane print error(a, u)of the surface (Core'sAspect ∘ Skew, two dual-number columns) — each unlessfixed` holds it.

source
RadiometricCamera.extract_variables — Method
extract_variables(s, vars, idx) -> (camera, poses, mat, surface, light)

The camera, the poses, the material, the surface and the lighting encoded in a variable vector (non-mutating; used by read_back! and tracing).

source
RadiometricCamera.focus_block — Method
focus_block(f) -> VgtkCore.SubsetManifold

The focus block of the LM: Core's restrict(ParameterManifold(f; box), free) of the focus surface f — its nodal values stepped additively and clamped at 0 (the box, t̂ᵢ ≥ 0), every node free. Its model is the focus (VgtkCore.model).

source
RadiometricCamera.lens_free — Method
lens_free(camera; fixed = ()) -> (names, held)

The free parameters of a parametric model's LM block, by Core's parameter names of its pixel camera, in the camera's order: every parameter of parameter_names(model(camera)) ((:f, :aspect, :skew, :cx, :cy, …the lens's)) but the skew (the gauge, held always) and those fixed names — the stack's one parameter-holding keyword, expanded by Core's free_parameter_names (parameter names or groups such as :k, :p; an entry that names nothing is an ArgumentError). Holding :aspect (fy/fx) moves the two focal lengths together at their ratio. Holding cx, cy removes the principal-point ↔ rotation gauge of narrow-FOV lenses. held: no parameter is free (fixed = parameter_names(model(camera)), a Core lens to be sampled into a grid) — the block then keeps the default names, which NLLSsolver requires to be non-empty, and run_lm! holds it fixed. The grid lenses have no such block: they are refined per tile (run_lm_grid!).

source
RadiometricCamera.lens_manifold — Method
lens_manifold(camera; fixed = ()) -> SubsetManifold

The per-view lens block of a parametric model (Core's pixel camera): VisualGeometryToolkitCore's ParameterManifold of its model — each parameter moved by the chart that keeps it inside its parameter_bounds (f and the aspect through a log, the double sphere's ξ through a log and α through a logit, an unbounded coefficient additively) — with the LM's search box lm_box (Core clamps every step into it) and the image-size coordinate scale lm_scale, restricted to lens_free's names. Its model is VgtkCore.model(block).

source
RadiometricCamera.read_back! — Function

read_back!(s, problem, idx, extract = extract_variables): write the optimised variables of problem back into the state, read through the route's extract (extract_variables per view, extract_variables_grid per tile): the one read-back of both LMs.

source
RadiometricCamera.run_lm! — Method
run_lm!(s; maxiters = 10, maxtime = 7200.0, fixed = (), height_degree = 0, inplane = false, kwargs...) -> (; code, rule, iterations, cost)

Levenberg–Marquardt over all parameter blocks but those fixed names (of (:poses, :distortion, :focus, :aperture, :material, :vignetting, :lighting)), the surface parameters it names (:height, :inplane) and the lens block's parameters fixed names by Core's parameter names (lens_free; default none: every parameter but the skew is free; :aspect ties the focal lengths): one holding keyword (build_problem, with the model's structure height_degree and inplane). iter_callback(it, cost, camera, poses, mat, surface, light) sees the current best variables after every iteration and trace collects the per-iteration snapshots (_lm_callback, as run_lm_grid!); with a file lm_log (lm.log) a line per iteration is appended to it (_lm_log). The solve is VisualGeometryToolkitCore's one LM, lmsolve_chart! on build_problem's LmProblem under LmStops (_lm_stops: Levenberg's λ·I, LM_DAMPING) — the RELATIVE cost decrease reldcost (its ftol), the relative step test xtol_rel ([lm] xtol_rel) and the absolute step max-norm xtol (Core's of record by default); no absolute cost decrease test — the cost is in the photographs' squared units, dimensionless when the rows are whitened (a two-view 32 × 32 fixture starts at ≈ 2e-4), so an absolute threshold of 1e-12 stopped the solver with the aperture, μ and the lighting still drifting together along a flat direction. Returns Core's termination record (code, a ReturnCode: Success at a tolerance stop — Core 0.11.0, converged by definition — or at a stationary point after the rejection cap; rule, a StopRule; iterations; cost, ‖r‖² at the solution).

source
RadiometricCamera.Θ̄_snapshot — Method
Θ̄_snapshot(s; camera = s.camera, poses = s.poses, mat = s.mat, surface = board_surface(s), light = s.light) -> NamedTuple

Everything needed to re-render the state later (camera, poses, mat, surface, light).

source
RadiometricCamera.CalibrationEstimate — Type
CalibrationEstimate(camera, poses, target, light)

The estimate of a radiometric calibration (refine_calibration!, calibrate): the calibrated camera (a CalibratedCamera: the RadiometricCameraModel — the geometric camera, the focus surface, the aperture radius and the vignetting — with the observation model its photographs were read under and its render settings), the poses (camera → world, one per photograph), the radiometric target (the printed target, its warping, its material and print) and the light.

source
RadiometricCamera.CalibrationMetadata — Type
CalibrationMetadata

A radiometric calibration's diagnostics (a Core FitResult's metadata): the LM's trace (one entry per LM iteration and per closed-form sweep), the cost and relative RMS of the start (linear_cost, linear_rms: after the closed-form start) and at the end (final_cost, final_rms), the LM's wall time (seconds), the last LM chunk's record (solver: Core's lmsolve_chart!'s (; code, rule, iterations, cost), nothing without an iteration), the non-finite Jacobian entries replaced, by block (scrubbed), and the calibrated camera's folds (folds: Core's folded_pixels over its coverage, calibrated_folds; nothing for a parametric camera), and the focus nodes of the run's support that ran away (focus_runaway: t̂ ≤ 0 or non-finite, focus_runaway; empty when none).

source
RadiometricCamera.calibrate — Method
calibrate(geometry::StartGeometry, photographs; options, device = default_device()) -> FitResult{CalibrationEstimate, CalibrationMetadata}
calibrate(camera, poses, observations, photographs; target, options, device = default_device())

A radiometric calibration in one call: start_calibration (with the start's options, start_options(options)), then refine_calibration! of that state. The state refined is the one a start record rebuilds (save_calibration_start → load_calibration_start, bin/refine.jl's path): the start reads no refinement-only key (REFINE_ONLY_KEYS), and a record carries the start's values bit for bit.

source
RadiometricCamera.refine_calibration! — Method
refine_calibration!(state; options) -> FitResult{CalibrationEstimate, CalibrationMetadata}

Refine the started radiometric state state (start_calibration or load_calibration_start) in place: the Levenberg–Marquardt over every block the options leave free (fixed), on the route the camera's type picks (lm_route: per view, in a parametric camera's own parameters; per tile for a SplineLens camera), optionally in chunks with a closed-form sweep of the lighting, the vignetting and μ between them (sweep.lm_chunk), up to lm.max_iter iterations and lm.max_time seconds. The result's estimate is the refined CalibrationEstimate; its retcode / stop_rule the LM's termination record (Core 0.11.0: a tolerance stop converged, the rejection cap judged by the stall postcondition at the final state) — (Failure, ShapeGate) when the calibrated SplineLens camera still folds over its coverage (fold_termination: no calibration; the camera is held to the coverage assertion too, calibrated_folds) or a focus node of its support runs to t̂ ≤ 0 (focus_runaway, the same validity_gate), iterations the LM iterations, rms the final relative RMS over the n measured values.

source
RadiometricCamera.load_state_into! — Method

Load a state (load_state) into s (the poses of the views by name; the camera's lens, focus and aperture; the target's material, warping and printed edge; the vignetting and the lighting when their sizes match). Returns (vig_ok, light_ok). The state's observation model must be the run's (observation_model(s): the same sensor record, photograph kind and channel): a state continues, or predicts, only photographs read as it was estimated on — another is refused naming both. Under sensor_model = OffSensorModel() (camera.sensor_model = "off") a state estimated under a sensor record continues a run that reads the same photographs without it (the run's resolution warned, observation_model's stated).

source

The grid models' tiles

RadiometricCamera.build_problem_grid — Method
build_problem_grid(s; patch = GRID_PATCH, fixed = (), height_degree = 0,
                   smoothness = nothing, inplane = false) -> (problem::LmProblem, idx)

The per-tile LM problem over the grid-lens state, VisualGeometryToolkitCore's LmProblem (the stack's one LM, lmsolve_chart!): pose variables per view, one patch block per grid patch, the shared focus/aperture/material/vignetting/lighting blocks, and one PerTileResidual per non-empty image tile (ndeps = 10 = NLLSsolver's MAXARGS). Held (the problem's fixed variables, idx.free the free mask): the dependent patches and the blocks fixed names (of (:poses, :grid, :focus, :aperture, :material, :vignetting, :lighting), :grid the patch blocks; :material holds Θm alone while a free surface parameter rides the block, _hold_material); another name is an ArgumentError. The patch size must satisfy p ≥ 5 (the 2 × 2-window guarantee) and divide both grid dimensions — and it must stay SMALL: NLLSsolver's Hessian accumulation (updatesymA!) slices the per-cost Hessian with nvars-sized static ranges and static broadcasts, so a patch of 8 × 8 nodes (128 parameters) makes LLVM materialize fully unrolled 128 × 128 static-array code for every dep pair — a codegen memory explosion (hundreds of GB). 5 × 5 nodes (50 parameters) compiles fine; pick the grid size as multiples of 5 (default 65 × 50).

  • height_degree > 0: the material block also carries the board warping h (board_height; the HEIGHT_NFREE free nodal-height parameters, dual-number columns). A FIXED warping (nodal heights set, degree 0) is rendered by every route; the free columns need the grid route.
  • inplane: the material block also carries the in-plane print error (a, u) of the surface (Core's Aspect ∘ Skew, inplane_calibration; two dual-number columns, additive, no gauge). A fixed error (parameters set, inplane = false) is rendered by every route.
  • :height, :inplane in fixed (SURFACE_HOLDS): that surface parameter held at its start (the block carries no columns for it), as on the per-view route.

The parameters are the nodes the lens holds (Core's present_nodes; with_present, grid_present): a pixel whose window holds an absent node is an ArgumentError (no residual reads an absent node), and a patch block with no present node is no variable.

  • smoothness (a GridSmoothness, grid_smoothness; nothing = none): its rows, one cost block per patch block or pair of them.
source
RadiometricCamera.run_lm_grid! — Method
run_lm_grid!(s; patch = GRID_PATCH, maxiters = 10, kwargs...) -> (; code, rule, iterations, cost)

Joint LM over the per-tile grid problem (all blocks; fixed as in run_lm! with :grid for the patch blocks in place of :distortion). height_degree and smoothness as in build_problem_grid, the problem and its held blocks its; iter_callback(it, cost, camera, poses, mat, surface, light) sees the current best variables after every iteration, and lm_log as run_lm!'s. The solve and its stopping tests and termination record as run_lm!'s (VisualGeometryToolkitCore's lmsolve_chart! under _lm_stops).

source