refine op• Data kinds: score × position → position
• Call: import fullseye as fs; fs.ledger.refine_peak_newton(score, idx, device='cpu', max_iter=12, tol=0.0001) (to call the implementation directly, import match3d; match3d.refine_peak_newton(score, idx, device='cpu', max_iter=12, tol=0.0001); from the registry, ops3d.get("refine_peak_newton"))
• Return value through the ledger: fullseye.ledger.refine_peak_newton(...) returns only the declared out type position (the underlying function also returns auxiliary values). When you need what was dropped, use fullseye.ledger.refine_peak_newton.raw(...) or call match3d.refine_peak_newton directly.
• GPU: this op has a GPU path (device="cuda")
Refine the integer peak of a score/correlation volume to sub-voxel accuracy by 3-D Newton (iterative optimisation).
Takes the integer peak idx returned by a coarse match (integer NCC / Fourier-Mellin ±3° / Hough ±0.5voxel) and iteratively moves it to the stationary point Δ=-H⁻¹g of a local 2nd-order model f(x)≈f0+gᵀΔ+½ΔᵀHΔ, converging to continuous coordinates. Unlike per-axis parabolic sub-pixel, it uses the full 3x3 Hessian (including the cross curvatures fzy,fzx,fyx), so it removes the coupling bias between coordinate axes even for rotated (cross-curved) anisotropic peaks.
Each iteration: sample the 27 neighbours around the current position trilinearly → build gradient g and the 6-component Hessian H by central differences, Δ=solve(H,-g). Clip each component to ±1 voxel (trust region), update the position, converge when |Δ|<tol. On a Gaussian peak the zero of the central-difference gradient coincides with the true peak, so it converges to the stationary point (a single step leaves 2nd-order model error and cannot get below ±0.05voxel, but iteration converges to ~0.02voxel). On real correlation surfaces where H is not negative definite (= not a maximum), it falls back to an ascent direction (gradient-ascent step) to prevent divergence.
score : array_like or torch.Tensor
3D score/correlation volume (D,H,W). Larger values are the peak.
idx : tuple[int,int,int]
Integer peak coordinates (z,y,x) (usually the unravelled argmax).
device : str
"cpu" / "cuda". Device for the torch operations.
max_iter : int
Maximum number of iterations (default 12).
tol : float
Convergence criterion (L2 norm of the update, default 1e-4).
numpy.ndarray
[score_peak, z, y, x] (after refinement). score_peak is the trilinearly interpolated score at the refined position.
• 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_translation_lk · refine_lm · fuse_to_voxel
refine)refine_translation_lk · 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.