geometric op• 데이터 종류: image2d × image2d → table
• 호출: import fullseye as fs; fs.ledger.register_image(reference, moving, upsample=20, method='phase', window='hann', max_shift=None, ambiguity_ratio=0.8, residual_tolerance=0.25)(구현을 직접 호출하려면 import aoi; aoi.register_image(reference, moving, upsample=20, method='phase', window='hann', max_shift=None, ambiguity_ratio=0.8, residual_tolerance=0.25), 원장에서 가져오려면 opsaoi.get("register_image"))
• GPU: 없음(CPU 참조 구현만)
검사 영상을 기준 영상에 맞추는 평행 이동을, 맞지 않음을 알 수 있는 양과 함께 돌려준다. → dict.
> 아래 상세 설명은 원문입니다 —— 요약과 제목은 번역되어 있습니다.
相関面(既定は位相相関)の山を整数画素で見つけ、その近傍を上標本 DFT で 1/upsample 画素まで詰める。返りは dict 1 つで、並進だけでなく「その答えがどれくらい当てになるか」を必ず一緒に返す。
符号の約束: moving(y, x) ≈ reference(y - dy, x - dx)。つまり moving は reference を (dy, dx) だけずらしたもので、moving を (-dy, -dx) 動かせば重なる。np.roll(ref, (3, 5), axis=(0, 1)) を渡せば dy=3, dx=5 が返る。
平行移動しか扱わない。 回転や倍率が入った対を渡しても例外は出ないが、residual が跳ね consistent が False になる。実測(128x128 の合成模様。勾配 + 円 + 棒 + 雑音で、乱数だけの画像は対称性の破れを隠すので使わない):
===================== ========== ============ ======== ============
与えた変形 residual peak_ratio peak consistent
===================== ========== ============ ======== ============
並進 (3, 5) px 整数 0.000000 0.0081 0.9698 True
並進 (2.5, -1.5) px 0.058785 0.2050 — True
並進 (0.5, 0) px 0.038918 0.2022 — True
回転 2 度 0.5886 0.1303 0.3200 False
回転 5 度 0.6555 0.4827 0.1132 False
倍率 1.05 0.6073 0.1687 0.2196 False
倍率 1.10 0.6767 0.5205 0.0968 False
===================== ========== ============ ======== ============
副画素の並進は upsample=20 で誤差 0.0000 px(上の 2 例とも真値と一致)。数字は tests/test_aoi.py が固定している。黙って「いちばん近い平行移動」を成功として返さないための量がこの residual で、返り値を見ずに dy/dx だけ使うと回転 2 度を「ずれ 0.14 px」として飲み込む(上の表の 4 行目)。
周期のある模様では答えが 1 つに決まらない —— そして peak_ratio はその半分しか見ていない。 実測(周期 8 px、np.roll で (3, 5) ずらした対):
=========== ========= ========= ============ =========== ==========
模様 dy dx peak_ratio ambiguous residual
=========== ========= ========= ============ =========== ==========
市松 8 px +2.950 +4.850 1.0000 True 0.1322
縞 8 px +0.000 +4.900 0.1996 False 0.0838
=========== ========= ========= ============ =========== ==========
市松は狙いどおり ambiguous=True になる(答えは周期 8 を法として等価なものが並ぶので、返る値はそのうちの 1 つであって間違いではないが一意でもない)。
★縞は捕まらない、という限界を正直に書いておく。 縞は縦方向に模様が無いので dy は原理的に決まらないのに、ambiguous は False で dy=0.000 が返る。peak_ratio は「離れた 2 番目の山」を見る量で、縞が作るのは山ではなく 尾根(dy 方向に平らな筋)だから検出できない。しかも尾根の中から dy=0 を選んでいるのは画像ではなく Hann 窓の包絡で、window="none" にすると別の値が出うる。片方向だけ模様が無い被写体(縞・織り目・筋目)では dy/dx のどちらかが窓の産物になりうるので、そういう面を測るなら直交する模様を画面に入れること。この限界は tests/test_aoi.py が両方向とも固定してある(市松が True・縞が False であることを、直すまで忘れないために)。
Args:
reference: 基準画像 (H, W)。
moving: 合わせる画像 (H, W)。reference と同じ形。
upsample: 副画素の分解能の逆数(1 なら整数画素まで)。
method: REGISTER_METHODS。"phase" は振幅を正規化するので明るさの
違いに強く、"cross" は素の相互相関で雑音に強い。
window: REGISTER_WINDOWS。
max_shift: 探索するずれの上限[px]。None なら画像の半分。
ambiguity_ratio: peak_ratio がこれ以上なら ambiguous=True。
residual_tolerance: residual がこれ以下なら consistent=True。
Returns:
dict。dy / dx(px、副画素)、peak(正規化した山の高さ [0, 1])、
peak_ratio(第 2 の山 / 第 1 の山。1 に近いほど当てにならない)、
ambiguous(bool)、residual(合わせたあとの残差 rms / 基準の rms)、
consistent(bool。平行移動だけで説明できるか)、model("translation")、
method / window / upsample。
Raises:
ValueError: 形が違う / 2-D でない / 非有限 / どちらかが定数画像(模様が無いので
ずれが定義できない)/ 引数が値域外(upsample が 1 未満か MAX_UPSAMPLE
超、max_shift / ambiguity_ratio / residual_tolerance が正の有限でない)。
• 샘플 데이터 카탈로그(DL URL / 라이선스) —— 2-D 는 skimage.data(BSD/public)+ 합성, 3-D 는 실데이터 소스(Stanford/PDS 등)의 DL URL.
• 연산자의 내력·참고문헌 —— 이 연산자 족의 바탕이 된 연구/기법의 출처.
• 알고리즘의 정전(저자·연도)과 용도는 위의 패밀리 사용 가이드에 적혀 있습니다.
• aoi_frontend_tour — py -3.11 examples/aoi_frontend_tour.py
• poc_multimodal_mi_registration — py -3.11 examples/poc_multimodal_mi_registration.py
table 를 입력으로 받는 것)symmetry_difference_map · symmetry_score
geometric)—
*Provenance: aoi.py — AOI 연산자 레지스트리. 이 op 노트는 tools/opdocs.py md 가 자동 생성합니다(직접 편집하지 마세요).*
© 2026 Kazufumi Furuse — Fullseye operator documentation. Licensed under Apache-2.0.