openlayers/lib/OpenLayers/Projection.js

   1 /* Copyright (c) 2006-2008 MetaCarta, Inc., published under a modified BSD license.
   2  * See http://svn.openlayers.org/trunk/openlayers/repository-license.txt
   3  * for the full text of the license. */
   4
   5 /**
   6  * @requires OpenLayers/Util.js
   7  */
   8
   9 /**
  10  * Class: OpenLayers.Projection
  11  * Class for coordinate transforms between coordinate systems.
  12  *     Depends on the proj4js library. If proj4js is not available,
  13  *     then this is just an empty stub.
  14  */
  15 OpenLayers.Projection = OpenLayers.Class({
  16
  17     /**
  18      * Property: proj
  19      * {Object} Proj4js.Proj instance.
  20      */
  21     proj: null,
  22
  23     /**
  24      * Property: projCode
  25      * {String}
  26      */
  27     projCode: null,
  28
  29     /**
  30      * Constructor: OpenLayers.Projection
  31      * This class offers several methods for interacting with a wrapped
  32      *     pro4js projection object.
  33      *
  34      * Parameters:
  35      * projCode - {String} A string identifying the Well Known Identifier for
  36      *    the projection.
  37      * options - {Object} An optional object to set additional properties
  38      *     on the layer.
  39      *
  40      * Returns:
  41      * {<OpenLayers.Projection>} A projection object.
  42      */
  43     initialize: function(projCode, options) {
  44         OpenLayers.Util.extend(this, options);
  45         this.projCode = projCode;
  46         if (window.Proj4js) {
  47             this.proj = new Proj4js.Proj(projCode);
  48         }
  49     },
  50
  51     /**
  52      * APIMethod: getCode
  53      * Get the string SRS code.
  54      *
  55      * Returns:
  56      * {String} The SRS code.
  57      */
  58     getCode: function() {
  59         return this.proj ? this.proj.srsCode : this.projCode;
  60     },
  61
  62     /**
  63      * APIMethod: getUnits
  64      * Get the units string for the projection -- returns null if
  65      *     proj4js is not available.
  66      *
  67      * Returns:
  68      * {String} The units abbreviation.
  69      */
  70     getUnits: function() {
  71         return this.proj ? this.proj.units : null;
  72     },
  73
  74     /**
  75      * Method: toString
  76      * Convert projection to string (getCode wrapper).
  77      *
  78      * Returns:
  79      * {String} The projection code.
  80      */
  81     toString: function() {
  82         return this.getCode();
  83     },
  84
  85     /**
  86      * Method: equals
  87      * Test equality of two projection instances.  Determines equality based
  88      *     soley on the projection code.
  89      *
  90      * Returns:
  91      * {Boolean} The two projections are equivalent.
  92      */
  93     equals: function(projection) {
  94         if (projection && projection.getCode) {
  95             return this.getCode() == projection.getCode();
  96         } else {
  97             return false;
  98         }
  99     },
 100
 101     /* Method: destroy
 102      * Destroy projection object.
 103      */
 104     destroy: function() {
 105         delete this.proj;
 106         delete this.projCode;
 107     },
 108
 109     CLASS_NAME: "OpenLayers.Projection"
 110 });
 111
 112 /**
 113  * Property: transforms
 114  * Transforms is an object, with from properties, each of which may
 115  * have a to property. This allows you to define projections without
 116  * requiring support for proj4js to be included.
 117  *
 118  * This object has keys which correspond to a 'source' projection object.  The
 119  * keys should be strings, corresponding to the projection.getCode() value.
 120  * Each source projection object should have a set of destination projection
 121  * keys included in the object.
 122  *
 123  * Each value in the destination object should be a transformation function,
 124  * where the function is expected to be passed an object with a .x and a .y
 125  * property.  The function should return the object, with the .x and .y
 126  * transformed according to the transformation function.
 127  *
 128  * Note - Properties on this object should not be set directly.  To add a
 129  *     transform method to this object, use the <addTransform> method.  For an
 130  *     example of usage, see the OpenLayers.Layer.SphericalMercator file.
 131  */
 132 OpenLayers.Projection.transforms = {};
 133
 134 /**
 135  * APIMethod: addTransform
 136  * Set a custom transform method between two projections.  Use this method in
 137  *     cases where the proj4js lib is not available or where custom projections
 138  *     need to be handled.
 139  *
 140  * Parameters:
 141  * from - {String} The code for the source projection
 142  * to - {String} the code for the destination projection
 143  * method - {Function} A function that takes a point as an argument and
 144  *     transforms that point from the source to the destination projection
 145  *     in place.  The original point should be modified.
 146  */
 147 OpenLayers.Projection.addTransform = function(from, to, method) {
 148     if(!OpenLayers.Projection.transforms[from]) {
 149         OpenLayers.Projection.transforms[from] = {};
 150     }
 151     OpenLayers.Projection.transforms[from][to] = method;
 152 };
 153
 154 /**
 155  * APIMethod: transform
 156  * Transform a point coordinate from one projection to another.  Note that
 157  *     the input point is transformed in place.
 158  *
 159  * Parameters:
 160  * point - {{OpenLayers.Geometry.Point> | Object} An object with x and y
 161  *     properties representing coordinates in those dimensions.
 162  * sourceProj - {OpenLayers.Projection} Source map coordinate system
 163  * destProj - {OpenLayers.Projection} Destination map coordinate system
 164  *
 165  * Returns:
 166  * point - {object} A transformed coordinate.  The original point is modified.
 167  */
 168 OpenLayers.Projection.transform = function(point, source, dest) {
 169     if (source.proj && dest.proj) {
 170         point = Proj4js.transform(source.proj, dest.proj, point);
 171     } else if (source && dest &&
 172                OpenLayers.Projection.transforms[source.getCode()] &&
 173                OpenLayers.Projection.transforms[source.getCode()][dest.getCode()]) {
 174         OpenLayers.Projection.transforms[source.getCode()][dest.getCode()](point);
 175     }
 176     return point;
 177 };