{"id":29544710,"url":"https://github.com/ratwolfzero/quaternion_3d_rotation","last_synced_at":"2025-07-17T15:38:00.076Z","repository":{"id":294557686,"uuid":"982166759","full_name":"ratwolfzero/Quaternion_3D_Rotation","owner":"ratwolfzero","description":"Quaternion 3D Rotation: A Gimbal-Lock-Free Solution","archived":false,"fork":false,"pushed_at":"2025-05-29T04:48:08.000Z","size":8660,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-05-29T05:18:32.763Z","etag":null,"topics":["3d-rotation","euler-angles","gimbal-lock","quaternions","quaternions-and-rotations","slerp","spatial-rotations","unit-quaternion"],"latest_commit_sha":null,"homepage":"https://github.com/ratwolfzero/Quaternion_3D_Rotation","language":"Python","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/ratwolfzero.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-05-12T13:24:45.000Z","updated_at":"2025-05-29T04:48:11.000Z","dependencies_parsed_at":"2025-05-26T00:30:55.154Z","dependency_job_id":null,"html_url":"https://github.com/ratwolfzero/Quaternion_3D_Rotation","commit_stats":null,"previous_names":["ratwolfzero/quaternion_3d_rotation"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/ratwolfzero/Quaternion_3D_Rotation","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ratwolfzero%2FQuaternion_3D_Rotation","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ratwolfzero%2FQuaternion_3D_Rotation/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ratwolfzero%2FQuaternion_3D_Rotation/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ratwolfzero%2FQuaternion_3D_Rotation/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ratwolfzero","download_url":"https://codeload.github.com/ratwolfzero/Quaternion_3D_Rotation/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ratwolfzero%2FQuaternion_3D_Rotation/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":265623415,"owners_count":23800160,"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":["3d-rotation","euler-angles","gimbal-lock","quaternions","quaternions-and-rotations","slerp","spatial-rotations","unit-quaternion"],"created_at":"2025-07-17T15:37:57.188Z","updated_at":"2025-07-17T15:38:00.059Z","avatar_url":"https://github.com/ratwolfzero.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# 🔄 Quaternion 3D Rotation: A Gimbal-Lock-Free Solution\n\nA visualization of smooth 3D rotations using quaternion math\n\n![Quaternion-Rotation](quaternion_rotation.gif)\n\n## 📌 What It Does\n\n* Animates three orthogonal rings (XY, YZ, XZ planes)\n* Applies a continuously changing rotation using **quaternions** around the X, Y, and Z axes\n* Demonstrates how quaternion multiplication preserves smooth orientation updates, avoiding gimbal lock\n\n## 🧠 Why Quaternions?\n\nQuaternions outperform Euler angles in 3D rotations because they:\n\n* Avoid gimbal lock (no sudden alignment of axes)\n* Support smooth interpolation between orientations (e.g., via SLERP, when needed)\n* Are numerically stable for long-duration animations\n\nThis animation uses a combined rotation in the order Z × Y × X, showcasing seamless transitions through direct quaternion multiplication.\n\n## 📜 Historical Context\n\n### Hamilton's Breakthrough (1843)\n\nWilliam Rowan Hamilton, an Irish mathematician, was both formally educated at Trinity College Dublin and largely self-taught, combining his academic studies with a deep personal passion for mathematics. This self-directed approach led him to discover quaternions while attempting to generalize complex numbers  \n(which take the form a + bi, where i² = −1) into triplets of the form a + bi + cj. Though this seemed a natural extension from two to three dimensions, he found that consistent multiplication rules were impossible to define.\n\nHis breakthrough came on October 16, 1843, while walking near Dublin’s Broom Bridge, when he abandoned the assumption of commutativity and consequently introduced four terms. By defining ij = k and ji = −k as the product of the first two imaginary units, he created quaternions of the form:\n\n$$a + bi + cj + dk$$\n\ngoverned by the relations:\n\n$$i^2 = j^2 = k^2 = ijk = -1$$\n\nThese fundamental relations lead to the non-commutative multiplication rules:\n\n$$\n\\begin{aligned}\nij \u0026= k, \u0026 ji \u0026= -k, \\\\\njk \u0026= i, \u0026 kj \u0026= -i, \\\\\nki \u0026= j, \u0026 ik \u0026= -j\n\\end{aligned}\n$$\n\nThis solution preserved algebraic consistency at the cost of commutativity — making quaternions mathematics’ first successful extension of complex numbers into higher dimensions.  \n\nInitially used in physics (e.g., in early formulations of Maxwell’s electromagnetism), quaternions were later eclipsed by the vector calculus of Gibbs and Heaviside for its relative simplicity.  \n\n## 20th-Century Revival\n\nTheir 20th-century revival cemented their role in:\n\n* 🚀 Aerospace (attitude control)\n* 🤖 Robotics (orientation interpolation)\n* 🎮 Computer graphics (camera rotations)\n\n---\n\n## 🔢 Quaternion Definition\n\nA quaternion is a **4D hypercomplex number**:\n\n$$ \\mathbf{q} = w + xi + yj + zk \\quad \\text{or} \\quad \\mathbf{q} = (w, \\mathbf{v}) $$\n\nwhere:\n\n* **Scalar part**: $w$ (real component)\n* **Vector part**: $\\mathbf{v} = (x, y, z)$ (imaginary components)\n\n### 🔧 Key Properties\n\n1. **Multiplication Rules**\n   * **Non-commutative**: $\\mathbf{p}\\mathbf{q} \\neq \\mathbf{q}\\mathbf{p}$ → order matters\n   * **Associative**: $(\\mathbf{p}\\mathbf{q})\\mathbf{r} = \\mathbf{p}(\\mathbf{q}\\mathbf{r})$ → stable chaining\n\n2. **Rotation Encoding**\n\nA **unit quaternion** (\\$|\\mathbf{q}| = 1\\$) encodes a rotation by angle \\$\\theta\\$ around axis\n\n\\$\\mathbf{u} = (u\\_x, u\\_y, u\\_z)\\$ where (\\$|\\mathbf{u}| = 1\\$) as:\n\n$\\mathbf{q} = \\cos\\left(\\frac{\\theta}{2}\\right) + \\sin\\left(\\frac{\\theta}{2}\\right)(u_x i + u_y j + u_z k)$\n\nThe \\$\\theta/2\\$ term ensures correct rotational composition (via quaternion multiplication).  \n\nWhile **SLERP** (Spherical Linear Interpolation) is often used to interpolate smoothly between two orientations — such as keyframes in animation or robotic motion planning — it is not used here, since this animation uses continuous incremental rotation updates.\n\nSLERP Note:\n\nSLERP smoothly interpolates between quaternions along the shortest 4D arc.  \n\nDue to the double-covering property (where q and −q represent the same 3D rotation), SLERP ensures the shortest path by negating one quaternion if their dot product is negative.  \n\n---\n\n## 🛠️ Requirements\n\n```bash\npip install numpy matplotlib numpy-quaternion\n```\n\n\u003e Note: `numpy-quaternion` is a separate package from NumPy.\n\n---\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fratwolfzero%2Fquaternion_3d_rotation","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fratwolfzero%2Fquaternion_3d_rotation","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fratwolfzero%2Fquaternion_3d_rotation/lists"}