new release 0.10.0

[kalwalt]

Release 0.10.0. Please merge with a merge commit (not squash), as for #73.

• feat(nft): move NFT tracking helpers from jsartoolkitNFT into WebARKitNFT (#75) #76 feat(nft): move NFT tracking helpers from jsartoolkitNFT into WebARKitNFT (Refactor: Move trackingMod, marker decompression, and tracking helpers from jsartoolkitNFT (ref #453) #75)
• fix(ar2): compute the random template index in double precision (#40) #77 fix(ar2): compute the random template index in double precision (Fix -Wimplicit-const-int-float-conversion warning in selectTemplate.c #40)
• chore: bump version to 0.10.0 #78 chore: bump version to 0.10.0
• fix(nft): address review findings before 0.10.0 #80 fix(nft): address review findings before 0.10.0
  • trackingInitMain checks the right pointer
  • .zft decompression capped at MARKER_DECOMPRESS_MAX_SIZE (128 MB), including limits below 4 MB and archives exactly at the limit
  • explicit #error if AR2_CAPABLE_ADAPTIVE_TEMPLATE is enabled
  • new webarkit_nft_limit_test, run in CI

The Qodo findings on this PR are answered in their threads: 2, 3 and 5 are fixed by #80; 1 (existing marker set overwritten on failure) and 4 (NUL bytes in .zft data) are not changed, with the reasons given there.

Tested with jsartoolkitNFT (webarkit/jsartoolkitNFT#687): full rebuild, vitest and node tests, and all examples, including the threaded ones.

After merging, tag 0.10.0 on master and publish the release notes.

🤖 Generated with Claude Code

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

PR Summary by Qodo

Release 0.10.0 with standalone NFT helpers and AR2 precision fix

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

AI Description

• Add an independently buildable NFT library without requiring OpenCV.
• Fix AR2 random template selection and expand native NFT test coverage.
• Document NFT build options and update the reported version to 0.10.0.

Diagram

graph TD
  Config["CMake options"] --> NFT["WebARKitNFT"] --> ARTK["ARToolKit sources"]
  Config --> Optical["Optical library"]
  NFT --> Deps["JPEG and zlib"]
  NFT --> Worker["Optional KPM worker"]
  Tests["Test suites"] --> NFT
  Tests --> Optical

Loading

High-Level Assessment

The following are alternative approaches to this PR:

1. Keep NFT helpers in jsartoolkitNFT

• ➕ Avoids maintaining a local copy of the helper sources.
• ➖ Leaves WebARKitNFT builds dependent on another repository's source layout and integration.

Recommendation: Keep the standalone WebARKitNFT target: it establishes a buildable, OpenCV-independent home for the helpers while preserving the existing optical target's default behavior. The external-source alternative reduces duplication but does not provide the same self-contained build.

Files changed (19) +2163 / -10

Enhancement (9) +1931 / -0

CMakeLists.txtDefine the standalone WebARKitNFT static library +94/-0

Define the standalone WebARKitNFT static library

• Compiles NFT helpers with their ARToolKit dependencies, optionally includes the KPM worker, and configures native or Emscripten compression and threading dependencies.

WebARKit/WebARKitTrackers/WebARKitNFT/CMakeLists.txt

NFTMarkerState.hAdd per-marker NFT tracking state +22/-0

Add per-marker NFT tracking state

• Defines C++ state for a marker's tracking status, pose, error, and pose-filter lifecycle.

WebARKit/WebARKitTrackers/WebARKitNFT/include/WebARKitTrackers/WebARKitNFT/NFTMarkerState.h

markerDecompress.hExpose marker archive decompression declarations +26/-0

Expose marker archive decompression declarations

• Declares the C-compatible .zft extraction API and adds an include guard.

WebARKit/WebARKitTrackers/WebARKitNFT/include/WebARKitTrackers/WebARKitNFT/markerDecompress.h

trackingMod.hExpose modified AR2 tracking APIs +83/-0

Expose modified AR2 tracking APIs

• Declares single-threaded AR2 handle and tracking functions, including a distinct name for the public 2D tracking helper.

WebARKit/WebARKitTrackers/WebARKitNFT/include/WebARKitTrackers/WebARKitNFT/trackingMod.h

trackingSub.hExpose threaded KPM detection APIs +95/-0

Expose threaded KPM detection APIs

• Declares worker lifecycle methods, multi-page results, and a legacy-compatible best-page result method.

WebARKit/WebARKitTrackers/WebARKitNFT/include/WebARKitTrackers/WebARKitNFT/trackingSub.h

markerDecompress.cDecompress .zft archives into marker files +231/-0

Decompress .zft archives into marker files

• Inflates zlib archives with a growing buffer and writes their iset, fset, and fset3 fields in binary mode. Reports malformed input and cleans up files after partial write failures.

WebARKit/WebARKitTrackers/WebARKitNFT/markerDecompress.c

trackingMod.cProvide single-threaded AR2 tracking +913/-0

Provide single-threaded AR2 tracking

• Adds modified AR2 handle management, feature matching, and pose estimation without AR2 tracking worker threads.

WebARKit/WebARKitTrackers/WebARKitNFT/trackingMod.c

trackingMod2d.cProvide renamed 2D template tracking helper +216/-0

Provide renamed 2D template tracking helper

• Adds the 2D feature-template matching routine under ar2Tracking2dSubMod, avoiding a symbol conflict with AR2's implementation.

WebARKit/WebARKitTrackers/WebARKitNFT/trackingMod2d.c

trackingSub.cImplement threaded multi-page KPM detection +251/-0

Implement threaded multi-page KPM detection

• Runs marker searches on a worker thread, collects matched pages, and retains best-match selection for single-page callers. Prevents another scan until the previous results have been collected.

WebARKit/WebARKitTrackers/WebARKitNFT/trackingSub.c

Bug fix (3) +4 / -1

selectTemplate.cUse double precision for random template selection +1/-1

Use double precision for random template selection

• Computes the random candidate index in double precision to avoid single-precision rounding at RAND_MAX.

lib/SRC/AR2/selectTemplate.c

visual_database_facade.cppInclude unordered_map explicitly +1/-0

Include unordered_map explicitly

• Adds the standard-library header required by the KPM source for native compilation.

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

hamming.hInclude limits explicitly +2/-0

Include limits explicitly

• Adds the standard-library header required by the Hamming-distance code for native compilation.

lib/SRC/KPM/FreakMatcher/math/hamming.h

Documentation (1) +25 / -1

README.mdDocument NFT APIs and build options +25/-1

Document NFT APIs and build options

• Describes the moved helpers, the OpenCV-independent NFT target, its CMake switches, an Emscripten build command, and the new test suite.

README.md

Other (6) +203 / -8

test.ymlRun NFT tests in native CI +3/-3

Run NFT tests in native CI

• Installs zlib development headers alongside libjpeg and runs the new NFT test executable after the existing optical tests.

.github/workflows/test.yml

CMakeLists.txtMake optical and NFT targets independently selectable +11/-0

Make optical and NFT targets independently selectable

• Adds switches to include the NFT subdirectory and to skip the existing OpenCV-based optical target when it is not needed.

WebARKit/CMakeLists.txt

WebARKitConfig.cppReport version 0.10.0 +2/-2

Report version 0.10.0

• Changes the optical library's version string and minor version constant from 0.9.0 to 0.10.0.

WebARKit/WebARKitTrackers/WebARKitOpticalTracking/WebARKitConfig.cpp

CMakeLists.txtBuild and register NFT GoogleTests +9/-1

Build and register NFT GoogleTests

• Enables the NFT and threaded targets for the test build, links a new NFT executable, and registers it with GoogleTest discovery.

tests/CMakeLists.txt

webarkit_nft_test.ccCover decompression and NFT helper lifecycles +176/-0

Cover decompression and NFT helper lifecycles

• Tests .zft extraction, malformed and large archives, binary preservation, default marker state, AR2 handle cleanup, and threaded worker behavior.

tests/webarkit_nft_test.cc

webarkit_test.ccExpect the 0.10.0 version +2/-2

Expect the 0.10.0 version

• Updates optical configuration and manager version assertions to match the release.

tests/webarkit_test.cc

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

Code Review by Qodo

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

1. A failed extraction erases existing markers 🐞 Bug ☼ Reliability

Description

saveMarkerFile opens each destination with wb, and extractDataAndSave removes earlier outputs
if a later write fails. When extraction replaces an existing marker set and .fset or .fset3
cannot be written, the previous files are not restored.

Code

WebARKit/WebARKitTrackers/WebARKitNFT/markerDecompress.c[R189-192]

+    if (saveMarkerFile(name, ".iset", iset, isetSize) != 0) return -1;
+    if (saveMarkerFile(name, ".fset", fset, fsetSize) != 0) {
+        removeMarkerFile(name, ".iset");
+        return -1;

Evidence

wb truncates an existing destination. The later failure branches remove files already written, and
the failing write can remove its destination too; none of those branches restores an overwritten
file.

WebARKit/WebARKitTrackers/WebARKitNFT/markerDecompress.c[116-136]
WebARKit/WebARKitTrackers/WebARKitNFT/markerDecompress.c[189-199]

Agent prompt

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

## Issue description
Extracting over an existing marker set truncates files before all three replacements succeed. Failure cleanup then deletes outputs without restoring the originals.
## Fix Focus Areas
- WebARKit/WebARKitTrackers/WebARKitNFT/markerDecompress.c[115-145]
- WebARKit/WebARKitTrackers/WebARKitNFT/markerDecompress.c[189-199]
## Recommended Fix
Write all three files to temporary paths first, and replace existing destinations only after every write and close succeeds. Preserve or restore the prior set if replacement fails.

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

---

2. A compressed marker can exhaust memory ✓ Resolved

Description

inflateAll doubles its output allocation until the entire stream has expanded, without a
decompressed-size limit. A small .zft with a large expansion ratio reaches repeated allocations
before its contents can be checked or rejected.

Code

WebARKit/WebARKitTrackers/WebARKitNFT/markerDecompress.c[R39-46]

+        if (strm.total_out == cap) {
+            char *bigger = realloc(out, cap * 2 + 1);
+            if (bigger == NULL) {
+                ret = Z_MEM_ERROR;
+                break;
+            }
+            out = bigger;
+            cap *= 2;

Evidence

The output buffer starts at four megabytes and doubles whenever full. Parsing occurs only after
inflateAll has expanded the complete stream.

WebARKit/WebARKitTrackers/WebARKitNFT/markerDecompress.c[22-52]
WebARKit/WebARKitTrackers/WebARKitNFT/markerDecompress.c[105-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
Inflating a `.zft` has no output-size bound, allowing a high-expansion stream to consume available memory before parsing begins.
## Fix Focus Areas
- WebARKit/WebARKitTrackers/WebARKitNFT/markerDecompress.c[22-62]
- WebARKit/WebARKitTrackers/WebARKitNFT/markerDecompress.c[105-109]
## Recommended Fix
Set an explicit maximum expanded archive size, reject growth beyond it before reallocating, and check capacity arithmetic for overflow. Add a test for an archive exceeding the limit.

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

---

3. Adaptive-template builds fail 🐞 Bug ≡ Correctness

Description

ar2TrackingMod calls ar2Tracking2dSubMod without the extra template argument required by its
adaptive-template definition. When AR2_CAPABLE_ADAPTIVE_TEMPLATE is enabled, that definition also
redeclares templ2 locally, so the new helper cannot compile in that configuration.

Code

WebARKit/WebARKitTrackers/WebARKitNFT/trackingMod2d.c[R59-62]

+#if AR2_CAPABLE_ADAPTIVE_TEMPLATE
+int ar2Tracking2dSubMod ( AR2HandleT *handle, AR2SurfaceSetT *surfaceSet, AR2TemplateCandidateT *candidate,
+                              ARUint8 *dataPtr, ARUint8 *mfImage, AR2TemplateT **templ,
+                              AR2Template2T **templ2, AR2Tracking2DResultT *result )

Evidence

The adaptive branch adds a templ2 parameter and then declares a local variable of the same name.
The call supplies only the non-adaptive arguments; the current configuration disables the branch,
which is why the default build does not reveal it.

WebARKit/WebARKitTrackers/WebARKitNFT/trackingMod2d.c[49-71]
WebARKit/WebARKitTrackers/WebARKitNFT/trackingMod.c[216-220]
include/AR2/config.h[81-81]

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 adaptive-template branch defines a different helper signature from its call and redeclares a parameter name. Enabling that compile-time configuration fails to build the NFT helper.
## Fix Focus Areas
- WebARKit/WebARKitTrackers/WebARKitNFT/trackingMod2d.c[49-71]
- WebARKit/WebARKitTrackers/WebARKitNFT/trackingMod.c[216-221]
- WebARKit/WebARKitTrackers/WebARKitNFT/include/WebARKitTrackers/WebARKitNFT/trackingMod.h[67-69]
## Recommended Fix
Make the adaptive declaration, definition, public header, and call agree on the `templ2` argument. Remove the conflicting local declaration and compile-test both macro settings.

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

---

4. Marker data containing zero bytes fails to unpack 🐞 Bug ≡ Correctness

Description

extractDataAndSave uses strncmp/strstr to find field boundaries in inflated data, while
decompressMarkers discards the decompressed length returned in outLen. When a .zft contains
raw binary .iset or .fset data with a NUL byte, the parser cannot find later delimiters such as
","fset":" and returns -1 instead of writing the three files.

Code

WebARKit/WebARKitTrackers/WebARKitNFT/markerDecompress.c[R105-109]

+    c = inflateAll(in, (size_t)filesize, &outLen);
+    free(in);
+    if (c == NULL) return -1;
+
+    int result = extractDataAndSave(c, outTemp);

Evidence

ar2WriteImageSet writes imageSet->num as a raw int with fwrite, so a real .iset can begin
with bytes such as 01 00 00 00; the .fset writer also emits binary values. The extractor obtains
outLen but passes only the buffer to extractDataAndSave, whose strstr calls treat the first
0x00 as the end of the data and cannot find subsequent fields. The KeepsBinaryBytesUnchanged
test uses bytes without zeros, so it does not expose this failure.

lib/SRC/AR2/imageSet.c[211-211]
WebARKit/WebARKitTrackers/WebARKitNFT/markerDecompress.c[147-178]
WebARKit/WebARKitTrackers/WebARKitNFT/markerDecompress.c[105-110]
WebARKit/WebARKitTrackers/WebARKitNFT/markerDecompress.c[147-183]
lib/SRC/AR2/featureSet.c[129-149]
lib/SRC/AR2/imageSet.c[207-226]

Agent prompt

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

## Issue description
`extractDataAndSave` searches inflated binary marker data as a NUL-terminated string, so embedded zero bytes hide later field delimiters. `decompressMarkers` obtains the decompressed length in `outLen` but does not pass it to the parser.
## Fix Focus Areas
- WebARKit/WebARKitTrackers/WebARKitNFT/markerDecompress.c[105-110]
- WebARKit/WebARKitTrackers/WebARKitNFT/markerDecompress.c[147-200]
- WebARKit/WebARKitTrackers/WebARKitNFT/include/WebARKitTrackers/WebARKitNFT/markerDecompress.h[20-20]
## Recommended Fix
Pass `outLen` to a length-aware parser, such as a static `extractDataAndSaveN(const char *str, size_t len, const char *name)`. Use portable, length-bounded searches to find each key and the end marker (the last `"}`), rather than NUL-terminated string searches. Keep the public `extractDataAndSave` as a wrapper that passes `strlen(str)`, and add a round-trip test with an embedded NUL byte in the `.iset` payload.

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

---

5. Worker thread skips its null check on the handle ✓ Resolved

Description

In trackingInitMain, the second guard re-checks threadHandle instead of the trackingInitHandle
it just got from threadGetArg, so this check can never be true. If the thread arg is NULL, the
next line trackingInitHandle->kpmHandle dereferences a null pointer on the worker thread instead
of logging and exiting.

Code

WebARKit/WebARKitTrackers/WebARKitNFT/trackingSub.c[R212-216]

+    trackingInitHandle = (TrackingInitHandle *)threadGetArg(threadHandle);
+    if (!threadHandle) {
+        ARLOGe("Error starting tracking thread: empty trackingInitHandle.\n");
+        return (NULL);
+    }

Evidence

Line 213 tests !threadHandle, which was already checked at line 208. Line 217 then dereferences
trackingInitHandle without any check.

WebARKit/WebARKitTrackers/WebARKitNFT/trackingSub.c[208-218]

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 null check after `threadGetArg` tests the wrong variable.
## Fix Focus Areas
- WebARKit/WebARKitTrackers/WebARKitNFT/trackingSub.c[212-216]
## Recommended Fix
Change `if (!threadHandle)` to `if (!trackingInitHandle)`.

ⓘ 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 route each severity your way: inline, summary, both, or drop

More tips ↗ | Customize Qodo ↗ | Qodo docs ↗