refine op• Data kinds: voxel × voxel × angle → angle
• Call: import fullseye as fs; fs.ledger.refine_rotation_z(scene, template, init_angle_deg=0.0, device='cpu', iters=40, tol=0.001, max_step_deg=5.0) (to call the implementation directly, import match3d; match3d.refine_rotation_z(scene, template, init_angle_deg=0.0, device='cpu', iters=40, tol=0.001, max_step_deg=5.0); from the registry, ops3d.get("refine_rotation_z"))
• Return value through the ledger: fullseye.ledger.refine_rotation_z(...) returns only the declared out type angle (the underlying function also returns auxiliary values). When you need what was dropped, use fullseye.ledger.refine_rotation_z.raw(...) or call match3d.refine_rotation_z directly.
• GPU: this op has a GPU path (device="cuda")
Gauss-Newton refinement of the rotation angle about z (Lucas-Kanade on SSD, one parameter).
A downstream refiner that takes a coarse z-axis rotation estimate (±3° class) from Fourier-Mellin etc. and makes it precise by minimising the SSD over the rotation angle θ alone. It assumes scene ≈ rotate_z(template, θ_true) and finds the θ for which warp_z(template, θ) matches scene. The returned angle has the same sign as match_logpolar_z (scene = template rotated by θ).
Formulation: linearise the residual r(θ)=T_warp(θ)−S in θ. The steepest-descent image of the rotation (analytic Jacobian) is built from the centred grid (X=W−cx, Y=H−cy) and the spatial gradient (gx,gy) of the warped template as J = ∂T_warp/∂θ = (−gx·Y + gy·X) (per rad). The 1-parameter GN update is Δθ = −(JᵀWr)/(JᵀWJ). Corners filled with 0 by the rotation are excluded by the valid mask W. The step is limited by max_step_deg to prevent divergence.
Measured (48³ asymmetric volume, CPU, scene generated with a different interpolator scipy order=3 = avoiding the inverse crime):
clean error ~0.0006°, 5% noise 0.009°, 10% noise 0.017° (all <0.3°). The capture range is at least ±10°, convergence in 3-5 iterations, ~12ms. About ~5000× better than using the coarse ±3° estimate as is (error 3°).
scene : array_like (D,H,W) Reference volume (the template is aligned to this pose).
template : array_like (D,H,W) Template volume that is rotated to match scene. Same grid, same centre.
init_angle_deg : float Coarse estimate angle (deg). Initial value from Fourier-Mellin etc.
device : str "cpu" / "cuda". Device-independent.
iters : int Maximum number of iterations.
tol : float Stops as converged when |Δθ| (deg) falls below this.
max_step_deg : float Upper limit of the angle step per 1 iteration (deg, prevents divergence).
(angle_deg, n_iters) : (float, int) Refined angle (deg) and 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
angle as input)refine)refine_peak_newton · refine_translation_lk · refine_lm · 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.