Pyquaternion

https://kieranwynn.github.io/pyquaternion/
Admin
Pyquaternion is a full-featured Python module for representing and using quaternions, supporting...
Tokens:19,048
Snippets:152
Trust Score:9.7
Update:5 months ago
Show doc for...
Tokens:
Raw
### Install PyQuaternion

Source: https://kieranwynn.github.io/pyquaternion

Install pyquaternion and its dependencies using pip. Numpy is a required dependency.

```bash
pip install pyquaternion
```

--------------------------------

### Quaternion SLERP Interpolation Example

Source: https://kieranwynn.github.io/pyquaternion

Demonstrates spherical linear interpolation (SLERP) between two quaternions to find an intermediate rotation. The amount parameter controls the position along the arc.

```python
q0 = Quaternion(axis=[1, 1, 1], angle=0.0)
q1 = Quaternion(axis=[1, 1, 1], angle=3.141592)
q  = Quaternion.slerp(q0, q1, 2.0/3.0) # Rotate 120 degrees (2 * pi / 3)
```

--------------------------------

### String Representation

Source: https://kieranwynn.github.io/pyquaternion

Get different string representations of the Quaternion object for display or debugging.

```APIDOC
## String Representation

### `__str__()`
`str(my_quaternion)` returns an informal, nicely printable string representation of the Quaternion object.

```python
>>> str(my_quaternion)
    '-0.810 +0.022i -0.563j -0.166k'
>>> print(my_quaternion)
    -0.810 +0.022i -0.563j -0.166k
>>>
```

### `__repr__()`
`repr(my_quaternion)` returns the 'official' string representation of the Quaternion object. This is a string representation of a valid Python expression that could be used to recreate an object with the same value (given an appropriate environment).

```python
>>> repr(my_quaternion)
    'Quaternion(-0.80951530224438595, 0.022231097065902788, -0.56268832802625091,-0.16604999023923223)'
>>> my_quaternion
    Quaternion(-0.80951530224438595, 0.022231097065902788, -0.56268832802625091,-0.16604999023923223)
>>>
```

### `__format__(format_spec)`
`a_string_containing_{format_spec}_placeholders.format(my_quaternion)` inserts a customisable, nicely printable string representation of the Quaternion object into the respective places in the provided string.

The syntax for `format_spec` mirrors that of the built in format specifiers for floating point types. Check out the official Python format specification mini-language for details. An empty `format_spec` string will result in the same behaviour as the `Quaternion.__str__()`.

```python
>>> "My quaternion is: {}".format(my_quaternion)
    'My quaternion is: -0.810 +0.022i -0.563j -0.166k'
>>> "My quaternion is: {:+.6}".format(my_quaternion)
    'My quaternion is: -0.809515 +0.0222311i -0.562688j -0.16605k'
```
```

--------------------------------

### Get Quaternion Derivative

Source: https://kieranwynn.github.io/pyquaternion

Use this method to get the instantaneous quaternion derivative. It requires a 3-element numpy array for the rotation rate.

```python
q_dot = my_quaternion.derivative([0, 0, 3.14159]) # Rotate about z at 0.5 rotation per second
```

--------------------------------

### Get Informal String Representation of Quaternion

Source: https://kieranwynn.github.io/pyquaternion

Obtain a nicely printable string representation of the Quaternion object using `str()` or `print()`.

```python
>>> str(my_quaternion)
    '-0.810 +0.022i -0.563j -0.166k'
>>> print(my_quaternion)
    -0.810 +0.022i -0.563j -0.166k
>>>
```

--------------------------------

### Get Quaternion Conjugate

Source: https://kieranwynn.github.io/pyquaternion

Obtain the conjugate of a Quaternion object. For unit quaternions, the conjugate is identical to the inverse.

```python
conj_quaternion = my_quaternion.conjugate
```

--------------------------------

### Quaternion Intermediate Rotations Generator

Source: https://kieranwynn.github.io/pyquaternion

Shows how to generate a sequence of intermediate quaternion rotations between two endpoints using a generator. The `include_endpoints` flag controls whether the start and end quaternions are included in the sequence.

```python
q0 = Quaternion(axis=[1, 1, 1], angle=0.0)
q1 = Quaternion(axis=[1, 1, 1], angle=2 * 3.141592 / 3)
for q in Quaternion.intermediates(q0, q1, 8, include_endpoints=True):
    v = q.rotate([1, 0, 0])
    print(v)
```

--------------------------------

### Get Quaternion Inverse

Source: https://kieranwynn.github.io/pyquaternion

Compute the inverse of a Quaternion object. For unit quaternions, this represents the inverse rotation.

```python
inv_quaternion = my_quaternion.inverse
```

--------------------------------

### Get Normalized Quaternion

Source: https://kieranwynn.github.io/pyquaternion

Generate a unit quaternion (versor) copy of the current Quaternion object. A zero quaternion cannot be normalized and will remain zero.

```python
unit_quaternion = my_quaternion.normalised
unit_quaternion = my_quaternion.unit
```

--------------------------------

### Quaternion Exponential Map Class Method

Source: https://kieranwynn.github.io/pyquaternion

Calculates the exponential map on the quaternion manifold. This method finds the endpoint of a geodesic starting at `q` in the direction of `eta`, with a length equal to the magnitude of `eta`. It's useful for integrating orientation variations.

```python
# Quaternion.exp_map(q, eta)
```

--------------------------------

### Get Official String Representation of Quaternion

Source: https://kieranwynn.github.io/pyquaternion

Obtain the official string representation of the Quaternion object using `repr()`. This string is a valid Python expression to recreate the object.

```python
>>> repr(my_quaternion)
    'Quaternion(-0.80951530224438595, 0.022231097065902788, -0.56268832802625091,-0.16604999023923223)'
>>> my_quaternion
    Quaternion(-0.80951530224438595, 0.022231097065902788, -0.56268832802625091,-0.16604999023923223)
>>>
```

--------------------------------

### Initialize Quaternion Explicitly by Element

Source: https://kieranwynn.github.io/pyquaternion

Specify each quaternion element (w, x, y, z) using keyword arguments like a, b, c, d or w, x, y, z or i, j, k. Elements can be real numbers or strings. Behavior is similar to initialization by element.

```python
q8a = Quaternion(a=1.0, b=0.0, c=0.0, d=0.0)
q8a = Quaternion(w=1.0, x=0.0, y=0.0, z=0.0)
q8a = Quaternion(a=1.0, i=0.0, j=0.0, k=0.0)
q8a = Quaternion(q1=1.0, q2=0.0, q3=0.0, q4=0.0)
```

--------------------------------

### Quaternion(a=w, b=x, c=y, d=z)

Source: https://kieranwynn.github.io/pyquaternion

Specify each quaternion element explicitly using keyword arguments. Accepted keywords include 'a', 'b', 'c', 'd', 'w', 'x', 'y', 'z', 'q1', 'q2', 'q3', 'q4'. Values can be real numbers or strings representing real numbers. Exception behavior is the same as initialization by element.

```APIDOC
## Explicitly by element
> **`Quaternion(a=w, b=x, c=y, d=z)`**
Specify each element, using any sequence of ordered labels
**Params:**
  * `a=w, b=x, c=y, d=z` can be real numbers, strings representing real numbers, or a mixture of both.

```python
q8a = Quaternion(a=1.0, b=0.0, c=0.0, d=0.0)
q8a = Quaternion(w=1.0, x=0.0, y=0.0, z=0.0)
q8a = Quaternion(a=1.0, i=0.0, j=0.0, k=0.0)
q8a = Quaternion(q1=1.0, q2=0.0, q3=0.0, q4=0.0)

```

**Rasises:** Exception behaviour is the same as initialisation by element as described above.
```

--------------------------------

### Create Quaternion by Copying

Source: https://kieranwynn.github.io/pyquaternion

Create a new Quaternion object that is an exact copy of an existing Quaternion instance.

```python
q2 = Quaternion(q1)
```

--------------------------------

### Initialize Quaternion from Matrix

Source: https://kieranwynn.github.io/pyquaternion

Create a Quaternion object from a 3x3 rotation matrix or a 4x4 transformation matrix. The translation part of a transformation matrix is ignored.

```APIDOC
## Quaternion(matrix=R) or Quaternion(matrix=T)

### Description
Specify the 3x3 rotation matrix (`R`) or 4x4 transformation matrix (`T`) from which the quaternion's rotation should be created.

### Parameters
#### Path Parameters
- **matrix=R** (numpy array or matrix) - Required - A 3x3 rotation matrix.
- **matrix=T** (numpy array or matrix) - Required - A 4x4 transformation matrix. Only the rotational component is used.

### Request Example
```python
import numpy

rotation = numpy.eye(3)
transformation = numpy.eye(4)
q8d = Quaternion(matrix=rotation) # Using 3x3 rotation matrix
q8d = Quaternion(matrix=transformation) # Using 4x4 transformation matrix
```

### Raises
- `ValueError` if the matrix is not 3x3 or 4x4 or if the matrix is not special orthogonal.
- `TypeError` if the matrix is of the wrong type.
```

--------------------------------

### Quaternion Norm

Source: https://kieranwynn.github.io/pyquaternion

Get the L2 norm (magnitude) of the quaternion's 4-vector. For a unit quaternion, this value should be 1.0.

```APIDOC
## norm or magnitude

### Description
L2 norm of the quaternion 4-vector. This should be 1.0 for a unit quaternion (versor).

### Returns
A scalar real number representing the square root of the sum of the squares of the elements of the quaternion.

### Request Example
```python
my_quaternion.norm
my_quaternion.magnitude
```
```

--------------------------------

### Initialize Quaternion from Elements

Source: https://kieranwynn.github.io/pyquaternion

Create a quaternion by providing the w, x, y, and z scalar elements. Elements can be real numbers or strings representing real numbers. Raises TypeError or ValueError if elements are invalid.

```python
q5 = Quaternion(1, 1, 0, 0)
q5 = Quaternion("1.0", "0", ""0.347"", "0.0")
q5 = Quaternion("1.76", 0, 0, 0)
```

--------------------------------

### Get Quaternion Norm/Magnitude

Source: https://kieranwynn.github.io/pyquaternion

Access the L2 norm (magnitude) of the quaternion's 4-vector. For a unit quaternion, this value should be 1.0.

```python
my_quaternion.norm
my_quaternion.magnitude
```

--------------------------------

### Import Quaternion

Source: https://kieranwynn.github.io/pyquaternion

Import the Quaternion object from the pyquaternion library to begin using its functionalities.

```python
>>> from pyquaternion import Quaternion
```

--------------------------------

### Initialize Quaternion from Numpy Array

Source: https://kieranwynn.github.io/pyquaternion

Create a Quaternion object directly from a 4-element numpy array representing the quaternion's elements [a, b, c, d].

```APIDOC
## Quaternion(array=a)

### Description
Specify a numpy 4-array of quaternion elements to be assigned directly to the internal vector representation of the quaternion object.

### Parameters
#### Path Parameters
- **array=a** (numpy array) - Required - A 4-element numpy array containing real valued elements in the order [a, b, c, d] corresponding to `a + bi + cj + dk`.

### Request Example
```python
import numpy

q8e = Quaternion(array=numpy.array([1.0, 0.0, 0.0, 0.0]))
```

### Raises
- `ValueError` if the array vector contains less/more than 4 elements.
```

--------------------------------

### Create Quaternion from Rotation/Transformation Matrix

Source: https://kieranwynn.github.io/pyquaternion

Instantiate a Quaternion object using a 3x3 rotation matrix or a 4x4 transformation matrix. The translation component of a 4x4 matrix is ignored. Ensure the matrix's rotation component is special orthogonal.

```python
rotation = numpy.eye(3)
transformation = numpy.eye(4)
q8d = Quaternion(matrix=rotation) // Using 3x3 rotation matrix
q8d = Quaternion(matrix=transformation) // Using 4x4 transformation matrix
```

--------------------------------

### Access Quaternion Rotation Angle

Source: https://kieranwynn.github.io/pyquaternion

Get the rotation angle in radians or degrees. The angle is within the range (-pi:pi). This method normalizes the quaternion to a unit quaternion.

```python
theta = my_quaternion.angle # Magnitude of rotation about the prescribed axis, in radians
theta = my_quaternion.radians # Equivalent, but explicit
theta = my_quaternion.degrees # The same, but in degrees
```

--------------------------------

### Initialize Quaternion Explicitly by Rotation Parameters

Source: https://kieranwynn.github.io/pyquaternion

Create a quaternion representing a rotation by specifying an axis and an angle (in radians or degrees). The axis must be a 3-element sequence or numpy array. Raises ValueError or TypeError for invalid inputs, and ZeroDivisionError if the axis has zero length.

```python
q8c = Quaternion(axis=(1.0, 0.0, 0.0), radians=math.pi/2) // Using radians asnd a 3-tuple
q8c = Quaternion(axis=[1.0, 0.0, 0.0], degrees=90) // Using degrees and a list
q8c = Quaternion(axis=numpy.array([1.0, 0.0, 0.0]), angle=math.pi/2) // Using radians and a Numpy 3-array
```

--------------------------------

### Quaternion Exponentiation (__pow__)

Source: https://kieranwynn.github.io/pyquaternion

Raises a quaternion to a real power. The result is a new Quaternion object.

```APIDOC
## `__pow__(other)`

### Description
Raises a quaternion `q` to the power of a real number `p`.

### Method
`q ** p`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```python
from pyquaternion import Quaternion
one = Quaternion(1, 0, 0, 0)
i   = Quaternion(0, 1, 0, 0)
j   = Quaternion(0, 0, 1, 0)
k   = Quaternion(0, 0, 0, 1)

result = i ** 2
```

### Response
#### Success Response (200)
- **return value** (Quaternion) - A new Quaternion object representing the result of the exponentiation.

#### Response Example
```python
# For the example above, result would be Quaternion(-1.0, 0.0, 0.0, 0.0)
```

### Raises
- **TypeError**: If `other` cannot be interpreted as a real number.
```

--------------------------------

### Initialize Quaternion from Numpy Array

Source: https://kieranwynn.github.io/pyquaternion

Create a quaternion from a 4-element Numpy array. The array elements correspond to w, x, y, and z components. Raises TypeError or ValueError for invalid array content or size.

```python
q6 = Quaternion(numpy.array([a, b, c, d]))
```

--------------------------------

### Create Quaternion from Numpy Array

Source: https://kieranwynn.github.io/pyquaternion

Initialize a Quaternion object directly from a 4-element numpy array representing the quaternion's elements [a, b, c, d] in the order a + bi + cj + dk. This method is efficient for direct assignment.

```python
q8e = Quaternion(array=numpy.array([1.0, 0.0, 0.0, 0.0]))
```

--------------------------------

### Customizable String Formatting for Quaternion

Source: https://kieranwynn.github.io/pyquaternion

Insert a customizable string representation of a Quaternion object into a string using the `format()` method. The format specifiers mirror floating-point types.

```python
>>> "My quaternion is: {}".format(my_quaternion)
    'My quaternion is: -0.810 +0.022i -0.563j -0.166k'
>>> "My quaternion is: {:+.6}".format(my_quaternion)
    'My quaternion is: -0.809515 +0.0222311i -0.562688j -0.16605k'
```

--------------------------------

### Initialize Quaternion Explicitly by Component

Source: https://kieranwynn.github.io/pyquaternion

Specify the quaternion using scalar (real) and vector (imaginary) parts. The vector part should be a 3-element sequence or numpy array. Either component can be None or empty, defaulting to zero. Raises ValueError for invalid vector size.

```python
q8b = Quaternion(scalar=1.0, vector=(0.0, 0.0, 0.0)) // Using 3-tuple
q8b = Quaternion(scalar=None, vector=[1.0, 0.0, 0.0]) // Using list
q8b = Quaternion(vector=numpy.array([1.0, 0.0, 0.0])) // Using Numpy 3-array

q8b = Quaternion(real=1.0, imaginary=(0.0, 0.0, 0.0)) // Using 3-tuple
q8b = Quaternion(real=None, imaginary=[1.0, 0.0, 0.0]) // Using list
q8b = Quaternion(imaginary=numpy.array([1.0, 0.0, 0.0])) // Using Numpy 3-array
```

--------------------------------

### Create Quaternion from Axis and Angle

Source: https://kieranwynn.github.io/pyquaternion

Create a Quaternion object to represent a specific rotation using an axis and an angle. Ensure numpy is imported for vector operations.

```python
>>> import numpy
>>> numpy.set_printoptions(suppress=True) # Suppress insignificant values for clarity
>>> v = numpy.array([0., 0., 1.]) # Unit vector in the +z direction
>>> my_quaternion = Quaternion(axis=[1, 0, 0], angle=3.14159265)
```

--------------------------------

### Quaternion Symmetrized Logarithm Map Class Method

Source: https://kieranwynn.github.io/pyquaternion

Computes the symmetrized logarithm map on the quaternion Riemannian manifold, corresponding to a symmetrized geodesic curve formulation.

```python
# Quaternion.sym_log_map(q, p)
```

--------------------------------

### Quaternion(w, x, y, z)

Source: https://kieranwynn.github.io/pyquaternion

Create a quaternion by specifying its four real-valued scalar elements (w, x, y, z). Elements can be real numbers, strings representing real numbers, or a mix of both. Raises TypeError if elements cannot be converted to real numbers, and ValueError if strings are not interpretable as real numbers.

```APIDOC
## From elements
> **`Quaternion(w, x, y, z)`**
Create a quaternion by specifying 4 real-numbered scalar elements.
**Params:**
  * `w, x, y, z` can be real numbers, strings representing real numbers, or a mixture of both.

```python
q5 = Quaternion(1, 1, 0, 0)
q5 = Quaternion("1.0", "0", ""0.347"", "0.0")
q5 = Quaternion("1.76", 0, 0, 0)

```

**Raises:**
  * `TypeError` if any of the provided values cannot be converted to a real number.
  * `ValueError` if any of the provided strings cannot be interpreted as a real number.
```

--------------------------------

### Initialize Quaternion from Sequence

Source: https://kieranwynn.github.io/pyquaternion

Create a quaternion from an iterable sequence (list, tuple, generator) of 4 real-valued elements. Elements correspond to w, x, y, and z. Raises TypeError or ValueError for invalid sequence content or size.

```python
q7 = Quaternion((a, b, c, d)) // from 4-tuple
q7 = Quaternion([a, b, c, d]) // from list of 4
```

--------------------------------

### Create Default Quaternion

Source: https://kieranwynn.github.io/pyquaternion

Create a unit quaternion representing a null rotation (1 + 0i + 0j + 0k). This quaternion has no effect on rotations or multiplications.

```python
q1 = Quaternion()
```

--------------------------------

### Quaternion.sym_exp_map(q, eta)

Source: https://kieranwynn.github.io/pyquaternion

Computes the Quaternion symmetrized exponential map on the quaternion Riemannian manifold.

```APIDOC
## Quaternion.sym_exp_map(q, eta)

### Description
Quaternion symmetrized exponential map. Finds the symmetrized exponential map on the quaternion Riemannian manifold.

### Method
Class Method

### Endpoint
N/A (Class Method)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
* **q** (Quaternion) - The base point as a Quaternion object.
* **eta** (Quaternion) - The tangent vector argument of the exponential map as a Quaternion object.

### Request Example
```python
result = Quaternion.sym_exp_map(base_quaternion, tangent_vector)
```

### Response
#### Success Response (200)
* **result** (Quaternion) - A quaternion p.

#### Response Example
```json
{
  "example": "(quaternion_representation)"
}
```
```

--------------------------------

### Quaternion(axis=ax, radians=rad) or Quaternion(axis=ax, degrees=deg) or Quaternion(axis=ax, angle=theta)

Source: https://kieranwynn.github.io/pyquaternion

Specify a rotation using an axis vector and an angle. The angle can be provided in radians (radians, angle) or degrees (degrees). The axis must be a sequence or NumPy array of 3 real numbers (cannot be zero magnitude). The angle keyword can be omitted (None or empty), defaulting to zero, but the axis must be provided. Raises ValueError if axis is missing or has incorrect dimensions, TypeError for angle conversion issues, and ZeroDivisionError if the axis has zero length.

```APIDOC
## Explicitly by rotation parameters
> **`Quaternion(axis=ax, radians=rad)`**or**`Quaternion(axis=ax, degrees=deg)`**or**`Quaternion(axis=ax, angle=theta)`**
Specify the angle (qualified as radians or degrees) for a rotation about an axis vector [x, y, z] to be described by the quaternion object.
**Params** _`axis=ax` can be a sequence or numpy array containing 3 real numbers. It can have any magnitude except `0`. _ `radians=rad` [optional] a real number, or a string representing a real number in radians. _`degrees=deg` [optional] a real number, or a string representing a real number in degrees. _ `angle=theta` [optional] a real number, or a string representing a real number in radians.
The `angle` (radians/degrees/angle) keyword may be absent, `None` or empty, and will be assumed to be zero in that case, but the `axis` keyword must be provided to describe a meaningful rotation.
```python
q8c = Quaternion(axis=(1.0, 0.0, 0.0), radians=math.pi/2) // Using radians asnd a 3-tuple
q8c = Quaternion(axis=[1.0, 0.0, 0.0], degrees=90) // Using degrees and a list
q8c = Quaternion(axis=numpy.array([1.0, 0.0, 0.0]), angle=math.pi/2) // Using radians and a Numpy 3-array

```

**Raises:**
  * `ValueError` if `axis` is missing
  * `ValueError` if `axis` contains less/more than 3 elements
  * `TypeError` if `radians/degrees/angle` cannot be interpreted as a real number
  * `ZeroDivisionError` if `axis` has 0 length.
```

--------------------------------

### Create a Random Quaternion

Source: https://kieranwynn.github.io/pyquaternion

Generate a random Quaternion object. This is useful for testing or initializing.

```python
my_quaternion = Quaternion.random()
```

--------------------------------

### Rotate 3D Vector with Quaternion

Source: https://kieranwynn.github.io/pyquaternion

Demonstrates rotating a 3D vector using the `rotate` method. The input vector can be a tuple, list, numpy array, or another Quaternion object. The output type matches the input type.

```python
rotated_tuple       = my_quaternion.rotate((1, 0, 0)) # Returns a tuple
```

```python
rotated_list        = my_quaternion.rotate([1.0, 0.0, 0.0]) # Returns a list
```

```python
rotated_array       = my_quaternion.rotate(numpy.array([1.0, 0.0, 0.0])) # Returns a Numpy 3-array
```

```python
rotated_quaternion  = my_quaternion.rotate(Quaternion(vector=[1, 0, 0])) # Returns a Quaternion object
```

--------------------------------

### Quaternion.sym_log_map(q, p)

Source: https://kieranwynn.github.io/pyquaternion

Computes the Quaternion symmetrized logarithm map on the quaternion Riemannian manifold.

```APIDOC
## Quaternion.sym_log_map(q, p)

### Description
Quaternion symmetrized logarithm map. Finds the symmetrized logarithm map on the quaternion Riemannian manifold.

### Method
Class Method

### Endpoint
N/A (Class Method)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
* **q** (Quaternion) - The base point at which the logarithm is computed, i.e. a Quaternion object.
* **p** (Quaternion) - The argument of the quaternion map, a Quaternion object.

### Request Example
```python
result = Quaternion.sym_log_map(base_quaternion, target_quaternion)
```

### Response
#### Success Response (200)
* **result** (Quaternion) - A tangent vector corresponding to the symmetrized geodesic curve formulation.

#### Response Example
```json
{
  "example": "(tangent_vector_representation)"
}
```
```

--------------------------------

### Quaternion Logarithm Map Class Method

Source: https://kieranwynn.github.io/pyquaternion

Finds the logarithm map on the quaternion Riemannian manifold. This method returns a tangent vector representing the geodesic joining `q` and `p`.

```python
# Quaternion.log_map(q, p)
```

--------------------------------

### integrate(rate, timestep)

Source: https://kieranwynn.github.io/pyquaternion

Advances a time-varying quaternion to its value at a future time `timestep`, modifying the quaternion in place.

```APIDOC
## integrate(rate, timestep)

### Description
Advance a time varying quaternion to its value at a time `timestep` in the future. The Quaternion object will be modified to its future value. It is guaranteed to remain a unit quaternion.

### Parameters
#### Path Parameters
- None

#### Query Parameters
- None

#### Request Body
- None

### Method
- Not applicable (method call on an object)

### Endpoint
- Not applicable (method call on an object)

### Request Example
```python
>>> q = Quaternion() # null rotation
>>> q.integrate([2*pi, 0, 0], 0.25) # Rotate about x at 1 rotation per second
>>> q == Quaternion(axis=[1, 0, 0], angle=(pi/2))
True
```

### Response
#### Success Response
- The Quaternion object is modified in place to its future value.

#### Response Example
- Not applicable (method modifies object in place)

### Error Handling
- `TypeError`: if any of `rate` contents cannot be converted to a real number.
- `ValueError`: if `rate` contains less/more than 3 elements
```

--------------------------------

### Access Rotation and Transformation Matrices

Source: https://kieranwynn.github.io/pyquaternion

Retrieve the 3x3 rotation matrix or the 4x4 homogeneous transformation matrix equivalent of a unit quaternion. The quaternion is implicitly normalized before conversion.

```python
R = my_quaternion.rotation_matrix         # 3x3 rotation matrix
T = my_quaternion.transformation_matrix   # 4x4 transformation matrix
```

--------------------------------

### Quaternion.exp_map(q, eta)

Source: https://kieranwynn.github.io/pyquaternion

Computes the Quaternion exponential map, finding the endpoint of a geodesic on the quaternion manifold. This is useful for integrating orientation variations.

```APIDOC
## Quaternion.exp_map(q, eta)

### Description
Quaternion exponential map. Finds the exponential map on the Riemannian manifold described by the quaternion space.

### Method
Class Method

### Endpoint
N/A (Class Method)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
* **q** (Quaternion) - The base point of the exponential map, i.e. a Quaternion object.
* **eta** (Quaternion) - The argument of the exponential map, a tangent vector, i.e. a Quaternion object.

### Request Example
```python
result = Quaternion.exp_map(base_quaternion, tangent_vector)
```

### Response
#### Success Response (200)
* **result** (Quaternion) - A quaternion p such that p is the endpoint of the geodesic starting at q in the direction of eta, having the length equal to the magnitude of eta.

#### Response Example
```json
{
  "example": "(quaternion_representation)"
}
```
```

--------------------------------

### derivative(rate)

Source: https://kieranwynn.github.io/pyquaternion

Calculates the instantaneous quaternion derivative representing a quaternion rotating at a given 3D rate vector.

```APIDOC
## derivative(rate)

### Description
Get the instantaneous quaternion derivative representing a quaternion rotating at a 3D rate vector `rate`.

### Parameters
#### Path Parameters
- None

#### Query Parameters
- None

#### Request Body
- None

### Method
- Not applicable (method call on an object)

### Endpoint
- Not applicable (method call on an object)

### Request Example
```python
q_dot = my_quaternion.derivative([0, 0, 3.14159]) # Rotate about z at 0.5 rotation per second
```

### Response
#### Success Response
- **Returns**: A unit quaternion describing the rotation rate.

#### Response Example
- Not applicable (method returns a value directly)

### Error Handling
- `TypeError`: if any of `rate` contents cannot be converted to a real number.
- `ValueError`: if `rate` contains less/more than 3 elements
```

--------------------------------

### Quaternion(seq)

Source: https://kieranwynn.github.io/pyquaternion

Create a quaternion object from an ordered sequence (list, tuple, generator, etc.) containing 4 real-valued scalar elements. The elements a, b, c, d correspond to the real, i, j, and k components respectively (a + bi + cj + dk). Raises TypeError for non-real sequence contents and ValueError if the sequence does not contain exactly 4 elements.

```APIDOC
## From a sequence
> **`Quaternion(seq)`**
Create a quaternion object from an ordered sequence containing 4 real valued scalar elements
**Params:**
  * `seq` can be a list, a tuple, a generator or any iterable sequence containing 4 values, each convertible to a real number.


The sequential elements `a, b, c, d` of the sequence correspond the the real, and each imaginary component respectively in the order `a + bi + cj + dk`.
```python
q7 = Quaternion((a, b, c, d)) // from 4-tuple
q7 = Quaternion([a, b, c, d]) // from list of 4

```

**Raises:**
  * `TypeError` if any of the sequence contents cannot be converted to a real number.
  * `ValueError` if the sequence contains less/more than 4 elements
```

--------------------------------

### Quaternion.log(q)

Source: https://kieranwynn.github.io/pyquaternion

Computes the Quaternion Logarithm for a given Quaternion object. This class method computes the logarithm of general quaternions.

```APIDOC
## Quaternion.log(q)

### Description
Quaternion Logarithm. Computes the logarithm of general quaternions.

### Method
Class Method

### Endpoint
N/A (Class Method)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
* **q** (Quaternion) - The input quaternion/argument as a Quaternion object.

### Request Example
```python
result = Quaternion.log(my_quaternion)
```

### Response
#### Success Response (200)
* **result** (Quaternion) - A quaternion amount representing `log(q) := (log(|q|), v/|v|acos(w/|q|))`.

#### Response Example
```json
{
  "example": "(quaternion_representation)"
}
```
```

--------------------------------

### Quaternion.exp(q)

Source: https://kieranwynn.github.io/pyquaternion

Computes the Quaternion Exponential for a given Quaternion object. This class method can compute the exponential of any quaternion.

```APIDOC
## Quaternion.exp(q)

### Description
Quaternion Exponential. Computes the exponential of any quaternion.

### Method
Class Method

### Endpoint
N/A (Class Method)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
* **q** (Quaternion) - The input quaternion/argument as a Quaternion object.

### Request Example
```python
result = Quaternion.exp(my_quaternion)
```

### Response
#### Success Response (200)
* **result** (Quaternion) - A quaternion amount representing the exp(q).

#### Response Example
```json
{
  "example": "(quaternion_representation)"
}
```
```

--------------------------------

### Addition

Source: https://kieranwynn.github.io/pyquaternion

Performs element-wise addition of two Quaternion objects. If the 'other' operand is not a Quaternion, it will be converted.

```APIDOC
## __add__(other)
`q1 + q2` is the quaternion formed by element-wise sum of `q1` and `q2`.
**Note:** If 'other' is not a Quaternion object, it will be converted to one. A `TypeError` or `ValueError` will be raised if this conversion fails.
**Returns:** a new Quaternion object representing the sum of the inputs. The sum is **not** guaranteed to be a unit quaternion.

### Example
```python
>>> from pyquaternion import Quaternion
>>> q1 = Quaternion.random()
>>> q2 = Quaternion.random()
>>> q1 + q2 == Quaternion(q1.elements() + q2.elements())
True
```
```

--------------------------------

### Quaternion Exponentiation

Source: https://kieranwynn.github.io/pyquaternion

Raises a quaternion to a real power. If the base is a unit quaternion, the result is also a unit quaternion. Raises TypeError if the exponent cannot be interpreted as a real number.

```python
>>> one = Quaternion(1, 0, 0, 0)
>>> i   = Quaternion(0, 1, 0, 0)
>>> j   = Quaternion(0, 0, 1, 0)
>>> k   = Quaternion(0, 0, 0, 1)
>>> (i ** 2) == (j ** 2) == (k ** 2) == -1
True
```

--------------------------------

### Quaternion(scalar=s, vector=v) or Quaternion(real=r, imaginary=i)

Source: https://kieranwynn.github.io/pyquaternion

Specify the quaternion using its scalar (real) and vector (imaginary) parts. The scalar part can be a real number or a string. The vector part must be a sequence or NumPy array of 3 real numbers. Either component can be omitted (None or empty), defaulting to zero. Raises ValueError if the vector/imaginary component does not have exactly 3 elements.

```APIDOC
## Explicitly by component
> **`Quaternion(scalar=s, vector=v)`or`Quaternion(real=r, imaginary=i)`**
Specify the scalar (real) and vector (imaginary) parts of the desired quaternion.
**Params:**
  * `scalar=s` or `real=r` can be a real number, or a string representing a real number.
  * `vector=v` or `imaginary=i` can be a sequence or numpy array containing 3 real numbers.


Either component (but not both) may be absent, `None` or empty, and will be assumed to be zero in that case.
```python
q8b = Quaternion(scalar=1.0, vector=(0.0, 0.0, 0.0)) // Using 3-tuple
q8b = Quaternion(scalar=None, vector=[1.0, 0.0, 0.0]) // Using list
q8b = Quaternion(vector=numpy.array([1.0, 0.0, 0.0])) // Using Numpy 3-array

q8b = Quaternion(real=1.0, imaginary=(0.0, 0.0, 0.0)) // Using 3-tuple
q8b = Quaternion(real=None, imaginary=[1.0, 0.0, 0.0]) // Using list
q8b = Quaternion(imaginary=numpy.array([1.0, 0.0, 0.0])) // Using Numpy 3-array

```

**Raises:** `ValueError` if the `vector` or `imaginary` component contains less/more than 3 elements
```

--------------------------------

### Create Quaternion from Scalar

Source: https://kieranwynn.github.io/pyquaternion

Create a Quaternion object from a real number (scalar) value. The imaginary parts (i, j, k) will be zero. Accepts real numbers or strings representing real numbers.

```python
q4 = Quaternion(4.7349)
q4 = Quaternion(-3)
q4 = Quaternion("4.7349")
q4 = Quaternion("98")
```

--------------------------------

### Accessing individual elements

Source: https://kieranwynn.github.io/pyquaternion

Retrieve all four elements of a quaternion object or access a specific element by its index.

```APIDOC
## Accessing individual elements

### `elements`
Return all four elements of the quaternion object. Result is not guaranteed to be a unit 4-vector.

**Returns:** a numpy 4-array of real numbered coefficients.

```python
>>> a = my_quaternion.elements
>>> print("{} + {}i + {}j + {}k".format(a[0], a[1], a[2], a[3]))
    -0.6753741977725701 + 0.4624451782281068i + -0.059197245808339134j + 0.5714103921047806k
```

### `__getitem__(index)`
`my_quaternion[i]` returns the real numbered element at the specified index `i` in the quaternion 4-array

**Params:**
  * `index` - integer in the range [-4:3] inclusive

```python
>>> print("{} + {}i + {}j + {}k".format(my_quaternion[0], my_quaternion[1], my_quaternion[2], my_quaternion[3]))
   -0.6753741977725701 + 0.4624451782281068i + -0.059197245808339134j + 0.5714103921047806k
>>> print("{} + {}i + {}j + {}k".format(my_quaternion[-4], my_quaternion[-3], my_quaternion[-2], my_quaternion[-1]))
   -0.6753741977725701 + 0.4624451782281068i + -0.059197245808339134j + 0.5714103921047806k
>>>
```

**Raises:**
  * `IndexError` if the index provided is invalid
  * `TypeError` or `ValueError` if the index cannot be interpreted as an integer
```

--------------------------------

### Quaternion Exponential Class Method

Source: https://kieranwynn.github.io/pyquaternion

Computes the exponential of any given quaternion using the `Quaternion.exp` class method.

```python
# Quaternion.exp(q)
```

--------------------------------

### Quaternion.intermediates

Source: https://kieranwynn.github.io/pyquaternion

Generates a sequence of evenly spaced quaternion rotations between two endpoints.

```APIDOC
## Quaternion.intermediates(q_start, q_end, n, include_endpoints=False)

### Description
Generates a sequence of `n` evenly spaced quaternion rotations between two existing quaternion endpoints lying on the unit radius hypersphere. This is a convenience function based on `Quaternion.slerp()`.

### Method
Class method

### Parameters
#### Path Parameters
- **q_start** (Quaternion) - Initial endpoint rotation as a Quaternion object.
- **q_end** (Quaternion) - Final endpoint rotation as a Quaternion object.
- **n** (int) - Number of intermediate quaternion objects to include within the interval.
- **include_endpoints** (bool) - Optional. If True, the sequence includes `q_start` and `q_end`. Defaults to False.

### Yields
- **generator** - A generator object iterating over a sequence of intermediate quaternion objects.

### Request Example
```python
q0 = Quaternion(axis=[1, 1, 1], angle=0.0)
q1 = Quaternion(axis=[1, 1, 1], angle=2 * 3.141592 / 3)
for q in Quaternion.intermediates(q0, q1, 8, include_endpoints=True):
    v = q.rotate([1, 0, 0])
    print(v)
```
```

--------------------------------

### Accessing Real Component

Source: https://kieranwynn.github.io/pyquaternion

Retrieves the scalar (real) component of the Quaternion object.

```APIDOC
## Accessing real components
> **`scalar`or`real`**
Get the real or scalar component of the Quaternion object
A quaternion can be described in terms of a scalar and vector part, q = [r, **v**] where:
  * r is the scalar coefficient of the real part of the quaternion i.e. **a** in a + b _i_ + c _j_ + d _k_
  * **v** is the 3-vector of coefficients to the imaginary parts of the quaternion i.e. [b, c, d] in a + b _i_ + c _j_ + d _k_


This property returns r
**Returns** the scalar, real valued element of the Quaternion object
```
r = my_quaternion.scalar
r = my_quaternion.real

```
```

--------------------------------

### Quaternion Symmetrized Exponential Map Class Method

Source: https://kieranwynn.github.io/pyquaternion

Computes the symmetrized exponential map on the quaternion Riemannian manifold. This formulation is similar to exponential maps for symmetric positive definite tensors.

```python
# Quaternion.sym_exp_map(q, eta)
```

--------------------------------

### Quaternion(array)

Source: https://kieranwynn.github.io/pyquaternion

Create a quaternion from a 4-element NumPy array. The array elements must be real numbers. The elements [a, b, c, d] correspond to the real, i, j, and k components respectively (a + bi + cj + dk). Raises TypeError for non-real array contents and ValueError if the array does not contain exactly 4 elements.

```APIDOC
## From a numpy array
> **`Quaternion(array)`**
Create a quaternion from the elements of a 4-element Numpy array
**Params:**
  * `array` must be a 4-element numpy array containing real valued elements.


The elements `[a, b, c, d]` of the array correspond the the real, and each imaginary component respectively in the order `a + bi + cj + dk`.
```python
q6 = Quaternion(numpy.array([a, b, c, d]))

```

**Raises:**
  * `TypeError` if any of the array contents cannot be converted to a real number.
  * `ValueError` if the array contains less/more than 4 elements
```

--------------------------------

### Access Individual Quaternion Elements by Index

Source: https://kieranwynn.github.io/pyquaternion

Access individual elements of a quaternion using integer indices. Supports both positive and negative indexing. Raises IndexError for invalid indices.

```python
>>> print("{} + {}i + {}j + {}k".format(my_quaternion[0], my_quaternion[1], my_quaternion[2], my_quaternion[3]))
   -0.6753741977725701 + 0.4624451782281068i + -0.059197245808339134j + 0.5714103921047806k
>>> print("{} + {}i + {}j + {}k".format(my_quaternion[-4], my_quaternion[-3], my_quaternion[-2], my_quaternion[-1]))
   -0.6753741977725701 + 0.4624451782281068i + -0.059197245808339134j + 0.5714103921047806k
>>>
```

--------------------------------

### Division

Source: https://kieranwynn.github.io/pyquaternion

Performs the Hamilton quotient of two Quaternion objects (q1 * q2.inverse()). The operation is not commutative. If the 'other' operand is not a Quaternion, it will be converted.

```APIDOC
## __truediv__(other) or __div__(other)
`q1 / q2` is the quaternion formed by Hamilton product of `q1` and `q2.inverse()`.
The Hamiltonian product is not commutative. Ensure your operands are correctly placed.
**Note:** If 'other' is not a Quaternion object, it will be converted to one. A `TypeError` or `ValueError` will be raised if this conversion fails. This operation holds true for scalar division as scalars are converted to pure real Quaternion objects.
**Returns:** a new Quaternion object representing the Hamilton quotient of the inputs. If the dividend and divisor are unit quaternions, the quotient is guaranteed to be a unit quaternion.

### Example
```python
>>> from pyquaternion import Quaternion
>>> my_quaternion = Quaternion(1, 2, 3, 4)
>>> my_quaternion / my_quaternion == Quaternion(1.0)
True
```
```

--------------------------------

### Create Random Quaternion

Source: https://kieranwynn.github.io/pyquaternion

Generate a random Quaternion object that represents a rotation chosen uniformly from the entire rotation space. This is a class method.

```python
q3 = Quaternion.random() # called as a class method
```

--------------------------------

### Quaternion.log_map(q, p)

Source: https://kieranwynn.github.io/pyquaternion

Computes the Quaternion logarithm map, finding the tangent vector representing the geodesic joining two quaternion points.

```APIDOC
## Quaternion.log_map(q, p)

### Description
Quaternion logarithm map. Finds the logarithm map on the quaternion Riemannian manifold.

### Method
Class Method

### Endpoint
N/A (Class Method)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
* **q** (Quaternion) - The base point at which the logarithm is computed, i.e. a Quaternion object.
* **p** (Quaternion) - The argument of the quaternion map, a Quaternion object.

### Request Example
```python
result = Quaternion.log_map(base_quaternion, target_quaternion)
```

### Response
#### Success Response (200)
* **result** (Quaternion) - A tangent vector having the length and direction given by the geodesic joining q and p.

#### Response Example
```json
{
  "example": "(tangent_vector_representation)"
}
```
```

--------------------------------

### Integrate Quaternion Over Time

Source: https://kieranwynn.github.io/pyquaternion

Advance a quaternion to its value at a future timestep. The quaternion is modified in place and re-normalized to remain a unit quaternion. Assumes the rate is constant over the timestep.

```python
>>> q = Quaternion() # null rotation
>>> q.integrate([2*pi, 0, 0], 0.25) # Rotate about x at 1 rotation per second
>>> q == Quaternion(axis=[1, 0, 0], angle=(pi/2))
True
>>>

```
Tokens:
Raw