refine op• Data kinds: voxel × voxel × position → table
• Call: import fullseye as fs; fs.ledger.refine_lm(scene, template, init_pos, device='cpu', iters=50, scale=True, gain=False, lam0=0.001, tol=1e-08) (to call the implementation directly, import match3d; match3d.refine_lm(scene, template, init_pos, device='cpu', iters=50, scale=True, gain=False, lam0=0.001, tol=1e-08); from the registry, ops3d.get("refine_lm"))
• GPU: this op has a GPU path (device="cuda")
Sub-voxel refinement of the translation (plus isotropic scale / intensity gain) by Levenberg-Marquardt.
Starting from the coarse match position init_pos (template centre in scene coordinates [z,y,x]), solves forward-additive Lucas-Kanade with damped Gauss-Newton (LM), minimising the SSD
E(p) = Σ_x [ I(W(x;p)) - g·T(x) ]²
over p. A downstream stage that converges coarse estimates from integer NCC / Fourier-Mellin / Hough to continuous coordinates.
Warp W(x;p) = t + s·(x - c_T) (c_T = template centre, t = translation, s = isotropic scale)
Jacobian ∂I(W)/∂p is obtained exactly by passing grid_sample through autodiff (analytic gradient of trilinear interpolation.
The fixed point coincides with the true SSD minimum → avoids the constant-factor bias of sobel, high accuracy).
LM Δp = -(H + λ·diag(H))⁻¹ b; on success (cost decrease) λ×0.4 damping, on failure λ×5 increase.
Arguments:
scene : scene volume (D,H,W).
template : template volume (Td,Th,Tw). Smaller than the scene.
init_pos : coarse template centre position [z,y,x] (voxel; e.g. [d,h,w] from NCC locate).
device : "cpu" / "cuda". Device-independent.
iters : maximum number of iterations (usually converges in 4-6).
scale : True optimises the isotropic scale s as well (4 parameters). False is translation only.
gain : True additionally optimises the luminance gain g (residual I(W)-g·T). Robust to brightness differences/noise.
lam0, tol : initial damping coefficient / convergence threshold (step norm, relative cost decrease).
Returns (dict):
pos : refined template centre [z,y,x] (continuous coordinates)
scale : isotropic scale (1.0 if scale=False)
gain : luminance gain (1.0 if gain=False)
cost : final SSD, rms: residual RMS per 1 voxel, iters: number of iterations run
• Sample-data catalog (download URLs / licences) — 2-D uses skimage.data (BSD/public domain) plus synthetic images; 3-D lists download URLs for real data sources (Stanford, PDS, …).
• Operator provenance and references — the sources of the research/methods this op family came from.
• refinement — py -3.11 examples_3d/refinement.py
table as input)fuse_to_voxel · mesh_select_lod
refine)refine_peak_newton · refine_translation_lk · refine_rotation_z · icp_point2point_3d · icp_point2plane
*Provenance: match3d.py — 3D operator registry. This per-op note is generated by tools/opdocs.py md (do not hand-edit).*
© 2026 Kazufumi Furuse — Fullseye operator documentation. Licensed under Apache-2.0.