rowan 0.6.1

Perform quaternion operations using numpy arrays

README

The rowan package provides a simple and consistent interface for using quaternions. 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. The package covers all basic quaternion algebraic and calculus operations, and also provides features for measuring distances, performing point cloud mapping, and interpolating.

Authors

• Vyas Ramasubramani, [e-mail] (Maintainer)

Setup

The recommended method for installing rowan is using pip.

Installation via pip

To install the package from PyPI, execute:

pip install rowan --user

Installation from source

To install from source, execute:

git clone https://bitbucket.org/vramasub/rowan.git
cd rowan
python setup.py install --user

Requirements

• Python = 2.7, >= 3.3
• Numpy >= 1.10

Testing

The package is currently tested for python versions 2.7, 3.3, 3.4, 3.5, 3.6, and 3.7 on Unix. Continuous integrated testing is performed using CircleCI on these python versions with numpy versions 1.10 and above.

To run the packaged unit tests, execute:

python -m unittest discover tests

To check test coverage, make sure the coverage module is installed:

pip install coverage

and then run the packaged unit tests:

coverage run -m unittest discover tests

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:

>>> import rowan
>>> one = np.array([10, 0, 0, 0])
>>> one_unit = rowan.normalize(one)
>>> assert(one_unit == np.array([1, 0, 0, 0]))
>>> if not one_unit == rowan.quat_multiply(one_unit, one_unit):
>>>     raise RuntimeError("Multiplication failed!")
>>>
>>> one_vec = np.array([1, 0, 0])
>>> rotated_vector = rowan.rotate(one_unit, one_vec)
>>>
>>> import numpy as np
>>> 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)

Documentation

Documentation for rowan is written in reStructuredText and compiled using Sphinx. To build the documentation, first install Sphinx:

pip install sphinx

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:

cd doc
make html # For html output
make latexpdf # For a LaTeX compiled PDF file
open build/html/index.html