Merge pull request #3362 from ahocevar/constructor-proj4js

Configure proj4 options and transforms upon construction

examples/sphere-mollweide.js

@@ -2,7 +2,7 @@ goog.require('ol.Graticule');
 goog.require('ol.Map');
 goog.require('ol.View');
 goog.require('ol.layer.Vector');
-goog.require('ol.proj');
+goog.require('ol.proj.Projection');
 goog.require('ol.source.GeoJSON');
 
 
@@ -11,11 +11,12 @@ proj4.defs('ESRI:53009', '+proj=moll +lon_0=0 +x_0=0 +y_0=0 +a=6371000 ' +
 
 // Configure the Sphere Mollweide projection object with an extent,
 // and a world extent. These are required for the Graticule.
-var sphereMollweideProjection = ol.proj.get('ESRI:53009');
-sphereMollweideProjection.setExtent([
-  -9009954.605703328, -9009954.605703328,
-  9009954.605703328, 9009954.605703328]);
-sphereMollweideProjection.setWorldExtent([-179, -90, 179, 90]);
+var sphereMollweideProjection = new ol.proj.Projection({
+  code: 'ESRI:53009',
+  extent: [-9009954.605703328, -9009954.605703328,
+    9009954.605703328, 9009954.605703328],
+  worldExtent: [-179, -90, 179, 90]
+});
 
 var map = new ol.Map({
   keyboardEventTarget: document,

examples/wms-custom-proj.js

@@ -12,7 +12,8 @@ goog.require('ol.source.TileWMS');
 
 // By default OpenLayers does not know about the EPSG:21781 (Swiss) projection.
 // So we create a projection instance for EPSG:21781 and pass it to
-// ol.proj.addProjection to make it available to the library.
+// ol.proj.addProjection to make it available to the library for lookup by its
+// code.
 
 var projection = new ol.proj.Projection({
   code: 'EPSG:21781',

examples/wms-image-custom-proj.js

@@ -5,21 +5,29 @@ goog.require('ol.control');
 goog.require('ol.control.ScaleLine');
 goog.require('ol.layer.Image');
 goog.require('ol.proj');
+goog.require('ol.proj.Projection');
 goog.require('ol.source.ImageWMS');
 
 
-// Transparent Proj4js support: ol.proj.get() creates and returns a projection
-// known to Proj4js if it is unknown to OpenLayers, and registers functions to
-// transform between all registered projections.
+// Transparent Proj4js support:
+//
 // EPSG:21781 is known to Proj4js because its definition was loaded in the html.
-// Note that we are getting the projection object here to set the extent. If
-// you do not need this, you do not have to use ol.proj.get(); simply use the
-// string code in the view projection below and the transforms will be
-// registered transparently.
-var projection = ol.proj.get('EPSG:21781');
-// The extent is used to determine zoom level 0. Recommended values for a
+// Now when we create an ol.proj.Projection instance with the 'EPSG:21781' code,
+// OpenLayers will pick up parameters like units and transform functions from
+// Proj4js.
+//
+// Note that we are setting the projection's extent here, which is used to
+// determine the view resolution for zoom level 0. Recommended values for a
 // projection's validity extent can be found at http://epsg.io/.
-projection.setExtent([485869.5728, 76443.1884, 837076.5648, 299941.7864]);
+//
+// If you use Proj4js only to transform coordinates, you don't even need to
+// create an ol.proj.Projection instance. ol.proj.get() will take care of it
+// internally.
+
+var projection = new ol.proj.Projection({
+  code: 'EPSG:21781',
+  extent: [485869.5728, 76443.1884, 837076.5648, 299941.7864]
+});
 
 var extent = [420000, 30000, 900000, 350000];
 var layers = [
@@ -67,7 +75,7 @@ var map = new ol.Map({
   target: 'map',
   view: new ol.View({
     projection: projection,
-    center: ol.proj.transform([8.23, 46.86], 'EPSG:4326', 'EPSG:21781'),
+    center: ol.proj.transform([8.23, 46.86], 'EPSG:4326', projection),
     extent: extent,
     zoom: 2
   })

externs/olx.js

@@ -411,7 +411,7 @@ olx.OverlayOptions.prototype.autoPanMargin;
 /**
  * Object literal with config options for the projection.
  * @typedef {{code: string,
- *     units: (ol.proj.Units|string),
+ *     units: (ol.proj.Units|string|undefined),
  *     extent: (ol.Extent|undefined),
  *     axisOrientation: (string|undefined),
  *     global: (boolean|undefined),
@@ -431,8 +431,8 @@ olx.ProjectionOptions.prototype.code;
 
 
 /**
- * Units.
- * @type {ol.proj.Units|string}
+ * Units. Required unless a proj4 projection is defined for `code`.
+ * @type {ol.proj.Units|string|undefined}
  * @api stable
  */
 olx.ProjectionOptions.prototype.units;

src/ol/proj/proj.js

@@ -134,6 +134,41 @@ ol.proj.Projection = function(options) {
    */
   this.defaultTileGrid_ = null;
 
+  if (ol.ENABLE_PROJ4JS && typeof proj4 == 'function') {
+    var code = options.code;
+    var def = proj4.defs(code);
+    if (goog.isDef(def)) {
+      if (goog.isDef(def.axis) && !goog.isDef(options.axisOrientation)) {
+        this.axisOrientation_ = def.axis;
+      }
+      if (!goog.isDef(options.units)) {
+        var units = def.units;
+        if (!goog.isDef(units)) {
+          if (goog.isDef(def.to_meter)) {
+            units = def.to_meter.toString();
+            ol.proj.METERS_PER_UNIT[units] = def.to_meter;
+          }
+        }
+        this.units_ = units;
+      }
+      var projections = ol.proj.projections_;
+      var currentCode, currentDef, currentProj, proj4Transform;
+      for (currentCode in projections) {
+        currentDef = proj4.defs(currentCode);
+        if (goog.isDef(currentDef)) {
+          currentProj = ol.proj.get(currentCode);
+          if (currentDef === def) {
+            ol.proj.addEquivalentProjections([currentProj, this]);
+          } else {
+            proj4Transform = proj4(currentCode, code);
+            ol.proj.addCoordinateTransforms(currentProj, this,
+                proj4Transform.forward, proj4Transform.inverse);
+          }
+        }
+      }
+    }
+  }
+
 };
 
 
@@ -392,7 +427,8 @@ ol.proj.addEquivalentTransforms =
 
 
 /**
- * Add a Projection object to the list of supported projections.
+ * Add a Projection object to the list of supported projections that can be
+ * looked up by their code.
  *
  * @param {ol.proj.Projection} projection Projection instance.
  * @api stable
@@ -562,43 +598,11 @@ ol.proj.get = function(projectionLike) {
     projection = projectionLike;
   } else if (goog.isString(projectionLike)) {
     var code = projectionLike;
-    var projections = ol.proj.projections_;
-    projection = projections[code];
+    projection = ol.proj.projections_[code];
     if (ol.ENABLE_PROJ4JS && !goog.isDef(projection) &&
-        typeof proj4 == 'function') {
-      var def = proj4.defs(code);
-      if (goog.isDef(def)) {
-        var units = def.units;
-        if (!goog.isDef(units)) {
-          if (goog.isDef(def.to_meter)) {
-            units = def.to_meter.toString();
-            ol.proj.METERS_PER_UNIT[units] = def.to_meter;
-          }
-        }
-        projection = new ol.proj.Projection({
-          code: code,
-          units: units,
-          axisOrientation: def.axis
-        });
-        ol.proj.addProjection(projection);
-        var currentCode, currentDef, currentProj, proj4Transform;
-        for (currentCode in projections) {
-          currentDef = proj4.defs(currentCode);
-          if (goog.isDef(currentDef)) {
-            currentProj = ol.proj.get(currentCode);
-            if (currentDef === def) {
-              ol.proj.addEquivalentProjections([currentProj, projection]);
-            } else {
-              proj4Transform = proj4(currentCode, code);
-              ol.proj.addCoordinateTransforms(currentProj, projection,
-                  proj4Transform.forward, proj4Transform.inverse);
-            }
-          }
-        }
-      } else {
-        goog.asserts.assert(goog.isDef(projection));
-        projection = null;
-      }
+        typeof proj4 == 'function' && goog.isDef(proj4.defs(code))) {
+      projection = new ol.proj.Projection({code: code});
+      ol.proj.addProjection(projection);
     }
   } else {
     projection = null;