Add support for transformation functions without using proj4js, and make

the SphericalMercator mixin register two transformations to/from EPSG:900913,
EPSG:4326. Thanks to Tim for the feedback and review. (Closes #1210)

This allows us to transform points to/from SphericalMercator 
without proj4js support -- and if other projects need similar functionality, 
they can write their own custom transformation functions rather than 
modifying proj4js to support some custom projection.


git-svn-id: http://svn.openlayers.org/trunk/openlayers@5410 dc9f47b5-9b13-0410-9fdd-eb0c1a62fdaf

apidoc_config/Menu.txt

@@ -168,6 +168,8 @@ Group: OpenLayers  {
       File: Box  (no auto-title, OpenLayers/Marker/Box.js)
       }  # Group: Marker
 
+   File: Projection  (no auto-title, OpenLayers/Projection.js)
+
    Group: Popup  {
 
       File: Popup  (OpenLayers/Popup.js)

doc_config/Menu.txt

@@ -168,6 +168,8 @@ Group: OpenLayers  {
       File: Box  (no auto-title, OpenLayers/Marker/Box.js)
       }  # Group: Marker
 
+   File: Projection  (no auto-title, OpenLayers/Projection.js)
+
    Group: Popup  {
 
       File: Popup  (OpenLayers/Popup.js)

lib/OpenLayers.js

@@ -78,6 +78,7 @@
             "Rico/Color.js",
             "OpenLayers/Ajax.js",
             "OpenLayers/Events.js",
+            "OpenLayers/Projection.js",
             "OpenLayers/Map.js",
             "OpenLayers/Layer.js",
             "OpenLayers/Icon.js",
@@ -175,8 +176,7 @@
             "OpenLayers/Layer/WFS.js",
             "OpenLayers/Control/MouseToolbar.js",
             "OpenLayers/Control/NavToolbar.js",
-            "OpenLayers/Control/EditingToolbar.js",
+            "OpenLayers/Control/EditingToolbar.js"
-            "OpenLayers/Projection.js"
         ); // etc.
 
 

lib/OpenLayers/Layer/SphericalMercator.js

@@ -1,4 +1,5 @@
 /** @requires OpenLayers/Layer.js
+ * @requires OpenLayers/Projection.js
  *
  * Class: OpenLayers.Layer.SphericalMercator
  * A mixin for layers that wraps up the pieces neccesary to have a coordinate
@@ -101,6 +102,55 @@ OpenLayers.Layer.SphericalMercator = {
         lat = 180/Math.PI * (2 * Math.atan(Math.exp(lat * Math.PI / 180)) - Math.PI / 2);
         
         return new OpenLayers.LonLat(lon, lat);
+    },
+
+    /**
+     * Method: projectForward 
+     * Given an object with x and y properties in EPSG:4326, modify the x,y
+     * properties on the object to be the Spherical Mercator projected
+     * coordinates.
+     *
+     * Parameters:
+     * point - {Object} An object with x and y properties. 
+     * 
+     * Returns:
+     * {Object} The point, with the x and y properties transformed to spherical
+     * mercator.
+     */
+    projectForward: function(point) {
+        var lonlat = OpenLayers.Layer.SphericalMercator.forwardMercator(point.x, point.y);
+        point.x = lonlat.lon;
+        point.y = lonlat.lat;
+        return point;
+    },
+    
+    /**
+     * Method: projectForward 
+     * Given an object with x and y properties in Spherical Mercator, modify
+     * the x,y properties on the object to be the unprojected coordinates.
+     *
+     * Parameters:
+     * point - {Object} An object with x and y properties. 
+     * 
+     * Returns:
+     * {Object} The point, with the x and y properties transformed from
+     * spherical mercator to unprojected coordinates..
+     */
+    projectInverse: function(point) {
+        var lonlat = OpenLayers.Layer.SphericalMercator.inverseMercator(point.x, point.y);
+        point.x = lonlat.lon;
+        point.y = lonlat.lat;
+        return point;
     }
 
 };
+
+/**
+ * Note: Two transforms declared
+ * Transforms from EPSG:4326 to EPSG:900913 and from EPSG:900913 to EPSG:4326
+ *     are set by this class.
+ */
+OpenLayers.Projection.addTransform("EPSG:4326", "EPSG:900913",
+    OpenLayers.Layer.SphericalMercator.projectForward);
+OpenLayers.Projection.addTransform("EPSG:900913", "EPSG:4326",
+    OpenLayers.Layer.SphericalMercator.projectInverse);

lib/OpenLayers/Projection.js

@@ -6,7 +6,7 @@
  * @requires OpenLayers/Util.js
  * 
  * Class: OpenLayers.Projection
- * Class for coordinate transformations between coordinate systems.
+ * Class for coordinate transforms between coordinate systems.
  *     Depends on the proj4js library. If proj4js is not available, 
  *     then this is just an empty stub.
  */
@@ -102,21 +102,68 @@ OpenLayers.Projection = OpenLayers.Class({
 });     
 
 /**
- * APIMethod: transform
+ * Property: transforms
- * Read data from a string, and return an object whose type depends on the
+ * Transforms is an object, with from properties, each of which may
- * subclass. 
+ * have a to property. This allows you to define projections without 
+ * requiring support for proj4js to be included.
+ *
+ * This object has keys which correspond to a 'source' projection object.  The
+ * keys should be strings, corresponding to the projection.getCode() value.
+ * Each source projection object should have a set of destination projection
+ * keys included in the object. 
+ * 
+ * Each value in the destination object should be a transformation function,
+ * where the function is expected to be passed an object with a .x and a .y
+ * property.  The function should return the object, with the .x and .y
+ * transformed according to the transformation function.
+ *
+ * Note - Properties on this object should not be set directly.  To add a
+ *     transform method to this object, use the <addTransform> method.  For an
+ *     example of usage, see the OpenLayers.Layer.SphericalMercator file.
+ */
+OpenLayers.Projection.transforms = {};
+
+/**
+ * APIMethod: addTransform
+ * Set a custom transform method between two projections.  Use this method in
+ *     cases where the proj4js lib is not available or where custom projections
+ *     need to be handled.
  *
  * Parameters:
- * point - {object} input horizontal coodinate
+ * from - {String} The code for the source projection
- * sourceProj - {OpenLayers.Projection} source map coordinate system
+ * to - {String} the code for the destination projection
- * destProj - {OpenLayers.Projection} destination map coordinate system
+ * method - {Function} A function that takes a point as an argument and
+ *     transforms that point from the source to the destination projection
+ *     in place.  The original point should be modified.
+ */
+OpenLayers.Projection.addTransform = function(from, to, method) {
+    if(!OpenLayers.Projection.transforms[from]) {
+        OpenLayers.Projection.transforms[from] = {};
+    }
+    OpenLayers.Projection.transforms[from][to] = method;
+};
+
+/**
+ * APIMethod: transform
+ * Transform a point coordinate from one projection to another.  Note that
+ *     the input point is transformed in place.
+ * 
+ * Parameters:
+ * point - {{OpenLayers.Geometry.Point> | Object} An object with x and y
+ *     properties representing coordinates in those dimensions.
+ * sourceProj - {OpenLayers.Projection} Source map coordinate system
+ * destProj - {OpenLayers.Projection} Destination map coordinate system
  *
  * Returns:
- * point - {object} trasnformed coordinate
+ * point - {object} A transformed coordinate.  The original point is modified.
  */
 OpenLayers.Projection.transform = function(point, source, dest) {
     if (source.proj && dest.proj) {
         point = Proj4js.transform(source.proj, dest.proj, point);
+    } else if (source && dest && 
+               OpenLayers.Projection.transforms[source.getCode()] && 
+               OpenLayers.Projection.transforms[source.getCode()][dest.getCode()]) {
+        OpenLayers.Projection.transforms[source.getCode()][dest.getCode()](point); 
     }
     return point;
 };

tests/Layer/test_SphericalMercator.html

@@ -1,9 +1,8 @@
 <html>
 <head>
-    <!-- this gmaps key generated for http://openlayers.org/dev/ -->
     <script src="../../lib/OpenLayers.js"></script>
     <script type="text/javascript">
-    function test_SphericalMercator_forwardProject(t) {
+    function test_SphericalMercator_forwardMercator(t) {
         t.plan(12);
         var arctic = OpenLayers.Layer.SphericalMercator.forwardMercator(0, 85);
         var antarctic = OpenLayers.Layer.SphericalMercator.forwardMercator(0, -85);
@@ -32,7 +31,7 @@
         t.eq(sw.lon, -20037508.34, "SW lon is correct");
     } 
     
-    function test_sphericalMercator_inverseProject(t) {
+    function test_sphericalMercator_inverseMercator(t) {
         t.plan(4);
         var sw =  OpenLayers.Layer.SphericalMercator.inverseMercator(-20037508.34,  -20037508.34);
         var ne =  OpenLayers.Layer.SphericalMercator.inverseMercator(20037508.34,  20037508.34);
@@ -43,6 +42,52 @@
         t.eq(ne.lat, 85.05112877980660, "Northeast lat correct");
     }
 
+    function strToFixed(str, dig) { 
+        if(dig == undefined) { 
+            dig = 5; 
+        } 
+        return str.replace(/(\d+\.\d+)/g, function(match) { 
+            return parseFloat(match).toFixed(dig); 
+        }); 
+    } 
+ 
+    function test_SphericalMercator_projectForward(t) { 
+        t.plan(1);
+        var point = new OpenLayers.Geometry.Point(10, 20); 
+        OpenLayers.Layer.SphericalMercator.projectForward(point); 
+
+        t.eq(strToFixed(point.toString()), 
+             strToFixed("POINT(1113194.9077777779 2273030.9266712805)"), 
+             "point transforms from EPSG:4326 to Spherical Mercator"); 
+    } 
+         
+    function test_SphericalMercator_to4326(t) { 
+        t.plan(1);
+        var point = new OpenLayers.Geometry.Point(1113195, 2273031); 
+
+        OpenLayers.Layer.SphericalMercator.projectInverse(point); 
+         
+        t.eq(strToFixed(point.toString()), 
+             strToFixed("POINT(10.000000828446318 20.000000618997227)"), 
+             "point transforms from EPSG:4326 to Spherical Mercator"); 
+    }
+    
+    function test_SphericalMercator_addTransform(t) {
+        // this class should add two methods to the
+        // OpenLayers.Projection.transforms object
+        t.plan(4);
+        var wgs84 = OpenLayers.Projection.transforms["EPSG:4326"];
+        t.ok(wgs84 instanceof Object, "EPSG:4326 exists in table");
+        
+        var smerc = OpenLayers.Projection.transforms["EPSG:900913"];
+        t.ok(smerc instanceof Object, "EPSG:900913 exists in table");
+        
+        t.ok(wgs84["EPSG:900913"] === OpenLayers.Layer.SphericalMercator.projectForward,
+             "from EPSG:4326 to EPSG:900913 correctly defined");
+        t.ok(smerc["EPSG:4326"] === OpenLayers.Layer.SphericalMercator.projectInverse,
+             "from EPSG:900913 to EPSG:4326 correctly defined");
+    }
+    
   </script> 
 </head>
 <body>