openlayers/lib/OpenLayers/Geometry/Point.js

   1 /* Copyright (c) 2006-2008 MetaCarta, Inc., published under the Clear BSD
   2  * license.  See http://svn.openlayers.org/trunk/openlayers/license.txt for the
   3  * full text of the license. */
   4
   5 /**
   6  * @requires OpenLayers/Geometry.js
   7  */
   8
   9 /**
  10  * Class: OpenLayers.Geometry.Point
  11  * Point geometry class.
  12  *
  13  * Inherits from:
  14  *  - <OpenLayers.Geometry>
  15  */
  16 OpenLayers.Geometry.Point = OpenLayers.Class(OpenLayers.Geometry, {
  17
  18     /**
  19      * APIProperty: x
  20      * {float}
  21      */
  22     x: null,
  23
  24     /**
  25      * APIProperty: y
  26      * {float}
  27      */
  28     y: null,
  29
  30     /**
  31      * Constructor: OpenLayers.Geometry.Point
  32      * Construct a point geometry.
  33      *
  34      * Parameters:
  35      * x - {float}
  36      * y - {float}
  37      *
  38      */
  39     initialize: function(x, y) {
  40         OpenLayers.Geometry.prototype.initialize.apply(this, arguments);
  41
  42         this.x = parseFloat(x);
  43         this.y = parseFloat(y);
  44     },
  45
  46     /**
  47      * APIMethod: clone
  48      *
  49      * Returns:
  50      * {<OpenLayers.Geometry.Point>} An exact clone of this OpenLayers.Geometry.Point
  51      */
  52     clone: function(obj) {
  53         if (obj == null) {
  54             obj = new OpenLayers.Geometry.Point(this.x, this.y);
  55         }
  56
  57         // catch any randomly tagged-on properties
  58         OpenLayers.Util.applyDefaults(obj, this);
  59
  60         return obj;
  61     },
  62
  63     /**
  64      * Method: calculateBounds
  65      * Create a new Bounds based on the lon/lat
  66      */
  67     calculateBounds: function () {
  68         this.bounds = new OpenLayers.Bounds(this.x, this.y,
  69                                             this.x, this.y);
  70     },
  71
  72     /**
  73      * APIMethod: distanceTo
  74      * Calculate the closest distance between two geometries (on the x-y plane).
  75      *
  76      * Parameters:
  77      * geometry - {<OpenLayers.Geometry>} The target geometry.
  78      * options - {Object} Optional properties for configuring the distance
  79      *     calculation.
  80      *
  81      * Valid options:
  82      * details - {Boolean} Return details from the distance calculation.
  83      *     Default is false.
  84      * edge - {Boolean} Calculate the distance from this geometry to the
  85      *     nearest edge of the target geometry.  Default is true.  If true,
  86      *     calling distanceTo from a geometry that is wholly contained within
  87      *     the target will result in a non-zero distance.  If false, whenever
  88      *     geometries intersect, calling distanceTo will return 0.  If false,
  89      *     details cannot be returned.
  90      *
  91      * Returns:
  92      * {Number | Object} The distance between this geometry and the target.
  93      *     If details is true, the return will be an object with distance,
  94      *     x0, y0, x1, and x2 properties.  The x0 and y0 properties represent
  95      *     the coordinates of the closest point on this geometry. The x1 and y1
  96      *     properties represent the coordinates of the closest point on the
  97      *     target geometry.
  98      */
  99     distanceTo: function(geometry, options) {
 100         var edge = !(options && options.edge === false);
 101         var details = edge && options && options.details;
 102         var distance, x0, y0, x1, y1, result;
 103         if(geometry instanceof OpenLayers.Geometry.Point) {
 104             x0 = this.x;
 105             y0 = this.y;
 106             x1 = geometry.x;
 107             y1 = geometry.y;
 108             distance = Math.sqrt(Math.pow(x0 - x1, 2) + Math.pow(y0 - y1, 2));
 109             result = !details ?
 110                 distance : {x0: x0, y0: y0, x1: x1, y1: y1, distance: distance};
 111         } else {
 112             result = geometry.distanceTo(this, options);
 113             if(details) {
 114                 // switch coord order since this geom is target
 115                 result = {
 116                     x0: result.x1, y0: result.y1,
 117                     x1: result.x0, y1: result.y0,
 118                     distance: result.distance
 119                 };
 120             }
 121         }
 122         return result;
 123     },
 124
 125     /**
 126      * APIMethod: equals
 127      * Determine whether another geometry is equivalent to this one.  Geometries
 128      *     are considered equivalent if all components have the same coordinates.
 129      *
 130      * Parameters:
 131      * geom - {<OpenLayers.Geometry.Point>} The geometry to test.
 132      *
 133      * Returns:
 134      * {Boolean} The supplied geometry is equivalent to this geometry.
 135      */
 136     equals: function(geom) {
 137         var equals = false;
 138         if (geom != null) {
 139             equals = ((this.x == geom.x && this.y == geom.y) ||
 140                       (isNaN(this.x) && isNaN(this.y) && isNaN(geom.x) && isNaN(geom.y)));
 141         }
 142         return equals;
 143     },
 144
 145     /**
 146      * Method: toShortString
 147      *
 148      * Returns:
 149      * {String} Shortened String representation of Point object.
 150      *         (ex. <i>"5, 42"</i>)
 151      */
 152     toShortString: function() {
 153         return (this.x + ", " + this.y);
 154     },
 155
 156     /**
 157      * APIMethod: move
 158      * Moves a geometry by the given displacement along positive x and y axes.
 159      *     This modifies the position of the geometry and clears the cached
 160      *     bounds.
 161      *
 162      * Parameters:
 163      * x - {Float} Distance to move geometry in positive x direction.
 164      * y - {Float} Distance to move geometry in positive y direction.
 165      */
 166     move: function(x, y) {
 167         this.x = this.x + x;
 168         this.y = this.y + y;
 169         this.clearBounds();
 170     },
 171
 172     /**
 173      * APIMethod: rotate
 174      * Rotate a point around another.
 175      *
 176      * Parameters:
 177      * angle - {Float} Rotation angle in degrees (measured counterclockwise
 178      *                 from the positive x-axis)
 179      * origin - {<OpenLayers.Geometry.Point>} Center point for the rotation
 180      */
 181     rotate: function(angle, origin) {
 182         angle *= Math.PI / 180;
 183         var radius = this.distanceTo(origin);
 184         var theta = angle + Math.atan2(this.y - origin.y, this.x - origin.x);
 185         this.x = origin.x + (radius * Math.cos(theta));
 186         this.y = origin.y + (radius * Math.sin(theta));
 187         this.clearBounds();
 188     },
 189
 190     /**
 191      * APIMethod: getCentroid
 192      *
 193      * Returns:
 194      * {<OpenLayers.Geometry.Point>} The centroid of the collection
 195      */
 196     getCentroid: function() {
 197         return new OpenLayers.Geometry.Point(this.x, this.y);
 198     },
 199
 200     /**
 201      * APIMethod: resize
 202      * Resize a point relative to some origin.  For points, this has the effect
 203      *     of scaling a vector (from the origin to the point).  This method is
 204      *     more useful on geometry collection subclasses.
 205      *
 206      * Parameters:
 207      * scale - {Float} Ratio of the new distance from the origin to the old
 208      *                 distance from the origin.  A scale of 2 doubles the
 209      *                 distance between the point and origin.
 210      * origin - {<OpenLayers.Geometry.Point>} Point of origin for resizing
 211      * ratio - {Float} Optional x:y ratio for resizing.  Default ratio is 1.
 212      *
 213      * Returns:
 214      * {OpenLayers.Geometry} - The current geometry.
 215      */
 216     resize: function(scale, origin, ratio) {
 217         ratio = (ratio == undefined) ? 1 : ratio;
 218         this.x = origin.x + (scale * ratio * (this.x - origin.x));
 219         this.y = origin.y + (scale * (this.y - origin.y));
 220         this.clearBounds();
 221         return this;
 222     },
 223
 224     /**
 225      * APIMethod: intersects
 226      * Determine if the input geometry intersects this one.
 227      *
 228      * Parameters:
 229      * geometry - {<OpenLayers.Geometry>} Any type of geometry.
 230      *
 231      * Returns:
 232      * {Boolean} The input geometry intersects this one.
 233      */
 234     intersects: function(geometry) {
 235         var intersect = false;
 236         if(geometry.CLASS_NAME == "OpenLayers.Geometry.Point") {
 237             intersect = this.equals(geometry);
 238         } else {
 239             intersect = geometry.intersects(this);
 240         }
 241         return intersect;
 242     },
 243
 244     /**
 245      * APIMethod: transform
 246      * Translate the x,y properties of the point from source to dest.
 247      *
 248      * Parameters:
 249      * source - {<OpenLayers.Projection>}
 250      * dest - {<OpenLayers.Projection>}
 251      *
 252      * Returns:
 253      * {<OpenLayers.Geometry>}
 254      */
 255     transform: function(source, dest) {
 256         if ((source && dest)) {
 257             OpenLayers.Projection.transform(
 258                 this, source, dest);
 259             this.bounds = null;
 260         }
 261         return this;
 262     },
 263
 264     /**
 265      * APIMethod: getVertices
 266      * Return a list of all points in this geometry.
 267      *
 268      * Parameters:
 269      * nodes - {Boolean} For lines, only return vertices that are
 270      *     endpoints.  If false, for lines, only vertices that are not
 271      *     endpoints will be returned.  If not provided, all vertices will
 272      *     be returned.
 273      *
 274      * Returns:
 275      * {Array} A list of all vertices in the geometry.
 276      */
 277     getVertices: function(nodes) {
 278         return [this];
 279     },
 280
 281     CLASS_NAME: "OpenLayers.Geometry.Point"
 282 });