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

用法