feat(kpm): facade-parity convenience accessors on VisualDatabase + FeatureStore slices (#148)

Mirror `VisualDatabaseFacade`'s Group-A accessors so the Rust port is a
drop-in for the C++ facade surface, and callers don't have to loop
`0..num_features()` element-by-element. Pure additive getters — no behavior
change.

- `FeatureStore`: add slice accessors `points() -> &[FeaturePoint]` and
  `descriptors() -> &[u8]` (counterparts to per-element `point(i)`/`descriptor(i)`).
- `VisualDatabase`: add `get_feature_points(id)`, `get_descriptors(id)`,
  `get_query_feature_points()`, `get_query_descriptors()`, `get_width(id)`,
  `get_height(id)` (Option-returning, 1-liners over the slice accessors).
- Tests for both (deterministic, no image pipeline).

Group B (3D feature points — RustFreakMatcher/NFT domain) and Group C
(computeFreakFeaturesAndDescriptors — no caller) are out of scope.

Refs #148.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Author: kalwalt

crates/core/src/kpm/freak/matcher.rs

@@ -133,6 +133,22 @@ impl FeatureStore {
     pub fn bytes_per_feature(&self) -> usize {
         self.bytes_per_feature
     }
+
+    /// Returns all feature points as a slice.
+    ///
+    /// Slice counterpart to [`point`](Self::point) — avoids forcing callers to
+    /// loop `0..num_features()` element-by-element (facade parity, #148).
+    pub fn points(&self) -> &[FeaturePoint] {
+        &self.points
+    }
+
+    /// Returns the flat descriptor buffer (`num_features() * bytes_per_feature()`
+    /// bytes, descriptor `i` at `[i * bpf .. (i+1) * bpf]`).
+    ///
+    /// Slice counterpart to [`descriptor`](Self::descriptor) (#148).
+    pub fn descriptors(&self) -> &[u8] {
+        &self.descriptors
+    }
 }
 
 // ============================================================================
@@ -583,6 +599,27 @@ mod tests {
         assert!(!s.point(2).maxima);
     }
 
+    #[test]
+    fn test_feature_store_slice_accessors() {
+        let mut s = FeatureStore::new(96).unwrap();
+        let d0 = make_descriptor(0);
+        let d1 = make_descriptor(1);
+        s.add(fp(0.0, 0.0, true), &d0).unwrap();
+        s.add(fp(1.0, 1.0, false), &d1).unwrap();
+
+        // points() slice agrees with per-element point(i).
+        let pts = s.points();
+        assert_eq!(pts.len(), 2);
+        assert_eq!(pts[0].x, s.point(0).x);
+        assert!(!pts[1].maxima);
+
+        // descriptors() flat buffer agrees with per-element descriptor(i).
+        let descs = s.descriptors();
+        assert_eq!(descs.len(), 2 * 96);
+        assert_eq!(&descs[0..96], s.descriptor(0));
+        assert_eq!(&descs[96..192], s.descriptor(1));
+    }
+
     #[test]
     fn test_feature_store_add_wrong_size() {
         let mut s = FeatureStore::new(96).unwrap();

crates/core/src/kpm/freak/visual_database.rs

@@ -667,6 +667,54 @@ impl VisualDatabase {
     pub fn keyframe(&self, id: usize) -> Option<&Keyframe> {
         self.keyframes.get(&id)
     }
+
+    // ── Facade-parity convenience accessors (#148, Group A) ──────────────
+    // Thin getters mirroring `VisualDatabaseFacade`, so callers don't have to
+    // reach through `keyframe(id).store` and loop element-by-element.
+
+    /// Feature points of the reference keyframe stored under `id`.
+    ///
+    /// C equivalent: `getFeaturePoints(id)`.
+    pub fn get_feature_points(&self, id: usize) -> Option<&[FeaturePoint]> {
+        self.keyframes.get(&id).map(|kf| kf.store.points())
+    }
+
+    /// Flat descriptor buffer of the reference keyframe stored under `id`.
+    ///
+    /// C equivalent: `getDescriptors(id)`.
+    pub fn get_descriptors(&self, id: usize) -> Option<&[u8]> {
+        self.keyframes.get(&id).map(|kf| kf.store.descriptors())
+    }
+
+    /// Feature points of the most recent query frame (see [`query`](Self::query)).
+    ///
+    /// C equivalent: `getQueryFeaturePoints()`.
+    pub fn get_query_feature_points(&self) -> Option<&[FeaturePoint]> {
+        self.query_keyframe.as_ref().map(|kf| kf.store.points())
+    }
+
+    /// Flat descriptor buffer of the most recent query frame.
+    ///
+    /// C equivalent: `getQueryDescriptors()`.
+    pub fn get_query_descriptors(&self) -> Option<&[u8]> {
+        self.query_keyframe
+            .as_ref()
+            .map(|kf| kf.store.descriptors())
+    }
+
+    /// Width of the reference image stored under `id`.
+    ///
+    /// C equivalent: `getWidth(id)`.
+    pub fn get_width(&self, id: usize) -> Option<i32> {
+        self.keyframes.get(&id).map(|kf| kf.width)
+    }
+
+    /// Height of the reference image stored under `id`.
+    ///
+    /// C equivalent: `getHeight(id)`.
+    pub fn get_height(&self, id: usize) -> Option<i32> {
+        self.keyframes.get(&id).map(|kf| kf.height)
+    }
 }
 
 impl Default for VisualDatabase {
@@ -1019,6 +1067,49 @@ mod tests {
         assert!(db.keyframe(0).unwrap().index().is_some());
     }
 
+    #[test]
+    fn test_facade_parity_accessors() {
+        // Build a tiny keyframe directly (no image pipeline) so the getters are
+        // exercised deterministically and fast (#148, Group A).
+        let mut kf = Keyframe::new(640, 480).unwrap();
+        let p0 = FeaturePoint {
+            x: 1.0,
+            y: 2.0,
+            angle: 0.0,
+            scale: 1.0,
+            maxima: true,
+        };
+        let p1 = FeaturePoint {
+            x: 3.0,
+            y: 4.0,
+            angle: 0.0,
+            scale: 1.0,
+            maxima: false,
+        };
+        kf.store.add(p0, &[7u8; 96]).unwrap();
+        kf.store.add(p1, &[9u8; 96]).unwrap();
+
+        let mut db = VisualDatabase::new().expect("new");
+        db.add_keyframe(kf, 0).expect("add_keyframe");
+
+        // Reference accessors for the stored id.
+        assert_eq!(db.get_width(0), Some(640));
+        assert_eq!(db.get_height(0), Some(480));
+        assert_eq!(db.get_feature_points(0).unwrap().len(), 2);
+        assert_eq!(db.get_feature_points(0).unwrap()[0].x, 1.0);
+        let descs = db.get_descriptors(0).unwrap();
+        assert_eq!(descs.len(), 2 * 96);
+        assert_eq!(&descs[0..96], &[7u8; 96]);
+
+        // Missing id → None.
+        assert!(db.get_feature_points(99).is_none());
+        assert!(db.get_width(99).is_none());
+
+        // No query run yet → query accessors are None.
+        assert!(db.get_query_feature_points().is_none());
+        assert!(db.get_query_descriptors().is_none());
+    }
+
     // -----------------------------------------------------------------
     // Dual-mode parity test (M9-1 gate per #140, closed by M9 #146)
     // -----------------------------------------------------------------