# artoolkitx/jsartoolkit5 architecture

> Architecture diagram of the GitHub repository artoolkitx/jsartoolkit5, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-06-06). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/artoolkitx/jsartoolkit5
- Repository: https://github.com/artoolkitx/jsartoolkit5

## Overview

##### 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

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Build & Tooling Layer
    subgraph "Build & Tooling" 
        direction TB
        Tools_Node(["Node.js & npm"]):::grey
        Docker(["Dockerized Emscripten"]):::grey
        Makem["makem.js"]:::grey
        GenBind["gen_embind_code.js"]:::grey
        Grunt["Gruntfile.js"]:::grey
        Tools_Node -->|uses| Docker
        Docker -->|runs| Makem
        Docker -->|runs| GenBind
        Docker -->|runs| Grunt
    end

    %% Build Artifacts
    subgraph "Build Artifacts" 
        direction TB
        ASMJS["ASM.js Bundle\n(artoolkit.debug.js)"]:::blue
        WASM_Module(("WebAssembly\n(artoolkit_wasm.wasm)")):::blue
        WASM_JS["WASM Loader\n(artoolkit_wasm.js)"]:::blue
        ASMJS & WASM_JS & WASM_Module
    end

    Tools_Node -->|"builds"| ASMJS
    Tools_Node -->|"builds"| WASM_JS
    Tools_Node -->|"builds"| WASM_Module

    %% Core Source
    subgraph "Core Engine Source" 
        direction TB
        ARToolKitJS["ARToolKitJS.cpp"]:::blue
        ARBindEM["ARBindEM.cpp"]:::blue
        TrackModC["trackingMod.c"]:::blue
        TrackMod2d["trackingMod2d.c"]:::blue
        TrackModH["trackingMod.h"]:::blue
    end

    ARToolKitJS & ARBindEM & TrackModC & TrackMod2d & TrackModH -->|compiled by Emscripten| ASMJS
    ARToolKitJS & ARBindEM & TrackModC & TrackMod2d & TrackModH -->|compiled by Emscripten| WASM_JS
    ARToolKitJS & ARBindEM & TrackModC & TrackMod2d & TrackModH -->|compiled by Emscripten| WASM_Module

    %% JS API Layers
    subgraph "JavaScript Binding Layers"
        direction TB
        API["artoolkit.api.js"]:::green
        API_DT["artoolkit.api.d.ts"]:::green
        Worker["artoolkit.worker.js"]:::green
        ThreeJS["artoolkit.three.js"]:::green
        ThreeJS_DT["artoolkit.three.d.ts"]:::green
    end

    ASMJS -->|"loaded by"| API
    WASM_JS -->|"loaded by"| API
    API -->|"spawns"| Worker
    API -->|"uses"| ThreeJS

    %% Client Applications
    subgraph "Client & Examples"
        direction TB
        subgraph "Raw API Demos"
            SI_HTML["simple_image.html"]:::orange
            SI_WASM["simple_image_wasm.html"]:::orange
            SV_HTML["simple_video.html"]:::orange
            SV_WASM["simple_video_wasm.html"]:::orange
            Intro["intro_example.html"]:::orange
            IndexExamples["index.html"]:::orange
        end
        subgraph "Three.js Demos"
            Boiler["boilerplate_threejs.html"]:::orange
            Barcode3["barcode_threejs.html"]:::orange
            Pattern3["pattern_threejs.html"]:::orange
            MultiBarcode["multimarker_barcode_threejs.html"]:::orange
            MultiPattern["multimarker_pattern_threejs.html"]:::orange
            Scratch3["threejs_from_scratch.html"]:::orange
            NFT3["nft_threejs_wasm.html"]:::orange
        end
        subgraph "Worker & NFT Demos"
            NFT_Worker_Index["nft_improved_worker/index.html"]:::orange
            NFT_Worker_Main["nft_improved_worker/main.html"]:::orange
            NFT_Worker_JS["nft_improved_worker/main.js"]:::orange
            NFT_Worker_Worker["nft_improved_worker/main_worker.js"]:::orange
            ThreeJS_Worker["nft_improved_worker/threejs_worker.js"]:::orange
            ThreeJS_WASM_Worker["nft_improved_worker/threejs_wasm_worker.js"]:::orange
            WASM_Worker_JS["nft_improved_worker/wasm_worker/artoolkit.wasm_worker.js"]:::orange
        end
    end

    API -->|"provides API to"| SI_HTML
    API -->|"provides API to"| SI_WASM
    API -->|"provides API to"| SV_HTML
    API -->|"provides API to"| SV_WASM
    API -->|"provides API to"| Intro
    API -->|"provides API to"| IndexExamples
    ThreeJS -->|"provides helper to"| Boiler
    ThreeJS -->|"provides helper to"| Barcode3
    ThreeJS -->|"provides helper to"| Pattern3
    ThreeJS -->|"provides helper to"| MultiBarcode
    ThreeJS -->|"provides helper to"| MultiPattern
    ThreeJS -->|"provides helper to"| Scratch3
    ThreeJS -->|"provides helper to"| NFT3
    Worker -->|"offloads processing for"| NFT_Worker_Index
    Worker -->|"offloads processing for"| NFT_Worker_Main
    Worker -->|"offloads processing for"| NFT_Worker_JS
    Worker -->|"offloads processing for"| NFT_Worker_Worker
    Worker -->|"offloads processing for"| ThreeJS_Worker
    Worker -->|"offloads processing for"| ThreeJS_WASM_Worker
    Worker -->|"offloads processing for"| WASM_Worker_JS

    %% External Assets & Data
    subgraph "External Assets & Data"
        direction TB
        CamPara1["camera_para.dat"]:::yellow
        CamPara2["camera_para-iPhone 5 rear 640x480 1.0m.dat"]:::yellow
        PattHiro["patt.hiro"]:::yellow
        PattKanji["patt.kanji"]:::yellow
        ModelFlamingo["Flamingo.glb"]:::yellow
        NFT_Fset["pinball.fset"]:::yellow
        TestCamPara["tests/camera_para.dat"]:::yellow
        TestPatt["tests/patt.hiro"]:::yellow
    end

    SI_HTML & SV_HTML & Intro -->|"loads"| CamPara1
    SI_HTML & SV_HTML & Intro -->|"loads"| PattHiro
    Boiler & Barcode3 & Pattern3 -->|"loads"| CamPara1
    Boiler & Barcode3 & Pattern3 -->|"loads"| PattHiro
    NFT3 & NFT_Worker_Index & NFT_Worker_Main -->|"loads NFT data"| NFT_Fset
    Scratch3 -->|"loads model"| ModelFlamingo

    %% Click Events
    click ARToolKitJS "https://github.com/artoolkitx/jsartoolkit5/blob/master/emscripten/ARToolKitJS.cpp"
    click ARBindEM "https://github.com/artoolkitx/jsartoolkit5/blob/master/emscripten/ARBindEM.cpp"
    click TrackModC "https://github.com/artoolkitx/jsartoolkit5/blob/master/emscripten/trackingMod.c"
    click TrackMod2d "https://github.com/artoolkitx/jsartoolkit5/blob/master/emscripten/trackingMod2d.c"
    click TrackModH "https://github.com/artoolkitx/jsartoolkit5/blob/master/emscripten/trackingMod.h"
    click ASMJS "https://github.com/artoolkitx/jsartoolkit5/blob/master/build/artoolkit.debug.js"
    click WASM_JS "https://github.com/artoolkitx/jsartoolkit5/blob/master/build/artoolkit_wasm.js"
    click WASM_Module "https://github.com/artoolkitx/jsartoolkit5/blob/master/build/artoolkit_wasm.wasm"
    click API "https://github.com/artoolkitx/jsartoolkit5/blob/master/js/artoolkit.api.js"
    click API_DT "https://github.com/artoolkitx/jsartoolkit5/blob/master/js/artoolkit.api.d.ts"
    click Worker "https://github.com/artoolkitx/jsartoolkit5/blob/master/js/artoolkit.worker.js"
    click ThreeJS "https://github.com/artoolkitx/jsartoolkit5/blob/master/js/artoolkit.three.js"
    click ThreeJS_DT "https://github.com/artoolkitx/jsartoolkit5/blob/master/js/artoolkit.three.d.ts"
    click SI_HTML "https://github.com/artoolkitx/jsartoolkit5/blob/master/examples/simple_image.html"
    click SI_WASM "https://github.com/artoolkitx/jsartoolkit5/blob/master/examples/simple_image_wasm.html"
    click SV_HTML "https://github.com/artoolkitx/jsartoolkit5/blob/master/examples/simple_video.html"
    click SV_WASM "https://github.com/artoolkitx/jsartoolkit5/blob/master/examples/simple_video_wasm.html"
    click Intro "https://github.com/artoolkitx/jsartoolkit5/blob/master/examples/intro_example.html"
    click IndexExamples "https://github.com/artoolkitx/jsartoolkit5/blob/master/examples/index.html"
    click Boiler "https://github.com/artoolkitx/jsartoolkit5/blob/master/examples/boilerplate_threejs.html"
    click Barcode3 "https://github.com/artoolkitx/jsartoolkit5/blob/master/examples/barcode_threejs.html"
    click Pattern3 "https://github.com/artoolkitx/jsartoolkit5/blob/master/examples/pattern_threejs.html"
    click MultiBarcode "https://github.com/artoolkitx/jsartoolkit5/blob/master/examples/multimarker_barcode_threejs.html"
    click MultiPattern "https://github.com/artoolkitx/jsartoolkit5/blob/master/examples/multimarker_pattern_threejs.html"
    click Scratch3 "https://github.com/artoolkitx/jsartoolkit5/blob/master/examples/threejs_from_scratch.html"
    click NFT3 "https://github.com/artoolkitx/jsartoolkit5/blob/master/examples/nft_threejs_wasm.html"
    click NFT_Worker_Index "https://github.com/artoolkitx/jsartoolkit5/blob/master/examples/nft_improved_worker/index.html"
    click NFT_Worker_Main "https://github.com/artoolkitx/jsartoolkit5/blob/master/examples/nft_improved_worker/main.html"
    click NFT_Worker_JS "https://github.com/artoolkitx/jsartoolkit5/blob/master/examples/nft_improved_worker/main.js"
    click NFT_Worker_Worker "https://github.com/artoolkitx/jsartoolkit5/blob/master/examples/nft_improved_worker/main_worker.js"
    click ThreeJS_Worker "https://github.com/artoolkitx/jsartoolkit5/blob/master/examples/nft_improved_worker/threejs_worker.js"
    click ThreeJS_WASM_Worker "https://github.com/artoolkitx/jsartoolkit5/blob/master/examples/nft_improved_worker/threejs_wasm_worker.js"
    click WASM_Worker_JS "https://github.com/artoolkitx/jsartoolkit5/blob/master/examples/nft_improved_worker/wasm_worker/artoolkit.wasm_worker.js"

    %% Styles
    classDef grey fill:#dddddd,stroke:#888888,stroke-width:1px
    classDef blue fill:#cce5ff,stroke:#337ab7,stroke-width:1px
    classDef green fill:#dff0d8,stroke:#3c763d,stroke-width:1px
    classDef orange fill:#fcf8e3,stroke:#8a6d3b,stroke-width:1px
    classDef yellow fill:#fff2cc,stroke:#bfa900,stroke-width:1px
```
