titiler-xarray 0.19.0__tar.gz

titiler.xarray-0.19.0/PKG-INFO

@@ -0,0 +1,153 @@
+Metadata-Version: 2.1
+Name: titiler.xarray
+Version: 0.19.0
+Summary: Xarray plugin for TiTiler.
+License: MIT
+Keywords: TiTiler,Xarray,Zarr,NetCDF,HDF
+Author-email: Vincent Sarago <vincent@developmentseed.com>,Aimee Barciauskas <aimee@developmentseed.com>
+Requires-Python: >=3.8
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Information Technology
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Topic :: Scientific/Engineering :: GIS
+Provides-Extra: full
+Provides-Extra: gcs
+Provides-Extra: http
+Provides-Extra: minimal
+Provides-Extra: s3
+Provides-Extra: test
+Project-URL: Changelog, https://developmentseed.org/titiler/release-notes/
+Project-URL: Documentation, https://developmentseed.org/titiler/
+Project-URL: Homepage, https://developmentseed.org/titiler/
+Project-URL: Issues, https://github.com/developmentseed/titiler/issues
+Project-URL: Source, https://github.com/developmentseed/titiler
+Description-Content-Type: text/markdown
+
+## titiler.xarray
+
+Adds support for Xarray Dataset (NetCDF/Zarr) in Titiler.
+
+## Installation
+
+```bash
+python -m pip install -U pip
+
+# From Pypi
+python -m pip install "titiler.xarray[full]"
+
+# Or from sources
+git clone https://github.com/developmentseed/titiler.git
+cd titiler && python -m pip install -e src/titiler/core -e "src/titiler/xarray[full]"
+```
+
+#### Installation options
+
+Default installation for `titiler.xarray` DOES NOT include `fsspec` or any storage's specific dependencies (e.g `s3fs`) nor `engine` dependencies (`zarr`, `h5netcdf`). This is to ease the customization and deployment of user's applications. If you want to use the default's dataset reader you will need to at least use the `[minimal]` dependencies (e.g `python -m pip install "titiler.xarray[minimal]"`).
+
+Here is the list of available options:
+
+- **full**: `zarr`, `h5netcdf`,  `fsspec`, `s3fs`, `aiohttp`, `gcsfs`
+- **minimal**: `zarr`, `h5netcdf`,  `fsspec`
+- **gcs**: `gcsfs`
+- **s3**: `s3fs`
+- **http**: `aiohttp`
+
+## How To
+
+```python
+from fastapi import FastAPI
+
+from titiler.xarray.extensions import VariablesExtension
+from titiler.xarray.factory import TilerFactory
+
+app = FastAPI(
+    openapi_url="/api",
+    docs_url="/api.html",
+    description="""Xarray based tiles server for MultiDimensional dataset (Zarr/NetCDF).
+
+---
+
+**Documentation**: <a href="https://developmentseed.org/titiler/" target="_blank">https://developmentseed.org/titiler/</a>
+
+**Source Code**: <a href="https://github.com/developmentseed/titiler" target="_blank">https://github.com/developmentseed/titiler</a>
+
+---
+    """,
+)
+
+md = TilerFactory(
+    router_prefix="/md",
+    extensions=[
+        VariablesExtension(),
+    ],
+)
+app.include_router(md.router, prefix="/md", tags=["Multi Dimensional"])
+```
+
+## Package structure
+
+```
+titiler/
+ └── xarray/
+    ├── tests/                   - Tests suite
+    └── titiler/xarray/          - `xarray` namespace package
+        ├── dependencies.py      - titiler-xarray dependencies
+        ├── extentions.py        - titiler-xarray extensions
+        ├── io.py                - titiler-xarray Readers
+        └── factory.py           - endpoints factory
+```
+
+## Custom Dataset Opener
+
+A default Dataset IO is provided within `titiler.xarray.Reader` class but will require optional dependencies (`fsspec`, `zarr`, `h5netcdf`, ...) to be installed with `python -m pip install "titiler.xarray[full]"`.
+Dependencies are optional so the entire package size can be optimized to only include dependencies required by a given application.
+
+Example:
+
+**requirements**:
+- `titiler.xarray` (base)
+- `h5netcdf`
+
+
+```python
+from typing import Callable
+import attr
+from fastapi import FastAPI
+from titiler.xarray.io import Reader
+from titiler.xarray.extensions import VariablesExtension
+from titiler.xarray.factory import TilerFactory
+
+import xarray
+import h5netcdf  # noqa
+
+# Create a simple Custom reader, using `xarray.open_dataset` opener
+@attr.s
+class CustomReader(Reader):
+    """Custom io.Reader using xarray.open_dataset opener."""
+    # xarray.Dataset options
+    opener: Callable[..., xarray.Dataset] = attr.ib(default=xarray.open_dataset)
+
+
+# Create FastAPI application
+app = FastAPI(openapi_url="/api", docs_url="/api.html")
+
+# Create custom endpoints with the CustomReader
+md = TilerFactory(
+    reader=CustomReader,
+    router_prefix="/md",
+    extensions=[
+        # we also want to use the simple opener for the Extension
+        VariablesExtension(dataset_opener==xarray.open_dataset),
+    ],
+)
+
+app.include_router(md.router, prefix="/md", tags=["Multi Dimensional"])
+```
+

titiler.xarray-0.19.0/README.md

@@ -0,0 +1,120 @@
+## titiler.xarray
+
+Adds support for Xarray Dataset (NetCDF/Zarr) in Titiler.
+
+## Installation
+
+```bash
+python -m pip install -U pip
+
+# From Pypi
+python -m pip install "titiler.xarray[full]"
+
+# Or from sources
+git clone https://github.com/developmentseed/titiler.git
+cd titiler && python -m pip install -e src/titiler/core -e "src/titiler/xarray[full]"
+```
+
+#### Installation options
+
+Default installation for `titiler.xarray` DOES NOT include `fsspec` or any storage's specific dependencies (e.g `s3fs`) nor `engine` dependencies (`zarr`, `h5netcdf`). This is to ease the customization and deployment of user's applications. If you want to use the default's dataset reader you will need to at least use the `[minimal]` dependencies (e.g `python -m pip install "titiler.xarray[minimal]"`).
+
+Here is the list of available options:
+
+- **full**: `zarr`, `h5netcdf`,  `fsspec`, `s3fs`, `aiohttp`, `gcsfs`
+- **minimal**: `zarr`, `h5netcdf`,  `fsspec`
+- **gcs**: `gcsfs`
+- **s3**: `s3fs`
+- **http**: `aiohttp`
+
+## How To
+
+```python
+from fastapi import FastAPI
+
+from titiler.xarray.extensions import VariablesExtension
+from titiler.xarray.factory import TilerFactory
+
+app = FastAPI(
+    openapi_url="/api",
+    docs_url="/api.html",
+    description="""Xarray based tiles server for MultiDimensional dataset (Zarr/NetCDF).
+
+---
+
+**Documentation**: <a href="https://developmentseed.org/titiler/" target="_blank">https://developmentseed.org/titiler/</a>
+
+**Source Code**: <a href="https://github.com/developmentseed/titiler" target="_blank">https://github.com/developmentseed/titiler</a>
+
+---
+    """,
+)
+
+md = TilerFactory(
+    router_prefix="/md",
+    extensions=[
+        VariablesExtension(),
+    ],
+)
+app.include_router(md.router, prefix="/md", tags=["Multi Dimensional"])
+```
+
+## Package structure
+
+```
+titiler/
+ └── xarray/
+    ├── tests/                   - Tests suite
+    └── titiler/xarray/          - `xarray` namespace package
+        ├── dependencies.py      - titiler-xarray dependencies
+        ├── extentions.py        - titiler-xarray extensions
+        ├── io.py                - titiler-xarray Readers
+        └── factory.py           - endpoints factory
+```
+
+## Custom Dataset Opener
+
+A default Dataset IO is provided within `titiler.xarray.Reader` class but will require optional dependencies (`fsspec`, `zarr`, `h5netcdf`, ...) to be installed with `python -m pip install "titiler.xarray[full]"`.
+Dependencies are optional so the entire package size can be optimized to only include dependencies required by a given application.
+
+Example:
+
+**requirements**:
+- `titiler.xarray` (base)
+- `h5netcdf`
+
+
+```python
+from typing import Callable
+import attr
+from fastapi import FastAPI
+from titiler.xarray.io import Reader
+from titiler.xarray.extensions import VariablesExtension
+from titiler.xarray.factory import TilerFactory
+
+import xarray
+import h5netcdf  # noqa
+
+# Create a simple Custom reader, using `xarray.open_dataset` opener
+@attr.s
+class CustomReader(Reader):
+    """Custom io.Reader using xarray.open_dataset opener."""
+    # xarray.Dataset options
+    opener: Callable[..., xarray.Dataset] = attr.ib(default=xarray.open_dataset)
+
+
+# Create FastAPI application
+app = FastAPI(openapi_url="/api", docs_url="/api.html")
+
+# Create custom endpoints with the CustomReader
+md = TilerFactory(
+    reader=CustomReader,
+    router_prefix="/md",
+    extensions=[
+        # we also want to use the simple opener for the Extension
+        VariablesExtension(dataset_opener==xarray.open_dataset),
+    ],
+)
+
+app.include_router(md.router, prefix="/md", tags=["Multi Dimensional"])
+```

titiler.xarray-0.19.0/pyproject.toml

@@ -0,0 +1,100 @@
+[project]
+name = "titiler.xarray"
+description = "Xarray plugin for TiTiler."
+readme = "README.md"
+requires-python = ">=3.8"
+authors = [
+    { name = "Vincent Sarago", email = "vincent@developmentseed.com" },
+    { name = "Aimee Barciauskas", email = "aimee@developmentseed.com" },
+]
+keywords = [
+    "TiTiler",
+    "Xarray",
+    "Zarr",
+    "NetCDF",
+    "HDF",
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Information Technology",
+    "Intended Audience :: Science/Research",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.8",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Scientific/Engineering :: GIS",
+]
+dynamic = []
+dependencies = [
+    "titiler.core==0.19.0",
+    "rio-tiler>=7.2,<8.0",
+    "xarray",
+    "rioxarray",
+]
+version = "0.19.0"
+
+[project.license]
+text = "MIT"
+
+[project.optional-dependencies]
+full = [
+    "zarr",
+    "h5netcdf",
+    "fsspec",
+    "s3fs",
+    "aiohttp",
+    "gcsfs",
+]
+minimal = [
+    "zarr",
+    "h5netcdf",
+    "fsspec",
+]
+gcs = [
+    "gcsfs",
+]
+s3 = [
+    "s3fs",
+]
+http = [
+    "aiohttp",
+]
+test = [
+    "pytest",
+    "pytest-cov",
+    "pytest-asyncio",
+    "httpx",
+    "zarr",
+    "h5netcdf",
+    "fsspec",
+]
+
+[project.urls]
+Homepage = "https://developmentseed.org/titiler/"
+Documentation = "https://developmentseed.org/titiler/"
+Issues = "https://github.com/developmentseed/titiler/issues"
+Source = "https://github.com/developmentseed/titiler"
+Changelog = "https://developmentseed.org/titiler/release-notes/"
+
+[build-system]
+requires = [
+    "pdm-pep517",
+]
+build-backend = "pdm.pep517.api"
+
+[tool.pdm.version]
+source = "file"
+path = "titiler/xarray/__init__.py"
+
+[tool.pdm.build]
+includes = [
+    "titiler/xarray",
+]
+excludes = [
+    "tests/",
+    "**/.mypy_cache",
+    "**/.DS_Store",
+]

titiler.xarray-0.19.0/titiler/xarray/__init__.py

@@ -0,0 +1,3 @@
+"""titiler.xarray"""
+
+__version__ = "0.19.0"

titiler.xarray-0.19.0/titiler/xarray/dependencies.py

@@ -0,0 +1,124 @@
+"""titiler.xarray dependencies."""
+
+from dataclasses import dataclass
+from typing import Optional, Union
+
+import numpy
+from fastapi import Query
+from rio_tiler.types import RIOResampling, WarpResampling
+from typing_extensions import Annotated
+
+from titiler.core.dependencies import DefaultDependency
+
+
+@dataclass
+class XarrayIOParams(DefaultDependency):
+    """Dataset IO Options."""
+
+    group: Annotated[
+        Optional[str],
+        Query(
+            description="Select a specific zarr group from a zarr hierarchy. Could be associated with a zoom level or dataset."
+        ),
+    ] = None
+
+    decode_times: Annotated[
+        Optional[bool],
+        Query(
+            title="decode_times",
+            description="Whether to decode times",
+        ),
+    ] = None
+
+    # cache_client
+
+
+@dataclass
+class XarrayDsParams(DefaultDependency):
+    """Xarray Dataset Options."""
+
+    variable: Annotated[str, Query(description="Xarray Variable name")]
+
+    drop_dim: Annotated[
+        Optional[str],
+        Query(description="Dimension to drop"),
+    ] = None
+
+    datetime: Annotated[
+        Optional[str], Query(description="Slice of time to read (if available)")
+    ] = None
+
+
+@dataclass
+class XarrayParams(XarrayIOParams, XarrayDsParams):
+    """Xarray Reader dependency."""
+
+    pass
+
+
+@dataclass
+class CompatXarrayParams(XarrayIOParams):
+    """Custom XarrayParams endpoints.
+
+    This Dependency aims to be used in a tiler where both GDAL/Xarray dataset would be supported.
+    By default `variable` won't be required but when using an Xarray dataset,
+    it would fail without the variable query-parameter set.
+    """
+
+    variable: Annotated[Optional[str], Query(description="Xarray Variable name")] = None
+
+    drop_dim: Annotated[
+        Optional[str],
+        Query(description="Dimension to drop"),
+    ] = None
+
+    datetime: Annotated[
+        Optional[str], Query(description="Slice of time to read (if available)")
+    ] = None
+
+
+@dataclass
+class DatasetParams(DefaultDependency):
+    """Low level WarpedVRT Optional parameters."""
+
+    nodata: Annotated[
+        Optional[Union[str, int, float]],
+        Query(
+            title="Nodata value",
+            description="Overwrite internal Nodata value",
+        ),
+    ] = None
+    reproject_method: Annotated[
+        Optional[WarpResampling],
+        Query(
+            alias="reproject",
+            description="WarpKernel resampling algorithm (only used when doing re-projection). Defaults to `nearest`.",
+        ),
+    ] = None
+
+    def __post_init__(self):
+        """Post Init."""
+        if self.nodata is not None:
+            self.nodata = numpy.nan if self.nodata == "nan" else float(self.nodata)
+
+
+# Custom PartFeatureParams which add `resampling`
+@dataclass
+class PartFeatureParams(DefaultDependency):
+    """Common parameters for bbox and feature."""
+
+    max_size: Annotated[Optional[int], "Maximum image size to read onto."] = None
+    height: Annotated[Optional[int], "Force output image height."] = None
+    width: Annotated[Optional[int], "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 and self.height:
+            self.max_size = None

titiler.xarray-0.19.0/titiler/xarray/extensions.py

@@ -0,0 +1,38 @@
+"""titiler.xarray Extensions."""
+
+from typing import Callable, List, Type
+
+import xarray
+from attrs import define
+from fastapi import Depends
+
+from titiler.core.dependencies import DefaultDependency
+from titiler.core.factory import FactoryExtension
+from titiler.xarray.dependencies import XarrayIOParams
+from titiler.xarray.factory import TilerFactory
+from titiler.xarray.io import xarray_open_dataset
+
+
+@define
+class VariablesExtension(FactoryExtension):
+    """Add /variables endpoint to a Xarray TilerFactory."""
+
+    # Custom dependency for /variables
+    io_dependency: Type[DefaultDependency] = XarrayIOParams
+    dataset_opener: Callable[..., xarray.Dataset] = xarray_open_dataset
+
+    def register(self, factory: TilerFactory):
+        """Register endpoint to the tiler factory."""
+
+        @factory.router.get(
+            "/variables",
+            response_model=List[str],
+            responses={200: {"description": "Return Xarray Dataset variables."}},
+        )
+        def variables(
+            src_path=Depends(factory.path_dependency),
+            io_params=Depends(self.io_dependency),
+        ):
+            """return available variables."""
+            with self.dataset_opener(src_path, **io_params.as_dict()) as ds:
+                return list(ds.data_vars)  # type: ignore

titiler.xarray-0.19.0/titiler/xarray/factory.py

@@ -0,0 +1,212 @@
+"""TiTiler.xarray factory."""
+
+from typing import Callable, Optional, Type, Union
+
+import rasterio
+from attrs import define, field
+from fastapi import Body, Depends, Query
+from geojson_pydantic.features import Feature, FeatureCollection
+from geojson_pydantic.geometries import MultiPolygon, Polygon
+from rio_tiler.constants import WGS84_CRS
+from rio_tiler.models import Info
+from typing_extensions import Annotated
+
+from titiler.core.dependencies import (
+    CoordCRSParams,
+    CRSParams,
+    DatasetPathParams,
+    DefaultDependency,
+    DstCRSParams,
+    HistogramParams,
+    StatisticsParams,
+)
+from titiler.core.factory import TilerFactory as BaseTilerFactory
+from titiler.core.models.responses import InfoGeoJSON, StatisticsGeoJSON
+from titiler.core.resources.responses import GeoJSONResponse, JSONResponse
+from titiler.xarray.dependencies import DatasetParams, PartFeatureParams, XarrayParams
+from titiler.xarray.io import Reader
+
+
+@define(kw_only=True)
+class TilerFactory(BaseTilerFactory):
+    """Xarray Tiler Factory."""
+
+    reader: Type[Reader] = Reader
+
+    path_dependency: Callable[..., str] = DatasetPathParams
+
+    reader_dependency: Type[DefaultDependency] = XarrayParams
+
+    # Indexes/Expression Dependencies (Not layer dependencies for Xarray)
+    layer_dependency: Type[DefaultDependency] = DefaultDependency
+
+    # Dataset Options (nodata, reproject)
+    dataset_dependency: Type[DefaultDependency] = DatasetParams
+
+    # Tile/Tilejson/WMTS Dependencies  (Not used in titiler.xarray)
+    tile_dependency: Type[DefaultDependency] = DefaultDependency
+
+    # Statistics/Histogram Dependencies
+    stats_dependency: Type[DefaultDependency] = StatisticsParams
+    histogram_dependency: Type[DefaultDependency] = HistogramParams
+
+    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)
+
+    # Custom /info endpoints (adds `show_times` options)
+    def info(self):
+        """Register /info endpoint."""
+
+        @self.router.get(
+            "/info",
+            response_model=Info,
+            response_model_exclude_none=True,
+            response_class=JSONResponse,
+            responses={200: {"description": "Return dataset's basic info."}},
+        )
+        def info_endpoint(
+            src_path=Depends(self.path_dependency),
+            reader_params=Depends(self.reader_dependency),
+            show_times: Annotated[
+                Optional[bool],
+                Query(description="Show info about the time dimension"),
+            ] = None,
+            env=Depends(self.environment_dependency),
+        ) -> Info:
+            """Return dataset's basic info."""
+            with rasterio.Env(**env):
+                with self.reader(src_path, **reader_params.as_dict()) as src_dst:
+                    info = src_dst.info().model_dump()
+                    if show_times and "time" in src_dst.input.dims:
+                        times = [str(x.data) for x in src_dst.input.time]
+                        info["count"] = len(times)
+                        info["times"] = times
+
+            return Info(**info)
+
+        @self.router.get(
+            "/info.geojson",
+            response_model=InfoGeoJSON,
+            response_model_exclude_none=True,
+            response_class=GeoJSONResponse,
+            responses={
+                200: {
+                    "content": {"application/geo+json": {}},
+                    "description": "Return dataset's basic info as a GeoJSON feature.",
+                }
+            },
+        )
+        def info_geojson(
+            src_path=Depends(self.path_dependency),
+            reader_params=Depends(self.reader_dependency),
+            show_times: Annotated[
+                Optional[bool],
+                Query(description="Show info about the time dimension"),
+            ] = None,
+            crs=Depends(CRSParams),
+            env=Depends(self.environment_dependency),
+        ):
+            """Return dataset's basic info as a GeoJSON feature."""
+            with rasterio.Env(**env):
+                with self.reader(src_path, **reader_params.as_dict()) as src_dst:
+                    bounds = src_dst.get_geographic_bounds(crs or WGS84_CRS)
+                    if bounds[0] > bounds[2]:
+                        pl = Polygon.from_bounds(-180, bounds[1], bounds[2], bounds[3])
+                        pr = Polygon.from_bounds(bounds[0], bounds[1], 180, bounds[3])
+                        geometry = MultiPolygon(
+                            type="MultiPolygon",
+                            coordinates=[pl.coordinates, pr.coordinates],
+                        )
+                    else:
+                        geometry = Polygon.from_bounds(*bounds)
+
+                    info = src_dst.info().model_dump()
+                    if show_times and "time" in src_dst.input.dims:
+                        times = [str(x.data) for x in src_dst.input.time]
+                        info["count"] = len(times)
+                        info["times"] = times
+
+            return Feature(
+                type="Feature",
+                bbox=bounds,
+                geometry=geometry,
+                properties=info,
+            )
+
+    # custom /statistics endpoints (remove /statistics - GET)
+    def statistics(self):
+        """add statistics endpoints."""
+
+        # POST endpoint
+        @self.router.post(
+            "/statistics",
+            response_model=StatisticsGeoJSON,
+            response_model_exclude_none=True,
+            response_class=GeoJSONResponse,
+            responses={
+                200: {
+                    "content": {"application/geo+json": {}},
+                    "description": "Return dataset's statistics from feature or featureCollection.",
+                }
+            },
+        )
+        def geojson_statistics(
+            geojson: Annotated[
+                Union[FeatureCollection, Feature],
+                Body(description="GeoJSON Feature or FeatureCollection."),
+            ],
+            src_path=Depends(self.path_dependency),
+            reader_params=Depends(self.reader_dependency),
+            coord_crs=Depends(CoordCRSParams),
+            dst_crs=Depends(DstCRSParams),
+            layer_params=Depends(self.layer_dependency),
+            dataset_params=Depends(self.dataset_dependency),
+            image_params=Depends(self.img_part_dependency),
+            post_process=Depends(self.process_dependency),
+            stats_params=Depends(self.stats_dependency),
+            histogram_params=Depends(self.histogram_dependency),
+            env=Depends(self.environment_dependency),
+        ):
+            """Get Statistics from a geojson feature or featureCollection."""
+            fc = geojson
+            if isinstance(fc, Feature):
+                fc = FeatureCollection(type="FeatureCollection", features=[geojson])
+
+            with rasterio.Env(**env):
+                with self.reader(src_path, **reader_params.as_dict()) as src_dst:
+                    for feature in fc:
+                        shape = feature.model_dump(exclude_none=True)
+                        image = src_dst.feature(
+                            shape,
+                            shape_crs=coord_crs or WGS84_CRS,
+                            dst_crs=dst_crs,
+                            **layer_params.as_dict(),
+                            **image_params.as_dict(),
+                            **dataset_params.as_dict(),
+                        )
+
+                        # Get the coverage % array
+                        coverage_array = image.get_coverage_array(
+                            shape,
+                            shape_crs=coord_crs or WGS84_CRS,
+                        )
+
+                        if post_process:
+                            image = post_process(image)
+
+                        stats = image.statistics(
+                            **stats_params.as_dict(),
+                            hist_options=histogram_params.as_dict(),
+                            coverage=coverage_array,
+                        )
+
+                        feature.properties = feature.properties or {}
+                        feature.properties.update({"statistics": stats})
+
+            return fc.features[0] if isinstance(geojson, Feature) else fc

titiler.xarray-0.19.0/titiler/xarray/io.py

@@ -0,0 +1,293 @@
+"""titiler.xarray.io"""
+
+from typing import Any, Callable, Dict, List, Optional
+from urllib.parse import urlparse
+
+import attr
+import numpy
+import xarray
+from morecantile import TileMatrixSet
+from rio_tiler.constants import WEB_MERCATOR_TMS
+from rio_tiler.io.xarray import XarrayReader
+
+
+def xarray_open_dataset(  # noqa: C901
+    src_path: str,
+    group: Optional[str] = None,
+    decode_times: bool = True,
+) -> xarray.Dataset:
+    """Open Xarray dataset with fsspec.
+
+    Args:
+        src_path (str): dataset path.
+        group (Optional, str): path to the netCDF/Zarr group in the given file to open given as a str.
+        decode_times (bool):  If True, decode times encoded in the standard NetCDF datetime format into datetime objects. Otherwise, leave them encoded as numbers.
+
+    Returns:
+        xarray.Dataset
+
+    """
+    import fsspec  # noqa
+
+    try:
+        import gcsfs
+    except ImportError:  # pragma: nocover
+        gcsfs = None  # type: ignore
+
+    try:
+        import s3fs
+    except ImportError:  # pragma: nocover
+        s3fs = None  # type: ignore
+
+    try:
+        import aiohttp
+    except ImportError:  # pragma: nocover
+        aiohttp = None  # type: ignore
+
+    try:
+        import h5netcdf
+    except ImportError:  # pragma: nocover
+        h5netcdf = None  # type: ignore
+
+    try:
+        import zarr
+    except ImportError:  # pragma: nocover
+        zarr = None  # type: ignore
+
+    parsed = urlparse(src_path)
+    protocol = parsed.scheme or "file"
+
+    if any(src_path.lower().endswith(ext) for ext in [".nc", ".nc4"]):
+        assert (
+            h5netcdf is not None
+        ), "'h5netcdf' must be installed to read NetCDF dataset"
+
+        xr_engine = "h5netcdf"
+
+    else:
+        assert zarr is not None, "'zarr' must be installed to read Zarr dataset"
+
+        xr_engine = "zarr"
+
+    if protocol in ["", "file"]:
+        filesystem = fsspec.filesystem(protocol)  # type: ignore
+        file_handler = (
+            filesystem.open(src_path)
+            if xr_engine == "h5netcdf"
+            else filesystem.get_mapper(src_path)
+        )
+
+    elif protocol == "s3":
+        assert (
+            s3fs is not None
+        ), "'aiohttp' must be installed to read dataset stored online"
+
+        s3_filesystem = s3fs.S3FileSystem()
+        file_handler = (
+            s3_filesystem.open(src_path)
+            if xr_engine == "h5netcdf"
+            else s3fs.S3Map(root=src_path, s3=s3_filesystem)
+        )
+
+    elif protocol == "gs":
+        assert (
+            gcsfs is not None
+        ), "'gcsfs' must be installed to read dataset stored in Google Cloud Storage"
+
+        gcs_filesystem = gcsfs.GCSFileSystem()
+        file_handler = (
+            gcs_filesystem.open(src_path)
+            if xr_engine == "h5netcdf"
+            else gcs_filesystem.get_mapper(root=src_path)
+        )
+
+    elif protocol in ["http", "https"]:
+        assert (
+            aiohttp is not None
+        ), "'aiohttp' must be installed to read dataset stored online"
+
+        filesystem = fsspec.filesystem(protocol)  # type: ignore
+        file_handler = (
+            filesystem.open(src_path)
+            if xr_engine == "h5netcdf"
+            else filesystem.get_mapper(src_path)
+        )
+
+    else:
+        raise ValueError(f"Unsupported protocol: {protocol}, for {src_path}")
+
+    # Arguments for xarray.open_dataset
+    # Default args
+    xr_open_args: Dict[str, Any] = {
+        "decode_coords": "all",
+        "decode_times": decode_times,
+    }
+
+    # Argument if we're opening a datatree
+    if group is not None:
+        xr_open_args["group"] = group
+
+    # NetCDF arguments
+    if xr_engine == "h5netcdf":
+        xr_open_args.update(
+            {
+                "engine": "h5netcdf",
+                "lock": False,
+            }
+        )
+
+        ds = xarray.open_dataset(file_handler, **xr_open_args)
+
+    # Fallback to Zarr
+    else:
+        ds = xarray.open_zarr(file_handler, **xr_open_args)
+
+    return ds
+
+
+def _arrange_dims(da: xarray.DataArray) -> xarray.DataArray:
+    """Arrange coordinates and time dimensions.
+
+    An rioxarray.exceptions.InvalidDimensionOrder error is raised if the coordinates are not in the correct order time, y, and x.
+    See: https://github.com/corteva/rioxarray/discussions/674
+
+    We conform to using x and y as the spatial dimension names..
+
+    """
+    if "x" not in da.dims and "y" not in da.dims:
+        try:
+            latitude_var_name = next(
+                name
+                for name in ["lat", "latitude", "LAT", "LATITUDE", "Lat"]
+                if name in da.dims
+            )
+            longitude_var_name = next(
+                name
+                for name in ["lon", "longitude", "LON", "LONGITUDE", "Lon"]
+                if name in da.dims
+            )
+        except StopIteration as e:
+            raise ValueError(f"Couldn't find X/Y dimensions in {da.dims}") from e
+
+        da = da.rename({latitude_var_name: "y", longitude_var_name: "x"})
+
+    if "TIME" in da.dims:
+        da = da.rename({"TIME": "time"})
+
+    if extra_dims := [d for d in da.dims if d not in ["x", "y"]]:
+        da = da.transpose(*extra_dims, "y", "x")
+    else:
+        da = da.transpose("y", "x")
+
+    # If min/max values are stored in `valid_range` we add them in `valid_min/valid_max`
+    vmin, vmax = da.attrs.get("valid_min"), da.attrs.get("valid_max")
+    if "valid_range" in da.attrs and not (vmin is not None and vmax is not None):
+        valid_range = da.attrs.get("valid_range")
+        da.attrs.update({"valid_min": valid_range[0], "valid_max": valid_range[1]})
+
+    return da
+
+
+def get_variable(
+    ds: xarray.Dataset,
+    variable: str,
+    datetime: Optional[str] = None,
+    drop_dim: Optional[str] = None,
+) -> xarray.DataArray:
+    """Get Xarray variable as DataArray.
+
+    Args:
+        ds (xarray.Dataset): Xarray Dataset.
+        variable (str): Variable to extract from the Dataset.
+        datetime (str, optional): datetime to select from the DataArray.
+        drop_dim (str, optional): DataArray dimension to drop in form of `{dimension}={value}`.
+
+    Returns:
+        xarray.DataArray: 2D or 3D DataArray.
+
+    """
+    da = ds[variable]
+
+    if drop_dim:
+        dim_to_drop, dim_val = drop_dim.split("=")
+        da = da.sel({dim_to_drop: dim_val}).drop_vars(dim_to_drop)
+
+    da = _arrange_dims(da)
+
+    # Make sure we have a valid CRS
+    crs = da.rio.crs or "epsg:4326"
+    da = da.rio.write_crs(crs)
+
+    if crs == "epsg:4326" and (da.x > 180).any():
+        # Adjust the longitude coordinates to the -180 to 180 range
+        da = da.assign_coords(x=(da.x + 180) % 360 - 180)
+
+        # Sort the dataset by the updated longitude coordinates
+        da = da.sortby(da.x)
+
+    # TODO: Technically we don't have to select the first time, rio-tiler should handle 3D dataset
+    if "time" in da.dims:
+        if datetime:
+            # TODO: handle time interval
+            time_as_str = datetime.split("T")[0]
+            if da["time"].dtype == "O":
+                da["time"] = da["time"].astype("datetime64[ns]")
+
+            da = da.sel(
+                time=numpy.array(time_as_str, dtype=numpy.datetime64), method="nearest"
+            )
+        else:
+            da = da.isel(time=0)
+
+    assert len(da.dims) in [2, 3], "titiler.xarray can only work with 2D or 3D dataset"
+
+    return da
+
+
+@attr.s
+class Reader(XarrayReader):
+    """Reader: Open Zarr file and access DataArray."""
+
+    src_path: str = attr.ib()
+    variable: str = attr.ib()
+
+    # xarray.Dataset options
+    opener: Callable[..., xarray.Dataset] = attr.ib(default=xarray_open_dataset)
+
+    group: Optional[str] = attr.ib(default=None)
+    decode_times: bool = attr.ib(default=True)
+
+    # xarray.DataArray options
+    datetime: Optional[str] = attr.ib(default=None)
+    drop_dim: Optional[str] = attr.ib(default=None)
+
+    tms: TileMatrixSet = attr.ib(default=WEB_MERCATOR_TMS)
+
+    ds: xarray.Dataset = attr.ib(init=False)
+    input: xarray.DataArray = attr.ib(init=False)
+
+    _dims: List = attr.ib(init=False, factory=list)
+
+    def __attrs_post_init__(self):
+        """Set bounds and CRS."""
+        self.ds = self.opener(
+            self.src_path,
+            group=self.group,
+            decode_times=self.decode_times,
+        )
+
+        self.input = get_variable(
+            self.ds,
+            self.variable,
+            datetime=self.datetime,
+            drop_dim=self.drop_dim,
+        )
+        super().__attrs_post_init__()
+
+    def close(self):
+        """Close xarray dataset."""
+        self.ds.close()
+
+    def __exit__(self, exc_type, exc_value, traceback):
+        """Support using with Context Managers."""
+        self.close()