User friendly Rasterio plugin to read raster datasets

9.0.6 · active · verified Thu Apr 16

rio-tiler is an active Python library that provides a user-friendly plugin for Rasterio, designed to read raster datasets efficiently. It acts as a wrapper around Rasterio and GDAL, facilitating dynamic slippy map tile creation and comprehensive data reading from various sources, including local files, HTTP, AWS S3, and Google Cloud Storage. The library is currently at version 9.0.6 and maintains a frequent release cadence, with both minor and major versions introducing new features and breaking changes.

Common errors

```
CPLE_AppDefinedError: Failed to connect to 169.254.169.254 port 80: Connection refused (or similar network connection error when using old `rio_tiler.sentinel2` module)
```
cause Attempting to use deprecated mission-specific modules (like `rio_tiler.sentinel2`) which might try to access old or removed public dataset URLs, or misconfigured AWS access for requester-pays buckets.

fix For public datasets, use the `rio-tiler-pds` plugin. For generic COGs, use `rio_tiler.io.Reader`. Ensure `AWS_REQUEST_PAYER='requester'` is set in the environment if accessing requester-pays S3 buckets.
```
AttributeError: 'COGReader' object has no attribute 'tile' (or similar method missing from COGReader)
```
cause This error typically occurs when using code written for rio-tiler versions prior to 4.0, where the main class was `COGReader`, but in a v4.0+ environment where it has been renamed to `Reader` and its methods might have changed or been reorganized.

fix Update your code to import `Reader` from `rio_tiler.io` and adjust method calls if necessary, following the v4.0 migration guide.
```
ValueError: Dataset does not have rioxarray spatial dimensions (or 'Dataset does not have rioxarray bounds')
```
cause When using `rio_tiler.io.XarrayReader`, the input `xarray.DataArray` or `xarray.Dataset` must have a defined Coordinate Reference System (CRS) and spatial dimensions (X, Y or longitude, latitude) along with their bounds.

fix Ensure your xarray object has proper geospatial metadata, including `crs`, `x_dim`, `y_dim`, and `bounds`. You might need to use `rioxarray` to add or verify these attributes before passing the data to `XarrayReader`.

Warnings

breaking The primary reader class `COGReader` was renamed to `Reader` in rio-tiler v4.0. Additionally, the `rio_tiler.io.cogeo` submodule was deprecated in favor of `rio_tiler.io.rasterio` (though `Reader` is directly importable from `rio_tiler.io`).
Fix: Update imports from `from rio_tiler.io.cogeo import COGReader` to `from rio_tiler.io import Reader` or `from rio_tiler.io.rasterio import Reader`.
breaking Support for Python 3.7 was removed in rio-tiler v4.0. Support for Python 3.9 and 3.10 was removed in v9.0.0.
Fix: Upgrade your Python environment to Python 3.11 or newer.
breaking In rio-tiler v4.0, band names returned by methods like `.statistics()` or `.info()` are now prefixed with 'b' (e.g., 'b1', 'b2') instead of just the band number ('1', '2').
Fix: Adjust code that accesses band names or metadata to expect the 'b' prefix.
breaking The way assets are specified in `STACReader`'s methods (e.g., `tile`) changed in v9.0.0b1. Instead of a string format like `"asset|indexes=1,2,3"`, it now requires a dictionary format: `{"name": "asset", "indexes": [1, 2, 3]}`.
Fix: Refactor `STACReader` asset parameter usage to pass a list of dictionaries.
gotcha Reading from non-Cloud Optimized GeoTIFF (COG) raster formats (e.g., JPEG2000 Sentinel-2 data on AWS) can be inefficient due to numerous GET requests and large data transfers, impacting performance and cost.
Fix: Prefer using Cloud Optimized GeoTIFFs (COGs) for optimal performance, especially with cloud-hosted data. If using non-COGs, be aware of potential performance implications.
gotcha Accessing data from 'requester-pays' S3 buckets (e.g., some public datasets like Sentinel-2 on AWS) will fail with 'Failed to connect' or similar errors if not configured correctly.
Fix: Set the `AWS_REQUEST_PAYER` environment variable to `"requester"` before making requests: `os.environ['AWS_REQUEST_PAYER'] = 'requester'`.

Install

pip install rio-tiler Install rio-tiler
pip install rio-tiler[xarray] Install with Xarray support (optional)

Imports

Reader
wrong:
```
from rio_tiler.io.cogeo import COGReader
```
correct:
```
from rio_tiler.io import Reader
```
The primary `COGReader` class was renamed to `Reader` in rio-tiler v4.0 and moved to `rio_tiler.io`.
STACReader
```
from rio_tiler.io import STACReader
```
Used for reading data from STAC (SpatioTemporal Asset Catalog) items.
XarrayReader
```
from rio_tiler.io import XarrayReader
```
Used for reading xarray DataArray objects. Requires `rio-tiler[xarray]` installation.
render
```
from rio_tiler.utils import render
```
Utility function for rendering tile data to image formats (e.g., PNG, JPEG).
cmap
```
from rio_tiler.colormap import cmap
```
Provides access to default and custom colormaps for rendering.

Quickstart

This quickstart demonstrates how to use the `rio_tiler.io.Reader` class to open a Cloud Optimized GeoTIFF (COG) from a URL, extract a specific Web Mercator tile (x, y, z), and then render it into a PNG image. The `ImageData` object returned by `tile()` contains both the raster data and its mask.

import os
from rio_tiler.io import Reader
from rio_tiler.utils import render

# Example Cloud Optimized GeoTIFF (COG) URL
# This URL is publicly available for testing
COG_URL = "https://sentinel-cogs.s3.amazonaws.com/sentinel-s2-l2a-cogs/29/R/KH/2020/2/S2A_29RKH_20200219_0_L2A/B04.tif"

# Define a tile (x, y, z) - example from documentation
x, y, z = 239, 220, 9

try:
    with Reader(COG_URL) as src:
        # Read a Web Mercator tile
        img = src.tile(x, y, z)

        # ImageData object holds the data (img.data) and mask (img.mask)
        print(f"Tile shape: {img.data.shape}") # e.g., (1, 256, 256) for a single band
        print(f"Mask shape: {img.mask.shape}") # e.g., (256, 256)

        # Render the tile to a PNG buffer
        buffer = img.render(img_format="PNG")

        # Save the buffer to a file
        output_filename = "output_tile.png"
        with open(output_filename, "wb") as f:
            f.write(buffer)
        print(f"Tile saved to {output_filename}")

except Exception as e:
    print(f"An error occurred: {e}")
    print("Ensure the COG_URL is accessible and GDAL is configured correctly.")
    # For AWS S3 requester-pays buckets, you might need: os.environ['AWS_REQUEST_PAYER'] = 'requester'

view raw JSON →