Debian Codegraph @

closure-library/closure/goog/math/coordinate3.js

raw
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 new Error('Conversion from an array requires an array of length 3');
170 };