refine op• 資料種類:voxel × voxel × angle → angle
• 呼叫: 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)(要直接呼叫實作,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);從台帳取用則 ops3d.get("refine_rotation_z"))
• 經台帳呼叫的回傳值: fullseye.ledger.refine_rotation_z(...) 只回傳**宣告的 out 型別 angle 的值**(底層函式還會回傳輔助資訊)。需要被捨棄的部分時,請用 fullseye.ledger.refine_rotation_z.raw(...),或直接呼叫 match3d.refine_rotation_z。
• GPU:該運算子有 GPU 路徑(device="cuda")
z 軸旋轉角的 Gauss-Newton 精化(SSD 上的 Lucas-Kanade,單參數)。
> 以下的詳細說明為原文 —— 摘要與標題已翻譯。
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)と実行反復数。
• 範例資料目錄(下載 URL / 授權) —— 2-D 用 skimage.data(BSD/公有領域)加合成圖,3-D 給出真實資料源(Stanford/PDS 等)的下載 URL。
• 運算子來歷與參考文獻 —— 該運算子族所依據的研究/方法出處。
• refinement — py -3.11 examples_3d/refinement.py
angle 作為輸入)refine)refine_peak_newton · refine_translation_lk · refine_lm · icp_point2point_3d · icp_point2plane
*Provenance: match3d.py — 3D 運算子登記表。本條目由 tools/opdocs.py md 自動產生(請勿手動編輯)。*
© 2026 Kazufumi Furuse — Fullseye operator documentation. Licensed under Apache-2.0.