register_spin — 3D `feature_register` op

• 数据种类:points × points → pose

• 调用: import fullseye as fs; fs.ledger.register_spin(src, dst, device='cpu', n_keypoints=220, normal_k=18, support_radius=None, n_alpha=16, n_beta=16, support_angle_deg=60.0, lowe_ratio=0.85, ransac_iters=4000, inlier_thr=None, min_inliers=8, seed=0)(要直接调用实现,import feat_spin; feat_spin.register_spin(src, dst, device='cpu', n_keypoints=220, normal_k=18, support_radius=None, n_alpha=16, n_beta=16, support_angle_deg=60.0, lowe_ratio=0.85, ransac_iters=4000, inlier_thr=None, min_inliers=8, seed=0);从台账取用则 ops3d.get("register_spin"))

用法

用 Spin Image 描述子 + RANSAC 的无初值稀疏特征刚体配准。

在没有任何初始位姿先验的情况下,对 2 个点云 src (N,3)、dst (M,3) 进行配准。以各点的法线(局部 PCA,符号统一为从质心向外 = 对刚体变换不变)为轴,将邻域点 "旋转(spin)"累积到 (α=到轴的距离, β=沿轴方向的高度) 的 2D 直方图中, 为每个 keypoint 构建 Spin Image 描述子(Johnson & Hebert 1997),在描述子空间中以最近邻进行匹配(用 Lowe ratio test 筛选),再用 RANSAC(3 点最小样本 + Kabsch) 估计对离群值鲁棒的刚体变换。与稠密匹配(NCC/相位相关/Hough)或 PCA 主轴对齐不同,即使在大旋转 + 部分重叠下也能从局部特征的对应恢复位姿,因此可用作 ICP 的前级(提供 coarse init)。返回的位姿遵循 dst ~= src @ R.T + t (= R @ src_i + t)的约定(与 icp_point2point_3d 相同)。

参数:

src: (N,3) 移动侧点云(numpy.ndarray 或 torch.Tensor)。

dst: (M,3) 固定侧(参考)点云。

device: torch 设备("cpu" 等)。在其上求解 SVD/最终位姿。

n_keypoints: 从各点云中提取的 keypoint 数(等间隔子采样)。

normal_k: 法线估计所用的邻域点数(局部 PCA)。

support_radius: Spin Image 的支持半径。None 时为各点云分别测得的 bbox 对角线(取较大者)

的 0.30 倍(为避免被未知平移污染,不取并集而是分别测量)。

n_alpha, n_beta: Spin Image 的 (α, β) 分箱数(描述子为 n_alpha*n_beta 维)。

support_angle_deg: 支持角阈值(度)。只累积法线与 keypoint 法线夹角在此角度以内的

支持点(对遮挡、背面鲁棒)。>=90 时无效。

lowe_ratio: Lowe 比率测试阈值(只采用 d1 < ratio*d2 的对应)。

ransac_iters: RANSAC 迭代次数。

inlier_thr: RANSAC 的内点距离阈值。None 时为 bbox 对角线的 0.04 倍。

min_inliers: 视为有效位姿的最少内点数(ok 判定)。

seed: RANSAC 随机种子。

返回值:

R: (3,3) torch.Tensor。满足 dst ~= src @ R.T + t 的旋转。

t: (3,) torch.Tensor。平移。

info: dict。"n_matches"(通过 ratio test 的对应数), "inliers"(RANSAC 最终),

"inlier_ratio", "rmse"(内点上的 RMSE), "support_radius",

"inlier_thr", "ok"(是否不少于 min_inliers)。

注意:

• 描述子依赖于法线符号。从质心向外的符号统一,对于法线大致呈放射状、n·(p-质心) 的符号稳定的形状(lumpy 的闭曲面等)有效。在薄板、管状等 n·(p-质心)≈0 的区域较多的形状上,符号可能在 2 个点云之间翻转。

• 平面、球等曲率在空间上均匀的部位描述子会退化,ratio test 会使对应消失(不适合无特征形状)。overlap 低于约 60% 时成功率骤降,失败时 RANSAC 可能锁定在几何上一致但错误的解上,导致灾难性误差(建议并用 ok / inlier_ratio 门控)。

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

• 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

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

fuse_to_voxel · pose_error · bundle_adjust · mean_reprojection_error · optimize_pose_graph · relative_pose · mean_edge_error · rotation_translation_error

同类别(`feature_register`)

harris3d_keypoints · iss_keypoints · compute_fpfh · shot_descriptor · register_fpfh · register_shot

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

register_spin — 3D feature_register op

用法