{"_id":"@ar-js-org/artoolkit5-ts","_rev":"4-be6d7070cbbd5aa203f81fa6036613de","name":"@ar-js-org/artoolkit5-ts","dist-tags":{"latest":"0.2.2"},"versions":{"0.1.0":{"name":"@ar-js-org/artoolkit5-ts","version":"0.1.0","keywords":["artoolkit","artoolkit5","augmented-reality","ar","webar","marker-tracking","barcode-marker","webassembly","wasm","typescript","ar.js","webarkit"],"author":{"url":"https://github.com/kalwalt","name":"Walter Perdan"},"license":"MIT","_id":"@ar-js-org/artoolkit5-ts@0.1.0","maintainers":[{"name":"kalwalt","email":"info@kalwaltart.it"},{"name":"nickw1","email":"nickw4426@gmail.com"},{"name":"nicolocarpignoli","email":"nicolocarpignoli@gmail.com"}],"homepage":"https://github.com/AR-js-org/artoolkit5-ts#readme","bugs":{"url":"https://github.com/AR-js-org/artoolkit5-ts/issues"},"dist":{"shasum":"fbd4f397500123ea64ba57f009236297bab90831","tarball":"https://registry.npmjs.org/@ar-js-org/artoolkit5-ts/-/artoolkit5-ts-0.1.0.tgz","fileCount":13,"integrity":"sha512-KntUdsNqAAo0afNiumMr2F4tvzvZrkQahqYRUPJEjfK+1jpDeexJNVoro3y4Nb3qjIk0cK419OenClz0vvFx4Q==","signatures":[{"sig":"MEQCIDO7yM+UxcfvilCpMkwYxV87iORvCwv6i1kbzBIla32DAiB+8ASNKwNb3QMsPxrX1o1lOKF2sDoSeIGYy7SjW3zDIA==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@ar-js-org%2fartoolkit5-ts@0.1.0","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"unpackedSize":38002},"main":"./dist/artoolkit5-ts.umd.cjs","type":"module","types":"./dist/index.d.ts","module":"./dist/artoolkit5-ts.js","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/artoolkit5-ts.js","require":"./dist/artoolkit5-ts.umd.cjs"}},"gitHead":"be283a8deaf212b5304f552a63d1429801026a29","private":false,"scripts":{"dev":"vite","test":"vitest run","build":"vite build && tsc -p tsconfig.build.json","preview":"vite preview","typecheck":"tsc --noEmit -p tsconfig.json","test:watch":"vitest","release-notes":"node scripts/release-notes.mjs"},"_npmUser":{"name":"kalwalt","email":"info@kalwaltart.it"},"repository":{"url":"git+https://github.com/AR-js-org/artoolkit5-ts.git","type":"git"},"_npmVersion":"10.9.8","description":"TypeScript marker tracking for the browser, built on a WebAssembly build of ARToolkit5 (WebARKitLib). Composable and tree-shakeable: state is plain data, operations are functions.","directories":{},"_nodeVersion":"22.23.2","dependencies":{"@ar-js-org/artoolkit5-wasm":"^0.1.3"},"_hasShrinkwrap":false,"devDependencies":{"vite":"^8.1.0","three":"^0.185.0","vitest":"^4.1.10","typescript":"^6.0.3","@types/node":"^26.0.1","@types/three":"^0.185.0"},"_npmOperationalInternal":{"tmp":"tmp/artoolkit5-ts_0.1.0_1786882852180_0.6062789449009431","host":"s3://npm-registry-packages-npm-production"}},"0.2.0":{"name":"@ar-js-org/artoolkit5-ts","version":"0.2.0","keywords":["artoolkit","artoolkit5","augmented-reality","ar","webar","marker-tracking","barcode-marker","webassembly","wasm","typescript","ar.js","webarkit"],"author":{"url":"https://github.com/kalwalt","name":"Walter Perdan"},"license":"MIT","_id":"@ar-js-org/artoolkit5-ts@0.2.0","maintainers":[{"name":"kalwalt","email":"info@kalwaltart.it"},{"name":"nickw1","email":"nickw4426@gmail.com"},{"name":"nicolocarpignoli","email":"nicolocarpignoli@gmail.com"}],"homepage":"https://github.com/AR-js-org/artoolkit5-ts#readme","bugs":{"url":"https://github.com/AR-js-org/artoolkit5-ts/issues"},"dist":{"shasum":"70dbef0a1f6d42905a5ec546d1c86cc815368214","tarball":"https://registry.npmjs.org/@ar-js-org/artoolkit5-ts/-/artoolkit5-ts-0.2.0.tgz","fileCount":15,"integrity":"sha512-3GXb+OjIZL4onqp/XMsb8WznuQJ5GklJBxTq2ZGF5Ex6IXXShrU8r9PC4ZZVtAMbBhJ4WiLAMc4zkrQxejzHdA==","signatures":[{"sig":"MEQCIHrFtYSLHFxoRnKf31+lezgDvAeFOzKMjZFwfwtfN1OvAiA4qt2R2fTS8TCZ/0SXAkDFnrvDHJiLy5EPpubiL4bXmQ==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"},{"sig":"MEQCIHpcCg+c7Pad7B4wpIYNkiABhsW1wbwC+gxiTG1TGbM6AiBx7jW34Mo4Ge0CHlWX/LhFaoGM+br7XxOp2LQlxT8Ykg==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":70800},"main":"./dist/artoolkit5-ts.umd.cjs","type":"module","types":"./dist/index.d.ts","module":"./dist/artoolkit5-ts.js","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/artoolkit5-ts.js","require":"./dist/artoolkit5-ts.umd.cjs"}},"gitHead":"96362d8ae0476002a6ecda38d9767e629a23ace8","private":false,"scripts":{"dev":"vite","test":"vitest run","build":"vite build && tsc -p tsconfig.build.json","preview":"vite preview","typecheck":"tsc --noEmit -p tsconfig.json","test:watch":"vitest","release-notes":"node scripts/release-notes.mjs"},"_npmUser":{"name":"kalwalt","email":"info@kalwaltart.it"},"repository":{"url":"git+https://github.com/AR-js-org/artoolkit5-ts.git","type":"git"},"_npmVersion":"11.19.0","description":"TypeScript marker tracking for the browser, built on a WebAssembly build of ARToolkit5 (WebARKitLib). Composable and tree-shakeable: state is plain data, operations are functions.","directories":{},"_nodeVersion":"24.20.0","dependencies":{"@ar-js-org/artoolkit5-wasm":"^0.3.0","@ar-js-org/artoolkit5-constants":"^0.3.0"},"_hasShrinkwrap":false,"devDependencies":{"vite":"^8.1.0","three":"^0.185.0","vitest":"^4.1.10","typescript":"^6.0.3","@types/node":"^26.0.1","@types/three":"^0.185.0"},"_npmOperationalInternal":{"tmp":"tmp/artoolkit5-ts_0.2.0_1789656419080_0.48129047243724576","host":"s3://npm-registry-packages-npm-production"}},"0.2.1":{"name":"@ar-js-org/artoolkit5-ts","version":"0.2.1","keywords":["artoolkit","artoolkit5","augmented-reality","ar","webar","marker-tracking","barcode-marker","webassembly","wasm","typescript","ar.js","webarkit"],"author":{"url":"https://github.com/kalwalt","name":"Walter Perdan"},"license":"MIT","_id":"@ar-js-org/artoolkit5-ts@0.2.1","maintainers":[{"name":"kalwalt","email":"info@kalwaltart.it"},{"name":"nickw1","email":"nickw4426@gmail.com"},{"name":"nicolocarpignoli","email":"nicolocarpignoli@gmail.com"}],"homepage":"https://github.com/AR-js-org/artoolkit5-ts#readme","bugs":{"url":"https://github.com/AR-js-org/artoolkit5-ts/issues"},"dist":{"shasum":"a3a969aba4534491ed77e55e1a137d84c3ea66bc","tarball":"https://registry.npmjs.org/@ar-js-org/artoolkit5-ts/-/artoolkit5-ts-0.2.1.tgz","fileCount":15,"integrity":"sha512-Rm2pcZ3I3izrS5JLcJcQxhGzDFAt+dsxwDC28+jJMCOonFlgnbZMdY5RgwdMVuqYP6k1itwdxXNtpqdAFZZFLg==","signatures":[{"sig":"MEQCIEvCnJMfbtX8Qp2UclYzNfOhKwP+YySpeT1RT8qU/+A9AiA8VTGFrBGaKb9n17P/LwnKVCW6QVD4ukSaiKhTv6cWmg==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"},{"sig":"MEQCICGi4In2dYCWReaX0eNsQ0MnYSS+i1utwyNjnRr9RDpeAiAPqslHT6eunJzZ3ehO4S0ALLbqY/QmnZ+n0nwb0H7t4g==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":74379},"main":"./dist/artoolkit5-ts.umd.cjs","type":"module","types":"./dist/index.d.ts","module":"./dist/artoolkit5-ts.js","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/artoolkit5-ts.js","require":"./dist/artoolkit5-ts.umd.cjs"}},"gitHead":"7579026a5086ea48b4855531a19fa1356a0ecbba","private":false,"scripts":{"dev":"vite","test":"vitest run","build":"vite build && tsc -p tsconfig.build.json","preview":"vite preview","typecheck":"tsc --noEmit -p tsconfig.json","test:watch":"vitest","release-notes":"node scripts/release-notes.mjs"},"_npmUser":{"name":"kalwalt","email":"info@kalwaltart.it"},"repository":{"url":"git+https://github.com/AR-js-org/artoolkit5-ts.git","type":"git"},"_npmVersion":"11.19.0","description":"TypeScript marker tracking for the browser, built on a WebAssembly build of ARToolkit5 (WebARKitLib). Composable and tree-shakeable: state is plain data, operations are functions.","directories":{},"_nodeVersion":"24.20.0","dependencies":{"@ar-js-org/artoolkit5-wasm":"^0.3.0","@ar-js-org/artoolkit5-constants":"^0.3.0"},"_hasShrinkwrap":false,"devDependencies":{"vite":"^8.1.0","three":"^0.185.0","vitest":"^4.1.10","typescript":"^6.0.3","@types/node":"^26.0.1","@types/three":"^0.185.0"},"_npmOperationalInternal":{"tmp":"tmp/artoolkit5-ts_0.2.1_1789803159290_0.15028724984983333","host":"s3://npm-registry-packages-npm-production"}},"0.2.2":{"_id":"@ar-js-org/artoolkit5-ts@0.2.2","bugs":{"url":"https://github.com/AR-js-org/artoolkit5-ts/issues"},"dist":{"shasum":"e2852fa633ade58d88def56d992d57c7d82e868c","tarball":"https://registry.npmjs.org/@ar-js-org/artoolkit5-ts/-/artoolkit5-ts-0.2.2.tgz","fileCount":15,"integrity":"sha512-eVw5TYtcKY2HP+b06MSMy2vKn0/rB54PUTdCiEGo88IHNpADRA2b9oN+b11ag4G6cOEO4zBYFFhumX98bZ+lpA==","signatures":[{"sig":"MEUCIFXAg6/5AcVrwcB87im/baSjtVNWCx0TgLTGxArpjqnyAiEAuedxYvc2MG/0BaXB0JRJWK8Wkd38YEwRjE7YC8MM2F4=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"},{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQDR/6cYq6cgporOrlO0MxIs5iyqLEjbtLyB6ZDz0nbhUgIhAP5+5l91fQlYHC+RUN81/iU3nQr/sB35edBUNLtDycmi"}],"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@ar-js-org%2fartoolkit5-ts@0.2.2","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"unpackedSize":74524},"main":"./dist/artoolkit5-ts.umd.cjs","name":"@ar-js-org/artoolkit5-ts","type":"module","types":"./dist/index.d.ts","author":{"url":"https://github.com/kalwalt","name":"Walter Perdan"},"module":"./dist/artoolkit5-ts.js","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/artoolkit5-ts.js","require":"./dist/artoolkit5-ts.umd.cjs"}},"gitHead":"c19cd68777c94c461dae0bef2c08c12f729ae4af","license":"MIT","private":false,"scripts":{"dev":"vite","test":"vitest run","build":"vite build && tsc -p tsconfig.build.json","preview":"vite preview","typecheck":"tsc --noEmit -p tsconfig.json","test:watch":"vitest","release-notes":"node scripts/release-notes.mjs"},"version":"0.2.2","_npmUser":{"name":"GitHub Actions","email":"npm-oidc-no-reply@github.com","trustedPublisher":{"id":"github","oidcConfigId":"oidc:e878d5c4-1224-4e0b-888b-4889ec8ccf38"}},"homepage":"https://github.com/AR-js-org/artoolkit5-ts#readme","keywords":["artoolkit","artoolkit5","augmented-reality","ar","webar","marker-tracking","barcode-marker","webassembly","wasm","typescript","ar.js","webarkit"],"repository":{"url":"git+https://github.com/AR-js-org/artoolkit5-ts.git","type":"git"},"_npmVersion":"11.19.0","description":"TypeScript marker tracking for the browser, built on a WebAssembly build of ARToolkit5 (WebARKitLib). Composable and tree-shakeable: state is plain data, operations are functions.","directories":{},"maintainers":[{"name":"kalwalt","email":"info@kalwaltart.it"},{"name":"nickw1","email":"nickw4426@gmail.com"},{"name":"nicolocarpignoli","email":"nicolocarpignoli@gmail.com"}],"_nodeVersion":"24.20.0","dependencies":{"@ar-js-org/artoolkit5-wasm":"^0.3.0","@ar-js-org/artoolkit5-constants":"^0.3.0"},"_hasShrinkwrap":false,"devDependencies":{"vite":"^8.1.0","three":"^0.185.0","vitest":"^4.1.10","typescript":"^6.0.3","@types/node":"^26.0.1","@types/three":"^0.185.0"},"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/artoolkit5-ts_0.2.2_1789804781405_0.24271754147660896"}}},"time":{"created":"2026-08-16T12:20:51.950Z","modified":"2026-09-19T07:59:41.864Z","0.1.0":"2026-08-16T12:20:52.323Z","0.2.0":"2026-09-17T14:46:59.164Z","0.2.1":"2026-09-19T07:32:39.363Z","0.2.2":"2026-09-19T07:59:41.501Z"},"bugs":{"url":"https://github.com/AR-js-org/artoolkit5-ts/issues"},"author":{"url":"https://github.com/kalwalt","name":"Walter Perdan"},"license":"MIT","homepage":"https://github.com/AR-js-org/artoolkit5-ts#readme","keywords":["artoolkit","artoolkit5","augmented-reality","ar","webar","marker-tracking","barcode-marker","webassembly","wasm","typescript","ar.js","webarkit"],"repository":{"url":"git+https://github.com/AR-js-org/artoolkit5-ts.git","type":"git"},"description":"TypeScript marker tracking for the browser, built on a WebAssembly build of ARToolkit5 (WebARKitLib). Composable and tree-shakeable: state is plain data, operations are functions.","maintainers":[{"name":"kalwalt","email":"info@kalwaltart.it"},{"name":"nickw1","email":"nickw4426@gmail.com"},{"name":"nicolocarpignoli","email":"nicolocarpignoli@gmail.com"}],"readme":"# artoolkit5-ts 🎯\n\n[![npm](https://img.shields.io/npm/v/@ar-js-org/artoolkit5-ts.svg?logo=npm&logoColor=white)](https://www.npmjs.com/package/@ar-js-org/artoolkit5-ts)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)\n[![TypeScript](https://img.shields.io/badge/TypeScript-strict-3178C6.svg?logo=typescript&logoColor=white)](tsconfig.json)\n[![Tested with Vitest](https://img.shields.io/badge/tested%20with-Vitest-6E9F18.svg?logo=vitest&logoColor=white)](test)\n[![WebAssembly](https://img.shields.io/badge/WebAssembly-ARToolkit5-654FF0.svg?logo=webassembly&logoColor=white)](https://github.com/AR-js-org/artoolkit5-wasm)\n[![Status: alpha](https://img.shields.io/badge/status-alpha-orange.svg)](#-roadmap)\n[![AR.js-next](https://img.shields.io/badge/AR.js--next-engine%20layer-00B4D8.svg)](https://github.com/AR-js-org/AR.js-next)\n\nTypeScript marker tracking for the browser, built on a WebAssembly build of ARToolkit5 (WebARKitLib).\n\n**This is the replacement for [`artoolkit5-js`](https://github.com/AR-js-org/artoolkit5-js)**, which is a fork of [`andypotato/artoolkit5-js`](https://github.com/andypotato/artoolkit5-js) — itself an ES6 module port of artoolkit5.\n\n`artoolkit5-ts` is a rewrite rather than another fork in that line. It is written in TypeScript against a maintained WebAssembly build, and it drops the monolithic `ARController` class those ports carried forward in favour of plain data and free functions. Nothing is hidden behind a class, so nothing has to be constructed before it can be used, tested, or tree-shaken.\n\n> ⚠️ **Status: alpha.** Pattern markers work end to end, but the API is not stable yet — expect breaking changes before 1.0. See [Roadmap](#-roadmap).\n\n## 🧩 Where this fits\n\n`artoolkit5-ts` is the detection engine layer of the AR.js-next ecosystem:\n\n```\nAR.js-next                ECS core, event bus, frame pump\n  arjs-plugin-artoolkit     ECS plugin: Web Worker, ImageBitmap, marker events\n    artoolkit5-ts           ← this library\n      artoolkit5-wasm       Emscripten / C++ bindings\n        artoolkit5-constants  ARToolkit5 constants, extracted from the headers\n```\n\nIt is renderer-agnostic and DOM-free. It gives you marker poses as matrices; what you draw with them is your business — Three.js, Babylon.js, raw WebGL, or nothing at all.\n\n## 📦 Installation\n\n```bash\nnpm install @ar-js-org/artoolkit5-ts\n```\n\n[`@ar-js-org/artoolkit5-wasm`](https://www.npmjs.com/package/@ar-js-org/artoolkit5-wasm) (`^0.3.0`) provides the WebAssembly engine. It installs automatically as a dependency, and is left external rather than bundled so the `.wasm` binary is fetched once and cached instead of being copied into every bundle that depends on it.\n\n`three` is only needed to run the examples, not the library.\n\n## 🚀 Quick start\n\n```typescript\nimport {\n  createARToolKitState,\n  loadPatternMarker,\n  trackMarker,\n  processFrame,\n} from '@ar-js-org/artoolkit5-ts';\n\n// 1. Initialise once — loads the WASM module and camera calibration\nconst state = await createARToolKitState(640, 480, './data/camera_para.dat');\n\n// 2. Register the markers you care about.\n//    The ID is assigned by the engine — never hardcode it.\nconst markerId = await loadPatternMarker(state, './data/patt.hiro');\ntrackMarker(state, markerId, 1.0);\n\n// 3. Per frame: pass RGBA pixels in, get poses out.\n//    Draw your video to a canvas and read it back; the library never\n//    touches the DOM, so obtaining the pixels is your side of the line.\nconst pixels = ctx.getImageData(0, 0, 640, 480).data;\nconst { detected, lost } = processFrame(state, pixels);\n\nfor (const marker of detected) {\n  // marker.matrixGL is a 4x4 column-major right-handed matrix,\n  // ready to hand to WebGL or Three.js.\n  // With Three.js, set mesh.matrixAutoUpdate = false once beforehand,\n  // or it recomputes the matrix from position/quaternion/scale and\n  // discards the pose you just wrote.\n  mesh.matrix.fromArray(marker.matrixGL);\n}\n\n// `lost` holds markers that were visible last frame and are not now —\n// reported once, on the frame they disappear\nfor (const marker of lost) {\n  hideObjectFor(marker.type, marker.id);\n}\n```\n\nTwo complete working examples — webcam capture, marker tracking and a Three.js cube overlay:\n\n```bash\nnpm run dev\n```\n\n[`examples/webcam`](examples/webcam) tracks a pattern marker; you will need the [Hiro marker](https://commons.wikimedia.org/wiki/File:Hiro_marker_wikipedia.png) printed or on a second screen. [`examples/barcode`](examples/barcode) tracks a matrix code marker instead — the marker image it needs ships in `examples/barcode/data/`.\n\n## 🧠 Why functions instead of a controller class\n\nThe `ARController` that `artoolkit5-js` inherited from `jsartoolkit5` was a God Object: it owned the WASM module, the canvas, the video element, marker state and the render loop. That made it impossible to tree-shake, awkward to run in a Worker, and hard to test without a browser.\n\nHere, `ARToolKitState` is a plain data container with no methods, and every operation takes it as its first argument:\n\n- **Tree-shakeable** — you bundle only the functions you import\n- **Testable** — functions take input and return output; no mocking a class hierarchy\n- **Worker-friendly** — no DOM anywhere in `src/`, so state can live off the main thread\n- **Framework-agnostic** — nothing assumes React, Vue, or any renderer\n\nThe trade-off is deliberate: this library will not open your camera, create a canvas, or run a render loop for you. Those belong to your application.\n\n## 📖 API\n\n### `createARToolKitState(width, height, cameraUrl, wasmUrl?)`\n\nInitialises the WASM module and camera parameters. Returns `Promise<ARToolKitState>`.\n\n| Parameter | Type | Description |\n|---|---|---|\n| `width` | `number` | Frame width; must match the frames you pass to `processFrame` |\n| `height` | `number` | Frame height |\n| `cameraUrl` | `string` | URL of an ARToolKit `camera_para.dat` calibration file |\n| `wasmUrl` | `string?` | Explicit URL for `artoolkit5.wasm`. Required when your bundler rewrites asset paths, as Vite does |\n\n### `loadPatternMarker(state, markerUrl)`\n\nDownloads a `.patt` file, writes it to the WASM virtual filesystem and registers it. Returns `Promise<number>` — the engine-assigned marker ID.\n\nLoading a marker does not start tracking it; pass the ID to `trackMarker`.\n\n### `trackMarker(state, pattId, markerWidth?)`\n\nRegisters a marker for tracking and allocates its reusable pose buffers.\n\n`markerWidth` defaults to `1.0`. Whatever unit you choose here is the unit all returned translations are expressed in — use millimetres if you want millimetres.\n\n### `trackBarcodeMarker(state, barcodeId, markerWidth?)`\n\nRegisters a barcode (matrix code) marker for tracking. Unlike a pattern marker, there is nothing to load first: the ID is encoded directly in the marker's geometry, so `barcodeId` is a value you choose when generating the marker, not one the engine assigns — pass it straight to this function.\n\nDetecting a barcode marker also requires `configureDetector` to have set a matrix-capable `detectionMode` (`'matrix'`, `'color_and_matrix'`, or `'mono_and_matrix'`) and a `matrixCodeType` matching the marker.\n\nPattern and barcode markers have **independent ID spaces**, and are kept in separate registries. Pattern IDs are assigned by the engine starting at 0; barcode IDs are encoded in the marker's own geometry and chosen by whoever printed it. So `7` in one family is unrelated to `7` in the other, and both can be tracked at once:\n\n```typescript\n// Pattern IDs come from the engine — never hardcode them\nconst patternId = await loadPatternMarker(state, './data/patt.hiro');\ntrackMarker(state, patternId);           // -> state.patternMarkers\n\n// Barcode IDs are yours: encoded in the marker you printed\ntrackBarcodeMarker(state, 0);            // -> state.barcodeMarkers\n```\n\nIf `patternId` also happens to be `0` — and it usually is, since the engine\nassigns from zero — both are tracked independently. Detections and losses\ncarry `type`, so you can always tell which family a result came from.\n\nThe engine reports each family through its own field (`idPatt` / `idMatrix`), so a detection is only ever matched against the registry it belongs to.\n\n### `configureDetector(state, opts)`\n\nTunes the underlying detector. Only the keys you pass are changed — call it again later with a single option to adjust just that one, mid-session.\n\n```typescript\nconfigureDetector(state, {\n  detectionMode: 'matrix',       // 'color' | 'mono' | 'matrix' | 'color_and_matrix' | 'mono_and_matrix'\n  matrixCodeType: '4x4_BCH_13_9_3',\n  thresholdMode: 'auto_otsu',    // 'manual' | 'auto_median' | 'auto_otsu' | 'auto_bracketing'\n  threshold: 100,                // 0–255, only meaningful when thresholdMode is 'manual'\n  labelingMode: 'black_region',  // 'white_region' | 'black_region' — the engine default\n  imageProcMode: 'frame',        // 'frame' | 'field'\n  patternRatio: 0.5,             // > 0 and < 1, exclusive\n  nearPlane: 1,\n  farPlane: 1000,\n  minConfidence: { pattern: 0, barcode: 0 },   // 0–1 per family; see below\n                                               // before choosing a value\n});\n```\n\nAn invalid string value or an out-of-range `threshold`/`patternRatio` throws `ARToolKitError` naming the option and, for string options, listing what it does accept — the engine itself would otherwise silently ignore the bad value and keep its previous setting, which is a much harder bug to notice.\n\n`'auto_adaptive'` threshold mode is not offered: the WebARKitLib build this library ships compiles that mode's implementation out, so passing it would silently degrade to `'manual'` while claiming to work.\n\n#### `minConfidence` — rejecting weak matches\n\nEvery other option here is handed to the engine. `minConfidence` is the exception: ARToolKit's own confidence cutoff is a compile-time constant with no setter, so this threshold is applied by `processFrame` instead. It can only ever be *stricter* than the engine's built-in 0.5.\n\nThe two families take separate thresholds because their confidences are not comparable.\n\n**There is no safe default value, and this library does not ship one.** Measured on a real camera with a Hiro pattern marker and 3x3 matrix markers:\n\n| | genuine match | false match |\n|---|---|---|\n| **pattern** (template matching) | 0.506 – 0.923 | 0.526 – 0.554 *(read off a barcode square)* |\n| **barcode** (matrix code) | 0.500 – 1.000 | 0.633 – 0.867 *(read off a pattern square)* |\n\nBoth ranges **overlap**, in both directions. A genuine pattern match scored `0.506`, below a false one at `0.554`. A genuine barcode scored `0.500` at an awkward angle while a phantom barcode — the engine decoding a Hiro marker's interior as a 3x3 grid — reached `0.867`. The same barcode marker, in the same detection mode minutes apart, ranged from `0.500` to `0.967` purely on viewing angle and focus.\n\nSo confidence is a continuous quality score, not a verdict, for **both** families. Matrix codes are *not* digital in this respect: a clean decode does not imply `1.0`.\n\nWhat that means in practice:\n\n- Both thresholds default to `0` — nothing is filtered beyond the engine's own 0.5 cutoff.\n- Any threshold you set trades missed real markers against admitted phantoms. There is no value that avoids both.\n- Measure **your** markers, in **your** lighting, at the angles you expect. Log `marker.confidence` for a while before choosing a number.\n- A threshold is most defensible when you control the conditions — fixed mounting, known print quality, consistent lighting — and least defensible in an uncontrolled environment.\n\n### `processFrame(state, videoFrame)`\n\nDetects registered markers in one frame. Returns a `FrameResult`:\n\n```typescript\ninterface FrameResult {\n  detected: MarkerPose[];  // visible in this frame\n  lost: LostMarker[];      // { id, type } visible last frame, gone in this one\n}\n```\n\nEach `lost` entry carries `type` as well as `id`, because the two families have independent ID spaces — a pattern `7` and a barcode `7` may both be registered, and an ID alone could not say which disappeared.\n\n`lost` is reported **exactly once**, on the frame a marker disappears — it does not repeat while the marker stays absent. Tracking already computes this transition internally, so exposing it saves every consumer from diffing successive results to recover it.\n\n`videoFrame` is a `Uint8ClampedArray` of RGBA pixels matching the width and height the state was created with — typically `ctx.getImageData(...).data`.\n\nThis runs on every animation frame and allocates no typed arrays: poses are written into buffers owned by the marker's tracking state, and **those buffers are reused next frame**. Copy the values if you need to retain them.\n\n### `disposeARToolKitState(state)`\n\nReleases the WASM resources the state holds. Call it when tracking stops — otherwise a page that starts and stops AR leaks the C++ instance and its heap allocations every time.\n\n```typescript\nconst state = await createARToolKitState(640, 480, cameraUrl);\n// … track markers …\ndisposeARToolKitState(state);\n```\n\nSafe to call more than once. Afterwards every other operation on that state throws `ARToolKitError` rather than reaching freed memory, so a use-after-dispose gives you a clear message instead of a crash inside the WASM module.\n\n### `ARToolKitError`\n\nThrown for misuse of this API — currently, using a state after disposing it. Distinct from a plain `Error` so you can tell an API mistake apart from a failure inside the WASM module or your own code.\n\n### `getCameraProjectionMatrix(state)`\n\nReturns the 4×4 projection matrix ARToolKit computed from your `camera_para.dat`, as a `Float64Array`. Use it in place of a generic perspective camera: it carries the measured focal length and principal point of the actual lens, so rendered geometry lines up with the video rather than merely sitting near it. (Radial distortion is not part of this matrix — no projection matrix can express it. ARToolKit corrects for it separately, when un-distorting detected marker corners.)\n\n### `transMatToGLMat(transMat, out?)` / `arglCameraViewRHf(glMatrix, out?, scale?)`\n\nMatrix helpers, exported because they are occasionally useful directly. `processFrame` already applies both.\n\nARToolKit produces a 3×4 row-major pose; WebGL wants a 4×4 column-major matrix in a right-handed system. `transMatToGLMat` expands the matrix, `arglCameraViewRHf` negates the Y and Z axes. Without the second step, poses render behind the camera.\n\nBoth take an optional output buffer — supply one in hot paths to avoid allocating.\n\n### Types\n\n`ARToolKitState`, `MarkerPose`, `FrameResult`, `LostMarker`, `TrackedMarkerState`, `MarkerType`, plus `ARToolKitModule`, `ARToolKitCore` and `MarkerInfo` describing the WASM boundary. `DetectorOptions` and its option types (`DetectionMode`, `MatrixCodeType`, `ThresholdMode`, `LabelingMode`, `ImageProcMode`) describe `configureDetector`'s input.\n\n```typescript\ninterface MarkerPose {\n  id: number;\n  type: 'pattern' | 'barcode';\n  confidence: number;      // 0–1, from this marker's own family\n  matrix: Float64Array;    // 3x4, row-major, as ARToolKit produces it\n  matrixGL: Float32Array;  // 4x4, column-major, right-handed, WebGL-ready\n  vertex: [number, number][];  // the square's 4 corners, camera image coords\n}\n```\n\n`vertex` gives the four corners of the detected square in camera image\ncoordinates, origin at top-left — enough to outline a marker, hit-test it or\nbuild an occlusion mask without touching the camera projection matrix. Two\nthings differ from the pose matrices:\n\n- **It is freshly allocated per frame**, not a view onto a reused buffer, so it is\n  safe to retain without copying. `matrix` and `matrixGL` are the opposite.\n- **Corner order follows the marker's rotation.** `vertex[(4 - dir) % 4]` is\n  the marker's own top-left corner, the rest clockwise from there. Outlining\n  the square can ignore this; anything orientation-sensitive cannot.\n\nThe webcam example draws exactly this outline, marking corner 0 so the\nordering is visible: see `createOutlineDrawer` in\n[`examples/webcam/main.ts`](examples/webcam/main.ts).\n\n`confidence` is read from the field belonging to the marker's family — `cfPatt` or `cfMatrix` — so it is comparable within a family but not across them. See [`minConfidence`](#minconfidence--rejecting-weak-matches) for measured ranges.\n\n`type` says which family a detection came from. The engine reports the two through separate fields — `idPatt` for pattern markers, `idMatrix` for barcode markers — and each is matched only against its own registry, so `type` follows from which registry answered rather than from any value the engine supplies. This is also why the families have independent ID spaces: the same integer in each is two unrelated markers.\n\n## 🖼️ Feeding frames from an ImageBitmap\n\n`processFrame` takes raw pixels, so `src/` never touches a canvas API. If your frames arrive as `ImageBitmap` — as they do in AR.js-next — convert them yourself, reusing one canvas rather than creating one per frame:\n\n```typescript\n// The same dimensions the state was created with. Reading back any other\n// size gives processFrame a buffer it will misinterpret.\nconst WIDTH = 640;\nconst HEIGHT = 480;\n\nconst canvas = new OffscreenCanvas(WIDTH, HEIGHT);\nconst ctx = canvas.getContext('2d', { willReadFrequently: true })!;\n\nfunction toPixels(bitmap: ImageBitmap): Uint8ClampedArray {\n  ctx.drawImage(bitmap, 0, 0, WIDTH, HEIGHT);\n  return ctx.getImageData(0, 0, WIDTH, HEIGHT).data;\n}\n```\n\nA helper that does this is on the roadmap; until then it is a few lines you own.\n\n## ⚠️ Limitations\n\n- **Combined detection requires `@ar-js-org/artoolkit5-wasm` >= 0.3.0.** `'color_and_matrix'` and `'mono_and_matrix'` rely on the per-mode marker fields (`idPatt`/`idMatrix`), which earlier versions of the binding did not expose — against `0.2.0` or older those modes silently detect nothing, or report the wrong marker. The dependency range already requires `^0.3.0`; this matters only if you override it.\n- **Worker support is untested.** Nothing in `src/` touches the DOM, which is necessary but not proof — WASM instantiation in worker scope has not been verified.\n- **NFT markers are out of scope** for this project — see [Roadmap](#-roadmap).\n\n## 🗺️ Roadmap\n\nDetailed design lives in [`docs/DESIGN-v0.1.md`](docs/DESIGN-v0.1.md) and, for the detector and barcode work, [`docs/DESIGN-detector-and-barcode.md`](docs/DESIGN-detector-and-barcode.md); work is tracked in [issues](https://github.com/AR-js-org/artoolkit5-ts/issues).\n\n**v0.1** (done) — lifecycle, packaging, marker-lost reporting from `processFrame`, a test suite and CI.\n\n**v0.2** (done) — `configureDetector`, barcode markers, independent ID registries for the two families, combined pattern+barcode detection verified against a real camera, and per-family match confidence.\n\n**Next** — a verified Worker example, an `ImageBitmap` conversion helper, and multi-marker sets.\n\n**Out of scope** — NFT tracking. This project and `artoolkit5-wasm` cover pattern and barcode markers; NFT belongs to other projects in the ecosystem.\n\n## 🛠️ Development\n\n```bash\nnpm run dev        # Vite dev server, opens the webcam example\nnpm run build      # library build (ES + UMD) plus type declarations\nnpm run preview    # preview the production build\nnpm test           # run the test suite once\nnpm run test:watch # re-run tests on change\nnpm run typecheck  # tsc --noEmit\n```\n\n### Tests\n\n[Vitest](https://vitest.dev) covers the matrix maths, the marker visibility state machine and the dispose lifecycle. The suite runs in well under a second because the WASM boundary is faked: `test/mock-core.ts` stands in for the Emscripten module and the bound C++ instance, so neither a browser nor a compiled binary is needed.\n\nThe suite aims at the code that fails *quietly* rather than at a line-count target — a transposed matrix still renders, just in the wrong place, and a marker-lost event that fires twice looks fine until something downstream double-handles it.\n\nIt is validated by mutation: deliberately breaking the collection order, the `Float32Array` return type, or the continuous-tracking condition each makes exactly one test fail. If you add tests, check they can actually fail.\n\n### Contributing\n\nBranch from `dev`; `main` holds release-ready code only. Commits follow [Conventional Commits](https://www.conventionalcommits.org/). Fuller guidance is in [`AGENTS.md`](AGENTS.md).\n\n### Releasing\n\nReleases are cut by the **Release** workflow, run manually from the Actions tab. Its only required input is the version to publish, without a leading `v` — for example `0.1.0`.\n\nEverything after that is automatic: it runs typecheck, tests and build, sets the version, promotes the changelog, derives release notes from the commits, commits, tags `vX.Y.Z`, creates the GitHub Release and publishes to npm with [provenance](https://docs.npmjs.com/generating-provenance-statements) — so the package carries a verifiable link back to the commit and workflow run that built it.\n\n**Run it with `dry_run` first.** That performs every check and prints the notes and the tarball contents without tagging, committing or publishing. It is the only way to rehearse: npm never allows a published version to be replaced.\n\nBefore running for real, the workflow refuses to start unless:\n\n- the version is valid semver, not already tagged, and not already on npm\n- the branch is `main`\n- the repository is public — npm will not generate provenance from a private repository\n\nPreparing a release means writing the changelog. Add entries to `## [Unreleased]` as you go; the workflow renames that heading to the released version and opens a fresh one. Anything between `<!-- promote:strip -->` markers is dropped during promotion, so notes meant only for editors do not survive into a released section. `npm run release-notes` prints the Conventional Commits since the last tag if you want to see what has accumulated.\n\nIt is a single workflow rather than a \"create release\" and a \"publish\" pair because a Release created with the default `GITHUB_TOKEN` does not trigger other workflows — GitHub blocks that to prevent recursion, so the second one would silently never fire.\n\n## 📄 Licence\n\nMIT — see [LICENSE](LICENSE).\n\nThis library wraps a WebAssembly build of **ARToolkit5 (WebARKitLib), which is licensed under the LGPL v3.0**. The MIT licence covers this TypeScript code, not the engine underneath: redistributing a build that includes the ARToolkit5 (WebARKitLib) WebAssembly binary carries that licence's obligations as well.\n","readmeFilename":"README.md"}