COG Talk — Part 5 rio-tiler 2.0

Blog

Estimated
6 min read
By
Avatar of Vincent Sarago
Vincent Saragoon
Blog post cover image

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.

cog talk5 rio tiler logo

rio-tiler 2.0

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.

What's new:

  • Documentation

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>=3.6

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 f-strings.

  • More Than Tiles

The 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)

Notebook: https://cogeotiff.github.io/rio-tiler/examples/Using-rio-tiler/

  • Readers

With 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 with.

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

By default rio-tiler comes with COGReader and 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

Notebook: https://cogeotiff.github.io/rio-tiler/examples/Using-rio-tiler-STACReader/

  • morecantile

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.

Notebook: https://cogeotiff.github.io/rio-tiler/examples/Using-tms/

  • Mosaics

When we created the mosaicJSON specification (see COG Talk 2), we also created a plugin for rio-tiler: rio-tiler-mosaic. For this new version, we chose to integrate the plugin directly in rio-tiler for easier maintenance.

Notebook: https://cogeotiff.github.io/rio-tiler/examples/Using-rio-tiler-mosaic/

  • 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 rio-tiler's 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/)

The A team

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.

cog talk5 rio tiler contributors

The value of Kyle and Jeff's contributions can't be measured in commits alone, their behind the scenes work on issues and reviews has been enormous 🙏 .

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.

Install

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 .

Other tools

rio-tiler is the base for other projects that have also been recently updated.

rio-tiler-pds

Mission-specific readers have been moved from rio-tiler to the rio-tiler-pds package.

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.

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).

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.

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.

cog talk5 rio tiler tilebench

Tilebench Viz user interface.

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!

What we're doing.

Latest