How artoolkitx/jsartoolkit5 works
Project Type and Purpose
• This is an open-source JavaScript/WebAssembly library (JSARToolKit5) that ports the native ARToolKit5 computer-vision marker-tracking engine to the browser.
• Its core functionality: detect and track various AR markers (square, barcode, multi-marker, NFT) in images/video streams.
File-Structure Analysis
• Top-level build artifacts:
• build/artoolkit.debug.js, build/artoolkit_wasm.js, build/artoolkit_wasm.wasm
• Core source:
• emscripten/ (C/C++ source, embind glue code)
• JavaScript API wrappers:
• js/artoolkit.api.js, js/artoolkit.three.js (Three.js helper), js/artoolkit.worker.js
• Examples/demos:
• examples/ (HTML+JS demos showing raw API and Three.js integration, including WebWorker/NFT)
• Tools and build scripts:
• tools/makem.js (invoke Emscripten), tools/gen_embind_code.js, Gruntfile.js
• Configuration and docs:
• conf.json, doc/ (Markdown and HTML docs), README.md
• Tests:
• tests/ (automated tests using test harness HTML and JS)
Key Insights from README
• Core compiled output via Emscripten (ASM.js + WebAssembly).
• Supports two build targets: asm.js (artoolkit.min.js) and wasm (artoolkit_wasm.js + .wasm).
• Exposes an event-based JS API (ARController, ARCameraParam, getMarker events).
• Provides Three.js bridge for 3D scene integration.
• Build process uses Docker for reproducible Emscripten environment.
• Examples folder illustrates usage patterns (image sources, video streams, workers, NFT).
Components
a. ARToolKit Core Engine
• C/C++ code compiled by Emscripten → two runtime artifacts:
• ASM.js bundle (artoolkit.debug.js / artoolkit.min.js)
• WebAssembly module (artoolkit_wasm.js + .wasm)
b. JavaScript Binding Layers
• artoolkit.api.js: high-level JS classes (ARController, ARCameraParam)
• artoolkit.worker.js: Web Worker wrapper for off-thread processing
• artoolkit.three.js: Three.js helper API
c. Client Applications (Examples & Integrations)
• Raw API demos (examples/simple_image.html, simple_video.html)
• Worker/NFT demos (examples/nft_improved_worker)
• Three.js demos (examples/boilerplate_threejs.html, …)
d. Build & Tooling
• Node.js + npm (package.json)
• Dockerized Emscripten container (build environment)
• Build scripts: makem.js, gen_embind_code.js, Gruntfile.js
e. Supporting Assets
• Marker data files (examples/Data)
• Camera parameters (camera_para.dat)
• Test harness (tests/)
Relationships & Data Flows
• Developers run build scripts (makem.js under Docker) → produce JS/WASM artifacts in build/
• Browser loads either ASM.js or WASM bundle → instantiates the core engine
• Client code (HTML/JS) initializes ARCameraParam → ARController
• ARController captures or receives image/video frames → processes via core engine
• Core emits marker detection events → client event handlers update scene or UI
• Three.js helper subscribes to marker events → injects tracked objects into WebGL scene
Architectural Patterns & Principles
• Layered separation:
• Native core engine (performance-critical)
• JS binding layer (language interop)
• Client/demo code (application logic)
• Plugin-style marker loaders: support additional marker types via modular data files
• Event-driven design: decouple frame processing from application callbacks
• Worker pattern: optional Web Worker for off-main-thread processing (especially NFT)
• Polyglot build: supports both asm.js fallback and modern WebAssembly