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. */
6 * @requires OpenLayers/Util.js
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.
15 OpenLayers.Projection = OpenLayers.Class({
19 * {Object} Proj4js.Proj instance.
30 * Constructor: OpenLayers.Projection
31 * This class offers several methods for interacting with a wrapped
32 * pro4js projection object.
35 * projCode - {String} A string identifying the Well Known Identifier for
37 * options - {Object} An optional object to set additional properties
41 * {<OpenLayers.Projection>} A projection object.
43 initialize: function(projCode, options) {
44 OpenLayers.Util.extend(this, options);
45 this.projCode = projCode;
47 this.proj = new Proj4js.Proj(projCode);
53 * Get the string SRS code.
56 * {String} The SRS code.
59 return this.proj ? this.proj.srsCode : this.projCode;
64 * Get the units string for the projection -- returns null if
65 * proj4js is not available.
68 * {String} The units abbreviation.
70 getUnits: function() {
71 return this.proj ? this.proj.units : null;
76 * Convert projection to string (getCode wrapper).
79 * {String} The projection code.
81 toString: function() {
82 return this.getCode();
87 * Test equality of two projection instances. Determines equality based
88 * soley on the projection code.
91 * {Boolean} The two projections are equivalent.
93 equals: function(projection) {
94 if (projection && projection.getCode) {
95 return this.getCode() == projection.getCode();
102 * Destroy projection object.
104 destroy: function() {
106 delete this.projCode;
109 CLASS_NAME: "OpenLayers.Projection"
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.
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.
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.
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.
132 OpenLayers.Projection.transforms = {};
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.
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.
147 OpenLayers.Projection.addTransform = function(from, to, method) {
148 if(!OpenLayers.Projection.transforms[from]) {
149 OpenLayers.Projection.transforms[from] = {};
151 OpenLayers.Projection.transforms[from][to] = method;
155 * APIMethod: transform
156 * Transform a point coordinate from one projection to another. Note that
157 * the input point is transformed in place.
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
166 * point - {object} A transformed coordinate. The original point is modified.
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);