Add quaternion nodes

- add 3 nodes: Quaternion In, Quaternion Out and Quaternion Math

Quaternion In:
Provides conversion from various quaternion components to quaternions (selectable via the mode option):
- components wxyz
- angle + axis
- euler angles
- matrix

Quaternion Out:
Provides conversion from quaterions to various quaternion components (selectable via the mode option):
- components wxyz
- angle + axis
- euler angles
- matrix

Quaternion Math:
Provides various quaternion arithmetic operations:

ADD
SUB
MULTIPLY
DIVIDE
ROTATE
DOT
DISTANCE
NEGATE
CONJUGATE
INVERT
NORMALIZE
SCALE
MAGNITUDE

Note: some operations take multiple quaternion inputs (input list grows as new sockets are connected), two quaternion inputs, single quaternion inputs, or quaternion + scalar input.

docs/nodes/quaternion/quaternion_in.rst

@@ -0,0 +1,64 @@
+Quaternion In
+-------------
+
+Quaternion In node constructs quaternions based on various input components provided for a selected mode.
+
+
+Modes
+=====
+
+The available **Modes** are: WXYZ, EULER, AXIS-ANGLE & MATRIX.
+
++============+================================================================+
+| Mode       | Description                                                    |
++------------+----------------------------------------------------------------+
+| WXYZ       | Converts W, X, Y, Z components into a quaternion. [1]          |
++------------+----------------------------------------------------------------+
+| EULER      | Converts X, Y, Z Euler angles and an order of rotation         |
+|            | into a quaternion. [2,3]                                       |
++------------+----------------------------------------------------------------+
+| AXIS-ANGLE | Converts an Axis & an Angle of rotation into a quaternion. [2] |
++------------+----------------------------------------------------------------+
+| MATRIX     | Converts an orthogonal 4x4 rotation matrix into a quaternion.  |
++============+================================================================+
+
+Notes:
+[1] : For WXYZ the node provides a "Normalize" option to generate a normalized quaternion.
+[2] : For EULER and AXIS-ANGLE modes (which take angle input) the node provides an
+angle unit conversion to let the angle values be converted to Radians, Degrees or Unities (0-1 range).
+[3] : For EULER mode the node provides the option to select the Euler rotation order:
+"XYZ", "XZY", "YXZ", "YZX", "ZXY" or "ZYX".
+
+
+Inputs
+======
+
+The node takes a list of various components, based on the selected mode, and it
+constructs the corresponding quaternions. The node is vectorized so the inputs take
+a value or a list of values. When multiple lists are connected the node will
+extend the length of the connected input lists to match the longest one before computing the list of output quaternions.
+
+Based on the selected **Mode** the node makes available the corresponding input sockets:
+
++============+================================+
+| Mode       | Input Sockets (types)          |
++------------+--------------------------------+
+| WXYZ       | W, X, Y, Z  (floats)           |
++------------+--------------------------------+
+| EULER      | X, Y, Z angles (floats)        |
++------------+--------------------------------+
+| AXIS-ANGLE | Axis (Vector) & Angle (float)  |
++------------+--------------------------------+
+| MATRIX     | Matrix (4x4 matrix)            |
++============+================================+
+
+
+Outputs
+=======
+
+**Quaternions**
+
+The node outputs a list of one ore more quaternions based on the given input.
+
+The node only generates the quaternions when the output socket is connected.
+

docs/nodes/quaternion/quaternion_math.rst

@@ -0,0 +1,161 @@
+Quaternion Math Node
+--------------------
+
+The Quaternion Math node performs various artithmetic operations on quaternions.
+
+The available arithmetic operations and their corresponding inputs/outputs are:
+
++============+========+========+=====================================+
+| Operation  | Input  | Output | Description                         |
++============+========+========+=====================================+
+| ADD        |   NQ   |   Q    | Add multiple quaternions            |
+| SUB        |   QQ   |   Q    | Subtract two quaternions            |
+| MULTIPLY   |   NQ   |   Q    | Multiply multiple quaternions       |
+| DIVIDE     |   QQ   |   Q    | Divide two quaternions              |
+| ROTATE     |   QQ   |   Q    | Rotate a quaternion around another  |
+| DOT        |   QQ   |   S    | Dot product two quaternions         |
+| DISTANCE   |   QQ   |   S    | Distance between two quaternions    |
+| NEGATE     |   Q    |   Q    | Negate a quaternion                 |
+| CONJUGATE  |   Q    |   Q    | Conjugate a quaternion              |
+| INVERT     |   Q    |   Q    | Invert a quaternion                 |
+| NORMALIZE  |   Q    |   Q    | Normalize a quaternion              |
+| SCALE      |   QS   |   Q    | Scale a quaternion by given factor  |
+| MAGNITUDE  |   Q    |   S    | Magnitude of a quaternion           |
++============+========+========+=====================================+
+
+where:
+
+NQ = arbitrary number of quaternion inputs
+QQ = two quaternion inputs
+Q  = one quaternion input
+QS = one quaternion + scalar value
+S  = scalar value
+
+For the operations that take multiple quaternion inputs (NQ & QQ) the node provides a PRE / POST option, which lets the node execute the operation on the quaternion inputs in a direct or reverse order. The exceptions to this rule are the ADD, DOT and DISTANCE operations for which the order of quaternions is irrelevant.
+
+For quaternion inputs A and B:
+PRE  = A op B
+POST = B op A
+
+
+Inputs
+======
+The input to the node are lists of quaternions as well as control parameters (like scale etc). For certain operations the node takes arbitrary number of quaternion input lists, for others it takes only two quaternion input lists and for some only one quaternion input list.
+
+The inputs accept single value quaternions or a list of quaternions. The node is vectorized so it will extend the quaternion lists to match the longest input.
+
+
+Operations
+==========
+
+* ADD : adds the components of two or more quaternions
+
+q1 = (w1, x1, y1, z1)
+q2 = (w2, x2, y2, z2)
+
+q1 + q2 = (w1 + w2, x1 + x2, y1 + y2, z1 + z1)
+
+
+* SUB : subtracts the components of two quaternions
+
+q1 = (w1, x1, y1, z1)
+q2 = (w2, x2, y2, z2)
+
+q1 - q2 = (w1 - w2, x1 - x2, y1 - y2, z1 - z2)
+
+
+* MULTIPLY : multiplies two or more quaternions
+
+q1 = (w1, x1, y1, z1) = (w1, V1), where V1 = (x1, y1, z1)
+q2 = (w2, x2, y2, z2) = (w2, V2), where V2 = (x2, y2, z2)
+
+q1 x q2 = (w1 * w2 - V1 * V2, w1 * V1 + w2 * V2 + V1 x V2)
+
+where V1 * V2 is dot product of vectors V1 & V2
+and V1 x V2 is the cross product of vectors V1 & V2
+
+
+* DIVIDE : divide two quaternions (multiply one quaternion with inverse of the other)
+
+q1 = (w1, x1, y1, z1)
+q2 = (w2, x2, y2, z2)
+
+q1 / q2 = q1 x inverse(q2)
+
+
+* ROTATE : rotates one quaternion around the other quaternion
+
+
+* DOT : the dot product of two quaternions
+
+q1 = (w1, x1, y1, z1)
+q2 = (w2, x2, y2, z2)
+
+q1 * q2 = w1 * w2 + x1 * x2 + y1 * y2 + z1 * z2
+
+
+* DISTANCE : the distance between two quaternions
+
+q1 = (w1, x1, y1, z1)
+q2 = (w2, x2, y2, z2)
+
+Distance(q1, q2) = Magnitude(q1 - q2)
+
+
+* NEGATE : negates a quaternion
+
+q = (w, x, y, z)
+
+Negate(q) = (-w, -x, -y, -z)
+
+
+* CONJUGATE : conjugates a quaternion
+
+q = (w, x, y, z)
+
+Conjugate(q) = (w, -x, -y, -z)
+
+
+* INVERT : inverts a quaternion
+
+q = (w, x, y, z)
+
+Inverse(q) = Conjugate(q) / Magnitude(q)^2
+
+
+* NORMALIZE : normalizes a quaternion
+
+q = (w, x, y, z)
+
+Normalize(q) = (w/m, x/m, y/m, z/m)
+
+where m = Magnitude(q)
+
+
+* SCALE : scales the components of a quaternion
+
+q = (w, x, y, z)
+
+s - (float) the scale factor
+sf = (sw, sx, sy, sz) - (array of bools) filters which component is scaled
+
+S = (s if sw else 1, s if sx else 1, s if sy else 1, s if sz else 1)
+
+scale(q, S) = (w * Sw, x * Sx, y * Sy, z * Sz)
+
+
+* MAGNITUDE : the magnitude of a quaternion
+
+q = (w, x, y, z)
+
+Magnitude(q) = sqrt(w * w + x * x + y * y + z * z)
+
+
+Output
+======
+
+**Quaternions** or **Values**
+Depending on the operation the output to the node is either a quaternion list or scalar value list.
+
+The node computes the results (quaternions or scalar values) only when the output socket is connected.
+

docs/nodes/quaternion/quaternion_out.rst

@@ -0,0 +1,59 @@
+Quaternion Out
+--------------
+
+Quaternion Out node converts a quaternion into various formats for a selected mode.
+
+Modes
+=====
+
+The available **Modes** are: WXYZ, EULER, AXIS-ANGLE & MATRIX.
+
++============+==============================================================+
+| Mode       | Description                                                  |
++------------+--------------------------------------------------------------+
+| WXYZ       | Converts a quaternion into its W, X, Y, Z components. [1]    |
++------------+--------------------------------------------------------------+
+| EULER      | Converts a quaternion into X, Y, Z angles corresponding      |
+|            | to the Euler rotation given an Euler rotation order. [2,3]   |
++------------+--------------------------------------------------------------+
+| AXIS-ANGLE | Converts a quaternion into the Axis & Angle of rotation. [2] |
++------------+--------------------------------------------------------------+
+| MATRIX     | Converts a quaternion into an orthogonal 4x4 rotation matrix.|
++============+==============================================================+
+
+Notes:
+[1] : For WXYZ the node provides a "Normalize" option to let the input quaternion
+be normalized before outputting its components.
+[2] : For EULER and AXIS-ANGLE modes, which output angles, the node provides an
+angle unit conversion to let the angle output values be converted to Radians,
+Degrees or Unities (0-1 range).
+[3] : For EULER mode the node provides the option to select the Euler rotation order:
+"XYZ", "XZY", "YXZ", "YZX", "ZXY" or "ZYX".
+
+Inputs
+======
+
+**Quaternions**
+The node takes a list of (one or more) quaternions and based on the selected mode
+it converts the quaternions into the corresponding components.
+
+
+Outputs
+=======
+
+Based on the selected **Mode** the node makes available the corresponding output sockets:
+
++============+================================+
+| Mode       | Output Sockets (types)         |
++------------+--------------------------------+
+| WXYZ       | W, X, Y, Z  (floats)           |
++------------+--------------------------------+
+| EULER      | X, Y, Z angles (floats)        |
++------------+--------------------------------+
+| AXIS-ANGLE | Axis (Vector) & Angle (float)  |
++------------+--------------------------------+
+| MATRIX     | Matrix (4x4 matrix)            |
++============+================================+
+
+The node only generates the conversion when the output sockets are connected.
+

index.md

@@ -345,3 +345,7 @@
     SvOffsetLineNode
     SvContourNode
     SvPlanarEdgenetToPolygons
+    ---
+    SvQuaternionOutNode
+    SvQuaternionInNode
+    SvQuaternionMathNode