Merge release-2.4

Release 2.4

.travis.yml

@@ -3,3 +3,6 @@ node_js:
   - 10
   - 12
   - lts/*
+branches:
+  only:
+    - main

README.md

@@ -54,7 +54,7 @@ The functions are grouped in *namespaces*, each focusing on a certain geometry.
 
 ## Coordinate systems and directions
 
-Affineplane uses right-handed coordinate system where the axes are perpendicular to each other. All rotations happen around z-axis and the rotation angle grows from the positive x-axis towards positive y-axis. Because affineplane is primarily intented for web applications, it is customary that, under zero rotation, the x-axis grows right, y-axis grows down, and z-axis grows away from the viewer, as illustrated below.
+Affineplane uses right-handed, orthonormal coordinate system. Due to orthonormality the axes are perpendicular to each other. All rotations happen around z-axis and the rotation angle grows from the positive x-axis towards positive y-axis. Because affineplane is primarily intented for web applications, it is customary that, under zero rotation, the x-axis grows right, y-axis grows down, and z-axis grows away from the viewer, as illustrated below.
 
 ![Right-handed coordinate system](docs/coordinates-directions-3d.png)
 
@@ -127,11 +127,11 @@ Vectors and other movements can only be projected orthogonally. This is because
 
 ## Type safety
 
-Affineplane is very loose on types and requires you to ensure you feed the functions what they minimally expect. This has a benefit: you can input objects that have extra properties. For example `{ color: 'ff00ff', x: 2, y: 3 }` is a valid affineplane [point2](https://axelpale.github.io/affineplane/docs/API.html#affineplanepoint2). Note that while all affineplane operations return new objects, the extra properties are not carried to them.
+Affineplane is very loose on types and requires you to ensure you feed the functions what they minimally expect. This has two benefits: the functions are fast and you can input objects that have extra properties. For example `{ color: 'ff00ff', x: 2, y: 3 }` is a valid affineplane [point2](https://axelpale.github.io/affineplane/docs/API.html#affineplanepoint2). Note that while all affineplane operations return new objects, the extra properties are not carried to them.
 
 To check validity of an object, each geometry type has `validate` function, for example [point2.validate](https://axelpale.github.io/affineplane/docs/API.html#affineplanepoint2validate). We could have included validity checking into each function but that would have caused excess of checking for this kind of low-level math functions. Instead, use `validate` when you need it.
 
-We might have TypeScript bindings in the future.
+To avoid unefficient type checking, optional parameters and default values are used sparsingly. Keep this in mind especially when making contributions.
 
 ## Contribute
 

docs/generate.js

@@ -13,7 +13,11 @@ yamdog.generate({
   // Main title of the document
   title: 'Affineplane API Documentation v' + version,
   // Introduction; the initial paragraph
-  intro: 'Welcome to affineplane API reference documentation.',
+  intro: 'Welcome to affineplane API reference documentation. ' +
+    'See also [Usage](https://axelpale.github.io/affineplane/) and ' +
+    '[GitHub](https://github.com/axelpale/affineplane) for ' +
+    'introduction and source code. The docs are generated with ' +
+    '[yamdog](https://axelpale.github.io/yamdog/).',
   // Styling; decorate the docs
   decorators: [
     decor.aliases(),

lib/dir2/index.js

@@ -9,6 +9,8 @@
 // When a direction is transited between planes, only the rotation of
 // the coordinate space affects the direction.
 //
+// ![Direction angle](docs/geometry_direction.png)
+//
 exports.create = require('./create')
 exports.transitFrom = require('./transitFrom')
 exports.transitTo = require('./transitTo')

lib/dist2/index.js

@@ -5,6 +5,8 @@
 // affects the distance. Rotation or translation of the plane does not
 // change the distance measure.
 //
+// ![Distance transited between planes](docs/projection_distance_2d.png)
+//
 
 exports.create = require('./create')
 exports.transitFrom = require('./transitFrom')

lib/index.js

@@ -32,6 +32,9 @@ exports.plane3 = require('./plane3')
 exports.point2 = require('./point2')
 exports.point3 = require('./point3')
 
+// TODO Ray. A line but into one direction only.
+// exports.ray3 = require('./ray3')
+
 // TODO Rectangle on a two-dimensional plane.
 // exports.rect2 = require('./rect2')
 

lib/plane3/getNormal.js

@@ -0,0 +1,16 @@
+// affineplane.plane3.getNormal(plane)
+//
+// Get a unit vector perpendicular to the plane.
+//
+// Parameters:
+//   plane
+//     a plane3 on the reference plane
+//
+// Return:
+//   a vec3, the plane normal vector.
+//
+module.exports = function (plane) {
+  // Because all planes are on xy, there is one
+  // normal vector shared by all the planes.
+  return { x: 0, y: 0, z: 1 }
+}

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.getNormal = require('./getNormal')
 exports.getScale = require('./getScale')
 exports.inverse = require('./invert')
 exports.invert = exports.inverse

lib/point2/difference.js

@@ -1,5 +1,6 @@
 module.exports = (p, q) => {
   // affineplane.point2.difference(p, q)
+  // affineplane.point2.diff
   // affineplane.point2.delta
   //
   // A vector from point p to point q.

lib/point2/index.js

@@ -5,6 +5,8 @@
 // although the distance between and their mean can be computed.
 // An affine space does not have origin; { x:0, y:0 } is not an origin.
 //
+// ![A point](docs/geometry_point.png)
+//
 
 // exports.add
 // Points cannot be added because no origin.
@@ -18,6 +20,7 @@ exports.copy = require('./copy')
 exports.create = require('./create')
 
 exports.delta = require('./difference')
+exports.diff = exports.delta
 exports.difference = exports.delta
 
 exports.distance = require('./distance')

lib/point3/difference.js

@@ -1,4 +1,5 @@
 // affineplane.point3.difference(p, q)
+// affineplane.point3.diff
 // affineplane.point3.delta
 //
 // A vector from point p to point q.
@@ -12,4 +13,13 @@
 // Return
 //   a vec3
 //
-module.exports = require('../vec3/difference')
+module.exports = (p, q) => {
+  // Inverse of vector subtraction -(p - q)
+  return {
+    x: q.x - p.x,
+    y: q.y - p.y,
+    z: q.z - p.z
+  }
+}
+
+require('../vec3/difference')

lib/point3/index.js

@@ -9,6 +9,7 @@ exports.copy = require('./copy')
 exports.clone = exports.copy
 exports.create = require('./create')
 exports.delta = require('./difference')
+exports.diff = exports.delta
 exports.difference = exports.delta
 exports.distance = require('./distance')
 exports.equal = require('./equal')

lib/vec2/difference.js

@@ -1,7 +1,7 @@
 module.exports = (v, w) => {
   // affineplane.vec2.difference(v, w)
   //
-  // A vector between v and w.
+  // A vector between v and w, in other words, v - w.
   //
   // Parameters:
   //   v

lib/vec2/divide.js

@@ -0,0 +1,28 @@
+module.exports = (vec, divisor) => {
+  // affineplane.vec2.divide(vec, divisor)
+  //
+  // The division of a vector.
+  // Equivalent to multiplying the vector by the inverse of the divisor.
+  // The direction of the vector does not change.
+  //
+  // Parameters:
+  //   vec
+  //     a vec2
+  //   divisor
+  //     a number
+  //
+  // Return
+  //   a vec2
+  //
+  // Throws:
+  //   if zero divisor
+  //
+
+  if (divisor === 0) {
+    throw new Error('Cannot divide vector by zero. Vectors must be finite.')
+  }
+  return {
+    x: vec.x / divisor,
+    y: vec.y / divisor
+  }
+}

lib/vec2/dot.js

@@ -1,7 +1,8 @@
 module.exports = (v, w) => {
   // affineplane.vec2.dot(v, w)
   //
-  // Dot product of two vectors.
+  // The dot product of two vectors,
+  // also called the scalar product.
   //
   // Parameters:
   //   v

lib/vec2/index.js

@@ -3,6 +3,8 @@
 //
 // Vector is a two dimensional dynamic movent between points.
 //
+// ![A vector](docs/geometry_vector.png)
+//
 
 exports.add = require('./add')
 
@@ -16,13 +18,18 @@ exports.create = require('./create')
 
 exports.cross = require('./cross')
 
-exports.difference = require('./difference')
+exports.diff = require('./difference')
+exports.difference = exports.diff
+
+exports.divide = require('./divide')
 
 // exports.distance
 // Vectors do not have distance. See magnitude.
 
 exports.dot = require('./dot')
 
+exports.equal = require('./equal')
+
 exports.fromArray = require('./fromArray')
 
 exports.fromPolar = require('./fromPolar')
@@ -43,6 +50,8 @@ exports.negate = exports.inverse
 
 exports.norm = exports.magnitude
 
+exports.normalize = require('./unit')
+
 exports.opposite = exports.negation
 
 // exports.polarAverage
@@ -56,6 +65,8 @@ exports.rotateTo = require('./rotateTo')
 exports.scaleBy = require('./scaleBy')
 exports.scaleTo = require('./scaleTo')
 
+exports.subtract = exports.diff
+
 exports.sum = require('./sum')
 
 exports.toArray = require('./toArray')
@@ -65,4 +76,6 @@ exports.toPolar = require('./toPolar')
 exports.transitFrom = require('./transitFrom')
 exports.transitTo = require('./transitTo')
 
+exports.unit = exports.normalize
+
 exports.validate = require('./validate')

lib/vec2/scaleBy.js

@@ -1,6 +1,7 @@
 module.exports = (vec, multiplier) => {
   // affineplane.vec2.scaleBy(vec, multiplier)
   //
+  // The scalar multiplication of a vector.
   // Scale the vector by a multiplier.
   // The direction of the vector does not change.
   //

lib/vec2/scaleTo.js

@@ -11,7 +11,7 @@ module.exports = (vec, magnitude) => {
   //   vec
   //     a vec2, non-zero vector.
   //   magnitude
-  //     a number, the target vector length
+  //     a number, the target vector length.
   //
   // Return
   //   a vec2

lib/vec2/unit.js

@@ -0,0 +1,30 @@
+const magnitude = require('./magnitude')
+
+module.exports = (v) => {
+  // affineplane.vec2.unit(v)
+  // affineplane.vec2.normalize
+  //
+  // Get unit vector parallel to the given vector.
+  // The magnitude of unit vector is equal to one.
+  // If zero vector is given, assume direction towards positive x.
+  //
+  // Parameters:
+  //   v
+  //     a vec2
+  //
+  // Return
+  //   a vec2, magnitude of one.
+  //
+  const m = magnitude(v)
+
+  if (m > 0) {
+    return {
+      x: v.x / m,
+      y: v.y / m
+    }
+  }
+  return {
+    x: 1,
+    y: 0
+  }
+}

lib/vec3/difference.js

@@ -1,10 +1,11 @@
 module.exports = (v, w) => {
   // affineplane.vec3.difference(v, w)
   // affineplane.vec3.diff(v, w)
+  // affineplane.vec3.subtract
   //
-  // Get the vector w - v. In other words, if we place v, w
+  // Get the vector v - w. In other words, if we place v, w
   // to begin from the same point then the result is a vector
-  // from the end of v to the end of w.
+  // from the end of w to the end of v.
   //
   // Parameters:
   //   v
@@ -16,8 +17,8 @@ module.exports = (v, w) => {
   //   a vec3
   //
   return {
-    x: w.x - v.x,
-    y: w.y - v.y,
-    z: w.z - v.z
+    x: v.x - w.x,
+    y: v.y - w.y,
+    z: v.z - w.z
   }
 }

lib/vec3/divide.js

@@ -0,0 +1,25 @@
+module.exports = (vec, divisor) => {
+  // affineplane.vec3.divide(vec, divisor)
+  //
+  // The division of a vector.
+  // Equivalent to multiplying the vector by the inverse of the divisor.
+  // The direction of the vector does not change.
+  //
+  // Parameters:
+  //   vec
+  //     a vec3
+  //   divisor
+  //     a number. If zero, will result a vector having infinite length.
+  //
+  // Return
+  //   a vec3
+  //
+  if (divisor === 0) {
+    throw new Error('Cannot divide vector by zero. Vectors must be finite.')
+  }
+  return {
+    x: vec.x / divisor,
+    y: vec.y / divisor,
+    z: vec.z / divisor
+  }
+}

lib/vec3/dot.js

@@ -1,7 +1,8 @@
 module.exports = (v, w) => {
   // affineplane.vec3.dot(v, w)
   //
-  // Dot product of two vectors.
+  // Dot product of two vectors,
+  // also called the scalar product.
   //
   // Parameters:
   //   v

lib/vec3/index.js

@@ -9,8 +9,9 @@ exports.average = require('./average')
 exports.copy = require('./copy')
 exports.create = require('./create')
 exports.cross = require('./cross')
-exports.difference = require('./difference')
-exports.diff = exports.difference
+exports.diff = require('./difference')
+exports.difference = exports.diff
+exports.divide = require('./divide')
 exports.dot = require('./dot')
 exports.equal = require('./equal')
 exports.fromArray = require('./fromArray')
@@ -20,15 +21,19 @@ exports.invert = require('./invert')
 exports.inverse = exports.invert
 exports.magnitude = require('./magnitude')
 exports.negate = exports.invert
+exports.norm = exports.magnitude
+exports.normalize = require('./unit')
 exports.projectTo = require('./projectTo')
 exports.rotateBy = require('./rotateBy')
 exports.rotateTo = require('./rotateTo')
 exports.scaleBy = require('./scaleBy')
 exports.scaleTo = require('./scaleTo')
+exports.subtract = exports.diff
 exports.sum = require('./sum')
 exports.toArray = require('./toArray')
 exports.toPolar = require('./toPolar')
 exports.toSpherical = require('./toSpherical')
 exports.transitFrom = require('./transitFrom')
 exports.transitTo = require('./transitTo')
+exports.unit = exports.normalize
 exports.validate = require('./validate')