match_pose op• 데이터 종류: voxel × voxel → shift
• 호출: import fullseye as fs; fs.ledger.match_phase_3d(a, b, device='cpu', window='tukey', whitening=0.25)(구현을 직접 호출하려면 import match3d; match3d.match_phase_3d(a, b, device='cpu', window='tukey', whitening=0.25), 원장에서 가져오려면 ops3d.get("match_phase_3d"))
• GPU: 이 연산자는 GPU 경로가 있습니다(device="cuda")
3D 위상 상관(FFT). b 를 a 에 맞추는 정수 시프트 (dz,dy,dx) 를 돌려줍니다.
Reddy & Chatterji의 3D 버전. 교차 파워 스펙트럼 R = A·conj(B)를 |R|^whitening으로 나누어 역 FFT한 피크 = 평행 이동. 템플릿 불필요, 전체 volume, O(N log N). 회전/스케일은 별도로 처리(PCA / log-polar).
인수: a, b는 같은 형상의 3-D 배열(다르면 ValueError). float32로 바꿔 FFT한다. window: "tukey"(기본값, α 0.5), "hann", None(창 없음) —— 창은 평균을 뺀 뒤 곱하며, 길이 8 미만인 축에는 곱하지 않는다. whitening: |R|의 지수(0~1, 1 = 고전적 위상 상관의 완전 백색화, 0 = 단순 상호상관, 기본값 0.25).
반환값: int tuple (dz, dy, dx), 각 축 (−N/2, N/2]로 접어 넣은 값. 의미는 np.roll(b, (dz,dy,dx), axis=(0,1,2)) ≈ a(b를 이만큼 움직이면 a와 겹친다).
★기본값을 바꾼 이유(2026-10-06, filters_freq.phase_correlation_fft와 같은 함정): 0.4.0까지의 "창 없음 + 완전 백색화(eps 1e-9)"는, 대역이 제한된 volume의 비주기적 잘라내기(겹침이 부분적인 2개의 촬영이라는 일반적인 사용법)에서, 신호가 없는 주파수 bin (잘라낸 가장자리의 불연속에서 오는 누설과 반올림)이 백색화로 신호가 있는 bin과 같은 가중치가 되어 올바른 이동을 반환하지 못했다 —— 저역 통과한 32³ 잘라내기에서 이동 10가지 중 0 / 10, 64³에서도 0 / 10. np.roll의 주기적 이동에서는 정확하므로 그것만 쓰는 게이트로는 보이지 않았다. 3차원에서는 2차원(기본값 Hann + 0.5)보다 창이 겹침을 더 깎고 백색화가 잡음 bin을 들어 올리기 쉽다: 실측 적중 수(이동 10가지 × 시드 3조)에서, 32³, 이동 ±6의 저역 잘라내기는 Hann + 0.5가 11 / 30, Hann + 0.25가 19 / 30, Tukey + 0.25가 28 / 30, 주기적 이동은각각 9 / 30, 18 / 30, 27 / 30(이전 30 / 30). 64³와 (1, 256, 256)에서는 3가지 모두 전부 적중(이전은 저역 잘라내기에서 0). 더 낮은 대역(차단 0.10)의 32³는 어느 것이나 6 / 10 이하로, 여기는 여전히 어렵다. 그래서 기본값은 Tukey(α 0.5) + 0.25. 이전 동작은 window=None, whitening=1.0(수치도 같은 경로).
• 순환 상관이므로 삐져나간 부분은 반대쪽에서 돌아 들어온다. 이동이 volume의 절반을 넘으면 부호가 반전되어 보인다. 창을 쓰는 기본값에서는 작은 volume(32³)의 큰 주기적 이동(변의 2/10)에서 빗나갈 수 있다(위의 27 / 30) —— 주기적 이동임을알고 있다면 window=None, whitening=1.0.
• 전부 0인 volume은 0이 되어 index 0을 반환한다.
• 정수 정밀도. 서브복셀은 refine_translation_lk / refine_peak_newton으로.
• 회전, 스케일이 있으면 효과가 없다(match_logpolar_z → 회전 보정 → 본 op 순서).
Raises ValueError: 형상이 다름, window 철자 오류, whitening이 [0, 1] 밖, torch가 없는 환경에서 device가 cpu 이외.
• 샘플 데이터 카탈로그(DL URL / 라이선스) —— 2-D 는 skimage.data(BSD/public)+ 합성, 3-D 는 실데이터 소스(Stanford/PDS 등)의 DL URL.
• 연산자의 내력·참고문헌 —— 이 연산자 족의 바탕이 된 연구/기법의 출처.
• shape_desc_pose — py -3.11 examples_3d/shape_desc_pose.py
shift 를 입력으로 받는 것)match_pose)match_pca · moment_axes · match_logpolar_z
*Provenance: match3d.py — 3D 연산자 레지스트리. 이 op 노트는 tools/opdocs.py md 가 자동 생성합니다(직접 편집하지 마세요).*
© 2026 Kazufumi Furuse — Fullseye operator documentation. Licensed under Apache-2.0.