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"))

用法

體素佔據的 IoU(intersection over union)。→ [0,1]。體積一致度。

兩個 volume 必須形狀相同。不同形狀會透過 numpy broadcasting 表面上對齊, 靜默回傳錯誤的 IoU(例:(10,1,10) vs (1,10,10) → 1.0),因此依 fail-closed 原則, shape 不一致時以 ValueError 拒絕。

計算:以 >= iso 將兩個 volume 二值化(iso 預設 0.5,含等號), 再求 |A∩B| / |A∪B|。聯集為空(兩者佔用皆為零)時回傳 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 搭配使用 —— 在 Blender 中建形、用 fullseye 量測(座標軸、單位、真值資料的陷阱)

• measurement_uncertainty — 量測不確定度與校正知識 —— 為了能主張「量得準」

參考(範例資料、文獻)

• 範例資料目錄(下載 URL / 授權) —— 2-D 用 skimage.data(BSD/公有領域)加合成圖,3-D 給出真實資料源(Stanford/PDS 等)的下載 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 運算子登記表。本條目由 tools/opdocs.py md 自動產生(請勿手動編輯)。*

voxel_iou — 3D metrics op

用法