Debian Codegraph @

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

raw
1 // Copyright 2006 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 two-dimensional positions.
17 */
18
19
20 goog.provide('goog.math.Coordinate');
21
22 goog.require('goog.math');
23
24
25
26 /**
27 * Class for representing coordinates and positions.
28 * @param {number=} opt_x Left, defaults to 0.
29 * @param {number=} opt_y Top, defaults to 0.
30 * @struct
31 * @constructor
32 */
33 goog.math.Coordinate = function(opt_x, opt_y) {
34 /**
35 * X-value
36 * @type {number}
37 */
38 this.x = goog.isDef(opt_x) ? opt_x : 0;
39
40 /**
41 * Y-value
42 * @type {number}
43 */
44 this.y = goog.isDef(opt_y) ? opt_y : 0;
45 };
46
47
48 /**
49 * Returns a new copy of the coordinate.
50 * @return {!goog.math.Coordinate} A clone of this coordinate.
51 */
52 goog.math.Coordinate.prototype.clone = function() {
53 return new goog.math.Coordinate(this.x, this.y);
54 };
55
56
57 if (goog.DEBUG) {
58 /**
59 * Returns a nice string representing the coordinate.
60 * @return {string} In the form (50, 73).
61 * @override
62 */
63 goog.math.Coordinate.prototype.toString = function() {
64 return '(' + this.x + ', ' + this.y + ')';
65 };
66 }
67
68
69 /**
70 * Returns whether the specified value is equal to this coordinate.
71 * @param {*} other Some other value.
72 * @return {boolean} Whether the specified value is equal to this coordinate.
73 */
74 goog.math.Coordinate.prototype.equals = function(other) {
75 return other instanceof goog.math.Coordinate &&
76 goog.math.Coordinate.equals(this, other);
77 };
78
79
80 /**
81 * Compares coordinates for equality.
82 * @param {goog.math.Coordinate} a A Coordinate.
83 * @param {goog.math.Coordinate} b A Coordinate.
84 * @return {boolean} True iff the coordinates are equal, or if both are null.
85 */
86 goog.math.Coordinate.equals = function(a, b) {
87 if (a == b) {
88 return true;
89 }
90 if (!a || !b) {
91 return false;
92 }
93 return a.x == b.x && a.y == b.y;
94 };
95
96
97 /**
98 * Returns the distance between two coordinates.
99 * @param {!goog.math.Coordinate} a A Coordinate.
100 * @param {!goog.math.Coordinate} b A Coordinate.
101 * @return {number} The distance between {@code a} and {@code b}.
102 */
103 goog.math.Coordinate.distance = function(a, b) {
104 var dx = a.x - b.x;
105 var dy = a.y - b.y;
106 return Math.sqrt(dx * dx + dy * dy);
107 };
108
109
110 /**
111 * Returns the magnitude of a coordinate.
112 * @param {!goog.math.Coordinate} a A Coordinate.
113 * @return {number} The distance between the origin and {@code a}.
114 */
115 goog.math.Coordinate.magnitude = function(a) {
116 return Math.sqrt(a.x * a.x + a.y * a.y);
117 };
118
119
120 /**
121 * Returns the angle from the origin to a coordinate.
122 * @param {!goog.math.Coordinate} a A Coordinate.
123 * @return {number} The angle, in degrees, clockwise from the positive X
124 * axis to {@code a}.
125 */
126 goog.math.Coordinate.azimuth = function(a) {
127 return goog.math.angle(0, 0, a.x, a.y);
128 };
129
130
131 /**
132 * Returns the squared distance between two coordinates. Squared distances can
133 * be used for comparisons when the actual value is not required.
134 *
135 * Performance note: eliminating the square root is an optimization often used
136 * in lower-level languages, but the speed difference is not nearly as
137 * pronounced in JavaScript (only a few percent.)
138 *
139 * @param {!goog.math.Coordinate} a A Coordinate.
140 * @param {!goog.math.Coordinate} b A Coordinate.
141 * @return {number} The squared distance between {@code a} and {@code b}.
142 */
143 goog.math.Coordinate.squaredDistance = function(a, b) {
144 var dx = a.x - b.x;
145 var dy = a.y - b.y;
146 return dx * dx + dy * dy;
147 };
148
149
150 /**
151 * Returns the difference between two coordinates as a new
152 * goog.math.Coordinate.
153 * @param {!goog.math.Coordinate} a A Coordinate.
154 * @param {!goog.math.Coordinate} b A Coordinate.
155 * @return {!goog.math.Coordinate} A Coordinate representing the difference
156 * between {@code a} and {@code b}.
157 */
158 goog.math.Coordinate.difference = function(a, b) {
159 return new goog.math.Coordinate(a.x - b.x, a.y - b.y);
160 };
161
162
163 /**
164 * Returns the sum of two coordinates as a new goog.math.Coordinate.
165 * @param {!goog.math.Coordinate} a A Coordinate.
166 * @param {!goog.math.Coordinate} b A Coordinate.
167 * @return {!goog.math.Coordinate} A Coordinate representing the sum of the two
168 * coordinates.
169 */
170 goog.math.Coordinate.sum = function(a, b) {
171 return new goog.math.Coordinate(a.x + b.x, a.y + b.y);
172 };
173
174
175 /**
176 * Rounds the x and y fields to the next larger integer values.
177 * @return {!goog.math.Coordinate} This coordinate with ceil'd fields.
178 */
179 goog.math.Coordinate.prototype.ceil = function() {
180 this.x = Math.ceil(this.x);
181 this.y = Math.ceil(this.y);
182 return this;
183 };
184
185
186 /**
187 * Rounds the x and y fields to the next smaller integer values.
188 * @return {!goog.math.Coordinate} This coordinate with floored fields.
189 */
190 goog.math.Coordinate.prototype.floor = function() {
191 this.x = Math.floor(this.x);
192 this.y = Math.floor(this.y);
193 return this;
194 };
195
196
197 /**
198 * Rounds the x and y fields to the nearest integer values.
199 * @return {!goog.math.Coordinate} This coordinate with rounded fields.
200 */
201 goog.math.Coordinate.prototype.round = function() {
202 this.x = Math.round(this.x);
203 this.y = Math.round(this.y);
204 return this;
205 };
206
207
208 /**
209 * Translates this box by the given offsets. If a {@code goog.math.Coordinate}
210 * is given, then the x and y values are translated by the coordinate's x and y.
211 * Otherwise, x and y are translated by {@code tx} and {@code opt_ty}
212 * respectively.
213 * @param {number|goog.math.Coordinate} tx The value to translate x by or the
214 * the coordinate to translate this coordinate by.
215 * @param {number=} opt_ty The value to translate y by.
216 * @return {!goog.math.Coordinate} This coordinate after translating.
217 */
218 goog.math.Coordinate.prototype.translate = function(tx, opt_ty) {
219 if (tx instanceof goog.math.Coordinate) {
220 this.x += tx.x;
221 this.y += tx.y;
222 } else {
223 this.x += Number(tx);
224 if (goog.isNumber(opt_ty)) {
225 this.y += opt_ty;
226 }
227 }
228 return this;
229 };
230
231
232 /**
233 * Scales this coordinate by the given scale factors. The x and y values are
234 * scaled by {@code sx} and {@code opt_sy} respectively. If {@code opt_sy}
235 * is not given, then {@code sx} is used for both x and y.
236 * @param {number} sx The scale factor to use for the x dimension.
237 * @param {number=} opt_sy The scale factor to use for the y dimension.
238 * @return {!goog.math.Coordinate} This coordinate after scaling.
239 */
240 goog.math.Coordinate.prototype.scale = function(sx, opt_sy) {
241 var sy = goog.isNumber(opt_sy) ? opt_sy : sx;
242 this.x *= sx;
243 this.y *= sy;
244 return this;
245 };
246
247
248 /**
249 * Rotates this coordinate clockwise about the origin (or, optionally, the given
250 * center) by the given angle, in radians.
251 * @param {number} radians The angle by which to rotate this coordinate
252 * clockwise about the given center, in radians.
253 * @param {!goog.math.Coordinate=} opt_center The center of rotation. Defaults
254 * to (0, 0) if not given.
255 */
256 goog.math.Coordinate.prototype.rotateRadians = function(radians, opt_center) {
257 var center = opt_center || new goog.math.Coordinate(0, 0);
258
259 var x = this.x;
260 var y = this.y;
261 var cos = Math.cos(radians);
262 var sin = Math.sin(radians);
263
264 this.x = (x - center.x) * cos - (y - center.y) * sin + center.x;
265 this.y = (x - center.x) * sin + (y - center.y) * cos + center.y;
266 };
267
268
269 /**
270 * Rotates this coordinate clockwise about the origin (or, optionally, the given
271 * center) by the given angle, in degrees.
272 * @param {number} degrees The angle by which to rotate this coordinate
273 * clockwise about the given center, in degrees.
274 * @param {!goog.math.Coordinate=} opt_center The center of rotation. Defaults
275 * to (0, 0) if not given.
276 */
277 goog.math.Coordinate.prototype.rotateDegrees = function(degrees, opt_center) {
278 this.rotateRadians(goog.math.toRadians(degrees), opt_center);
279 };