Example

Here’s an example of some basic features that Rasterio provides. Three bands are read from an image and averaged to produce something like a panchromatic band. This new band is then written to a new single band TIFF.

import numpy as np
import rasterio

# Read raster bands directly to Numpy arrays.
#
with rasterio.open('tests/data/RGB.byte.tif') as src:
    r, g, b = src.read()

# Combine arrays in place. Expecting that the sum will
# temporarily exceed the 8-bit integer range, initialize it as
# a 64-bit float (the numpy default) array. Adding other
# arrays to it in-place converts those arrays "up" and
# preserves the type of the total array.
total = np.zeros(r.shape)
for band in r, g, b:
    total += band
total /= 3

# Write the product as a raster band to a new 8-bit file. For
# the new file's profile, we start with the meta attributes of
# the source file, but then change the band count to 1, set the
# dtype to uint8, and specify LZW compression.
profile = src.profile
profile.update(dtype=rasterio.uint8, count=1, compress='lzw')

with rasterio.open('example-total.tif', 'w', **profile) as dst:
    dst.write(total.astype(rasterio.uint8), 1)

The output:

API Overview

Rasterio gives access to properties of a geospatial raster file.

with rasterio.open('tests/data/RGB.byte.tif') as src:
    print(src.width, src.height)
    print(src.crs)
    print(src.transform)
    print(src.count)
    print(src.indexes)

# Printed:
# (791, 718)
# {u'units': u'm', u'no_defs': True, u'ellps': u'WGS84', u'proj': u'utm', u'zone': 18}
# Affine(300.0379266750948, 0.0, 101985.0,
#        0.0, -300.041782729805, 2826915.0)
# 3
# [1, 2, 3]

A rasterio dataset also provides methods for getting extended array slices given georeferenced coordinates.

with rasterio.open('tests/data/RGB.byte.tif') as src:
    print src.window(**src.window_bounds(((100, 200), (100, 200))))

# Printed:
# ((100, 200), (100, 200))

Rasterio CLI

Rasterio’s command line interface, named “rio”, is documented at cli.rst. Its rio insp command opens the hood of any raster dataset so you can poke around using Python.

$ rio insp tests/data/RGB.byte.tif
Rasterio 0.10 Interactive Inspector (Python 3.4.1)
Type "src.meta", "src.read(1)", or "help(src)" for more information.
>>> src.name
'tests/data/RGB.byte.tif'
>>> src.closed
False
>>> src.shape
(718, 791)
>>> src.crs
{'init': 'epsg:32618'}
>>> b, g, r = src.read()
>>> b
masked_array(data =
 [[-- -- -- ..., -- -- --]
 [-- -- -- ..., -- -- --]
 [-- -- -- ..., -- -- --]
 ...,
 [-- -- -- ..., -- -- --]
 [-- -- -- ..., -- -- --]
 [-- -- -- ..., -- -- --]],
             mask =
 [[ True  True  True ...,  True  True  True]
 [ True  True  True ...,  True  True  True]
 [ True  True  True ...,  True  True  True]
 ...,
 [ True  True  True ...,  True  True  True]
 [ True  True  True ...,  True  True  True]
 [ True  True  True ...,  True  True  True]],
       fill_value = 0)

>>> np.nanmin(b), np.nanmax(b), np.nanmean(b)
(0, 255, 29.94772668847656)

Installation

Please install Rasterio in a virtual environment so that its requirements don’t tamper with your system’s Python.

$ export CURL_CA_BUNDLE=/etc/ssl/certs/ca-certificates.crt

$ pip install -U pip
$ pip install GDAL-2.0.2-cp27-none-win32.whl
$ pip install rasterio-0.34.0-cp27-cp27m-win32.whl

$ conda install -c conda-forge rasterio

$ sudo add-apt-repository ppa:ubuntugis/ppa
$ sudo apt-get update
$ sudo apt-get install gdal-bin libgdal-dev
$ pip install -U pip
$ pip install rasterio

$ brew update
$ brew install gdal
$ pip install -U pip
$ pip install --no-use-wheel rasterio

$ python setup.py build_ext -I<path to gdal include files> -lgdal_i -L<path to gdal library>
$ python setup.py install

Support

The primary forum for questions about installation and usage of Rasterio is https://rasterio.groups.io/g/main. The authors and other users will answer questions when they have expertise to share and time to explain. Please take the time to craft a clear question and be patient about responses.

Please do not bring these questions to Rasterio’s issue tracker, which we want to reserve for bug reports and other actionable issues.

While Rasterio’s repo is in the Mapbox GitHub organization, Mapbox’s Support team is focused on customer support for its commercial platform and Rasterio support requests may be perfunctorily closed with or without a link to https://rasterio.groups.io/g/main. It’s better to bring questions directly to the main Rasterio group at groups.io.

Development and Testing

See CONTRIBUTING.rst.

Documentation

See docs/.

License

See LICENSE.txt.

Authors

See AUTHORS.txt.

Changes

See CHANGES.txt.

Who is Using Rasterio?

See here.