Adds zoom_adjust to add_basemap (#228)

* adds zoom_adjust, needs to be tested

* creates venv and test file

* removes temporary files and adds to docstrings

* removes temporary files

* resolve diff

* removes Stamen (deprecated) from providers test

* add test to add_basemap zoom_adjust

* better merge commit

---------

Co-authored-by: Martin Fleischmann <martin@martinfleischmann.net>

contextily/plotting.py

@@ -25,6 +25,7 @@ def add_basemap(
     reset_extent=True,
     crs=None,
     resampling=Resampling.bilinear,
+    zoom_adjust=None,
     **extra_imshow_args
 ):
     """
@@ -75,6 +76,10 @@ def add_basemap(
         [Optional. Default=Resampling.bilinear] Resampling
         method for executing warping, expressed as a
         `rasterio.enums.Resampling` method
+    zoom_adjust : int or None
+        [Optional. Default: None]
+        The amount to adjust a chosen zoom level if it is chosen automatically. 
+        Values outside of -1 to 1 are not recommended as they can lead to slow execution.
     **extra_imshow_args :
         Other parameters to be passed to `imshow`.
 
@@ -127,7 +132,7 @@ def add_basemap(
             )
         # Download image
         image, extent = bounds2img(
-            left, bottom, right, top, zoom=zoom, source=source, ll=False
+            left, bottom, right, top, zoom=zoom, source=source, ll=False, zoom_adjust=zoom_adjust
         )
         # Warping
         if crs is not None:

contextily/tile.py

@@ -171,7 +171,7 @@ def bounds2raster(
 
 
 def bounds2img(
-    w, s, e, n, zoom="auto", source=None, ll=False, wait=0, max_retries=2, n_connections=1, use_cache=True
+    w, s, e, n, zoom="auto", source=None, ll=False, wait=0, max_retries=2, n_connections=1, use_cache=True, zoom_adjust=None
 ):
     """
     Take bounding box and zoom and return an image with all the tiles
@@ -220,6 +220,10 @@ def bounds2img(
         If False, caching of the downloaded tiles will be disabled. This can be useful in resource constrained
         environments, especially when using n_connections > 1, or when a tile provider's terms of use don't allow
         caching.
+    zoom_adjust : int or None
+        [Optional. Default: None]
+        The amount to adjust a chosen zoom level if it is chosen automatically.
+        Values outside of -1 to 1 are not recommended as they can lead to slow execution.
 
     Returns
     -------
@@ -239,6 +243,8 @@ def bounds2img(
     auto_zoom = zoom == "auto"
     if auto_zoom:
         zoom = _calculate_zoom(w, s, e, n)
+    if zoom_adjust:
+        zoom += zoom_adjust
     zoom = _validate_zoom(zoom, provider, auto=auto_zoom)
     # create list of tiles to download
     tiles = list(mt.tiles(w, s, e, n, [zoom]))

tests/test_cx.py

@@ -354,10 +354,10 @@ def test_add_basemap_query():
     ax_extent = (x1, x2, y1, y2)
     assert ax.axis() == ax_extent
 
-    assert ax.images[0].get_array().sum() == 64717007
+    assert ax.images[0].get_array().sum() == 64691220
     assert ax.images[0].get_array().shape == (256, 256, 4)
-    assert_array_almost_equal(ax.images[0].get_array()[:, :, :3].mean(), 244.167719)
-    assert_array_almost_equal(ax.images[0].get_array().mean(), 246.875789642)
+    assert_array_almost_equal(ax.images[0].get_array()[:, :, :3].mean(), 244.03656)
+    assert_array_almost_equal(ax.images[0].get_array().mean(), 246.77742)
 
 
 @pytest.mark.network
@@ -420,6 +420,43 @@ def test_add_basemap_auto_zoom():
     )
     assert_array_almost_equal(ax.images[0].get_array().mean(), 217.2718038, decimal=0)
 
+@pytest.mark.network
+@pytest.mark.parametrize("zoom_adjust, expected_extent, expected_sum_1, expected_sum_2, expected_shape", [
+    # zoom_adjust and expected values where zoom_adjust == 1
+    (1, (
+        -11740727.544603072,
+        -11701591.786121061,
+        4852834.051769271,
+        4891969.810251278,
+    ), 648244877, 915631757, (1024, 1024, 4)),
+
+    # zoom_adjust and expected values where zoom_adjust == -1
+    (-1, (
+        -11740727.544603072,
+        -11701591.786121061,
+        4852834.051769271,
+        4891969.810251278,
+    ), 40396582, 57108262, (256, 256, 4)),
+])
+def test_add_basemap_zoom_adjust(zoom_adjust, expected_extent, expected_sum_1, expected_sum_2, expected_shape):
+    x1, x2, y1, y2 = [-11740727.544603072, -11701591.786121061, 4852834.0517692715, 4891969.810251278]
+
+    f, ax = matplotlib.pyplot.subplots(1)
+    ax.set_xlim(x1, x2)
+    ax.set_ylim(y1, y2)
+    cx.add_basemap(ax, zoom="auto", zoom_adjust=zoom_adjust)
+
+    ax_extent = expected_extent
+    assert_array_almost_equal(ax_extent, ax.images[0].get_extent())
+
+    assert ax.images[0].get_array()[:, :, :3].sum() == pytest.approx(expected_sum_1, rel=0.1)
+    assert ax.images[0].get_array().sum() == pytest.approx(expected_sum_2, rel=0.1)
+    assert ax.images[0].get_array().shape == expected_shape
+    assert_array_almost_equal(
+        ax.images[0].get_array()[:, :, :3].mean(), 204.695738, decimal=0
+    )
+    assert_array_almost_equal(ax.images[0].get_array().mean(), 217.2718038, decimal=0)
+
 
 @pytest.mark.network
 def test_add_basemap_warping():

tests/test_providers.py

@@ -16,7 +16,6 @@ def test_providers():
     )
     for provider in [
         cx.providers.OpenStreetMap.Mapnik,
-        cx.providers.Stamen.Toner,
         cx.providers.NASAGIBS.ViirsEarthAtNight2012,
     ]:
         cx.bounds2img(w, s, e, n, 4, source=provider, ll=True)