# 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 | * @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 | };