harris3d_keypoints — 3D `feature_register` op

• Datenarten: voxel → keypoints

• Aufruf: 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) (die Implementierung direkt: 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); aus dem Register: ops3d.get("harris3d_keypoints"))

• Rückgabewert über das Register: fullseye.ledger.harris3d_keypoints(...) liefert nur den Wert des deklarierten Out-Typs keypoints (die zugrunde liegende Funktion gibt zusätzlich Hilfsinformationen zurück). Wird das Verworfene gebraucht, nutze fullseye.ledger.harris3d_keypoints.raw(...) oder rufe feat_harris.harris3d_keypoints direkt auf.

• Rückgabe der Funktion: (keypoints, scores)

• GPU: Dieser Operator hat einen GPU-Pfad (device="cuda")

Verwendung

3-D-Harris-Keypoint-Detektion (die 3-D-Version des 2-D-Harris-Eckendetektors).

Aus dem 3D-Gradienten g=(gz,gy,gx) eines Voxel-Dichtefelds wird an jedem Voxel der lokale Strukturtensor M=Σ_w w·g gᵀ (3x3 symmetrisch, gewichtete Summe mit gaussian-Fenster sigma_i) gebildet und die Eckigkeit gemessen. Voxel, deren Antwort ein lokales Maximum ist und über dem Schwellwert liegt, werden zu keypoints (da sie ohne Anfangsposenschätzung detektiert werden können, eignen sie sich für Zuordnungen bei großer Rotation + Teilüberlappung oder als coarse init für ICP).

Maße der Eckigkeit:

• "mineig" (Standard): kleinster Eigenwert der symmetrischen 3x3-Matrix (nach Shi-Tomasi). Je mehr Struktur in allen 3 Richtungen vorhanden ist (= Ecke), desto größer der kleinste Eigenwert. In geschlossener Form (trigonometrisches Verfahren) berechnet. Robust ohne k-Abstimmung (gemessen mean repeatability 85%, min 72.5%).

• "harris": R = det(M) - k·tr(M)³. In 3D gibt es 3 Eigenwerte, daher wird mit der 3. Potenz von tr entdimensionalisiert. ★Achtung: an Ecken eines Dichte-Voxelfelds beträgt das Verhältnis det/tr³ empirisch nur ~0.01, daher werden mit dem 2D-Standard k=0.04-0.06 alle Antworten negativ und es werden 0 Punkte detektiert. In 3D ist k≈0.005 nötig (gemessen mean 89.6% bei k=0.005).

Argumente:

vol: (D,H,W) Dichte-Voxel (numpy / torch). Als Ausgabe von points_to_voxel gedacht.

device: torch-Gerät ("cpu" usw.). Alle Operationen laufen auf diesem Gerät.

k: Harris-Empfindlichkeitskoeffizient (nur bei response="harris" wirksam). Für 3D-Dichtefelder

etwa 0.005 (die 2D-Konvention 0.04-0.06 ist in 3D zu stark und detektiert 0 Punkte).

nms: Seitenlänge des kubischen Fensters der Non-Maximum-Suppression (ungerade, Standard 3 = 3x3x3-Nachbarschaft).

topn: maximale Anzahl zurückgegebener keypoints, absteigend nach Antwort.

sigma_i: Standardabweichung (voxel) des Integrationsfensters (gaussian) des Strukturtensors.

response: "mineig" (Standard, robust) oder "harris".

rel_thresh: Antwort-Schwellwert = rel_thresh × maximale Antwort im gültigen Bereich (Rauschunterdrückung).

border: innerhalb von border Voxeln vom Rand wird nichts detektiert (entfernt Randeffekte des Gradienten).

Rückgabewert:

keypoints: (M,3) float64. voxel-Koordinaten (z,y,x) der keypoints (gleiche Achsenreihenfolge wie

sobel3d). Absteigend nach Antwort, höchstens topn.

responses: (M,) float64. Die zugehörigen Antwortwerte (absteigend).

Abhängigkeiten: sobel3d (3D-Gradient), _gauss3d (Glättung im Integrationsfenster). Beide laufen auf dem device.

Hintergrundwissen (Physik und Konventionen hinter diesem Operator)

• blas_threads_and_memory — Warum Matrixzerlegungen langsam sind — BLAS-Threads, Caches, Speicherlayout

Referenzen (Beispieldaten, Literatur)

• Katalog der Beispieldaten (Download-URLs / Lizenzen) — 2-D nutzt skimage.data (BSD/Public Domain) plus synthetische Bilder, 3-D nennt Download-URLs echter Datenquellen (Stanford, PDS, …).

• Herkunft und Literatur der Operatoren — die Quellen der Forschung/Verfahren, auf denen diese Operatorfamilie beruht.

Ausführbare Beispiele (verifizierte Samples, die diesen Operator wirklich aufrufen)

• feature_register — py -3.11 examples_3d/feature_register.py

Typkompatible Folge-Operatoren (nehmen `keypoints` als Eingabe)

fuse_to_voxel · dlt_pose · pnp_ransac · reprojection_error

Gleiche Kategorie (`feature_register`)

iss_keypoints · compute_fpfh · shot_descriptor · register_spin · register_fpfh · register_shot

*Provenance: feat_harris.py — 3D Operator-Registry. Diese Notiz wird von tools/opdocs.py md erzeugt (nicht von Hand bearbeiten).*

harris3d_keypoints — 3D feature_register op