Package: rowan
Getting StartedInstallationQuickstartRunning TestsRunning BenchmarksBuilding DocumentationSupport and ContributionWelcome 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 quaterniona + bi + cj + dk.
This package provides tools for standard algebraic operations on quaternions as well as a number of additional tools fore.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 StartedInstallationThe recommended methods for installing rowan are usingpiporconda.
To install the package from PyPI, execute:$pipinstallrowan--userTo install the package from conda, first add theconda-forgechannel and
then install rowan:$condaconfig--addchannelsconda-forge$condainstallrowanIf you wish, you may also install rowan by cloningthe repositoryand running the setup script:$gitclonehttps://github.com/glotzerlab/rowan.git$cdrowan$pythonsetup.pyinstall--userThe minimum requirements for using rowan are:Python >= 3.6NumPy >= 1.15QuickstartThis library can be used to work with quaternions by simply instantiating the appropriate NumPy arrays and passing them to the required functions.
For example:importrowanimportnumpyasnpone=np.array([10,0,0,0])one_unit=rowan.normalize(one)assert(np.all(one_unit==np.array([1,0,0,0])))ifnotnp.all(one_unit==rowan.multiply(one_unit,one_unit)):raiseRuntimeError("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 TestsThe 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:python-munittestdiscovertestsTo check test coverage, make sure the coverage module is installed:pipinstallcoverageand then run the packaged unit tests with the coverage module:coveragerun-munittestdiscovertestsRunning BenchmarksBenchmarks for the package are contained in a Jupyter notebook in thebenchmarksfolder 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 installpyquaternionandnumpy_quaternionif you wish to see those comparisons.Building DocumentationYou can also build this documentation from source if you clone the repository.
The documentation is written inreStructuredTextand compiled usingSphinx.
To build from source, first install Sphinx:pipinstallsphinxsphinx_rtd_themeYou 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:cddocmakehtml# For html outputmakelatexpdf# For a LaTeX compiled PDF fileopenbuild/html/index.htmlSupport and ContributionThis package is hosted onGitHub.
Please report any bugs or problems that you find on theissue tracker.All contributions to rowan are welcomed via pull requests!
Please see thedevelopment guidefor more information on requirements for new code.