Oolite JavaScript Reference: Vector3D - Revision history

Massively Locked: /* Methods */ replaced "function" (x2), added code tags

2022-10-28T19:49:27Z

‎Methods: replaced "function" (x2), added code tags

Milo: expanded caution with example of mistakenly calling distanceTo or squaredDistanceTo on a ship instead of a vector

2020-06-18T22:30:51Z

expanded caution with example of mistakenly calling distanceTo or squaredDistanceTo on a ship instead of a vector

Milo: corrected distanceTo and squaredDistanceTo (my previous understanding was incorrect)

2020-06-18T22:25:06Z

corrected distanceTo and squaredDistanceTo (my previous understanding was incorrect)

Milo: clarified descriptions of distanceTo and squaredDistanceTo and emphasized that both the source and the target must be vectors

2020-06-18T21:16:42Z

clarified descriptions of distanceTo and squaredDistanceTo and emphasized that both the source and the target must be vectors

Ahruman: /* rotationTo */ Noted that both vectors must be normal, and cleaned up.

2012-01-06T16:41:28Z

‎rotationTo: Noted that both vectors must be normal, and cleaned up.

Eric Walch: added info about the need of normalizing a vector in 'rotationTo'

2011-10-01T09:32:28Z

added info about the need of normalizing a vector in 'rotationTo'

Eric Walch: Added example of use for 'rotationTo'

2011-08-06T10:59:32Z

Added example of use for 'rotationTo'

Eric Walch: dot: added examples

2011-07-12T08:17:59Z

dot: added examples

Ahruman: Update for 1.75.

2011-02-20T20:44:59Z

Update for 1.75.

Ahruman: /* Methods */ su goes after sq.

2011-02-12T19:20:53Z

‎Methods: su goes after sq.

@@ Line 62: / Line 62: @@
 <code>u.distanceTo(v)</code> is equivalent to <code>u.[[#subtract|subtract]](v).[[#magnitude|magnitude]]()</code>.
-'''CAUTION:''' If passed an invalid <code>v</code> the function will return zero, not log an error.  It is also incorrect to call distanceTo on something that is not a vector, for example <code>this.ship.distanceTo(v)</code> is missing <code>position</code> and needs to be written as <code>this.ship.position.distanceTo(v)</code>.
+'''CAUTION:''' If passed an invalid <code>v</code>, the method will return zero, not log an error.  It is also incorrect to call <code>distanceTo</code> on something that is not a vector.  For example: <code>this.ship.distanceTo(v)</code> is missing <code>position</code> and needs to be written as <code>this.ship.position.distanceTo(v)</code>.
 '''See Also:''' <code>[[#squaredDistanceTo|squaredDistanceTo]]()</code>
@@ Line 118: / Line 118: @@
 <code>u.squaredDistanceTo(v)</code> is equivalent to <code>u.[[#distanceTo|distanceTo]](v) * u.[[#distanceTo|distanceTo]](v)</code>, or <code>u.[[#subtract|subtract]](v).[[#squaredMagnitude|squaredMagnitude]]()</code>.
-'''CAUTION:''' If passed an invalid <code>v</code> the function will return zero, not log an error.  It is also incorrect to call distanceTo on something that is not a vector, for example <code>this.ship.squaredDistanceTo(v)</code> is missing <code>position</code> and needs to be written as <code>this.ship.position.squaredDistanceTo(v)</code>.
+'''CAUTION:''' If passed an invalid <code>v</code>, the method will return zero, not log an error.  It is also incorrect to call <code>squaredDistanceTo</code> on something that is not a vector.  For example: <code>this.ship.squaredDistanceTo(v)</code> is missing <code>position</code> and needs to be written as <code>this.ship.position.squaredDistanceTo(v)</code>.
 '''See Also:''' <code>[[#distanceTo|distanceTo]]()</code>

@@ Line 62: / Line 62: @@
 <code>u.distanceTo(v)</code> is equivalent to <code>u.[[#subtract|subtract]](v).[[#magnitude|magnitude]]()</code>.
-'''CAUTION:''' If passed an invalid <code>v</code> the function will return zero, not log an error.
+'''CAUTION:''' If passed an invalid <code>v</code> the function will return zero, not log an error.  It is also incorrect to call distanceTo on something that is not a vector, for example <code>this.ship.distanceTo(v)</code> is missing <code>position</code> and needs to be written as <code>this.ship.position.distanceTo(v)</code>.
 '''See Also:''' <code>[[#squaredDistanceTo|squaredDistanceTo]]()</code>
@@ Line 118: / Line 118: @@
 <code>u.squaredDistanceTo(v)</code> is equivalent to <code>u.[[#distanceTo|distanceTo]](v) * u.[[#distanceTo|distanceTo]](v)</code>, or <code>u.[[#subtract|subtract]](v).[[#squaredMagnitude|squaredMagnitude]]()</code>.
-'''CAUTION:''' If passed an invalid <code>v</code> the function will return zero, not log an error.
+'''CAUTION:''' If passed an invalid <code>v</code> the function will return zero, not log an error.  It is also incorrect to call distanceTo on something that is not a vector, for example <code>this.ship.squaredDistanceTo(v)</code> is missing <code>position</code> and needs to be written as <code>this.ship.position.squaredDistanceTo(v)</code>.
 '''See Also:''' <code>[[#distanceTo|distanceTo]]()</code>

@@ Line 58: / Line 58: @@
 === <code>distanceTo</code> ===
   function '''distanceTo'''(v : [[#Vector Expressions|vectorExpression]]) : Number
-Returns the distance between the source vector and vector <code>v</code>.
+Returns the distance between the source vector and <code>v</code>. If <code>v</code> is not a vector, then if it is an [[Oolite JavaScript Reference: Entity|Entity]] its position will be used; and if it is an array of three values (for example, <code>[x, y, z]</code> or <code>[1, 2, 3]</code>), it will be treated as a vector with those coordinates.
 <code>u.distanceTo(v)</code> is equivalent to <code>u.[[#subtract|subtract]](v).[[#magnitude|magnitude]]()</code>.
-'''CAUTION:''' If passed a non-vector, the return code will be zero (no error will be raised).  A common mistake is <code>this.ship.position.distanceTo(thatShip)</code>, which will always return zero!  To fix it, change <code>thatShip</code> to <code>thatShip.position</code>.  Similarly, <code>this.ship.distanceTo(thatShip.position)</code> is incorrect!  It is missing <code>position</code> before <code>distanceTo</code>.
+'''CAUTION:''' If passed an invalid <code>v</code> the function will return zero, not log an error.
 '''See Also:''' <code>[[#squaredDistanceTo|squaredDistanceTo]]()</code>
@@ Line 70: / Line 70: @@
 Returns the [http://en.wikipedia.org/wiki/Vector_%28spatial%29#Dot_product dot product] of the target and <code>v</code>.
-The dot product of two vectors says something how well they are aligned to each other. The dot product of two identical vectors is 1 while two vectors pointing in opposite direction result in a -1 result. Also you can't reliably compare two vectors with each other to see if they are identical. To to check if <code>vector1 == vector2</code> you need the dot product :
+The dot product of two vectors says something how well they are aligned to each other. The dot product of two identical vectors is 1 while two vectors pointing in opposite direction result in a -1 result. Also you can't reliably compare two vectors with each other to see if they are identical. To check if <code>vector1 == vector2</code> you need the dot product :
   vector1.dot(vector2) > 0.999
@@ Line 114: / Line 114: @@
 === <code>squaredDistanceTo</code> ===
   function '''squaredDistanceTo'''(v: [[#Vector Expressions|vectorExpression]]) : Number
-Returns the square of the distance between the source vector and vector <code>v</code>.
+Returns the square of the distance between the source vector and vector <code>v</code>. If <code>v</code> is not a vector, then if it is an [[Oolite JavaScript Reference: Entity|Entity]] its position will be used; and if it is an array of three values (for example, <code>[x, y, z]</code> or <code>[1, 2, 3]</code>), it will be treated as a vector with those coordinates.
 <code>u.squaredDistanceTo(v)</code> is equivalent to <code>u.[[#distanceTo|distanceTo]](v) * u.[[#distanceTo|distanceTo]](v)</code>, or <code>u.[[#subtract|subtract]](v).[[#squaredMagnitude|squaredMagnitude]]()</code>.
-'''CAUTION:''' If passed a non-vector, the return code will be zero (no error will be raised).  A common mistake is <code>this.ship.position.squaredDistanceTo(thatShip)</code>, which will always return zero!  To fix it, change <code>thatShip</code> to <code>thatShip.position</code>.  Similarly, <code>this.ship.squaredDistanceTo(thatShip.position)</code> is incorrect!  It is missing <code>position</code> before <code>squaredDistanceTo</code>.
+'''CAUTION:''' If passed an invalid <code>v</code> the function will return zero, not log an error.
 '''See Also:''' <code>[[#distanceTo|distanceTo]]()</code>

@@ Line 58: / Line 58: @@
 === <code>distanceTo</code> ===
   function '''distanceTo'''(v : [[#Vector Expressions|vectorExpression]]) : Number
-Returns the distance between the target and <code>v</code>.
+Returns the distance between the source vector and vector <code>v</code>.
 <code>u.distanceTo(v)</code> is equivalent to <code>u.[[#subtract|subtract]](v).[[#magnitude|magnitude]]()</code>.
 '''See Also:''' <code>[[#squaredDistanceTo|squaredDistanceTo]]()</code>
@@ Line 112: / Line 114: @@
 === <code>squaredDistanceTo</code> ===
   function '''squaredDistanceTo'''(v: [[#Vector Expressions|vectorExpression]]) : Number
-Returns the square of the distance between the target and <code>v</code>.
+Returns the square of the distance between the source vector and vector <code>v</code>.
 <code>u.squaredDistanceTo(v)</code> is equivalent to <code>u.[[#distanceTo|distanceTo]](v) * u.[[#distanceTo|distanceTo]](v)</code>, or <code>u.[[#subtract|subtract]](v).[[#squaredMagnitude|squaredMagnitude]]()</code>.
 === <code>squaredMagnitude</code> ===

@@ Line 102: / Line 102: @@
 === <code>rotationTo</code> ===
   function '''rotationTo'''(v : [[#Vector Expressions|vectorExpression]] [, maxArc : Number]) : [[Oolite JavaScript Reference: Quaternion|Quaternion]]
-Returns a [[Oolite JavaScript Reference: Quaternion|quaternion]] corresponding to a rotation from the target vector to <code>v</code>. The optional parameter <code>maxArc</code> specifies a maximum rotation angle; if the angle between the target and <code>v</code> is greater than <code>maxArc</code> radians, a rotation of <code>maxArc</code> radians towards <code>vectorExpression</code> is generated instead.<br>
+Returns a [[Oolite JavaScript Reference: Quaternion|quaternion]] corresponding to a rotation from the target vector to <code>v</code>. The optional parameter <code>maxArc</code> specifies a maximum rotation angle; if the angle between the target and <code>v</code> is greater than <code>maxArc</code> radians, a rotation of <code>maxArc</code> radians towards <code>vectorExpression</code> is generated instead.
-Warning: The vector <code>v</code> must be a normalized vector. And a 180 degree rotation is not allowed because there is no defined axis to rotate around for this value.
 '''Example:'''
-  var orientation = myVector.rotationTo(new Vector3D(0,0,1))
+  var orientation = myVector.rotationTo([0, 0, 1])
-This will generate a quaternion were the <code>forwardVector</code> is pointing in the same direction as <code>myVector</code>. (<code>Vector3D(0,0,1)</code> is the forwardVector of the <code>identityQuaternion</code>)
+This will generate a quaternion were the <code>forwardVector</code> is pointing in the same direction as <code>myVector</code>. (<code>[0, 0, 1]</code> is equal to the <code>forwardVector</code> of the identity quaternion.)
 === <code>squaredDistanceTo</code> ===

@@ Line 67: / Line 67: @@
   function '''dot'''(v : [[#Vector Expressions|vectorExpression]]) : Number
 Returns the [http://en.wikipedia.org/wiki/Vector_%28spatial%29#Dot_product dot product] of the target and <code>v</code>.
 '''See Also:''' <code>[[#cross|cross]]()</code>

@@ Line 71: / Line 71: @@
 === <code>fromCoordinateSystem</code> ===
   function '''fromCoordinateSystem'''(system : String) : Vector3D
 Convert a vector from an [[Oolite coordinate systems|abstract coordinate system]] to absolute coordinates. <code>system</code> must be a three-letter string specifying an abstract coordinate system.
@@ Line 125: / Line 124: @@
 === <code>toCoordinateSystem</code> ===
   function '''toCoordinateSystem'''(system : String) : Vector3D
 Convert a vector from absolute coordinates to an [[Oolite coordinate systems|abstract coordinate system]]. <code>system</code> must be a three-letter string specifying an abstract coordinate system. The target of the method must be a vector in absolute coordinates. (To convert a vector from one abstract coordinate system to another, you must first call code>[[#fromCoordinateSystem|fromCoordinateSystem]]()</code>, then <code>toCoordinateSystem()</code>.)

@@ Line 101: / Line 101: @@
   function '''rotationTo'''(v : [[#Vector Expressions|vectorExpression]] [, maxArc : Number]) : [[Oolite JavaScript Reference: Quaternion|Quaternion]]
 Returns a [[Oolite JavaScript Reference: Quaternion|quaternion]] corresponding to a rotation from the target vector to <code>v</code>. The optional parameter <code>maxArc</code> specifies a maximum rotation angle; if the angle between the target and <code>v</code> is greater than <code>maxArc</code> radians, a rotation of <code>maxArc</code> radians towards <code>vectorExpression</code> is generated instead.
 === <code>squaredDistanceTo</code> ===
@@ Line 119: / Line 113: @@
 <code>v.squaredMagnitude()</code> is equivalent to <code>v.[[#magnitude|magnitude]]() * v.[[#magnitude|magnitude]]()</code>.
 === <code>toArray</code> ===