refine op• Data kinds: voxel × voxel × position → position
• Call: import fullseye as fs; fs.ledger.refine_translation_lk(scene, template, init_pos, device='cpu', iters=30, tol=0.0001) (to call the implementation directly, import match3d; match3d.refine_translation_lk(scene, template, init_pos, device='cpu', iters=30, tol=0.0001); from the registry, ops3d.get("refine_translation_lk"))
• GPU: this op has a GPU path (device="cuda")
Sub-voxel refinement of the 3-D translation by inverse-compositional Lucas-Kanade with Gauss-Newton.
Starting from the integer initial position init_pos given by a coarse match (integer NCC / Fourier-Mellin / Hough), minimises the SSD Σ|I(x+p) − T(x)|² and converges to the sub-voxel translation p.
Being inverse-compositional (Baker–Matthews), the steepest-descent image SD = ∇T and the Hessian H = Σ SDᵀSD are precomputed only once before iterating, and each iteration is only "trilinear warp of the scene + residual + 3×3 linear solve Δp = H⁻¹ Σ SDᵀ(I(x+p)−T)". The translation composition is p ← p − Δp. For a pure translation warp ∂W/∂p=I, so SD=∇T can be used as is.
Coordinate system: both init_pos and the return value are where the template origin (corner, index 0,0,0) lands in the scene as (dz,dy,dx). Matches the corner convention of sobel3d / grid_sample (note it differs from the centre convention of NCC (ncc_locate_3d) by T//2).
scene : (D,H,W) array_like
Volume to search.
template : (Td,Th,Tw) array_like
Template to register (smaller than the scene).
init_pos : (3,) sequence
Integer initial position (dz,dy,dx) = scene coordinates of the template origin.
device : str
"cpu" / "cuda" etc. Device-independent.
iters : int
Maximum number of iterations.
tol : float
Stop as converged when ‖Δp‖ falls below this value.
pos : (3,) np.ndarray (float64)
Refined sub-voxel position (dz,dy,dx).
• Assumes a smooth (band-limited) density field. If the integer initial value is within ±0.5 to 1 voxel of the ground truth, usually 5 to 8 iterations give ‖err‖ < 0.05 voxel (at low noise). Measured (independent cubic-spline GT):
noise-free mean 0.008 / max 0.013 voxel (≈6 iterations, ≈1.2ms per call), about 60× better than the NCC sub-voxel
baseline (mean 0.56 voxel).
• grad_scale=32 is the fixed scale of the separable sobel3d (derivative [-1,0,1] × smoothing [1,2,1]²) (measured 32.0 on a linear ramp). It normalises to the true gradient and corrects the scale of Δp.
• A small Levenberg regularisation is added to H to prevent numerical breakdown on flat templates with little gradient.
• 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
position as input)refine_peak_newton · refine_lm · fuse_to_voxel
refine)refine_peak_newton · refine_lm · 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.