Merge pull request #10 from stackgl/quat-opt

Optimize transformQuat

Author: rreusser

README.md

@@ -217,7 +217,7 @@ var scale = require('gl-vec3/scale')
 
 ## transformQuat(out:vec3, a:vec3, q:quat)
 
-  Transforms the vec3 with a quat
+  Transforms the vec3 with a unit quat
 
 ## License
 

test/index.js

@@ -294,7 +294,15 @@ test('transformMat4', function (t) {
 })
 
 test('transformQuat', function (t) {
-  var result = vec3.transformQuat([], [3, 4, 5], [6, 7, 8, 9])
-  t.deepEqual(result, [882, 824, 1090])
+  // Construct unit quaternion q manually
+  const l = Math.sqrt(1 * 1 + 2 * 2 + 2 * 2 + 4 * 4)
+  const q = [1 / l, 2 / l, -2 / l, 4 / l]
+
+  var result = vec3.transformQuat([], [3, 4, 5], q)
+  t.deepEqual(result, [
+      6.6800000000000015,
+      -2.2400000000000007,
+      0.5999999999999992
+  ])
   t.end()
 })

transformQuat.js

@@ -3,26 +3,35 @@ module.exports = transformQuat;
 /**
  * Transforms the vec3 with a quat
  *
+ * Note: the quaternion must be a unit quaternion (|q| = 1) in
+ * order for this operation to be valid.
+ *
  * @param {vec3} out the receiving vector
  * @param {vec3} a the vector to transform
- * @param {quat} q quaternion to transform with
+ * @param {quat} q unit quaternion to transform with
  * @returns {vec3} out
  */
 function transformQuat(out, a, q) {
-    // benchmarks: http://jsperf.com/quaternion-transform-vec3-implementations
+    // Fast Vector Rotation using Quaternions by Robert Eisele
+    // https://raw.org/proof/vector-rotation-using-quaternions/
 
     var x = a[0], y = a[1], z = a[2],
-        qx = q[0], qy = q[1], qz = q[2], qw = q[3],
+        qx = q[0], qy = q[1], qz = q[2], qw = q[3]
+
+    // t = q x v
+    var tx = qy * z - qz * y
+    var ty = qz * x - qx * z
+    var tz = qx * y - qy * x
+
+    // t = 2t
+    tx *= 2
+    ty *= 2
+    tz *= 2
 
-        // calculate quat * vec
-        ix = qw * x + qy * z - qz * y,
-        iy = qw * y + qz * x - qx * z,
-        iz = qw * z + qx * y - qy * x,
-        iw = -qx * x - qy * y - qz * z
+    // v + w t + q x t
+    out[0] = x + qw * tx + qy * tz - qz * ty
+    out[1] = y + qw * ty + qz * tx - qx * tz
+    out[2] = z + qw * tz + qx * ty - qy * tx
 
-    // calculate result * inverse quat
-    out[0] = ix * qw + iw * -qx + iy * -qz - iz * -qy
-    out[1] = iy * qw + iw * -qy + iz * -qx - ix * -qz
-    out[2] = iz * qw + iw * -qz + ix * -qy - iy * -qx
     return out
-}
+}