Summary

This defines the point3D class which is a special case of a Vector.

/**MathWorx Copyright (c) 2008 Shane Steinert-Threlkeld
Dual-licensed under the MIT and GNU GPL Licenses.
For more information, see LICENSE file */

/**@fileoverview This defines the point3D class which is a special case of a Vector. */

dependencies = ['Vector', 'AffineTransform'];
require(dependencies);

/**Constructor function.  Makes a new 3D point (x,y,z,1).
@class The point3D class defines a point in 3-dimensional Euclidean space via homogeneous coordinates (i.e. as a 4-vector (x,y,z,1)).  This allows affine transformations to be applied to 3-D points via matrix multiplication.
@param {Number} x the x component
@param {Number} y the y component
@param {Number} z the z component
@requires Vector
@constructor */
function point3D(x, y, z) {

	if(x instanceof point3D) {
		return new point3D(x.get(1), x.get(2), x.get(3));
	}

	/**The x-value of the 3D point.
	@type Number */
	this.x = x;
	/**The y-value of the 3D point.
	@type Number */
	this.y = y;
	/**The z-value of the 3D point.
	@type Number */
	this.z = z;
	/**The "dimension" of the point; ALWAYS 3. Important that this.n != 3; gives "illusion" of 3-D vector while allowing multiplication by matrices with 3 columns for transformations
	@type Integer
	@final */
	this.n = 3;
	/**The components of the 3D point.  This allows multiplication by affine transformation matrices and other useful Vector operations.
	@type Array */
	this.components = [this.x, this.y, this.z, 1];

}

point3D.prototype = new Vector;

/**Maps this point to a new 3D point according to a given function.  Overwrites the map function of the Vector class.
Used internally for things like addition, multiplication, dot products, etc.
@param func {Object} the mapping function
@return {point3D} the new, mapped point */
point3D.prototype.map = function(func) {
	var x = func(this.x, 0, 0);
	var y = func(this.y, 1, 0);
	var z = func(this.z, 2, 0);
	return new point3D(x, y, z);
}

/**Rotates a 3D point through an angle phi about the x axis and returns a new 3D point.
@param {Number} phi the angle in radians to rotate the point
@return {point3D} a new point3D object that has been rotated an angle phi around the x axis */
point3D.prototype.rotateX = function(phi) {
	var T = new AffineTransform(3).rotationX(phi);
	return T.applyTo(this);
}

/**Rotates a 3D point through an angle theta about the y axis and returns a new 3D point.
@param {Number} theta the angle in radians to rotate the point
@return {point3D} a new point3D object that has been rotated an angle theta around the y axis */
point3D.prototype.rotateY = function(theta) {
	var vec = new AffineTransform(3).rotationY(theta);
	return T.applyTo(this);
}

/**Rotates a 3D point through an angle psi about the z axis and returns a new 3D point.
@param {Number} psi the angle in radians to rotate the point
@return {point3D} a new point3D object that has been rotated an angle psi around the z axis */
point3D.prototype.rotateZ = function(psi) {
	var T = new AffineTransform(3).rotationZ(psi);
	return T.applyTo(this);
}

/**Rotates a point3D object through an angle theta about an arbitrary axis.
@param {Number} theta the degree (in radians) to rotate the point
@param {Object} axis the axis about which to rotate; either a point3D, 3-D Vector or 3D Array */
point3D.prototype.rotate = function(theta, axis) {
	var T = new AffineTransform(3).rotation(theta, axis);
	return T.applyTo(this);
}

/**Returns a new 3D point (x',y',z',1) = (x+dx,y+dy,z+dz,1).
@param {Number} dx the x translation
@param {Number} dy the y translation
@param {Number} dz the z translation
@return {point3D} a new point3D object that is the original point translated */
point3D.prototype.translate = function(dx,dy,dz) {
	var T = new AffineTransform(3).translate3D(dx,dy,dz);
	return T.applyTo(this);
}

/**Converts a point in Cartesian coordinates to spherical coordinates (r, psi, theta).
@return {point3D} a new point3D (x,y,z,1) = (r (length), arctan(sqrt(x^2+y^2)/z), arctan(y/x)) */
point3D.prototype.toSpherical = function() {
	var r = this.getLength();
	var phi = Math.atan2(Math.sqrt(this.x*this.x + this.y*this.y),this.z);
	var theta = Math.atan2(this.y, this.x);
	return new point3D(r, phi, theta);
}

/**Converts point3D object back to a Vector. Will no longer be homogeneous coordinates.
@return {Vector} the vector [x,y,z] */
point3D.prototype.toVector = function() {
	return new Vector([this.x,this.y,this.z]);
}

/**Produces a string representation of the point.  Overwrites the toString function of the Vector class.
@return {String} the string (x,y,z) */
point3D.prototype.toString = function() {
	return "("+this.x+","+this.y+","+this.z+")";
}

/**A 3D point with coordinates (0,0,0).  A.k.a. "the origin"
@type point3D
@final */
point3D.zero = new point3D(0,0,0);