Difference between revisions of "IC Python API:RLPy RQuaternion"

From Reallusion Wiki!
Jump to: navigation, search
m
m
Line 15: Line 15:
 
|-
 
|-
 
|RQuaternion.ZERO
 
|RQuaternion.ZERO
−
|4D x unit vector: (0, 0, 0, 0)
+
|4D x unit vector: (0, 0, 0, 0)init
 
|}
 
|}
  
Line 33: Line 33:
  
 
The constructor. Initialize a new RQuaternion object from a 4D vector RVector4.
 
The constructor. Initialize a new RQuaternion object from a 4D vector RVector4.
 +
 +
==== Parameters ====
 +
:'''vV''' [IN]  a 4D vector - RLPy.RVector4
  
 
<syntaxhighlight lang="Python">
 
<syntaxhighlight lang="Python">
Line 40: Line 43:
 
print(str(q.x) + ', ' + str(q.y) + ', ' + str(q.z) + ', ' + str(q.w)) # 1.0, 2.0, 3.0, 4.0
 
print(str(q.x) + ', ' + str(q.y) + ', ' + str(q.z) + ', ' + str(q.w)) # 1.0, 2.0, 3.0, 4.0
 
</syntaxhighlight>
 
</syntaxhighlight>
−
 
−
==== Parameters ====
 
−
:'''vV''' [IN]  a 4D vector - RLPy.RVector4
 
  
 
=== __init__( self, qQ ) ===
 
=== __init__( self, qQ ) ===
 +
 +
==== Parameters ====
 +
:'''qQ''' [IN]  a quaternion - RLPy.RQuaternion
  
 
<syntaxhighlight lang="Python">
 
<syntaxhighlight lang="Python">
Line 53: Line 56:
 
print(str(p.x) + ', ' + str(p.y) + ', ' + str(p.z) + ', ' + str(p.w)) # 1.0, 2.0, 3.0, 4.0
 
print(str(p.x) + ', ' + str(p.y) + ', ' + str(p.z) + ', ' + str(p.w)) # 1.0, 2.0, 3.0, 4.0
 
</syntaxhighlight>
 
</syntaxhighlight>
−
 
−
==== Parameters ====
 
−
:'''qQ''' [IN]  a quaternion - RLPy.RQuaternion
 
  
 
=== __init__( self, kAxis, fAngle ) ===
 
=== __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.
 
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 - RLPy.RVector3
 +
:'''fAngle''' [IN] the rotation angle - float
  
 
<syntaxhighlight lang="Python">
 
<syntaxhighlight lang="Python">
Line 68: Line 72:
 
     # 0.0, 0.0, 0.7071067094802856, 0.7071067690849304
 
     # 0.0, 0.0, 0.7071067094802856, 0.7071067690849304
 
</syntaxhighlight>
 
</syntaxhighlight>
−
 
−
==== Parameters ====
 
−
:'''kAxis''' [IN]  the rotation axis - RLPy.RVector3
 
−
:'''fAngle''' [IN] the rotation angle - float
 
  
 
=== __init__( self, kRot ) ===
 
=== __init__( self, kRot ) ===
Line 328: Line 328:
  
 
=== AlmostEqual( self, qQ ) ===
 
=== AlmostEqual( self, qQ ) ===
 +
 +
Determine the two quaternions are almost the same with tolerance: 0.00001.
 +
 +
==== Parameters ====
 +
:'''qQ''' [IN] The target quaternion to check for equivalence - RLPy.RQuaternion
 +
 +
==== Returns ====
 +
:True if the two quaternions are almost the same - bool
  
 
<syntaxhighlight lang="Python">
 
<syntaxhighlight lang="Python">
Line 343: Line 351:
 
     print("p ≈ r")
 
     print("p ≈ r")
 
</syntaxhighlight>
 
</syntaxhighlight>
−
 
−
==== Parameters ====
 
−
:'''qQ''' [IN] The target quaternion to check for equivalence - RLPy.RQuaternion
 
−
 
−
==== Returns ====
 
−
:True if the two quaternions are almost the same - bool
 
  
 
=== Conjugate( self ) ===
 
=== Conjugate( self ) ===
  
 
Conjugate this quaternion.
 
Conjugate this quaternion.
 +
 +
==== Returns ====
 +
:Returns the conjugated quaternion. The result is a quaternion whose x, y, and z values have been negated - RLPy.RQuaternion
  
 
<syntaxhighlight lang="Python">
 
<syntaxhighlight lang="Python">
Line 361: Line 366:
 
print(str(q.x) + ', ' + str(q.y) + ', ' + str(q.z) + ', ' + str(q.w)) # -1.0, -2.0, -3.0, 4.0
 
print(str(q.x) + ', ' + str(q.y) + ', ' + str(q.z) + ', ' + str(q.w)) # -1.0, -2.0, -3.0, 4.0
 
</syntaxhighlight>
 
</syntaxhighlight>
−
 
−
==== Returns ====
 
−
:Returns the conjugated quaternion. The result is a quaternion whose x, y, and z values have been negated - RLPy.RQuaternion
 
  
 
=== Dot( self, qQ ) ===
 
=== Dot( self, qQ ) ===

Revision as of 23:15, 24 February 2020

Main article: Modules.
Last modified: 02/24/2020

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)init

Constructor & Destructor

__init__( self )

The constructor. Initialize a new RQuaternion object without initialization. 

q = RLPy.RQuaternion()

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 RVector4.

Parameters

vV [IN] a 4D vector - RLPy.RVector4
v = RLPy.RVector4(1, 2, 3, 4)
q = RLPy.RQuaternion(v)

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 - RLPy.RQuaternion
v = RLPy.RVector4(1, 2, 3, 4)
q = RLPy.RQuaternion(v)
p = RLPy.RQuaternion(q)

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 - RLPy.RVector3
fAngle [IN] the rotation angle - float
v = RLPy.RVector3(0, 0, 1)
q = RLPy.RQuaternion(v, math.pi/2)

print(str(q.x) + ', ' + str(q.y) + ', ' + str(q.z) + ', ' + str(q.w))
    # 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 - RLPy.RMatrix3
v = RLPy.RVector3(0, 0, 1)
m = RLPy.RMatrix3(v, math.pi/2)
q = RLPy.RQuaternion(m)

print(str(q.x) + ', ' + str(q.y) + ', ' + str(q.z) + ', ' + str(q.w))
    # 0.0, 0.0, 0.7071067690849304, 0.7071067690849304

Operator

=

The "equal to" operator. 

q = RLPy.RQuaternion()
p = q
if q == p:                         # True
    print("equal")

!=

The "not equal to" operator. 

a = RLPy.RVector4(1, 2, 3, 4)
q = RLPy.RQuaternion(a)
b = RLPy.RVector4(2, 2, 3, 4)
p = RLPy.RQuaternion(b)
if a != b:                         #True
    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. 

a = RLPy.RVector4(0, 1, 5, 2)
b = RLPy.RVector4(0, 1, 5, 3)
c = RLPy.RVector4(1, 0, 1, 0)
d = RLPy.RVector4(0, 1, 5, 2)

p = RLPy.RQuaternion(a)
q = RLPy.RQuaternion(b)
r = RLPy.RQuaternion(c)
s = RLPy.RQuaternion(d)

if p< q:                       #True
    print('p< q')
if q< r:                       #True
    print('q< r')
if p< s:                       #False
    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. 

a = RLPy.RVector4(0, 1, 5, 2)
b = RLPy.RVector4(0, 1, 5, 3)
c = RLPy.RVector4(1, 0, 1, 0)
d = RLPy.RVector4(0, 1, 5, 2)

p = RLPy.RQuaternion(a)
q = RLPy.RQuaternion(b)
r = RLPy.RQuaternion(c)
s = RLPy.RQuaternion(d)

if q >p:                       #True
    print('q >p')
if r >q:                       #True
    print('r >q')
if p >s:                       #False
    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. 

a = RLPy.RVector4(0, 1, 5, 2)
b = RLPy.RVector4(0, 1, 5, 3)
c = RLPy.RVector4(1, 0, 1, 0)
d = RLPy.RVector4(0, 1, 5, 2)

p = RLPy.RQuaternion(a)
q = RLPy.RQuaternion(b)
r = RLPy.RQuaternion(c)
s = RLPy.RQuaternion(d)

if p<= q:                       #True
    print('p<= q')
if q<= r:                       #True
    print('q<= r')
if p<= s:                       #True
    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. 

a = RLPy.RVector4(0, 1, 5, 2)
b = RLPy.RVector4(0, 1, 5, 3)
c = RLPy.RVector4(1, 0, 1, 0)
d = RLPy.RVector4(0, 1, 5, 2)

p = RLPy.RQuaternion(a)
q = RLPy.RQuaternion(b)
r = RLPy.RQuaternion(c)
s = RLPy.RQuaternion(d)

if q >= p:                       #True
    print('q >= p')
if r >= q:                       #True
    print('r >= q')
if p >= s:                       #True
    print('p >= s')

+

The "addition" operator. Perform quaternion addition. 

a = RLPy.RVector4(0, 1, 2, 3)
b = RLPy.RVector4(1, 2, 3, 4)
p = RLPy.RQuaternion(a)
q = RLPy.RQuaternion(b)
r = p + q

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. 

a = RLPy.RVector4(0, 1, 2, 3)
b = RLPy.RVector4(3, 2, 1, 0)
p = RLPy.RQuaternion(a)
q = RLPy.RQuaternion(b)
r = q - p

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. 

a = RLPy.RVector4(1, 2, 3, 4)
p = RLPy.RQuaternion(a)
q = p * 2
r = p * p

print(str(q.x) + ', ' + str(q.y) + ', ' + str(q.z) + ', ' + str(q.w)) # 2.0, 4.0, 6.0, 8.0
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. 

a = RLPy.RVector4(1, 2, 3, 4)
p = RLPy.RQuaternion(a)
q = p / 2

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. 

a = RLPy.RVector4(1, 2, 3, 4)
p = RLPy.RQuaternion(a)
q = -p

print(str(q.x) + ', ' + str(q.y) + ', ' + str(q.z) + ', ' + str(q.w)) # -1.0, -2.0, -3.0, -4.0

+ =

The "addition assignment" operator. 

a = RLPy.RVector4(0, 1, 2, 3)
b = RLPy.RVector4(1, 2, 3, 4)
p = RLPy.RQuaternion(a)
q = RLPy.RQuaternion(b)
p += q

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. 

a = RLPy.RVector4(0, 1, 4, 5)
b = RLPy.RVector4(1, 2, 3, 1)
p = RLPy.RQuaternion(a)
q = RLPy.RQuaternion(b)
p -= q

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. 

a = RLPy.RVector4(1, 2, 3, 4)
p = RLPy.RQuaternion(a)
p *= 2

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. 

a = RLPy.RVector4(1, 2, 3, 4)
p = RLPy.RQuaternion(a)
p /= 2

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 the two quaternions are almost the same with tolerance: 0.00001.

Parameters

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

Returns

True if the two quaternions are almost the same - bool
a = RLPy.RVector4(1, 2, 3, 4)
p = RLPy.RQuaternion(a)
q = RLPy.RQuaternion(a)
r = RLPy.RQuaternion(a)

q.w = 4.000000001
r.w = 4.00001

if p.AlmostEqual(q):               #True
    print("p ≈ q")
if q.AlmostEqual(r):               #False
    print("p ≈ r")

Conjugate( self )

Conjugate this quaternion.

Returns

Returns the conjugated quaternion. The result is a quaternion whose x, y, and z values have been negated - RLPy.RQuaternion
a = RLPy.RVector4(1, 2, 3, 4)
p = RLPy.RQuaternion(a)
q = p.Conjugate()

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 dot product of the two quaternions.

Parameters

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

Returns

Returns the value of the dot product - float
a = RLPy.RVector4(1, 2, 3, 4)
b = RLPy.RVector4(1, 2, 3, 0)
p = RLPy.RQuaternion(a)
q = RLPy.RQuaternion(b)
f = p.Dot(q)

print(f)     # 14.0

FromAxisAngle( self, rkAxis, fAngle )

Quaternion from axis angle.

Parameters

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

Returns

Return a new quaternion from a axis angle - RLPy.RQuaternion
p = RLPy.RQuaternion()
v = RLPy.RVector3(0, 0, 1)
p.FromAxisAngle(v, math.pi/2)

print(str(p.x) + ', ' + str(p.y) + ', ' + str(p.z) + ', ' + str(p.w)) # 0.0, 0.0, 0.7071067094802856, 0.7071067690849304

FromRotationMatrix( self, rkRot )

Quaternion from a rotation matrix.

Parameters

rkRot [IN] Rotation matrix - RLPy.RMatrix3

Returns

Return a new quaternion from a rotation matrix - RLPy.RQuaternion
v = RLPy.RVector3(0, 0, 1)
m = RLPy.RMatrix3(v, math.pi/2)
p = RLPy.RQuaternion()
p.FromRotationMatrix(m)

print(str(p.x) + ', ' + str(p.y) + ', ' + str(p.z) + ', ' + str(p.w)) # 0.0, 0.0, 0.7071067690849304, 0.7071067690849304

Inverse( self, rkRot )

Obtain the inverse of this quaternion.

Returns

The inversed quaternion - RLPy.RQuaternion
a = RLPy.RVector4(1, 1, 1, 1)
p = RLPy.RQuaternion(a)
q = p.Inverse()

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 by another quaternion.

Parameters

qQ [IN] The quaternion to multiply - RLPy.RQuaternion

Returns

Returns the multiplied quaternion - RLPy.RQuaternion
a = RLPy.RVector4(1, 2, 3, 4)
b = RLPy.RVector4(1, 2, 2, 1)

p = RLPy.RQuaternion(a)
q = RLPy.RQuaternion(b)
r = p.Multiply(q)

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 - RLPy.RQuaternion

Returns

Returns the multiplied quaternion - RLPy.RQuaternion
a = RLPy.RVector4(1, 2, 3, 4)
b = RLPy.RVector4(1, 2, 2, 1)

p = RLPy.RQuaternion(a)
q = RLPy.RQuaternion(b)
r = p.MultiplyEqual(q)

print(str(r.x) + ', ' + str(r.y) + ', ' + str(r.z) + ', ' + str(r.w)) # 3.0, 11.0, 11.0, -7.0

Normalize( self )

Normalizes this quaternion.

Returns

Returns the normalized quaternion - RLPy.RQuaternion
a = RLPy.RVector4(1, 1, 1, 1)
p = RLPy.RQuaternion(a)
q = p.Normalize()

print(str(q.x) + ', ' + str(q.y) + ', ' + str(q.z) + ', ' + str(q.w))
    # 0.4999999701976776, 0.4999999701976776, 0.4999999701976776, 0.4999999701976776

Rotate180( self )

Rotate 180 degree of this quaternion.

Returns

Returns the rotated quaternion - RLPy.RQuaternion
a = RLPy.RVector4(1, 1, 1, 1)
p = RLPy.RQuaternion(a)
q = p.Normalize()

print(str(q.x) + ', ' + str(q.y) + ', ' + str(q.z) + ', ' + str(q.w))
   #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
a = RLPy.RVector4(1, 2, 3, 4)
p = RLPy.RQuaternion(a)
p.SetX(9)

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
a = RLPy.RVector4(1, 2, 3, 4)
p = RLPy.RQuaternion(a)
p.SetY(9)
print(str(p.x) + ', ' + str(p.y) + ', ' + str(p.z) + ', ' + str(p.w))
    #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
a = RLPy.RVector4(1, 2, 3, 4)
p = RLPy.RQuaternion(a)
p.SetZ(9)
print(str(p.x) + ', ' + str(p.y) + ', ' + str(p.z) + ', ' + str(p.w))
    #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
a = RLPy.RVector4(1, 2, 3, 4)
p = RLPy.RQuaternion(a)
p.SetW(9)
print(str(p.x) + ', ' + str(p.y) + ', ' + str(p.z) + ', ' + str(p.w))
    #1.0, 2.0, 3.0, 9.0
Retrieved from "https://wiki.reallusion.com/index.php?title=IC_Python_API:RLPy_RQuaternion&oldid=4244"