{"id":13676011,"url":"https://github.com/moble/quaternion","last_synced_at":"2025-05-14T04:00:39.594Z","repository":{"id":24491260,"uuid":"27896013","full_name":"moble/quaternion","owner":"moble","description":"Add built-in support for quaternions to numpy","archived":false,"fork":false,"pushed_at":"2025-04-01T04:10:43.000Z","size":986,"stargazers_count":626,"open_issues_count":10,"forks_count":86,"subscribers_count":22,"default_branch":"main","last_synced_at":"2025-04-06T00:15:38.980Z","etag":null,"topics":["math","numpy","physics","python","quaternion","robotics"],"latest_commit_sha":null,"homepage":"","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/moble.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}},"created_at":"2014-12-11T22:59:41.000Z","updated_at":"2025-04-01T04:10:47.000Z","dependencies_parsed_at":"2022-07-12T20:30:29.647Z","dependency_job_id":"cf7e0844-e4c5-46c6-ac5f-650fd3767fd6","html_url":"https://github.com/moble/quaternion","commit_stats":{"total_commits":643,"total_committers":24,"mean_commits":"26.791666666666668","dds":"0.15241057542768277","last_synced_commit":"0b198227fee6ff94af5fb401ec89bfbd4dd3ef60"},"previous_names":[],"tags_count":38,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/moble%2Fquaternion","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/moble%2Fquaternion/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/moble%2Fquaternion/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/moble%2Fquaternion/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/moble","download_url":"https://codeload.github.com/moble/quaternion/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248281416,"owners_count":21077423,"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":["math","numpy","physics","python","quaternion","robotics"],"created_at":"2024-08-02T12:01:08.655Z","updated_at":"2025-04-10T19:35:49.354Z","avatar_url":"https://github.com/moble.png","language":"Python","readme":"[![Test Status](https://github.com/moble/quaternion/workflows/tests/badge.svg)](https://github.com/moble/quaternion/actions)\n[![Documentation Status](https://readthedocs.org/projects/quaternion/badge/?version=latest)](https://quaternion.readthedocs.io/en/latest/?badge=latest)\n[![PyPI Version](https://img.shields.io/pypi/v/numpy-quaternion?color=)](https://pypi.org/project/numpy-quaternion/)\n[![Conda Version](https://img.shields.io/conda/vn/conda-forge/quaternion.svg?color=)](https://anaconda.org/conda-forge/quaternion)\n[![MIT License](https://img.shields.io/github/license/moble/quaternion.svg)](https://github.com/moble/quaternion/blob/main/LICENSE)\n[![DOI](https://zenodo.org/badge/27896013.svg)](https://zenodo.org/badge/latestdoi/27896013)\n\n\n# Quaternions in numpy\n\nThis Python module adds a quaternion dtype to NumPy.\n\nThe code was originally based on [code by Martin\nLing](https://github.com/martinling/numpy_quaternion) (which he wrote\nwith help from Mark Wiebe), but was rewritten with ideas from\n[rational](https://github.com/numpy/numpy-dtypes/tree/master/npytypes/rational)\nto work with newer python versions (and to fix a few bugs), and\n*greatly* expands the applications of quaternions.\n\nSee also the pure-python package\n[quaternionic](https://github.com/moble/quaternionic).\n\n## Quickstart\n\n```sh\nconda install -c conda-forge quaternion\n```\n\nor\n\n```sh\npython -m pip install --upgrade --force-reinstall numpy-quaternion\n```\n\nOptionally add `--user` after `install` in the second command if\nyou're not using a python environment — though you should start.\n\n\n## Installation\n\nAssuming you use `conda` to manage your python installation (which is\ncurrently the preferred choice for science and engineering with\npython), you can install this package simply as\n\n```sh\nconda install -c conda-forge quaternion\n```\n\nIf you prefer to use `pip`, you can instead do\n\n```sh\npython -m pip install --upgrade --force-reinstall numpy-quaternion\n```\n\n(See [here](https://snarky.ca/why-you-should-use-python-m-pip/) for a\nveteran python core contributor's explanation of why you should always\nuse `python -m pip` instead of just `pip` or `pip3`.)  The `--upgrade\n--force-reinstall` options are not always necessary, but will ensure\nthat pip will update numpy if it has to.\n\nIf you refuse to use `conda`, you might want to install inside your\nhome directory without root privileges.  (Conda does this by default\nanyway.)  This is done by adding `--user` to the above command:\n\n```sh\npython -m pip install --user --upgrade --force-reinstall numpy-quaternion\n```\n\nNote that pip will attempt to compile the code — which requires a\nworking `C` compiler.\n\nFinally, there's also the fully manual option of just downloading the\ncode, changing to the code directory, and running\n\n```sh\npython -m pip install --upgrade --force-reinstall .\n```\n\nThis should work regardless of the installation method, as long as you\nhave a compiler hanging around.\n\n\n## Basic usage\n\nThe full documentation can be found on [Read the\nDocs](https://quaternion.readthedocs.io/), and most functions have\ndocstrings that should explain the relevant points.  The following are\nmostly for the purposes of example.\n\n```python\n\u003e\u003e\u003e import numpy as np\n\u003e\u003e\u003e import quaternion\n\u003e\u003e\u003e np.quaternion(1,0,0,0)\nquaternion(1, 0, 0, 0)\n\u003e\u003e\u003e q1 = np.quaternion(1,2,3,4)\n\u003e\u003e\u003e q2 = np.quaternion(5,6,7,8)\n\u003e\u003e\u003e q1 * q2\nquaternion(-60, 12, 30, 24)\n\u003e\u003e\u003e a = np.array([q1, q2])\n\u003e\u003e\u003e a\narray([quaternion(1, 2, 3, 4), quaternion(5, 6, 7, 8)], dtype=quaternion)\n\u003e\u003e\u003e np.exp(a)\narray([quaternion(1.69392, -0.78956, -1.18434, -1.57912),\n       quaternion(138.909, -25.6861, -29.9671, -34.2481)], dtype=quaternion)\n```\n\nNote that this package represents a quaternion as a scalar, followed\nby the `x` component of the vector part, followed by `y`, followed by\n`z`.  These components can be accessed directly:\n```python\n\u003e\u003e\u003e q1.w, q1.x, q1.y, q1.z\n(1.0, 2.0, 3.0, 4.0)\n```\nHowever, this only works on an individual `quaternion`; for arrays it\nis better to use \"vectorized\" operations like `as_float_array`.\n\nThe following ufuncs are implemented (which means they run fast on\nnumpy arrays):\n```python\nadd, subtract, multiply, divide, log, exp, power, negative, conjugate,\ncopysign, equal, not_equal, less, less_equal, isnan, isinf, isfinite, absolute\n```\n\nQuaternion components are stored as double-precision floating point\nnumbers — `float`s, in python language, or `float64` in more precise\nnumpy language.  Numpy arrays with `dtype=quaternion` can be accessed\nas arrays of doubles without any (slow, memory-consuming) copying of\ndata; rather, a `view` of the exact same memory space can be created\nwithin a microsecond, regardless of the shape or size of the\nquaternion array.\n\nComparison operations follow the same lexicographic ordering as\ntuples.\n\nThe unary tests isnan and isinf return true if they would return true\nfor any individual component; isfinite returns true if it would return\ntrue for all components.\n\nReal types may be cast to quaternions, giving quaternions with zero\nfor all three imaginary components. Complex types may also be cast to\nquaternions, with their single imaginary component becoming the first\nimaginary component of the quaternion. Quaternions may not be cast to\nreal or complex types.\n\nSeveral array-conversion functions are also included.  For example, to\nconvert an Nx4 array of floats to an N-dimensional array of\nquaternions, use `as_quat_array`:\n```python\n\u003e\u003e\u003e import numpy as np\n\u003e\u003e\u003e import quaternion\n\u003e\u003e\u003e a = np.random.rand(7, 4)\n\u003e\u003e\u003e a\narray([[ 0.93138726,  0.46972279,  0.18706385,  0.86605021],\n       [ 0.70633523,  0.69982741,  0.93303559,  0.61440879],\n       [ 0.79334456,  0.65912598,  0.0711557 ,  0.46622885],\n       [ 0.88185987,  0.9391296 ,  0.73670503,  0.27115149],\n       [ 0.49176628,  0.56688076,  0.13216632,  0.33309146],\n       [ 0.11951624,  0.86804078,  0.77968826,  0.37229404],\n       [ 0.33187593,  0.53391165,  0.8577846 ,  0.18336855]])\n\u003e\u003e\u003e qs = quaternion.as_quat_array(a)\n\u003e\u003e\u003e qs\narray([ quaternion(0.931387262880247, 0.469722787598354, 0.187063852060487, 0.866050210100621),\n       quaternion(0.706335233363319, 0.69982740767353, 0.933035590130247, 0.614408786768725),\n       quaternion(0.793344561317281, 0.659125976566815, 0.0711557025000925, 0.466228847713644),\n       quaternion(0.881859869074069, 0.939129602918467, 0.736705031709562, 0.271151494174001),\n       quaternion(0.491766284854505, 0.566880763189927, 0.132166320200012, 0.333091463422536),\n       quaternion(0.119516238634238, 0.86804077992676, 0.779688263524229, 0.372294043850009),\n       quaternion(0.331875925159073, 0.533911652483908, 0.857784598617977, 0.183368547490701)], dtype=quaternion)\n```\n[Note that quaternions are printed with full precision, unlike floats,\nwhich is why you see extra digits above.  But the actual data is\nidentical in the two cases.]  To convert an N-dimensional array of\nquaternions to an Nx4 array of floats, use `as_float_array`:\n```python\n\u003e\u003e\u003e b = quaternion.as_float_array(qs)\n\u003e\u003e\u003e b\narray([[ 0.93138726,  0.46972279,  0.18706385,  0.86605021],\n       [ 0.70633523,  0.69982741,  0.93303559,  0.61440879],\n       [ 0.79334456,  0.65912598,  0.0711557 ,  0.46622885],\n       [ 0.88185987,  0.9391296 ,  0.73670503,  0.27115149],\n       [ 0.49176628,  0.56688076,  0.13216632,  0.33309146],\n       [ 0.11951624,  0.86804078,  0.77968826,  0.37229404],\n       [ 0.33187593,  0.53391165,  0.8577846 ,  0.18336855]])\n```\n\nIt is also possible to convert a quaternion to or from a 3x3 array of\nfloats representing a rotation matrix, or an array of N quaternions to\nor from an Nx3x3 array of floats representing N rotation matrices,\nusing `as_rotation_matrix` and `from_rotation_matrix`.  Similar\nconversions are possible for rotation vectors using\n`as_rotation_vector` and `from_rotation_vector`, and for spherical\ncoordinates using `as_spherical_coords` and `from_spherical_coords`.\nFinally, it is possible to derive the Euler angles from a quaternion\nusing `as_euler_angles`, or create a quaternion from Euler angles\nusing `from_euler_angles` — though be aware that Euler angles are\nbasically the worst things\never.\u003csup\u003e[1](#1-euler-angles-are-awful)\u003c/sup\u003e Before you complain\nabout those functions using something other than your favorite\nconventions, please read [this\npage](https://github.com/moble/quaternion/wiki/Euler-angles-are-horrible).\n\n\n## Dependencies\n\nWith the standard installation methods, hopefully you won't need to\nworry about dependencies directly.  But in case you do, here's what\nyou need to know.\n\nThe basic requirements for this code are reasonably current versions\nof `python` and `numpy`.  In particular, `python` versions 3.10\nthrough 3.13 are routinely tested.  Because of its crucial dependence\non `numpy`, this package can only support versions of `python` that\nare directly supported by `numpy` — which limits support to releases\nfrom the past few years.  Old versions of `python` will work with\n*older* versions of this package, which are still available from PyPI\nand conda-forge.  Some older versions of `python` may still work with\nnewer versions of this package, but your mileage may vary.\n\nHowever, certain advanced functions in this package (including\n`squad`, `mean_rotor_in_intrinsic_metric`,\n`integrate_angular_velocity`, and related functions) require\n[`scipy`](http://scipy.org/) and can automatically use\n[`numba`](http://numba.pydata.org/).  `Scipy` is a standard python\npackage for scientific computation, and implements interfaces to C and\nFortran codes for optimization (among other things) need for finding\nmean and optimal rotors.  `Numba` uses [LLVM](http://llvm.org/) to\ncompile python code to machine code, accelerating many numerical\nfunctions by factors of anywhere from 2 to 2000.  It is *possible* to\nrun all the code without `numba`, but these particular functions can\nbe anywhere from 4 to 400 times slower without it.\n\nBoth `scipy` and `numba` can be installed with `pip` or `conda`.\nHowever, because `conda` is specifically geared toward scientific\npython, it is generally more robust for these more complicated\npackages.  In fact, the main\n[`anaconda`](https://www.anaconda.com/products/individual) package\ncomes with both `numba` and `scipy`.  If you prefer the smaller\ndownload size of [`miniconda`](http://conda.pydata.org/miniconda.html)\n(which comes with minimal extras), you'll also have to run this\ncommand:\n\n```sh\nconda install numpy scipy numba\n```\n\n\n## Bug reports and feature requests\n\nBug reports and feature requests are entirely welcome (with [very few\nexceptions](https://github.com/moble/quaternion/wiki/Euler-angles-are-horrible#opening-issues-and-pull-requests)).\nThe best way to do this is to open an [issue on this code's github\npage](https://github.com/moble/quaternion/issues).  For bug reports,\nplease try to include a minimal working example demonstrating the\nproblem.\n\n[Pull requests](https://help.github.com/articles/using-pull-requests/)\nare also entirely welcome, of course, if you have an idea where the\ncode is going wrong, or have an idea for a new feature that you know\nhow to implement.\n\nThis code is routinely tested on recent versions of both python (3.8\nthough 3.11) and numpy (\u003e=1.13).  But the test coverage is not\nnecessarily as complete as it could be, so bugs may certainly be\npresent, especially in the higher-level functions like\n`mean_rotor_...`.\n\n\n## Acknowledgments\n\nThis code is, of course, hosted on github.  Because it is an\nopen-source project, the hosting is free, and all the wonderful\nfeatures of github are available, including free wiki space and web\npage hosting, pull requests, a nice interface to the git logs, etc.\nGithub user Hannes Ovrén (hovren) pointed out some errors in a\nprevious version of this code and suggested some nice utility\nfunctions for rotation matrices, etc.  Github user Stijn van Drongelen\n(rhymoid) contributed some code that makes compilation work with\nMSVC++.  Github user Jon Long (longjon) has provided some elegant\ncontributions to substantially improve several tricky parts of this\ncode.  Rebecca Turner (9999years) and Leo Stein (duetosymmetry) did\nall the work in getting the documentation onto [Read the\nDocs](https://quaternion.readthedocs.io/).\n\nEvery change in this code is [automatically\ntested](https://github.com/moble/quaternion/actions) on Github\nActions.  The code is downloaded and installed fresh each time, and\nthen tested, on each of the different supported versions of python, on\neach of the supported platforms.  This ensures that no change I make\nto the code breaks either installation or any of the features that I\nhave written tests for.  Github Actions also automatically builds the\n`pip` versions of the code hosted on\n[pypi](https://pypi.python.org/pypi/numpy-quaternion).  Conda-forge\nalso uses Github Actions to build [the conda/mamba\nversion](https://github.com/conda-forge/quaternion-feedstock) hosted\non [anaconda.org](https://anaconda.org/conda-forge/quaternion).  These\nare all free services for open-source projects like this one.\n\nThe work of creating this code was supported in part by the Sherman\nFairchild Foundation and by NSF Grants No. PHY-1306125 and\nAST-1333129.\n\n\n\n\n\u003cbr/\u003e\n\n---\n\n###### \u003csup\u003e1\u003c/sup\u003e Euler angles are awful\n\nEuler angles are pretty much [the worst things\never](https://moble.github.io/spherical_functions/#euler-angles) and it\nmakes me feel bad even supporting them.  Quaternions are faster, more\naccurate, basically free of singularities, more intuitive, and\ngenerally easier to understand.  You can work entirely without Euler\nangles (I certainly do).  You absolutely never need them.  But if\nyou really can't give them up, they are mildly supported.\n","funding_links":[],"categories":["Computations","Resources"],"sub_categories":["Synthetic Data","NLP","Others"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmoble%2Fquaternion","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmoble%2Fquaternion","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmoble%2Fquaternion/lists"}