From 8758933a227f8dc02a7ba1298b7827568f910533 Mon Sep 17 00:00:00 2001 From: Walter Perdan Date: Sat, 20 Jun 2026 23:52:50 +0200 Subject: [PATCH 1/7] docs(#51): rewrite README + bump version to 0.8.0 MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit README: replace the stub with a developer-oriented map — the two lineages (WebARKit/ = ArtoolkitX-OCVT-derived active code vs vendored lib/SRC + include/AR = old ARToolKit5, built by jsartoolkitNFT; ARnft consumes jsartoolkitNFT as an npm module), code layout, pose pipeline, who-builds-what (webarkit-testing builds WebARKit/ to WASM via makem.js, CMake migration planned), the gtest/CMake tests, and the contribution path. version: 0.8.0 (was 1.0.0) -- 1.0.0 should denote a complete/LTS release, which this isn't yet. Updates WEBARKIT_HEADER_VERSION_STRING + MAJOR/MINOR. Refs #51. Co-Authored-By: Claude Opus 4.8 --- README.md | 86 +++++++++++++++++-- .../WebARKitConfig.cpp | 6 +- 2 files changed, 82 insertions(+), 10 deletions(-) diff --git a/README.md b/README.md index 0963902..e3f227b 100644 --- a/README.md +++ b/README.md @@ -1,15 +1,87 @@ - ![github releases](https://flat.badgen.net/github/release/webarkit/WebARKitLib) ![github stars](https://flat.badgen.net/github/stars/webarkit/WebARKitLib) ![github forks](https://flat.badgen.net/github/forks/webarkit/WebARKitLib)[![Test](https://github.com/webarkit/WebARKitLib/actions/workflows/test.yml/badge.svg)](https://github.com/webarkit/WebARKitLib/actions/workflows/test.yml) + # WebARKitLib -The C/C++ source code of WebARKit, from Artoolkit5 and extended. +The C/C++ source of **WebARKit** — a browser-side Augmented Reality tracker. The +active code (`WebARKit/`) is an emscripten-friendly port of the **OCVT** planar +image-tracking design from [ArtoolkitX](https://github.com/artoolkitx/artoolkitx), +built on OpenCV. It is normally compiled to WebAssembly and consumed from the +[webarkit-testing](https://github.com/webarkit/webarkit-testing) superproject. + +> **Two lineages live here, keep them straight:** +> - **`WebARKit/`** — the WebAR OCVT planar tracker (the design reference is *ArtoolkitX*). This is the code under active development. +> - **`lib/SRC/**`, `include/AR/**`** — vendored **old ARToolKit5** utility sources/headers, kept only because [jsartoolkitNFT](https://github.com/webarkit/jsartoolkitNFT) needs them (and [ARnft](https://github.com/webarkit/ARnft) in turn consumes jsartoolkitNFT as an npm module). Treated as untouched upstream. (Updated to Eigen 3.4.0 / emsdk 3.1.26.) + +## Code layout (`WebARKit/`) + +| Component | Role | +|---|---| +| `WebARKitManager` | top-level façade — owns the tracker, drives init/process, exposes the output (homography, pose, GL-view, projection) | +| `WebARKitTrackers/WebARKitOpticalTracking/WebARKitTracker` | the OCVT tracker core: feature detect/match → homography → optical-flow + template-match tracking | +| `…/TrackingPointSelector` + `…/TrackedPoint` | bin-based selection of template tracking points (ArtoolkitX-derived) | +| `…/WebARKitHomographyInfo` + `WebARKitUtils.h` | RANSAC homography estimation/validation (`getHomographyInliers`) | +| `…/WebARKitConfig` | tuning constants (feature counts, match ratios, pyramid/template sizes, version) | +| `…/TrackerVisualization` | optional debug-overlay scaffolding (inert until wired) | +| `WebARKitCamera` | camera intrinsics from a diagonal-FOV estimate | +| `WebARKitGL` | CV→GL matrix conversion (`arglCameraViewRHf`) + GL projection | +| `WebARKitPattern` | the reference marker (`WebARKitPattern`) and per-frame pose state (`WebARKitPatternTrackingInfo`) | +| `WebARKitLog` | logging | + +## Pose pipeline (one glance) + +``` +solvePnP (cameraPoseFromPoints) // OpenCV-convention camera pose + -> getTrackablePose / updateTrackable // CV->GL handedness fix, D*R*D (see #42) + -> arglCameraViewRHf // right-handed GL modelview + -> matrixGL_RH // what the examples attach content to +``` + +Pose getters: **`getPoseMatrixCV()`** (raw 4×4 OpenCV pose) and **`getPoseMatrixGL()`** +(the GL/right-handed pose); projection via `getCameraProjectionMatrix()`. The full +derivation is in +[`docs/design-projection-and-pose-artoolkitx-alignment.md`](https://github.com/webarkit/webarkit-testing/blob/dev/docs/design-projection-and-pose-artoolkitx-alignment.md) +(webarkit-testing). + +## Building + +This repo isn't built as a single unit — each consumer compiles the **subset it +needs**: + +- **`WebARKit/` (the OCVT tracker)** is built by the + [webarkit-testing](https://github.com/webarkit/webarkit-testing) superproject, which + compiles it to WebAssembly with emscripten (emsdk **3.1.26**) inside Docker and wires + it to JS through `emscripten/WebARKitJS.{cpp,h}` + `bindings.cpp` (which live in + webarkit-testing). webarkit-testing currently drives that compile with the Node script + `tools/makem.js` (`npm run build-docker` → `build-es6`); migrating to the CMake config + (`WebARKit/CMakeLists.txt`) is planned. +- **The vendored `lib/SRC/**` + `include/AR/**` (old ARToolKit5)** is built by + [jsartoolkitNFT](https://github.com/webarkit/jsartoolkitNFT) as part of its build — + not by webarkit-testing. ([ARnft](https://github.com/webarkit/ARnft) consumes + jsartoolkitNFT as an npm module and doesn't build the emscripten code itself.) + +A standalone CMake config also exists for the unit tests (see below). + +## Tests + +C++ unit tests (GoogleTest) live in [`tests/`](tests/) (`webarkit_test.cc`, +`CMakeLists.txt`, `pinball.jpg`) and run in CI via +[`.github/workflows/test.yml`](https://github.com/webarkit/WebARKitLib/actions/workflows/test.yml). +Build them standalone with CMake: + +```bash +cmake -S tests -B tests/build && cmake --build tests/build && ctest --test-dir tests/build +``` + +## Contributing -Updated to [Eigen](https://eigen.tuxfamily.org) 3.4.0 and Emscripten emsdk 3.1.26. +- Branch from `dev`; PR back to `dev`; sign your commits and reference the issue. +- Library changes are usually paired with a build/bump in webarkit-testing — see that + repo's "cross-repo PR pair" flow. +- Don't modify the vendored `lib/SRC/**` / `include/AR/**` (old ARToolKit5) as part of + WebAR work. -## Features +## License -The library containes the following features: -**Artoolkit5** C/C++ code used by [jsartoolkitNFT](https://github.com/webarkit/jsartoolkitNFT) and [ARnft](https://github.com/webarkit/ARnft) (see lib and include folders). Note that is not the full Artoolkit5 library, but only the code needed by jsartoolkitNFT and ARnft. The code is updated to Eigen 3.4.0 and can be compiled with Emscripten emsdk 3.1.26. -**WebARKit** C++ code, which is our experimental code for WebAR. It is completetly independent from Artoolkit5 and can be used as a standalone library. It can be compiled with Emscripten emsdk 3.1.26. \ No newline at end of file +LGPL-3.0 (see `LICENSE.txt`). diff --git a/WebARKit/WebARKitTrackers/WebARKitOpticalTracking/WebARKitConfig.cpp b/WebARKit/WebARKitTrackers/WebARKitOpticalTracking/WebARKitConfig.cpp index a06b027..1cf6e1e 100644 --- a/WebARKit/WebARKitTrackers/WebARKitOpticalTracking/WebARKitConfig.cpp +++ b/WebARKit/WebARKitTrackers/WebARKitOpticalTracking/WebARKitConfig.cpp @@ -21,19 +21,19 @@ extern const cv::Size blurSize(3, 3); extern const double ransac_thresh = 2.5f; extern cv::RNG rng( 0xFFFFFFFF ); extern const double m_pi = 3.14159265358979323846; -extern const std::string WEBARKIT_HEADER_VERSION_STRING = "1.0.0"; +extern const std::string WEBARKIT_HEADER_VERSION_STRING = "0.8.0"; /*@ The MAJOR version number defines non-backwards compatible changes in the ARToolKit API. Range: [0-99]. */ -extern const int WEBARKIT_HEADER_VERSION_MAJOR = 1; +extern const int WEBARKIT_HEADER_VERSION_MAJOR = 0; /*@ The MINOR version number defines additions to the ARToolKit API, or (occsasionally) other significant backwards-compatible changes in runtime functionality. Range: [0-99]. */ -extern const int WEBARKIT_HEADER_VERSION_MINOR = 0; +extern const int WEBARKIT_HEADER_VERSION_MINOR = 8; /*@ The TINY version number defines bug-fixes to existing From ef74ff56f3d39465e5b589ab2c8c8a630fc1837a Mon Sep 17 00:00:00 2001 From: Walter Perdan Date: Sun, 21 Jun 2026 00:04:50 +0200 Subject: [PATCH 2/7] test(#51): update version assertions to 0.8.0 The version bump (1.0.0 -> 0.8.0) broke the gtest version checks: WEBARKIT_HEADER_VERSION_STRING and getWebARKitVersion() are now "0.8.0". Co-Authored-By: Claude Opus 4.8 --- tests/webarkit_test.cc | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/tests/webarkit_test.cc b/tests/webarkit_test.cc index cdda727..7ac2964 100644 --- a/tests/webarkit_test.cc +++ b/tests/webarkit_test.cc @@ -38,7 +38,7 @@ TEST(WebARKitConfigTest, TestConfigValues) { EXPECT_EQ(maxLevel, 3); EXPECT_EQ(featureDetectPyramidLevel, 1.05f); EXPECT_EQ(featureBorder, 8); - EXPECT_EQ(WEBARKIT_HEADER_VERSION_STRING, "1.0.0"); + EXPECT_EQ(WEBARKIT_HEADER_VERSION_STRING, "0.8.0"); } TEST(WebARKitConfigTest, TestWinSize) { @@ -136,7 +136,7 @@ TEST(WebARKitTest, CheckWebARKitVersion) { // Init the manager with the Akaze tracker manager.initialiseBase(webarkit::TRACKER_TYPE::AKAZE_TRACKER, 640, 480); // Check if the WebARKit version is correct - EXPECT_STREQ(manager.getWebARKitVersion().c_str(), "1.0.0"); + EXPECT_STREQ(manager.getWebARKitVersion().c_str(), "0.8.0"); } // Check cameraProjectionMatrix from manager From b782441b160d048490fd455a1b0623353a7bbd04 Mon Sep 17 00:00:00 2001 From: Walter Perdan Date: Sun, 21 Jun 2026 10:22:20 +0200 Subject: [PATCH 3/7] docs(#51): clarify CMake already builds the static lib Note in the Building section that WebARKit/CMakeLists.txt can already build WebARKitLib as a static library today; the "planned" migration is specifically webarkit-testing moving its WASM build off tools/makem.js onto it. Co-Authored-By: Claude Opus 4.8 --- README.md | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index e3f227b..9fb5350 100644 --- a/README.md +++ b/README.md @@ -61,7 +61,10 @@ needs**: not by webarkit-testing. ([ARnft](https://github.com/webarkit/ARnft) consumes jsartoolkitNFT as an npm module and doesn't build the emscripten code itself.) -A standalone CMake config also exists for the unit tests (see below). +`WebARKit/CMakeLists.txt` can **already build WebARKitLib as a static library** +today; the "planned" part above is webarkit-testing switching its WASM build over to +it (away from `tools/makem.js`). A standalone CMake config also drives the unit tests +(see below). ## Tests From f5ac06f53ffe47a9490f960e0cfcbf807b89abe8 Mon Sep 17 00:00:00 2001 From: Walter Perdan Date: Sun, 21 Jun 2026 10:38:48 +0200 Subject: [PATCH 4/7] docs(#51): note static-lib targets (WASM + Linux) and opencv-em dependency Clarify the CMake static-lib build: it targets both WASM (emscripten) and native Linux via EMSCRIPTEN_COMP, and depends on a prebuilt OpenCV from webarkit/opencv-em (emscripten opencv-js build for WASM, native build for Linux), fetched via FetchContent. Co-Authored-By: Claude Opus 4.8 --- README.md | 10 +++++++--- 1 file changed, 7 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 9fb5350..e8f2b77 100644 --- a/README.md +++ b/README.md @@ -62,9 +62,13 @@ needs**: jsartoolkitNFT as an npm module and doesn't build the emscripten code itself.) `WebARKit/CMakeLists.txt` can **already build WebARKitLib as a static library** -today; the "planned" part above is webarkit-testing switching its WASM build over to -it (away from `tools/makem.js`). A standalone CMake config also drives the unit tests -(see below). +today — for both **WASM** (emscripten) and **native Linux**, selected via the +`EMSCRIPTEN_COMP` flag. It depends on a prebuilt **OpenCV** from +[webarkit/opencv-em](https://github.com/webarkit/opencv-em) (the emscripten +`opencv-js-…-emcc` build for WASM, or the native `opencv-…` build for Linux), +fetched automatically via CMake `FetchContent`. The "planned" part above is +webarkit-testing switching its WASM build over to this CMake config (away from +`tools/makem.js`). The same config also drives the unit tests (see below). ## Tests From f113d880fa47e3276ca7836e9c7a19d382ae6d0f Mon Sep 17 00:00:00 2001 From: Walter Perdan Date: Sun, 21 Jun 2026 10:53:50 +0200 Subject: [PATCH 5/7] docs(#51): require Conventional Commits + point to CONTRIBUTING.md Contributing section now requires commit messages to follow Conventional Commits and links to ./CONTRIBUTING.md (to be added) for the full guidelines. Co-Authored-By: Claude Opus 4.8 --- README.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/README.md b/README.md index e8f2b77..42448ab 100644 --- a/README.md +++ b/README.md @@ -83,7 +83,11 @@ cmake -S tests -B tests/build && cmake --build tests/build && ctest --test-dir t ## Contributing +Please read [`./CONTRIBUTING.md`](./CONTRIBUTING.md) for the full guidelines. In short: + - Branch from `dev`; PR back to `dev`; sign your commits and reference the issue. +- **Commit messages must follow [Conventional Commits](https://www.conventionalcommits.org/)** + (e.g. `feat:`, `fix:`, `docs:`, `refactor:`, `test:`, `chore:`). - Library changes are usually paired with a build/bump in webarkit-testing — see that repo's "cross-repo PR pair" flow. - Don't modify the vendored `lib/SRC/**` / `include/AR/**` (old ARToolKit5) as part of From c02b9c054f8c5fe4b0f49c9e1457c225291627d8 Mon Sep 17 00:00:00 2001 From: Walter Perdan Date: Sun, 21 Jun 2026 10:58:57 +0200 Subject: [PATCH 6/7] docs(#51): add CONTRIBUTING.md Add contribution guidelines: branch-from-dev / PR-to-dev, signed commits, Conventional Commits (with examples), what may/may not change (WebARKit/ vs the vendored old-ARToolKit5 lib/SRC), the cross-repo PR-pair flow, and build/test (CMake static lib for WASM/Linux via opencv-em; gtest). README already links here. Co-Authored-By: Claude Opus 4.8 --- CONTRIBUTING.md | 67 +++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 67 insertions(+) create mode 100644 CONTRIBUTING.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..28cda1c --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,67 @@ +# Contributing to WebARKitLib + +Thanks for helping improve WebARKit! This is the C/C++ source of the tracker; most +changes are consumed by the [webarkit-testing](https://github.com/webarkit/webarkit-testing) +superproject as a submodule. + +## Workflow + +- **Branch from `dev`** and open your PR **against `dev`** (not `main`). +- Reference the related issue in the PR description. +- **Sign your commits** (`git commit -S …`). + +## Commit messages — Conventional Commits + +All commit messages **must** follow +[Conventional Commits](https://www.conventionalcommits.org/): + +``` +(): +``` + +Common types: `feat`, `fix`, `docs`, `refactor`, `test`, `chore`, `perf`. Examples: + +``` +feat(tracker): detect features on a downsampled frame +fix(#55): populate pose3d so getPoseMatrixCV() isn't zero +docs: document the pose pipeline +refactor(#50): remove dead computePose/invertPose +``` + +## What you may change + +- Active WebAR work lives under **`WebARKit/`** (the OCVT planar tracker). +- **Do not** modify the vendored **old ARToolKit5** sources under `lib/SRC/**` or + `include/AR/**` — those are upstream utilities used by + [jsartoolkitNFT](https://github.com/webarkit/jsartoolkitNFT) / + [ARnft](https://github.com/webarkit/ARnft) and are kept untouched. + +## Cross-repo changes (the PR pair) + +A change that affects the WASM build is consumed by webarkit-testing via the +submodule. Coordinate both repos: + +1. Branch from `dev` in **both** WebARKitLib and webarkit-testing. +2. Make the C++ change here; in webarkit-testing bump the submodule pointer and + rebuild (`npm run build-docker` → `build-es6`). +3. Open a **PR pair** (WebARKitLib → `dev`, webarkit-testing → `dev`); cross-link them. +4. After the WebARKitLib PR merges, re-point the submodule to the merged `dev` tip. + +## Building & tests + +- The library is normally built **from webarkit-testing** (WASM) — see its README. + `WebARKit/CMakeLists.txt` can also build it as a static lib for **WASM** or **native + Linux** (selected via `EMSCRIPTEN_COMP`), pulling OpenCV from + [webarkit/opencv-em](https://github.com/webarkit/opencv-em). +- **Unit tests** (GoogleTest) live in `tests/` and run in CI on every PR: + + ```bash + cmake -S tests -B tests/build && cmake --build tests/build && ctest --test-dir tests/build + ``` + + If you change a config constant or the version, update the matching assertions in + `tests/webarkit_test.cc`. + +## License + +By contributing, you agree that your contributions are licensed under **LGPL-3.0**. From d243408082a89942f030765576b7a4968db7e770 Mon Sep 17 00:00:00 2001 From: Walter Perdan Date: Sun, 21 Jun 2026 11:04:44 +0200 Subject: [PATCH 7/7] docs(#51): clarify PR-pair flow scope (WebARKit/ <-> webarkit-testing) Note that the cross-repo PR-pair flow applies to WebARKit/ folder changes consumed by the webarkit-testing repo as WASM; vendored lib/SRC + include/AR (old ARToolKit5) changes instead flow through jsartoolkitNFT and don't use it. Co-Authored-By: Claude Opus 4.8 --- CONTRIBUTING.md | 10 ++++++++-- 1 file changed, 8 insertions(+), 2 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 28cda1c..2f7d9cd 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -38,8 +38,14 @@ refactor(#50): remove dead computePose/invertPose ## Cross-repo changes (the PR pair) -A change that affects the WASM build is consumed by webarkit-testing via the -submodule. Coordinate both repos: +> **Applies to `WebARKit/` (this folder) ↔ the `webarkit-testing` repo.** This flow is +> for changes to the **`WebARKit/`** OCVT tracker, which the **webarkit-testing** +> superproject compiles to WASM. Changes to the vendored `lib/SRC/**` / `include/AR/**` +> (old ARToolKit5) do **not** use this flow — they reach the web through +> [jsartoolkitNFT](https://github.com/webarkit/jsartoolkitNFT), a different consumer. + +A change to `WebARKit/` that affects the WASM build is consumed by webarkit-testing via +the submodule. Coordinate both repos: 1. Branch from `dev` in **both** WebARKitLib and webarkit-testing. 2. Make the C++ change here; in webarkit-testing bump the submodule pointer and