AR_MATRIX_CODE_GLOBAL_ID decoding not implemented; ARMarkerInfo::global_id always 0

[kalwalt]

Summary

AR_MATRIX_CODE_GLOBAL_ID matrix decoding is not implemented; consequently ARMarkerInfo::global_id is never populated.

Environment

• Product/Service: webarkit/WebARKitLib-rs
• Crate/Module: crates/core/src/ar/matrix.rs, crates/core/src/ar/marker.rs
• Discovery context: ARMarkerInfo field-population audit during PR Fix marker.cf_patt/id_patt and symmetric matrix-mode bug #87 (issue marker.cf_patt / marker.id_patt not populated when template match succeeds #86 follow-up)

Reproduction Steps

1. Configure the pipeline with matrix_code_type = ARMatrixCodeType::GlobalID (if/when present in the enum) or any code type that upstream ARToolKit treats as global-ID.
2. Run detection against a global-ID marker.
3. Inspect marker.global_id on the resulting ARMarkerInfo.

Expected Behavior

Per include/AR/ar.h:214:

globalID — If arPattDetectionMode is a matrix mode, matrixCodeType is AR_MATRIX_CODE_GLOBAL_ID, and idMatrix >= 0, will contain the globalID.

C populates this via arPattGetIDGlobal as one of the out-params at arGetMarkerInfo.c:80. ARMulti uses it explicitly at arMultiGetTransMat.c:96-98 and arMultiReadConfigFile.c:92-113 to dispatch on a 64-bit global identifier.

Actual Behavior

1. crates/core/src/ar/matrix.rs:529-532 explicitly punts on the variant:

   _ => {
       // The unhandled types include GLOBAL_ID, etc.
       Ok((code_raw as i32, 0))
   }

2. ar_get_marker_info therefore has no value to write into marker_info[j].global_id, and the field remains 0 (its Default::default() value).

Source References

• C contract:
  https://github.com/webarkit/WebARKitLib/blob/master/lib/SRC/AR/arGetMarkerInfo.c#L80
• C field documentation:
  https://github.com/webarkit/WebARKitLib/blob/master/include/AR/ar.h#L214
• Rust unhandled variant:
  crates/core/src/ar/matrix.rs:529-532

Impact

Medium-Low — only affects users who would otherwise want to use AR_MATRIX_CODE_GLOBAL_ID (a 64-bit identifier scheme). Users on AR_MATRIX_CODE_3x3, 4x4_BCH_*, 5x5_BCH_* are unaffected. Blocks any future port of ARMulti's global-ID path.

Suggested Approach

This is genuinely a missing feature, not just plumbing:

1. Decide whether AR_MATRIX_CODE_GLOBAL_ID should be added as an explicit ARMatrixCodeType variant (currently swallowed by the _ => arm).
2. Port the C decoding (encoding is described at arGetMarkerInfo.c and helpers in lib/SRC/AR/arPattGetID.c).
3. Plumb the resulting u64 out of ar_matrix_code_get_id and write it into marker_info[j].global_id in ar_get_marker_info.
4. Add unit tests with hand-crafted global-ID bit patterns from upstream test data, if available.

Recommend treating this as its own work item — do not bundle it with the cutoff_phase plumbing issue, the scope is qualitatively different.

Additional Context

• Discovered during the same audit that produced marker.cf_patt / marker.id_patt not populated when template match succeeds #86 and the cutoff_phase follow-up issue.
• marker_info2_ptr was also unpopulated, but matches upstream behavior (C never sets it either) — that one is not a bug.

Labels suggested: enhancement, area:matrix-code, help-wanted.
Priority: Low (no current consumer in the repo blocked).

[kalwalt]

Scope discovery — substantially larger than initial plan

While planning for #88 (cutoff_phase plumbing) we initially scoped #89 as small plumbing too: add ARMatrixCodeType::GlobalId, surface global_id from the matrix decoder, populate ARMarkerInfo::global_id. Inspecting the C source (arPattGetID.c) revealed this is substantially more than plumbing — it's a missing decoder.

What AR_MATRIX_CODE_GLOBAL_ID actually requires

1. A different grid sampler — uses a 14×14 outer grid (AR_GLOBAL_ID_OUTER_SIZE), not the 3..=6 grids our current ar_matrix_code_get_id handles. See arPattGetID.c:98-99. Our dim ∉ 3..=6 early-bail (matrix.rs:100) rejects it outright.
2. A different BCH decoder — uses BCH(127, 64) with t=9 error correction (Hamming distance 19). 120 data bits encoded into a 127-bit codeword. See arPattGetID.c:1864-1869:

   } else if (matrixCodeType == AR_MATRIX_CODE_GLOBAL_ID) {
       t = 9; k = 64;
       n = 127;
       length = 120;

   Our bch.rs does not have these parameters.
3. A custom bit-extraction layout — skips the 3×3 inner region and locator-corner cells, with four orientation-specific loops. See arPattGetID.c:2336-2390.
4. The (globalID & 0xffff8000) == 0 ? lower 15 bits : 0 formula that initially looked like the decoding step is actually from arMultiReadConfigFile.c:111 — that's a config file parser, not image decoding. It maps a stored globalID to a short alias id_matrix. It is downstream of decoding, not the decoding itself.

Why this matters for #88

Issue #88 just merged a redesign of pattern_match and ar_matrix_code_get_id to return Result<MatchOk, MatchError>. We initially planned to add MatchOk.global_id: Option<u64> to surface a global-ID value. We dropped that field for now (commit 05e45dd on branch issue/88-89-cutoff-phase-global-id) — it would have been dead weight (always None) without the actual decoder. The field will reappear when this issue is implemented.

Proposed scope for #89

Three sub-tasks:

1. bch.rs extension — add BCH(127, 64, t=9) decoder. Likely needs new GF tables; can crib from arPattGetID.c:1869-2000 or use an existing crate.
2. matrix.rs GlobalId branch — add ARMatrixCodeType::GlobalId enum variant; in ar_matrix_code_get_id, branch on it before the dim ∉ 3..=6 check; implement the 14×14 sampler and the orientation-aware bit-extraction loop.
3. Wiring — re-add MatchOk.global_id: Option<u64> and populate marker.global_id in marker.rs.

C-faithfulness: stay close to arPattGetID.c:1864-2400 for the decoder, our arGetMarkerInfo.c:80 parity for the call site.

References

All line refs are against the WebARKitLib repo as of submodule SHA pinned in benchmarks/c_benchmark/libraries.json:

• Header constant + bit layout constants: https://github.com/webarkit/WebARKitLib/blob/master/lib/SRC/AR/arPattGetID.c#L98-L99
• Top-level dispatch on AR_MATRIX_CODE_GLOBAL_ID: https://github.com/webarkit/WebARKitLib/blob/master/lib/SRC/AR/arPattGetID.c#L200-L205
• BCH(127, 64) parameters: https://github.com/webarkit/WebARKitLib/blob/master/lib/SRC/AR/arPattGetID.c#L1864-L1869
• Bit-extraction loops (per orientation): https://github.com/webarkit/WebARKitLib/blob/master/lib/SRC/AR/arPattGetID.c#L2336-L2390
• decode_bch call: https://github.com/webarkit/WebARKitLib/blob/master/lib/SRC/AR/arPattGetID.c#L2397
• Config-file alias formula (NOT the decoder): https://github.com/webarkit/WebARKitLib/blob/master/lib/SRC/ARMulti/arMultiReadConfigFile.c#L111

Recommendation

Treat #89 as a self-contained feature port — likely 1–2 days of focused work. Not blocking #88. Could be a candidate for the M6 milestone or its own follow-up milestone since the BCH(127,64) decoder is reusable for other future codes.