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