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.
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.
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
- 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.
rio-cogeo
- 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.
morecantile
- 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).
rio-viz
- 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.
tilebench
- 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!
What we're doing.
Latest