or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

advanced-math.mdbasic-operations.mdconstruction.mdindex.mdinterpolation.mdrotation.md
tile.json

tessl/pypi-pyquaternion

A fully featured, pythonic library for quaternion representation, manipulation, 3D animation and geometry.

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
pypipkg:pypi/pyquaternion@0.9.x

To install, run

npx @tessl/cli install tessl/pypi-pyquaternion@0.9.0

index.mddocs/

pyquaternion

A fully featured, pythonic library for quaternion representation, manipulation, 3D animation and geometry. Provides comprehensive quaternion mathematics designed for 3D rotation representation, manipulation, and animation with efficient NumPy-based computation.

Package Information

  • Package Name: pyquaternion
  • Language: Python
  • Installation: pip install pyquaternion
  • Dependencies: numpy

Core Imports

from pyquaternion import Quaternion

Basic Usage

from pyquaternion import Quaternion
import numpy as np

# Create quaternion from axis and angle
q1 = Quaternion(axis=[0, 1, 0], degrees=90)  # 90° rotation about Y-axis

# Create quaternion from components
q2 = Quaternion(w=1, x=0, y=0, z=0)  # Identity quaternion

# Create quaternion from rotation matrix
rotation_matrix = np.eye(3)
q3 = Quaternion(matrix=rotation_matrix)

# Rotate a 3D vector
vector = [1, 0, 0]
rotated_vector = q1.rotate(vector)  # Returns [0, 0, -1]

# Quaternion arithmetic
q4 = q1 * q2  # Quaternion multiplication
q5 = q1 + q2  # Quaternion addition
q_conjugate = q1.conjugate  # Quaternion conjugate
q_inverse = q1.inverse  # Quaternion inverse

# Interpolation between quaternions
intermediate_q = Quaternion.slerp(q1, q2, amount=0.5)

Architecture

The library is built around a single Quaternion class that provides:

  • Multiple Construction Methods: Create quaternions from scalars, vectors, axis-angle, rotation matrices, or direct component specification
  • Complete Mathematical Operations: Full support for quaternion algebra including multiplication, addition, exponentiation, and advanced mathematical functions
  • 3D Rotation Operations: Vector rotation, conversion to rotation matrices, Euler angles, and axis-angle representations
  • Interpolation and Animation: SLERP (Spherical Linear Interpolation) and intermediate quaternion generation for smooth animations
  • Advanced Mathematics: Exponential/logarithm operations, manifold operations, and Riemannian geometry functions
  • Python Integration: Full operator overloading, type conversion, and pythonic API design

Capabilities

Quaternion Construction

Create quaternions from various representations including components, axis-angle, rotation matrices, and other quaternions.

class Quaternion:
    def __init__(self, *args, **kwargs): ...
    
    @classmethod
    def random(cls) -> 'Quaternion': ...

Construction

Basic Operations

Fundamental quaternion operations including arithmetic, comparison, normalization, and component access.

# Arithmetic operations
def __add__(self, other) -> 'Quaternion': ...
def __mul__(self, other) -> 'Quaternion': ...
def __pow__(self, exponent) -> 'Quaternion': ...

# Properties
@property
def conjugate(self) -> 'Quaternion': ...
@property
def inverse(self) -> 'Quaternion': ...
@property
def norm(self) -> float: ...
@property
def normalised(self) -> 'Quaternion': ...

# Utility methods
def is_unit(self, tolerance=1e-14) -> bool: ...

# Static conversion methods
@staticmethod
def to_degrees(angle_rad: float) -> float: ...
@staticmethod
def to_radians(angle_deg: float) -> float: ...

Basic Operations

3D Rotation

Apply quaternion rotations to 3D vectors and convert between different rotation representations.

def rotate(self, vector) -> Union[list, tuple, np.ndarray, 'Quaternion']: ...
def get_axis(self, undefined=np.zeros(3)) -> np.ndarray: ...

@property
def rotation_matrix(self) -> np.ndarray: ...
@property
def transformation_matrix(self) -> np.ndarray: ...
@property
def yaw_pitch_roll(self) -> tuple: ...
@property
def axis(self) -> np.ndarray: ...
@property
def angle(self) -> float: ...
@property
def degrees(self) -> float: ...

3D Rotation

Interpolation and Animation

Smooth interpolation between quaternion orientations for animation and trajectory planning.

@classmethod
def slerp(cls, q0, q1, amount=0.5) -> 'Quaternion': ...

@classmethod
def intermediates(cls, q0, q1, n, include_endpoints=False) -> Iterator['Quaternion']: ...

def derivative(self, rate) -> 'Quaternion': ...
def integrate(self, rate, timestep) -> 'Quaternion': ...

Interpolation

Advanced Mathematics

Advanced mathematical operations including exponential/logarithm functions and Riemannian manifold operations.

@classmethod
def exp(cls, q) -> 'Quaternion': ...
@classmethod
def log(cls, q) -> 'Quaternion': ...
@classmethod
def exp_map(cls, q, eta) -> 'Quaternion': ...
@classmethod
def sym_exp_map(cls, q, eta) -> 'Quaternion': ...
@classmethod
def log_map(cls, q, p) -> 'Quaternion': ...
@classmethod
def sym_log_map(cls, q, p) -> 'Quaternion': ...
@classmethod
def distance(cls, q0, q1) -> float: ...
@classmethod
def absolute_distance(cls, q0, q1) -> float: ...
@classmethod
def sym_distance(cls, q0, q1) -> float: ...

Advanced Mathematics

Operator Overloading and Type Conversion

Complete Python integration with operator overloading, type conversion, and container interface.

# Comparison
def __eq__(self, other) -> bool: ...

# Unary operations
def __neg__(self) -> 'Quaternion': ...
def __abs__(self) -> float: ...
def __invert__(self) -> 'Quaternion': ...

# Type conversion
def __int__(self) -> int: ...
def __float__(self) -> float: ...
def __complex__(self) -> complex: ...
def __bool__(self) -> bool: ...

# String representation
def __str__(self) -> str: ...
def __repr__(self) -> str: ...
def __format__(self, formatstr) -> str: ...
def __hash__(self) -> int: ...

# In-place arithmetic
def __iadd__(self, other) -> 'Quaternion': ...
def __isub__(self, other) -> 'Quaternion': ...
def __imul__(self, other) -> 'Quaternion': ...
def __itruediv__(self, other) -> 'Quaternion': ...
def __ipow__(self, other) -> 'Quaternion': ...

# Matrix multiplication operator (@)
def __matmul__(self, other) -> 'Quaternion': ...
def __imatmul__(self, other) -> 'Quaternion': ...

# Copy operations
def __copy__(self) -> 'Quaternion': ...
def __deepcopy__(self, memo) -> 'Quaternion': ...

Basic Operations

Types

class Quaternion:
    """
    Class to represent a 4-dimensional complex number or quaternion.
    
    Attributes:
        q: Quaternion 4-vector represented as a Numpy array
    """
    
    # Component access
    @property
    def scalar(self) -> float: ...  # Real component (w)
    @property
    def vector(self) -> np.ndarray: ...  # Imaginary components (x,y,z)
    @property
    def real(self) -> float: ...  # Alias for scalar
    @property
    def imaginary(self) -> np.ndarray: ...  # Alias for vector
    @property
    def w(self) -> float: ...  # Scalar component
    @property
    def x(self) -> float: ...  # First vector component
    @property
    def y(self) -> float: ...  # Second vector component
    @property
    def z(self) -> float: ...  # Third vector component
    @property
    def elements(self) -> np.ndarray: ...  # All components as array
    
    # Magnitude properties
    @property
    def magnitude(self) -> float: ...  # Alias for norm
    @property
    def unit(self) -> 'Quaternion': ...  # Alias for normalised
    
    # Angle properties  
    @property
    def radians(self) -> float: ...  # Alias for angle
    
    # Polar decomposition
    @property
    def polar_unit_vector(self) -> np.ndarray: ...
    @property
    def polar_angle(self) -> float: ...
    @property
    def polar_decomposition(self) -> tuple: ...
    
    # Container interface
    def __getitem__(self, index: int) -> float: ...
    def __setitem__(self, index: int, value: float) -> None: ...