titiler-extensions 0.17.3__tar.gz

titiler.extensions-0.17.3/PKG-INFO

@@ -0,0 +1,185 @@
+Metadata-Version: 2.1
+Name: titiler.extensions
+Version: 0.17.3
+Summary: Extensions for TiTiler Factories.
+License: MIT
+Keywords: COG,STAC,MosaicJSON,Fastapi,Dynamic tile server,GDAL,Rasterio,OGC
+Author-email: Vincent Sarago <vincent@developmentseed.com>
+Requires-Python: >=3.8
+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: cogeo
+Provides-Extra: stac
+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.extensions
+
+Extent TiTiler Tiler Factories
+
+## Installation
+
+```bash
+$ python -m pip install -U pip
+
+# From Pypi
+$ python -m pip install titiler.extensions
+
+# Or from sources
+$ git clone https://github.com/developmentseed/titiler.git
+$ cd titiler && python -m pip install -e src/titiler/core -e src/titiler/extensions
+```
+
+## Available extensions
+
+#### cogValidateExtension
+
+- Goal: adds a `/validate` endpoint which return the content of rio-cogeo `info` method
+- Additional requirements: `titiler.extensions["cogeo"]`
+
+#### cogViewerExtension
+
+- Goal: adds a `/viewer` endpoint which return an HTML viewer for simple COGs
+
+#### stacViewerExtension
+
+- Goal: adds a `/viewer` endpoint which return an HTML viewer for STAC item
+
+#### wmsExtension
+
+- Goal: adds a `/wms` endpoint to support OGC Web Map Service (`GetTile` and `GetCapabilities`) specification
+
+## Use extensions
+
+Extensions must be set at TilerFactory's creation using the `extensions=` options.
+
+```python
+from fastapi import FastAPI
+from titiler.core.factory import TilerFactory
+from titiler.extensions import cogValidateExtension
+
+# Create a FastAPI application
+app = FastAPI(description="A lightweight Cloud Optimized GeoTIFF tile server")
+
+# Create a set of endpoints using TiTiler TilerFactory
+tiler = TilerFactory(
+    router_prefix="/cog",
+    extensions=[
+        cogValidateExtension()  # the cogeoExtension will add a rio-cogeo /validate endpoint
+    ]
+)
+
+# Register endpoints to the application
+app.include_router(tiler.router, prefix="/cog")
+```
+
+See [titiler.application](../application) for a full example.
+
+
+## Create your own
+
+```python
+from dataclasses import dataclass, field
+from typing import Tuple, List, Optional
+
+from starlette.responses import Response
+from fastapi import Depends, FastAPI, Query
+from titiler.core.factory import BaseTilerFactory, FactoryExtension, TilerFactory
+from titiler.core.dependencies import RescalingParams
+from titiler.core.factory import TilerFactory
+from titiler.core.resources.enums import ImageType
+
+
+@dataclass
+class thumbnailExtension(FactoryExtension):
+    """Add endpoint to a TilerFactory."""
+
+    # Set some options
+    max_size: int = field(default=128)
+
+    # Register method is mandatory and must take a BaseTilerFactory object as input
+    def register(self, factory: BaseTilerFactory):
+        """Register endpoint to the tiler factory."""
+
+        # register an endpoint to the factory's router
+        @factory.router.get(
+            "/thumbnail",
+            responses={
+                200: {
+                    "content": {
+                        "image/png": {},
+                        "image/jpeg": {},
+                    },
+                    "description": "Return an image.",
+                }
+            },
+            response_class=Response,
+        )
+        def thumbnail(
+            # we can reuse the factory dependency
+            src_path: str = Depends(factory.path_dependency),
+            layer_params=Depends(factory.layer_dependency),
+            dataset_params=Depends(factory.dataset_dependency),
+            post_process=Depends(factory.process_dependency),
+            rescale: Optional[List[Tuple[float, ...]]] = Depends(RescalingParams),
+            color_formula: Optional[str] = Query(
+                None,
+                title="Color Formula",
+                description="rio-color formula (info: https://github.com/mapbox/rio-color)",
+            ),
+            colormap=Depends(factory.colormap_dependency),
+            render_params=Depends(factory.render_dependency),
+            reader_params=Depends(factory.reader_dependency),
+            env=Depends(factory.environment_dependency),
+        ):
+            with rasterio.Env(**env):
+                with factory.reader(src_path, **reader_params) as src:
+                    image = src.preview(
+                        max_size=self.max_size,
+                        **layer_params,
+                        **dataset_params,
+                    )
+
+            if post_process:
+                image = post_process(image)
+
+            if rescale:
+                image.rescale(rescale)
+
+            if color_formula:
+                image.apply_color_formula(color_formula)
+
+            format = ImageType.jpeg if image.mask.all() else ImageType.png
+
+            content = image.render(
+                img_format=format.driver,
+                colormap=colormap,
+                **format.profile,
+                **render_params,
+            )
+
+            return Response(content, media_type=format.mediatype)
+
+# Use it
+app = FastAPI()
+tiler = TilerFactory(
+    extensions=[
+        thumbnailExtension(max_size=64)
+    ]
+)
+app.include_router(tiler.router)
+```
+

titiler.extensions-0.17.3/README.md

@@ -0,0 +1,156 @@
+## titiler.extensions
+
+Extent TiTiler Tiler Factories
+
+## Installation
+
+```bash
+$ python -m pip install -U pip
+
+# From Pypi
+$ python -m pip install titiler.extensions
+
+# Or from sources
+$ git clone https://github.com/developmentseed/titiler.git
+$ cd titiler && python -m pip install -e src/titiler/core -e src/titiler/extensions
+```
+
+## Available extensions
+
+#### cogValidateExtension
+
+- Goal: adds a `/validate` endpoint which return the content of rio-cogeo `info` method
+- Additional requirements: `titiler.extensions["cogeo"]`
+
+#### cogViewerExtension
+
+- Goal: adds a `/viewer` endpoint which return an HTML viewer for simple COGs
+
+#### stacViewerExtension
+
+- Goal: adds a `/viewer` endpoint which return an HTML viewer for STAC item
+
+#### wmsExtension
+
+- Goal: adds a `/wms` endpoint to support OGC Web Map Service (`GetTile` and `GetCapabilities`) specification
+
+## Use extensions
+
+Extensions must be set at TilerFactory's creation using the `extensions=` options.
+
+```python
+from fastapi import FastAPI
+from titiler.core.factory import TilerFactory
+from titiler.extensions import cogValidateExtension
+
+# Create a FastAPI application
+app = FastAPI(description="A lightweight Cloud Optimized GeoTIFF tile server")
+
+# Create a set of endpoints using TiTiler TilerFactory
+tiler = TilerFactory(
+    router_prefix="/cog",
+    extensions=[
+        cogValidateExtension()  # the cogeoExtension will add a rio-cogeo /validate endpoint
+    ]
+)
+
+# Register endpoints to the application
+app.include_router(tiler.router, prefix="/cog")
+```
+
+See [titiler.application](../application) for a full example.
+
+
+## Create your own
+
+```python
+from dataclasses import dataclass, field
+from typing import Tuple, List, Optional
+
+from starlette.responses import Response
+from fastapi import Depends, FastAPI, Query
+from titiler.core.factory import BaseTilerFactory, FactoryExtension, TilerFactory
+from titiler.core.dependencies import RescalingParams
+from titiler.core.factory import TilerFactory
+from titiler.core.resources.enums import ImageType
+
+
+@dataclass
+class thumbnailExtension(FactoryExtension):
+    """Add endpoint to a TilerFactory."""
+
+    # Set some options
+    max_size: int = field(default=128)
+
+    # Register method is mandatory and must take a BaseTilerFactory object as input
+    def register(self, factory: BaseTilerFactory):
+        """Register endpoint to the tiler factory."""
+
+        # register an endpoint to the factory's router
+        @factory.router.get(
+            "/thumbnail",
+            responses={
+                200: {
+                    "content": {
+                        "image/png": {},
+                        "image/jpeg": {},
+                    },
+                    "description": "Return an image.",
+                }
+            },
+            response_class=Response,
+        )
+        def thumbnail(
+            # we can reuse the factory dependency
+            src_path: str = Depends(factory.path_dependency),
+            layer_params=Depends(factory.layer_dependency),
+            dataset_params=Depends(factory.dataset_dependency),
+            post_process=Depends(factory.process_dependency),
+            rescale: Optional[List[Tuple[float, ...]]] = Depends(RescalingParams),
+            color_formula: Optional[str] = Query(
+                None,
+                title="Color Formula",
+                description="rio-color formula (info: https://github.com/mapbox/rio-color)",
+            ),
+            colormap=Depends(factory.colormap_dependency),
+            render_params=Depends(factory.render_dependency),
+            reader_params=Depends(factory.reader_dependency),
+            env=Depends(factory.environment_dependency),
+        ):
+            with rasterio.Env(**env):
+                with factory.reader(src_path, **reader_params) as src:
+                    image = src.preview(
+                        max_size=self.max_size,
+                        **layer_params,
+                        **dataset_params,
+                    )
+
+            if post_process:
+                image = post_process(image)
+
+            if rescale:
+                image.rescale(rescale)
+
+            if color_formula:
+                image.apply_color_formula(color_formula)
+
+            format = ImageType.jpeg if image.mask.all() else ImageType.png
+
+            content = image.render(
+                img_format=format.driver,
+                colormap=colormap,
+                **format.profile,
+                **render_params,
+            )
+
+            return Response(content, media_type=format.mediatype)
+
+# Use it
+app = FastAPI()
+tiler = TilerFactory(
+    extensions=[
+        thumbnailExtension(max_size=64)
+    ]
+)
+app.include_router(tiler.router)
+```

titiler.extensions-0.17.3/pyproject.toml

@@ -0,0 +1,80 @@
+[project]
+name = "titiler.extensions"
+description = "Extensions for TiTiler Factories."
+readme = "README.md"
+requires-python = ">=3.8"
+authors = [
+    { name = "Vincent Sarago", email = "vincent@developmentseed.com" },
+]
+keywords = [
+    "COG",
+    "STAC",
+    "MosaicJSON",
+    "Fastapi",
+    "Dynamic tile server",
+    "GDAL",
+    "Rasterio",
+    "OGC",
+]
+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 = []
+dependencies = [
+    "titiler.core==0.17.3",
+]
+version = "0.17.3"
+
+[project.license]
+text = "MIT"
+
+[project.optional-dependencies]
+test = [
+    "pytest",
+    "pytest-cov",
+    "pytest-asyncio",
+    "httpx",
+    "pystac[validation]>=1.0.0,<2.0.0",
+]
+cogeo = [
+    "rio-cogeo>=5.0,<6.0",
+]
+stac = [
+    "rio-stac>=0.8,<0.9",
+]
+
+[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/extensions/__init__.py"
+
+[tool.pdm.build]
+includes = [
+    "titiler/extensions",
+]
+excludes = [
+    "tests/",
+    "**/.mypy_cache",
+    "**/.DS_Store",
+]

titiler.extensions-0.17.3/titiler/extensions/__init__.py

@@ -0,0 +1,8 @@
+"""titiler.extensions"""
+
+__version__ = "0.17.3"
+
+from .cogeo import cogValidateExtension  # noqa
+from .stac import stacExtension  # noqa
+from .viewer import cogViewerExtension, stacViewerExtension  # noqa
+from .wms import wmsExtension  # noqa

titiler.extensions-0.17.3/titiler/extensions/cogeo.py

@@ -0,0 +1,43 @@
+"""rio-cogeo Extension."""
+
+from dataclasses import dataclass
+
+from fastapi import Depends, Query
+from typing_extensions import Annotated
+
+from titiler.core.factory import BaseTilerFactory, FactoryExtension
+from titiler.core.resources.responses import JSONResponse
+
+try:
+    from rio_cogeo.cogeo import cog_info
+    from rio_cogeo.models import Info
+except ImportError:  # pragma: nocover
+    cog_info = None  # type: ignore
+    Info = None
+
+
+@dataclass
+class cogValidateExtension(FactoryExtension):
+    """Add /validate endpoint to a COG TilerFactory."""
+
+    def register(self, factory: BaseTilerFactory):
+        """Register endpoint to the tiler factory."""
+
+        assert (
+            cog_info is not None
+        ), "'rio-cogeo' must be installed to use CogValidateExtension"
+
+        @factory.router.get(
+            "/validate",
+            response_model=Info,
+            response_class=JSONResponse,
+        )
+        def validate(
+            src_path=Depends(factory.path_dependency),
+            strict: Annotated[
+                bool,
+                Query(description="Treat warnings as errors"),
+            ] = False,
+        ):
+            """Validate a COG"""
+            return cog_info(src_path, strict=strict)

titiler.extensions-0.17.3/titiler/extensions/stac.py

@@ -0,0 +1,166 @@
+"""rio-stac Extension."""
+
+from dataclasses import dataclass
+from typing import Any, Dict, List, Literal, Optional
+
+from fastapi import Depends, Query
+from typing_extensions import Annotated, TypedDict
+
+from titiler.core.factory import BaseTilerFactory, FactoryExtension
+
+try:
+    import pystac
+    from pystac.utils import datetime_to_str, str_to_datetime
+    from rio_stac.stac import create_stac_item
+except ImportError:  # pragma: nocover
+    create_stac_item = None  # type: ignore
+    pystac = None  # type: ignore
+    str_to_datetime = datetime_to_str = None  # type: ignore
+
+
+class Item(TypedDict, total=False):
+    """STAC Item."""
+
+    type: str
+    stac_version: str
+    stac_extensions: Optional[List[str]]
+    id: str
+    geometry: Dict[str, Any]
+    bbox: List[float]
+    properties: Dict[str, Any]
+    links: List[Dict[str, Any]]
+    assets: Dict[str, Any]
+    collection: str
+
+
+@dataclass
+class stacExtension(FactoryExtension):
+    """Add /stac endpoint to a COG TilerFactory."""
+
+    def register(self, factory: BaseTilerFactory):
+        """Register endpoint to the tiler factory."""
+
+        assert (
+            create_stac_item is not None
+        ), "'rio-stac' must be installed to use stacExtension"
+        assert pystac is not None, "'pystac' must be installed to use stacExtension"
+
+        media = [m.value for m in pystac.MediaType] + ["auto"]
+
+        @factory.router.get("/stac", response_model=Item, name="Create STAC Item")
+        def create_stac(
+            src_path=Depends(factory.path_dependency),
+            datetime: Annotated[
+                Optional[str],
+                Query(
+                    description="The date and time of the assets, in UTC (e.g 2020-01-01, 2020-01-01T01:01:01).",
+                ),
+            ] = None,
+            extensions: Annotated[
+                Optional[List[str]],
+                Query(description="STAC extension URL the Item implements."),
+            ] = None,
+            collection: Annotated[
+                Optional[str],
+                Query(description="The Collection ID that this item belongs to."),
+            ] = None,
+            collection_url: Annotated[
+                Optional[str],
+                Query(description="Link to the STAC Collection."),
+            ] = None,
+            # properties: Optional[Dict] = Query(None, description="Additional properties to add in the item."),
+            id: Annotated[
+                Optional[str],
+                Query(
+                    description="Id to assign to the item (default to the source basename)."
+                ),
+            ] = None,
+            asset_name: Annotated[
+                Optional[str],
+                Query(description="asset name for the source (default to 'data')."),
+            ] = "data",
+            asset_roles: Annotated[
+                Optional[List[str]],
+                Query(description="list of asset's roles."),
+            ] = None,
+            asset_media_type: Annotated[  # type: ignore
+                Optional[Literal[tuple(media)]],
+                Query(description="Asset's media type"),
+            ] = "auto",
+            asset_href: Annotated[
+                Optional[str],
+                Query(description="Asset's URI (default to source's path)"),
+            ] = None,
+            with_proj: Annotated[
+                Optional[bool],
+                Query(description="Add the `projection` extension and properties."),
+            ] = True,
+            with_raster: Annotated[
+                Optional[bool],
+                Query(description="Add the `raster` extension and properties."),
+            ] = True,
+            with_eo: Annotated[
+                Optional[bool],
+                Query(description="Add the `eo` extension and properties."),
+            ] = True,
+            max_size: Annotated[
+                Optional[int],
+                Query(
+                    gt=0,
+                    description="Limit array size from which to get the raster statistics.",
+                ),
+            ] = 1024,
+            geom_densify_pts: Annotated[
+                Optional[int],
+                Query(
+                    alias="geometry_densify",
+                    ge=0,
+                    description="Number of points to add to each edge to account for nonlinear edges transformation.",
+                ),
+            ] = 0,
+            geom_precision: Annotated[
+                Optional[int],
+                Query(
+                    alias="geometry_precision",
+                    ge=-1,
+                    description="Round geometry coordinates to this number of decimal.",
+                ),
+            ] = -1,
+        ):
+            """Create STAC item."""
+            properties = (
+                {}
+            )  # or properties = properties or {} if we add properties in Query
+
+            dt = None
+            if datetime:
+                if "/" in datetime:
+                    start_datetime, end_datetime = datetime.split("/")
+                    properties["start_datetime"] = datetime_to_str(
+                        str_to_datetime(start_datetime)
+                    )
+                    properties["end_datetime"] = datetime_to_str(
+                        str_to_datetime(end_datetime)
+                    )
+                else:
+                    dt = str_to_datetime(datetime)
+
+            return create_stac_item(
+                src_path,
+                input_datetime=dt,
+                extensions=extensions,
+                collection=collection,
+                collection_url=collection_url,
+                properties=properties,
+                id=id,
+                asset_name=asset_name,
+                asset_roles=asset_roles,
+                asset_media_type=asset_media_type,
+                asset_href=asset_href or src_path,
+                with_proj=with_proj,
+                with_raster=with_raster,
+                with_eo=with_eo,
+                raster_max_size=max_size,
+                geom_densify_pts=geom_densify_pts,
+                geom_precision=geom_precision,
+            ).to_dict()