match_localize op• Data kinds: voxel × voxel → position
• Call: import fullseye as fs; fs.ledger.match_shape_3d(vol, template, device='cpu', mc=0.05, subvoxel=True) (to call the implementation directly, import match3d; match3d.match_shape_3d(vol, template, device='cpu', mc=0.05, subvoxel=True); from the registry, ops3d.get("match_shape_3d"))
• Return value through the ledger: fullseye.ledger.match_shape_3d(...) returns only the declared out type position (the underlying function also returns auxiliary values). When you need what was dropped, use fullseye.ledger.match_shape_3d.raw(...) or call match3d.match_shape_3d directly.
• GPU: this op has a GPU path (device="cuda")
3-D shape-based (gradient-orientation) matching = the voxel version of the 2-D shapematch_gpu ("contour matching").
The sum of dot products of unit gradient vectors of template and scene (Steger style). Invariant to intensity/contrast, it measures the match by edges/shape. score(pos)=Σ<û_scene(pos+dt), û_model(dt)>/n, computed with conv3d over 3 components.
Procedure: sobel3d on both volumes → only voxels whose magnitude exceeds mc are made unit vectors (the rest are 0). The 3 components of the template's unit gradient are used as kernels, conv3d is applied component-wise to the scene's unit gradient and summed, and the result is divided by the number of valid template voxels n. The score is in [−1, 1]: 1 is a perfect match (all gradient directions aligned), and −1 under contrast inversion.
• mc: threshold on the raw output (32 times the true gradient) of sobel3d. The smaller it is, the more noise gradients from flat regions
enter the vote.
• Position: the coordinates of the return value [score, z, y, x] (float64 array) are where in the scene the template centre voxel (index T//2)
lands. Positions where the template does not fit entirely are set to 0, so if the template is larger than the scene everything stays 0 and index (0,0,0) is returned (no exception).
• subvoxel=True refines to the centroid of the positive scores in the ±2 neighbourhood of the argmax (accel_match._subvoxel_com).
Downstream: refine_translation_lk (corner convention, so subtract T//2) / refine_lm. It is not invariant to rotation (align the rotation first with match_logpolar_z).
• 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.
• matching_localize — py -3.11 examples_3d/matching_localize.py
position as input)refine_peak_newton · refine_translation_lk · refine_lm · fuse_to_voxel
match_localize)match_chamfer_3d · match_curvature_3d · match_hough_3d · match_mip_2d · match_points_ncc
*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.