Merge pull request #279 from alexismanin/refactor/web_optimized_arg

Refactor/web optimized arg

.gitignore

@@ -101,3 +101,7 @@ ENV/
 .mypy_cache/
 
 .pytest_cache
+
+# Jetbrains IDE (PyCharm or other with Python plugin installed)
+.idea
+*.iml

CHANGES.md

@@ -4,6 +4,31 @@
 
 * remove `is_tiled` rasterio method and add better test for blockshapes for the validation script (author @sgillies, https://github.com/cogeotiff/rio-cogeo/pull/278)
 
+* Deprecate parameter **web_optimized** of `cogeo.cog_translate` Python function (author @alexismanin, https://github.com/cogeotiff/rio-cogeo/pull/279)
+
+    ```python
+    # before
+    output_profile = cog_profiles.get(profile)
+
+    tms = morecantile.tms.get("WGS1984Quad")
+    cog_translate(
+        "in.tif",
+        "out.tif",
+        output_profile,
+        web_optimzed=True,
+        tms=tms
+    )
+
+    # now
+    tms = morecantile.tms.get("WGS1984Quad")
+    cog_translate(
+        "in.tif",
+        "out.tif",
+        output_profile,
+        tms=tms
+    )
+    ```
+
 ## 5.1.1 (2024-01-08)
 
 * use morecantile `TileMatrixSet.cellSize` property instead of deprecated/private `TileMatrixSet._resolution` method

CONTRIBUTING.md

@@ -31,10 +31,10 @@ $ cd rio-cogeo
 $ pip install -e .["docs"]
 ```
 
-Hot-reloading docs:
+Hot-reloading docs (from repository root):
 
 ```bash
-$ mkdocs serve
+$ mkdocs serve -f docs/mkdocs.yml
 ```
 
 To manually deploy docs (note you should never need to do this because Github

rio_cogeo/cogeo.py

@@ -126,18 +126,23 @@ def cog_translate(  # noqa: C901
         RasterIO Resampling algorithm for overviews
     web_optimized: bool, optional (default: False)
         Create web-optimized cogeo.
+        Deprecated: Behavior changed since 5.1.2. See deprecation warning at the bottom of function doc.
     tms: morecantile.TileMatrixSet, optional (default: "WebMercatorQuad")
         TileMatrixSet to use for reprojection, resolution and alignment.
     zoom_level_strategy: str, optional (default: auto)
         Strategy to determine zoom level (same as in GDAL 3.2).
+        Used only when either "web_optimized" argument is True, or `tms` is not None.
         LOWER will select the zoom level immediately below the theoretical computed non-integral zoom level, leading to subsampling.
         On the contrary, UPPER will select the immediately above zoom level, leading to oversampling.
         Defaults to AUTO which selects the closest zoom level.
         ref: https://gdal.org/drivers/raster/cog.html#raster-cog
     zoom_level: int, optional.
-        Zoom level number (starting at 0 for coarsest zoom level). If this option is specified, `--zoom-level-strategy` is ignored.
+        Zoom level number (starting at 0 for coarsest zoom level).
+        If this option is specified, `--zoom-level-strategy` is ignored.
+        In any case, it is used only when either "web_optimized" argument is True, or `tms` is not None.
     aligned_levels: int, optional.
         Number of overview levels for which GeoTIFF tile and tiles defined in the tiling scheme match.
+        Used only when either "web_optimized" argument is True, or `tms` is not None.
         Default is to use the maximum overview levels. Note: GDAL use number of resolution levels instead of overview levels.
     resampling : str, optional (default: "nearest")
         Warp Resampling algorithm.
@@ -167,8 +172,20 @@ def cog_translate(  # noqa: C901
     use_cog_driver: bool, optional (default: False)
         Use GDAL COG driver if set to True. COG driver is available starting with GDAL 3.1.
 
+    .. deprecated:: 5.1.2
+        `web_optimized` is deprecated in favor of `tms`.
+        Previously, `tms` usage was conditioned by `web_optimized` state.
+        The behaviour has changed to allow setting a tile matrix set without the need of `web_optimized` flag.
+        `web_optimized` now only serve to activate a default `WebMercatorQuad` tile matrix set.
+        Set to be removed 6.0.
+
     """
-    tms = tms or morecantile.tms.get("WebMercatorQuad")
+    if web_optimized:
+        warnings.warn(
+            "'web_optomized' option is deprecated and will be removed in 6.0. Please use the `tms` option",
+            DeprecationWarning,
+        )
+        tms = tms or morecantile.tms.get("WebMercatorQuad")
 
     dst_kwargs = dst_kwargs.copy()
 
@@ -227,7 +244,7 @@ def cog_translate(  # noqa: C901
             if alpha:
                 vrt_params.update({"add_alpha": False})
 
-            if web_optimized:
+            if tms:
                 wo_params = utils.get_web_optimized_params(
                     src_dst,
                     zoom_level_strategy=zoom_level_strategy,
@@ -345,7 +362,7 @@ def cog_translate(  # noqa: C901
                         ].name.upper()
                     }
                 )
-                if web_optimized:
+                if tms:
                     default_zoom = tms.zoom_for_res(
                         max(tmp_dst.res),
                         max_z=30,

rio_cogeo/scripts/cli.py

@@ -3,8 +3,10 @@
 import json
 import os
 import typing
+from typing import Optional
 
 import click
+import morecantile
 import numpy
 from morecantile import TileMatrixSet
 from rasterio.rio import options
@@ -269,12 +271,13 @@ def create(
         }
     )
 
+    tilematrixset: Optional[TileMatrixSet] = None
     if tms:
         with open(tms, "r") as f:
             tilematrixset = TileMatrixSet(**json.load(f))
 
-    else:
-        tilematrixset = None
+    elif web_optimized:
+        tilematrixset = morecantile.tms.get("WebMercatorQuad")
 
     cog_translate(
         input,
@@ -286,7 +289,6 @@ def create(
         add_mask=add_mask,
         overview_level=overview_level,
         overview_resampling=overview_resampling,
-        web_optimized=web_optimized,
         zoom_level_strategy=zoom_level_strategy,
         zoom_level=zoom_level,
         aligned_levels=aligned_levels,

tests/test_cogeo.py

@@ -3,6 +3,7 @@
 import os
 import pathlib
 
+import morecantile
 import numpy
 import pytest
 import rasterio
@@ -624,6 +625,7 @@ def test_gdal_cog_compare(runner):
 def test_gdal_cog_compareWeb(runner):
     """Test GDAL COG."""
     with runner.isolated_filesystem():
+        web_tms = morecantile.tms.get("WebMercatorQuad")
         profile = cog_profiles.get("jpeg")
         profile["blockxsize"] = 256
         profile["blockysize"] = 256
@@ -635,7 +637,7 @@ def test_gdal_cog_compareWeb(runner):
             profile.copy(),
             quiet=True,
             use_cog_driver=True,
-            web_optimized=True,
+            tms=web_tms,
             aligned_levels=1,
         )
 
@@ -671,12 +673,13 @@ def test_gdal_cog_web_mask(runner):
     """Raise a warning for specific mask/compression/web combination."""
     with runner.isolated_filesystem():
         with pytest.warns(UserWarning):
+            web_tms = morecantile.tms.get("WebMercatorQuad")
             cog_translate(
                 raster_path_rgb,
                 "cogeo.tif",
                 cog_profiles.get("deflate"),
                 use_cog_driver=True,
-                web_optimized=True,
+                tms=web_tms,
                 add_mask=True,
                 quiet=True,
             )