add colormap endpoints (#796)

* Bump version: 0.17.0 → 0.17.1 * add colormap endpoints * fix orientation * update height/width descriptions * remove hex options and handle different cmap types * update from main * fix typo * support discrete cmap * handle sequence cmap * add tests * update docs * colormaps -> colorMaps * update changelog
developmentseed · Mar 21, 2024 · 9df1731 · 9df1731
1 parent 66f06ef
commit 9df1731
Show file tree

Hide file tree

Showing 14 changed files with 815 additions and 60 deletions.
diff --git a/.bumpversion.cfg b/.bumpversion.cfg
@@ -3,10 +3,10 @@ current_version = 0.17.3
 commit = True
 tag = True
 tag_name = {new_version}
-parse = 
+parse =
 	(?P<major>\d+)\.(?P<minor>\d+)\.(?P<patch>\d+)
 	((?P<pre>a|b|rc)(?P<prenum>\d+))?
-serialize = 
+serialize =
 	{major}.{minor}.{patch}{pre}{prenum}
 	{major}.{minor}.{patch}
 

diff --git a/CHANGES.md b/CHANGES.md
@@ -1,5 +1,11 @@
 # Release Notes
 
+## Unreleased
+
+### titiler.core
+
+* Add `ColorMapFactory` to create colorMap metadata endpoints (https://github.com/developmentseed/titiler/pull/796)
+
 ## 0.17.3 (2024-03-21)
 
 ### titiler.application

diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml
@@ -28,7 +28,7 @@ nav:
     - Output data format: "output_format.md"
 
   - Advanced User Guide:
-      - Tiler Factories: "advanced/tiler_factories.md"
+      - Endpoints Factories: "advanced/endpoints_factories.md"
       - Dependencies: "advanced/dependencies.md"
       - Customization: "advanced/customization.md"
       - Performance Tuning: "advanced/performance_tuning.md"
@@ -42,6 +42,8 @@ nav:
     - /stac: "endpoints/stac.md"
     - /mosaicjson: "endpoints/mosaic.md"
     - /tileMatrixSets: "endpoints/tms.md"
+    - /algorithms: "endpoints/algorithms.md"
+    - /colormaps: "endpoints/colormaps.md"
 
   - Examples:
     - Create dynamic tilers with TiTiler:

diff --git a/docs/src/advanced/tiler_factories.md → docs/src/advanced/endpoints_factories.md b/docs/src/advanced/tiler_factories.md → docs/src/advanced/endpoints_factories.md
diff --git a/docs/src/endpoints/algorithms.md b/docs/src/endpoints/algorithms.md
@@ -0,0 +1,116 @@
+In addition to the `/cog`, `/stac` and `/mosaicjson` endpoints, the `titiler.application` package FastAPI application commes with additional metadata endpoints.
+
+# Algorithms
+
+## API
+
+| Method | URL                          | Output          | Description
+| ------ | ---------------------------- |---------------- |--------------
+| `GET`  | `/algorithms`                | JSON            | retrieve the list of available Algorithms
+| `GET`  | `/algorithms/{algorithmId}`  | JSON            | retrieve the metadata of the specified algorithm.
+
+## Description
+
+
+### List Algorithm
+
+`:endpoint:/algorithm` - Get the list of supported TileMatrixSet
+
+```bash
+$ curl https://myendpoint/algorithms | jq
+
+{
+  "hillshade": {
+    "title": "Hillshade",
+    "description": "Create hillshade from DEM dataset.",
+    "inputs": {
+      "nbands": 1
+    },
+    "outputs": {
+      "nbands": 1,
+      "dtype": "uint8",
+      "min": null,
+      "max": null
+    },
+    "parameters": {
+      "azimuth": {
+        "default": 90,
+        "maximum": 360,
+        "minimum": 0,
+        "title": "Azimuth",
+        "type": "integer"
+      },
+      "angle_altitude": {
+        "default": 90.0,
+        "maximum": 90.0,
+        "minimum": -90.0,
+        "title": "Angle Altitude",
+        "type": "number"
+      },
+      "buffer": {
+        "default": 3,
+        "maximum": 99,
+        "minimum": 0,
+        "title": "Buffer",
+        "type": "integer"
+      }
+    }
+  },
+  ...
+}
+```
+
+### Get Algorithm info
+
+`:endpoint:/algorithms/{algorithmId}` - Get the algorithm metadata
+
+- PathParams:
+    - **algorithmId**: algorithm name
+
+```bash
+$ curl http://127.0.0.1:8000/algorithms/contours | jq
+
+{
+  "title": "Contours",
+  "description": "Create contours from DEM dataset.",
+  "inputs": {
+    "nbands": 1
+  },
+  "outputs": {
+    "nbands": 3,
+    "dtype": "uint8",
+    "min": null,
+    "max": null
+  },
+  "parameters": {
+    "increment": {
+      "default": 35,
+      "maximum": 999,
+      "minimum": 0,
+      "title": "Increment",
+      "type": "integer"
+    },
+    "thickness": {
+      "default": 1,
+      "maximum": 10,
+      "minimum": 0,
+      "title": "Thickness",
+      "type": "integer"
+    },
+    "minz": {
+      "default": -12000,
+      "maximum": 99999,
+      "minimum": -99999,
+      "title": "Minz",
+      "type": "integer"
+    },
+    "maxz": {
+      "default": 8000,
+      "maximum": 99999,
+      "minimum": -99999,
+      "title": "Maxz",
+      "type": "integer"
+    }
+  }
+}
+```
diff --git a/docs/src/endpoints/colormaps.md b/docs/src/endpoints/colormaps.md
@@ -0,0 +1,96 @@
+In addition to the `/cog`, `/stac` and `/mosaicjson` endpoints, the `titiler.application` package FastAPI application commes with additional metadata endpoints.
+
+# Algorithms
+
+## API
+
+| Method | URL                          | Output | Description
+| ------ | ---------------------------- |--------|--------------
+| `GET`  | `/colorMaps`                 | JSON   | retrieve the list of available colorMaps
+| `GET`  | `/colorMaps/{colorMapId}`    | JSON   | retrieve the metadata or image of the specified colorMap.
+
+## Description
+
+
+### List colormaps
+
+`:endpoint:/colorMaps` - Get the list of supported ColorMaps
+
+```bash
+$ curl https://myendpoint/colorMaps | jq
+
+{
+  "colorMaps": [
+    "dense_r",
+    "delta",
+    ...
+  ],
+  "links": [
+    {
+      "href": "http://myendpoint/colorMaps",
+      "rel": "self",
+      "type": "application/json",
+      "title": "List of available colormaps"
+    },
+    {
+      "href": "http://myendpoint/colorMaps/{colorMapId}",
+      "rel": "data",
+      "type": "application/json",
+      "templated": true,
+      "title": "Retrieve colormap metadata"
+    },
+    {
+      "href": "http://myendpoint/colorMaps/{colorMapId}?format=png",
+      "rel": "data",
+      "type": "image/png",
+      "templated": true,
+      "title": "Retrieve colormap as image"
+    }
+  ]
+}
+```
+
+### Get ColorMap metadata or as image
+
+`:endpoint:/colorMaps/{colorMapId}` - Get the ColorMap metadata or image
+
+- PathParams:
+    - **colorMapId**: colormap name
+
+- QueryParams:
+    - **format** (str): output image format (PNG/JPEG...). Defaults to JSON output.
+    - **orientation** (["vertical", "horizontal"]): image orientation. Defaults to `horizontal`.
+    - **height** (int): output image height. Default to 20px for horizontal or 256px for vertical.
+    - **width** (int): output image width. Defaults to 256px for horizontal or 20px for vertical.
+
+```bash
+$ curl http://myendpoint/colorMaps/viridis | jq
+
+{
+  "0": [
+    68,
+    1,
+    84,
+    255
+  ],
+  ...
+  "255": [
+    253,
+    231,
+    36,
+    255
+  ]
+}
+```
+
+```
+curl http://myendpoint/colorMaps/viridis?format=png
+```
+
+```
+curl http://myendpoint/colorMaps/viridis?format=png&orientation=vertical
+```
+
+```
+curl http://myendpoint/colorMaps/viridis?format=png&orientation=vertical&width=100&height=1000
+```
diff --git a/docs/src/endpoints/tms.md b/docs/src/endpoints/tms.md
@@ -1,17 +1,7 @@
-The `titiler.application` package comes with a full FastAPI application with COG, STAC and MosaicJSON supports.
 
-# TileMatrixSets
-
-The `tms` router extend the default `titiler.core.factory.TMSFactory`, adding some custom TileMatrixSets.
-
-```python
-from fastapi import FastAPI
-from titiler.application.routers.tms import tms
-
-app = FastAPI()
-app.include_router(tms.router, tags=["TileMatrixSets"])
-```
+In addition to the `/cog`, `/stac` and `/mosaicjson` endpoints, the `titiler.application` package FastAPI application comes with additional metadata endpoints.
 
+# TileMatrixSets
 
 ## API
 

diff --git a/docs/src/intro.md b/docs/src/intro.md
@@ -27,7 +27,9 @@ See default endpoints documentation pages:
 * [`/cog` - Cloud Optimized GeoTIFF](endpoints/cog.md)
 * [`/mosaicjson` - MosaicJSON](endpoints/mosaic.md)
 * [`/stac` - Spatio Temporal Asset Catalog](endpoints/stac.md)
-* [`/tms` - TileMatrixSets](endpoints/tms.md)
+* [`/tileMatrixSets` - Tiling Schemes](endpoints/tms.md)
+* [`/algorithms` - Algorithms](endpoints/algorithms.md)
+* [`/colorMaps` - ColorMaps](endpoints/colormaps.md)
 
 #### Settings
 
@@ -47,7 +49,7 @@ The default application can be customized using environment variables defined in
 
 ## Customized, minimal app
 
-`TiTiler` has been developed so users can build their own app using only the portions they need. Using [TilerFactories](advanced/tiler_factories.md), users can create a fully customized application with only the endpoints needed.
+`TiTiler` has been developed so users can build their own application with only the endpoints they need. Using [Factories](advanced/endpoints_factories.md), users can create a fully customized application with only a defined set of endpoints.
 
 When building a custom application, you may wish to only install the `core` and/or `mosaic` modules. To install these from PyPI:
 

diff --git a/src/titiler/application/titiler/application/main.py b/src/titiler/application/titiler/application/main.py
@@ -18,6 +18,7 @@
 from titiler.core.errors import DEFAULT_STATUS_CODES, add_exception_handlers
 from titiler.core.factory import (
     AlgorithmFactory,
+    ColorMapFactory,
     MultiBaseTilerFactory,
     TilerFactory,
     TMSFactory,
@@ -155,6 +156,15 @@ def validate_access_token(access_token: str = Security(api_key_query)):
     tags=["Algorithms"],
 )
 
+###############################################################################
+# Colormaps endpoints
+cmaps = ColorMapFactory()
+app.include_router(
+    cmaps.router,
+    tags=["ColorMaps"],
+)
+
+
 add_exception_handlers(app, DEFAULT_STATUS_CODES)
 add_exception_handlers(app, MOSAIC_STATUS_CODES)