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
20goog.provide('goog.math.Coordinate');
21
22goog.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 */
33goog.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 */
52goog.math.Coordinate.prototype.clone = function() {
53 return new goog.math.Coordinate(this.x, this.y);
54};
55
56
57if (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 */
75goog.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 */
92goog.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 */
104goog.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 */
115goog.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 */
132goog.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 */
147goog.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 */
159goog.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 */
168goog.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 */
179goog.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 */
190goog.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 */
207goog.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 */
229goog.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 */
245goog.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 */
266goog.math.Coordinate.prototype.rotateDegrees = function(degrees, opt_center) {
267 this.rotateRadians(goog.math.toRadians(degrees), opt_center);
268};