titiler-core 0.17.3__tar.gz

titiler.core-0.17.3/PKG-INFO

@@ -0,0 +1,92 @@
+Metadata-Version: 2.1
+Name: titiler.core
+Version: 0.17.3
+Summary: A modern dynamic tile server built on top of FastAPI and Rasterio/GDAL.
+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: 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.core
+
+Core of Titiler's application. Contains blocks to create dynamic tile servers.
+
+## Installation
+
+```bash
+$ python -m pip install -U pip
+
+# From Pypi
+$ python -m pip install titiler.core
+
+# Or from sources
+$ git clone https://github.com/developmentseed/titiler.git
+$ cd titiler && python -m pip install -e src/titiler/core
+```
+
+## How To
+
+```python
+from fastapi import FastAPI
+from titiler.core.factory import TilerFactory
+
+# Create a FastAPI application
+app = FastAPI(
+    description="A lightweight Cloud Optimized GeoTIFF tile server",
+)
+
+# Create a set of COG endpoints
+cog = TilerFactory()
+
+# Register the COG endpoints to the application
+app.include_router(cog.router, tags=["Cloud Optimized GeoTIFF"])
+```
+
+See [titiler.application](../application) for a full example.
+
+## Package structure
+
+```
+titiler/
+ └── core/
+    ├── tests/                   - Tests suite
+    └── titiler/core/            - `core` namespace package
+        ├── algorithm/
+        |   ├── base.py          - ABC Base Class for custom algorithms
+        |   ├── dem.py           - Elevation data related algorithms
+        |   └── index.py         - Simple band index algorithms
+        ├── models/
+        |   ├── response.py      - Titiler's response models
+        |   ├── mapbox.py        - Mapbox TileJSON pydantic model
+        |   └── OGC.py           - Open GeoSpatial Consortium pydantic models (TileMatrixSets...)
+        ├── resources/
+        |   ├── enums.py         - Titiler's enumerations (e.g MediaType)
+        |   └── responses.py     - Custom Starlette's responses
+        ├── templates/
+        |   ├── map.html         - Simple Map viewer (built with leaflet)
+        |   └── wmts.xml         - OGC WMTS document template
+        ├── dependencies.py      - Titiler FastAPI's dependencies
+        ├── errors.py            - Errors handler factory
+        ├── middleware.py        - Starlette middlewares
+        ├── factory.py           - Dynamic tiler endpoints factories
+        ├── routing.py           - Custom APIRoute class
+        └── utils.py             - Titiler utility functions
+```
+

titiler.core-0.17.3/README.md

@@ -0,0 +1,65 @@
+## titiler.core
+
+Core of Titiler's application. Contains blocks to create dynamic tile servers.
+
+## Installation
+
+```bash
+$ python -m pip install -U pip
+
+# From Pypi
+$ python -m pip install titiler.core
+
+# Or from sources
+$ git clone https://github.com/developmentseed/titiler.git
+$ cd titiler && python -m pip install -e src/titiler/core
+```
+
+## How To
+
+```python
+from fastapi import FastAPI
+from titiler.core.factory import TilerFactory
+
+# Create a FastAPI application
+app = FastAPI(
+    description="A lightweight Cloud Optimized GeoTIFF tile server",
+)
+
+# Create a set of COG endpoints
+cog = TilerFactory()
+
+# Register the COG endpoints to the application
+app.include_router(cog.router, tags=["Cloud Optimized GeoTIFF"])
+```
+
+See [titiler.application](../application) for a full example.
+
+## Package structure
+
+```
+titiler/
+ └── core/
+    ├── tests/                   - Tests suite
+    └── titiler/core/            - `core` namespace package
+        ├── algorithm/
+        |   ├── base.py          - ABC Base Class for custom algorithms
+        |   ├── dem.py           - Elevation data related algorithms
+        |   └── index.py         - Simple band index algorithms
+        ├── models/
+        |   ├── response.py      - Titiler's response models
+        |   ├── mapbox.py        - Mapbox TileJSON pydantic model
+        |   └── OGC.py           - Open GeoSpatial Consortium pydantic models (TileMatrixSets...)
+        ├── resources/
+        |   ├── enums.py         - Titiler's enumerations (e.g MediaType)
+        |   └── responses.py     - Custom Starlette's responses
+        ├── templates/
+        |   ├── map.html         - Simple Map viewer (built with leaflet)
+        |   └── wmts.xml         - OGC WMTS document template
+        ├── dependencies.py      - Titiler FastAPI's dependencies
+        ├── errors.py            - Errors handler factory
+        ├── middleware.py        - Starlette middlewares
+        ├── factory.py           - Dynamic tiler endpoints factories
+        ├── routing.py           - Custom APIRoute class
+        └── utils.py             - Titiler utility functions
+```

titiler.core-0.17.3/pyproject.toml

@@ -0,0 +1,82 @@
+[project]
+name = "titiler.core"
+description = "A modern dynamic tile server built on top of FastAPI and Rasterio/GDAL."
+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 = [
+    "fastapi>=0.107.0",
+    "geojson-pydantic>=1.0,<2.0",
+    "jinja2>=2.11.2,<4.0.0",
+    "numpy",
+    "pydantic~=2.0",
+    "rasterio",
+    "rio-tiler>=6.3.0,<7.0",
+    "morecantile>=5.0,<6.0",
+    "simplejson",
+    "typing_extensions>=4.6.1",
+]
+version = "0.17.3"
+
+[project.license]
+text = "MIT"
+
+[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/core/__init__.py"
+
+[tool.pdm.build]
+includes = [
+    "titiler/core",
+]
+excludes = [
+    "tests/",
+    "**/.mypy_cache",
+    "**/.DS_Store",
+]

titiler.core-0.17.3/titiler/core/__init__.py

@@ -0,0 +1,11 @@
+"""titiler.core"""
+
+__version__ = "0.17.3"
+
+from . import dependencies, errors, factory, routing  # noqa
+from .factory import (  # noqa
+    BaseTilerFactory,
+    MultiBandTilerFactory,
+    MultiBaseTilerFactory,
+    TilerFactory,
+)

titiler.core-0.17.3/titiler/core/algorithm/__init__.py

@@ -0,0 +1,82 @@
+"""titiler.core.algorithm."""
+
+import json
+from copy import copy
+from typing import Dict, List, Literal, Optional, Type
+
+import attr
+from fastapi import HTTPException, Query
+from pydantic import ValidationError
+from typing_extensions import Annotated
+
+from titiler.core.algorithm.base import AlgorithmMetadata, BaseAlgorithm  # noqa
+from titiler.core.algorithm.dem import Contours, HillShade, TerrainRGB, Terrarium
+from titiler.core.algorithm.index import NormalizedIndex
+
+default_algorithms: Dict[str, Type[BaseAlgorithm]] = {
+    "hillshade": HillShade,
+    "contours": Contours,
+    "normalizedIndex": NormalizedIndex,
+    "terrarium": Terrarium,
+    "terrainrgb": TerrainRGB,
+}
+
+
+@attr.s(frozen=True)
+class Algorithms:
+    """Algorithms."""
+
+    data: Dict[str, Type[BaseAlgorithm]] = attr.ib()
+
+    def get(self, name: str) -> BaseAlgorithm:
+        """Fetch a TMS."""
+        if name not in self.data:
+            raise KeyError(f"Invalid name: {name}")
+
+        return self.data[name]
+
+    def list(self) -> List[str]:
+        """List registered Algorithm."""
+        return list(self.data.keys())
+
+    def register(
+        self,
+        algorithms: Dict[str, BaseAlgorithm],
+        overwrite: bool = False,
+    ) -> "Algorithms":
+        """Register Algorithm(s)."""
+        for name, _algo in algorithms.items():
+            if name in self.data and not overwrite:
+                raise Exception(f"{name} is already a registered. Use overwrite=True.")
+
+        return Algorithms({**self.data, **algorithms})
+
+    @property
+    def dependency(self):
+        """FastAPI PostProcess dependency."""
+
+        def post_process(
+            algorithm: Annotated[
+                Literal[tuple(self.data.keys())],
+                Query(description="Algorithm name"),
+            ] = None,
+            algorithm_params: Annotated[
+                Optional[str],
+                Query(description="Algorithm parameter"),
+            ] = None,
+        ) -> Optional[BaseAlgorithm]:
+            """Data Post-Processing options."""
+            kwargs = json.loads(algorithm_params) if algorithm_params else {}
+            if algorithm:
+                try:
+                    return self.get(algorithm)(**kwargs)
+
+                except ValidationError as e:
+                    raise HTTPException(status_code=400, detail=str(e)) from e
+
+            return None
+
+        return post_process
+
+
+algorithms = Algorithms(copy(default_algorithms))  # noqa

titiler.core-0.17.3/titiler/core/algorithm/base.py

@@ -0,0 +1,40 @@
+"""Algorithm base class."""
+
+import abc
+from typing import Dict, Optional, Sequence
+
+from pydantic import BaseModel
+from rio_tiler.models import ImageData
+
+
+class BaseAlgorithm(BaseModel, metaclass=abc.ABCMeta):
+    """Algorithm baseclass.
+
+    Note: attribute starting with `input_` or `output_` are considered as metadata
+
+    """
+
+    # metadata
+    input_nbands: Optional[int] = None
+    output_nbands: Optional[int] = None
+    output_dtype: Optional[str] = None
+    output_min: Optional[Sequence] = None
+    output_max: Optional[Sequence] = None
+
+    model_config = {"extra": "allow"}
+
+    @abc.abstractmethod
+    def __call__(self, img: ImageData) -> ImageData:
+        """Apply algorithm"""
+        ...
+
+
+class AlgorithmMetadata(BaseModel):
+    """Algorithm metadata."""
+
+    title: Optional[str] = None
+    description: Optional[str] = None
+
+    inputs: Dict
+    outputs: Dict
+    parameters: Dict

titiler.core-0.17.3/titiler/core/algorithm/dem.py

@@ -0,0 +1,183 @@
+"""titiler.core.algorithm DEM."""
+
+import numpy
+from pydantic import Field
+from rasterio import windows
+from rio_tiler.colormap import apply_cmap, cmap
+from rio_tiler.models import ImageData
+from rio_tiler.utils import linear_rescale
+
+from titiler.core.algorithm.base import BaseAlgorithm
+
+
+class HillShade(BaseAlgorithm):
+    """Hillshade."""
+
+    title: str = "Hillshade"
+    description: str = "Create hillshade from DEM dataset."
+
+    # parameters
+    azimuth: int = Field(90, ge=0, le=360)
+    angle_altitude: float = Field(90.0, ge=-90.0, le=90.0)
+    buffer: int = Field(3, ge=0, le=99)
+
+    # metadata
+    input_nbands: int = 1
+    output_nbands: int = 1
+    output_dtype: str = "uint8"
+
+    def __call__(self, img: ImageData) -> ImageData:
+        """Create hillshade from DEM dataset."""
+        x, y = numpy.gradient(img.array[0])
+        slope = numpy.pi / 2.0 - numpy.arctan(numpy.sqrt(x * x + y * y))
+        aspect = numpy.arctan2(-x, y)
+        azimuthrad = self.azimuth * numpy.pi / 180.0
+        altituderad = self.angle_altitude * numpy.pi / 180.0
+        shaded = numpy.sin(altituderad) * numpy.sin(slope) + numpy.cos(
+            altituderad
+        ) * numpy.cos(slope) * numpy.cos(azimuthrad - aspect)
+        data = 255 * (shaded + 1) / 2
+
+        bounds = img.bounds
+        if self.buffer:
+            data = data[self.buffer : -self.buffer, self.buffer : -self.buffer]
+
+            window = windows.Window(
+                col_off=self.buffer,
+                row_off=self.buffer,
+                width=data.shape[1],
+                height=data.shape[0],
+            )
+            bounds = windows.bounds(window, img.transform)
+
+        return ImageData(
+            data.astype(self.output_dtype),
+            assets=img.assets,
+            crs=img.crs,
+            bounds=bounds,
+            band_names=["hillshade"],
+        )
+
+
+class Contours(BaseAlgorithm):
+    """Contours.
+
+    Original idea from https://custom-scripts.sentinel-hub.com/dem/contour-lines/
+    """
+
+    title: str = "Contours"
+    description: str = "Create contours from DEM dataset."
+
+    # parameters
+    increment: int = Field(35, ge=0, le=999)
+    thickness: int = Field(1, ge=0, le=10)
+    minz: int = Field(-12000, ge=-99999, le=99999)
+    maxz: int = Field(8000, ge=-99999, le=99999)
+
+    # metadata
+    input_nbands: int = 1
+    output_nbands: int = 3
+    output_dtype: str = "uint8"
+
+    def __call__(self, img: ImageData) -> ImageData:
+        """Add contours."""
+        data = img.data
+
+        # Apply rescaling for minz,maxz to 1->255 and apply Terrain colormap
+        arr = linear_rescale(data, (self.minz, self.maxz), (1, 255)).astype(
+            self.output_dtype
+        )
+        arr, _ = apply_cmap(arr, cmap.get("terrain"))
+
+        # set black (0) for contour lines
+        arr = numpy.where(data % self.increment < self.thickness, 0, arr)
+
+        data = numpy.ma.MaskedArray(arr)
+        data.mask = ~img.mask
+
+        return ImageData(
+            data,
+            assets=img.assets,
+            crs=img.crs,
+            bounds=img.bounds,
+        )
+
+
+class Terrarium(BaseAlgorithm):
+    """Encode DEM into RGB (Mapzen Terrarium)."""
+
+    title: str = "Terrarium"
+    description: str = "Encode DEM into RGB (Mapzen Terrarium)."
+
+    # metadata
+    input_nbands: int = 1
+    output_nbands: int = 3
+    output_dtype: str = "uint8"
+
+    def __call__(self, img: ImageData) -> ImageData:
+        """Encode DEM into RGB."""
+        data = numpy.clip(img.array[0] + 32768.0, 0.0, 65535.0)
+        r = data / 256
+        g = data % 256
+        b = (data * 256) % 256
+
+        return ImageData(
+            numpy.ma.stack([r, g, b]).astype(self.output_dtype),
+            assets=img.assets,
+            crs=img.crs,
+            bounds=img.bounds,
+        )
+
+
+class TerrainRGB(BaseAlgorithm):
+    """Encode DEM into RGB (Mapbox Terrain RGB)."""
+
+    title: str = "Terrarium"
+    description: str = "Encode DEM into RGB (Mapbox Terrain RGB)."
+
+    # parameters
+    interval: float = Field(0.1, ge=0.0, le=1.0)
+    baseval: float = Field(-10000.0, ge=-99999.0, le=99999.0)
+
+    # metadata
+    input_nbands: int = 1
+    output_nbands: int = 3
+    output_dtype: str = "uint8"
+
+    def __call__(self, img: ImageData) -> ImageData:
+        """Encode DEM into RGB (Mapbox Terrain RGB).
+
+        Code from https://github.com/mapbox/rio-rgbify/blob/master/rio_rgbify/encoders.py (MIT)
+
+        """
+
+        def _range_check(datarange):
+            """
+            Utility to check if data range is outside of precision for 3 digit base 256
+            """
+            maxrange = 256**3
+
+            return datarange > maxrange
+
+        round_digits = 0
+
+        data = img.array[0].astype(numpy.float64)
+        data -= self.baseval
+        data /= self.interval
+
+        data = numpy.around(data / 2**round_digits) * 2**round_digits
+
+        datarange = data.max() - data.min()
+        if _range_check(datarange):
+            raise ValueError(f"Data of {datarange} larger than 256 ** 3")
+
+        r = ((((data // 256) // 256) / 256) - (((data // 256) // 256) // 256)) * 256
+        g = (((data // 256) / 256) - ((data // 256) // 256)) * 256
+        b = ((data / 256) - (data // 256)) * 256
+
+        return ImageData(
+            numpy.ma.stack([r, g, b]).astype(self.output_dtype),
+            assets=img.assets,
+            crs=img.crs,
+            bounds=img.bounds,
+        )

titiler.core-0.17.3/titiler/core/algorithm/index.py

@@ -0,0 +1,36 @@
+"""titiler.core.algorithm Normalized Index."""
+
+from typing import Sequence
+
+import numpy
+from rio_tiler.models import ImageData
+
+from titiler.core.algorithm.base import BaseAlgorithm
+
+
+class NormalizedIndex(BaseAlgorithm):
+    """Normalized Difference Index."""
+
+    title: str = "Normalized Difference Index"
+    description: str = "Compute normalized difference index from two bands."
+
+    # metadata
+    input_nbands: int = 2
+    output_nbands: int = 1
+    output_dtype: str = "float32"
+    output_min: Sequence[float] = [-1.0]
+    output_max: Sequence[float] = [1.0]
+
+    def __call__(self, img: ImageData) -> ImageData:
+        """Normalized difference."""
+        b1 = img.array[0].astype("float32")
+        b2 = img.array[1].astype("float32")
+        arr = numpy.ma.MaskedArray((b2 - b1) / (b2 + b1), dtype=self.output_dtype)
+        bnames = img.band_names
+        return ImageData(
+            arr,
+            assets=img.assets,
+            crs=img.crs,
+            bounds=img.bounds,
+            band_names=[f"({bnames[1]} - {bnames[0]}) / ({bnames[1]} + {bnames[0]})"],
+        )