{"_id":"@ar-js-org/aruco-rs","name":"@ar-js-org/aruco-rs","dist-tags":{"latest":"0.1.0"},"versions":{"0.1.0":{"name":"@ar-js-org/aruco-rs","type":"module","collaborators":["kalwalt <https://github.com/kalwalt>"],"description":"A high-performance, SIMD-accelerated ArUco marker detector for Native and WASM.","version":"0.1.0","license":"MIT","repository":{"type":"git","url":"git+https://github.com/AR-js-org/aruco-rs.git"},"main":"aruco_rs.js","types":"aruco_rs.d.ts","sideEffects":["./snippets/*"],"keywords":["cv","computervision","aruco","simd","wasm"],"_id":"@ar-js-org/aruco-rs@0.1.0","gitHead":"502ca008130d1e968ff64e831fcd04e791f1d172","bugs":{"url":"https://github.com/AR-js-org/aruco-rs/issues"},"homepage":"https://github.com/AR-js-org/aruco-rs#readme","_nodeVersion":"22.21.1","_npmVersion":"10.9.4","dist":{"integrity":"sha512-Xp5U2ig+F6J4bQD6TDHnQLs0blkBEyrmfWUYwJ8dtZwxJMmDHSa7jYuwYO+RLNe9CBqx74uBqmI94yunWxb82w==","shasum":"fb4239231520109e4174f436dc6a09c4ed930980","tarball":"https://registry.npmjs.org/@ar-js-org/aruco-rs/-/aruco-rs-0.1.0.tgz","fileCount":6,"unpackedSize":74258,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIGg7xAvI7djYIt+Ejh46wWpzVBCvIsLbEk271yeuQLUEAiEAv/h2AqDKJ3NEOJkCtNVaEe/hjsVy90NHJN/9ZGaBEn4="}]},"_npmUser":{"name":"kalwalt","email":"info@kalwaltart.it"},"directories":{},"maintainers":[{"name":"kalwalt","email":"info@kalwaltart.it"},{"name":"nickw1","email":"nickw4426@gmail.com"},{"name":"nicolocarpignoli","email":"nicolocarpignoli@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/aruco-rs_0.1.0_1772231127970_0.14723162323201833"},"_hasShrinkwrap":false}},"time":{"created":"2026-02-27T22:25:27.882Z","0.1.0":"2026-02-27T22:25:28.144Z","modified":"2026-02-27T22:25:28.395Z"},"maintainers":[{"name":"kalwalt","email":"info@kalwaltart.it"},{"name":"nickw1","email":"nickw4426@gmail.com"},{"name":"nicolocarpignoli","email":"nicolocarpignoli@gmail.com"}],"description":"A high-performance, SIMD-accelerated ArUco marker detector for Native and WASM.","homepage":"https://github.com/AR-js-org/aruco-rs#readme","keywords":["cv","computervision","aruco","simd","wasm"],"repository":{"type":"git","url":"git+https://github.com/AR-js-org/aruco-rs.git"},"bugs":{"url":"https://github.com/AR-js-org/aruco-rs/issues"},"license":"MIT","readme":"# aruco-rs\r\n\r\nA high-performance, cross-platform ArUco marker detection library written in Rust and compiled to WebAssembly.\r\n\r\n## What is an ArUco Marker?\r\nAn **ArUco marker** is a synthetic square black marker with a wide black border and an inner binary matrix that determines its unique ID. Originally developed as part of OpenCV, ArUco markers are heavily utilized in Augmented Reality (AR), robotics, and camera calibration due to their robustness, high detection speed, and resilience to occlusion and lighting changes.\r\n\r\nTheir clear planar geometry allows for extremely fast and accurate 3D pose estimation (calculating camera position and rotation relative to the marker) from a single 2D camera feed.\r\n\r\n## Overview\r\nThis project is a native Rust port of [ARuco-ts](https://github.com/kalwalt/ARuco-ts), strictly maintaining 100% bit-for-bit parity while drastically improving performance. \r\n\r\nIt is specifically optimized for **WebAssembly (WASM)** and **Native architectures** using manual **SIMD** kernels. `aruco-rs` is designed to be the foundational tracking engine powering the next-generation Entity Component System (ECS) architecture for [webarkit](https://github.com/webarkit) and [AR.js](https://github.com/AR-js-org). By unifying the CV engine in Rust, both WebXR and Native target platforms benefit from a unified, zero-copy, highly optimized detection pipeline.\r\n\r\n## Project Structure\r\n- `src/cv/`: Computer vision primitives (Grayscale, Threshold, Contours).\r\n- `src/core/`: ArUco specific logic (Detector, Dictionary mapping).\r\n- `src/simd/`: Hardware-specific SIMD implementations (WASM, x86_64, ARM).\r\n- `src/pose/`: 3D math and PnP solvers using `nalgebra`.\r\n\r\n## Development Principles\r\n- **Logic Parity**: We maintain strict 1:1 functional identity with the original `ARuco-ts` algorithms.\r\n- **Performance**: We utilize zero-copy memory management and explicit SIMD instructions to ensure 60fps tracking on web and mobile.\r\n- **Cleanliness**: The core is `no_std` compatible where possible, with all documentation in English.\r\n\r\n## Performance\r\nThe underlying algorithmic port (Scalar fallback without explicit hardware SIMD enablement) performs extremely efficiently:\r\n* **~1,300 FPS** tracking pipeline for `320x240` buffers\r\n* **~295 FPS** tracking pipeline for `640x480` standard webcam buffers\r\n* **~168 FPS** downscaled tracking pipeline interpolating from a raw `2048x2080 (4.2MP)` real-world image. \r\n\r\nThese speeds reflect the entire `Detector` end-to-end execution, spanning raw RGBA grayscale mapping, adaptive thresholding, polygon extraction, marker filtering, homography interpolation, and Dictionary ID hashing.\r\n\r\n## Usage Examples\r\n\r\n### WebAssembly (JavaScript/TypeScript)\r\n`aruco-rs` uses `wasm-bindgen` and `serde` to safely serialize deeply technical math objects into flat, memory-safe Javascript arrays, entirely avoiding manual WASM pointer GC management.\r\n```js\r\nimport { ARucoDetector } from '@ar-js-org/aruco-rs'; // Assuming generated pkg/ folder is exported\r\n\r\n// 1. Initialize detector predicting standard ARUCO dictionary\r\nconst detector = new ARucoDetector(\"ARUCO\", undefined);\r\n\r\n// 2. Obtain raw pixel buffer (e.g. from a <canvas> getImageData or WebGL buffer)\r\nconst width = 640;\r\nconst height = 480;\r\nconst imageData = new Uint8Array(width * height * 4); \r\n\r\n// 3. Detect and receive serialized JSON objects containing ID, Distance, and Corners\r\nconst markers = detector.detect_image(width, height, imageData);\r\n\r\nmarkers.forEach(marker => {\r\n    console.log(`Detected Marker ID: ${marker.id} with ${marker.distance} bit errors.`);\r\n    console.log(`Top-Left Corner: ${marker.corners[0].x}, ${marker.corners[0].y}`);\r\n});\r\n```\r\n\r\n### Native Rust\r\n```rust\r\nuse aruco_rs::core::detector::{Detector, DetectorOptions};\r\nuse aruco_rs::core::dictionary::{Dictionary, PredefinedDictionary};\r\nuse aruco_rs::cv::scalar::ScalarCV;\r\nuse aruco_rs::ImageBuffer;\r\n\r\n// 1. Setup the Detector Pipeline\r\nlet dict = Dictionary::from_predefined(PredefinedDictionary::Aruco);\r\nlet mut detector = Detector::new(dict, ScalarCV, DetectorOptions::default());\r\n\r\n// 2. Prepare the ImageBuffer (wrapping an image decode)\r\nlet raw_pixels: Vec<u8> = vec![0; 640 * 480 * 4];\r\nlet buffer = ImageBuffer { data: &raw_pixels, width: 640, height: 480 };\r\n\r\n// 3. Execute Detection\r\nlet markers = detector.detect(&buffer).unwrap();\r\n\r\nfor marker in markers {\r\n    println!(\"Found ArUco ID {}, Corners: {:?}\", marker.id, marker.corners);\r\n}\r\n```\r\n\r\n## Contributing\r\nWhen creating new source files (`.rs`, `.ts`, `.js`), please ensure they include the standard MIT license header at the very top:\r\n```rust\r\n// Copyright (c) 2026 kalwalt and AR.js-org contributors\r\n//\r\n// This software is released under the MIT License.\r\n// https://opensource.org/licenses/MIT\r\n```\r\nYou can use the provided `add_license.ps1` script to automatically apply this header to missing files.\r\n\r\n## License\r\nMIT","readmeFilename":"README.md","_rev":"1-bdf49b8f2422ff891ac66823ebb9aa4c"}