[develop -> master] New Math functionality

packages/math/arrays.js → packages/math/array.js

@@ -1,9 +1,15 @@
-jsio('import .util');
+jsio('import math.util as util');
 
 /**
- * @namespace
+ * @package math.array;
+ *
+ * Functions to manipulate one or more arrays in tandem.
  */
 
+/**
+ * Returns the weighted average
+ */ 
+
 exports.weightedAverage = function (a, w, n) {
 	n = n || a.length;
 	var s = 0;
@@ -13,14 +19,22 @@ exports.weightedAverage = function (a, w, n) {
 	return s / n;
 }
 
-exports.subtract = function(a, b) {
+/**
+ * Subtract two arrays, (a - b)
+ */
+
+exports.subtract = function (a, b) {
 	var length = a.length,
-		diff = new Array(length);
+			diff = new Array(length);
 	for (var i = 0; i < length; ++i) {
-		diff[i] = b[i] - a[i];
+		diff[i] = a[i] - b[i];
 	}
 	return diff;
-}
+};
+
+/**
+ * Average an array.
+ */
 
 exports.average = function (a, n) {
 	n = n || a.length;
@@ -31,6 +45,10 @@ exports.average = function (a, n) {
 	return s / n;
 }
 
+/**
+ * Return the standard deviation of an array.
+ */
+
 exports.stddev = function (a, n) {
 	var avg = exports.average(a, n);
 	n = n || a.length;
@@ -42,6 +60,10 @@ exports.stddev = function (a, n) {
 	return Math.sqrt(s / (n - 1));
 }
 
+/**
+ * Shuffle an array. Takes an optional random seed.
+ */
+
 exports.shuffle = function(a, randGen) {
 	var len = a.length;
 	for (var i = 0; i < len; ++i) {
@@ -53,6 +75,10 @@ exports.shuffle = function(a, randGen) {
 	return a;
 }
 
+/**
+ * Rotate an array's elements left.
+ */
+
 exports.rotate = function(a, count) {
 	var len = a.length,
 		b = new Array(len),

packages/math/geom/Circle.js

@@ -0,0 +1,40 @@
+import math.geom.Point as Point;
+
+/**
+ * @extends math.geom.Point
+ * Models a circle given a radius.
+ *   Circle(x, y, radius)
+ *   Circle({x: default 0, y: default 0, radius: default 0})
+ */
+exports = Class(Point, function(supr) {
+	this.init = function(a, b, c) {
+		switch(arguments.length) {
+			case 0:
+				this.x = 0;
+				this.y = 0;
+				this.radius = 0;
+				break;
+			case 1:
+			case 2:
+				this.x = a.x || 0;
+				this.y = a.y || 0;
+				this.radius = a.radius || 0;
+				break;
+			case 3:
+				this.x = a;
+				this.y = b;
+				this.radius = c;
+				break;
+		}
+	}
+
+	/**
+	 * Scale the position and radius of this circle by a percentage.
+	 */
+
+	this.scale = function(s) {
+		supr(this, 'scale', arguments);
+		this.radius *= s;
+		return this;
+	}
+});

packages/math/geom/Line.js

@@ -0,0 +1,37 @@
+import math.geom.Point as Point;
+
+exports = Class(function() {
+	this.init = function(a, b, c, d) {
+		switch(arguments.length) {
+			case 0:
+				this.start = new Point();
+				this.end = new Point();
+				break;
+			case 1:
+				this.start = new Point(a.start);
+				this.end = new Point(a.end);
+				break;
+			case 2:
+				this.start = new Point(a);
+				this.end = new Point(b);
+				break;
+			case 3:
+				this.start = new Point(a);
+				this.end = new Point(b, c);
+				break;
+			case 4:
+			default:
+				this.start = new Point(a, b);
+				this.end = new Point(c, d);
+				break;
+		}
+	}
+
+	this.getMagnitude = 
+	this.getLength = function() {
+		var dx = this.end.x - this.start.x,
+			dy = this.end.y - this.start.y;
+
+		return Math.sqrt(dx * dx + dy * dy);
+	}
+});

packages/math/geom/Point.js

@@ -0,0 +1,179 @@
+/**
+ * @package math.geom.Point;
+ * Models a Point in 2D space.
+ */
+
+var Point = exports = Class(function() {
+	this.init = function(a, b) {
+		switch(arguments.length) {
+			case 0:
+				this.x = 0;
+				this.y = 0;
+				break;
+			case 1:
+				this.x = a.x || 0;
+				this.y = a.y || 0;
+				break;
+			case 2:
+				this.x = a || 0;
+				this.y = b || 0;
+				break;
+		}
+	}
+
+	/**
+	 * Rotates this point around the origin by a value in radians.
+	 */
+
+	this.rotate = function(r) {
+		var x = this.x,
+			y = this.y,
+			cosr = Math.cos(r),
+			sinr = Math.sin(r);
+
+		this.x = x * cosr - y * sinr;
+		this.y = x * sinr + y * cosr;
+
+		return this;
+	}
+
+	/**
+	 * Translate this point by two scalars or by another point.
+	 */
+
+	this.translate = this.add = function(x, y) {
+		if (typeof x == 'number') {
+			this.x += x;
+			this.y += y;
+		} else {
+			this.x += x.x;
+			this.y += x.y;
+		}
+		return this;
+	}
+
+	/**
+	 * Subtract this point by two scalars or by another point.
+	 */
+
+	this.subtract = function(x, y) {
+		if (typeof x == 'number') {
+			this.x -= x;
+			this.y -= y;
+		} else {
+			this.x -= x.x;
+			this.y -= x.y;
+		}
+		return this;
+	}
+
+	/**
+	 * Scale this number.
+	 */
+
+	this.scale = function(s) {
+		this.x *= s;
+		this.y *= s;
+		return this;
+	}
+
+	/**
+	 * Set the magnitude of this point at a constant angle.
+	 */
+
+	this.setMagnitude = function(m) {
+		var theta = this.getAngle();
+		this.x = m * Math.cos(theta);
+		this.y = m * Math.sin(theta);
+		return this;
+	}
+
+	/**
+	 * Normalize this point to the unit circle.
+	 */
+
+	this.normalize = function() {
+		var m = this.getMagnitude();
+		this.x /= m;
+		this.y /= m;
+		return this;
+	};
+
+	/**
+	 * Add magnitude to this point.
+	 */
+
+	this.addMagnitude = function(m) {
+		return this.setMagnitude(this.getMagnitude() + m);
+	};
+
+	this.getMagnitude = function() {
+		return Math.sqrt(this.x * this.x + this.y * this.y);
+	};
+
+	this.getSquaredMagnitude = function() {
+		return this.x * this.x + this.y * this.y;
+	};
+
+	this.getDirection = this.getAngle = function() {
+		return Math.atan2(this.y, this.x);
+	};
+
+});
+
+Point.getPolarR = function(x, y) { 
+	throw "notImplemented";
+}
+
+Point.getPolarTheta = function(x, y) { 
+	var val = Math.atan2(y,x) + (Math.PI * 2); 
+	return val > Math.PI * 2 ? val % (Math.PI * 2) : val;
+}
+
+Point.add = Point.translate = function(a, b, c, d) {
+	switch(arguments.length) {
+		case 2: return new Point(a).add(b);
+		case 3: return new Point(a).add(b, c);
+		case 4: return new Point(a, b).add(c, d);
+	}
+}
+
+Point.subtract = function(a, b, c, d) {
+	switch(arguments.length) {
+		case 2: return new Point(a).subtract(b);
+		case 3: return new Point(a).subtract(b, c);
+		case 4: return new Point(a, b).subtract(c, d);
+	}
+}
+
+Point.scale = function(a, b, c) {
+	switch(arguments.length) {
+		case 2: return new Point(a).scale(b);
+		case 3: return new Point(a, b).scale(c);
+	}
+}
+
+Point.setMagnitude = function(a, b, c) {
+	switch(arguments.length) {
+		case 2: return new Point(a).setMagnitude(c);
+		case 3: return new Point(a, b).setMagnitude(c);
+	}
+}
+
+Point.addMagnitude = function(a, b, c) {
+	switch(arguments.length) {
+		case 2: pt = new Point(a); break;
+		case 3: pt = new Point(a, b); b = c; break;
+	}
+
+	return pt.addMagnitude(b);
+}
+
+Point.getMagnitude = function(a, b) { return new Point(a, b).getMagnitude(); }
+
+Point.rotate = function(a, b, c) {
+	switch(arguments.length) {
+		case 2: return new Point(a).rotate(b);
+		case 3: return new Point(a, b).rotate(c);
+	}
+}