Feature/mosaic asset accessor (#1151)

* add assets_accessor_dependency to MosaicTilerFactory

* update docs

Author: vincentsarago

CHANGES.md

@@ -144,7 +144,7 @@
 * add `/bbox` prefix to `/{minx},{miny},{maxx},{maxy}/assets` endpoint -> `/bbox/{minx},{miny},{maxx},{maxy}/assets` **breaking change**
 * add `/point` prefix to `{lon},{lat}/assets` endpoint -> `/point/{lon},{lat}/assets` **breaking change**
 * add `/tiles` prefix to `/{tileMatrixSetId}/{z}/{x}/{y}/assets` endpoint -> `/tiles/{tileMatrixSetId}/{z}/{x}/{y}/assets` **breaking change**
-
+* add `assets_accessor_dependency` dependency to the MosaicTileFactory to pass options to the backend's `get_assets` method.
 
 ## 0.21.1 (2025-01-29)
 

docs/src/advanced/endpoints_factories.md

@@ -302,6 +302,7 @@ Endpoints factory for mosaics, built on top of [MosaicJSON](https://github.com/d
 - **dataset_reader**: Dataset Reader. Defaults to `rio_tiler.io.Reader`
 - **reader_dependency**: Dependency to control options passed to the reader instance init. Defaults to `titiler.core.dependencies.DefaultDependency`
 - **path_dependency**: Dependency to use to define the dataset url. Defaults to `titiler.mosaic.factory.DatasetPathParams`.
+- **assets_accessor_dependency**: Dependency to define options to be forwarded to the backend `get_assets` method. Defaults to `titiler.core.dependencies.DefaultDependency`.
 - **layer_dependency**: Dependency to define band indexes or expression. Defaults to `titiler.core.dependencies.BidxExprParams`.
 - **dataset_dependency**: Dependency to overwrite `nodata` value, apply `rescaling` and change the `I/O` or `Warp` resamplings. Defaults to `titiler.core.dependencies.DatasetParams`.
 - **tile_dependency**: Dependency to define `buffer` and `padding` to apply at tile creation. Defaults to `titiler.core.dependencies.TileParams`.

src/titiler/mosaic/pyproject.toml

@@ -41,6 +41,7 @@ test = [
     "pytest-cov",
     "pytest-asyncio",
     "httpx",
+    "cogeo-mosaic>=8.2,<9.0",
 ]
 
 [project.urls]

src/titiler/mosaic/tests/test_factory.py

@@ -5,15 +5,18 @@
 from contextlib import contextmanager
 from dataclasses import dataclass
 from io import BytesIO
+from typing import List, Optional
 from unittest.mock import patch
 
+import attr
 import morecantile
 import numpy
 from cogeo_mosaic.backends import FileBackend
 from cogeo_mosaic.mosaic import MosaicJSON
-from fastapi import FastAPI
+from fastapi import FastAPI, Query
 from rio_tiler.mosaic.methods import PixelSelectionMethod
 from starlette.testclient import TestClient
+from typing_extensions import Annotated
 
 from titiler.core.dependencies import DefaultDependency
 from titiler.core.resources.enums import OptionalHeader
@@ -384,3 +387,53 @@ def test_MosaicTilerFactory_strict_zoom():
             )
             assert response.status_code == 400
             assert "Invalid ZOOM level 11" in response.text
+
+
+@dataclass
+class AssetsAccessParams(DefaultDependency):
+    """Backend options to overwrite min/max zoom."""
+
+    limit: Annotated[int, Query()] = 10
+
+
+@attr.s
+class CustomBackend(FileBackend):
+    """Custom FileBackend."""
+
+    def get_assets(
+        self, x: int, y: int, z: int, limit: Optional[int] = None
+    ) -> List[str]:
+        """Find assets."""
+        assets = super().get_assets(x, y, z)
+
+        if limit and len(assets) > limit:
+            return assets[:limit]
+
+        return assets
+
+
+def test_MosaicTilerFactory_asset_accessor():
+    """Test MosaicTilerFactory factory with Backend dependency."""
+    mosaic = MosaicTilerFactory(
+        backend=CustomBackend,
+        router_prefix="/mosaic",
+        assets_accessor_dependency=AssetsAccessParams,
+    )
+    app = FastAPI()
+    app.include_router(mosaic.router, prefix="/mosaic")
+    client = TestClient(app)
+
+    with tmpmosaic() as mosaic_file:
+        response = client.get(
+            "/mosaic/tiles/WGS1984Quad/8/148/61/assets",
+            params={"url": mosaic_file},
+        )
+        assert response.status_code == 200
+        assert len(response.json()) == 2
+
+        response = client.get(
+            "/mosaic/tiles/WGS1984Quad/8/148/61/assets",
+            params={"url": mosaic_file, "limit": 1},
+        )
+        assert response.status_code == 200
+        assert len(response.json()) == 1

src/titiler/mosaic/titiler/mosaic/factory.py

@@ -90,6 +90,9 @@ class MosaicTilerFactory(BaseFactory):
     # Path Dependency
     path_dependency: Callable[..., Any] = DatasetPathParams
 
+    # Backend.get_assets() Options
+    assets_accessor_dependency: Type[DefaultDependency] = DefaultDependency
+
     # Indexes/Expression Dependencies
     layer_dependency: Type[DefaultDependency] = BidxExprParams
 
@@ -585,6 +588,7 @@ def tile(
             src_path=Depends(self.path_dependency),
             backend_params=Depends(self.backend_dependency),
             reader_params=Depends(self.reader_dependency),
+            assets_accessor_params=Depends(self.assets_accessor_dependency),
             layer_params=Depends(self.layer_dependency),
             dataset_params=Depends(self.dataset_dependency),
             pixel_selection=Depends(self.pixel_selection_dependency),
@@ -628,6 +632,7 @@ def tile(
                         **tile_params.as_dict(),
                         **layer_params.as_dict(),
                         **dataset_params.as_dict(),
+                        **assets_accessor_params.as_dict(),
                     )
 
             if post_process:
@@ -687,6 +692,7 @@ def tilejson(
             src_path=Depends(self.path_dependency),
             backend_params=Depends(self.backend_dependency),
             reader_params=Depends(self.reader_dependency),
+            assets_accessor_params=Depends(self.assets_accessor_dependency),
             layer_params=Depends(self.layer_dependency),
             dataset_params=Depends(self.dataset_dependency),
             pixel_selection=Depends(self.pixel_selection_dependency),
@@ -783,6 +789,7 @@ def map_viewer(
             src_path=Depends(self.path_dependency),
             backend_params=Depends(self.backend_dependency),
             reader_params=Depends(self.reader_dependency),
+            assets_accessor_params=Depends(self.assets_accessor_dependency),
             layer_params=Depends(self.layer_dependency),
             dataset_params=Depends(self.dataset_dependency),
             pixel_selection=Depends(self.pixel_selection_dependency),
@@ -856,6 +863,7 @@ def wmts(
             src_path=Depends(self.path_dependency),
             backend_params=Depends(self.backend_dependency),
             reader_params=Depends(self.reader_dependency),
+            assets_accessor_params=Depends(self.assets_accessor_dependency),
             layer_params=Depends(self.layer_dependency),
             dataset_params=Depends(self.dataset_dependency),
             pixel_selection=Depends(self.pixel_selection_dependency),
@@ -982,6 +990,7 @@ def point(
             src_path=Depends(self.path_dependency),
             backend_params=Depends(self.backend_dependency),
             reader_params=Depends(self.reader_dependency),
+            assets_accessor_params=Depends(self.assets_accessor_dependency),
             coord_crs=Depends(CoordCRSParams),
             layer_params=Depends(self.layer_dependency),
             dataset_params=Depends(self.dataset_dependency),
@@ -1002,6 +1011,7 @@ def point(
                         threads=MOSAIC_THREADS,
                         **layer_params.as_dict(),
                         **dataset_params.as_dict(),
+                        **assets_accessor_params.as_dict(),
                     )
 
             return {
@@ -1038,6 +1048,7 @@ def assets_for_bbox(
             src_path=Depends(self.path_dependency),
             backend_params=Depends(self.backend_dependency),
             reader_params=Depends(self.reader_dependency),
+            assets_accessor_params=Depends(self.assets_accessor_dependency),
             coord_crs=Depends(CoordCRSParams),
             env=Depends(self.environment_dependency),
         ):
@@ -1055,6 +1066,7 @@ def assets_for_bbox(
                         maxx,
                         maxy,
                         coord_crs=coord_crs or WGS84_CRS,
+                        **assets_accessor_params.as_dict(),
                     )
 
         @self.router.get(
@@ -1069,6 +1081,7 @@ def assets_for_lon_lat(
             coord_crs=Depends(CoordCRSParams),
             backend_params=Depends(self.backend_dependency),
             reader_params=Depends(self.reader_dependency),
+            assets_accessor_params=Depends(self.assets_accessor_dependency),
             env=Depends(self.environment_dependency),
         ):
             """Return a list of assets which overlap a point"""
@@ -1083,6 +1096,7 @@ def assets_for_lon_lat(
                         lon,
                         lat,
                         coord_crs=coord_crs or WGS84_CRS,
+                        **assets_accessor_params.as_dict(),
                     )
 
         @self.router.get(
@@ -1118,6 +1132,7 @@ def assets_for_tile(
             src_path=Depends(self.path_dependency),
             backend_params=Depends(self.backend_dependency),
             reader_params=Depends(self.reader_dependency),
+            assets_accessor_params=Depends(self.assets_accessor_dependency),
             env=Depends(self.environment_dependency),
         ):
             """Return a list of assets which overlap a given tile"""
@@ -1130,4 +1145,9 @@ def assets_for_tile(
                     reader_options=reader_params.as_dict(),
                     **backend_params.as_dict(),
                 ) as src_dst:
-                    return src_dst.assets_for_tile(x, y, z)
+                    return src_dst.assets_for_tile(
+                        x,
+                        y,
+                        z,
+                        **assets_accessor_params.as_dict(),
+                    )