TileLayer: add zoomOffset prop

docs/api-reference/geo-layers/tile-layer.md

@@ -82,7 +82,7 @@ At each integer zoom level (`z`), the XY plane in the view space is divided into
 
 When the `TileLayer` is used with a geospatial view such as the [MapView](/docs/api-reference/core/map-view.md), x, y, and z are determined from [the OSM tile index](https://wiki.openstreetmap.org/wiki/Slippy_map_tilenames).
 
-When the `TileLayer` is used used with a non-geospatial view such as the [OrthographicView](/docs/api-reference/core/orthographic-view.md) or the [OrbitView](/docs/api-reference/core/orbit-view.md), `x` and `y` increment from the world origin, and each tile's width and height match that defined by the `tileSize` prop. For example, the tile `x: 0, y: 0` occupies the square between `[0, 0]` and `[tileSize, tileSize]`.
+When the `TileLayer` is used used with a non-geospatial view such as the [OrthographicView](/docs/api-reference/core/orthographic-view.md) or the [OrbitView](/docs/api-reference/core/orbit-view.md), `x` and `y` increment from the world origin, and each tile's width and height match that defined by the `tileSize` prop. For example, the tile `x: 0, y: 0` occupies the square between `[0, 0]` and `[tileSize, tileSize]`.  If you need to offset the `z` level at which the tiles are fetched, there is a `tileOffset` prop.
 
 
 ## Properties
@@ -138,10 +138,17 @@ if (signal.aborted) {
 
 The pixel dimension of the tiles, usually a power of 2.
 
-The tile size represents the target pixel width and height of each tile when rendered. Smaller tile sizes display the content at higher resolution, while the layer needs to load more tiles to fill the same viewport.
+For geospatial viewports, tile size represents the target pixel width and height of each tile when rendered. Smaller tile sizes display the content at higher resolution, while the layer needs to load more tiles to fill the same viewport.
+
+For non-geospatial viewports, the tile size should correspond to the true pixel size of the tiles.
 
 - Default: `512`
 
+##### `tileOffset` (Number, optional)
+
+For non-geospatial viewports, this offset changes the zoom level at which the tiles are fetched.
+
+- Default: `0`
 
 ##### `maxZoom` (Number|Null, optional)
 

modules/geo-layers/src/tile-layer/tile-layer.js

@@ -23,7 +23,8 @@ const defaultProps = {
   maxCacheByteSize: null,
   refinementStrategy: STRATEGY_DEFAULT,
   zRange: null,
-  maxRequests: 6
+  maxRequests: 6,
+  tileOffset: 0
 };
 
 export default class TileLayer extends CompositeLayer {
@@ -89,7 +90,8 @@ export default class TileLayer extends CompositeLayer {
       maxCacheByteSize,
       refinementStrategy,
       extent,
-      maxRequests
+      maxRequests,
+      tileOffset
     } = props;
 
     return {
@@ -100,7 +102,8 @@ export default class TileLayer extends CompositeLayer {
       tileSize,
       refinementStrategy,
       extent,
-      maxRequests
+      maxRequests,
+      tileOffset
     };
   }
 

modules/geo-layers/src/tile-layer/tileset-2d.js

@@ -159,7 +159,7 @@ export default class Tileset2D {
 
   // Returns array of {x, y, z}
   getTileIndices({viewport, maxZoom, minZoom, zRange, modelMatrix, modelMatrixInverse}) {
-    const {tileSize, extent} = this.opts;
+    const {tileSize, extent, tileOffset} = this.opts;
     return getTileIndices({
       viewport,
       maxZoom,
@@ -168,13 +168,15 @@ export default class Tileset2D {
       tileSize,
       extent,
       modelMatrix,
-      modelMatrixInverse
+      modelMatrixInverse,
+      tileOffset
     });
   }
 
   // Add custom metadata to tiles
   getTileMetadata({x, y, z}) {
-    return {bbox: tileToBoundingBox(this._viewport, x, y, z)};
+    const {tileSize} = this.opts;
+    return {bbox: tileToBoundingBox(this._viewport, x, y, z, tileSize)};
   }
 
   // Returns {x, y, z} of the parent tile

modules/geo-layers/src/tile-layer/utils.js

@@ -117,8 +117,8 @@ function getIndexingCoords(bbox, scale, modelMatrixInverse) {
   return bbox.map(i => (i * scale) / TILE_SIZE);
 }
 
-function getScale(z) {
-  return Math.pow(2, z);
+function getScale(z, tileSize = TILE_SIZE) {
+  return (Math.pow(2, z) * TILE_SIZE) / tileSize;
 }
 
 // https://wiki.openstreetmap.org/wiki/Slippy_map_tilenames#Lon..2Flat._to_tile_numbers_2
@@ -130,25 +130,24 @@ export function osmTile2lngLat(x, y, z) {
   return [lng, lat];
 }
 
-function tile2XY(x, y, z) {
-  const scale = getScale(z);
+function tile2XY(x, y, z, tileSize) {
+  const scale = getScale(z, tileSize);
   return [(x / scale) * TILE_SIZE, (y / scale) * TILE_SIZE];
 }
-
-export function tileToBoundingBox(viewport, x, y, z) {
+export function tileToBoundingBox(viewport, x, y, z, tileSize = TILE_SIZE) {
   if (viewport.isGeospatial) {
     const [west, north] = osmTile2lngLat(x, y, z);
     const [east, south] = osmTile2lngLat(x + 1, y + 1, z);
     return {west, north, east, south};
   }
-  const [left, top] = tile2XY(x, y, z);
-  const [right, bottom] = tile2XY(x + 1, y + 1, z);
+  const [left, top] = tile2XY(x, y, z, tileSize);
+  const [right, bottom] = tile2XY(x + 1, y + 1, z, tileSize);
   return {left, top, right, bottom};
 }
 
-function getIdentityTileIndices(viewport, z, extent, modelMatrixInverse) {
+function getIdentityTileIndices(viewport, z, tileSize, extent, modelMatrixInverse) {
   const bbox = getBoundingBox(viewport, null, extent);
-  const scale = getScale(z);
+  const scale = getScale(z, tileSize);
   const [minX, minY, maxX, maxY] = getIndexingCoords(bbox, scale, modelMatrixInverse);
   const indices = [];
 
@@ -178,9 +177,12 @@ export function getTileIndices({
   extent,
   tileSize = TILE_SIZE,
   modelMatrix,
-  modelMatrixInverse
+  modelMatrixInverse,
+  tileOffset = 0
 }) {
-  let z = Math.round(viewport.zoom + Math.log2(TILE_SIZE / tileSize));
+  let z = viewport.isGeospatial
+    ? Math.round(viewport.zoom + Math.log2(TILE_SIZE / tileSize))
+    : Math.ceil(viewport.zoom) + tileOffset;
   if (Number.isFinite(minZoom) && z < minZoom) {
     if (!extent) {
       return [];
@@ -196,7 +198,13 @@ export function getTileIndices({
   }
   return viewport.isGeospatial
     ? getOSMTileIndices(viewport, z, zRange, extent || DEFAULT_EXTENT)
-    : getIdentityTileIndices(viewport, z, transformedExtent || DEFAULT_EXTENT, modelMatrixInverse);
+    : getIdentityTileIndices(
+        viewport,
+        z,
+        tileSize,
+        transformedExtent || DEFAULT_EXTENT,
+        modelMatrixInverse
+      );
 }
 
 /**

test/modules/geo-layers/tile-layer/utils.spec.js

@@ -142,7 +142,7 @@ const TEST_CASES = [
       }
     }),
     tileSize: 256,
-    output: ['1,2,4', '1,3,4', '2,2,4', '2,3,4', '3,2,4', '3,3,4', '4,2,4', '4,3,4']
+    output: ['1,2,3', '1,3,3', '2,2,3', '2,3,3', '3,2,3', '3,3,3', '4,2,3', '4,3,3']
   },
   {
     title: 'non-geospatial modelMatrix identity',
@@ -396,6 +396,12 @@ test('tileToBoundingBox#Infovis', t => {
     '0,0,1 Should match the results.'
   );
 
+  t.deepEqual(
+    tileToBoundingBox(viewport, 0, 0, 0, 256),
+    {left: 0, top: 0, right: 256, bottom: 256},
+    '0,0,0 with custom tileSize Should match the results.'
+  );
+
   t.deepEqual(
     tileToBoundingBox(viewport, 4, -1, 2),
     {left: 512, top: -128, right: 640, bottom: 0},
@@ -408,6 +414,12 @@ test('tileToBoundingBox#Infovis', t => {
     '4,-1,3 Should match the results.'
   );
 
+  t.deepEqual(
+    tileToBoundingBox(viewport, 4, -1, 2, 256),
+    {left: 256, top: -64, right: 320, bottom: 0},
+    '4,-1,2 with custom tileSize Should match the results.'
+  );
+
   t.end();
 });