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, 1 매개변수).
> 아래 상세 설명은 원문입니다 —— 요약과 제목은 번역되어 있습니다.
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)と実行反復数。
• 샘플 데이터 카탈로그(DL URL / 라이선스) —— 2-D 는 skimage.data(BSD/public)+ 합성, 3-D 는 실데이터 소스(Stanford/PDS 등)의 DL 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 연산자 레지스트리. 이 op 노트는 tools/opdocs.py md 가 자동 생성합니다(직접 편집하지 마세요).*
© 2026 Kazufumi Furuse — Fullseye operator documentation. Licensed under Apache-2.0.