{"id":29788074,"url":"https://github.com/passeriform/three-tour-controls","last_synced_at":"2025-07-27T20:12:03.064Z","repository":{"id":289057897,"uuid":"969982089","full_name":"Passeriform/three-tour-controls","owner":"Passeriform","description":"Camera controller for navigating through a sequence of framed views with smooth scroll-based transitions.","archived":false,"fork":false,"pushed_at":"2025-06-29T13:08:26.000Z","size":174,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-06-29T13:11:19.761Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"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/Passeriform.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-04-21T09:01:50.000Z","updated_at":"2025-06-29T13:08:15.000Z","dependencies_parsed_at":"2025-04-21T10:35:14.994Z","dependency_job_id":null,"html_url":"https://github.com/Passeriform/three-tour-controls","commit_stats":null,"previous_names":["passeriform/three-tour-controls"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/Passeriform/three-tour-controls","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Passeriform%2Fthree-tour-controls","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Passeriform%2Fthree-tour-controls/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Passeriform%2Fthree-tour-controls/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Passeriform%2Fthree-tour-controls/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Passeriform","download_url":"https://codeload.github.com/Passeriform/three-tour-controls/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Passeriform%2Fthree-tour-controls/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":267417664,"owners_count":24083839,"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","status":"online","status_checked_at":"2025-07-27T02:00:11.917Z","response_time":82,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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":"2025-07-27T20:11:47.996Z","updated_at":"2025-07-27T20:12:03.053Z","avatar_url":"https://github.com/Passeriform.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# TourControls\n\n**TourControls** is a lightweight, customizable control for **Three.js** that allows you to navigate through a series of predefined \"poses\" using scroll events. This control provides an intuitive way to cycle through different camera positions or orientations in your 3D scene like a tour.\n\n## Installation\n\nYou can install TourControls via npm:\n\n```bash\nnpm install @passeriform/three-tour-controls\n```\n\nOr, if you use Yarn:\n\n```bash\nyarn add @passeriform/three-tour-controls\n```\n\n## Usage\n\nTo use **TourControls** in your Three.js project, follow these steps:\n\n### 1. Import TourControls\n\nFirst, make sure you import both **Three.js** and **TourControls**.\n\n```ts\nimport * as THREE from \"three\"\nimport TourControls from \"@passeriform/three-tour-controls\"\n```\n\n### 2. Set Up the Camera and Scene\n\nCreate a basic Three.js scene and camera.\n\n```ts\nconst scene = new THREE.Scene()\nconst camera = new THREE.PerspectiveCamera(75, window.innerWidth / window.innerHeight, 0.1, 1000)\nconst renderer = new THREE.WebGLRenderer()\ndocument.body.appendChild(renderer.domElement)\nrenderer.setSize(window.innerWidth, window.innerHeight)\n\n// Add some objects to your scene (optional)\nconst geometry = new THREE.BoxGeometry()\nconst material = new THREE.MeshBasicMaterial({ color: 0x00ff00 })\nconst cube = new THREE.Mesh(geometry, material)\nscene.add(cube)\n```\n\n### 3. Create Camera Poses\n\nDefine the poses you want to cycle through. Each pose consists of a position and a rotation (or orientation).\n\n```ts\nconst poses = [\n    {\n        position: new THREE.Vector3(10, 10, 10),\n        quaternion: new THREE.Quaternion().setFromEuler(new THREE.Euler(0, Math.PI / 4, 0)),\n    },\n    {\n        position: new THREE.Vector3(20, 10, 0),\n        quaternion: new THREE.Quaternion().setFromEuler(new THREE.Euler(0, Math.PI / 2, 0)),\n    },\n    {\n        position: new THREE.Vector3(0, 20, 10),\n        quaternion: new THREE.Quaternion().setFromEuler(new THREE.Euler(Math.PI / 4, 0, 0)),\n    },\n]\n```\n\n### 4. Initialize TourControls\n\nCreate and attach the `TourControls` instance to the camera. Pass in the array of predefined poses.\n\n```ts\nconst controls = new TourControls(camera, poses)\n\n// Timing of pose switching can be adjusted as required\ncontrols.timing = 1000 // Timing for the pose transition in milliseconds (optional) [default: 400]\n```\n\n### 5. Render Loop\n\nUse the animation loop to continuously update the camera and render the scene.\n\n```ts\nfunction animate() {\n    requestAnimationFrame(animate)\n\n    // Update the controls\n    controls.update()\n\n    // Render the scene from the camera's perspective\n    renderer.render(scene, camera)\n}\n\nanimate()\n```\n\n### 6. Handling Window Resize\n\nCamera aspect ratio is automatically updated when window is resized.\n\n### 7. Updating Poses\n\nUpdating poses automatically marks the first pose as active and transitions to it.\n\n```ts\nconst newPoses = [\n    {\n        position: new THREE.Vector3(0, 20, 10),\n        quaternion: new THREE.Quaternion().setFromEuler(new THREE.Euler(Math.PI / 4, 0, 0)),\n    },\n    {\n        position: new THREE.Vector3(10, 10, 10),\n        quaternion: new THREE.Quaternion().setFromEuler(new THREE.Euler(0, Math.PI / 4, 0)),\n    },\n    {\n        position: new THREE.Vector3(20, 10, 0),\n        quaternion: new THREE.Quaternion().setFromEuler(new THREE.Euler(0, Math.PI / 2, 0)),\n    },\n]\ncontrols.setPoses(newPoses)\n```\n\nIf you want to disable automatic animation when updating poses, set `transitionOnPoseChange` to `false`.\n**NOTE:** Setting this option may cause undesirable user experience in the tour and is thus not recommended.\n\n```ts\ncontrols.transitionOnPoseChange = false\ncontrols.setPoses(newPoses)\n```\n\n## API\n\n### `TourControls(camera: THREE.PerspectiveCamera, boundPoses: Array\u003c{ bounds: THREE.Box3, quaternion: THREE.Quaternion }\u003e, domElement?: HTMLElement)`\n\n- **camera**: The Three.js perspective camera you want to control.\n- **boundPoses**: An array of objects representing the different camera poses. Each object should have:\n    - `bounds`: The `THREE.Box3` bounding box for the pose.\n    - `quaternion`: The `THREE.Quaternion` rotation (or orientation) for the camera.\n- **domElement**: The HTML element to attach event listeners to (optional).\n\n### `controls.setPoses(poses: Array\u003c{ position: THREE.Vector3, quaternion: THREE.Quaternion }\u003e, boundSize?: THREE.Vector3)`\n\n- **poses**: An array of objects representing the different camera poses. Each object should have:\n    - `position`: The `THREE.Vector3` position for the camera.\n    - `quaternion`: The `THREE.Quaternion` rotation (or orientation) for the camera.\n- **boundSize**: The size of the bounding box for each pose (optional, default: `new THREE.Vector3(1, 1, 1)`).\n\n### `controls.setBoundPoses(boundPoses: Array\u003c{ bounds: THREE.Box3, quaternion: THREE.Quaternion }\u003e)`\n\n- **boundPoses**: An array of objects representing the different camera poses. Each object should have:\n    - `bounds`: The `THREE.Box3` bounding box for the pose.\n    - `quaternion`: The `THREE.Quaternion` rotation (or orientation) for the camera.\n\n### `controls.timing: number`\n\n- The speed of transition across poses in milliseconds. Default: `400`.\n\n### `controls.setCameraOffset(offset: number)`\n\n- Z-direction offset of camera from the given pose. This can be updated on runtime and will be used on the next transition.\n  Changing this property does not trigger a transition by itself. Default: `400`.\n\n### `controls.transitionOnPoseChange: boolean`\n\n- Whether to begin a transition when the poses are updated using `setPoses()` or `setBoundPoses()`. Default: `true`.\n\n### `controls.update(time?: number)`\n\n- Updates the internal tween animations. Call this in your render loop.\n\n### `controls.clear()`\n\n- Clears all animations and disposes of the controls.\n\n## Example\n\n```ts\nimport * as THREE from \"three\"\nimport TourControls from \"@passeriform/three-tour-controls\"\n\nconst scene = new THREE.Scene()\nconst camera = new THREE.PerspectiveCamera(75, window.innerWidth / window.innerHeight, 0.1, 1000)\nconst renderer = new THREE.WebGLRenderer()\ndocument.body.appendChild(renderer.domElement)\n\nconst poses = [\n    {\n        position: new THREE.Vector3(10, 10, 10),\n        quaternion: new THREE.Quaternion().setFromEuler(new THREE.Euler(0, Math.PI / 4, 0)),\n    },\n    {\n        position: new THREE.Vector3(20, 10, 0),\n        quaternion: new THREE.Quaternion().setFromEuler(new THREE.Euler(0, Math.PI / 2, 0)),\n    },\n    {\n        position: new THREE.Vector3(0, 20, 10),\n        quaternion: new THREE.Quaternion().setFromEuler(new THREE.Euler(Math.PI / 4, 0, 0)),\n    },\n]\n\nconst controls = new TourControls(camera, poses)\ncontrols.timing = 1000\n\nfunction animate() {\n    requestAnimationFrame(animate)\n    controls.update()\n    renderer.render(scene, camera)\n}\n\nanimate()\n\nwindow.addEventListener(\"resize\", () =\u003e {\n    renderer.setSize(window.innerWidth, window.innerHeight)\n})\n```\n\n## License\n\nMIT License. See [LICENSE](LICENSE) for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpasseriform%2Fthree-tour-controls","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpasseriform%2Fthree-tour-controls","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpasseriform%2Fthree-tour-controls/lists"}