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
};
280

281