Adding --decimation_base option to cogeo cli, along with docs

docs/docs/Advanced.md

@@ -41,6 +41,20 @@ print(overviews)
 [2, 4, 8]
 ```
 
+### Decimation Base
+
+As described above, a decimation base of 2 is used by default. However you can provide a custom base, N > 1, with *--decimation-base N*. Optimal overviews are computed assuming a base 2 is used, so using *--decimation-base* also requires that *--overview-level* is provided. Similar to the default example, here are the overviews for base 3:
+
+```python
+overview_level = 3
+decimation_base = 3
+overviews = [decimation_base ** j for j in range(1, overview_level + 1)]
+print(overviews)
+[3, 9, 27]
+```
+
+This is primarily useful when working with [custom TileMatrixSets](https://developmentseed.org/morecantile/usage/#define-custom-grid) that also use a non-default decimation base.
+
 ## Band metadata
 By default rio cogeo DO NOT forward **band** metadata (e.g statistics) to the output dataset.
 

rio_cogeo/scripts/cli.py

@@ -122,6 +122,14 @@ def cogeo():
     "selected until the smallest overview is smaller than the value of the "
     "internal blocksize)",
 )
+@click.option(
+    "--decimation-base",
+    type=int,
+    help="Decimation base, how to sub-divide a raster for each overview level. "
+    "Also requires that --overview-level is provided.",
+    default=2,
+    show_default=True,
+)
 @click.option(
     "--overview-resampling",
     help="Overview creation resampling algorithm.",
@@ -230,6 +238,7 @@ def create(
     add_mask,
     blocksize,
     overview_level,
+    decimation_base,
     overview_resampling,
     overview_blocksize,
     web_optimized,
@@ -318,6 +327,7 @@ def create(
         tms=tilematrixset,
         use_cog_driver=use_cog_driver,
         quiet=quiet,
+        decimation_base=decimation_base,
     )
 
 

tests/test_cli.py

@@ -210,6 +210,28 @@ def test_cogeo_validOvrOption(runner):
             assert src.overviews(1) == [2, 4]
 
 
+def test_cogeo_decimation_base_option(runner):
+    """Should work as expected."""
+    with runner.isolated_filesystem():
+        result = runner.invoke(
+            cogeo,
+            [
+                "create",
+                raster_path_rgb,
+                "output.tif",
+                "--decimation-base",
+                3,
+                "--overview-level",
+                6,
+            ],
+        )
+        assert not result.exception
+        assert result.exit_code == 0
+        with rasterio.open("output.tif") as src:
+            assert len(src.overviews(1)) == 6
+            assert src.overviews(1)[0] == 3
+
+
 def test_cogeo_overviewTilesize(monkeypatch, runner):
     """Should work as expected."""
     with runner.isolated_filesystem():