Refactor tile functions

* Add support for minZoom in XYZ tile grids and tile sources
* Factor out common tile coordinate transforms

src/objectliterals.jsdoc

@@ -451,6 +451,7 @@
 
 /**
  * @typedef {Object} ol.tilegrid.TileGridOptions
+ * @property {number|undefined} minZoom Minimum zoom.
  * @property {ol.Coordinate|undefined} origin Origin.
  * @property {Array.<ol.Coordinate>|undefined} origins Origins.
  * @property {!Array.<number>} resolutions Resolutions.

src/ol/renderer/layerrenderer.js

@@ -317,9 +317,9 @@ ol.renderer.Layer.prototype.manageTilePyramid = function(
   }
   var wantedTiles = frameState.wantedTiles[tileSourceKey];
   var tileQueue = frameState.tileQueue;
+  var minZoom = tileGrid.getMinZoom();
   var tile, tileRange, tileResolution, x, y, z;
-  // FIXME this should loop up to tileGrid's minZ when implemented
-  for (z = currentZ; z >= 0; --z) {
+  for (z = currentZ; z >= minZoom; --z) {
     tileRange = tileGrid.getTileRangeForExtentAndZ(extent, z);
     tileResolution = tileGrid.getResolution(z);
     for (x = tileRange.minX; x <= tileRange.maxX; ++x) {

src/ol/source/bingmapssource.js

@@ -3,11 +3,9 @@ goog.provide('ol.source.BingMaps');
 goog.require('goog.Uri');
 goog.require('goog.array');
 goog.require('goog.asserts');
-goog.require('goog.math');
 goog.require('goog.net.Jsonp');
 goog.require('ol.Attribution');
 goog.require('ol.Size');
-goog.require('ol.TileCoord');
 goog.require('ol.TileRange');
 goog.require('ol.TileUrlFunction');
 goog.require('ol.extent');
@@ -72,30 +70,17 @@ ol.source.BingMaps.prototype.handleImageryMetadataResponse =
   goog.asserts.assert(resourceSet.resources.length == 1);
   var resource = resourceSet.resources[0];
 
-  var zoomMin = resource.zoomMin;
-  var zoomMax = resource.zoomMax;
   var tileSize = new ol.Size(resource.imageWidth, resource.imageHeight);
   var tileGrid = new ol.tilegrid.XYZ({
-    maxZoom: zoomMax,
+    minZoom: resource.zoomMin,
+    maxZoom: resource.zoomMax,
     tileSize: tileSize
   });
   this.tileGrid = tileGrid;
 
   var culture = this.culture_;
   this.tileUrlFunction = ol.TileUrlFunction.withTileCoordTransform(
-      function(tileCoord) {
-        if (tileCoord.z < zoomMin || zoomMax < tileCoord.z) {
-          return null;
-        }
-        var n = 1 << tileCoord.z;
-        var y = -tileCoord.y - 1;
-        if (y < 0 || n <= y) {
-          return null;
-        } else {
-          var x = goog.math.modulo(tileCoord.x, n);
-          return new ol.TileCoord(tileCoord.z, x, y);
-        }
-      },
+      tileGrid.createTileCoordTransform(),
       ol.TileUrlFunction.createFromTileUrlFunctions(
           goog.array.map(
               resource.imageUrlSubdomains,

src/ol/source/tilejsonsource.js

@@ -1,6 +1,5 @@
 // FIXME add some error checking
 // FIXME check order of async callbacks
-// FIXME use minzoom when supported
 
 /**
  * @see http://mapbox.com/developers/api/
@@ -10,10 +9,8 @@ goog.provide('ol.source.TileJSON');
 goog.provide('ol.tilejson');
 
 goog.require('goog.asserts');
-goog.require('goog.math');
 goog.require('goog.net.jsloader');
 goog.require('ol.Attribution');
-goog.require('ol.TileCoord');
 goog.require('ol.TileRange');
 goog.require('ol.TileUrlFunction');
 goog.require('ol.extent');
@@ -77,17 +74,14 @@ ol.source.TileJSON.prototype.handleTileJSONResponse = function() {
 
   var epsg4326Projection = ol.projection.get('EPSG:4326');
 
-  var epsg4326Extent, extent;
+  var extent;
   if (goog.isDef(tileJSON.bounds)) {
     var bounds = tileJSON.bounds;
-    epsg4326Extent = [bounds[0], bounds[2], bounds[1], bounds[3]];
+    var epsg4326Extent = [bounds[0], bounds[2], bounds[1], bounds[3]];
     var transform = ol.projection.getTransformFromProjections(
         epsg4326Projection, this.getProjection());
     extent = ol.extent.transform(epsg4326Extent, transform);
     this.setExtent(extent);
-  } else {
-    epsg4326Extent = null;
-    extent = null;
   }
 
   var scheme = goog.isDef(tileJSON.scheme) || 'xyz';
@@ -95,38 +89,22 @@ ol.source.TileJSON.prototype.handleTileJSONResponse = function() {
     goog.asserts.assert(tileJSON.scheme == 'xyz');
   }
   var minZoom = tileJSON.minzoom || 0;
-  goog.asserts.assert(minZoom === 0); // FIXME
   var maxZoom = tileJSON.maxzoom || 22;
   var tileGrid = new ol.tilegrid.XYZ({
-    maxZoom: maxZoom
+    maxZoom: maxZoom,
+    minZoom: minZoom
   });
   this.tileGrid = tileGrid;
 
   this.tileUrlFunction = ol.TileUrlFunction.withTileCoordTransform(
-      function(tileCoord) {
-        if (tileCoord.z < minZoom || maxZoom < tileCoord.z) {
-          return null;
-        }
-        var n = 1 << tileCoord.z;
-        var y = -tileCoord.y - 1;
-        if (y < 0 || n <= y) {
-          return null;
-        }
-        var x = goog.math.modulo(tileCoord.x, n);
-        if (!goog.isNull(extent)) {
-          var tileExtent = tileGrid.getTileCoordExtent(
-              new ol.TileCoord(tileCoord.z, x, tileCoord.y));
-          if (!ol.extent.intersects(tileExtent, extent)) {
-            return null;
-          }
-        }
-        return new ol.TileCoord(tileCoord.z, x, y);
-      },
+      tileGrid.createTileCoordTransform({
+        extent: extent
+      }),
       ol.TileUrlFunction.createFromTemplates(tileJSON.tiles));
 
   if (goog.isDef(tileJSON.attribution)) {
-    var attributionExtent = goog.isNull(extent) ?
-        epsg4326Projection.getExtent() : extent;
+    var attributionExtent = goog.isDef(extent) ?
+        extent : epsg4326Projection.getExtent();
     /** @type {Object.<string, Array.<ol.TileRange>>} */
     var tileRanges = {};
     var z, zKey;

src/ol/source/xyzsource.js

@@ -1,15 +1,10 @@
-// FIXME add minZoom support
-
 goog.provide('ol.source.XYZ');
 goog.provide('ol.source.XYZOptions');
 
-goog.require('goog.math');
 goog.require('ol.Attribution');
 goog.require('ol.Projection');
-goog.require('ol.TileCoord');
 goog.require('ol.TileUrlFunction');
 goog.require('ol.TileUrlFunctionType');
-goog.require('ol.extent');
 goog.require('ol.projection');
 goog.require('ol.source.ImageTileSource');
 goog.require('ol.tilegrid.XYZ');
@@ -21,6 +16,7 @@ goog.require('ol.tilegrid.XYZ');
  *            extent: (ol.Extent|undefined),
  *            logo: (string|undefined),
  *            maxZoom: number,
+ *            minZoom: (number|undefined),
  *            projection: (ol.Projection|undefined),
  *            tileUrlFunction: (ol.TileUrlFunctionType|undefined),
  *            url: (string|undefined),
@@ -54,55 +50,16 @@ ol.source.XYZ = function(options) {
   }
 
   var tileGrid = new ol.tilegrid.XYZ({
-    maxZoom: options.maxZoom
+    maxZoom: options.maxZoom,
+    minZoom: options.minZoom
   });
 
-  // FIXME factor out common code
-  if (goog.isDef(options.extent)) {
+  var tileCoordTransform = tileGrid.createTileCoordTransform({
+    extent: options.extent
+  });
 
-    var extent = options.extent;
-    var tmpExtent = ol.extent.createEmptyExtent();
-    var tmpTileCoord = new ol.TileCoord(0, 0, 0);
-    tileUrlFunction = ol.TileUrlFunction.withTileCoordTransform(
-        function(tileCoord) {
-          if (options.maxZoom < tileCoord.z) {
-            return null;
-          }
-          var n = 1 << tileCoord.z;
-          var y = -tileCoord.y - 1;
-          if (y < 0 || n <= y) {
-            return null;
-          }
-          var x = goog.math.modulo(tileCoord.x, n);
-          tmpTileCoord.z = tileCoord.z;
-          tmpTileCoord.x = x;
-          tmpTileCoord.y = tileCoord.y;
-          var tileExtent = tileGrid.getTileCoordExtent(tmpTileCoord, tmpExtent);
-          if (!ol.extent.intersects(tileExtent, extent)) {
-            return null;
-          }
-          return new ol.TileCoord(tileCoord.z, x, y);
-        },
-        tileUrlFunction);
-
-  } else {
-
-    tileUrlFunction = ol.TileUrlFunction.withTileCoordTransform(
-        function(tileCoord) {
-          if (options.maxZoom < tileCoord.z) {
-            return null;
-          }
-          var n = 1 << tileCoord.z;
-          var y = -tileCoord.y - 1;
-          if (y < 0 || n <= y) {
-            return null;
-          } else {
-            var x = goog.math.modulo(tileCoord.x, n);
-            return new ol.TileCoord(tileCoord.z, x, y);
-          }
-        },
-        tileUrlFunction);
-  }
+  tileUrlFunction = ol.TileUrlFunction.withTileCoordTransform(
+      tileCoordTransform, tileUrlFunction);
 
   goog.base(this, {
     attributions: options.attributions,

src/ol/tilegrid/tilegrid.js

@@ -1,5 +1,3 @@
-// FIXME cope with tile grids whose minium zoom is not zero
-
 goog.provide('ol.tilegrid.TileGrid');
 
 goog.require('goog.array');
@@ -32,6 +30,12 @@ ol.DEFAULT_MAX_ZOOM = 42;
  */
 ol.tilegrid.TileGrid = function(options) {
 
+  /**
+   * @protected
+   * @type {number}
+   */
+  this.minZoom = goog.isDef(options.minZoom) ? options.minZoom : 0;
+
   /**
    * @private
    * @type {!Array.<number>}
@@ -42,10 +46,10 @@ ol.tilegrid.TileGrid = function(options) {
   }, true));
 
   /**
-   * @private
+   * @protected
    * @type {number}
    */
-  this.numResolutions_ = this.resolutions_.length;
+  this.maxZoom = this.resolutions_.length - 1;
 
   /**
    * @private
@@ -60,7 +64,7 @@ ol.tilegrid.TileGrid = function(options) {
   this.origins_ = null;
   if (goog.isDef(options.origins)) {
     this.origins_ = options.origins;
-    goog.asserts.assert(this.origins_.length == this.resolutions_.length);
+    goog.asserts.assert(this.origins_.length == this.maxZoom + 1);
   }
   goog.asserts.assert(
       (goog.isNull(this.origin_) && !goog.isNull(this.origins_)) ||
@@ -73,7 +77,7 @@ ol.tilegrid.TileGrid = function(options) {
   this.tileSizes_ = null;
   if (goog.isDef(options.tileSizes)) {
     this.tileSizes_ = options.tileSizes;
-    goog.asserts.assert(this.tileSizes_.length == this.resolutions_.length);
+    goog.asserts.assert(this.tileSizes_.length == this.maxZoom + 1);
   }
 
   /**
@@ -111,7 +115,7 @@ ol.tilegrid.TileGrid.prototype.forEachTileCoordParentTileRange =
     function(tileCoord, callback, opt_obj, opt_tileRange, opt_extent) {
   var tileCoordExtent = this.getTileCoordExtent(tileCoord, opt_extent);
   var z = tileCoord.z - 1;
-  while (z >= 0) {
+  while (z >= this.minZoom) {
     if (callback.call(opt_obj, z,
         this.getTileRangeForExtentAndZ(tileCoordExtent, z, opt_tileRange))) {
       return true;
@@ -122,6 +126,22 @@ ol.tilegrid.TileGrid.prototype.forEachTileCoordParentTileRange =
 };
 
 
+/**
+ * @return {number} Max zoom.
+ */
+ol.tilegrid.TileGrid.prototype.getMaxZoom = function() {
+  return this.maxZoom;
+};
+
+
+/**
+ * @return {number} Min zoom.
+ */
+ol.tilegrid.TileGrid.prototype.getMinZoom = function() {
+  return this.minZoom;
+};
+
+
 /**
  * @param {number} z Z.
  * @return {ol.Coordinate} Origin.
@@ -131,7 +151,7 @@ ol.tilegrid.TileGrid.prototype.getOrigin = function(z) {
     return this.origin_;
   } else {
     goog.asserts.assert(!goog.isNull(this.origins_));
-    goog.asserts.assert(0 <= z && z < this.origins_.length);
+    goog.asserts.assert(this.minZoom <= z && z <= this.maxZoom);
     return this.origins_[z];
   }
 };
@@ -142,7 +162,7 @@ ol.tilegrid.TileGrid.prototype.getOrigin = function(z) {
  * @return {number} Resolution.
  */
 ol.tilegrid.TileGrid.prototype.getResolution = function(z) {
-  goog.asserts.assert(0 <= z && z < this.numResolutions_);
+  goog.asserts.assert(this.minZoom <= z && z <= this.maxZoom);
   return this.resolutions_[z];
 };
 
@@ -328,7 +348,8 @@ ol.tilegrid.TileGrid.prototype.getTileCoordForCoordAndZ =
  * @return {number} Tile resolution.
  */
 ol.tilegrid.TileGrid.prototype.getTileCoordResolution = function(tileCoord) {
-  goog.asserts.assert(0 <= tileCoord.z && tileCoord.z < this.numResolutions_);
+  goog.asserts.assert(
+      this.minZoom <= tileCoord.z && tileCoord.z <= this.maxZoom);
   return this.resolutions_[tileCoord.z];
 };
 
@@ -342,7 +363,7 @@ ol.tilegrid.TileGrid.prototype.getTileSize = function(z) {
     return this.tileSize_;
   } else {
     goog.asserts.assert(!goog.isNull(this.tileSizes_));
-    goog.asserts.assert(0 <= z && z < this.tileSizes_.length);
+    goog.asserts.assert(this.minZoom <= z && z <= this.maxZoom);
     return this.tileSizes_[z];
   }
 };

src/ol/tilegrid/xyztilegrid.js

@@ -1,7 +1,10 @@
 goog.provide('ol.tilegrid.XYZ');
 
+goog.require('goog.math');
 goog.require('ol.Size');
+goog.require('ol.TileCoord');
 goog.require('ol.TileRange');
+goog.require('ol.extent');
 goog.require('ol.projection');
 goog.require('ol.projection.EPSG3857');
 goog.require('ol.tilegrid.TileGrid');
@@ -15,20 +18,15 @@ goog.require('ol.tilegrid.TileGrid');
  */
 ol.tilegrid.XYZ = function(options) {
 
-  /**
-   * @private
-   * @type {number}
-   */
-  this.maxZoom_ = options.maxZoom;
-
-  var resolutions = new Array(this.maxZoom_ + 1);
+  var resolutions = new Array(options.maxZoom + 1);
   var z;
   var size = 2 * ol.projection.EPSG3857.HALF_SIZE / ol.DEFAULT_TILE_SIZE;
-  for (z = 0; z <= this.maxZoom_; ++z) {
+  for (z = 0; z <= options.maxZoom; ++z) {
     resolutions[z] = size / Math.pow(2, z);
   }
 
   goog.base(this, {
+    minZoom: options.minZoom,
     origin: [-ol.projection.EPSG3857.HALF_SIZE,
              ol.projection.EPSG3857.HALF_SIZE],
     resolutions: resolutions,
@@ -39,15 +37,75 @@ ol.tilegrid.XYZ = function(options) {
 goog.inherits(ol.tilegrid.XYZ, ol.tilegrid.TileGrid);
 
 
+/**
+ * @param {{wrapX: (boolean|undefined),
+ *          extent: (ol.Extent|undefined)}=} opt_options Options.
+ * @return {function(ol.TileCoord, ol.Projection, ol.TileCoord=): ol.TileCoord}
+ *     Tile coordinate transform.
+ */
+ol.tilegrid.XYZ.prototype.createTileCoordTransform = function(opt_options) {
+  var options = goog.isDef(opt_options) ? opt_options : {};
+  var tileGrid = this;
+  var minZ = this.minZoom;
+  var maxZ = this.maxZoom;
+  var wrapX = goog.isDef(options.wrapX) ? options.wrapX : true;
+  var extent = options.extent;
+  var tmpExtent = ol.extent.createEmptyExtent();
+  var tmpTileCoord = new ol.TileCoord(0, 0, 0);
+  return (
+      /**
+       * @param {ol.TileCoord} tileCoord Tile coordinate.
+       * @param {ol.Projection} projection Projection.
+       * @param {ol.TileCoord=} opt_tileCoord Destination tile coordinate.
+       * @return {ol.TileCoord} Tile coordinate.
+       */
+      function(tileCoord, projection, opt_tileCoord) {
+        var z = tileCoord.z;
+        if (z < minZ || maxZ < z) {
+          return null;
+        }
+        var n = Math.pow(2, z);
+        var x = tileCoord.x;
+        if (wrapX) {
+          x = goog.math.modulo(x, n);
+        } else if (x < 0 || n <= x) {
+          return null;
+        }
+        var y = tileCoord.y;
+        if (y < -n || -1 < y) {
+          return null;
+        }
+        if (goog.isDef(extent)) {
+          tmpTileCoord.z = z;
+          tmpTileCoord.x = x;
+          tmpTileCoord.y = y;
+          var tileExtent =
+              tileGrid.getTileCoordExtent(tmpTileCoord, tmpExtent);
+          if (!ol.extent.intersects(extent, tileExtent)) {
+            return null;
+          }
+        }
+        if (goog.isDef(opt_tileCoord)) {
+          opt_tileCoord.z = z;
+          opt_tileCoord.x = x;
+          opt_tileCoord.y = -y - 1;
+          return opt_tileCoord;
+        } else {
+          return new ol.TileCoord(z, x, -y - 1);
+        }
+      });
+};
+
+
 /**
  * @inheritDoc
  */
 ol.tilegrid.XYZ.prototype.getTileCoordChildTileRange =
     function(tileCoord, opt_tileRange) {
-  if (tileCoord.z < this.maxZoom_) {
+  if (tileCoord.z < this.maxZoom) {
     return ol.TileRange.createOrUpdate(
-        tileCoord.x << 1, tileCoord.x + 1 << 1,
-        tileCoord.y << 1, tileCoord.y + 1 << 1,
+        2 * tileCoord.x, 2 * (tileCoord.x + 1),
+        2 * tileCoord.y, 2 * (tileCoord.y + 1),
         opt_tileRange);
   } else {
     return null;
@@ -63,7 +121,7 @@ ol.tilegrid.XYZ.prototype.forEachTileCoordParentTileRange =
   var tileRange = ol.TileRange.createOrUpdate(
       0, tileCoord.x, 0, tileCoord.y, opt_tileRange);
   var z;
-  for (z = tileCoord.z - 1; z >= 0; --z) {
+  for (z = tileCoord.z - 1; z >= this.minZoom; --z) {
     tileRange.minX = tileRange.maxX >>= 1;
     tileRange.minY = tileRange.maxY >>= 1;
     if (callback.call(opt_obj, z, tileRange)) {

src/ol/tileurlfunction.js

@@ -8,8 +8,7 @@ goog.require('ol.extent');
 
 
 /**
- * @typedef {function(this:ol.source.ImageTileSource, ol.TileCoord,
- *     ol.Projection): (string|undefined)}
+ * @typedef {function(ol.TileCoord, ol.Projection): (string|undefined)}
  */
 ol.TileUrlFunctionType;
 
@@ -98,19 +97,22 @@ ol.TileUrlFunction.nullTileUrlFunction = function(tileCoord, projection) {
 
 
 /**
- * @param {function(this:ol.source.ImageTileSource, ol.TileCoord,
- *     ol.Projection) : ol.TileCoord} transformFn Transform function.
+ * @param {function(ol.TileCoord, ol.Projection, ol.TileCoord=): ol.TileCoord}
+ *     transformFn Transform function.
  * @param {ol.TileUrlFunctionType} tileUrlFunction Tile URL function.
  * @return {ol.TileUrlFunctionType} Tile URL function.
  */
 ol.TileUrlFunction.withTileCoordTransform =
     function(transformFn, tileUrlFunction) {
+  var tmpTileCoord = new ol.TileCoord(0, 0, 0);
   return function(tileCoord, projection) {
     if (goog.isNull(tileCoord)) {
       return undefined;
     } else {
-      return tileUrlFunction.call(this,
-          transformFn.call(this, tileCoord, projection), projection);
+      return tileUrlFunction.call(
+          this,
+          transformFn.call(this, tileCoord, projection, tmpTileCoord),
+          projection);
     }
   };
 };