# IC Python API:RLPy RQuaternion

## Detailed Description

This class represents a quaternion in mathematics. Quaternions represetn directions as a single rotation, just as rectangular coordinates represent positions as single vector. RQuaternion also defines some constants that can be used directly:

Constant Description
RQuaternion.IDENTITY 4D zero vector: (0, 0, 0, 1)
RQuaternion.ZERO 4D x unit vector: (0, 0, 0, 0) initialization value

## Constructor & Destructor

### __init__ ( self )

The constructor. Initialize a new RQuaternion object without initialization.

```1 q = RLPy.RQuaternion()
2
3 print(str(q.x) + ', ' + str(q.y) + ', ' + str(q.z) + ', ' + str(q.w)) # random values
```

### __init__ ( self, vV )

The constructor. Initialize a new RQuaternion object from a 4D vector.

#### Parameters

vV [IN] a 4D vector - RVector4
```1 v = RLPy.RVector4(1, 2, 3, 4)
2 q = RLPy.RQuaternion(v)
3
4 print(str(q.x) + ', ' + str(q.y) + ', ' + str(q.z) + ', ' + str(q.w)) # 1.0, 2.0, 3.0, 4.0
```

### __init__ ( self, qQ )

#### Parameters

qQ [IN] a quaternion - RQuaternion
```1 v = RLPy.RVector4(1, 2, 3, 4)
2 q = RLPy.RQuaternion(v)
3 p = RLPy.RQuaternion(q)
4
5 print(str(p.x) + ', ' + str(p.y) + ', ' + str(p.z) + ', ' + str(p.w)) # 1.0, 2.0, 3.0, 4.0
```

### __init__ ( self, kAxis, fAngle )

The constructor. Initialize a new RQuaternion object with Axis-angle. The axis is specified by a 3D vector, and the angle is specified by a float value.

#### Parameters

kAxis [IN] the rotation axis - RVector3
fAngle [IN] the rotation angle - float
```1 v = RLPy.RVector3(0, 0, 1)
2 q = RLPy.RQuaternion(v, math.pi/2)
3
4 print(str(q.x) + ', ' + str(q.y) + ', ' + str(q.z) + ', ' + str(q.w))
5     # 0.0, 0.0, 0.7071067094802856, 0.7071067690849304
```

### __init__ ( self, kRot )

The constructor. Initialize a new RQuaternion object with a 3x3 rotation matrix.

#### Parameters

kRot [IN] a 3x3 rotation matrix - RMatrix3
```1 v = RLPy.RVector3(0, 0, 1)
2 m = RLPy.RMatrix3(v, math.pi/2)
3 q = RLPy.RQuaternion(m)
4
5 print(str(q.x) + ', ' + str(q.y) + ', ' + str(q.z) + ', ' + str(q.w))
6     # 0.0, 0.0, 0.7071067690849304, 0.7071067690849304
```

## Operators

### =

The "equal to" operator.

```1 q = RLPy.RQuaternion()
2 p = q
3 if q == p:                         # True
4     print("equal")
```

### !=

The "not equal to" operator.

```1 a = RLPy.RVector4(1, 2, 3, 4)
2 q = RLPy.RQuaternion(a)
3 b = RLPy.RVector4(2, 2, 3, 4)
4 p = RLPy.RQuaternion(b)
5 if a != b:                         #True
6     print("not equal")
```

### <

The "less than" operator. Similar to string comparison: Returns True upon the first match that is less than and False if it is greater than. If the current comparison is equal, continue onto the next element. If all elements are equal then return False.

``` 1 a = RLPy.RVector4(0, 1, 5, 2)
2 b = RLPy.RVector4(0, 1, 5, 3)
3 c = RLPy.RVector4(1, 0, 1, 0)
4 d = RLPy.RVector4(0, 1, 5, 2)
5
6 p = RLPy.RQuaternion(a)
7 q = RLPy.RQuaternion(b)
8 r = RLPy.RQuaternion(c)
9 s = RLPy.RQuaternion(d)
10
11 if p< q:                       #True
12     print('p< q')
13 if q< r:                       #True
14     print('q< r')
15 if p< s:                       #False
16     print('p< s')
```

### >

The "greater than" operator. Similar to string comparison: Returns True upon the first match that is greater than and False if it is less than. If the current comparison is equal, continue onto the next element. If all elements are equal then return False.

``` 1 a = RLPy.RVector4(0, 1, 5, 2)
2 b = RLPy.RVector4(0, 1, 5, 3)
3 c = RLPy.RVector4(1, 0, 1, 0)
4 d = RLPy.RVector4(0, 1, 5, 2)
5
6 p = RLPy.RQuaternion(a)
7 q = RLPy.RQuaternion(b)
8 r = RLPy.RQuaternion(c)
9 s = RLPy.RQuaternion(d)
10
11 if q >p:                       #True
12     print('q >p')
13 if r >q:                       #True
14     print('r >q')
15 if p >s:                       #False
16     print('p >s')
```

### <=

The "less than or equal" operator. Similar to string comparison: Returns True upon the first match that is less than and False if it is greater than. If the current comparison is equal, continue onto the next element. If all elements are equal then return True.

``` 1 a = RLPy.RVector4(0, 1, 5, 2)
2 b = RLPy.RVector4(0, 1, 5, 3)
3 c = RLPy.RVector4(1, 0, 1, 0)
4 d = RLPy.RVector4(0, 1, 5, 2)
5
6 p = RLPy.RQuaternion(a)
7 q = RLPy.RQuaternion(b)
8 r = RLPy.RQuaternion(c)
9 s = RLPy.RQuaternion(d)
10
11 if p<= q:                       #True
12     print('p<= q')
13 if q<= r:                       #True
14     print('q<= r')
15 if p<= s:                       #True
16     print('p<= s')
```

### >=

The "greater than or equal" operator. Similar to string comparison: Returns True upon the first match that is greater than and False if it is less than. If the current comparison is equal, continue onto the next element. If all elements are equal then return True.

``` 1 a = RLPy.RVector4(0, 1, 5, 2)
2 b = RLPy.RVector4(0, 1, 5, 3)
3 c = RLPy.RVector4(1, 0, 1, 0)
4 d = RLPy.RVector4(0, 1, 5, 2)
5
6 p = RLPy.RQuaternion(a)
7 q = RLPy.RQuaternion(b)
8 r = RLPy.RQuaternion(c)
9 s = RLPy.RQuaternion(d)
10
11 if q >= p:                       #True
12     print('q >= p')
13 if r >= q:                       #True
14     print('r >= q')
15 if p >= s:                       #True
16     print('p >= s')
```

### +

```1 a = RLPy.RVector4(0, 1, 2, 3)
2 b = RLPy.RVector4(1, 2, 3, 4)
3 p = RLPy.RQuaternion(a)
4 q = RLPy.RQuaternion(b)
5 r = p + q
6
7 print(str(r.x) + ', ' + str(r.y) + ', ' + str(r.z) + ', ' + str(r.w))  # 1.0, 3.0, 5.0, 7.0
```

### -

The "subtraction" operator. Perform quaternion subtraction.

```1 a = RLPy.RVector4(0, 1, 2, 3)
2 b = RLPy.RVector4(3, 2, 1, 0)
3 p = RLPy.RQuaternion(a)
4 q = RLPy.RQuaternion(b)
5 r = q - p
6
7 print(str(r.x) + ', ' + str(r.y) + ', ' + str(r.z) + ', ' + str(r.w)) # 3.0, 1.0, -1.0, -3.0
```

### *

The "multiplication" operator. Perform a scalar multiplication when the second operand is an integer or float. If the second operand is another quaternion, then the respective elements are multiplied.

```1 a = RLPy.RVector4(1, 2, 3, 4)
2 p = RLPy.RQuaternion(a)
3 q = p * 2
4 r = p * p
5
6 print(str(q.x) + ', ' + str(q.y) + ', ' + str(q.z) + ', ' + str(q.w)) # 2.0, 4.0, 6.0, 8.0
7 print(str(r.x) + ', ' + str(r.y) + ', ' + str(r.z) + ', ' + str(r.w)) # 1.0, 4.0, 9.0, 16.0
```

### /

The "division" operator. Perform a scalar division with a int or float value which the second operand is limited to.

```1 a = RLPy.RVector4(1, 2, 3, 4)
2 p = RLPy.RQuaternion(a)
3 q = p / 2
4
5 print(str(q.x) + ', ' + str(q.y) + ', ' + str(q.z) + ', ' + str(q.w)) # 0.5, 1.0, 1.5, 2.0
```

### -

The "unary minus" operator. Inverse the sign of each element.

```1 a = RLPy.RVector4(1, 2, 3, 4)
2 p = RLPy.RQuaternion(a)
3 q = -p
4
5 print(str(q.x) + ', ' + str(q.y) + ', ' + str(q.z) + ', ' + str(q.w)) # -1.0, -2.0, -3.0, -4.0
```

### + =

```1 a = RLPy.RVector4(0, 1, 2, 3)
2 b = RLPy.RVector4(1, 2, 3, 4)
3 p = RLPy.RQuaternion(a)
4 q = RLPy.RQuaternion(b)
5 p += q
6
7 print(str(p.x) + ', ' + str(p.y) + ', ' + str(p.z) + ', ' + str(p.w)) # 1.0, 3.0, 5.0, 7.0
```

### - =

The "subtraction assignment" operator.

```1 a = RLPy.RVector4(0, 1, 4, 5)
2 b = RLPy.RVector4(1, 2, 3, 1)
3 p = RLPy.RQuaternion(a)
4 q = RLPy.RQuaternion(b)
5 p -= q
6
7 print(str(p.x) + ', ' + str(p.y) + ', ' + str(p.z) + ', ' + str(p.w)) # -1.0, -1.0, 1.0, 4.0
```

### *=

The "multiplication assignment" operator. For calculation method, refer to the * operator.

```1 a = RLPy.RVector4(1, 2, 3, 4)
2 p = RLPy.RQuaternion(a)
3 p *= 2
4
5 print(str(p.x) + ', ' + str(p.y) + ', ' + str(p.z) + ', ' + str(p.w)) # 2.0, 4.0, 6.0, 8.0
```

### /=

The "division assignment" operator. For calculation method, refer to the / operator.

```1 a = RLPy.RVector4(1, 2, 3, 4)
2 p = RLPy.RQuaternion(a)
3 p /= 2
4
5 print(str(p.x) + ', ' + str(p.y) + ', ' + str(p.z) + ', ' + str(p.w)) # 0.5, 1.0, 1.5, 2.0
```

## Member Functions

### AlmostEqual ( self, qQ )

Determine if two quaternions are almost the same within a tolerance of 0.00001.

#### Parameters

qQ [IN] The target quaternion to check for equivalence - RQuaternion

#### Returns

True if the two quaternions are almost the same, else False - bool
``` 1 a = RLPy.RVector4(1, 2, 3, 4)
2 p = RLPy.RQuaternion(a)
3 q = RLPy.RQuaternion(a)
4 r = RLPy.RQuaternion(a)
5
6 q.w = 4.000000001
7 r.w = 4.00001
8
9 if p.AlmostEqual(q):               #True
10     print("p ≈ q")
11 if q.AlmostEqual(r):               #False
12     print("p ≈ r")
```

### Conjugate ( self )

Get the conjugate of this quaternion. The result is a quaternion whose x, y, and z values have been negated.

#### Returns

The conjugated quaternion. - RQuaternion
```1 a = RLPy.RVector4(1, 2, 3, 4)
2 p = RLPy.RQuaternion(a)
3 q = p.Conjugate()
4
5 print(str(q.x) + ', ' + str(q.y) + ', ' + str(q.z) + ', ' + str(q.w)) # -1.0, -2.0, -3.0, 4.0
```

### Dot ( self, qQ )

Calculate the dot product of two quaternions.

#### Parameters

qQ [IN] The quaternion to compute dot product - RQuaternion

#### Returns

Value of the dot product - float
```1 a = RLPy.RVector4(1, 2, 3, 4)
2 b = RLPy.RVector4(1, 2, 3, 0)
3 p = RLPy.RQuaternion(a)
4 q = RLPy.RQuaternion(b)
5 f = p.Dot(q)
6
7 print(f)     # 14.0
```

### FromAxisAngle ( self, rkAxis, fAngle )

Create a quaternion from axis angle.

#### Parameters

rkAxis [IN] axis vector - RVector3
fAngle [IN] angle in radians - float

#### Returns

Return a new quaternion from a axis angle - RQuaternion
```1 p = RLPy.RQuaternion()
2 v = RLPy.RVector3(0, 0, 1)
3 p.FromAxisAngle(v, math.pi/2)
4
5 print(str(p.x) + ', ' + str(p.y) + ', ' + str(p.z) + ', ' + str(p.w)) # 0.0, 0.0, 0.7071067094802856, 0.7071067690849304
```

### FromRotationMatrix ( self, rkRot )

Create a quaternion from a rotation matrix.

#### Parameters

rkRot [IN] Rotation matrix - RMatrix3

#### Returns

Return a new quaternion from a rotation matrix - RQuaternion
```1 v = RLPy.RVector3(0, 0, 1)
2 m = RLPy.RMatrix3(v, math.pi/2)
3 p = RLPy.RQuaternion()
4 p.FromRotationMatrix(m)
5
6 print(str(p.x) + ', ' + str(p.y) + ', ' + str(p.z) + ', ' + str(p.w)) # 0.0, 0.0, 0.7071067690849304, 0.7071067690849304
```

### Inverse ( self, rkRot )

Get the inverse of this quaternion.

#### Returns

The inversed quaternion - RQuaternion
```1 a = RLPy.RVector4(1, 1, 1, 1)
2 p = RLPy.RQuaternion(a)
3 q = p.Inverse()
4
5 print(str(q.x) + ', ' + str(q.y) + ', ' + str(q.z) + ', ' + str(q.w)) # -0.25, -0.25, -0.25, 0.25
```

### Multiply ( self, qQ )

Multiply this quaternion by another quaternion.

#### Parameters

qQ [IN] The quaternion to multiply - RQuaternion

#### Returns

Returns the multiplied quaternion - RQuaternion
```1 a = RLPy.RVector4(1, 2, 3, 4)
2 b = RLPy.RVector4(1, 2, 2, 1)
3
4 p = RLPy.RQuaternion(a)
5 q = RLPy.RQuaternion(b)
6 r = p.Multiply(q)
7
8 print(str(r.x) + ', ' + str(r.y) + ', ' + str(r.z) + ', ' + str(r.w)) # 3.0, 11.0, 11.0, -7.0
```

### MultiplyEqual ( self, qQ )

#### Parameters

qQ [IN] The quaternion to multiply - RQuaternion

#### Returns

Returns the multiplied quaternion - RQuaternion
```1 a = RLPy.RVector4(1, 2, 3, 4)
2 b = RLPy.RVector4(1, 2, 2, 1)
3
4 p = RLPy.RQuaternion(a)
5 q = RLPy.RQuaternion(b)
6 r = p.MultiplyEqual(q)
7
8 print(str(r.x) + ', ' + str(r.y) + ', ' + str(r.z) + ', ' + str(r.w)) # 3.0, 11.0, 11.0, -7.0
```

### Normalize ( self )

Normalize this quaternion, e.g. with a magnitude of 2.

#### Returns

The normalized quaternion - RQuaternion
```1 a = RLPy.RVector4(1, 1, 1, 1)
2 p = RLPy.RQuaternion(a)
3 q = p.Normalize()
4
5 print(str(q.x) + ', ' + str(q.y) + ', ' + str(q.z) + ', ' + str(q.w))
6     # 0.4999999701976776, 0.4999999701976776, 0.4999999701976776, 0.4999999701976776
```

### Rotate180 ( self )

Rotate this quaternion by 180 degrees.

#### Returns

The rotated quaternion - RQuaternion
```1 a = RLPy.RVector4(1, 1, 1, 1)
2 p = RLPy.RQuaternion(a)
3 q = p.Normalize()
4
5 print(str(q.x) + ', ' + str(q.y) + ', ' + str(q.z) + ', ' + str(q.w))
6    #0.4999999701976776, 0.4999999701976776, 0.4999999701976776, 0.4999999701976776
```

### SetX ( self, tX )

Set the value of the x-axis.

#### Parameters

tX [IN] the value of the x-axis - float
```1 a = RLPy.RVector4(1, 2, 3, 4)
2 p = RLPy.RQuaternion(a)
3 p.SetX(9)
4
5 print(str(p.x) + ', ' + str(p.y) + ', ' + str(p.z) + ', ' + str(p.w)) # 9.0, 2.0, 3.0, 4.0
```

### SetY ( self, tY )

Set the value of the y-axis.

#### Parameters

tY [IN] the value of the y-axis - float
```1 a = RLPy.RVector4(1, 2, 3, 4)
2 p = RLPy.RQuaternion(a)
3 p.SetY(9)
4 print(str(p.x) + ', ' + str(p.y) + ', ' + str(p.z) + ', ' + str(p.w))
5     #1.0, 9.0, 3.0, 4.0
```

### SetZ ( self, tZ )

Set the value of the z-axis.

#### Parameters

tZ [IN] the value of the z-axis - float
```1 a = RLPy.RVector4(1, 2, 3, 4)
2 p = RLPy.RQuaternion(a)
3 p.SetZ(9)
4 print(str(p.x) + ', ' + str(p.y) + ', ' + str(p.z) + ', ' + str(p.w))
5     #1.0, 2.0, 9.0, 4.0
```

### SetW ( self, tW )

Set the value of the w-axis.

#### Parameters

tW [IN] the value of the w-axis - float
```1 a = RLPy.RVector4(1, 2, 3, 4)
2 p = RLPy.RQuaternion(a)
3 p.SetW(9)
4 print(str(p.x) + ', ' + str(p.y) + ', ' + str(p.z) + ', ' + str(p.w))
5     #1.0, 2.0, 3.0, 9.0
```