Skip to main content

Visualize Cloud Optimized GeoTIFF in browser

Project description


A Rasterio plugin to visualize Cloud Optimized GeoTIFF in browser.

Test Coverage Package version Downloads


You can install rio-viz using pip

$ pip install rio-viz

with 3d feature

# 3d visualization features is optional
$ pip install -U pip
$ pip install rio-viz["mvt"]

Build from source

$ git clone
$ cd rio-viz
$ pip install -e .


$ rio viz --help
Usage: rio viz [OPTIONS] SRC_PATH

  Rasterio Viz cli.

  --nodata NUMBER|nan  Set nodata masking values for input dataset.
  --minzoom INTEGER    Overwrite minzoom
  --maxzoom INTEGER    Overwrite maxzoom
  --port INTEGER       Webserver port (default: 8080)
  --host TEXT          Webserver host url (default:
  --no-check           Ignore COG validation
  --reader TEXT        rio-tiler Reader (BaseReader). Default is ``
  --layers TEXT        limit to specific layers (only used for MultiBand and MultiBase Readers). (e.g --layers b1 --layers b2).
  --server-only        Launch API without opening the rio-viz web-page.
  --config NAME=VALUE  GDAL configuration options.
  --help               Show this message and exit.

Multi Reader support

rio-viz support multiple/custom reader as long they are subclass of

# Multi Files as Bands
$ rio viz "cog_band{2,3,4}.tif" --reader

# Simple Mosaic
$ rio viz "tests/fixtures/mosaic_cog{1,2}.tif" --reader

# MultiBandReader
# Landsat 8 - rio-tiler-pds
# We use `--layers` to limit the number of bands
$ rio viz LC08_L1TP_013031_20130930_20170308_01_T1 \
  --reader \
  --layers B1,B2 \

# MultiBaseReader
# We use `--layers` to limit the number of assets
rio viz \
  --reader \
  --layers B04,B03,B02


When launching rio-viz, the application will create a FastAPI application to access and read the data you want. By default the CLI will open a web-page for you to explore your file but you can use --server-only option to ignore this.

$ rio viz my.tif --server-only

# In another console
$ curl | jq
  "bounds": [6.608576517072109, 51.270642883468895, 11.649386808679436, 53.89267160832534],
  "band_metadata": [...],
  "band_descriptions": [...],
  "dtype": "uint8",
  "nodata_type": "Mask",
  "colorinterp": [

You can see the full API documentation over

API documentation

In Notebook environment

Thanks to the awesome server-thread we can use rio-viz application in Notebook environment.

import time

import httpx
from folium import Map, TileLayer

from import Client

# Create rio-viz Client (using server-thread to launch backgroud task)
client = Client("")

# Gives some time for the server to setup

r = httpx.get(
    params = {
        "rescale": "1600,2000",  # from the info endpoint
        "colormap_name": "terrain",

bounds = r["bounds"]
m = Map(
    location=((bounds[1] + bounds[3]) / 2,(bounds[0] + bounds[2]) / 2),

aod_layer = TileLayer(

3D (Experimental)

rio-viz supports Mapbox VectorTiles encoding from a raster array. This feature was added to visualize sparse data stored as raster but will also work for dense array. This is highly experimental and might be slow to render in certain browser and/or for big rasters.


Ready to use docker image can be found on Github registry.

docker run \
  --volume "$PWD":/data \
  --platform linux/amd64 \
  --rm -it -p 8080:8080 \
  rio viz --host /data/your-file.tif


  • --platform linux/amd64 is only needed if you are using latest MacOS M1 machines
  • --volume "$PWD":/data is needed to mount your local directory to the docker image
  • rio-viz's option --host is required to access the web server

Contribution & Development



Created by Development Seed





Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

rio_viz-0.12.1.tar.gz (46.8 kB view hashes)

Uploaded source

Built Distribution

rio_viz-0.12.1-py3-none-any.whl (43.5 kB view hashes)

Uploaded py3

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page