Merge release-2.5

Release v2.5.0

lib/helm2/almostEqual.js

@@ -1,7 +1,7 @@
 const EPSILON = require('../epsilon')
 
 module.exports = function (tr, ts, epsilon) {
-  // affineplane.helm2.almostEqual(tr, ts, [epsilon])
+  // affineplane.helm2.almostEqual(tr, ts[, epsilon])
   // affineplane.helm2.almostEquals
   //
   // Are two transforms almost equal? Return true if a matrix norm

lib/helm2/det.js

@@ -14,6 +14,6 @@ module.exports = (tr) => {
   // Return
   //   a number, the determinant.
   //
-  /// See note 2015-10-26-16-30 for analysis.
+  /// See note 2022-09-14-11 for analysis.
   return tr.a * tr.a + tr.b * tr.b
 }

lib/helm2/fromPolar.js

@@ -1,5 +1,5 @@
 module.exports = function (scale, rotation, tx, ty) {
-  // affineplane.helm2.fromPolar(scale, rotation, tx, ty)
+  // affineplane.helm2.fromPolar(scale, rotation[, tx[, ty]])
   //
   // Create a transform object by using scale magnitude,
   // rotation angle, and translation.

lib/helm2/projectTo.js

@@ -2,7 +2,7 @@ const scaleBy = require('./scaleBy')
 const transitTo = require('./transitTo')
 
 module.exports = (tr, plane, camera) => {
-  // affineplane.helm2.projectTo(tr, plane, camera)
+  // affineplane.helm2.projectTo(tr, plane[, camera])
   //
   // Project transformation onto a plane.
   // If camera is given perspectively.

lib/helm3/almostEqual.js

@@ -1,7 +1,7 @@
 const EPSILON = require('../epsilon')
 
 module.exports = function (tr, ts, epsilon) {
-  // affineplane.helm3.almostEqual(tr, ts, [epsilon])
+  // affineplane.helm3.almostEqual(tr, ts[, epsilon])
   // affineplane.helm3.almostEquals
   //
   // Are two transforms almost equal? Return true if a matrix norm

lib/helm3/det.js

@@ -15,5 +15,6 @@ module.exports = (tr) => {
   // Return
   //   a number, the determinant.
   //
+  /// See 2022-09-14-11 for derivation. Astonishingly equals the scale^2.
   return tr.a * tr.a + tr.b * tr.b
 }

lib/plane2/projectTo.js

@@ -2,7 +2,7 @@ const scaleBy = require('./scaleBy')
 const transitTo = require('./transitTo')
 
 module.exports = (plane, target, camera) => {
-  // affineplane.plane2.projectTo(plane, target, camera)
+  // affineplane.plane2.projectTo(plane, target[, camera])
   //
   // Project a 2D plane from reference to the target parallel 2D plane in 3D.
   // If camera is given, project perspectively, otherwise orthogonally.

lib/plane3/projectTo.js

@@ -2,6 +2,8 @@ const scaleBy = require('../plane2/scaleBy')
 const transitTo = require('../plane2/transitTo')
 
 module.exports = (plane, target, camera) => {
+  // affineplane.plane3.projectTo(plane, target[, camera])
+  //
   // Project the plane based on the image plane position
   // and the optional camera position.
   // If camera is given, project perspectively, otherwise orthogonally.

lib/point2/almostEqual.js

@@ -0,0 +1,17 @@
+// affineplane.point2.almostEqual(p, q[, epsilon])
+//
+// Test if points are almost equal by the margin of epsilon.
+//
+// Parameters
+//   p
+//     a point2
+//   q
+//     a point2
+//   epsilon
+//     optional number, default to affineplane.epsilon.
+//     .. Set to 0 for strict comparison.
+//
+// Return
+//   a boolean
+//
+module.exports = require('../vec2/almostEqual')

lib/point2/index.js

@@ -12,6 +12,7 @@
 // Points cannot be added because no origin.
 // See .translate to add a vector.
 
+exports.almostEqual = require('./almostEqual')
 exports.average = require('./average')
 exports.mean = exports.average
 

lib/point2/projectTo.js

@@ -2,7 +2,7 @@ const transitTo = require('./transitTo')
 const homothety = require('./homothety')
 
 module.exports = (point, plane, camera) => {
-  // affineplane.point2.projectTo(point, plane, camera)
+  // affineplane.point2.projectTo(point, plane[, camera])
   //
   // Project a point onto another plane in 3d.
   // If camera is given, project perspectively.

lib/point3/almostEqual.js

@@ -1,4 +1,4 @@
-// affineplane.point3.almostEqual(p, q, [epsilon])
+// affineplane.point3.almostEqual(p, q[, epsilon])
 //
 // Test if points are almost equal by the margin of epsilon.
 //

lib/point3/projectTo.js

@@ -2,7 +2,7 @@ const homothety = require('./homothety')
 const transitTo = require('../point2/transitTo')
 
 module.exports = (point, plane, camera) => {
-  // affineplane.point3.projectTo(point, plane, camera)
+  // affineplane.point3.projectTo(point, plane[, camera])
   //
   // Project a 3D point onto a plane in 3D space.
   //

lib/vec2/almostEqual.js

@@ -1,7 +1,7 @@
 const EPSILON = require('../epsilon')
 
 module.exports = (v, w, epsilon) => {
-  // affineplane.vec2.almostEqual(v, w, [epsilon])
+  // affineplane.vec2.almostEqual(v, w[, epsilon])
   //
   // Test if two vectors v and w are almost equal by the margin of epsilon.
   //

lib/vec2/independent.js

@@ -0,0 +1,25 @@
+const epsilon = require('../epsilon')
+
+module.exports = (v, w) => {
+  // affineplane.vec2.independent(v, w)
+  //
+  // Test if the two vectors are [linearly independent](
+  // https://en.wikipedia.org/wiki/Linear_independence) or almost so
+  // within the margin of affineplane.epsilon.
+  //
+  // Parameters:
+  //   v
+  //     a vec2
+  //   w
+  //     a vec2
+  //
+  // Return
+  //   a boolean, true if vectors are independent.
+  //
+
+  // Dependent when determinant is zero
+  // | v.x  w.x |
+  // | v.y  w.y |
+  //
+  return Math.abs(v.x * w.y - v.y * w.x) > epsilon
+}

lib/vec2/index.js

@@ -1,7 +1,9 @@
 // affineplane.vec2
 // affineplane.vector2
 //
-// Vector is a two dimensional dynamic movent between points.
+// Vector is a two dimensional dynamic movent between points,
+// also known as a displacement vector. See affineplane.point2 for
+// position vectors.
 //
 // ![A vector](geometry_vector.png)
 //
@@ -35,6 +37,8 @@ exports.fromArray = require('./fromArray')
 exports.fromPolar = require('./fromPolar')
 exports.polar = exports.fromPolar
 
+exports.independent = require('./independent')
+
 exports.inverse = require('./inverse')
 exports.invert = exports.inverse
 
@@ -73,6 +77,8 @@ exports.toArray = require('./toArray')
 
 exports.toPolar = require('./toPolar')
 
+exports.transformBy = require('./transformBy')
+
 exports.transitFrom = require('./transitFrom')
 exports.transitTo = require('./transitTo')
 

lib/vec2/projectTo.js

@@ -2,7 +2,7 @@ const scaleBy = require('./scaleBy')
 const transitTo = require('./transitTo')
 
 module.exports = (v, plane, camera) => {
-  // affineplane.vec2.projectTo(v, plane, camera)
+  // affineplane.vec2.projectTo(v, plane[, camera])
   //
   // Project a vector onto another plane.
   // If camera is given, project perspectively.

lib/vec2/transform.js → lib/vec2/transformBy.js

@@ -1,5 +1,5 @@
 module.exports = function (vec, tr) {
-  // affineplane.vec2.transform(vec, tr)
+  // affineplane.vec2.transformBy(vec, tr)
   //
   // Transform a vector. Translation does not affect the vector.
   //

lib/vec3/almostEqual.js

@@ -1,7 +1,7 @@
 const EPSILON = require('../epsilon')
 
 module.exports = (v, w, epsilon) => {
-  // affineplane.vec3.almostEqual(v, w, [epsilon])
+  // affineplane.vec3.almostEqual(v, w[, epsilon])
   //
   // Test if vectors are almost equal by the margin of epsilon.
   //

lib/vec3/independent.js

@@ -0,0 +1,26 @@
+const epsilon = require('../epsilon')
+const cross = require('./cross')
+const abs = Math.abs
+
+module.exports = (v, w) => {
+  // affineplane.vec3.independent(v, w)
+  //
+  // Test if the two vectors are [linearly independent](
+  // https://en.wikipedia.org/wiki/Linear_independence) or almost so
+  // within the margin of affineplane.epsilon.
+  //
+  // Parameters:
+  //   v
+  //     a vec3
+  //   w
+  //     a vec3
+  //
+  // Return
+  //   a boolean, true if vectors are independent.
+  //
+
+  // Dependent when the cross product is zero.
+  // Independnet when non-zero
+  const c = cross(v, w)
+  return abs(c.x) + abs(c.y) + abs(c.z) > epsilon
+}

lib/vec3/index.js

@@ -17,6 +17,7 @@ exports.equal = require('./equal')
 exports.fromArray = require('./fromArray')
 exports.fromPolar = require('./fromPolar')
 exports.fromSpherical = require('./fromSpherical')
+exports.independent = require('./independent')
 exports.invert = require('./invert')
 exports.inverse = exports.invert
 exports.magnitude = require('./magnitude')
@@ -33,6 +34,7 @@ exports.sum = require('./sum')
 exports.toArray = require('./toArray')
 exports.toPolar = require('./toPolar')
 exports.toSpherical = require('./toSpherical')
+exports.transformBy = require('./transformBy')
 exports.transitFrom = require('./transitFrom')
 exports.transitTo = require('./transitTo')
 exports.unit = exports.normalize

lib/vec3/transformBy.js

@@ -0,0 +1,20 @@
+module.exports = function (vec, tr) {
+  // affineplane.vec3.transformBy(vec, tr)
+  //
+  // Transform a vector. Translation does not affect the vector.
+  //
+  // Parameters
+  //   vec
+  //     a vec3
+  //   tr
+  //     a helm3
+  //
+  // Return
+  //   a vec3, the transformed vector
+  //
+  return {
+    x: tr.a * vec.x - tr.b * vec.y,
+    y: tr.b * vec.x + tr.a * vec.y,
+    z: vec.z
+  }
+}

package.json

@@ -1,6 +1,6 @@
 {
   "name": "affineplane",
-  "version": "2.4.0",
+  "version": "2.5.0",
   "description": "Affine plane geometry library",
   "keywords": [
     "affine",

test/point2/almostEqual.test.js

@@ -0,0 +1,13 @@
+const point2 = require('../../lib/point2')
+
+module.exports = (ts) => {
+  ts.test('case: margin', (t) => {
+    const p = { x: 0, y: 0 }
+    const q = { x: 3, y: 3 }
+    t.false(point2.almostEqual(p, q, 1))
+    t.false(point2.almostEqual(p, q, 5))
+    t.true(point2.almostEqual(p, q, 6))
+
+    t.end()
+  })
+}

test/point2/index.test.js

@@ -1,5 +1,6 @@
 // A unit for each method.
 const units = {
+  almostEqual: require('./almostEqual.test'),
   average: require('./average.test'),
   difference: require('./difference.test'),
   homothety: require('./homothety.test'),

test/vec2/independent.test.js

@@ -0,0 +1,32 @@
+const affineplane = require('../../index')
+const vec2 = affineplane.vec2
+
+module.exports = (ts) => {
+  ts.test('case: basic independency', (t) => {
+    t.false(
+      vec2.independent(
+        { x: 0, y: 0 },
+        { x: 0, y: 0 }
+      ),
+      'zero vectors dependent'
+    )
+
+    t.true(
+      vec2.independent(
+        { x: 1, y: 1 },
+        { x: 2, y: 1 }
+      ),
+      'vectors have different direction'
+    )
+
+    t.false(
+      vec2.independent(
+        { x: -1, y: -1 },
+        { x: 2, y: 2 }
+      ),
+      'vectors have opposite direction'
+    )
+
+    t.end()
+  })
+}

test/vec2/index.test.js

@@ -11,6 +11,7 @@ const units = {
   dot: require('./dot.test'),
   equal: require('./equal.test'),
   fromPolar: require('./fromPolar.test'),
+  independent: require('./independent.test'),
   inverse: require('./inverse.test'),
   magnitude: require('./magnitude.test'),
   max: require('./max.test'),
@@ -22,6 +23,7 @@ const units = {
   scaleTo: require('./scaleTo.test'),
   sum: require('./sum.test'),
   toPolar: require('./toPolar.test'),
+  transformBy: require('./transformBy.test'),
   transitFrom: require('./transitFrom.test'),
   transitTo: require('./transitTo.test'),
   unit: require('./unit.test'),

test/vec2/transformBy.test.js

@@ -0,0 +1,35 @@
+const affineplane = require('../../index')
+const vec2 = affineplane.vec2
+
+module.exports = (ts) => {
+  ts.test('case: basic transformation', (t) => {
+    t.almostEqual(
+      vec2.transformBy({ x: 0, y: 0 }, { a: 1, b: 2, x: 3, y: 4 }),
+      { x: 0, y: 0 },
+      'zero vector remains zero'
+    )
+
+    const rot90 = { a: 0, b: 1, x: 0, y: 0 }
+    t.almostEqual(
+      vec2.transformBy({ x: 1, y: -1 }, rot90),
+      { x: 1, y: 1 },
+      'vector is rotated'
+    )
+
+    const rot90tran = { a: 0, b: 1, x: 5, y: 5 }
+    t.almostEqual(
+      vec2.transformBy({ x: 1, y: -1 }, rot90tran),
+      { x: 1, y: 1 },
+      'translation does not affect'
+    )
+
+    const singular = { a: 0, b: 0, x: 0, y: 0 }
+    t.almostEqual(
+      vec2.transformBy({ x: 1, y: -1 }, singular),
+      { x: 0, y: 0 },
+      'singular transform results zero vector'
+    )
+
+    t.end()
+  })
+}