Allow extents to restrict tile ranges requested from the server

The addition of full extent tile ranges also allows us to simplify wrapX handling for tile layers. By limiting wrapX to true and false as possible values, we can remove a lot of guessing logic.
2015-04-28 23:14:08 +02:00
parent 700903ca5c
commit a116878a57
17 changed files with 535 additions and 199 deletions
--- a/src/ol/attribution.js
+++ b/src/ol/attribution.js
@@ -78,8 +78,8 @@ ol.Attribution.prototype.intersectsAnyTileRange =
      if (testTileRange.intersects(tileRange)) {
        return true;
      }
-      var extentTileRange = tileGrid.getTileRange(
-          parseInt(zKey, 10), projection);
+      var extentTileRange = tileGrid.getTileRangeForExtentAndZ(
+          projection.getExtent(), parseInt(zKey, 10));
      var width = extentTileRange.getWidth();
      if (tileRange.minX < extentTileRange.minX ||
          tileRange.maxX > extentTileRange.maxX) {
--- a/src/ol/source/source.js
+++ b/src/ol/source/source.js
@@ -75,9 +75,9 @@ ol.source.Source = function(options) {

  /**
   * @private
-   * @type {boolean|undefined}
+   * @type {boolean}
   */
-  this.wrapX_ = options.wrapX;
+  this.wrapX_ = goog.isDef(options.wrapX) ? options.wrapX : false;

 };
 goog.inherits(ol.source.Source, ol.Object);
--- a/src/ol/source/tileimagesource.js
+++ b/src/ol/source/tileimagesource.js
@@ -93,7 +93,8 @@ ol.source.TileImage.prototype.getTile =
  } else {
    goog.asserts.assert(projection, 'argument projection is truthy');
    var tileCoord = [z, x, y];
-    var urlTileCoord = this.getWrapXTileCoord(tileCoord, projection);
+    var urlTileCoord = this.getTileCoordForTileUrlFunction(
+        tileCoord, projection);
    var tileUrl = goog.isNull(urlTileCoord) ? undefined :
        this.tileUrlFunction(urlTileCoord, pixelRatio, projection);
    var tile = new this.tileClass(
--- a/src/ol/source/tilesource.js
+++ b/src/ol/source/tilesource.js
@@ -2,6 +2,7 @@ goog.provide('ol.source.Tile');
 goog.provide('ol.source.TileEvent');
 goog.provide('ol.source.TileOptions');

+goog.require('goog.asserts');
 goog.require('goog.events.Event');
 goog.require('ol.Attribution');
 goog.require('ol.Extent');
@@ -216,28 +217,23 @@ ol.source.Tile.prototype.getTilePixelSize =


 /**
- * Handles x-axis wrapping. When `wrapX` is `undefined` or the projection is not
- * a global projection, `tileCoord` will be returned unaltered. When `wrapX` is
- * `true`, the tile coordinate will be wrapped horizontally.
- * When `wrapX` is `false`, `null` will be returned for tiles that are
- * outside the projection extent.
+ * Handles x-axis wrapping and returns a tile coordinate when it is within
+ * the resolution and extent range.
 * @param {ol.TileCoord} tileCoord Tile coordinate.
 * @param {ol.proj.Projection=} opt_projection Projection.
- * @return {ol.TileCoord} Tile coordinate.
+ * @return {ol.TileCoord} Tile coordinate to be passed to the tileUrlFunction or
+ *     null if no tile URL should be created for the passed `tileCoord`.
 */
-ol.source.Tile.prototype.getWrapXTileCoord =
+ol.source.Tile.prototype.getTileCoordForTileUrlFunction =
    function(tileCoord, opt_projection) {
  var projection = goog.isDef(opt_projection) ?
      opt_projection : this.getProjection();
  var tileGrid = this.getTileGridForProjection(projection);
-  var wrapX = this.getWrapX();
-  if (goog.isDef(wrapX) && tileGrid.isGlobal(tileCoord[0], projection)) {
-    return wrapX ?
-        ol.tilecoord.wrapX(tileCoord, tileGrid, projection) :
-        ol.tilecoord.clipX(tileCoord, tileGrid, projection);
-  } else {
-    return tileCoord;
+  goog.asserts.assert(!goog.isNull(tileGrid), 'tile grid needed');
+  if (this.getWrapX()) {
+    tileCoord = ol.tilecoord.wrapX(tileCoord, tileGrid, projection);
  }
+  return ol.tilecoord.restrictByExtentAndZ(tileCoord, tileGrid);
 };


--- a/src/ol/source/tilewmssource.js
+++ b/src/ol/source/tilewmssource.js
@@ -49,7 +49,7 @@ ol.source.TileWMS = function(opt_options) {
    tileGrid: options.tileGrid,
    tileLoadFunction: options.tileLoadFunction,
    tileUrlFunction: goog.bind(this.tileUrlFunction_, this),
-    wrapX: options.wrapX
+    wrapX: goog.isDef(options.wrapX) ? options.wrapX : true
  });

  var urls = options.urls;
--- a/src/ol/source/wmtssource.js
+++ b/src/ol/source/wmtssource.js
@@ -11,7 +11,6 @@ goog.require('ol.TileUrlFunctionType');
 goog.require('ol.extent');
 goog.require('ol.proj');
 goog.require('ol.source.TileImage');
-goog.require('ol.tilecoord');
 goog.require('ol.tilegrid.WMTS');


@@ -181,31 +180,8 @@ ol.source.WMTS = function(options) {
          goog.array.map(this.urls_, createFromWMTSTemplate)) :
      ol.TileUrlFunction.nullTileUrlFunction;

-  var tmpExtent = ol.extent.createEmpty();
  tileUrlFunction = ol.TileUrlFunction.withTileCoordTransform(
-      /**
-       * @param {ol.TileCoord} tileCoord Tile coordinate.
-       * @param {ol.proj.Projection} projection Projection.
-       * @param {ol.TileCoord=} opt_tileCoord Tile coordinate.
-       * @return {ol.TileCoord} Tile coordinate.
-       */
-      function(tileCoord, projection, opt_tileCoord) {
-        goog.asserts.assert(!goog.isNull(tileGrid),
-            'tileGrid must not be null');
-        if (tileGrid.getResolutions().length <= tileCoord[0]) {
-          return null;
-        }
-        var x = tileCoord[1];
-        var y = -tileCoord[2] - 1;
-        var tileExtent = tileGrid.getTileCoordExtent(tileCoord, tmpExtent);
-        var extent = projection.getExtent();
-
-        if (!ol.extent.intersects(tileExtent, extent) ||
-            ol.extent.touches(tileExtent, extent)) {
-          return null;
-        }
-        return ol.tilecoord.createOrUpdate(tileCoord[0], x, y, opt_tileCoord);
-      },
+      ol.tilegrid.createOriginTopLeftTileCoordTransform(tileGrid),
      tileUrlFunction);

  goog.base(this, {
@@ -450,9 +426,6 @@ ol.source.WMTS.optionsFromCapabilities = function(wmtsCap, config) {
  goog.asserts.assert(!goog.isNull(matrixSetObj),
      'found matrixSet in Contents/TileMatrixSet');

-  var tileGrid = ol.tilegrid.WMTS.createFromCapabilitiesMatrixSet(
-      matrixSetObj);
-
  var projection;
  if (goog.isDef(config['projection'])) {
    projection = ol.proj.get(config['projection']);
@@ -461,6 +434,19 @@ ol.source.WMTS.optionsFromCapabilities = function(wmtsCap, config) {
        /urn:ogc:def:crs:(\w+):(.*:)?(\w+)$/, '$1:$3'));
  }

+  var projectionExtent = projection.getExtent();
+  var extent;
+  if (!goog.isNull(projectionExtent)) {
+    var projectionExtentWgs84 = ol.proj.transformExtent(
+        projectionExtent, projection, 'EPSG:4326');
+    if (ol.extent.containsExtent(projectionExtentWgs84, wgs84BoundingBox)) {
+      extent = ol.proj.transformExtent(
+          wgs84BoundingBox, 'EPSG:4326', projection);
+    }
+  }
+  var tileGrid = ol.tilegrid.WMTS.createFromCapabilitiesMatrixSet(
+      matrixSetObj, extent);
+
  /** @type {!Array.<string>} */
  var urls = [];
  var requestEncoding = config['requestEncoding'];
--- a/src/ol/tilecoord.js
+++ b/src/ol/tilecoord.js
@@ -3,7 +3,7 @@ goog.provide('ol.tilecoord');

 goog.require('goog.array');
 goog.require('goog.asserts');
-goog.require('goog.math');
+goog.require('ol.extent');


 /**
@@ -149,25 +149,42 @@ ol.tilecoord.toString = function(tileCoord) {
 */
 ol.tilecoord.wrapX = function(tileCoord, tileGrid, projection) {
  var z = tileCoord[0];
-  var x = tileCoord[1];
-  var tileRange = tileGrid.getTileRange(z, projection);
-  if (x < tileRange.minX || x > tileRange.maxX) {
-    x = goog.math.modulo(x, tileRange.getWidth());
-    return [z, x, tileCoord[2]];
+  var center = tileGrid.getTileCoordCenter(tileCoord);
+  var projectionExtent = ol.tilegrid.extentFromProjection(projection);
+  if (!ol.extent.containsCoordinate(projectionExtent, center)) {
+    var worldWidth = ol.extent.getWidth(projectionExtent);
+    var worldsAway = Math.ceil((projectionExtent[0] - center[0]) / worldWidth);
+    center[0] += worldWidth * worldsAway;
+    return tileGrid.getTileCoordForCoordAndZ(center, z);
+  } else {
+    return tileCoord;
  }
-  return tileCoord;
 };


 /**
 * @param {ol.TileCoord} tileCoord Tile coordinate.
- * @param {ol.tilegrid.TileGrid} tileGrid Tile grid.
- * @param {ol.proj.Projection} projection Projection.
+ * @param {!ol.tilegrid.TileGrid} tileGrid Tile grid.
 * @return {ol.TileCoord} Tile coordinate.
 */
-ol.tilecoord.clipX = function(tileCoord, tileGrid, projection) {
+ol.tilecoord.restrictByExtentAndZ = function(tileCoord, tileGrid) {
  var z = tileCoord[0];
  var x = tileCoord[1];
-  var tileRange = tileGrid.getTileRange(z, projection);
-  return (x < tileRange.minX || x > tileRange.maxX) ? null : tileCoord;
+  var y = tileCoord[2];
+
+  if (tileGrid.getMinZoom() > z || z > tileGrid.getMaxZoom()) {
+    return null;
+  }
+  var extent = tileGrid.getExtent();
+  var tileRange;
+  if (goog.isNull(extent)) {
+    tileRange = tileGrid.getFullTileRange(z);
+  } else {
+    tileRange = tileGrid.getTileRangeForExtentAndZ(extent, z);
+  }
+  if (goog.isNull(tileRange)) {
+    return tileCoord;
+  } else {
+    return tileRange.containsXY(x, y) ? tileCoord : null;
+  }
 };
--- a/src/ol/tilegrid/tilegrid.js
+++ b/src/ol/tilegrid/tilegrid.js
@@ -4,6 +4,7 @@ goog.require('goog.array');
 goog.require('goog.asserts');
 goog.require('goog.functions');
 goog.require('goog.math');
+goog.require('goog.object');
 goog.require('ol');
 goog.require('ol.Coordinate');
 goog.require('ol.TileCoord');
@@ -69,6 +70,10 @@ ol.tilegrid.TileGrid = function(options) {
    goog.asserts.assert(this.origins_.length == this.resolutions_.length,
        'number of origins and resolutions must be equal');
  }
+  if (goog.isNull(this.origins_) && goog.isNull(this.origin_) &&
+      goog.isDef(options.extent)) {
+    this.origin_ = ol.extent.getBottomLeft(options.extent);
+  }
  goog.asserts.assert(
      (goog.isNull(this.origin_) && !goog.isNull(this.origins_)) ||
      (!goog.isNull(this.origin_) && goog.isNull(this.origins_)),
@@ -97,6 +102,51 @@ ol.tilegrid.TileGrid = function(options) {
      (!goog.isNull(this.tileSize_) && goog.isNull(this.tileSizes_)),
      'either tileSize or tileSizes must be configured, never both');

+  var extent = options.extent;
+
+  /**
+   * @private
+   * @type {ol.Extent}
+   */
+  this.extent_ = goog.isDef(extent) ? extent : null;
+
+  /**
+   * @private
+   * @type {Array.<ol.TileRange>}
+   */
+  this.fullTileRanges_ = null;
+
+  if (goog.isDef(options.sizes)) {
+    goog.asserts.assert(options.sizes.length == this.resolutions_.length,
+        'number of sizes and resolutions must be equal');
+    this.fullTileRanges_ = goog.array.map(options.sizes, function(size, z) {
+      goog.asserts.assert(size[0] > 0, 'width must be > 0');
+      goog.asserts.assert(size[1] !== 0, 'height must not be 0');
+      var tileRange = new ol.TileRange(0, size[0] - 1, 0, size[1] - 1);
+      if (tileRange.maxY < tileRange.minY) {
+        tileRange.minY = size[1];
+        tileRange.maxY = -1;
+      }
+      if (this.minZoom <= z && z <= this.maxZoom && goog.isDef(extent)) {
+        goog.asserts.assert(tileRange.containsTileRange(
+            this.getTileRangeForExtentAndZ(extent, z)),
+            'extent tile range must not exceed tilegrid width and height');
+      }
+      return tileRange;
+    }, this);
+  } else if (goog.isDef(extent)) {
+    var extentWidth = ol.extent.getWidth(extent);
+    var extentHeight = ol.extent.getHeight(extent);
+    var fullTileRanges = new Array(this.resolutions_.length);
+    var tileSize;
+    for (var z = 0, zz = fullTileRanges.length; z < zz; ++z) {
+      tileSize = ol.size.toSize(this.getTileSize(z), this.tmpSize_);
+      fullTileRanges[z] = new ol.TileRange(
+          0, Math.ceil(extentWidth / tileSize[0] / this.resolutions_[z]) - 1,
+          0, Math.ceil(extentHeight / tileSize[1] / this.resolutions_[z]) - 1);
+    }
+    this.fullTileRanges_ = fullTileRanges;
+  }

  /**
   * @private
@@ -104,17 +154,6 @@ ol.tilegrid.TileGrid = function(options) {
   */
  this.tmpSize_ = [0, 0];

-  /**
-   * @private
-   * @type {Array.<number>}
-   */
-  this.widths_ = null;
-  if (goog.isDef(options.widths)) {
-    this.widths_ = options.widths;
-    goog.asserts.assert(this.widths_.length == this.resolutions_.length,
-        'number of widths and resolutions must be equal');
-  }
-
 };


@@ -161,6 +200,15 @@ ol.tilegrid.TileGrid.prototype.forEachTileCoordParentTileRange =
 };


+/**
+ * Get the extent for this tile grid, if it was configured.
+ * @return {ol.Extent} Extent.
+ */
+ol.tilegrid.TileGrid.prototype.getExtent = function() {
+  return this.extent_;
+};
+
+
 /**
 * Get the maximum zoom level for the grid.
 * @return {number} Max zoom.
@@ -412,25 +460,6 @@ ol.tilegrid.TileGrid.prototype.getTileCoordResolution = function(tileCoord) {
 };


-/**
- * @param {number} z Zoom level.
- * @param {ol.proj.Projection} projection Projection.
- * @param {ol.TileRange=} opt_tileRange Tile range.
- * @return {ol.TileRange} Tile range.
- */
-ol.tilegrid.TileGrid.prototype.getTileRange =
-    function(z, projection, opt_tileRange) {
-  var projectionExtentTileRange = this.getTileRangeForExtentAndZ(
-      ol.tilegrid.extentFromProjection(projection), z);
-  var width = this.getWidth(z);
-  if (!goog.isDef(width)) {
-    width = projectionExtentTileRange.getWidth();
-  }
-  return ol.TileRange.createOrUpdate(
-      0, width - 1, 0, projectionExtentTileRange.getHeight(), opt_tileRange);
-};
-
-
 /**
 * Get the tile size for a zoom level. The type of the return value matches the
 * `tileSize` or `tileSizes` that the tile grid was configured with. To always
@@ -455,15 +484,16 @@ ol.tilegrid.TileGrid.prototype.getTileSize = function(z) {

 /**
 * @param {number} z Zoom level.
- * @return {number|undefined} Width for the specified zoom level or `undefined`
- *     if unknown.
+ * @return {ol.TileRange} Extent tile range for the specified zoom level.
 */
-ol.tilegrid.TileGrid.prototype.getWidth = function(z) {
-  if (!goog.isNull(this.widths_)) {
+ol.tilegrid.TileGrid.prototype.getFullTileRange = function(z) {
+  if (goog.isNull(this.fullTileRanges_)) {
+    return null;
+  } else {
    goog.asserts.assert(this.minZoom <= z && z <= this.maxZoom,
        'z is not in allowed range (%s <= %s <= %s',
        this.minZoom, z, this.maxZoom);
-    return this.widths_[z];
+    return this.fullTileRanges_[z];
  }
 };

@@ -478,26 +508,6 @@ ol.tilegrid.TileGrid.prototype.getZForResolution = function(resolution) {
 };


-/**
- * @param {number} z Zoom level.
- * @param {ol.proj.Projection} projection Projection.
- * @return {boolean} Whether the tile grid is defined for the whole globe when
- *     used with the provided `projection` at zoom level `z`.
- */
-ol.tilegrid.TileGrid.prototype.isGlobal = function(z, projection) {
-  var width = this.getWidth(z);
-  if (goog.isDef(width)) {
-    var projTileGrid = ol.tilegrid.getForProjection(projection);
-    var projExtent = projection.getExtent();
-    return ol.size.toSize(this.getTileSize(z), this.tmpSize_)[0] * width ==
-        projTileGrid.getTileSize(z) *
-        projTileGrid.getTileRangeForExtentAndZ(projExtent, z).getWidth();
-  } else {
-    return projection.isGlobal();
-  }
-};
-
-
 /**
 * @param {ol.proj.Projection} projection Projection.
 * @return {ol.tilegrid.TileGrid} Default tile grid for the passed projection.
@@ -611,3 +621,36 @@ ol.tilegrid.extentFromProjection = function(projection) {
  }
  return extent;
 };
+
+
+/**
+ * @param {ol.tilegrid.TileGrid} tileGrid Tile grid.
+ * @return {function(ol.TileCoord, ol.proj.Projection, ol.TileCoord=):
+ *     ol.TileCoord} Tile coordinate transform.
+ */
+ol.tilegrid.createOriginTopLeftTileCoordTransform = function(tileGrid) {
+  goog.asserts.assert(!goog.isNull(tileGrid), 'tileGrid required');
+  return (
+      /**
+       * @param {ol.TileCoord} tileCoord Tile coordinate.
+       * @param {ol.proj.Projection} projection Projection.
+       * @param {ol.TileCoord=} opt_tileCoord Destination tile coordinate.
+       * @return {ol.TileCoord} Tile coordinate.
+       */
+      function(tileCoord, projection, opt_tileCoord) {
+        if (goog.isNull(tileCoord)) {
+          return null;
+        }
+        var z = tileCoord[0];
+        var fullTileRange = tileGrid.getFullTileRange(z);
+        var height;
+        if (goog.isNull(fullTileRange) || fullTileRange.minY < 0) {
+          height = 0;
+        } else {
+          height = fullTileRange.getHeight();
+        }
+        return ol.tilecoord.createOrUpdate(
+            z, tileCoord[1], height - tileCoord[2] - 1, opt_tileCoord);
+      }
+  );
+};
--- a/src/ol/tilegrid/wmtstilegrid.js
+++ b/src/ol/tilegrid/wmtstilegrid.js
@@ -32,12 +32,13 @@ ol.tilegrid.WMTS = function(options) {
  // FIXME: should the matrixIds become optionnal?

  goog.base(this, {
+    extent: options.extent,
    origin: options.origin,
    origins: options.origins,
    resolutions: options.resolutions,
    tileSize: options.tileSize,
    tileSizes: options.tileSizes,
-    widths: options.widths
+    sizes: options.sizes
  });

 };
@@ -69,11 +70,13 @@ ol.tilegrid.WMTS.prototype.getMatrixIds = function() {
 * Create a tile grid from a WMTS capabilities matrix set.
 * @param {Object} matrixSet An object representing a matrixSet in the
 *     capabilities document.
+ * @param {ol.Extent=} opt_extent An optional extent to restrict the tile
+ *     ranges the server provides.
 * @return {ol.tilegrid.WMTS} WMTS tileGrid instance.
 * @api
 */
 ol.tilegrid.WMTS.createFromCapabilitiesMatrixSet =
-    function(matrixSet) {
+    function(matrixSet, opt_extent) {

  /** @type {!Array.<number>} */
  var resolutions = [];
@@ -83,8 +86,8 @@ ol.tilegrid.WMTS.createFromCapabilitiesMatrixSet =
  var origins = [];
  /** @type {!Array.<ol.Size>} */
  var tileSizes = [];
-  /** @type {!Array.<number>} */
-  var widths = [];
+  /** @type {!Array.<ol.Size>} */
+  var sizes = [];

  var supportedCRSPropName = 'SupportedCRS';
  var matrixIdsPropName = 'TileMatrix';
@@ -108,26 +111,30 @@ ol.tilegrid.WMTS.createFromCapabilitiesMatrixSet =
  goog.array.forEach(matrixSet[matrixIdsPropName],
      function(elt, index, array) {
        matrixIds.push(elt[identifierPropName]);
+        var resolution = elt[scaleDenominatorPropName] * 0.28E-3 /
+            metersPerUnit;
+        var tileWidth = elt[tileWidthPropName];
+        var tileHeight = elt[tileHeightPropName];
+        var matrixHeight = elt['MatrixHeight'];
        if (switchOriginXY) {
          origins.push([elt[topLeftCornerPropName][1],
            elt[topLeftCornerPropName][0]]);
        } else {
          origins.push(elt[topLeftCornerPropName]);
        }
-        resolutions.push(elt[scaleDenominatorPropName] * 0.28E-3 /
-            metersPerUnit);
-        var tileWidth = elt[tileWidthPropName];
-        var tileHeight = elt[tileHeightPropName];
+        resolutions.push(resolution);
        tileSizes.push(tileWidth == tileHeight ?
            tileWidth : [tileWidth, tileHeight]);
-        widths.push(elt['MatrixWidth']);
+        // top-left origin, so height is negative
+        sizes.push([elt['MatrixWidth'], -matrixHeight]);
      });

  return new ol.tilegrid.WMTS({
+    extent: opt_extent,
    origins: origins,
    resolutions: resolutions,
    matrixIds: matrixIds,
    tileSizes: tileSizes,
-    widths: widths
+    sizes: sizes
  });
 };