This blog is the fifth in a series called “COG Talk”, which looks at ways to use Cloud-Optimized GeoTIFFs to efficiently render and analyze planetary-scale remote sensing data
After almost a year working on it, today is finally the day we can share that we have released the new version of
rio-tiler 🎉 🎉 🎉 ! In this post we’ll look at its new features and other libraries we released, which we hope will help you access and process Earth Observation data.
The development of
rio-tiler started three years ago within the Mapbox organization and was initially a tool focused on creating Web Map tiles in the Web Mercator projection from Landsat 8 and Sentinel 2 data stored on AWS. The library was pretty simple and was mostly a wrapper around some excellent rasterio and GDAL libraries. In this new version, we tried to keep rio-tiler simple but also added new features to ease creation of dynamic tiling APIs.
The new version of
rio-tiler is a major version, meaning that sadly it has some breaking changes. In fact, there are a lot of breaking changes but to help with the transition we made a migration guide.
Maybe the biggest overall improvement to version 2 is the new documentation website. All libraries — both good and bad — are useless without good documentation. Writing good documentation had been on our to do list since the creation of
rio-tiler but we never took the time to create it properly. For
rio-tiler version 2, we rewrote all the Python docstrings and published an online documentation website: https://cogeotiff.github.io/rio-tiler/
On the online documentation page we tried to cover most features of
rio-tiler and also added some example Jupyter notebooks to showcase basic functionality (notebook).
Python 2 was officially deprecated last year so we decided to say goodbye to this good old friend and to embrace Python 3. Removing support in
rio-tiler for Python 2 enables adding type hints and advanced dependencies like Pydantic, as well as developer-friendly code like
- More Than Tiles
rio-tiler name was chosen because the primary goal of the library was to create Web Map Tiles. While the name stands, there’s more functionality in version 2 than just creating tiles. Version 2 has some neat features that help with reading and rendering more than tiles.
from rio_tiler.io import COGReader with COGReader("my-tif.tif") as cog: # get info info = cog.info() # get image statistics stats = cog.stats() # get metadata (info + image statistics) meta = cog.metadata() # Read data for a mercator tile tile = cog.tile(tile_x, tile_y, tile_zoom, tilesize=256) # Read part of a data for a given bbox (size is maxed out to 1024) aoi = cog.part([minx, miny, maxx, maxy]) # Read data for a given geojson polygon (size is maxed out to 1024) feat = cog.feature(geojson_feature) # Get a preview (size is maxed out to 1024) preview = cog.preview() # Get pixel values for a given lon/lat coordinate values = cog.point(lon, lat)
rio-tiler 2.0 we added a new way to handle input datasets. Using Python’s
Context Manager-like notation creates more pythonic code blocks by using
from rio_tiler.io import COGReader with COGReader("my-tif.tif") as cog: assert isinstance(cog.dataset, rasterio.io.DatasetReader) tile = cog.tile(1,1,1) assert cog.dataset.is_closed
rio-tiler comes with
STACReader classes. The
COGReader handles any raster data (though performance is highest when reading Cloud-Optimized GeoTIFFs), while the
STACReader was designed to work specifically with STAC items.
from rio_tiler.io import STACReader with STACReader("stac_item.json") as stac: assert isinstance(stac.item, pystac.Item) img = stac.preview(assets="image") # read the `image` asset
Version 1 of
rio-tiler relied heavily on the mercantile library, which turns Web Mercator tile indexes into geospatial coordinates. While it worked great, we wanted to add support for more projections than just Web Mercator. Using OGC TileMatrixSet (TMS) grids enables creating output tiles in any projection. Version 2 of
rio-tiler switches to a new library, morecantile, that replicates most of the
mercantile methods for any arbitrary TMS.
mercantile includes a dozen default TMS definitions and includes support for user defined grids.
When we created the mosaicJSON specification (see COG Talk 2), we also created a plugin for
rio-tiler-mosaic. For this new version, we chose to integrate the plugin directly in
rio-tiler for easier maintenance.
- REST API-friendly models
While you can use
rio-tiler locally to read and perform analysis on raster data, the library is really useful when used in conjunction with a REST API (e.g a dynamic tiler like TiTiler). For easier integration, most of
reader methods return data in the form of Pydantic models. New Python web frameworks such as FastAPI use the model definition for output validation and documentation (see: https://fastapi.tiangolo.com/tutorial/response-model/)
Designing and writing this new version of
rio-tiler wasn’t a one person project but a major team effort and since moving
rio-tiler to the cogeotiff organization we have gained several helpful contributors.
With performance and code quality in mind, it took us almost a year to get to a 2.0 official release but today I’m proud of the work and I can’t wait to get your feedback.
rio-tiler is available on pypi and the conda release should be published soon.
$ pip install -U rio-tiler # or $ git clone https://github.com/cogeotiff/rio-tiler.git $ cd rio-tiler $ pip install -e .
rio-tiler is the base for other projects that have also been recently updated.
- Version: 0.5.0
- Repo: https://github.com/cogeotiff/rio-tiler-pds
- Documentations: https://cogeotiff.github.io/rio-tiler-pds/
Mission-specific readers have been moved from rio-tiler to the rio-tiler-pds package.
- Version: 2.1.1
- Repo: https://github.com/cogeotiff/rio-cogeo
- Documentations: https://cogeotiff.github.io/rio-cogeo/
After an official 2.0 in October 2020,
rio-cogeo received several updates to better align with the new COG driver released in GDAL 3.1.
- Version: 2.1
- Repo: https://github.com/developmentseed/morecantile
- Documentations: https://developmentseed.org/morecantile/
As mentioned previously, rio-tiler was first designed to work only with the Web Mercator projection. For 2.0 we wanted to add more projection flexibility for the user community. We started to work on a simple library to replace
mercantile and came up with
morecantile (the name reflects the inspiration).
- Version: 0.4.4
- Repo: https://github.com/developmentseed/rio-viz
rio-viz is a lightweight library that helps you vizualize raster data localy. It just got refactored to support more rio-tiler’s readers.
- Version: 0.2
- Repo: https://github.com/developmentseed/tilebench
We often receive the question “What is the best COG configuration ?” There is no one
best configuration as the optimal configuration is dependent on the data use cases.
One of the most important parameters is the internal tile size (after the compression and the NoData value). Using a large internal tile size might reduce the overall number of GET requests but it will also mean more data transfer per request. A visual explanation is always better than words, and that’s why we created
TileBench. This library comes with a CLI that helps you
debug your COG and see how many GET requests a tile read might require.
Got Data ?
We’re always looking for interesting problems to tackle using COGs. If you have a raster dataset and want to learn how the different tools we are building could help, please feel free to ping me on Twitter or LinkedIn ! And if you are interested in joining Development Seed to help us build technology that helps solve global challenges take a look at our open positions!