Merge release-2.8

Release 2.8

lib/helm2/fromBasisVector.js

@@ -0,0 +1,21 @@
+module.exports = (vec) => {
+  // affineplane.helm2.fromBasisVector(vec)
+  //
+  // Create a linear transformation from the basis vector for x-axis.
+  // This uniquely determines the basis vector for y-axis, at
+  // 90 degrees clock-wise.
+  //
+  // Parameters:
+  //   vec
+  //     a vec2, the basis vector for x-axis.
+  //
+  // Return:
+  //   a helm2, but with zero translation.
+  //
+  return {
+    a: vec.x,
+    b: vec.y,
+    x: 0,
+    y: 0
+  }
+}

lib/helm2/fromVector.js

@@ -0,0 +1,19 @@
+module.exports = (vec) => {
+  // affineplane.helm2.fromVector(vec)
+  //
+  // Create a helm2 transformation from a translation vector.
+  //
+  // Parameters:
+  //   vec
+  //     a vec2, the displacement vector
+  //
+  // Return:
+  //   a helm2
+  //
+  return {
+    a: 1,
+    b: 0,
+    x: vec.x,
+    y: vec.y
+  }
+}

lib/helm2/index.js

@@ -110,8 +110,10 @@ exports.equal = require('./equal')
 exports.equals = exports.equal
 
 exports.fromArray = require('./fromArray')
+exports.fromBasisVector = require('./fromBasisVector')
 exports.fromFeatures = require('./fromFeatures')
 exports.fromPolar = require('./fromPolar')
+exports.fromVector = require('./fromVector')
 
 exports.getDilation = require('./getDilation')
 exports.getRotation = require('./getRotation')

lib/helm3/fromBasisVector.js

@@ -0,0 +1,25 @@
+module.exports = (vec) => {
+  // affineplane.helm3.fromBasisVector(vec)
+  //
+  // Create a linear transformation from the basis vector for x-axis.
+  // This basis vector is limited to 2D and does not have z-component.
+  // This uniquely determines the basis vector for y-axis, at
+  // 90 degrees clock-wise, and consequently the z-axis according to the
+  // right-hand rule.
+  //
+  // Parameters:
+  //   vec
+  //     a vec2, the basis vector for x-axis
+  //     .. in the xy-plane of the reference basis.
+  //
+  // Return:
+  //   a helm2z, but with zero translation.
+  //
+  return {
+    a: vec.x,
+    b: vec.y,
+    x: 0,
+    y: 0,
+    z: 0
+  }
+}

lib/helm3/fromVector.js

@@ -0,0 +1,20 @@
+module.exports = (vec) => {
+  // affineplane.helm3.fromVector(vec)
+  //
+  // Create a helm3 transformation from a translation vector.
+  //
+  // Parameters:
+  //   vec
+  //     a vec3, the displacement vector
+  //
+  // Return:
+  //   a helm3
+  //
+  return {
+    a: 1,
+    b: 0,
+    x: vec.x,
+    y: vec.y,
+    z: (vec.z ? vec.z : 0) // allow vec2 secretly
+  }
+}

lib/helm3/index.js

@@ -102,7 +102,9 @@ exports.det = require('./det')
 exports.determinant = exports.det
 exports.equal = require('./equal')
 exports.fromArray = require('./fromArray')
+exports.fromBasisVector = require('./fromBasisVector')
 exports.fromFeatures = require('./fromFeatures')
+exports.fromVector = require('./fromVector')
 exports.getDilation = require('./getDilation')
 exports.getRotation = require('./getRotation')
 exports.getScale = exports.getDilation

lib/index.js

@@ -1,6 +1,6 @@
 // affineplane
 //
-// The affineplane module provides functions for affine 2D geometry.
+// The affineplane module provides functions for affine 2D and 3D geometry.
 // The functions are grouped in the following submodules.
 //
 

lib/plane2/fromHelmert.js

@@ -0,0 +1,57 @@
+module.exports = function (tr, origin) {
+  // affineplane.plane2.fromHelmert(tr, origin)
+  //
+  // Create a plane by transforming an identity plane about
+  // the given transform origin. For example, you can create
+  // a plane that has been rotated around a point (100, 100).
+  // The choice of transform origin does not affect scale or rotation
+  // of the created plane but does affect its translative component.
+  //
+  // Parameters:
+  //   tr
+  //     a helm2 on the reference plane
+  //   origin
+  //     a point2 on the reference plane
+  //
+  // Return
+  //   a plane2 on the reference plane
+  //
+
+  // Consider affine transformation T = Ax + c, where
+  // - A is a linear transformation
+  // - x is an input vector
+  // - c is a translation vector
+  //
+  // The transform origin works by first translating the input vector
+  // to a vector relative to the origin: (x-o),
+  // then performing the linear transformation (A(x-o)),
+  // and finally translating the output back to the original basis (A(x-o)+o)
+  // The corrected transformation becomes T_o = A(x - o) + o + c
+  //
+  // We can represent the corrected transformation with a single
+  // affine transformation T_o = O * T * iO, where
+  // - O is translation
+  // - iO is its inverse
+  //
+  // Let us represent it with matrices:
+  //   1  0  ox   a -b  tx   1  0 -ox
+  //   0  1  oy * b  a  ty * 0  1 -oy
+  //   0  0  1    0  0  1    0  0  1
+  // And open it:
+  //   1  0  ox   a -b -a*ox+b*oy+tx   a -b -a*ox+b*oy+tx+ox
+  // = 0  1  oy * b  a -b*ox-a*oy+ty = b  a -b*ox-a*oy+ty+oy
+  //   0  0  1    0  0  1              0  0  1
+  //
+
+  const a = tr.a
+  const b = tr.b
+  const ox = origin.x
+  const oy = origin.y
+
+  return {
+    a,
+    b,
+    x: -a * ox + b * oy + tr.x + ox,
+    y: -b * ox - a * oy + tr.y + oy
+  }
+}

lib/plane2/index.js

@@ -32,6 +32,7 @@ exports.create = require('./create')
 exports.difference = exports.between
 exports.equal = require('./equal')
 exports.fromFeatures = require('./fromFeatures')
+exports.fromHelmert = require('./fromHelmert')
 exports.getScale = require('./getScale')
 exports.inverse = require('./invert')
 exports.invert = exports.inverse

lib/plane2/transform.js

@@ -1,32 +1,62 @@
-module.exports = function (plane, tr) {
-  // affineplane.plane2.transform(plane, tr)
+module.exports = function (plane, tr, origin) {
+  // affineplane.plane2.transform(plane, tr[, origin])
   //
-  // Transform the plane with a helmert transformation.
-  // Basically, the plane is a transformation from its internal
-  // coordinate system to the reference coordinate system.
-  // The returned plane is the result when the plane matrix
-  // is multiplied from left by the given transform matrix.
-  // For multiplication from right, see affineplane.plane2.compose.
+  // Transform the plane with a helmert transformation applied at origin.
   //
   // Parameters:
   //   plane
-  //     a plane2 on the reference plane
+  //     a plane2 on the reference basis
   //   tr
-  //     a helm2 on the reference plane
+  //     a helm2 on the reference basis
+  //   origin
+  //     optional point2 on the reference basis. Default `{x:0,y:0}`.
+  //     .. The transformation will be applied to the plane at this point.
   //
   // Return
   //   a plane2 on the reference plane
   //
 
-  // For reading aid:
-  //   |a -b  x|   |a -b  x|
-  //   |b  a  y| * |b  a  y|
-  //   |0  0  1|   |0  0  1|
+  if (!origin) {
+    origin = { x: 0, y: 0 }
+  }
+
+  // Basically, we first convert the helmert transformation T to a plane T_o
+  // by applying it to an identity plane around the origin. See fromHelmert.
+  //
+  //         a -b  tx
+  //     T = b  a  ty
+  //         0  0  1
+  //
+  //         a -b -a*ox+b*oy+tx+ox
+  //   T_o = b  a -b*ox-a*oy+ty+oy
+  //         0  0  1
+  //
+  // Then, because the converted plane is defined on the reference and
+  // applied to the plane outside, we multiply the given plane from the left.
   //
+  //    P' = T_o * P
+  //
+  //         a -b -a*ox+b*oy+tx+ox   c -d  v
+  //       = b  a -b*ox-a*oy+ty+oy * d  c  w
+  //         0  0  1                 0  0  1
+  //
+  //         a*c-b*d  -a*d-b*c  a*v-b*w-a*ox+b*oy+tx+ox
+  //       = b*c+a*d  -b*d+a*c  b*v+a*w-b*ox-a*oy+ty+oy
+  //         0         0        1
+  //
+  const a = tr.a
+  const b = tr.b
+  const c = plane.a
+  const d = plane.b
+  const v = plane.x
+  const w = plane.y
+  const ox = origin.x
+  const oy = origin.y
+
   return {
-    a: tr.a * plane.a - tr.b * plane.b,
-    b: tr.a * plane.b + tr.b * plane.a,
-    x: tr.a * plane.x - tr.b * plane.y + tr.x,
-    y: tr.b * plane.x + tr.a * plane.y + tr.y
+    a: a * c - b * d,
+    b: a * d + b * c,
+    x: a * v - b * w - a * ox + b * oy + tr.x + ox,
+    y: b * v + a * w - b * ox - a * oy + tr.y + oy
   }
 }

lib/plane3/fromHelmert.js

@@ -0,0 +1,66 @@
+module.exports = function (tr, origin) {
+  // affineplane.plane3.fromHelmert(tr, origin)
+  //
+  // Create a plane by applying a transformation to an identity plane
+  // at the given transform origin. For example, you can create
+  // a plane that has been scaled about a point (100, 100, 100).
+  // The choice of transform origin does not affect scale or rotation
+  // of the created plane but does affect its translative component.
+  // Note that any rotation is performed around such a line that is
+  // parallel to z-axis and goes through the given origin point.
+  //
+  // Parameters:
+  //   tr
+  //     a helm2z on the reference plane
+  //   origin
+  //     a point3 on the reference plane.
+  //
+  // Return
+  //   a plane3 on the reference plane
+  //
+
+  // Consider affine transformation T = Ax + c, where
+  // - A is a linear transformation
+  // - x is an input vector
+  // - c is a translation vector
+  //
+  // The transform origin works by first translating the input vector
+  // to a vector relative to the origin: (x-o),
+  // then performing the linear transformation (A(x-o)),
+  // and finally translating the output back to the original basis (A(x-o)+o)
+  // The corrected transformation becomes T_o = A(x - o) + o + c
+  //
+  // We can represent the corrected transformation with a single
+  // affine transformation T_o = O * T * iO, where
+  // - O is translation
+  // - iO is its inverse
+  //
+  // Let us represent it with matrices:
+  //   1  0  0  ox   a -b  0  tx   1  0  0 -ox
+  //   0  1  0  oy * b  a  0  ty * 0  1  0 -oy
+  //   0  0  1  oz   0  0  m  tz   0  0  1 -oz
+  //   0  0  0  1    0  0  0  1    0  0  0  1
+  // where m is the dilation, i.e. the magnitude of vector (a, b).
+  //
+  // Let us compute the matrix result:
+  //   1  0  0  ox   a -b  0 -a*ox+b*oy+tx   a -b  0 -a*ox+b*oy+tx+ox
+  // = 0  1  0  oy * b  a  0 -b*ox-a*oy+ty = b  a  0 -b*ox-a*oy+ty+oy
+  //   0  0  1  oz   0  0  m -m*oz+tz        0  0  m -m*oz+tz+oz
+  //   0  0  0  1    0  0  0  1              0  0  0  1
+  //
+
+  const a = tr.a
+  const b = tr.b
+  const m = Math.sqrt(a * a + b * b)
+  const ox = origin.x
+  const oy = origin.y
+  const oz = (origin.z ? origin.z : 0)
+
+  return {
+    a,
+    b,
+    x: -a * ox + b * oy + tr.x + ox,
+    y: -b * ox - a * oy + tr.y + oy,
+    z: -m * oz + tr.z + oz
+  }
+}

lib/plane3/index.js

@@ -34,6 +34,7 @@ exports.create = require('./create')
 exports.difference = exports.between
 exports.equal = require('./equal')
 exports.fromFeatures = require('./fromFeatures')
+exports.fromHelmert = require('./fromHelmert')
 exports.getNormal = require('./getNormal')
 exports.getScale = require('./getScale')
 exports.inverse = require('./invert')