Oolite JavaScript Reference: Vector3D - Revision history

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.

Ahruman: /* Vector Expressions */ Removed vectorOrEntity which isn’t used anywhere.

2011-01-11T22:27:31Z

‎Vector Expressions: Removed vectorOrEntity which isn’t used anywhere.

@@ 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
 <code>u.distanceTo(v)</code> is equivalent to <code>u.[[#subtract|subtract]](v).[[#magnitude|magnitude]]()</code>.
 '''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
 <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>.
 '''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 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.
+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>
 '''Example:'''

@@ 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> ===

@@ Line 5: / Line 5: @@
 === Vector Expressions ===
-All Oolite-provided functions which take a vector as an argument may instead be passed an [[Oolite JavaScript Reference: Entity|Entity]] instead, in which case the entity’s <code>[[Oolite JavaScript Reference: Entity#position|position]]</code> is used. In specifications, this is represented by arguments typed <code>vectorOrEntity</code>.
+All Oolite-provided functions which take a vector as an argument may instead be passed an array of three numbers, or an [[Oolite JavaScript Reference: Entity|Entity]] (in which case the entity’s <code>[[Oolite JavaScript Reference: Entity#position|position]]</code> is used). In specifications, this is represented by arguments typed <code>vectorExpression</code>. For example, if <code>a</code> and <code>b</code> are vectors whose values are (0, 1, 0) and (1, 0, 0) respectively, the following are equivalent:
  var c = a.add(b);