allow bidx option in multibasetiler (#724)

CHANGES.md

@@ -1,5 +1,41 @@
 # Release Notes
 
+## 0.15.4 (2023-11-06)
+
+### titiler.core
+
+* update `rio-tiler` requirement to `>=6.2.5,<7.0`
+
+* allow `bidx` option in `titiler.core.dependencies.AssetsBidxExprParams` and `titiler.core.dependencies.AssetsBidxParams`
+
+    ```python
+    # merge band 1 form asset1 and asset2
+    # before
+    httpx.get(
+        "/stac/preview",
+        params=(
+            ("url", "stac.json"),
+            ("assets", "asset1"),
+            ("assets", "asset2"),
+            ("asset_bidx", "asset1|1"),
+            ("asset_bidx", "asset2|1"),
+        )
+    )
+
+    # now
+    httpx.get(
+        "/stac/preview",
+        params=(
+            ("url", "stac.json"),
+            ("assets", "asset1"),
+            ("assets", "asset2"),
+            ("bidx", 1),
+        )
+    )
+    ```
+
+* fix openapi examples
+
 ## 0.15.3 (2023-11-02)
 
 * add `dst_crs` options in `/statistics [POST]` and `/feature [POST]` endpoints

docs/src/advanced/dependencies.md

@@ -57,7 +57,7 @@ class AssetsParams(DefaultDependency):
         None,
         title="Asset names",
         description="Asset's names.",
-        examples={
+        openapi_examples={
             "one-asset": {
                 "description": "Return results for asset `data`.",
                 "value": ["data"],
@@ -96,7 +96,7 @@ class AssetsBidxParams(AssetsParams):
             title="Per asset band indexes",
             description="Per asset band indexes",
             alias="asset_bidx",
-            examples={
+            openapi_examples={
                 "one-asset": {
                     "description": "Return indexes 1,2,3 of asset `data`.",
                     "value": ["data|1;2;3"],
@@ -114,7 +114,7 @@ class AssetsBidxParams(AssetsParams):
         Query(
             title="Per asset band expression",
             description="Per asset band expression",
-            examples={
+            openapi_examples={
                 "one-asset": {
                     "description": "Return results for expression `b1*b2+b3` of asset `data`.",
                     "value": ["data|b1*b2+b3"],
@@ -168,7 +168,7 @@ class AssetsBidxExprParams(AssetsParams):
         Query(
             title="Band Math expression",
             description="Band math expression between assets",
-            examples={
+            openapi_examples={
                 "simple": {
                     "description": "Return results of expression between assets.",
                     "value": "asset1_b1 + asset2_b1 / asset3_b1",
@@ -183,7 +183,7 @@ class AssetsBidxExprParams(AssetsParams):
             title="Per asset band indexes",
             description="Per asset band indexes (coma separated indexes)",
             alias="asset_bidx",
-            examples={
+            openapi_examples={
                 "one-asset": {
                     "description": "Return indexes 1,2,3 of asset `data`.",
                     "value": ["data|1,2,3"],
@@ -269,7 +269,7 @@ class BandsParams(DefaultDependency):
         None,
         title="Band names",
         description="Band's names.",
-        examples={
+        openapi_examples={
             "one-band": {
                 "description": "Return results for band `B01`.",
                 "value": ["B01"],
@@ -350,7 +350,7 @@ class BidxParams(DefaultDependency):
             title="Band indexes",
             alias="bidx",
             description="Dataset band indexes",
-            examples={"one-band": {"value": [1]}, "multi-bands": {"value": [1, 2, 3]}},
+            openapi_examples={"one-band": {"value": [1]}, "multi-bands": {"value": [1, 2, 3]}},
         ),
     ] = None
 ```
@@ -378,7 +378,7 @@ class ExpressionParams(DefaultDependency):
         Query(
             title="Band Math expression",
             description="rio-tiler's band math expression",
-            examples={
+            openapi_examples={
                 "simple": {"description": "Simple band math.", "value": "b1/b2"},
                 "multi-bands": {
                     "description": "Semicolon (;) delimited expressions (band1: b1/b2, band2: b2+b3).",
@@ -654,7 +654,7 @@ If bins is a sequence (comma `,` delimited values), it defines a monotonically i
 
 link: https://numpy.org/doc/stable/reference/generated/numpy.histogram.html
             """,
-            examples={
+            openapi_examples={
                 "simple": {
                     "description": "Defines the number of equal-width bins",
                     "value": 8,

src/titiler/core/pyproject.toml

@@ -35,7 +35,7 @@ dependencies = [
     "numpy",
     "pydantic~=2.0",
     "rasterio",
-    "rio-tiler>=6.2.1,<7.0",
+    "rio-tiler>=6.2.5,<7.0",
     "morecantile>=5.0,<6.0",
     "simplejson",
     "typing_extensions>=4.6.1",

src/titiler/core/tests/test_factories.py

@@ -746,6 +746,25 @@ def test_MultiBaseTilerFactory(rio):
     assert meta["dtype"] == "uint16"
     assert meta["count"] == 3
 
+    response = client.get(
+        f"/preview.tif?url={DATA_DIR}/item.json&assets=B01&bidx=1&bidx=1&return_mask=false"
+    )
+    assert response.status_code == 200
+    assert response.headers["content-type"] == "image/tiff; application=geotiff"
+    meta = parse_img(response.content)
+    assert meta["dtype"] == "uint16"
+    assert meta["count"] == 2
+
+    with pytest.warns(UserWarning):
+        response = client.get(
+            f"/preview.tif?url={DATA_DIR}/item.json&assets=B01&asset_bidx=B01|1,1,1&bidx=1&return_mask=false"
+        )
+        assert response.status_code == 200
+        assert response.headers["content-type"] == "image/tiff; application=geotiff"
+        meta = parse_img(response.content)
+        assert meta["dtype"] == "uint16"
+        assert meta["count"] == 3
+
     response = client.get(
         "/preview.tif",
         params={

src/titiler/core/titiler/core/dependencies.py

@@ -1,6 +1,7 @@
 """Common dependency."""
 
 import json
+import warnings
 from dataclasses import dataclass
 from typing import Callable, Dict, List, Literal, Optional, Sequence, Tuple, Union
 
@@ -86,7 +87,10 @@ class BidxParams(DefaultDependency):
             title="Band indexes",
             alias="bidx",
             description="Dataset band indexes",
-            examples={"one-band": {"value": [1]}, "multi-bands": {"value": [1, 2, 3]}},
+            openapi_examples={
+                "one-band": {"value": [1]},
+                "multi-bands": {"value": [1, 2, 3]},
+            },
         ),
     ] = None
 
@@ -100,7 +104,7 @@ class ExpressionParams(DefaultDependency):
         Query(
             title="Band Math expression",
             description="rio-tiler's band math expression",
-            examples={
+            openapi_examples={
                 "simple": {"description": "Simple band math.", "value": "b1/b2"},
                 "multi-bands": {
                     "description": "Semicolon (;) delimited expressions (band1: b1/b2, band2: b2+b3).",
@@ -128,7 +132,7 @@ class AssetsParams(DefaultDependency):
         Query(
             title="Asset names",
             description="Asset's names.",
-            examples={
+            openapi_examples={
                 "one-asset": {
                     "description": "Return results for asset `data`.",
                     "value": ["data"],
@@ -143,15 +147,15 @@ class AssetsParams(DefaultDependency):
 
 
 @dataclass
-class AssetsBidxExprParams(AssetsParams):
+class AssetsBidxExprParams(AssetsParams, BidxParams):
     """Assets, Expression and Asset's band Indexes parameters."""
 
     expression: Annotated[
         Optional[str],
         Query(
             title="Band Math expression",
             description="Band math expression between assets",
-            examples={
+            openapi_examples={
                 "simple": {
                     "description": "Return results of expression between assets.",
                     "value": "asset1_b1 + asset2_b1 / asset3_b1",
@@ -166,7 +170,7 @@ class AssetsBidxExprParams(AssetsParams):
             title="Per asset band indexes",
             description="Per asset band indexes (coma separated indexes)",
             alias="asset_bidx",
-            examples={
+            openapi_examples={
                 "one-asset": {
                     "description": "Return indexes 1,2,3 of asset `data`.",
                     "value": ["data|1,2,3"],
@@ -200,6 +204,12 @@ def __post_init__(self):
                 for idx in self.asset_indexes
             }
 
+        if self.asset_indexes and self.indexes:
+            warnings.warn(
+                "Both `asset_bidx` and `bidx` passed; only `asset_bidx` will be considered.",
+                UserWarning,
+            )
+
 
 @dataclass
 class AssetsBidxExprParamsOptional(AssetsBidxExprParams):
@@ -213,9 +223,15 @@ def __post_init__(self):
                 for idx in self.asset_indexes
             }
 
+        if self.asset_indexes and self.indexes:
+            warnings.warn(
+                "Both `asset_bidx` and `bidx` passed; only `asset_bidx` will be considered.",
+                UserWarning,
+            )
+
 
 @dataclass
-class AssetsBidxParams(AssetsParams):
+class AssetsBidxParams(AssetsParams, BidxParams):
     """Assets, Asset's band Indexes and Asset's band Expression parameters."""
 
     asset_indexes: Annotated[
@@ -224,7 +240,7 @@ class AssetsBidxParams(AssetsParams):
             title="Per asset band indexes",
             description="Per asset band indexes",
             alias="asset_bidx",
-            examples={
+            openapi_examples={
                 "one-asset": {
                     "description": "Return indexes 1,2,3 of asset `data`.",
                     "value": ["data|1;2;3"],
@@ -242,7 +258,7 @@ class AssetsBidxParams(AssetsParams):
         Query(
             title="Per asset band expression",
             description="Per asset band expression",
-            examples={
+            openapi_examples={
                 "one-asset": {
                     "description": "Return results for expression `b1*b2+b3` of asset `data`.",
                     "value": ["data|b1*b2+b3"],
@@ -268,6 +284,12 @@ def __post_init__(self):
                 idx.split("|")[0]: idx.split("|")[1] for idx in self.asset_expression
             }
 
+        if self.asset_indexes and self.indexes:
+            warnings.warn(
+                "Both `asset_bidx` and `bidx` passed; only `asset_bidx` will be considered.",
+                UserWarning,
+            )
+
 
 # Dependencies for  MultiBandReader
 @dataclass
@@ -279,7 +301,7 @@ class BandsParams(DefaultDependency):
         Query(
             title="Band names",
             description="Band's names.",
-            examples={
+            openapi_examples={
                 "one-band": {
                     "description": "Return results for band `B01`.",
                     "value": ["B01"],
@@ -462,7 +484,7 @@ class HistogramParams(DefaultDependency):
 
 link: https://numpy.org/doc/stable/reference/generated/numpy.histogram.html
             """,
-            examples={
+            openapi_examples={
                 "simple": {
                     "description": "Defines the number of equal-width bins",
                     "value": 8,