add initial Line3.js with unit tests.

src/math/Line3.js

@@ -0,0 +1,111 @@
+/**
+ * @author bhouston / http://exocortex.com
+ */
+
+THREE.Line3 = function ( start, end ) {
+
+	this.start = ( start !== undefined ) ? start : new THREE.Vector3();
+	this.end = ( end !== undefined ) ? end : new THREE.Vector3();
+
+};
+
+THREE.extend( THREE.Line3.prototype, {
+
+	set: function ( start, end ) {
+
+		this.start.copy( start );
+		this.end.copy( end );
+
+		return this;
+
+	},
+
+	copy: function ( line ) {
+
+		this.start.copy( line.start );
+		this.end.copy( line.end );
+
+		return this;
+
+	},
+
+	center: function ( optionalTarget ) {
+
+		var result = optionalTarget || new THREE.Vector3();
+		return result.addVectors( this.start, this.end ).multiplyScalar( 0.5 );
+
+	},
+
+	delta: function ( optionalTarget ) {
+
+		var result = optionalTarget || new THREE.Vector3();
+		return result.subVectors( this.end, this.start );
+
+	},
+
+	distanceSq: function ( optionalTarget ) {
+
+		return this.start.distanceToSquared( this.end );
+
+	},
+
+	distance: function ( optionalTarget ) {
+
+		return this.start.distanceTo( this.end );
+
+	},
+
+	at: function ( t, optionalTarget ) {
+
+		var result = optionalTarget || new THREE.Vector3();
+
+		return this.delta( result ).multiplyScalar( t ).add( this.start );
+
+	},
+
+	closestPointToPoint: function() {
+
+		var startP = new THREE.Vector3();
+		var startEnd = new THREE.Vector3();
+
+		return function ( point, optionalTarget ) {
+
+			var result = optionalTarget || new THREE.Vector3();
+
+			startP.subVectors( point, this.start );
+			startEnd.subVectors( this.end, this.start );
+
+			var startEnd2 = startEnd.dot( startEnd );
+			var startEnd_startP = startEnd.dot( startP );
+
+			var t = startEnd_startP / startEnd2;
+	        t = THREE.Math.clamp( t, 0, 1 );
+
+	        return result.copy( startEnd ).multiplyScalar( t ).add( this.start );
+
+		};
+
+	}(),
+
+	transform: function ( matrix ) {
+
+		this.start.applyMatrix4( matrix );
+		this.end.applyMatrix4( matrix );
+
+		return this;
+
+	},
+
+	equals: function ( line ) {
+
+		return line.start.equals( this.start ) && line.end.equals( this.end );
+
+	},
+
+	clone: function () {
+
+		return new THREE.Line3().copy( this );
+
+	}
+
+} );

test/unit/math/Line3.js

@@ -0,0 +1,63 @@
+/**
+ * @author bhouston / http://exocortex.com
+ */
+
+module( "Line3" );
+
+test( "constructor/equals", function() {
+	var a = new THREE.Line3();
+	ok( a.start.equals( zero3 ), "Passed!" );
+	ok( a.end.equals( zero3 ), "Passed!" );
+
+	a = new THREE.Line3( two3.clone(), one3.clone() );
+	ok( a.start.equals( two3 ), "Passed!" );
+	ok( a.end.equals( one3 ), "Passed!" );
+});
+
+test( "copy/equals", function() {
+	var a = new THREE.Line3( zero3.clone(), one3.clone() );
+	var b = new THREE.Line3().copy( a );
+	ok( b.start.equals( zero3 ), "Passed!" );
+	ok( b.end.equals( one3 ), "Passed!" );
+
+	// ensure that it is a true copy
+	a.start = zero3;
+	a.end = one3;
+	ok( b.start.equals( zero3 ), "Passed!" );
+	ok( b.end.equals( one3 ), "Passed!" );
+});
+
+test( "set", function() {
+	var a = new THREE.Line3();
+
+	a.set( one3, one3 );
+	ok( a.start.equals( one3 ), "Passed!" );
+	ok( a.end.equals( one3 ), "Passed!" );
+});
+
+test( "at", function() {
+	var a = new THREE.Line3( one3.clone(), new THREE.Vector3( 1, 1, 2 ) );
+
+	ok( a.at( -1 ).distanceTo( new THREE.Vector3( 1, 1, 0 ) ) < 0.0001, "Passed!" );
+	ok( a.at( 0 ).distanceTo( one3 ) < 0.0001, "Passed!" );
+	ok( a.at( 1 ).distanceTo( new THREE.Vector3( 1, 1, 2 ) ) < 0.0001, "Passed!" );
+	ok( a.at( 2 ).distanceTo( new THREE.Vector3( 1, 1, 3 ) ) < 0.0001, "Passed!" );
+});
+
+
+test( "closestPointToPoint", function() {
+	var a = new THREE.Line3( one3.clone(), new THREE.Vector3( 1, 1, 2 ) );
+
+	// nearby the ray
+	var b1 = a.closestPointToPoint( zero3 );
+	console.log( b1 );
+	ok( b1.distanceTo( new THREE.Vector3( 1, 1, 1 ) ) < 0.0001, "Passed!" );
+
+	// nearby the ray
+	var b = a.closestPointToPoint( new THREE.Vector3( 1, 1, 5 ) );
+	ok( b.distanceTo( new THREE.Vector3( 1, 1, 2 ) ) < 0.0001, "Passed!" );
+
+	// exactly on the ray
+	var c = a.closestPointToPoint( one3 );
+	ok( c.distanceTo( one3 ) < 0.0001, "Passed!" );
+});

test/unit/unittests_sources.html

@@ -17,6 +17,7 @@
   <script src="../../src/math/Vector2.js"></script>
   <script src="../../src/math/Vector3.js"></script>
   <script src="../../src/math/Vector4.js"></script>
+  <script src="../../src/math/Line3.js"></script>
   <script src="../../src/math/Box2.js"></script>
   <script src="../../src/math/Box3.js"></script>
   <script src="../../src/math/Matrix3.js"></script>
@@ -25,7 +26,7 @@
   <script src="../../src/math/Frustum.js"></script>
   <script src="../../src/math/Plane.js"></script>
   <script src="../../src/math/Sphere.js"></script>
-  <script src="../../src/math/Math.js"></script>
+  <script src="../../src/math/Math.js"></script>  
   <script src="../../src/math/Triangle.js"></script>
 
   <!-- add class-based unit tests below -->
@@ -40,6 +41,7 @@
   <script src="math/Vector2.js"></script>
   <script src="math/Vector3.js"></script>
   <script src="math/Vector4.js"></script>
+  <script src="math/Line3.js"></script>
   <script src="math/Quaternion.js"></script>
   <script src="math/Matrix3.js"></script>
   <script src="math/Matrix4.js"></script>

test/unit/unittests_three-math.html

@@ -25,6 +25,7 @@
   <script src="math/Vector2.js"></script>
   <script src="math/Vector3.js"></script>
   <script src="math/Vector4.js"></script>
+  <script src="math/Line3.js"></script>
   <script src="math/Quaternion.js"></script>
   <script src="math/Matrix3.js"></script>
   <script src="math/Matrix4.js"></script>

test/unit/unittests_three.html

@@ -25,6 +25,7 @@
   <script src="math/Vector2.js"></script>
   <script src="math/Vector3.js"></script>
   <script src="math/Vector4.js"></script>
+  <script src="math/Line3.js"></script>
   <script src="math/Quaternion.js"></script>
   <script src="math/Matrix3.js"></script>
   <script src="math/Matrix4.js"></script>

test/unit/unittests_three.min.html

@@ -25,6 +25,7 @@
   <script src="math/Vector2.js"></script>
   <script src="math/Vector3.js"></script>
   <script src="math/Vector4.js"></script>
+  <script src="math/Line3.js"></script>
   <script src="math/Quaternion.js"></script>
   <script src="math/Matrix3.js"></script>
   <script src="math/Matrix4.js"></script>

utils/build/includes/math.json

@@ -5,6 +5,7 @@
 	"src/math/Vector2.js",
 	"src/math/Vector3.js",
 	"src/math/Vector4.js",
+	"src/math/Line3.js",
 	"src/math/Box2.js",
 	"src/math/Box3.js",
 	"src/math/Matrix3.js",