refine_rotation_z — 3D `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")

Usage

Gauss-Newton refinement of the rotation angle about z (Lucas-Kanade on SSD, one parameter).

> The detailed description below is the original text — the summary and the headings are translated.

Fourier-Mellin 等の粗い z 軸回転推定(±3° 級)を、SSD を回転角 θ だけで最小化して高精度化

する下流精緻化器。scene ≈ rotate_z(template, θ_true) を仮定し、warp_z(template, θ) が scene に

一致する θ を求める。返り値の角は match_logpolar_z と同符号(scene = template を θ 回転)。

定式化: 残差 r(θ)=T_warp(θ)−S を θ で線形化。回転の steepest-descent image(解析ヤコビアン)

は、中心化格子 (X=W−cx, Y=H−cy) と warp 済みテンプレの空間勾配 (gx,gy) から

J = ∂T_warp/∂θ = (−gx·Y + gy·X)(rad あたり)。1 パラメータ GN 更新は Δθ = −(JᵀWr)/(JᵀWJ)。

回転で 0 詰めされた隅は valid マスク W で除外。step は max_step_deg で制限し発散を防ぐ。

実測(48³ 非対称 volume, CPU, 別補間器 scipy order=3 で scene 生成=inverse crime 回避):

clean 誤差 ~0.0006°、5% ノイズ 0.009°、10% ノイズ 0.017°(いずれも <0.3°)。捕捉レンジは

最低 ±10°、収束 3-5 反復・~12ms。粗推定 ±3° をそのまま使う場合(誤差 3°)比で ~5000 倍改善。

Parameters

----------

scene : array_like (D,H,W) 基準 volume(この姿勢へ template を合わせる)。

template : array_like (D,H,W) 回転させて scene に合わせるテンプレ volume。同一格子・同一中心。

init_angle_deg : float 粗推定角(deg)。Fourier-Mellin 等の初期値。

device : str "cpu" / "cuda"。device 非依存。

iters : int 最大反復数。

tol : float |Δθ|(deg)がこれ未満で収束打ち切り。

max_step_deg : float 1 反復あたりの角ステップ上限(deg、発散防止)。

Returns

-------

(angle_deg, n_iters) : (float, int) 精緻化角(deg)と実行反復数。

References (sample data, literature)

• 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.

Runnable examples (verified samples that actually call this op)

• refinement — py -3.11 examples_3d/refinement.py

Ops the type connects to (they accept `angle` as input)

fuse_to_voxel

Same category (`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).*

refine_rotation_z — 3D refine op