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

用法