decode_fringe — 3D `structured_light` op

• 데이터 종류: images → depth

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

사용법

위상 이동 이미지 열을 한 번에 복호: wrapped → unwrap →(기준 감산으로) 높이.

phase_shift_images: N-step 위상 시프트 줄무늬 영상열((N,H,W) 또는 길이 N의 시퀀스).

ref_phase: 참조 평면(높이 0)의 언랩된 위상. None이면 높이 = k·(unwrapped).

k: 위상→높이 캘리브레이션 상수.

mask: 생략 가능. True=유효 화소. 무효 화소는 NaN.

min_modulation: 생략 가능. 지정하면 modulation < 이 값인 화소를 저신뢰로 보아 무효화.

반환값: 높이 맵(2D float). ref_phase=None일 때는 k를 곱한 연속 위상을 반환한다. 무효 화소는 NaN.

절차(구현 그대로): wrapped_phase → 신뢰 마스크를 짠다(min_modulation이있으면 modulation(stack) >= min_modulation, mask가 있으면 그것과 AND)→ unwrap_phase_2d(wrapped, mask=신뢰 마스크) → ref_phase가 None이면 k * unwrapped, 있으면 phase_to_height(k * (unwrapped - ref_phase)).

인수:

• phase_shift_images: (N, H, W), N >= 3, 등간격 위상 시프트.

• ref_phase: 스칼라 또는 (H, W). 참조면을 같은 절차로 언랩한 위상을넘긴다(unwrap_phase_2d의 대역 오프셋이 양쪽에서 같게 취급되도록, 참조도본 op에서 ref_phase=None으로 복호한 결과를 쓰는 것이 안전).

• k: 위상→높이의 캘리브레이션 상수(단위/rad). synthesize_fringes의 phase_gain의 역수에 대응.

• mask: (H, W)의 bool, True = 유효. min_modulation: 변조도의 하한([0, 1] 정도. 그림자·포화 화소를 떨어뜨린다).

검증(ValueError): 영상열이 3-D가 아님·N < 3·비유한 / mask의 형상이다름 / ref_phase의 형상이 다름 / 유효 화소가 0. scikit-image가 없으면 RuntimeError.

반환값: (H, W) float64. 무효 화소는 NaN. 단위는 k의 단위.

주의: 공간 언랩에 의존하므로, 계단·오클루전으로 섬으로 나뉜 장면에서는섬마다 2πm k의 높이 오프셋이 남을 수 있다. 절대 높이가 필요한 장면은 graycode_decode → absolute_phase → triangulate_column의 경로.

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

• 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

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

depth_to_points · tsdf_from_depth · to_points · fuse_to_voxel · depth_to_organized_points · normals_from_depth · occlusion_edges · bearing_angle_image

같은 카테고리(`structured_light`)

wrapped_phase · unwrap_phase_2d · graycode_decode · synthesize_fringes · absolute_phase · triangulate_column

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

decode_fringe — 3D structured_light op

사용법