webarkitlib-rs 0.1.5

A high-performance, memory-safe Rust port of WebARKitLib (ARToolKit) for native and WASM.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149

# WebARKitLib-rs 🦀

[![CI](https://github.com/webarkit/WebARKitLib-rs/actions/workflows/ci.yml/badge.svg)](https://github.com/webarkit/WebARKitLib-rs/actions/workflows/ci.yml)
[![Crates.io](https://img.shields.io/crates/v/webarkitlib-rs.svg)](https://crates.io/crates/webarkitlib-rs)
[![npm](https://img.shields.io/npm/v/@webarkit/webarkitlib-wasm.svg)](https://www.npmjs.com/package/@webarkit/webarkitlib-wasm)
[![GitHub stars](https://img.shields.io/github/stars/webarkit/WebARKitLib-rs.svg?style=social)](https://github.com/webarkit/WebARKitLib-rs/stargazers)

**WebARKitLib-rs** is a high-performance, memory-safe Rust port of the [WebARKitLib](https://github.com/webarkit/WebARKitLib) (originally C/C++). 

This project aims to provide a pure-Rust implementation of the core ARToolKit algorithms, targeting both **native** systems and **WebAssembly (WASM)** for high-performance augmented reality in the browser.

> [!NOTE]
> This project is currently a **Work in Progress**. While the core marker detection and pose estimation are functional, we are continuously optimizing and expanding the feature set.

## 🌟 Key Features

- **Pure Rust**: Built for safety, speed, and modern concurrency. ([crates.io](https://crates.io/crates/webarkitlib-rs))
- **Dual WASM Strategy**: Automated release of both **Standard** and **SIMD** binaries to maximize performance and compatibility.
- **SIMD-Accelerated Pattern Matching**: Uses `i16` fixed-point arithmetic and WASM `i32x4_dot_i16x8` instructions for ultra-fast correlation matching.
- **Barcode Marker Support**: Robust decoding for square matrix markers (3x3 to 6x6) with ECC.
- **WASM Ready**: High-performance tracking in the browser via WebAssembly. ([@webarkit/webarkitlib-wasm](https://www.npmjs.com/package/@webarkit/webarkitlib-wasm))
- **Side-Effect Free**: Pure mathematical engine, easy to test and integrate.
- **CI-Integrated Benchmarking**: Performance parity with original C implementation.

## ⚡ Performance & Accuracy

- **SIMD-Accelerated Pattern Matching**: Uses `i16` fixed-point arithmetic for the core correlation loops, leveraging WASM `i32x4_dot_i16x8` instructions for significant speedups.
- **Numerical Parity**: Our SIMD and Scalar paths are calibrated to produce bit-identical results (including rounding logic in grayscale and thresholding), ensuring deterministic behavior across all devices.
- **Sub-millisecond Tracking**: Core detection loop is optimized for sub-millisecond execution on standard ARM/x86 hardware.

## 🚀 Getting Started

### Native Rust Example

To see the marker detection in action on your local machine, run the provided simple example:

```bash
cargo run --example simple
```

This example loads a camera parameter file, a marker (pattern or barcode), and a sample image, performing detection and outputting the 3D pose extrinsics.

#### Barcode Detection Example

A unified, parameterized barcode example is available for testing all supported matrix code types:

```bash
# Default: 3x3 matrix code type, auto-sweeps threshold 60–180
cargo run --example barcode

# Specify a matrix code type (e.g. 4x4) and supply the matching marker image
cargo run --example barcode -- -m 4x4 -i crates/core/examples/Data/marker_07_4x4.jpg

# Use a fixed threshold instead of auto-sweeping
cargo run --example barcode -- -m 3x3 -t 100

# Full example: type, threshold, and custom image path
cargo run --example barcode -- -m 5x5 -t 120 -i path/to/marker.jpg
```

**Options:**

| Flag | Long form | Description | Default |
|------|-----------|-------------|---------|
| `-m` | `--matrix-code-type` | Matrix code type (`3x3`, `3x3parity65`, `3x3hamming63`, `4x4`, `4x4bch1393`, `4x4bch1355`, `5x5`, `5x5bch22125`, `5x5bch2277`, `6x6`) | `3x3` |
| `-t` | `--threshold` | Fixed labeling threshold (0–255). When omitted, sweeps 60–180 in steps of 20 | *(auto-sweep)* |
| `-i` | `--image` | Path to the input image | bundled 3x3 marker image |

### WebAssembly (WASM) Demo

The WASM port allows you to run the AR engine directly in most modern browsers.

1. **Build the modules**:
   Use the npm script to generate both Standard and SIMD bundles (works on all platforms):
   ```bash
   npm run build:wasm
   ```
   > **Alternatively**, download the pre-built `wasm-package` artifact from the latest [CI run](https://github.com/webarkit/WebARKitLib-rs/actions) and extract its contents into `crates/wasm/pkg/`.

2. **Run the demo**:
   The `www` folder contains two web demos. Serve it with any local HTTP server:
   ```bash
   cd crates/wasm/www
   # Serve using any local HTTP server, e.g.:
   npx serve .
   ```
   - **`simple.html`** – static image demo with engine selector and threshold visualization.
   - **`simple_video_marker_example.html`** – live webcam demo with engine selector, marker type (pattern/barcode) selector, and threshold slider.

## 📊 Benchmarking

We maintain a strict performance comparison with the original C library to ensure our Rust port remains competitive. 

Detailed SIMD performance results and reproduction steps can be found in the [BENCHMARKS.md](crates/core/benches/BENCHMARKS.md) file.

### Running the Comparison

1.  **Bootstrap the C library**:
    ```bash
    cd benchmarks/c_benchmark
    python ../bootstrap.py --bootstrap-file libraries.json
    ```

2.  **Execute the Suite**:
    ```bash
    # Rust Benchmark
    cargo bench -p webarkitlib-rs --bench marker_bench

    # C Benchmark (Manual build required once)
    cd benchmarks/c_benchmark/build
    cmake --build . --config Release
    ./c_benchmark ../../data/camera_para.dat ../../data/patt.hiro ../../data/hiro.raw 429 317
    ```

### Tracking Performance

We use `criterion` to track performance over time. You can save specific snapshots as "baselines":

```bash
# Save a milestone baseline
cargo bench -- --save-baseline milestone-20260307
```

## 🏗️ Project Structure

- `crates/core`: The core AR engine (pure Rust).
- `crates/wasm`: WASM bindings, dual-build scripts, and diagnostic web demo.
- `benchmarks`: C vs Rust performance comparison suite.
- `examples`: Usage demonstrations for patterns and barcodes.
- [`ARCHITECTURE.md`](ARCHITECTURE.md): Detailed technical overview of the library's design and SIMD optimizations.

## 🗺️ Roadmap

### 🎯 Near-term Goals (v1.0.0+)
- **Enhanced Documentation**: Expand API reference, integration walkthroughs for JS/TS, and provide detailed usage examples.
- **WASM Memory Management**: Improve resource cleanup when switching engines or markers in long-running browser sessions.

### 🔭 Long-term Vision
- **Multi-Marker Support**: Port `arMulti` logic to enable tracking of multiple markers simultaneously.
- **KPM/NFT (Natural Feature Tracking)**: Implement robust tracking of arbitrary images and surfaces.
- **Advanced Video Abstraction**: Develop a cross-platform video handling layer to simplify integration with various input sources.

## 📜 Credits

This project is a port of the excellent [WebARKitLib](https://github.com/webarkit/WebARKitLib) project. Special thanks to the original ARToolKit contributors.

## 📄 License

This project is licensed under the LGPLv3 License - see the [LICENSE](LICENSE) file for details.