{"id":13773561,"url":"https://github.com/meta-quest/reality-accelerator-toolkit","last_synced_at":"2025-08-20T22:30:42.475Z","repository":{"id":147015988,"uuid":"610968042","full_name":"meta-quest/reality-accelerator-toolkit","owner":"meta-quest","description":"RATK (Reality Accelerator Toolkit) simplifies the integration of Mixed Reality experiences in WebXR, making it easier for developers to bring their MR ideas to life.","archived":false,"fork":false,"pushed_at":"2023-12-13T18:56:35.000Z","size":945,"stargazers_count":97,"open_issues_count":2,"forks_count":10,"subscribers_count":13,"default_branch":"main","last_synced_at":"2024-05-18T07:02:58.920Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://meta-quest.github.io/reality-accelerator-toolkit/","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/meta-quest.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE.md","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null}},"created_at":"2023-03-07T20:58:44.000Z","updated_at":"2024-05-15T12:47:38.000Z","dependencies_parsed_at":"2024-02-14T05:44:01.836Z","dependency_job_id":null,"html_url":"https://github.com/meta-quest/reality-accelerator-toolkit","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/meta-quest%2Freality-accelerator-toolkit","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/meta-quest%2Freality-accelerator-toolkit/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/meta-quest%2Freality-accelerator-toolkit/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/meta-quest%2Freality-accelerator-toolkit/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/meta-quest","download_url":"https://codeload.github.com/meta-quest/reality-accelerator-toolkit/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":230462906,"owners_count":18229864,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-08-03T17:01:17.149Z","updated_at":"2024-12-19T16:10:33.462Z","avatar_url":"https://github.com/meta-quest.png","language":"TypeScript","funding_links":[],"categories":["Interaction","SDKs"],"sub_categories":["XR Interaction"],"readme":"# Reality Accelerator Toolkit\n\n[![npm version](https://badge.fury.io/js/ratk.svg)](https://badge.fury.io/js/ratk)\n[![language](https://badgen.net/badge/icon/typescript?icon=typescript\u0026label)](https://www.typescriptlang.org/)\n[![npm download](https://badgen.net/npm/dw/ratk)](https://www.npmjs.com/package/ratk)\n[![license](https://badgen.net/github/license/meta-quest/reality-accelerator-toolkit)](/LICENSE.md)\n\nThe Reality Accelerator Toolkit is a comprehensive WebXR utilities library that simplifies the integration of mixed reality features in WebXR applications. Compatible with the [three.js](https://threejs.org/) 3D library, it bridges the gap between the low-level WebXR APIs and the higher-level APIs offered by three.js. Designed for extensibility, it enables the management of detected planes, meshes, anchors, and real-world hit test targets, translating them seamlessly to Object3D instances in the three.js scene.\n\n## Features\n\n- 🚀 Seamless integration with three.js for enhanced 3D application development.\n- 🌐 Automatic detection and update of planes, meshes and anchors in the scene.\n- 🎯 Translation of real-world hit test targets to Object3D instances in three.js.\n\n## Getting Started\n\n### Prerequisites\n\n- **Peer dependency**: three.js (latest version recommended): [three.js Documentation](https://threejs.org/docs/)\n\n### Installation\n\nTo install the package via NPM, run:\n\n```bash\n$ npm install ratk\n```\n\n## Usage\n\nEach section below details how to use different features of the toolkit.\n\n### RATK Setup\n\n1. **Setting Up AR Button**: Request a WebXR session with specified features.\n\n```js\nimport { ARButton } from 'ratk';\nconst renderer = /* Three.js WebGLRenderer */;\nconst arButton = document.getElementById('ar-button');\n\nARButton.convertToARButton(arButton, renderer, {\n  sessionInit: {\n    requiredFeatures: ['hit-test', 'plane-detection', 'mesh-detection', 'anchors'],\n    optionalFeatures: [],\n  },\n});\n```\n\n2. **Initializing RATK**: Integrate RATK's root object with your scene. Update it in the render loop.\n\n```js\n// Import the library\nimport { RealityAccelerator } from 'ratk';\nconst ratk = new RealityAccelerator(renderer.xr);\nconst scene = /* Three.js Scene object */;\nscene.add(ratk.root);\n\nfunction render() {\n\tratk.update();\n}\n```\n\n### Anchors\n\n- **Creating Anchors**: Define position and orientation, then attach objects.\n\n  ```js\n  const ratk = /* RealityAccelerator instance */;\n  const anchorPosition = new Vector3(1, 2, 3);\n  const anchorQuaternion = new Quaternion(0, 0, 0, 1);\n\n  ratk.createAnchor(anchorPosition, anchorQuaternion, isPersistent)\n    .then((anchor /* RATK Anchor object extends Object3D */) =\u003e {\n      // Attach a new THREE.Mesh to the anchor\n      anchor.add(new THREE.Mesh(geometry, material));\n    });\n  ```\n\n- **Recovering Anchors**: Access persistent anchors from previous sessions.\n\n  ```js\n  ratk.restorePersistentAnchors().then(() =\u003e {\n  \tratk.anchors.forEach((anchor) =\u003e {\n  \t\t// Process each recovered anchor\n  \t\tanchor.add(new THREE.Mesh(geometry, material));\n  \t});\n  });\n  ```\n\n### Planes\n\n- **Processing Planes**: Define a hook to handle new planes.\n\n  ```js\n  ratk.onPlaneAdded = (plane /* extends Object3D */) =\u003e {\n  \tif (plane.semanticLabel === 'wall art') {\n  \t\tconst mesh = plane.planeMesh; // Three.js Plane Mesh\n  \t\tmesh.material = new MeshBasicMaterial(/_ parameters _/);\n  \t\t// Additional plane processing\n  \t}\n  };\n  ```\n\n- Alternatively, access planes directly from the RATK instance:\n\n  ```js\n  ratk.planes.forEach((plane) =\u003e {\n  \t// Process each plane\n  });\n  ```\n\n### Meshes\n\n- **Processing Meshes**: Define a hook to handle new meshes.\n\n  ```js\n  ratk.onMeshAdded = (rmesh /* extends Object3D */) =\u003e {\n    const meshMesh = rmesh.meshMesh; /* reconstructed Three.js Mesh */\n    meshMesh.material = new MeshBasicMaterial(...);\n    meshMesh.geometry.computeBoundingBox();\n\n    // put a text label on top of the mesh\n    const semanticLabel = new Text();\n    meshMesh.add(semanticLabel);\n    semanticLabel.text = mesh.semanticLabel;\n    semanticLabel.sync();\n    semanticLabel.position.y = meshMesh.geometry.boundingBox.max.y;\n  };\n  ```\n\n- Alternatively, access meshes directly from the RATK instance:\n\n  ```js\n  ratk.meshes.forEach((rmesh) =\u003e {\n  \t// Process each mesh\n  });\n  ```\n\n### Hit Testing\n\n- **Controller Hit-Testing**: Create HitTestTarget from controller with offset transform\n\n  ```js\n  const ratk = /* RealityAccelerator instance */;\n  const offsetPosition = new Vector3(0, 0, 0);\n  const offsetQuaternion = new Quaternion(0, 0, 0, 1);\n\n  ratk\n    .createHitTestTargetFromControllerSpace(\n      handedness,\n      offsetPosition,\n      offsetQuaternion,\n    )\n    .then((hitTestTarget /* extends Object3D */) =\u003e {\n      hitTestTarget.add(\n        new Mesh(...),\n      );\n    });\n  ```\n\n- Alternatively, conduct hit-testing from viewer space:\n\n  ```js\n  ratk.createHitTestTargetFromViewerSpace(\n    offsetPosition,\n    offsetQuaternion,\n  ).then(...);\n  ```\n\n## Documentation\n\n- **API Reference**: [RATK API Documentation](https://meta-quest.github.io/reality-accelerator-toolkit).\n- **Example Application**: [Example WebXR Application](https://meta-quest.github.io/reality-accelerator-toolkit/example) ([Source Code](./example/)).\n\n## Contributing\n\nPlease read [CONTRIBUTING.md](./CONTRIBUTING.md) for details on how to contribute to the project.\n\n## License\n\nThis project is licensed under the MIT License - see the [LICENSE.md](./LICENSE.md) file for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmeta-quest%2Freality-accelerator-toolkit","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmeta-quest%2Freality-accelerator-toolkit","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmeta-quest%2Freality-accelerator-toolkit/lists"}