Rename projection functions for a friendlier API

The following functions are renamed:

getTransform -> getTransformForProjections
getTransformFromCodes -> getTransform
transform -> transformWithProjections
transformWithCodes -> transform

With this change, the faster functions that avoid projection look-up
have longer names and are used internally, whereas the slower but
friendlier short name functions are available for users.

examples/anchored-elements.js

@@ -25,7 +25,7 @@ var map = new ol.Map({
 // Vienna label
 var vienna = new ol.AnchoredElement({
   map: map,
-  position: ol.projection.transformWithCodes(
+  position: ol.projection.transform(
       new ol.Coordinate(16.3725, 48.208889), 'EPSG:4326', 'EPSG:3857'),
   element: document.getElementById('vienna')
 });
@@ -39,7 +39,7 @@ map.addEventListener('click', function(evt) {
   var coordinate = evt.getCoordinate();
   popup.getElement().innerHTML =
       'Welcome to ol3. The location you clicked was<br>' +
-      ol.Coordinate.toStringHDMS(ol.projection.transformWithCodes(
+      ol.Coordinate.toStringHDMS(ol.projection.transform(
           coordinate, 'EPSG:3857', 'EPSG:4326'));
   popup.setPosition(coordinate);
 });

examples/animation.js

@@ -9,15 +9,15 @@ goog.require('ol.projection');
 goog.require('ol.source.OpenStreetMap');
 
 
-var london = ol.projection.transformWithCodes(
+var london = ol.projection.transform(
     new ol.Coordinate(-0.12755, 51.507222), 'EPSG:4326', 'EPSG:3857');
-var moscow = ol.projection.transformWithCodes(
+var moscow = ol.projection.transform(
     new ol.Coordinate(37.6178, 55.7517), 'EPSG:4326', 'EPSG:3857');
-var instanbul = ol.projection.transformWithCodes(
+var instanbul = ol.projection.transform(
     new ol.Coordinate(28.9744, 41.0128), 'EPSG:4326', 'EPSG:3857');
-var rome = ol.projection.transformWithCodes(
+var rome = ol.projection.transform(
     new ol.Coordinate(12.5, 41.9), 'EPSG:4326', 'EPSG:3857');
-var bern = ol.projection.transformWithCodes(
+var bern = ol.projection.transform(
     new ol.Coordinate(7.4458, 46.95), 'EPSG:4326', 'EPSG:3857');
 
 var map = new ol.Map({

examples/bing-maps.js

@@ -19,7 +19,7 @@ var map = new ol.Map({
   renderers: ol.RendererHints.createFromQueryData(),
   target: 'map',
   view: new ol.View2D({
-    center: ol.projection.transformWithCodes(
+    center: ol.projection.transform(
         new ol.Coordinate(-123.1, 49.25), 'EPSG:4326', 'EPSG:3857'),
     zoom: 8
   })

examples/canvas-tiles.js

@@ -25,7 +25,7 @@ var layers = [
 
 var webglMap = new ol.Map({
   view: new ol.View2D({
-    center: ol.projection.transformWithCodes(
+    center: ol.projection.transform(
         new ol.Coordinate(-0.1275, 51.507222), 'EPSG:4326', 'EPSG:3857'),
     zoom: 10
   }),

examples/mapquest.js

@@ -16,7 +16,7 @@ var map = new ol.Map({
   renderers: ol.RendererHints.createFromQueryData(),
   target: 'map',
   view: new ol.View2D({
-    center: ol.projection.transformWithCodes(
+    center: ol.projection.transform(
         new ol.Coordinate(139.6917, 35.689506), 'EPSG:4326', 'EPSG:3857'),
     zoom: 9
   })

examples/side-by-side.js

@@ -11,9 +11,9 @@ goog.require('ol.projection');
 goog.require('ol.source.MapQuestOpenAerial');
 
 
-var LONDON = ol.projection.transformWithCodes(
+var LONDON = ol.projection.transform(
     new ol.Coordinate(-0.12755, 51.507222), 'EPSG:4326', 'EPSG:3857');
-var MOSCOW = ol.projection.transformWithCodes(
+var MOSCOW = ol.projection.transform(
     new ol.Coordinate(37.6178, 55.7517), 'EPSG:4326', 'EPSG:3857');
 
 var layer = new ol.layer.TileLayer({

examples/stamen.js

@@ -23,7 +23,7 @@ var map = new ol.Map({
   renderers: ol.RendererHints.createFromQueryData(),
   target: 'map',
   view: new ol.View2D({
-    center: ol.projection.transformWithCodes(
+    center: ol.projection.transform(
         new ol.Coordinate(-122.416667, 37.783333), 'EPSG:4326', 'EPSG:3857'),
     zoom: 12
   })

src/ol/control/mousepositioncontrol.js

@@ -169,7 +169,7 @@ ol.control.MousePosition.prototype.updateHTML_ = function(pixel) {
   if (!goog.isNull(pixel)) {
     if (this.renderedProjection_ != this.mapProjection_) {
       if (!goog.isNull(this.projection_)) {
-        this.transform_ = ol.projection.getTransform(
+        this.transform_ = ol.projection.getTransformFromProjections(
             this.mapProjection_, this.projection_);
       } else {
         this.transform_ = ol.projection.identityTransform;

src/ol/control/scalelinecontrol.js

@@ -176,7 +176,7 @@ ol.control.ScaleLine.prototype.updateElement_ = function(frameState) {
 
     // Convert pointResolution from meters or feet to degrees
     if (goog.isNull(this.toEPSG4326_)) {
-      this.toEPSG4326_ = ol.projection.getTransform(
+      this.toEPSG4326_ = ol.projection.getTransformFromProjections(
           projection, ol.projection.get('EPSG:4326'));
     }
     var vertex = [center.x, center.y];

src/ol/geolocation.js

@@ -76,7 +76,7 @@ ol.Geolocation.prototype.disposeInternal = function() {
 ol.Geolocation.prototype.handleProjectionChanged_ = function() {
   var projection = this.getProjection();
   if (goog.isDefAndNotNull(projection)) {
-    this.transformFn_ = ol.projection.getTransform(
+    this.transformFn_ = ol.projection.getTransformFromProjections(
         ol.projection.get('EPSG:4326'), projection);
     if (!goog.isNull(this.position_)) {
       var vertex = [this.position_.x, this.position_.y];

src/ol/projection.exports

@@ -15,7 +15,7 @@
 @exportSymbol ol.projection.addProjection
 @exportSymbol ol.projection.get
 @exportSymbol ol.projection.getTransform
-@exportSymbol ol.projection.getTransformFromCodes
+@exportSymbol ol.projection.getTransformFromProjections
 @exportSymbol ol.projection.transform
-@exportSymbol ol.projection.transformWithCodes
+@exportSymbol ol.projection.transformWithProjections
 @exportSymbol ol.projection.configureProj4jsProjection

src/ol/projection.js

@@ -218,7 +218,7 @@ ol.Proj4jsProjection_.prototype.getPointResolution =
     // measuring its width and height on the normal sphere, and taking the
     // average of the width and height.
     if (goog.isNull(this.toEPSG4326_)) {
-      this.toEPSG4326_ = ol.projection.getTransform(
+      this.toEPSG4326_ = ol.projection.getTransformFromProjections(
           this, ol.projection.getProj4jsProjectionFromCode_({
             code: 'EPSG:4326',
             extent: null
@@ -430,7 +430,7 @@ ol.projection.removeTransform = function(source, destination) {
 
 /**
  * @param {ol.ProjectionLike} projectionLike Either a code string which is a
- *     combination of authority and identifier such as “EPSG:4326”, or an
+ *     combination of authority and identifier such as "EPSG:4326", or an
  *     existing projection object, or undefined.
  * @return {ol.Projection} Projection.
  */
@@ -499,24 +499,43 @@ ol.projection.equivalent = function(projection1, projection2) {
   } else if (projection1.getUnits() != projection2.getUnits()) {
     return false;
   } else {
-    var transformFn = ol.projection.getTransform(projection1, projection2);
+    var transformFn = ol.projection.getTransformFromProjections(
+        projection1, projection2);
     return transformFn === ol.projection.cloneTransform;
   }
 };
 
 
+/**
+ * Given the projection-like objects this method searches for a transformation
+ * function to convert a coordinates array from the source projection to the
+ * destination projection.
+ *
+ * @param {ol.ProjectionLike} source Source.
+ * @param {ol.ProjectionLike} destination Destination.
+ * @return {ol.TransformFunction} Transform.
+ */
+ol.projection.getTransform = function(source, destination) {
+  var sourceProjection = ol.projection.get(source);
+  var destinationProjection = ol.projection.get(destination);
+  return ol.projection.getTransformFromProjections(
+      sourceProjection, destinationProjection);
+};
+
+
 /**
  * Searches a function that can be used to convert coordinates from the source
  * projection to the destination projection.
  *
- * @param {ol.Projection} source Source.
+ * @param {ol.Projection} sourceProjection Source projection.
- * @param {ol.Projection} destination Destination.
+ * @param {ol.Projection} destinationProjection Destination projection.
  * @return {ol.TransformFunction} Transform.
  */
-ol.projection.getTransform = function(source, destination) {
+ol.projection.getTransformFromProjections =
+    function(sourceProjection, destinationProjection) {
   var transforms = ol.projection.transforms_;
-  var sourceCode = source.getCode();
+  var sourceCode = sourceProjection.getCode();
-  var destinationCode = destination.getCode();
+  var destinationCode = destinationProjection.getCode();
   var transform;
   if (goog.object.containsKey(transforms, sourceCode) &&
       goog.object.containsKey(transforms[sourceCode], destinationCode)) {
@@ -524,23 +543,23 @@ ol.projection.getTransform = function(source, destination) {
   }
   if (ol.HAVE_PROJ4JS && !goog.isDef(transform)) {
     var proj4jsSource;
-    if (source instanceof ol.Proj4jsProjection_) {
+    if (sourceProjection instanceof ol.Proj4jsProjection_) {
-      proj4jsSource = source;
+      proj4jsSource = sourceProjection;
     } else {
       proj4jsSource =
           ol.projection.getProj4jsProjectionFromCode_({
-            code: source.getCode(),
+            code: sourceCode,
             extent: null
           });
     }
     var sourceProj4jsProj = proj4jsSource.getProj4jsProj();
     var proj4jsDestination;
-    if (destination instanceof ol.Proj4jsProjection_) {
+    if (destinationProjection instanceof ol.Proj4jsProjection_) {
-      proj4jsDestination = destination;
+      proj4jsDestination = destinationProjection;
     } else {
       proj4jsDestination =
           ol.projection.getProj4jsProjectionFromCode_({
-            code: destination.getCode(),
+            code: destinationCode,
             extent: null
           });
     }
@@ -575,7 +594,8 @@ ol.projection.getTransform = function(source, destination) {
       }
       return output;
     };
-    ol.projection.addTransform(source, destination, transform);
+    ol.projection.addTransform(
+        sourceProjection, destinationProjection, transform);
   }
   if (!goog.isDef(transform)) {
     goog.asserts.assert(goog.isDef(transform));
@@ -585,22 +605,6 @@ ol.projection.getTransform = function(source, destination) {
 };
 
 
-/**
- * Given the projection codes this method searches for a transformation function
- * to convert a coordinates array from the source projection to the destination
- * projection.
- *
- * @param {string} sourceCode Source code.
- * @param {string} destinationCode Destination code.
- * @return {ol.TransformFunction} Transform.
- */
-ol.projection.getTransformFromCodes = function(sourceCode, destinationCode) {
-  var source = ol.projection.get(sourceCode);
-  var destination = ol.projection.get(destinationCode);
-  return ol.projection.getTransform(source, destination);
-};
-
-
 /**
  * @param {Array.<number>} input Input coordinate array.
  * @param {Array.<number>=} opt_output Output array of coordinate values.
@@ -642,11 +646,9 @@ ol.projection.cloneTransform = function(input, opt_output, opt_dimension) {
 
 
 /**
- * Transforms the given point to the destination projection.
- *
  * @param {ol.Coordinate} point Point.
- * @param {ol.Projection} source Source.
+ * @param {ol.ProjectionLike} source Source.
- * @param {ol.Projection} destination Destination.
+ * @param {ol.ProjectionLike} destination Destination.
  * @return {ol.Coordinate} Point.
  */
 ol.projection.transform = function(point, source, destination) {
@@ -658,15 +660,17 @@ ol.projection.transform = function(point, source, destination) {
 
 
 /**
+ * Transforms the given point to the destination projection.
+ *
  * @param {ol.Coordinate} point Point.
- * @param {string} sourceCode Source code.
+ * @param {ol.Projection} sourceProjection Source projection.
- * @param {string} destinationCode Destination code.
+ * @param {ol.Projection} destinationProjection Destination projection.
  * @return {ol.Coordinate} Point.
  */
-ol.projection.transformWithCodes =
+ol.projection.transformWithProjections =
-    function(point, sourceCode, destinationCode) {
+    function(point, sourceProjection, destinationProjection) {
-  var transformFn = ol.projection.getTransformFromCodes(
+  var transformFn = ol.projection.getTransformFromProjections(
-      sourceCode, destinationCode);
+      sourceProjection, destinationProjection);
   var vertex = [point.x, point.y];
   vertex = transformFn(vertex, vertex, 2);
   return new ol.Coordinate(vertex[0], vertex[1]);

src/ol/source/bingmapssource.js

@@ -111,7 +111,7 @@ ol.source.BingMaps.prototype.handleImageryMetadataResponse =
                 };
               })));
 
-  var transform = ol.projection.getTransform(
+  var transform = ol.projection.getTransformFromProjections(
       ol.projection.get('EPSG:4326'), this.getProjection());
   var attributions = goog.array.map(
       resource.imageryProviders,

src/ol/source/source.js

@@ -38,7 +38,7 @@ ol.source.Source = function(sourceOptions) {
    */
   this.extent_ = goog.isDef(sourceOptions.extent) ?
       sourceOptions.extent : goog.isDef(sourceOptions.projection) ?
-          sourceOptions.projection.getExtent() : null;
+          this.projection_.getExtent() : null;
 
   /**
    * @private

src/ol/source/tilejsonsource.js

@@ -87,8 +87,8 @@ ol.source.TileJSON.prototype.handleTileJSONResponse = function() {
     var bounds = tileJSON.bounds;
     epsg4326Extent = new ol.Extent(
         bounds[0], bounds[1], bounds[2], bounds[3]);
-    extent = epsg4326Extent.transform(
+    extent = epsg4326Extent.transform(ol.projection.getTransformFromProjections(
-        ol.projection.getTransform(epsg4326Projection, this.getProjection()));
+        epsg4326Projection, this.getProjection()));
     this.setExtent(extent);
   } else {
     epsg4326Extent = null;

test/spec/ol/extent.test.js

@@ -70,8 +70,7 @@ describe('ol.Extent', function() {
   describe('transform', function() {
 
     it('does transform', function() {
-      var transformFn =
+      var transformFn = ol.projection.getTransform('EPSG:4326', 'EPSG:3857');
-          ol.projection.getTransformFromCodes('EPSG:4326', 'EPSG:3857');
       var sourceExtent = new ol.Extent(-15, -30, 45, 60);
       var destinationExtent = sourceExtent.transform(transformFn);
       expect(destinationExtent).not.toBeUndefined();

test/spec/ol/projection.test.js

@@ -70,7 +70,7 @@ describe('ol.projection', function() {
   describe('transform 0,0 from 4326 to 3857', function() {
 
     it('returns expected value', function() {
-      var point = ol.projection.transformWithCodes(
+      var point = ol.projection.transform(
           new ol.Coordinate(0, 0), 'EPSG:4326', 'EPSG:3857');
       expect(point).not.toBeUndefined();
       expect(point).not.toBeNull();
@@ -81,7 +81,7 @@ describe('ol.projection', function() {
   describe('transform 0,0 from 3857 to 4326', function() {
 
     it('returns expected value', function() {
-      var point = ol.projection.transformWithCodes(
+      var point = ol.projection.transform(
           new ol.Coordinate(0, 0), 'EPSG:3857', 'EPSG:4326');
       expect(point).not.toBeUndefined();
       expect(point).not.toBeNull();
@@ -94,7 +94,7 @@ describe('ol.projection', function() {
     // http://alastaira.wordpress.com/2011/01/23/the-google-maps-bing-maps-spherical-mercator-projection/
 
     it('returns expected value', function() {
-      var point = ol.projection.transformWithCodes(
+      var point = ol.projection.transform(
           new ol.Coordinate(-5.625, 52.4827802220782),
           'EPSG:4326',
           'EPSG:900913');
@@ -109,7 +109,7 @@ describe('ol.projection', function() {
     // http://alastaira.wordpress.com/2011/01/23/the-google-maps-bing-maps-spherical-mercator-projection/
 
     it('returns expected value', function() {
-      var point = ol.projection.transformWithCodes(
+      var point = ol.projection.transform(
           new ol.Coordinate(-626172.13571216376, 6887893.4928337997),
           'EPSG:900913',
           'EPSG:4326');
@@ -123,7 +123,7 @@ describe('ol.projection', function() {
   describe('Proj4js integration', function() {
 
     it('allows Proj4js projections to be used transparently', function() {
-      var point = ol.projection.transformWithCodes(
+      var point = ol.projection.transform(
           new ol.Coordinate(-626172.13571216376, 6887893.4928337997),
           'GOOGLE',
           'WGS84');
@@ -136,7 +136,7 @@ describe('ol.projection', function() {
           '+proj=somerc +lat_0=46.95240555555556 +lon_0=7.439583333333333 ' +
           '+k_0=1 +x_0=600000 +y_0=200000 +ellps=bessel ' +
           '+towgs84=674.374,15.056,405.346,0,0,0,0 +units=m +no_defs';
-      var point = ol.projection.transformWithCodes(
+      var point = ol.projection.transform(
           new ol.Coordinate(7.439583333333333, 46.95240555555556),
           'EPSG:4326',
           'EPSG:21781');
@@ -192,13 +192,13 @@ describe('ol.projection', function() {
 
   });
 
-  describe('ol.projection.getTransform()', function() {
+  describe('ol.projection.getTransformFromProjections()', function() {
 
     var sm = ol.projection.get('GOOGLE');
     var gg = ol.projection.get('EPSG:4326');
 
     it('returns a transform function', function() {
-      var transform = ol.projection.getTransform(sm, gg);
+      var transform = ol.projection.getTransformFromProjections(sm, gg);
       expect(typeof transform).toBe('function');
 
       var output = transform([-12000000, 5000000]);
@@ -208,7 +208,7 @@ describe('ol.projection', function() {
     });
 
     it('works for longer arrays', function() {
-      var transform = ol.projection.getTransform(sm, gg);
+      var transform = ol.projection.getTransformFromProjections(sm, gg);
       expect(typeof transform).toBe('function');
 
       var output = transform([-12000000, 5000000, -12000000, 5000000]);
@@ -221,17 +221,15 @@ describe('ol.projection', function() {
 
   });
 
-  describe('ol.projection.getTransformFromCodes()', function() {
+  describe('ol.projection.getTransform()', function() {
 
     it('returns a function', function() {
-      var transform = ol.projection.getTransformFromCodes(
+      var transform = ol.projection.getTransform('GOOGLE', 'EPSG:4326');
-          'GOOGLE', 'EPSG:4326');
       expect(typeof transform).toBe('function');
     });
 
     it('returns a transform function', function() {
-      var transform = ol.projection.getTransformFromCodes(
+      var transform = ol.projection.getTransform('GOOGLE', 'EPSG:4326');
-          'GOOGLE', 'EPSG:4326');
       expect(typeof transform).toBe('function');
 
       var output = transform([-626172.13571216376, 6887893.4928337997]);
@@ -242,8 +240,7 @@ describe('ol.projection', function() {
     });
 
     it('works for longer arrays of coordinate values', function() {
-      var transform = ol.projection.getTransformFromCodes(
+      var transform = ol.projection.getTransform('GOOGLE', 'EPSG:4326');
-          'GOOGLE', 'EPSG:4326');
       expect(typeof transform).toBe('function');
 
       var output = transform([
@@ -261,8 +258,7 @@ describe('ol.projection', function() {
     });
 
     it('accepts an optional destination array', function() {
-      var transform = ol.projection.getTransformFromCodes(
+      var transform = ol.projection.getTransform('EPSG:3857', 'EPSG:4326');
-          'EPSG:3857', 'EPSG:4326');
       var input = [-12000000, 5000000];
       var output = [];
 
@@ -276,8 +272,7 @@ describe('ol.projection', function() {
     });
 
     it('accepts a dimension', function() {
-      var transform = ol.projection.getTransformFromCodes(
+      var transform = ol.projection.getTransform('GOOGLE', 'EPSG:4326');
-          'GOOGLE', 'EPSG:4326');
       expect(typeof transform).toBe('function');
 
       var dimension = 3;