TileLayer: add zoomOffset prop

[ilan-gold]

Background

This adds the feature of zoomOffset and updates the docs as well, as mentioned here

Change List

• Add a zoomOffset prop to TileLayer for infovis applications to offset the z level at which tiles are fetched.

[ilan-gold]

This actually seemed more reflective of the state of things now than before. Before both methods used the OSM index, from what I can tell, but now the infovis obeys the above.

[ilan-gold]

Another option here would be Math.ceil(viewport.zoom + zoomOffset) which is less error-prone for users (since it would also produce a valid z value) but would be less interpretable since we apply the ceil operation.

[Pessimistress]

Additional changes:

• Recommend using zoomOffset in upgrade guide
• Update the map-tiles example (tileSize: 256, zoomOffset: devicePixelRatio === 1 ? -1 : 0)
• Update the image-tiles example (data: '${ROOT_URL}/moon.image_files/{z}/{x}_{y}.jpeg', zoomOffset: 15)

[ilan-gold]

The last one doesn't quite work that way, I think. I need to think about this a bit. I think the issue might be the extent prop. I think it assumes that the 0th zoom level is where the full resolution of your tiled image renders, but that wouldn't be the case here. So this might actually be a bug in what we have at the moment.

[ilan-gold]

On second thought, this isn't really how I intended this prop to be used. It is meant more for fetching tiles at a higher or lower resolution given the current zoom level. So changing this prop independent of other things just changes the resolution of the image but this + 15 that currently exists in the image-tiles examples is meant just to reconcile their inverted (compared to ours) system.

[ilan-gold]

The map-tiles use case makes sense to me though, but maybe I am missing something. There, previously, we were actually intentionally affecting the resolution.

[Pessimistress]

Maybe we should clamp z to minZoom, maxZoom before applying any adjustment (both from tileSize and zoomOffset)? Part of the confusion comes from mixing the terms z and zoom. Either way it would be good to explain how this works in the minZoom, maxZoom documentation.

[ilan-gold]

I think that is a good call. This affects the level of fetching, not the viewport to which maxZoom and minZoom should apply.

[ilan-gold]

One issue this could cause would be if you zoom into zoom level 0 with maxZoom: 0 and then offset by some number. The maxZoom prop currently prevents fetching at that level but now you would fetch there even though at zoom level -1 with zoomOffset: 1 you might want to fetch at zoom level 0. I think it is good as it stands now, but we should update the docs to explain that this clips the fetching, which is what is currently done.

[ilan-gold]

Re-requesting review. Added a note to the docs.

[coveralls]

Coverage remained the same at 82.366% when pulling 478b795 on ig/tile_offset_feature_and_docs into 7e1c115 on master.