transforms3d

Transforms3d is a library for converting between various geometric transformations. It provides tools for:

• Composition: Combining rotations, zooms, shears, and translations into an affine matrix.
• Decomposition: Breaking down an affine matrix into its constituent rotations, zooms, shears, and translations.
• Rotation Conversions: Converting between different rotation representations, specifically:
  • 3x3 Rotation matrices
  • Euler angles
  • Quaternions

The transforms3d package provides a collection of Python functions and classes designed to create and convert 3-dimensional transformations. Supported transformations include:

• Rotations
• Zooms
• Shears
• Reflections

The following mathematical concepts are fundamental to the library's operations:

• Euclidean Norm (L2 Norm): The length of a vector $\mathbf{x}$, calculated as $\sqrt{x_1^2 + \cdots + x_n^2}$.
• Unit Vector: A vector with a Euclidean norm of 1. Also referred to as a normalized vector.
• Linear Transformation: A transformation that preserves lines (e.g., rotation, scaling, and shear).
• Homogenous Coordinates: A coordinate system used to represent affine transformations (including translation) as matrix multiplications.
• Reflection: A transformation that creates a mirror image of an object across a plane defined by a point and a normal vector.

The transforms3d library follows a specific convention for applying transformations to coordinates.

1. Matrix Application: Transformation matrices are applied to the left of the coordinate vectors.
2. Vector Storage: Coordinates are stored as column vectors.
3. Point Matrices: When transforming a set of $N$ points, they are organized into a single matrix $P$ where each column represents a point $(x, y, z)$.

To transform a matrix of points $P$ using a $3\times3$ transformation matrix $M$, the operation is:

$v^\prime = M \cdot P$

This means the resulting matrix $v^\prime$ contains the transformed coordinates in its columns.

   P = \left( \begin{matrix} 
     x^1, x^2, \ldots, x^N \\
     y^1, y^2, \ldots, y^N \\
     z^1, z^2, \ldots, z^N \\
     \end{matrix} \right)

   v^\prime = M \cdot P

Gimbal lock is a deficiency in Euler angle rotation sequences where two of the three rotation axes align, causing a loss of one degree of freedom. In a sequence like $x ightarrow y ightarrow z$, if the $y$ axis rotation reaches $\pm\pi/2$ radians, the $x$ and $z$ axes become indistinguishable. This means any rotation around the $z$ axis has the exact same effect as an additional rotation around the $x$ axis.

For the common 'sxyz' (intrinsic $x, y, z$) convention, gimbal lock occurs when $\cos(\beta) = 0$, where $\beta$ is the angle of rotation around the $y$ axis.

After the PyPI release, upload the project documentation using the make github command within the doc directory.

pip install -e .
pip install -r doc-requirements.txt
cd doc
make github

Ensure that all examples within the documentation are correct by running the doctests. This requires the dependencies listed in doc-requirements.txt.

1. Install documentation requirements.
2. Navigate to the doc directory.
3. Run make doctest.

pip install -r doc-requirements.txt
cd doc
make doctest
cd ..

The documentation for transforms3d is built using Sphinx. To build the documentation locally, you must have Sphinx v1.0 or greater installed.

Follow these steps:

1. Install the necessary documentation dependencies using the requirements file located in the parent directory.
2. Use the provided Makefile to generate the HTML documentation.

# Install dependencies
pip install -r ../doc-requirements.txt

# Build HTML documentation
make html

Before releasing, ensure the package installs correctly by performing a clean installation into a fresh virtual environment and running the test suite.

1. Create and activate a virtual environment.
2. Install testing dependencies (pytest, wheel).
3. Clean the repository of build artifacts.
4. Install the package using setup.py.
5. Run pytest with --doctest-modules to verify functionality and documentation examples.

mkvirtualenv transforms3d-test
pip install pytest wheel
git clean -fxd
python setup.py install
mkdir for_test
cd for_test
pytest --doctest-modules transforms3d