ARToolKit5 Constants

Zero-dependency, auto-generated TypeScript definitions for ARToolKit5 constants.

This package provides a strict "Single Source of Truth" for the ARToolKit ecosystem. Instead of manually maintaining magic numbers in JavaScript, we extract values directly from the C++ source code using a WebAssembly extractor.

📦 Installation

npm install @ar-js-org/artoolkit5-constants

🚀 Usage

This library exports constants individually to support tree-shaking. You have two ways to use them depending on your preference.

1. Named Imports (Recommended)

Import only what you need. This allows bundlers (Webpack, Rollup, Vite) to remove unused code, keeping your application lightweight.

import {
    AR_PIXEL_FORMAT_RGBA,
    AR_MATRIX_CODE_DETECTION
} from '@ar-js-org/artoolkit5-constants';

// Example: Configuring ARController
const config = {
    pixelFormat: AR_PIXEL_FORMAT_RGBA,
    detectionMode: AR_MATRIX_CODE_DETECTION
};

if (config.pixelFormat === AR_PIXEL_FORMAT_RGBA) {
    console.log("Using RGBA format");
}

2. Namespace Import (Grouped Style)

If you prefer accessing constants via a global object (similar to how Enums work or legacy ARToolKit structure), use the import * as syntax:

import * as AR from '@ar-js-org//artoolkit5-constants';

// Now you can access everything under 'AR'
console.log(AR.AR_LOG_LEVEL_ERROR); // Output: 3
console.log(AR.AR_TEMPLATE_MATCHING_MONO); // Output: 1

function setLogLevel(level: number) {
    if (level === AR.AR_LOG_LEVEL_DEBUG) {
        // enable debug tools
    }
}

🛠 How it Works (For Contributors)

This project uses a unique build pipeline to ensure accuracy:

1. C++ Source: It links against the WebARKitLib submodule.
2. Embind Extraction: A minimal C++ program exposes macros and enums via WebAssembly.
3. Generation: A Node.js script loads the WASM, reads the values, and generates a static .ts file.

Build Requirements

• Emscripten SDK
• CMake
• Ninja
• Node.js (v18+)

Development Commands

# 1. Install dependencies
npm install

# 2. Initialize submodule (ARToolKit5 source)
git submodule update --init --recursive

# 3. Generate the TypeScript file (Requires Emscripten environment active)
npm run generate

# 4. Build the final package (Transpile to JS + .d.ts)
npm run build

The generated source file is located at src/generated/artoolkit_constants.ts.

License

This project is licensed under the GPLv3 License - see the LICENSE file for details.