solid op• 데이터 종류: image2d × image2d × flow2d → image2d
• 호출: import fullseye as fs; fs.ledger.correlation_quality(ref: 'Any', cur: 'Any', flow: 'Any', info: 'Optional[dict]' = None, subset: 'int' = 31) -> 'np.ndarray'(구현을 직접 호출하려면 import dic; dic.correlation_quality(ref: 'Any', cur: 'Any', flow: 'Any', info: 'Optional[dict]' = None, subset: 'int' = 31) -> 'np.ndarray', 원장에서 가져오려면 opspiv.get("correlation_quality"))
주어진 변위장이 얼마나 맞는지를 점마다 반환하는 ZNCC 맵.
인수
ref 기준 이미지.
cur 변형 후 이미지. ref와 같은 형태.
flow pivops의 flow2d (2, h, w), 성분은 (dy, dx) [px].
info를 넘기지 않으면 (2, H, W)의 전 화소 장.
info piv_cross_correlate가 반환한 dict. 넘기면 창 격자의 flow를
화소로 쌍선형으로 넓힌 뒤 잰다.
subset 상관을 취하는 정사각 서브셋의 한 변 [px]. 홀수.
반환값은 입력 이미지와 같은 형태의 float 배열. 값은 [-1, 1]의 ZNCC이며, 잴 수 없었던 점은 NaN(서브셋이 이미지에서 삐져나오는 가장자리, 변형 후의표본점이 이미지 밖으로 나가는 점, 분산이 없는 서브셋).
★ 이것은 상관기가 아니다 —— 이미 있는 변위장의 채점 담당
piv_cross_correlate도 optical_flow_lk도 demons_register도,
내놓은 변위가 옳은지는 반환하지 않는다. 여기서는 cur를 flow로 기준 쪽으로
되돌리고(쌍선형), ref와의 ZNCC를 subset의 상자로 잴 뿐이다.
어느 추정기의 출력이든 같은 창구로 채점할 수 있는 것이 요점으로, 상관기를
1개 더 늘리지 않고 품질만을 더할 수 있다.
평균과 표준편차 양쪽을 할인하므로 게인과 오프셋에는 불변.
노출이 바뀐 쌍에서도 "맞고 있는가"만을 본다.
★★ 기존의 info["peak_ratio"]로는 부족한 장면이 있다(실측)
peak_ratio(제1 피크 / 제2 피크)는 PIV의 표준적인 SN비로,
상관면에 경합하는 봉우리가 서는 종류의 실패를 잡는다. 잡지 못하는 것은
"그 장소가 다른 것이 되었다" 종류의 실패. u=0.37 px의 쌍 중 60x60 화소
만을 무관한 무늬로 바꾼 실측:
지표 교체 영역 건전 영역 구별
peak_ratio 1.207 1.304 7.5 % 차(겹침)
correlation_quality 0.1101 0.9993 9배 차
품질로 잘랐을 때 변위 오차 RMS가 어떻게 바뀌는가:
게이트 남는 비율 오차 RMS [px]
없음 100.0 % 1.8110
zncc >= 0.8 84.9 % 0.0031 ← 584배 개선
peak_ratio >= 1.2 81.8 % 1.2183 ← 1.5배
peak_ratio >= 1.3 41.6 % 1.4471 ← 6할을 버리고 악화
양쪽을 보는 것이 옳다. peak_ratio는 경합 피크를, ZNCC는
상관 소실을 본다. 한쪽만으로는 구멍이 뚫린다.
★★ 함정 —— 품질이 높은 것은 정밀도가 높은 것이 아니다
ZNCC는 서브픽셀의 오차에 거의 반응하지 않는다. 참 변위 0.37 px의 쌍에
일부러 오차를 넣은 장을 채점한 실측(반점의 직경 3.8 px):
변위의 오차 [px] 0.00 0.05 0.10 0.25 0.50 1.00 2.00
zncc 중앙값 0.99945 0.99920 0.99845 0.99330 0.97615 0.90617 0.67655
0.05 px 틀려도 0.9992 —— 완전히 맞는 0.99945와의 차이는
2.5e-4밖에 없다. 이 지표가 잴 수 있는 것은 "반점의 크기에 비해 큰
어긋남·결측·다른 것으로의 교체"이지, 0.01 px의 정밀도가 아니다.
균일한 잡음으로 모든 점이 똑같이 열화한 경우(σ=0.15)도, 게이트로 잘라 남는 것은
21.8 %이고 오차 RMS는 0.1736 → 0.1292의 1.34배 개선에 그친다 ——
효과가 있는 것은 실패가 국소적일 때뿐.
★ 되돌리기는 서브셋별 평행 이동이 아니라 장 그 자체
보통의 DIC는 서브셋을 강체적으로 어긋나게 하여 상관을 취하지만, 여기서는 화소별
flow로 cur를 왜곡한 뒤 상자로 상관을 취한다. flow가 매끄러우면
둘은 일치하고, 그렇지 않다면 이쪽이 더 옳다(서브셋 안의
변형도 포함하여 잔차를 보기 때문). 비용도 O(N)으로 끝난다(256²에서 0.003초).
fail-closed
• ref / cur가 2차원이 아님, 형태가 다름, NaN·Inf를 포함.
• flow가 (2, h, w)가 아님.
• info 없이 flow가 이미지와 다른 형태(고치는 법을 붙여 거부).
• info에 rows / cols가 없음, 격자와 flow의 형태가 어긋남, 격자가 어느 한 축에서 2 미만.
• subset이 짝수·3 미만·이미지보다 큼.
• 샘플 데이터 카탈로그(DL URL / 라이선스) —— 2-D 는 skimage.data(BSD/public)+ 합성, 3-D 는 실데이터 소스(Stanford/PDS 등)의 DL URL.
• 연산자의 내력·참고문헌 —— 이 연산자 족의 바탕이 된 연구/기법의 출처.
• 알고리즘의 정전(저자·연도)과 용도는 위의 패밀리 사용 가이드에 적혀 있습니다.
• piv_field_analysis_tour — py -3.11 examples/piv_field_analysis_tour.py
image2d 를 입력으로 받는 것)piv_cross_correlate · piv_multipass · piv_deform_pass · strain_from_displacement · speckle_quality
solid)strain_from_displacement · speckle_quality
*Provenance: dic.py — PIV 연산자 레지스트리. 이 op 노트는 tools/opdocs.py md 가 자동 생성합니다(직접 편집하지 마세요).*
© 2026 Kazufumi Furuse — Fullseye operator documentation. Licensed under Apache-2.0.