fix(example): reproduce & validate small-marker pinball-demo.jpg detection (#53)

[kalwalt]

Summary

Validates the WebARKitLib small-marker fix (webarkit/WebARKitLib#53) against the
pinball-demo.jpg scene using the static-image example. The WebARKitLib submodule
is bumped to the #53 fix (f9c68a8), the example now loads the small-marker scene,
and the WASM toolchain is made offline-capable so the bundles can be rebuilt in
network-restricted CI.

Features accomplished

• Submodule emscripten/WebARKitLib: ce5c280 → f9c68a8 (the #53 fix).
• Example threejs_teblid_static_image_ES6_example.html: pinball-demo-big.jpg
  → pinball-demo.jpg (the small-marker scene, 2000×1500 → detection pyrLevel=1).
• tools/makem.js: dropped -s USE_ZLIB=1 / -s USE_LIBJPEG (emscripten ports
  fetch from github.com at build time and fail under TLS-intercepted / offline
  environments); links the prebuilt WASM zlib (opencv_js/3rdparty/lib/libzlib.a)
  instead. No libjpeg symbols are used by the tracker (examples decode JPEG in JS).
• Rebuilt build/ WASM bundles with the fix.

Issues resolved

• Investigate: small-marker pinball-demo.jpg not detected under downsampling (works in WebARKitLib-rs & jsartoolkitNFT) WebARKitLib#53 — AKAZE confirmed fixed. Headless validation
  (pinball.jpg ref + pinball-demo.jpg scene) shows the marker is detected with
  the fix (FOUND at attempt 2, 1809 keypoints/matches on the downsampled frame)
  vs NOT FOUND before. The win came from the OCVT-aligned AKAZE params
  (threshold 3e-4→1e-3, nn_match_ratio 0.7→0.8).

What's next

• TEBLID / ORB / FREAK fail small-marker detection even at full resolution (homography stage) — follow-up to #53 WebARKitLib#65 — TEBLID / ORB / FREAK still fail on this scene even at
  full resolution. Root cause is downstream of keypoint detection (ratio-test →
  homography RANSAC), independent of the pyrDown issue #53 addressed. A follow-up
  PR will investigate and fix it; the example intentionally stays on TEBLID until then.
• Rebuild & commit dist/WebARKit.js (npm run build-es6) so the live browser
  example picks up the rebuilt WASM.

[qodo-code-review]

PR Summary by Qodo

Reproduce small-marker tracking with the updated WebARKitLib

🐞 Bug fix ⚙️ Configuration changes 🕐 20-40 Minutes

AI Description

• Advances WebARKitLib to the small-marker detection fix.
• Exercises the lower-resolution pinball scene in the static-image example.
• Links bundled zlib directly, avoiding network-dependent Emscripten ports during WASM builds.

Diagram

graph TD
  SCENE["Small scene"] --> EXAMPLE["Static example"] --> WORKER["Browser worker"] --> API["WebARKit API"] --> WASM["WASM module"] --> TRACKER["WebARKitLib fix"]
  BUILD["WASM build"] --> ZLIB["Bundled zlib"] --> WASM

Loading

High-Level Assessment

The following are alternative approaches to this PR:

1. Add an automated headless regression test

• ➕ Directly asserts that the small marker is detected
• ➕ Prevents future WebARKitLib or WASM rebuild regressions
• ➕ Removes reliance on manual browser observation
• ➖ Requires a browser or WASM-capable test harness
• ➖ Adds fixture management and potentially expensive CI execution

2. Preseed the Emscripten ports cache

• ➕ Retains standard USE_ZLIB dependency handling
• ➕ Lets Emscripten manage port compatibility
• ➖ Requires additional CI cache provisioning
• ➖ Is less reliable in clean, fully offline environments
• ➖ May vary with Emscripten SDK versions

Recommendation: The submodule bump, representative scene, and direct linkage of the existing OpenCV zlib archive are pragmatic for reproducing the issue and enabling offline builds. For durable validation, add a headless detection assertion; the changed HTML still selects teblid, so it does not independently demonstrate the described AKAZE success unless the tracker selector is also aligned.

Files changed (3) +6 / -4

Bug fix (1) +1 / -1

threejs_teblid_static_image_ES6_example.htmlLoad the small-marker pinball scene +1/-1

Load the small-marker pinball scene

• Replaces 'pinball-demo-big.jpg' with the lower-resolution 'pinball-demo.jpg' scene so the static-image example exercises the small-marker case.

examples/threejs_teblid_static_image_ES6_example.html

Other (2) +5 / -3

WebARKitLibAdvance WebARKitLib to the small-marker fix +1/-1

Advance WebARKitLib to the small-marker fix

• Updates the WebARKitLib gitlink from 'ce5c280' to 'f9c68a8', bringing in the upstream small-marker detection correction.

emscripten/WebARKitLib

makem.jsMake zlib linkage independent of Emscripten ports +4/-2

Make zlib linkage independent of Emscripten ports

• Disables the 'USE_ZLIB' and 'USE_LIBJPEG' port flags that can trigger network downloads. Adds OpenCV's prebuilt 'libzlib.a' to the static libraries linked into both WASM variants.

tools/makem.js

[qodo-code-review]

Code Review by Qodo

🐞 Bugs (1) 📘 Rule violations (0) 📜 Skill insights (0)

1. Failing tracker validates wrong fix ✓ Resolved 🐞 Bug ≡ Correctness

Description

The new small-marker scene is still passed to the TEBLID tracker, although this PR's validation
establishes that only AKAZE detects it and TEBLID remains unfixed. The example therefore exhausts
its bounded attempts without demonstrating the small-marker fix.

Code

examples/threejs_teblid_static_image_ES6_example.html[38]

+    <img id="static-image" src="data/pinball-demo.jpg"

Evidence

The HTML explicitly chooses teblid; the worker forwards that string to controller initialization,
and the controller selects TRACKER_TEBLID. The processing loop gives up after twelve unsuccessful
responses, so the changed scene cannot validate the AKAZE-only result described by this PR.

examples/threejs_teblid_static_image_ES6_example.html[46-49]
examples/worker_threejs.js[22-30]
examples/worker_threejs.js[64-66]
src/WebARKitController.js[96-104]
examples/threejs_static_image_worker_ES6.js[157-164]
examples/threejs_static_image_worker_ES6.js[203-205]

Agent prompt

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

## Issue description
The small-marker scene is configured to use TEBLID even though the validated fix succeeds only with AKAZE. Use an AKAZE-specific example for this scene, or retain the working large scene in the TEBLID example until TEBLID is fixed.

## Issue Context
`setTrackerType()` returns `teblid`, the worker forwards that value unchanged, and `WebARKitController` maps it to `TRACKER_TEBLID`. Repeated failures stop after twelve attempts.

## Fix Focus Areas
- examples/threejs_teblid_static_image_ES6_example.html[38-49]
- examples/threejs_static_image_worker_ES6.js[157-165]
- examples/threejs_static_image_worker_ES6.js[203-205]

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

---

2. Example uses stale tracker bundle 🐞 Bug ≡ Correctness

Description

The changed example executes dist/WebARKit.js, which embeds its WASM dependency during webpack
bundling and was not rebuilt after the submodule/WASM changes. Consequently, switching to the
small-marker image still runs the pre-fix tracker and reproduces the old detection failure.

Code

examples/threejs_teblid_static_image_ES6_example.html[38]

+    <img id="static-image" src="data/pinball-demo.jpg"

Evidence

The changed HTML loads the static-image driver, which creates worker_threejs.js; that worker
imports only dist/WebARKit.js. The source controller imports the generated WASM module, while
webpack emits the controller and that dependency into dist/WebARKit.js, proving the rebuilt
build/ files reach this example only after webpack regenerates the distribution.

examples/threejs_teblid_static_image_ES6_example.html[52-52]
examples/threejs_static_image_worker_ES6.js[91-95]
examples/worker_threejs.js[1-1]
src/WebARKitController.js[1-1]
webpack.config.js[40-49]

Agent prompt

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

## Issue description
The static-image example loads `dist/WebARKit.js`, not the newly rebuilt WASM files directly. Rebuild and commit the distribution bundle so it embeds the updated tracker implementation.

## Issue Context
`worker_threejs.js` imports the distribution artifact. Webpack builds that artifact from `src/WebARKitController.js`, which imports the SIMD WASM module, so rebuilding only `build/webarkit_ES6_wasm*.js` does not update the example's runtime code.

## Fix Focus Areas
- examples/threejs_teblid_static_image_ES6_example.html[38-52]
- examples/worker_threejs.js[1-1]
- src/WebARKitController.js[1-1]
- package.json[38-41]

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

---

Context sources

Review mode: ⚖️ Balanced

Tip of the day

💡 Did you know, you can turn on the rule miner and Qodo learns your standards from review history

More tips ↗ | Customize Qodo ↗ | Qodo docs ↗