Skip to content

Commit

Permalink
[WIP] add STAC endpoints (#28)
Browse files Browse the repository at this point in the history
* add STAC endpoints

* refactor

* update tests and docs

* update changelog [skip ci]

* update STAC UI
  • Loading branch information
vincentsarago committed Jun 9, 2020
1 parent f4fdc02 commit fa2cb78
Show file tree
Hide file tree
Showing 42 changed files with 2,798 additions and 779 deletions.
8 changes: 8 additions & 0 deletions CHANGES.txt
Original file line number Diff line number Diff line change
@@ -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
2 changes: 1 addition & 1 deletion Dockerfiles/ecs/Dockerfile
Original file line number Diff line number Diff line change
Expand Up @@ -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
2 changes: 1 addition & 1 deletion Dockerfiles/lambda/Dockerfile
Original file line number Diff line number Diff line change
Expand Up @@ -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;
Expand Down
267 changes: 57 additions & 210 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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:

Expand Down Expand Up @@ -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.

Expand Down
Loading

0 comments on commit fa2cb78

Please sign in to comment.