1
// Copyright 2008 The Closure Library Authors. All Rights Reserved.
2
//
3
// Licensed under the Apache License, Version 2.0 (the "License");
4
// you may not use this file except in compliance with the License.
5
// You may obtain a copy of the License at
6
//
7
//      http://www.apache.org/licenses/LICENSE-2.0
8
//
9
// Unless required by applicable law or agreed to in writing, software
10
// distributed under the License is distributed on an "AS-IS" BASIS,
11
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12
// See the License for the specific language governing permissions and
13
// limitations under the License.
14

15
/**
16
 * @fileoverview A utility class for representing three-dimensional points.
17
 *
18
 * Based heavily on coordinate.js by:
19
 */
20

21
goog.provide('goog.math.Coordinate3');
22

23

24

25
/**
26
 * Class for representing coordinates and positions in 3 dimensions.
27
 *
28
 * @param {number=} opt_x X coordinate, defaults to 0.
29
 * @param {number=} opt_y Y coordinate, defaults to 0.
30
 * @param {number=} opt_z Z coordinate, defaults to 0.
31
 * @struct
32
 * @constructor
33
 */
34
goog.math.Coordinate3 = function(opt_x, opt_y, opt_z) {
35
  /**
36
   * X-value
37
   * @type {number}
38
   */
39
  this.x = goog.isDef(opt_x) ? opt_x : 0;
40

41
  /**
42
   * Y-value
43
   * @type {number}
44
   */
45
  this.y = goog.isDef(opt_y) ? opt_y : 0;
46

47
  /**
48
   * Z-value
49
   * @type {number}
50
   */
51
  this.z = goog.isDef(opt_z) ? opt_z : 0;
52
};
53

54

55
/**
56
 * Returns a new copy of the coordinate.
57
 *
58
 * @return {!goog.math.Coordinate3} A clone of this coordinate.
59
 */
60
goog.math.Coordinate3.prototype.clone = function() {
61
  return new goog.math.Coordinate3(this.x, this.y, this.z);
62
};
63

64

65
if (goog.DEBUG) {
66
  /**
67
   * Returns a nice string representing the coordinate.
68
   *
69
   * @return {string} In the form (50, 73, 31).
70
   * @override
71
   */
72
  goog.math.Coordinate3.prototype.toString = function() {
73
    return '(' + this.x + ', ' + this.y + ', ' + this.z + ')';
74
  };
75
}
76

77

78
/**
79
 * Compares coordinates for equality.
80
 *
81
 * @param {goog.math.Coordinate3} a A Coordinate3.
82
 * @param {goog.math.Coordinate3} b A Coordinate3.
83
 * @return {boolean} True iff the coordinates are equal, or if both are null.
84
 */
85
goog.math.Coordinate3.equals = function(a, b) {
86
  if (a == b) {
87
    return true;
88
  }
89
  if (!a || !b) {
90
    return false;
91
  }
92
  return a.x == b.x && a.y == b.y && a.z == b.z;
93
};
94

95

96
/**
97
 * Returns the distance between two coordinates.
98
 *
99
 * @param {goog.math.Coordinate3} a A Coordinate3.
100
 * @param {goog.math.Coordinate3} b A Coordinate3.
101
 * @return {number} The distance between {@code a} and {@code b}.
102
 */
103
goog.math.Coordinate3.distance = function(a, b) {
104
  var dx = a.x - b.x;
105
  var dy = a.y - b.y;
106
  var dz = a.z - b.z;
107
  return Math.sqrt(dx * dx + dy * dy + dz * dz);
108
};
109

110

111
/**
112
 * Returns the squared distance between two coordinates. Squared distances can
113
 * be used for comparisons when the actual value is not required.
114
 *
115
 * Performance note: eliminating the square root is an optimization often used
116
 * in lower-level languages, but the speed difference is not nearly as
117
 * pronounced in JavaScript (only a few percent.)
118
 *
119
 * @param {goog.math.Coordinate3} a A Coordinate3.
120
 * @param {goog.math.Coordinate3} b A Coordinate3.
121
 * @return {number} The squared distance between {@code a} and {@code b}.
122
 */
123
goog.math.Coordinate3.squaredDistance = function(a, b) {
124
  var dx = a.x - b.x;
125
  var dy = a.y - b.y;
126
  var dz = a.z - b.z;
127
  return dx * dx + dy * dy + dz * dz;
128
};
129

130

131
/**
132
 * Returns the difference between two coordinates as a new
133
 * goog.math.Coordinate3.
134
 *
135
 * @param {goog.math.Coordinate3} a A Coordinate3.
136
 * @param {goog.math.Coordinate3} b A Coordinate3.
137
 * @return {!goog.math.Coordinate3} A Coordinate3 representing the difference
138
 *     between {@code a} and {@code b}.
139
 */
140
goog.math.Coordinate3.difference = function(a, b) {
141
  return new goog.math.Coordinate3(a.x - b.x, a.y - b.y, a.z - b.z);
142
};
143

144

145
/**
146
 * Returns the contents of this coordinate as a 3 value Array.
147
 *
148
 * @return {!Array<number>} A new array.
149
 */
150
goog.math.Coordinate3.prototype.toArray = function() {
151
  return [this.x, this.y, this.z];
152
};
153

154

155
/**
156
 * Converts a three element array into a Coordinate3 object.  If the value
157
 * passed in is not an array, not array-like, or not of the right length, an
158
 * error is thrown.
159
 *
160
 * @param {Array<number>} a Array of numbers to become a coordinate.
161
 * @return {!goog.math.Coordinate3} A new coordinate from the array values.
162
 * @throws {Error} When the oject passed in is not valid.
163
 */
164
goog.math.Coordinate3.fromArray = function(a) {
165
  if (a.length <= 3) {
166
    return new goog.math.Coordinate3(a[0], a[1], a[2]);
167
  }
168

169
  throw Error('Conversion from an array requires an array of length 3');
170
};
171

172