new release 0.9.0

[kalwalt]

This pull request introduces several important improvements and updates across the build system, versioning, and the core matching logic for handling multiple reference images per page. The changes enhance the flexibility of OpenCV integration, improve multi-marker support in the matching pipeline, and update dependencies and documentation for clarity and correctness.

Build and Dependency Updates:

• Upgraded GitHub Actions workflow to use newer versions of actions/checkout (v7), actions/setup-node (v6), Node.js (22.x), and the Emscripten Docker image (3.1.69) for improved compatibility and performance. [1] [2]
• Centralized OpenCV version and hash configuration in the new cmake/OpenCVEm.cmake file, supporting both native and multiple Emscripten builds (including SIMD), and updated CMake files to fetch OpenCV using these shared settings. [1] [2] [3] [4]

Versioning and Documentation:

• Updated WebARKit version to 0.9.0 in code and tests to reflect new features and changes. [1] [2] [3] [4]
• Improved CONTRIBUTING.md with clearer instructions for merging long-lived branches, emphasizing the use of merge commits for branch syncs to prevent history issues.

Multi-Marker Matching Enhancements:

• Refactored the matcher logic to keep all reference images that pass geometric verification, not just the single best match. The new image_match_t and image_matches_t types store all successful matches per query, enabling robust multi-marker (multi-page) support. [1] [2] [3] [4] [5] [6] [7]
• Updated the matching pipeline in kpmMatching.cpp to aggregate and process all valid matches per page, ensuring that pose estimation attempts all candidates and improves tracking reliability when multiple markers are visible. [1] [2] [3] [4]

Summary of Most Important Changes

Multi-Marker Matching Improvements:

• Introduced image_match_t and image_matches_t types to store all geometrically verified matches, not just the best one, and refactored the matching pipeline to process all valid matches per page for robust multi-marker support. [1] [2] [3] [4] [5] [6] [7] [8]

Build System and Dependency Management:

• Centralized and upgraded OpenCV dependency management via the new cmake/OpenCVEm.cmake, supporting native, Emscripten, and SIMD builds, and updated CMake and test configuration to use these settings. [1] [2] [3] [4]
• Updated GitHub Actions workflow to use newer versions of tools and Docker images, improving build reliability and future-proofing the CI pipeline. [1] [2]

Versioning and Documentation:

• Bumped WebARKit version to 0.9.0 in code and tests to match new features and changes. [1] [2] [3] [4]
• Clarified branch merging procedures in CONTRIBUTING.md, highlighting the importance of merge commits for branch syncs to maintain correct git history.

[qodo-free-for-open-source-projects]

PR Summary by Qodo

Release 0.9.0 with multi-page matching and OpenCV 4.12

✨ Enhancement 🐞 Bug fix ⚙️ Configuration changes 📝 Documentation 🕐 40+ Minutes

AI Description

• Retains every geometrically verified image match and estimates poses for each matched page.
• Centralizes OpenCV 4.12 artifacts, hashes, and optional Emscripten SIMD selection.
• Releases WebARKit 0.9.0 with refreshed CI and branch-sync guidance.

Diagram

graph TD
  Q["Query frame"] --> V["Visual database"] --> G{"Geometry valid?"}
  G -->|Yes| M["Image matches"] --> P["Page grouping"] --> S["Pose estimation"] --> R["Page results"]
  G -->|No| X["Discard candidate"]

Loading

High-Level Assessment

The following are alternative approaches to this PR:

1. Aggregate matches inside VisualDatabase

• ➕ Could return one ranked candidate collection per logical page.
• ➕ Would reduce grouping logic in kpmMatching.cpp.
• ➖ The generic visual database does not own KPM page metadata.
• ➖ It would couple reusable image matching code to KPM-specific page semantics.
• ➖ Existing consumers rely on database image identifiers rather than page identifiers.

2. Keep only the best image per page

• ➕ Reduces retained match data and pose-estimation attempts.
• ➕ Provides simpler downstream result processing.
• ➖ Requires page metadata during matching or an additional filtering pass.
• ➖ Loses fallback candidates when the strongest image match cannot produce a pose.
• ➖ Could reduce tracking reliability for pages registered at multiple scales.

Recommendation: Keep the PR's separation: VisualDatabase should expose every verified image while KPM performs page-aware grouping and pose fallback. This preserves the existing single-best-match API for compatibility, avoids coupling the generic matcher to KPM page metadata, and retains alternate scale candidates when pose fitting fails.

Files changed (14) +152 / -68

Enhancement (4) +30 / -5

visual_database_facade.cppExpose all verified matches through the facade +5/-1

Expose all verified matches through the facade

• Implements the facade accessor that forwards the latest collection of geometrically verified image matches.

lib/SRC/KPM/FreakMatcher/facade/visual_database_facade.cpp

visual_database_facade.hDeclare the multi-match facade API +3/-1

Declare the multi-match facade API

• Adds a public matches() accessor so KPM consumers can retrieve every verified reference image rather than only the best match.

lib/SRC/KPM/FreakMatcher/facade/visual_database_facade.h

matcher_types.hDefine per-image verified match results +12/-1

Define per-image verified match results

• Introduces image_match_t to retain a reference image ID, inlier correspondences, and homography. Adds image_matches_t as the collection returned for each query.

lib/SRC/KPM/FreakMatcher/matchers/matcher_types.h

visual_database.hStore and expose multi-image query matches +10/-2

Store and expose multi-image query matches

• Adds the verified-match collection and its accessor to VisualDatabase while preserving matchedId(), inliers(), and matchedGeometry() as the single-best-match interface.

lib/SRC/KPM/FreakMatcher/matchers/visual_database.h

Bug fix (3) +58 / -43

visual_database-inline.hRetain every geometrically verified reference image +16/-5

Retain every geometrically verified reference image

• Clears multi-match state for each query and records every candidate meeting the inlier threshold. The legacy best-match fields remain populated with the strongest candidate for compatibility.

lib/SRC/KPM/FreakMatcher/matchers/visual_database-inline.h

kpmMatching.cppEstimate poses for every matched page +41/-38

Estimate poses for every matched page

• Maps database images to internal page indices, groups verified candidates by page, and tries each page's candidates in descending inlier order. Successful results now use the correct internal result index while retaining the page's external number.

lib/SRC/KPM/kpmMatching.cpp

kpmPrivate.hTrack database images by internal page index +1/-0

Track database images by internal page index

• Adds a database-image-to-page-index mapping so matching results address result[] independently of externally assigned page numbers.

lib/SRC/KPM/kpmPrivate.h

Tests (1) +2 / -2

webarkit_test.ccUpdate version assertions for WebARKit 0.9.0 +2/-2

Update version assertions for WebARKit 0.9.0

• Adjusts configuration and manager version expectations to verify the new 0.9.0 release identifier.

tests/webarkit_test.cc

Documentation (1) +18 / -1

CONTRIBUTING.mdDocument safe long-lived branch synchronization +18/-1

Document safe long-lived branch synchronization

• Corrects the target branch terminology and requires merge commits when synchronizing long-lived branches. It explains why squash or rebase merges break ancestry and cause repeated conflicts.

CONTRIBUTING.md

Other (5) +44 / -17

test.ymlRefresh CI actions, Node.js, and Emscripten +4/-4

Refresh CI actions, Node.js, and Emscripten

• Upgrades checkout and Node setup actions, moves CI to Node.js 22.x, and aligns the Emscripten container with the compiler used by the new OpenCV artifacts.

.github/workflows/test.yml

CMakeLists.txtSelect centralized native or Emscripten OpenCV artifacts +22/-10

Select centralized native or Emscripten OpenCV artifacts

• Loads shared OpenCV release coordinates, adds the WEBARKIT_SIMD option, and selects native, standard Emscripten, or SIMD Emscripten packages. Fetches are now protected by SHA-256 verification.

WebARKit/CMakeLists.txt

WebARKitConfig.cppBump the WebARKit runtime version to 0.9.0 +2/-2

Bump the WebARKit runtime version to 0.9.0

• Updates the exposed version string and minor-version constant from 0.8 to 0.9.

WebARKit/WebARKitTrackers/WebARKitOpticalTracking/WebARKitConfig.cpp

OpenCVEm.cmakeCentralize OpenCV 4.12 release coordinates +13/-0

Centralize OpenCV 4.12 release coordinates

• Defines the opencv-em 0.2.0 release URL and checksums for native, Emscripten, and SIMD Emscripten packages. This provides one upgrade point for production and test builds.

cmake/OpenCVEm.cmake

CMakeLists.txtUse shared verified OpenCV dependency settings +3/-1

Use shared verified OpenCV dependency settings

• Reuses the centralized native OpenCV 4.12 URL and SHA-256 hash instead of maintaining a separate hardcoded test dependency.

tests/CMakeLists.txt

[qodo-free-for-open-source-projects]

Code Review by Qodo

🐞 Bugs (1) 📘 Rule violations (0) 📎 Requirement gaps (0) 🎨 UX issues (0) 🔗 Cross-repo conflicts (0) 📜 Skill insights (0)

1. Reloading a smaller dataset can crash ✓ Resolved 🐞 Bug ☼ Reliability

Description

kpmMatching() trusts every retained matcher ID when reading pageIndices and indexing result,
while kpmSetRefDataSet() reuses the existing visual database and only rewrites mappings for IDs
present in the newly loaded dataset. After replacing a dataset with fewer images, a stale higher-ID
keyframe that passes verification is processed by the new all-match loop and can resolve to an old
page index beyond the new result array.

Code

lib/SRC/KPM/kpmMatching.cpp[R653-654]

+for (const vision::image_match_t& imageMatch : imageMatches) {
+    candidatesPerPage[kpmHandle->pageIndices[imageMatch.id]].push_back(&imageMatch);

Evidence

The public API explicitly allows a later dataset load, but the setter only replaces KPM-owned
dataset and result storage before restarting database IDs at zero; it never clears freakMatcher.
The visual database rejects duplicate IDs without replacing existing keyframes, while the facade
still overwrites point data, and the new loop consumes every returned ID and indexes the newly sized
result array through its old page mapping.

include/KPM/kpm.h[223-241]
lib/SRC/KPM/kpmMatching.cpp[194-258]
lib/SRC/KPM/kpmMatching.cpp[272-300]
lib/SRC/KPM/FreakMatcher/matchers/visual_database-inline.h[139-151]
lib/SRC/KPM/FreakMatcher/facade/visual_database_facade.cpp[76-87]
lib/SRC/KPM/kpmMatching.cpp[651-660]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
Reloading a reference dataset leaves old keyframes and 3D-point entries in the binary matcher. The new all-match loop processes those stale IDs and can index beyond the newly allocated result array.
## Fix Focus Areas
- lib/SRC/KPM/kpmMatching.cpp[242-300]
- lib/SRC/KPM/kpmMatching.cpp[651-660]
- lib/SRC/KPM/FreakMatcher/facade/visual_database_facade.cpp[42-87]
## Recommended Fix
Clear or recreate the binary visual database and its 3D-point map before registering a replacement reference dataset. Also validate every returned image ID and derived page index before using them to access `pageIndices` or `result`, returning or logging an explicit error when an invariant is violated.

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

2. Large reference sets corrupt memory 🐞 Bug ☼ Reliability

Description

kpmSetRefDataSet() writes pageIndices[db_id] once per reference image without checking
DB_IMAGE_MAX. When a dataset contains 1024 or more page images, the new mapping write runs beyond
the handle’s fixed array and later matching uses the corrupted mapping as a result index.

Code

lib/SRC/KPM/kpmMatching.cpp[298]

+                kpmHandle->pageIndices[db_id] = k;

Evidence

The new pageIndices mapping has the same fixed capacity as the existing page-ID mapping, but the
registration loop iterates every image declared by every page and increments db_id with no
capacity check. The matching path then dereferences the new mapping using matcher image IDs, making
the overflow affect result indexing.

lib/SRC/KPM/kpmPrivate.h[44-44]
lib/SRC/KPM/kpmPrivate.h[88-92]
lib/SRC/KPM/kpmMatching.cpp[275-300]
lib/SRC/KPM/kpmMatching.cpp[651-660]
include/KPM/kpm.h[78-109]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
`kpmSetRefDataSet()` registers one matcher database ID per page image, but writes the new `pageIndices[db_id]` mapping into a fixed `DB_IMAGE_MAX` array without validating the aggregate image count. A dataset with at least 1024 images writes past the `KpmHandle` allocation, and `kpmMatching()` subsequently reads this mapping to index `result`.
## Fix Focus Areas
- lib/SRC/KPM/kpmMatching.cpp[275-300]
- lib/SRC/KPM/kpmPrivate.h[88-92]
- lib/SRC/KPM/kpmMatching.cpp[651-660]
## Recommended Fix
Before registering images, count the total `imageNum` values and reject datasets exceeding `DB_IMAGE_MAX` with an error, before writing either per-image mapping. Prefer replacing both fixed mapping arrays with vectors sized to the registered image count if supporting larger datasets is required; retain a bounds check before every mapping access.

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

Tip of the day

💡 Did you know, you can reply 'qodo' on any finding to push back, ask questions, or dig deeper

More tips ↗ | Customize Qodo ↗ | Qodo docs ↗

[qodo-free-for-open-source-projects]

2. Large reference sets corrupt memory 🐞 Bug ☼ Reliability

kpmSetRefDataSet() writes pageIndices[db_id] once per reference image without checking
DB_IMAGE_MAX. When a dataset contains 1024 or more page images, the new mapping write runs beyond
the handle’s fixed array and later matching uses the corrupted mapping as a result index.

Agent Prompt

## Issue description
`kpmSetRefDataSet()` registers one matcher database ID per page image, but writes the new `pageIndices[db_id]` mapping into a fixed `DB_IMAGE_MAX` array without validating the aggregate image count. A dataset with at least 1024 images writes past the `KpmHandle` allocation, and `kpmMatching()` subsequently reads this mapping to index `result`.

## Fix Focus Areas
- lib/SRC/KPM/kpmMatching.cpp[275-300]
- lib/SRC/KPM/kpmPrivate.h[88-92]
- lib/SRC/KPM/kpmMatching.cpp[651-660]

## Recommended Fix
Before registering images, count the total `imageNum` values and reject datasets exceeding `DB_IMAGE_MAX` with an error, before writing either per-image mapping. Prefer replacing both fixed mapping arrays with vectors sized to the registered image count if supporting larger datasets is required; retain a bounds check before every mapping access.

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

[kalwalt]

Confirmed, and fixed in #74 (86b61a0). pageIDs[] and pageIndices[] hold DB_IMAGE_MAX (1024) entries, one per registered image (pages × scales), and nothing checked the total. kpmSetRefDataSet() now counts the images first and rejects the dataset with an ARLOGe before changing any state, so neither array can be overrun. pageIDs[] was already unguarded before #71. Moving to vectors would lift the limit, but the bound is enough for the realistic sizes (jsartoolkitNFT caps markers at PAGES_MAX = 20).