[WIP] add STAC endpoints (#28)

* add STAC endpoints * refactor * update tests and docs * update changelog [skip ci] * update STAC UI
developmentseed · Jun 9, 2020 · fa2cb78 · fa2cb78
1 parent f4fdc02
commit fa2cb78
Show file tree

Hide file tree

Showing 42 changed files with 2,798 additions and 779 deletions.
diff --git a/CHANGES.txt b/CHANGES.txt
@@ -1,3 +1,11 @@
+2.0.0 (2020-06-09)
+------------------
+- support STAC items (#16)
+- better API documentation via response models
+- update UI (`/stac/viewer`, `/cog/viewer`)
+- re-order OpenAPI route tags
+- update documentation
+
 1.0.0 (2020-06-04)
 ------------------
 - Initial release
diff --git a/Dockerfiles/ecs/Dockerfile b/Dockerfiles/ecs/Dockerfile
@@ -9,4 +9,4 @@ COPY README.md /app/README.md
 COPY titiler/ /app/titiler/
 COPY setup.py /app/setup.py
 
-RUN pip install -e /app/. --no-cache-dir
+RUN pip install -e /app/.["stac"] --no-cache-dir
diff --git a/Dockerfiles/lambda/Dockerfile b/Dockerfiles/lambda/Dockerfile
@@ -8,7 +8,7 @@ COPY README.md /app/README.md
 COPY titiler/ /app/titiler/
 COPY setup.py /app/setup.py
 
-RUN pip install /app/.["lambda"] -t /var/task --no-binary numpy
+RUN pip install /app/.["lambda","stac"] -t /var/task --no-binary numpy
 
 # Reduce package size and remove useless files
 RUN cd /var/task && find . -type f -name '*.pyc' | while read f; do n=$(echo $f | sed 's/__pycache__\///' | sed 's/.cpython-[2-3][0-9]//'); cp $f $n; done;

diff --git a/README.md b/README.md
@@ -5,11 +5,18 @@ A lightweight Cloud Optimized GeoTIFF dynamic tile server.
 [![CircleCI](https://circleci.com/gh/developmentseed/titiler.svg?style=svg)](https://circleci.com/gh/developmentseed/titiler)
 [![codecov](https://codecov.io/gh/developmentseed/titiler/branch/master/graph/badge.svg)](https://codecov.io/gh/developmentseed/titiler)
 
-Titiler, pronounced **tee-tiler** (*ti* is the diminutiveversion of the french *petit* which means small), is lightweight service, which sole goal is to create map tiles dynamically from Cloud Optimized GeoTIFF [COG](cogeo.org).
+Titiler, pronounced **tee-tiler** (*ti* is the diminutive version of the french *petit* which means small), is lightweight service, which sole goal is to create map tiles dynamically from Cloud Optimized GeoTIFF [COG](cogeo.org).
 
 This project is the descendant of https://github.com/developmentseed/cogeo-tiler
 
-Built on top of the *modern and fast* [FastAPI](https://fastapi.tiangolo.com) framework, titiler is written using async/await asynchronous code to improve the performances and handle heavy loads.
+## Features
+
+- Multiple TileMatrixSets via [morecantile](https://github.com/developmentseed/morecantile). Default is set to WebMercatorQuad which is the usual Web Mercator projection used in most of Wep Map libraries.)
+- Cloud Optimized GeoTIFF support
+- SpatioTemporal Asset Catalog support (Optional)
+- OGC WMTS support
+- Caching layer for tiles (Optional)
+- AWS Lambda / ECS deployement options
 
 ### Test locally
 ```bash
@@ -24,218 +31,17 @@ $ docker-compose build
 $ docker-compose up 
 ```
 
-# API
-
-## Doc
-
-`:endpoint:/docs`
-
-<details>
-
-![](https://user-images.githubusercontent.com/10407788/83449203-33e8eb00-a421-11ea-8c78-6b12d368fad5.png)
-
-</details>
-
-## Tiles
-
-`:endpoint:/v1/cog/tiles/[{TileMatrixSetId}]/{z}/{x}/{y}[@{scale}x][.{ext}]`
-
-- PathParams:
-    - **TileMatrixSetId**: TileMatrixSet name, default is `WebMercatorQuad`. OPTIONAL
-    - **z**: Mercator tiles's zoom level.
-    - **x**: Mercator tiles's column.
-    - **y**: Mercator tiles's row.
-    - **scale**: Tile size scale, default is set to 1 (256x256). OPTIONAL
-    - **ext**: Output image format, default is set to None and will be either JPEG or PNG depending on masked value. OPTIONAL
-
-- QueryParams:
-    - **url**: Cloud Optimized GeoTIFF URL. **REQUIRED**
-    - **bidx**: Coma (',') delimited band indexes. OPTIONAL
-    - **nodata**: Overwrite internal Nodata value. OPTIONAL
-    - **rescale**: Coma (',') delimited Min,Max bounds. OPTIONAL
-    - **color_formula**: rio-color formula. OPTIONAL
-    - **color_map**: rio-tiler color map name. OPTIONAL
-
-Example: 
-- `https://myendpoint/v1/cog/tiles/1/2/3?url=https://somewhere.com/mycog.tif`
-- `https://myendpoint/v1/cog/tiles/1/2/3.jpg?url=https://somewhere.com/mycog.tif`
-- `https://myendpoint/v1/cog/tiles/WorldCRS84Quad/1/2/3@2x.png?url=https://somewhere.com/mycog.tif`
-- `https://myendpoint/v1/cog/tiles/WorldCRS84Quad/1/2/3?url=https://somewhere.com/mycog.tif&bidx=1,2,3&rescale=0,1000&color_map=cfastie`
-
-## TileMatrixSets
-
-
-`:endpoint:/v1/tileMatrixSets` - Get the list of supported TileMatrixSet
-
-```
-$ curl https://myendpoint/v1/tileMatrixSets | jq
-
-{
-  "tileMatrixSets": [
-    {
-      "id": "LINZAntarticaMapTilegrid",
-      "title": "LINZ Antarctic Map Tile Grid (Ross Sea Region)",
-      "links": [
-        {
-          "href": "https://myendpoint/v1/tileMatrixSets/LINZAntarticaMapTilegrid",
-          "rel": "item",
-          "type": "application/json"
-        }
-      ]
-    },
-    ...
-  ]
-}
-```
-
-`:endpoint:/v1/tileMatrixSets/{TileMatrixSetId}` - Get the TileMatrixSet JSON document
-
-- PathParams:
-    - **TileMatrixSetId**: TileMatrixSet name
-
-```
-$ curl http://127.0.0.1:8000/v1/tileMatrixSets/WebMercatorQuad | jq
-
-{
-  "type": "TileMatrixSetType",
-  "title": "Google Maps Compatible for the World",
-  "identifier": "WebMercatorQuad",
-  "supportedCRS": "http://www.opengis.net/def/crs/EPSG/0/3857",
-  "wellKnownScaleSet": "http://www.opengis.net/def/wkss/OGC/1.0/GoogleMapsCompatible",
-  "boundingBox": {
-    "type": "BoundingBoxType",
-    "crs": "http://www.opengis.net/def/crs/EPSG/0/3857",
-    "lowerCorner": [
-      -20037508.3427892,
-      -20037508.3427892
-    ],
-    "upperCorner": [
-      20037508.3427892,
-      20037508.3427892
-    ]
-  },
-  "tileMatrix": [
-    {
-      "type": "TileMatrixType",
-      "identifier": "0",
-      "scaleDenominator": 559082264.028717,
-      "topLeftCorner": [
-        -20037508.3427892,
-        20037508.3427892
-      ],
-      "tileWidth": 256,
-      "tileHeight": 256,
-      "matrixWidth": 1,
-      "matrixHeight": 1
-    },
-    ...
-```
-
-## TilesJSON
-
-`:endpoint:/v1/cog/[{TileMatrixSetId}]/tilejson.json` - Get tileJSON document
-
-- PathParams:
-    - **TileMatrixSetId**: TileMatrixSet name, default is `WebMercatorQuad`. OPTIONAL
-
-- QueryParams:
-    - **url**: Cloud Optimized GeoTIFF URL. **REQUIRED**
-    - **tile_format**: Output image format, default is set to None and will be either JPEG or PNG depending on masked value.
-    - **tile_scale**: Tile size scale, default is set to 1 (256x256). OPTIONAL
-    - **kwargs**: Other options will be forwarded to the `tiles` url.
-
-Example: 
-- `https://myendpoint/v1/cog/tilejson.json?url=https://somewhere.com/mycog.tif`
-- `https://myendpoint/v1/cog/tilejson.json?url=https://somewhere.com/mycog.tif&tile_format=png`
-- `https://myendpoint/v1/cog/WorldCRS84Quad/tilejson.json?url=https://somewhere.com/mycog.tif&tile_scale=2&bidx=1,2,3`
-
-## Bounds
+### Installation options
+
+- STAC: `pip install -e .["stac"]`
 
-`:endpoint:/v1/cog/bounds` - Get general image bounds
 
-- QueryParams:
-    - **url**: Cloud Optimized GeoTIFF URL. **REQUIRED**
+# Docs
 
-Example: 
-- `https://myendpoint/v1/cog/bounds?url=https://somewhere.com/mycog.tif`
+[link](docs/README.md)
 
 
-## Info
-
-`:endpoint:/v1/cog/info` - Get general image info
-- QueryParams:
-    - **url**: Cloud Optimized GeoTIFF URL. **REQUIRED**
-
-Example: 
-- `https://myendpoint/v1/cog/info?url=https://somewhere.com/mycog.tif`
-
-## Metadata
-
-`:endpoint:/v1/cog/metadata` - Get image statistics
-
-- QueryParams:
-    - **url**: Cloud Optimized GeoTIFF URL. **REQUIRED**
-    - **bidx**: Coma (',') delimited band indexes. OPTIONAL
-    - **nodata**: Overwrite internal Nodata value. OPTIONAL
-    - **pmin**: min percentile, default is 2. OPTIONAL
-    - **pmax**: max percentile, default is 98. OPTIONAL
-    - **max_size**: Max image size from which to calculate statistics, default is 1024. OPTIONAL
-    - **histogram_bins**: Histogram bins, default is 20. OPTIONAL
-    - **histogram_range**: Coma (',') delimited histogram bounds. OPTIONAL
-
-Example: 
-- `https://myendpoint/v1/cog/metadata?url=https://somewhere.com/mycog.tif&bidx=1,2,3`
-
-## Demo
-
-`:endpoint:/index.html` - Full UI (histogram, predefined rescaling, ...)
-
-`:endpoint:/simple_viewer.html` - Simple UI (no histogram, manual rescaling, ...)
-
-# Project structure
-
-```
-titiler/                         - titiler python module.
- ├── api/                        - general api directory.
- │   ├── api_v1/                 - directory hosting version 1 of the API.
- │   │   ├── endpoints           - api routes.
- │   │   │   ├── metadata.py     - metadata endpoints (e.g. /tilesjson.json, /metadata...).
- │   │   │   ├── ogc.py          - OGC endpoints (e.g WMTS).
- │   │   │   ├── operations.py   - clip/points endpoints.
- │   │   │   ├── tiles.py        - tiling related endpoints.
- │   │   └── api.py              - construct the API by merging api_v1 endpoints.
- │   ├── deps.py                 - API dependencies.
- │   └── utils.py                - API utility functions.
- │
- ├── core/                       - application configuration.
- ├── custom/                     - Custom colormap and TMS grids.
- ├── db/                         - db related stuff.
- ├── models/                     - pydantic models for this application.
- ├── ressources/                 - application ressources (enums, constants, ...).
- ├── templates/                  - html/xml models.
- ├── main.py                     - FastAPI application creation and configuration.
- ├── utils.py                    - utility functions.
- │
-stack/
- ├── app.py                      - AWS Stack definition (vpc, cluster, ecs, alb ...)
- ├── config.py                   - Optional parameters for the stack definition [EDIT THIS]
- │
-Dockerfiles/
- ├── ecs/
- │   └── Dockerfile              - Dockerfile to build the ECS service image.
- ├── lambda/
- │   └── Dockerfile              - Dockerfile to build the Lambda service image.
- │
-lambda/
- │   └── handler.py              - Mangum adaptator fro AWS Lambda.
- │
-docs/
- └── openapi.json                - OpenAPI document.
-
-```
-
-
-## Deployment
+# Deployment
 
 To be able to deploy on either ECS or Lambda you first need to install more dependencies:
 
@@ -336,7 +142,48 @@ $ cdk deploy titiler-lambda-dev # Deploys the stack(s) titiler-lambda-dev in sta
 
 </details>
 
-## Contribution & Development
+# Project structure
+
+```
+titiler/                         - titiler python module.
+ ├── api/                        - general api directory.
+ │   ├── api_                 - directory hosting version 1 of the API.
+ │   │   ├── endpoints           - api routes.
+ │   │   │   ├── metadata.py     - metadata endpoints (e.g. /tilesjson.json, /metadata...).
+ │   │   │   ├── ogc.py          - OGC endpoints (e.g WMTS).
+ │   │   │   ├── operations.py   - clip/points endpoints.
+ │   │   │   ├── tiles.py        - tiling related endpoints.
+ │   │   └── api.py              - construct the API by merging api_v1 endpoints.
+ │   ├── deps.py                 - API dependencies.
+ │   └── utils.py                - API utility functions.
+ │
+ ├── core/                       - application configuration.
+ ├── custom/                     - Custom colormap and TMS grids.
+ ├── db/                         - db related stuff.
+ ├── models/                     - pydantic models for this application.
+ ├── ressources/                 - application ressources (enums, constants, ...).
+ ├── templates/                  - html/xml models.
+ ├── main.py                     - FastAPI application creation and configuration.
+ ├── utils.py                    - utility functions.
+ │
+stack/
+ ├── app.py                      - AWS Stack definition (vpc, cluster, ecs, alb ...)
+ ├── config.py                   - Optional parameters for the stack definition [EDIT THIS]
+ │
+Dockerfiles/
+ ├── ecs/
+ │   └── Dockerfile              - Dockerfile to build the ECS service image.
+ ├── lambda/
+ │   └── Dockerfile              - Dockerfile to build the Lambda service image.
+ │
+lambda/
+ │   └── handler.py              - Mangum adaptator fro AWS Lambda.
+ │
+docs/                            - Project documentations.
+
+```
+
+# Contribution & Development
 
 Issues and pull requests are more than welcome.