harris3d_keypoints — 3D `feature_register` op

• 数据种类:voxel → keypoints

• 调用: import fullseye as fs; fs.ledger.harris3d_keypoints(vol, device='cpu', k=0.005, nms=3, topn=64, sigma_i=1.5, response='mineig', rel_thresh=0.01, border=2)(要直接调用实现,import feat_harris; feat_harris.harris3d_keypoints(vol, device='cpu', k=0.005, nms=3, topn=64, sigma_i=1.5, response='mineig', rel_thresh=0.01, border=2);从台账取用则 ops3d.get("harris3d_keypoints"))

• 经台账调用的返回值: fullseye.ledger.harris3d_keypoints(...) 只返回声明的 out 类型 keypoints 的值(底层函数还会返回辅助信息)。需要被丢弃的部分时,使用 fullseye.ledger.harris3d_keypoints.raw(...),或直接调用 feat_harris.harris3d_keypoints。

• 底层返回: (keypoints, scores)

• GPU:该算子有 GPU 路径(device="cuda")

用法

3D Harris 关键点检测(2D Harris 角点检测的 3D 版)。

从 voxel 密度场的 3D 梯度 g=(gz,gy,gx) 出发,在各体素构建局部结构张量 M=Σ_w w·g gᵀ(3x3 对称,用 gaussian 窗口 sigma_i 加权求和),测量角点性。响应在周围为极大且超过阈值的体素作为 keypoint(由于无需初始位姿估计即可检测,可用于大旋转+部分重叠的对应,或为 ICP 提供 coarse init)。

角点性指标:

• "mineig"(默认): 3x3 对称矩阵的最小特征值(Shi-Tomasi 式)。3 个方向都有结构(=角)时最小特征值越大。以闭式(三角函数法)计算。无需调整 k 且稳健(实测 mean repeatability 85%,min 72.5%)。

• "harris": R = det(M) - k·tr(M)³。3D 中有 3 个特征值,因此用 tr 的 3 次方

无量纲化。★注意: 在密度 voxel 的角处 det/tr³ 比经验上只有 ~0.01,

因此用 2D 标准的 k=0.04〜0.06 时全部响应为负,检测数为 0。

3D 中需要 k≈0.005(实测 k=0.005 时 mean 89.6%)。

参数:

vol: (D,H,W) 密度 voxel(numpy / torch)。假定为 points_to_voxel 的输出。

device: torch 设备("cpu" 等)。所有运算都在该设备上进行。

k: Harris 的灵敏度系数(仅在 response="harris" 时有效)。3D 密度场中

约 0.005(2D 惯例的 0.04〜0.06 在 3D 中过强,检测数为 0)。

nms: 非极大值抑制的立方体窗口边长(奇数,标准 3 = 3x3x3 邻域)。

topn: 按响应降序返回的 keypoint 最大数量。

sigma_i: 结构张量积分窗口(gaussian)的标准差(voxel)。

response: "mineig"(默认,稳健)或 "harris"。

rel_thresh: 响应阈值 = rel_thresh × 有效区域的最大响应(抑制噪声)。

border: 距边缘 border 个体素以内不检测(去除梯度的边缘效应)。

返回值:

keypoints: (M,3) float64。keypoint 的 voxel 坐标 (z,y,x)(与 sobel3d

相同的轴顺序)。按响应降序,最多 topn 个。

responses: (M,) float64。对应的响应值(降序)。

依赖: sobel3d(3D 梯度)、_gauss3d(积分窗口平滑)。均在 device 上运行。

背景知识指南(该算子背后的物理与约定)

• blas_threads_and_memory — 矩阵分解为何慢 —— BLAS 线程、缓存、内存布局

参考(示例数据、文献)

• 示例数据目录(下载 URL / 许可证) —— 2-D 用 skimage.data(BSD/公有领域)加合成图,3-D 给出真实数据源(Stanford/PDS 等)的下载 URL。

• 算子来历与参考文献 —— 该算子族所依据的研究/方法出处。

可运行的示例(实际调用该算子并已验证的样例)

• feature_register — py -3.11 examples_3d/feature_register.py

类型可衔接的下一个算子(可接受 `keypoints` 作为输入)

fuse_to_voxel · dlt_pose · pnp_ransac · reprojection_error

同类别(`feature_register`)

iss_keypoints · compute_fpfh · shot_descriptor · register_spin · register_fpfh · register_shot

*Provenance: feat_harris.py — 3D 算子登记表。本条目由 tools/opdocs.py md 自动生成(请勿手工编辑)。*

harris3d_keypoints — 3D feature_register op

用法