unwrap_phase_2d — 3D `structured_light` op

• 데이터 종류: image2d → image2d

• 호출: import fullseye as fs; fs.ledger.unwrap_phase_2d(wrapped, mask=None, crop_valid=False) -> 'np.ndarray'(구현을 직접 호출하려면 import fringe; fringe.unwrap_phase_2d(wrapped, mask=None, crop_valid=False) -> 'np.ndarray', 원장에서 가져오려면 ops3d.get("unwrap_phase_2d"))

• GPU: 없음(CPU 참조 구현만)

사용법

감긴 위상을 skimage.restoration.unwrap_phase 로 연속 위상으로 펼칩니다.

wrapped: wrapped_phase의 출력(2D). NaN을 포함해도 된다(무효 화소로 취급).

mask: 생략 가능. True = 유효 화소(numpy masked array의 관례와는 반대인 직관적인 방향).

NaN 화소와 mask=False 화소는 무효로 보아 언랩에서 제외하고, 출력에서는 NaN을 반환한다.

crop_valid: 생략 가능(기본 False = 전체 처리). True이면 유효 화소의 외접 직사각형만 skimage에 넘기고 바깥은 NaN 그대로 돌려준다(무효 화소가 많은 테두리 있는 영상에서 더 빠른 대안 경로. 유효 화소의 위상은 섬마다 2π의 정수배 오프셋을 제외하면 전체 처리와 일치한다. 그 오프셋은 skimage 버전에 따라 달라질 수 있다).

반환값: 연속 위상(2D float). 무효 화소는 NaN. 대역 오프셋(+2πm)의 부정성은 남는다.

절차: 무효 화소(wrapped의 비유한 ∪ mask == False)가 없으면 skimage.restoration.unwrap_phase(arr)를 그대로 호출한다. 있으면 무효 화소를 0으로채운 numpy.ma의 masked array로 넘기고(skimage는 masked 화소를 언랩에서제외한다), 출력의 무효 화소를 NaN으로 되돌린다.

검증: scikit-image를 import할 수 없는 환경에서는 RuntimeError(ImportError 가 아님). wrapped가 2-D가 아님, mask의 형상이 다름, 모든 화소가 무효 (언랩할 화소가 없음)은 ValueError.

전제(Itoh의 조건): 인접한 유효 화소의 참 위상 차가 π 미만. 급한 계단·깊은 구멍· 오클루전 경계에서는 2π 점프를 잘못 판단하여, 그 너머의 영역 전체가 2πm 어긋난다. 마스크로 섬으로 나뉜 영역끼리의 상대 차수는 정해지지 않는다(섬마다 독립된오프셋). 절대성이 필요할 때는 graycode_decode → absolute_phase의화소 독립적인 차수 확정을 사용한다.

쓰임새: wrapped_phase → 본 op → phase_to_height(같은 모듈의함수, height = k (phase - ref_phase)). ★전개의 전역 오프셋 2πm은전개마다 정해지므로(기점의 분기는 입력 위상장에 따라 다름), 참조면과 계측면을 따로 전개해 빼도 상쇄되지 않는다(2026-11-05까지 "상쇄된다"고 적혀 있었으나, 60 조건 중 24에서 높이가 k·2π 어긋났다). 참조를 뺄 때는 decode_fringe의 ref_phase를 쓴다 —— 감긴 위상의 차를 먼저 취한 뒤 1회만 전개한다.

빈 입력(wrapped 이(가) 0 개 요소)은 ValueError 를 발생시킨다.

배경 지식 가이드(이 연산자 앞에 있는 물리·규약)

• depth_sensors — 깊이 센서 지식 — 측거 원리·실기 수치·결측이 나타나는 방식

참고(샘플 데이터·문헌)

• 샘플 데이터 카탈로그(DL URL / 라이선스) —— 2-D 는 skimage.data(BSD/public)+ 합성, 3-D 는 실데이터 소스(Stanford/PDS 등)의 DL URL.

• 연산자의 내력·참고문헌 —— 이 연산자 족의 바탕이 된 연구/기법의 출처.

실행 가능한 예제(이 연산자를 실제로 호출하는 검증된 샘플)

• structured_light — py -3.11 examples_3d/structured_light.py

타입이 이어지는 다음 연산자(`image2d` 를 입력으로 받는 것)

fuse_to_voxel · fit_poly_surface · eval_poly_surface · surface_form_error · background_flatten · polar_unwrap · fit_zernike · matcap_shade

같은 카테고리(`structured_light`)

wrapped_phase · graycode_decode · decode_fringe · fringe_ftp_phase · depth_from_focus · synthesize_fringes · absolute_phase · triangulate_column

*Provenance: fringe.py — 3D 연산자 레지스트리. 이 op 노트는 tools/opdocs.py md 가 자동 생성합니다(직접 편집하지 마세요).*

unwrap_phase_2d — 3D structured_light op

사용법