=====
rowan
=====
.. contents::
:local:
|ReadTheDocs|
|CircleCI|
|Codecov|
|PyPI|
|Codacy|
|Zenodo|
|JOSS|
.. |ReadTheDocs| image:: https://readthedocs.org/projects/rowan/badge/?version=latest
:target: http://rowan.readthedocs.io/en/latest/?badge=latest
.. |CircleCI| image:: https://circleci.com/gh/glotzerlab/rowan.svg?style=svg
:target: https://circleci.com/gh/glotzerlab/rowan
.. |Codecov| image:: https://codecov.io/gh/glotzerlab/rowan/branch/master/graph/badge.svg
:target: https://codecov.io/gh/glotzerlab/rowan
.. |PyPI| image:: https://img.shields.io/pypi/v/rowan.svg
:target: https://pypi.org/project/rowan/
.. |Codacy| image:: https://api.codacy.com/project/badge/Grade/2ff6c23cb9be4f77827428a87e0e9cfc
:target: https://www.codacy.com/app/vramasub/rowan?utm_source=github.com&utm_medium=referral&utm_content=glotzerlab/rowan&utm_campaign=Badge_Grade
.. |Zenodo| image:: https://zenodo.org/badge/DOI/10.5281/zenodo.1323676.svg
:target: https://doi.org/10.5281/zenodo.1323676
.. |JOSS| image:: http://joss.theoj.org/papers/10.21105/joss.00787/status.svg
:target: https://doi.org/10.21105/joss.00787
Welcome to the documentation for rowan, a package for working with quaternions!
Quaternions, which form a number system with various interesting properties, were originally developed for classical mechanics.
Although they have since been largely displaced from this application by vector mathematics, they have become a standard method of representing rotations in three dimensions.
Quaternions are now commonly used for this purpose in various fields, including computer graphics and attitude control.
The package is built entirely on top of NumPy and represents quaternions using NumPy arrays, meaning that all functions support arbitrarily high-dimensional arrays of quaternions.
Quaternions are encoded as arrays of shape `(..., 4)`, with the convention that the final dimension of an array `(a, b, c, d)` represents the quaternion `a + bi + cj + dk`.
This package provides tools for standard algebraic operations on quaternions as well as a number of additional tools for *e.g.* measuring distances between quaternions, interpolating between them, and performing basic point-cloud mapping.
A particular focus of the rowan package is working with unit quaternions, which are a popular means of representing rotations in 3D.
In order to provide a unified framework for working with the various rotation formalisms in 3D, rowan allows easy interconversion between these formalisms.
Core features of rowan include (but are not limited to):
* Algebra (multiplication, exponentiation, etc).
* Derivatives and integrals of quaternions.
* Rotation and reflection operations, with conversions to and from matrices, axis angles, etc.
* Various distance metrics for quaternions.
* Basic point set registration, including solutions of the Procrustes problem
and the Iterative Closest Point algorithm.
* Quaternion interpolation (slerp, squad).
Getting Started
===============
Installation
------------
The recommended methods for installing rowan are using **pip** or **conda**.
To install the package from PyPI, execute:
.. code-block:: bash
$ pip install rowan --user
To install the package from conda, first add the **conda-forge** channel and
then install rowan:
.. code-block:: bash
$ conda config --add channels conda-forge
$ conda install rowan
If you wish, you may also install rowan by cloning `the repository <https://github.com/glotzerlab/rowan>`_ and running the setup script:
.. code-block:: bash
$ git clone https://github.com/glotzerlab/rowan.git
$ cd rowan
$ python setup.py install --user
The minimum requirements for using rowan are:
* Python >= 3.6
* NumPy >= 1.15
Quickstart
----------
This library can be used to work with quaternions by simply instantiating the appropriate NumPy arrays and passing them to the required functions.
For example:
.. code-block:: python
import rowan
import numpy as np
one = np.array([10, 0, 0, 0])
one_unit = rowan.normalize(one)
assert(np.all(one_unit == np.array([1, 0, 0, 0])))
if not np.all(one_unit == rowan.multiply(one_unit, one_unit)):
raise RuntimeError("Multiplication failed!")
one_vec = np.array([1, 0, 0])
rotated_vector = rowan.rotate(one_unit, one_vec)
mat = np.eye(3)
quat_rotate = rowan.from_matrix(mat)
alpha, beta, gamma = rowan.to_euler(quat_rotate)
quat_rotate_returned = rowan.from_euler(alpha, beta, gamma)
identity = rowan.to_matrix(quat_rotate_returned)
Running Tests
-------------
The package is currently tested for Python >= 3.6 on Unix-like systems.
Continuous integrated testing is performed using CircleCI on these Python versions with NumPy versions 1.15 and above.
To run the packaged unit tests, execute the following line from the root of the repository:
.. code-block:: bash
python -m unittest discover tests
To check test coverage, make sure the coverage module is installed:
.. code-block:: bash
pip install coverage
and then run the packaged unit tests with the coverage module:
.. code-block:: bash
coverage run -m unittest discover tests
Running Benchmarks
------------------
Benchmarks for the package are contained in a Jupyter notebook in the `benchmarks` folder in the root of the repository.
If you do not have or do not wish to use the notebook format, an equivalent Benchmarks.py script is also included.
The benchmarks compare rowan to two alternative packages, so you will need to install ``pyquaternion`` and ``numpy_quaternion`` if you wish to see those comparisons.
Building Documentation
----------------------
You can also build this documentation from source if you clone the repository.
The documentation is written in `reStructuredText <http://docutils.sourceforge.net/rst.html>`_ and compiled using `Sphinx <http://www.sphinx-doc.org/en/master/>`_.
To build from source, first install Sphinx:
.. code-block:: bash
pip install sphinx sphinx_rtd_theme
You can then use Sphinx to create the actual documentation in either PDF or HTML form by running the following commands in the rowan root directory:
.. code-block:: bash
cd doc
make html # For html output
make latexpdf # For a LaTeX compiled PDF file
open build/html/index.html
Support and Contribution
========================
This package is hosted on `GitHub <https://github.com/glotzerlab/rowan>`_.
Please report any bugs or problems that you find on the `issue tracker <https://github.com/glotzerlab/rowan/issues>`_.
All contributions to rowan are welcomed via pull requests!
Please see the `development guide <https://rowan.readthedocs.io/en/latest/development.html>`_ for more information on requirements for new code.
Raw data
{
"_id": null,
"home_page": "https://github.com/glotzerlab/rowan",
"name": "rowan",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.6, <4",
"maintainer_email": "",
"keywords": "",
"author": "Vyas Ramasubramani",
"author_email": "vramasub@umich.edu",
"download_url": "https://files.pythonhosted.org/packages/9f/01/628d3be02e29d39d51945dafe9e3893a38db7a0bf1a80caae4b596065c53/rowan-1.3.0.post1.tar.gz",
"platform": "",
"description": "=====\nrowan\n=====\n\n.. contents::\n :local:\n\n|ReadTheDocs|\n|CircleCI|\n|Codecov|\n|PyPI|\n|Codacy|\n|Zenodo|\n|JOSS|\n\n.. |ReadTheDocs| image:: https://readthedocs.org/projects/rowan/badge/?version=latest\n :target: http://rowan.readthedocs.io/en/latest/?badge=latest\n.. |CircleCI| image:: https://circleci.com/gh/glotzerlab/rowan.svg?style=svg\n :target: https://circleci.com/gh/glotzerlab/rowan\n.. |Codecov| image:: https://codecov.io/gh/glotzerlab/rowan/branch/master/graph/badge.svg\n :target: https://codecov.io/gh/glotzerlab/rowan\n.. |PyPI| image:: https://img.shields.io/pypi/v/rowan.svg\n :target: https://pypi.org/project/rowan/\n.. |Codacy| image:: https://api.codacy.com/project/badge/Grade/2ff6c23cb9be4f77827428a87e0e9cfc\n :target: https://www.codacy.com/app/vramasub/rowan?utm_source=github.com&utm_medium=referral&utm_content=glotzerlab/rowan&utm_campaign=Badge_Grade\n.. |Zenodo| image:: https://zenodo.org/badge/DOI/10.5281/zenodo.1323676.svg\n :target: https://doi.org/10.5281/zenodo.1323676\n.. |JOSS| image:: http://joss.theoj.org/papers/10.21105/joss.00787/status.svg\n :target: https://doi.org/10.21105/joss.00787\n\nWelcome to the documentation for rowan, a package for working with quaternions!\nQuaternions, which form a number system with various interesting properties, were originally developed for classical mechanics.\nAlthough they have since been largely displaced from this application by vector mathematics, they have become a standard method of representing rotations in three dimensions.\nQuaternions are now commonly used for this purpose in various fields, including computer graphics and attitude control.\n\nThe package is built entirely on top of NumPy and represents quaternions using NumPy arrays, meaning that all functions support arbitrarily high-dimensional arrays of quaternions.\nQuaternions are encoded as arrays of shape `(..., 4)`, with the convention that the final dimension of an array `(a, b, c, d)` represents the quaternion `a + bi + cj + dk`.\nThis package provides tools for standard algebraic operations on quaternions as well as a number of additional tools for *e.g.* measuring distances between quaternions, interpolating between them, and performing basic point-cloud mapping.\nA particular focus of the rowan package is working with unit quaternions, which are a popular means of representing rotations in 3D.\nIn order to provide a unified framework for working with the various rotation formalisms in 3D, rowan allows easy interconversion between these formalisms.\n\nCore features of rowan include (but are not limited to):\n\n* Algebra (multiplication, exponentiation, etc).\n* Derivatives and integrals of quaternions.\n* Rotation and reflection operations, with conversions to and from matrices, axis angles, etc.\n* Various distance metrics for quaternions.\n* Basic point set registration, including solutions of the Procrustes problem\n and the Iterative Closest Point algorithm.\n* Quaternion interpolation (slerp, squad).\n\nGetting Started\n===============\n\nInstallation\n------------\n\nThe recommended methods for installing rowan are using **pip** or **conda**.\nTo install the package from PyPI, execute:\n\n.. code-block:: bash\n\n $ pip install rowan --user\n\nTo install the package from conda, first add the **conda-forge** channel and\nthen install rowan:\n\n.. code-block:: bash\n\n $ conda config --add channels conda-forge\n $ conda install rowan\n\n\nIf you wish, you may also install rowan by cloning `the repository <https://github.com/glotzerlab/rowan>`_ and running the setup script:\n\n.. code-block:: bash\n\n $ git clone https://github.com/glotzerlab/rowan.git\n $ cd rowan\n $ python setup.py install --user\n\nThe minimum requirements for using rowan are:\n\n* Python >= 3.6\n* NumPy >= 1.15\n\nQuickstart\n----------\n\nThis library can be used to work with quaternions by simply instantiating the appropriate NumPy arrays and passing them to the required functions.\nFor example:\n\n.. code-block:: python\n\n import rowan\n import numpy as np\n one = np.array([10, 0, 0, 0])\n one_unit = rowan.normalize(one)\n assert(np.all(one_unit == np.array([1, 0, 0, 0])))\n if not np.all(one_unit == rowan.multiply(one_unit, one_unit)):\n raise RuntimeError(\"Multiplication failed!\")\n\n one_vec = np.array([1, 0, 0])\n rotated_vector = rowan.rotate(one_unit, one_vec)\n\n mat = np.eye(3)\n quat_rotate = rowan.from_matrix(mat)\n alpha, beta, gamma = rowan.to_euler(quat_rotate)\n quat_rotate_returned = rowan.from_euler(alpha, beta, gamma)\n identity = rowan.to_matrix(quat_rotate_returned)\n\nRunning Tests\n-------------\n\nThe package is currently tested for Python >= 3.6 on Unix-like systems.\nContinuous integrated testing is performed using CircleCI on these Python versions with NumPy versions 1.15 and above.\n\nTo run the packaged unit tests, execute the following line from the root of the repository:\n\n.. code-block:: bash\n\n python -m unittest discover tests\n\nTo check test coverage, make sure the coverage module is installed:\n\n.. code-block:: bash\n\n pip install coverage\n\nand then run the packaged unit tests with the coverage module:\n\n.. code-block:: bash\n\n coverage run -m unittest discover tests\n\nRunning Benchmarks\n------------------\nBenchmarks for the package are contained in a Jupyter notebook in the `benchmarks` folder in the root of the repository.\nIf you do not have or do not wish to use the notebook format, an equivalent Benchmarks.py script is also included.\nThe benchmarks compare rowan to two alternative packages, so you will need to install ``pyquaternion`` and ``numpy_quaternion`` if you wish to see those comparisons.\n\nBuilding Documentation\n----------------------\n\nYou can also build this documentation from source if you clone the repository.\nThe documentation is written in `reStructuredText <http://docutils.sourceforge.net/rst.html>`_ and compiled using `Sphinx <http://www.sphinx-doc.org/en/master/>`_.\nTo build from source, first install Sphinx:\n\n.. code-block:: bash\n\n pip install sphinx sphinx_rtd_theme\n\nYou can then use Sphinx to create the actual documentation in either PDF or HTML form by running the following commands in the rowan root directory:\n\n.. code-block:: bash\n\n cd doc\n make html # For html output\n make latexpdf # For a LaTeX compiled PDF file\n open build/html/index.html\n\nSupport and Contribution\n========================\n\nThis package is hosted on `GitHub <https://github.com/glotzerlab/rowan>`_.\nPlease report any bugs or problems that you find on the `issue tracker <https://github.com/glotzerlab/rowan/issues>`_.\n\nAll contributions to rowan are welcomed via pull requests!\nPlease see the `development guide <https://rowan.readthedocs.io/en/latest/development.html>`_ for more information on requirements for new code.\n\n\n",
"bugtrack_url": null,
"license": "",
"summary": "Perform quaternion operations using NumPy arrays",
"version": "1.3.0.post1",
"project_urls": {
"Homepage": "https://github.com/glotzerlab/rowan"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "1ec91db928d23c74318af701d94cc60f880ebcff40c1493e0bf05d5a05cb74a4",
"md5": "895781483191f81aa428ce1387df1646",
"sha256": "234b77896650f6cf07e181cc9e3c49259fcebeb9725897ffd5922ddf2e8de82e"
},
"downloads": -1,
"filename": "rowan-1.3.0.post1-py2.py3-none-any.whl",
"has_sig": false,
"md5_digest": "895781483191f81aa428ce1387df1646",
"packagetype": "bdist_wheel",
"python_version": "py2.py3",
"requires_python": ">=3.6, <4",
"size": 28103,
"upload_time": "2020-06-18T21:28:36",
"upload_time_iso_8601": "2020-06-18T21:28:36.685176Z",
"url": "https://files.pythonhosted.org/packages/1e/c9/1db928d23c74318af701d94cc60f880ebcff40c1493e0bf05d5a05cb74a4/rowan-1.3.0.post1-py2.py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "9f01628d3be02e29d39d51945dafe9e3893a38db7a0bf1a80caae4b596065c53",
"md5": "5723ee2131babf4d3699057a81a69ce5",
"sha256": "8f1d0e3279f80c6ae1ee68a90955301853b5586f64e42ba4c27d85504d525e4f"
},
"downloads": -1,
"filename": "rowan-1.3.0.post1.tar.gz",
"has_sig": false,
"md5_digest": "5723ee2131babf4d3699057a81a69ce5",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.6, <4",
"size": 31437,
"upload_time": "2020-06-18T21:28:38",
"upload_time_iso_8601": "2020-06-18T21:28:38.241239Z",
"url": "https://files.pythonhosted.org/packages/9f/01/628d3be02e29d39d51945dafe9e3893a38db7a0bf1a80caae4b596065c53/rowan-1.3.0.post1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2020-06-18 21:28:38",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "glotzerlab",
"github_project": "rowan",
"travis_ci": false,
"coveralls": true,
"github_actions": false,
"circle": true,
"requirements": [],
"lcname": "rowan"
}
JSON
