fix(simple,marker): honour the buff/pixel_format contract (#103)

Closes the symptom from issue #103 (cf ~= 0.0965 on hiro template).
The library extraction was already correct (cf ~= 0.89 in the PR-A
diagnostic on the same path); the bug was that simple.rs declared
ar_pixel_format = MONO but fed an RGBA buffer into AR2VideoBufferT.buff,
violating the contract documented at artoolkit5/video2.c:682:
when pixel_format == MONO, buff IS the luma data.

Fixes:
- simple.rs now feeds the luma buffer into both buff and buff_luma
  (matching pixfmt = MONO), with a comment pointing at the upstream
  contract.
- ar_detect_marker now validates that frame.buff.len() matches
  xsize * ysize * pixel_size (and buff_luma matches xsize * ysize),
  emitting arlog_e! and returning Err on mismatch — turns silent
  contract violations into loud, immediate failures.
- ar_detect_marker doc comment grew a "Frame buffer contract" section
  documenting the rule and linking issue #103.

After this change, the simple example reports cf=0.8925 and id=0
on benchmarks/data/img.jpg (was cf=0.0965, id=-1 before).

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: kalwalt

crates/core/examples/simple.rs

@@ -218,12 +218,15 @@ fn main() {
 
     let luma_buffer_vec = luma_img.into_raw();
     let mut out_img = color_img.clone();
-    let color_buffer_vec = color_img.into_raw();
 
-    // Construct the AR2VideoBufferT pointing to our image data
+    // ARToolKit5's contract (cf. artoolkit5/video2.c:682): `buff` MUST hold
+    // data in the format declared by ar_pixel_format. When pixel_format is
+    // MONO, that means buff IS the luma data — buffLuma is just an alias.
+    // Feeding RGBA into buff while declaring MONO produces silent low-cf
+    // detections (see issue #103).
     let frame = AR2VideoBufferT {
-        buff: Some(color_buffer_vec),     // Color data
-        buff_luma: Some(luma_buffer_vec), // Gray data used for binarization
+        buff: Some(luma_buffer_vec.clone()), // pixfmt=MONO → buff IS luma
+        buff_luma: Some(luma_buffer_vec.clone()),
         buf_planes: None,
         buf_plane_count: 0,
         fill_flag: true,

crates/core/src/ar/marker.rs

@@ -82,6 +82,19 @@ pub enum ImageProcMode {
 ///
 /// Results are written into `ar_handle.marker_info` (up to `AR_SQUARE_MAX` markers).
 ///
+/// # Frame buffer contract
+///
+/// `frame.buff` MUST hold data in the format declared by
+/// `ar_handle.ar_pixel_format`. ARToolKit5's `video2.c:682` documents this
+/// contract: when `ar_pixel_format == MONO`, `buff` IS the luma data
+/// (and `buff_luma` is just an alias to it); otherwise `buff` holds the
+/// declared format and `buff_luma` is a separately-converted greyscale view.
+///
+/// Mismatching the buffer layout against the declared format used to
+/// produce silent low-confidence matches (see
+/// [issue #103](https://github.com/webarkit/WebARKitLib-rs/issues/103));
+/// `ar_detect_marker` now rejects such mismatches up front.
+///
 /// Mirrors the C `arDetectMarker()` entry point from `arDetectMarker.c:80-322`.
 ///
 /// # Example
@@ -131,6 +144,43 @@ pub fn ar_detect_marker(
         }
     };
 
+    // Frame-buffer contract (artoolkit5/video2.c:682, issue #103): when
+    // ar_pixel_size > 0 (i.e. a known fixed bytes-per-pixel format), `buff`
+    // length must equal xsize * ysize * pixel_size. Sub-sampled formats
+    // (NV21, 420v, 420f) have pixel_size == 0 and are skipped.
+    let pixel_size = ar_handle.ar_pixel_size as usize;
+    if pixel_size > 0 {
+        let expected = (ar_handle.xsize as usize) * (ar_handle.ysize as usize) * pixel_size;
+        if color_buff.len() != expected {
+            arlog_e!(
+                "ar_detect_marker: AR2VideoBufferT.buff length {} does not match \
+                 expected {} for {}x{} {:?} (pixel_size={}). \
+                 buff must hold data in the format declared by ar_pixel_format \
+                 (cf. artoolkit5 video2.c:682).",
+                color_buff.len(),
+                expected,
+                ar_handle.xsize,
+                ar_handle.ysize,
+                ar_handle.ar_pixel_format,
+                pixel_size
+            );
+            return Err("AR2VideoBufferT.buff length mismatches ar_pixel_format");
+        }
+    }
+    // Buff_luma is always 1 byte per pixel.
+    let expected_luma = (ar_handle.xsize as usize) * (ar_handle.ysize as usize);
+    if luma_buff.len() != expected_luma {
+        arlog_e!(
+            "ar_detect_marker: AR2VideoBufferT.buff_luma length {} does not match \
+             expected {} for {}x{} (1 byte/pixel)",
+            luma_buff.len(),
+            expected_luma,
+            ar_handle.xsize,
+            ar_handle.ysize
+        );
+        return Err("AR2VideoBufferT.buff_luma length mismatches xsize*ysize");
+    }
+
     let thresh = ar_handle.ar_labeling_thresh as u8;
     // TODO: port AR_LABELING_THRESH_MODE_*_AUTO variants (bracketing, median, etc.) from C
     let label_mode = if ar_handle.ar_labeling_mode == 0 {