# lib/goog/math/coordinate.js

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