[xarray] add preview endpoints (#1198)

Author: vincentsarago

CHANGES.md

@@ -10,9 +10,13 @@
 
 * add OpenTelemetry tracing to the FastAPI application
 
+### titiler.xarray
+
+* add `add_preview` in factory attribute (default to `False`)
+
 ### Misc
 
-* Add otel-collector and jaeger to the docker network 
+* Add otel-collector and jaeger to the docker network
 
 ## 0.22.4 (2025-07-02)
 

docs/src/advanced/endpoints_factories.md

@@ -359,9 +359,9 @@ class: `titiler.xarray.factory.TilerFactory`
 - **environment_dependency**: Dependency to define GDAL environment at runtime. Default to `lambda: {}`.
 - **supported_tms**: List of available TileMatrixSets. Defaults to `morecantile.tms`.
 - **templates**: *Jinja2* templates to use in endpoints. Defaults to `titiler.core.factory.DEFAULT_TEMPLATES`.
-- **add_part**: . Add `/bbox` and `/feature` endpoints to the router. Defaults to `True`.
-- **add_viewer**: . Add `/map.html` endpoints to the router. Defaults to `True`.
-
+- **add_part**: Add `/bbox` and `/feature` endpoints to the router. Defaults to `True`.
+- **add_viewer**: Add `/map.html` endpoints to the router. Defaults to `True`.
+- **add_preview**: Add `/preview` endpoints to the router. Default to `False`.
 
 ```python
 from fastapi import FastAPI
@@ -373,8 +373,9 @@ app = FastAPI()
 
 # Create router and register set of endpoints
 md = TilerFactory(
-    add_part=True,
-    add_viewer=True,
+    add_part=True,     # default to True
+    add_viewer=True,   # default to True
+    add_preview=True,  # default to False
 )
 
 # add router endpoint to the main application
@@ -398,6 +399,7 @@ app.include_router(md.router)
 | `GET`  | `/point/{lon},{lat}`                                            | JSON ([Point][point_model])                 | return pixel values from a dataset
 | `GET`  | `/bbox/{minx},{miny},{maxx},{maxy}[/{width}x{height}].{format}` | image/bin                                   | create an image from part of a dataset **Optional**
 | `POST` | `/feature[/{width}x{height}][.{format}]`                        | image/bin                                   | create an image from a GeoJSON feature **Optional**
+| `GET`  | `/preview[/{width}x{height}][.{format}]`                        | image/bin                                   | create a preview image from a dataset **Optional**
 
 
 [bounds_model]: https://github.com/cogeotiff/rio-tiler/blob/9aaa88000399ee8d36e71d176f67b6ea3ec53f2d/rio_tiler/models.py#L43-L46

src/titiler/xarray/tests/test_factory.py

@@ -30,14 +30,21 @@ def test_deprecated_extension():
 def test_tiler_factory():
     """Test factory with options."""
     """Test TilerFactory class."""
+    md = TilerFactory()
+    assert len(md.router.routes) == 19
+
+    with pytest.warns(UserWarning):
+        md = TilerFactory(
+            # /preview, /preview.{format}, /preview/{width}x{height}.{format}
+            add_preview=True,
+        )
+        assert len(md.router.routes) == 22
+
     md = TilerFactory(
-        add_viewer=False,
-        add_part=False,
+        router_prefix="/md",
+        # /dataset, /dataset/dict, /dataset/keys
         extensions=[DatasetMetadataExtension()],
     )
-    assert len(md.router.routes) == 16
-
-    md = TilerFactory(router_prefix="/md", extensions=[DatasetMetadataExtension()])
     assert len(md.router.routes) == 22
 
     app = FastAPI()
@@ -377,3 +384,56 @@ def test_zarr_group(group, app):
         params={"url": zarr_pyramid, "variable": "dataset", "group": str(group)},
     )
     assert resp.json()["values"] == [group * 2 + 1]
+
+
+@pytest.mark.parametrize(
+    "filename",
+    [dataset_2d_nc, dataset_3d_nc, dataset_3d_zarr],
+)
+def test_preview(filename):
+    """App fixture."""
+    with pytest.warns(UserWarning):
+        md = TilerFactory(add_preview=True)
+
+    app = FastAPI()
+    app.include_router(md.router)
+    with TestClient(app) as client:
+        resp = client.get(
+            "/preview",
+            params={
+                "url": filename,
+                "variable": "dataset",
+                "rescale": "0,500",
+                "bidx": 1,
+            },
+        )
+        assert resp.status_code == 200
+        assert resp.headers["content-type"] == "image/jpeg"
+
+        resp = client.get(
+            "/preview.png",
+            params={
+                "url": filename,
+                "variable": "dataset",
+                "rescale": "0,500",
+                "bidx": 1,
+            },
+        )
+        assert resp.status_code == 200
+        assert resp.headers["content-type"] == "image/png"
+
+        resp = client.get(
+            "/preview/1024x1024.png",
+            params={
+                "url": filename,
+                "variable": "dataset",
+                "rescale": "0,500",
+                "bidx": 1,
+            },
+        )
+        assert resp.status_code == 200
+        assert resp.headers["content-type"] == "image/png"
+        with MemoryFile(resp.content) as mem:
+            with mem.open() as dst:
+                assert dst.width == 1024
+                assert dst.height == 1024

src/titiler/xarray/titiler/xarray/dependencies.py

@@ -145,3 +145,37 @@ def __post_init__(self):
         """Post Init."""
         if self.width or self.height:
             self.max_size = None
+
+
+# Custom PreviewParams which add `resampling`
+@dataclass
+class PreviewParams(DefaultDependency):
+    """Common Preview parameters."""
+
+    max_size: Annotated[
+        Optional[int], Field(description="Maximum image size to read onto.")
+    ] = 1024
+    height: Annotated[
+        Optional[int], Field(description="Force output image height.")
+    ] = None
+    width: Annotated[Optional[int], Field(description="Force output image width.")] = (
+        None
+    )
+    resampling_method: Annotated[
+        Optional[RIOResampling],
+        Query(
+            alias="resampling",
+            description="RasterIO resampling algorithm. Defaults to `nearest`.",
+        ),
+    ] = None
+
+    def __post_init__(self):
+        """Post Init."""
+        if self.width or self.height:
+            self.max_size = None
+
+        # NOTE: By default we don't exclude None when we forward the parameter to the preview() method
+        # because we need to be able to pass max_size=None
+        # So we need to set the `resampling_method` to a default = 'nearest'
+        # https://github.com/developmentseed/titiler/blob/b8cc304382d0cb3b4f16cea9dbb0cfba35517085/src/titiler/core/titiler/core/factory.py#L1300
+        self.resampling_method = self.resampling_method or "nearest"

src/titiler/xarray/titiler/xarray/factory.py

@@ -1,10 +1,11 @@
 """TiTiler.xarray factory."""
 
 import logging
+import warnings
 from typing import Any, Callable, Optional, Type, Union
 
 import rasterio
-from attrs import define, field
+from attrs import define
 from fastapi import Body, Depends, Query
 from geojson_pydantic.features import Feature, FeatureCollection
 from rio_tiler.constants import WGS84_CRS
@@ -26,7 +27,12 @@
 from titiler.core.models.responses import InfoGeoJSON, StatisticsGeoJSON
 from titiler.core.resources.responses import GeoJSONResponse, JSONResponse
 from titiler.core.utils import bounds_to_geometry
-from titiler.xarray.dependencies import DatasetParams, PartFeatureParams, XarrayParams
+from titiler.xarray.dependencies import (
+    DatasetParams,
+    PartFeatureParams,
+    PreviewParams,
+    XarrayParams,
+)
 from titiler.xarray.io import Reader
 
 logger = logging.getLogger(__name__)
@@ -55,14 +61,25 @@ class TilerFactory(BaseTilerFactory):
     stats_dependency: Type[DefaultDependency] = StatisticsParams
     histogram_dependency: Type[DefaultDependency] = HistogramParams
 
+    img_preview_dependency: Type[DefaultDependency] = PreviewParams
     img_part_dependency: Type[DefaultDependency] = PartFeatureParams
 
     add_viewer: bool = True
     add_part: bool = True
 
-    # remove some attribute from init
-    img_preview_dependency: Type[DefaultDependency] = field(init=False)
-    add_preview: bool = field(init=False, default=False)
+    # /preview endpoints disabled by default
+    add_preview: bool = False
+
+    def __attrs_post_init__(self):
+        """Raise warning if preview is enabled."""
+        if self.add_preview:
+            warnings.warn(
+                "`preview` endpoints enabled Xarray based TilerFactory. MultiDim dataset might not be suitable for preview.",
+                UserWarning,
+                stacklevel=1,
+            )
+
+        super().__attrs_post_init__()
 
     # Custom /info endpoints (adds `show_times` options)
     def info(self):