Add Xarray sub-package

.github/workflows/ci.yml

@@ -49,6 +49,11 @@ jobs:
           python -m pip install -e src/titiler/extensions["test,cogeo,stac"]
           python -m pytest src/titiler/extensions --cov=titiler.extensions --cov-report=xml --cov-append --cov-report=term-missing
 
+      - name: Test titiler.xarray
+        run: |
+          python -m pip install -e src/titiler/xarray["test"]
+          python -m pytest src/titiler/xarray --cov=titiler.xarray --cov-report=xml --cov-append --cov-report=term-missing
+
       - name: Test titiler.mosaic
         run: |
           python -m pip install -e src/titiler/mosaic["test"]

.github/workflows/deploy_mkdocs.yml

@@ -29,7 +29,7 @@ jobs:
       - name: Install dependencies
         run: |
           python -m pip install --upgrade pip
-          python -m pip install src/titiler/core src/titiler/extensions["cogeo,stac"] src/titiler/mosaic src/titiler/application
+          python -m pip install src/titiler/core src/titiler/extensions["cogeo,stac"] src/titiler/xarray src/titiler/mosaic src/titiler/application
           python -m pip install -r requirements/requirements-docs.txt
 
 

README.md

@@ -55,6 +55,7 @@ Starting with version `0.3.0`, the `TiTiler` python module has been split into a
 | Package | Version |  Description
 | ------- | ------- |-------------
 [**titiler.core**](https://github.com/developmentseed/titiler/tree/main/src/titiler/core) | [![titiler.core](https://img.shields.io/pypi/v/titiler.core?color=%2334D058&label=pypi)](https://pypi.org/project/titiler.core) | The `Core` package contains libraries to help create a  dynamic tiler for COG and STAC
+[**titiler.xarray**](https://github.com/developmentseed/titiler/tree/main/src/titiler/xarray) | [![titiler.xarray](https://img.shields.io/pypi/v/titiler.xarray?color=%2334D058&label=pypi)](https://pypi.org/project/titiler.xarray) | The `xarray` package contains libraries to help create a  dynamic tiler for Zarr/NetCDF datasets
 [**titiler.extensions**](https://github.com/developmentseed/titiler/tree/main/src/titiler/extensions) | [![titiler.extensions](https://img.shields.io/pypi/v/titiler.extensions?color=%2334D058&label=pypi)](https://pypi.org/project/titiler.extensions) | TiTiler's extensions package. Contains extensions for Tiler Factories.
 [**titiler.mosaic**](https://github.com/developmentseed/titiler/tree/main/src/titiler/mosaic) | [![titiler.mosaic](https://img.shields.io/pypi/v/titiler.mosaic?color=%2334D058&label=pypi)](https://pypi.org/project/titiler.mosaic) | The `mosaic` package contains libraries to help create a dynamic tiler for MosaicJSON (adds `cogeo-mosaic` requirement)
 [**titiler.application**](https://github.com/developmentseed/titiler/tree/main/src/titiler/application) | [![titiler.application](https://img.shields.io/pypi/v/titiler.application?color=%2334D058&label=pypi)](https://pypi.org/project/titiler.application) | TiTiler's `demo` package. Contains a FastAPI application with full support of COG, STAC and MosaicJSON
@@ -71,6 +72,7 @@ python -m pip install -U pip
 python -m pip  install titiler.{package}
 # e.g.,
 # python -m pip  install titiler.core
+# python -m pip  install titiler.xarray
 # python -m pip  install titiler.extensions
 # python -m pip  install titiler.mosaic
 # python -m pip  install titiler.application (also installs core, extensions and mosaic)
@@ -89,7 +91,7 @@ git clone https://github.com/developmentseed/titiler.git
 cd titiler
 
 python -m pip install -U pip
-python -m pip install -e src/titiler/core -e src/titiler/extensions -e src/titiler/mosaic -e src/titiler/application
+python -m pip install -e src/titiler/core -e src/titiler/xarray -e src/titiler/extensions -e src/titiler/mosaic -e src/titiler/application
 python -m pip install uvicorn
 
 uvicorn titiler.application.main:app --reload
@@ -125,6 +127,7 @@ Some options can be set via environment variables, see: https://github.com/tiang
 src/titiler/                     - titiler modules.
  ├── application/                - Titiler's `Application` package
  ├── extensions/                 - Titiler's `Extensions` package
+ ├── xarray/                     - Titiler's `Xarray` package
  ├── core/                       - Titiler's `Core` package
  └── mosaic/                     - Titiler's `Mosaic` package
 ```

scripts/publish

@@ -2,6 +2,7 @@
 
 SUBPACKAGE_DIRS=(
     "core"
+    "xarray"
     "mosaic"
     "application"
     "extensions"

src/titiler/core/titiler/core/factory.py

@@ -1049,7 +1049,7 @@ def bbox_image(
         ):
             """Create image from a bbox."""
             with rasterio.Env(**env):
-                with self.reader(src_path, **reader_params) as src_dst:
+                with self.reader(src_path, **reader_params.as_dict()) as src_dst:
                     image = src_dst.part(
                         [minx, miny, maxx, maxy],
                         dst_crs=dst_crs,

src/titiler/xarray/README.md

@@ -0,0 +1,46 @@
+## 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
+
+# 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
+```
+
+## How To
+
+```python
+from fastapi import FastAPI
+from titiler.xarray.factory import TilerFactory
+
+# Create a FastAPI application
+app = FastAPI(
+    description="A lightweight Cloud Optimized GeoTIFF tile server",
+)
+
+# Create a set of MosaicJSON endpoints
+endpoint = TilerFactory()
+
+# Register the Mosaic endpoints to the application
+app.include_router(endpoint.router)
+```
+
+## Package structure
+
+```
+titiler/
+ └── xarray/
+    ├── tests/                   - Tests suite
+    └── titiler/xarray/          - `xarray` namespace package
+        ├── dependencies.py      - titiler-xarray dependencies
+        ├── io.py                - titiler-xarray Readers
+        └── factory.py           - endpoints factory
+```

src/titiler/xarray/pyproject.toml

@@ -0,0 +1,70 @@
+[project]
+name = "titiler.xarray"
+description = "Xarray plugin for TiTiler."
+readme = "README.md"
+requires-python = ">=3.8"
+authors = [
+    {name = "Vincent Sarago", email = "[email protected]"},
+    {name = "Aimee Barciauskas", email = "[email protected]"},
+]
+license = {text = "MIT"}
+keywords = [
+    "TiTiler",
+    "Xarray",
+    "Zarr",
+    "NetCDF",
+    "HDF",
+]
+classifiers = [
+    "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 = ["version"]
+dependencies = [
+    "titiler.core==0.19.0.dev",
+    "cftime",
+    "h5netcdf",
+    "xarray",
+    "rioxarray",
+    "zarr",
+    "fsspec",
+    "s3fs",
+    "aiohttp",
+    "pandas",
+    "httpx",
+]
+
+[project.optional-dependencies]
+test = [
+    "pytest",
+    "pytest-cov",
+    "pytest-asyncio",
+    "httpx",
+]
+
+[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"]

src/titiler/xarray/tests/conftest.py

@@ -0,0 +1 @@
+"""titiler.xarray test configuration."""

src/titiler/xarray/tests/fixtures/dataset_3d.zarr/.zattrs

@@ -0,0 +1 @@
+{}

src/titiler/xarray/tests/fixtures/dataset_3d.zarr/.zgroup

@@ -0,0 +1,3 @@
+{
+    "zarr_format": 2
+}

src/titiler/xarray/tests/fixtures/dataset_3d.zarr/.zmetadata

@@ -0,0 +1,119 @@
+{
+    "metadata": {
+        ".zattrs": {},
+        ".zgroup": {
+            "zarr_format": 2
+        },
+        "dataset/.zarray": {
+            "chunks": [
+                1,
+                250,
+                500
+            ],
+            "compressor": {
+                "blocksize": 0,
+                "clevel": 5,
+                "cname": "lz4",
+                "id": "blosc",
+                "shuffle": 1
+            },
+            "dtype": "<f8",
+            "fill_value": "NaN",
+            "filters": null,
+            "order": "C",
+            "shape": [
+                2,
+                1000,
+                2000
+            ],
+            "zarr_format": 2
+        },
+        "dataset/.zattrs": {
+            "_ARRAY_DIMENSIONS": [
+                "time",
+                "y",
+                "x"
+            ],
+            "valid_max": 1000.0,
+            "valid_min": 0.0
+        },
+        "time/.zarray": {
+            "chunks": [
+                2
+            ],
+            "compressor": {
+                "blocksize": 0,
+                "clevel": 5,
+                "cname": "lz4",
+                "id": "blosc",
+                "shuffle": 1
+            },
+            "dtype": "<i8",
+            "fill_value": null,
+            "filters": null,
+            "order": "C",
+            "shape": [
+                2
+            ],
+            "zarr_format": 2
+        },
+        "time/.zattrs": {
+            "_ARRAY_DIMENSIONS": [
+                "time"
+            ],
+            "calendar": "proleptic_gregorian",
+            "units": "days since 2022-01-01 00:00:00"
+        },
+        "x/.zarray": {
+            "chunks": [
+                2000
+            ],
+            "compressor": {
+                "blocksize": 0,
+                "clevel": 5,
+                "cname": "lz4",
+                "id": "blosc",
+                "shuffle": 1
+            },
+            "dtype": "<f8",
+            "fill_value": "NaN",
+            "filters": null,
+            "order": "C",
+            "shape": [
+                2000
+            ],
+            "zarr_format": 2
+        },
+        "x/.zattrs": {
+            "_ARRAY_DIMENSIONS": [
+                "x"
+            ]
+        },
+        "y/.zarray": {
+            "chunks": [
+                1000
+            ],
+            "compressor": {
+                "blocksize": 0,
+                "clevel": 5,
+                "cname": "lz4",
+                "id": "blosc",
+                "shuffle": 1
+            },
+            "dtype": "<f8",
+            "fill_value": "NaN",
+            "filters": null,
+            "order": "C",
+            "shape": [
+                1000
+            ],
+            "zarr_format": 2
+        },
+        "y/.zattrs": {
+            "_ARRAY_DIMENSIONS": [
+                "y"
+            ]
+        }
+    },
+    "zarr_consolidated_format": 1
+}

src/titiler/xarray/tests/fixtures/dataset_3d.zarr/dataset/.zarray

@@ -0,0 +1,24 @@
+{
+    "chunks": [
+        1,
+        250,
+        500
+    ],
+    "compressor": {
+        "blocksize": 0,
+        "clevel": 5,
+        "cname": "lz4",
+        "id": "blosc",
+        "shuffle": 1
+    },
+    "dtype": "<f8",
+    "fill_value": "NaN",
+    "filters": null,
+    "order": "C",
+    "shape": [
+        2,
+        1000,
+        2000
+    ],
+    "zarr_format": 2
+}

src/titiler/xarray/tests/fixtures/dataset_3d.zarr/dataset/.zattrs

@@ -0,0 +1,9 @@
+{
+    "_ARRAY_DIMENSIONS": [
+        "time",
+        "y",
+        "x"
+    ],
+    "valid_max": 1000.0,
+    "valid_min": 0.0
+}

src/titiler/xarray/tests/fixtures/dataset_3d.zarr/time/.zarray

@@ -0,0 +1,20 @@
+{
+    "chunks": [
+        2
+    ],
+    "compressor": {
+        "blocksize": 0,
+        "clevel": 5,
+        "cname": "lz4",
+        "id": "blosc",
+        "shuffle": 1
+    },
+    "dtype": "<i8",
+    "fill_value": null,
+    "filters": null,
+    "order": "C",
+    "shape": [
+        2
+    ],
+    "zarr_format": 2
+}

src/titiler/xarray/tests/fixtures/dataset_3d.zarr/time/.zattrs

@@ -0,0 +1,7 @@
+{
+    "_ARRAY_DIMENSIONS": [
+        "time"
+    ],
+    "calendar": "proleptic_gregorian",
+    "units": "days since 2022-01-01 00:00:00"
+}