voxel_iou — 3D `metrics` op

• 데이터 종류: voxel × voxel → measurement

• 호출: import fullseye as fs; fs.ledger.voxel_iou(vol_a, vol_b, iso=0.5)(구현을 직접 호출하려면 import metrics3d; metrics3d.voxel_iou(vol_a, vol_b, iso=0.5), 원장에서 가져오려면 ops3d.get("voxel_iou"))

사용법

voxel 점유의 IoU(intersection over union). → [0,1]. 체적 일치도.

두 volume은 shape이 같아야 한다. 형상이 다르면 numpy broadcasting으로 겉보기에 일치해잘못된 IoU(예: (10,1,10) vs (1,10,10) → 1.0)를 조용히 반환하므로, fail-closed로 shape 불일치는 ValueError로 거부한다.

계산: 두 volume을 >= iso로 이진화하고(iso 기본값 0.5, 등호 포함), |A∩B| / |A∪B|를 구한다. 합집합이 비어 있으면(둘 다 점유 0) 1.0을 반환한다("둘 다 비어 있음"은 일치로 간주한다. 오류로 하지 않는다).

인수: vol_a, vol_b는 같은 shape의 배열(3-D에 한정되지 않으며 차원 수는 검사하지 않는다. bool / 0-1 / 밀도 grid 어느 것이든 좋다). iso는 점유로 간주하는 임계값이며, fuse_to_voxel이나 points_to_voxel의 밀도 grid(값은 점 개수)에 쓴다면 iso=1 이상을 명시한다. NaN은 >=에서 False(비점유)가 된다.

반환값: Python float, [0, 1]. 1 = 완전 일치, 0 = 겹침 없음.

주의: 같은 격자(bounds와 size)에 올라가 있지 않으면 비교가 되지 않는다 — fuse_to_voxel / points_to_voxel에는 같은 bounds를 넘긴다. 얇은 껍질끼리는 1 voxel만 어긋나도 IoU가 크게 떨어지므로, 표면 평가에는 chamfer_distance / fscore가 더 적합하다. 체적이 작은 대상에는 Dice (voxel_dice, 같은 모듈의 함수)가 관례적으로 쓰인다.

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

• blender_interop — Blender와 함께 쓰기 — 형상을 만들고 fullseye로 측정(축·단위·정답 데이터의 함정)

• measurement_uncertainty — 측정 불확도와 교정 지식 — ‘측정되고 있다’고 주장하려면

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

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

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

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

• metrics_eval — py -3.11 examples_3d/metrics_eval.py

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

vol_gaussian_psf · fuse_to_voxel · fresnel_reflectance · snell_angle

같은 카테고리(`metrics`)

chamfer_distance · hausdorff_distance · m3c2_distance · fscore · rmse_correspondence · normal_consistency · pose_error

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

voxel_iou — 3D metrics op

사용법