{"id":7678,"library":"rio-tiler","title":"User friendly Rasterio plugin to read raster datasets","description":"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.","status":"active","version":"9.0.6","language":"en","source_language":"en","source_url":"https://github.com/cogeotiff/rio-tiler","tags":["geospatial","raster","tiling","cloud-optimized-geotiff","GDAL","Rasterio","STAC","remote-sensing"],"install":[{"cmd":"pip install rio-tiler","lang":"bash","label":"Install rio-tiler"},{"cmd":"pip install rio-tiler[xarray]","lang":"bash","label":"Install with Xarray support (optional)"}],"dependencies":[{"reason":"Core dependency for raster data I/O.","package":"rasterio"},{"reason":"Underlying geospatial library, required by Rasterio.","package":"GDAL"},{"reason":"Used for TileMatrixSet (TMS) grids, enabling support for various projections.","package":"morecantile","optional":true},{"reason":"Required for Python versions < 3.15.","package":"typing-extensions","optional":true},{"reason":"Optional dependency for the XarrayReader, to work with xarray DataArray objects.","package":"xarray","optional":true}],"imports":[{"note":"The primary `COGReader` class was renamed to `Reader` in rio-tiler v4.0 and moved to `rio_tiler.io`.","wrong":"from rio_tiler.io.cogeo import COGReader","symbol":"Reader","correct":"from rio_tiler.io import Reader"},{"note":"Used for reading data from STAC (SpatioTemporal Asset Catalog) items.","symbol":"STACReader","correct":"from rio_tiler.io import STACReader"},{"note":"Used for reading xarray DataArray objects. Requires `rio-tiler[xarray]` installation.","symbol":"XarrayReader","correct":"from rio_tiler.io import XarrayReader"},{"note":"Utility function for rendering tile data to image formats (e.g., PNG, JPEG).","symbol":"render","correct":"from rio_tiler.utils import render"},{"note":"Provides access to default and custom colormaps for rendering.","symbol":"cmap","correct":"from rio_tiler.colormap import cmap"}],"quickstart":{"code":"import os\nfrom rio_tiler.io import Reader\nfrom rio_tiler.utils import render\n\n# Example Cloud Optimized GeoTIFF (COG) URL\n# This URL is publicly available for testing\nCOG_URL = \"https://sentinel-cogs.s3.amazonaws.com/sentinel-s2-l2a-cogs/29/R/KH/2020/2/S2A_29RKH_20200219_0_L2A/B04.tif\"\n\n# Define a tile (x, y, z) - example from documentation\nx, y, z = 239, 220, 9\n\ntry:\n    with Reader(COG_URL) as src:\n        # Read a Web Mercator tile\n        img = src.tile(x, y, z)\n\n        # ImageData object holds the data (img.data) and mask (img.mask)\n        print(f\"Tile shape: {img.data.shape}\") # e.g., (1, 256, 256) for a single band\n        print(f\"Mask shape: {img.mask.shape}\") # e.g., (256, 256)\n\n        # Render the tile to a PNG buffer\n        buffer = img.render(img_format=\"PNG\")\n\n        # Save the buffer to a file\n        output_filename = \"output_tile.png\"\n        with open(output_filename, \"wb\") as f:\n            f.write(buffer)\n        print(f\"Tile saved to {output_filename}\")\n\nexcept Exception as e:\n    print(f\"An error occurred: {e}\")\n    print(\"Ensure the COG_URL is accessible and GDAL is configured correctly.\")\n    # For AWS S3 requester-pays buckets, you might need: os.environ['AWS_REQUEST_PAYER'] = 'requester'","lang":"python","description":"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."},"warnings":[{"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`.","message":"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`).","severity":"breaking","affected_versions":"4.0.0 and later"},{"fix":"Upgrade your Python environment to Python 3.11 or newer.","message":"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.","severity":"breaking","affected_versions":"4.0.0 and later (for Python 3.7), 9.0.0 and later (for Python 3.9, 3.10)"},{"fix":"Adjust code that accesses band names or metadata to expect the 'b' prefix.","message":"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').","severity":"breaking","affected_versions":"4.0.0 and later"},{"fix":"Refactor `STACReader` asset parameter usage to pass a list of dictionaries.","message":"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]}`.","severity":"breaking","affected_versions":"9.0.0b1 and later"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Set the `AWS_REQUEST_PAYER` environment variable to `\"requester\"` before making requests: `os.environ['AWS_REQUEST_PAYER'] = 'requester'`.","message":"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.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"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.","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.","error":"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)"},{"fix":"Update your code to import `Reader` from `rio_tiler.io` and adjust method calls if necessary, following the v4.0 migration guide.","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.","error":"AttributeError: 'COGReader' object has no attribute 'tile' (or similar method missing from COGReader)"},{"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`.","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.","error":"ValueError: Dataset does not have rioxarray spatial dimensions (or 'Dataset does not have rioxarray bounds')"}]}