src/third_party/google_input_tools/third_party/closure_library/closure/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 };