rasterio/README.rst

Rasterio
========

Rasterio reads and writes geospatial raster datasets.

.. image:: https://travis-ci.org/mapbox/rasterio.png?branch=master
   :target: https://travis-ci.org/mapbox/rasterio

Rasterio employs GDAL under the hood for file I/O and raster formatting. Its
functions typically accept and return Numpy ndarrays. Rasterio is designed to
make working with geospatial raster data more productive and more fun.

Example
-------

Here's an example of the basic features rasterio provides. Three bands are
read from an image and summed to produce something like a panchromatic band.
This new band is then written to a new single band TIFF.

.. code-block:: python

    import numpy
    import rasterio
    import subprocess
    
    # Register format drivers with a context manager
    
    with rasterio.drivers():
        
        # Read raster bands directly to Numpy arrays.
        #
        with rasterio.open('rasterio/tests/data/RGB.byte.tif') as src:
            b, g, r = map(src.read_band, (1, 2, 3))
        
        # Combine arrays in place. Expecting that the sum will 
        # temporarily exceed the 8-bit integer range, initialize it as
        # 16-bit. Adding other arrays to it in-place converts those
        # arrays "up" and preserves the type of the total array.

        total = numpy.zeros(r.shape, dtype=rasterio.uint16)
        for band in r, g, b:
            total += band
        total /= 3
        assert total.dtype == rasterio.uint16

        # Write the product as a raster band to a new 8-bit file. For
        # keyword arguments, 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.

        kwargs = src.meta
        kwargs.update(
            dtype=rasterio.uint8,
            count=1,
            compress='lzw')
        
        with rasterio.open('example-total.tif', 'w', **kwargs) as dst:
            dst.write_band(1, total.astype(rasterio.uint8))

    # At the end of the ``with rasterio.drivers()`` block, context
    # manager exits and all drivers are de-registered.

    # Dump out gdalinfo's report card and open the image.
    
    info = subprocess.check_output(
        ['gdalinfo', '-stats', 'example-total.tif'])
    print(info)
    subprocess.call(['open', 'example-total.tif'])

.. image:: http://farm6.staticflickr.com/5501/11393054644_74f54484d9_z_d.jpg
   :width: 640
   :height: 581

The rasterio.drivers() function and context manager are new in 0.5. The example
above shows the way to use it to register and de-register drivers in
a deterministic and efficient way. Code written for rasterio 0.4 will continue
to work: opened raster datasets may manage the global driver registry if no
other manager is present.

Simple access is provided to properties of a geospatial raster file.

.. code-block:: python
    
    with rasterio.drivers():

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

    # Output:
    # (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]

Rasterio also affords conversion of GeoTIFFs, on copy, to other formats.

.. code-block:: python
    
    with rasterio.drivers():

        rasterio.copy(
            'example-total.tif',
            'example-total.jpg', 
            driver='JPEG')
    
    subprocess.call(['open', 'example-total.jpg'])

rio_insp
--------

The rio_insp program opens the hood of any raster dataset so you can poke
around using Python.

.. code-block:: console

    $ rio_insp rasterio/tests/data/RGB.byte.tif
    Rasterio 0.8 Interactive Inspector (Python 3.3.5)
    Type "src.meta", "src.read_band(1)", or "help(src)" for more information.
    >>> src.name
    'rasterio/tests/data/RGB.byte.tif'
    >>> src.shape
    (718, 791)
    >>> import pprint
    >>> pprint.pprint(src.crs)
    {u'ellps': u'WGS84',
    u'no_defs': True,
    u'proj': u'utm',
    u'units': u'm',
    u'zone': 18}
    >>> b = src.read_band(1)
    >>> b
    array([[0, 0, 0, ..., 0, 0, 0],
           [0, 0, 0, ..., 0, 0, 0],
           [0, 0, 0, ..., 0, 0, 0],
           ...,
           [0, 0, 0, ..., 0, 0, 0],
           [0, 0, 0, ..., 0, 0, 0],
           [0, 0, 0, ..., 0, 0, 0]], dtype=uint8)
    >>> b.min(), b.max(), b.mean()
    (0, 255, 29.94772668847656)

Dependencies
------------

C library dependecies:

- GDAL

Python package dependencies (see also requirements.txt):

- affine
- Numpy
- setuptools

Development also requires (see requirements-dev.txt)

- Cython
- pytest

Installation
------------

Rasterio is a C extension and to install on Linux or OS X you'll need a working
compiler (XCode on OS X etc). Unofficial Windows binary packages created by
Christoph Gohlke are available `here
<http://www.lfd.uci.edu/~gohlke/pythonlibs/#rasterio>`_.

To install from the source distribution on PyPI, do the following:

.. code-block:: console

    $ pip install -r https://raw.github.com/mapbox/rasterio/master/requirements.txt
    $ pip install rasterio

To install from a forked repo, do this (in a virtualenv, preferably):

.. code-block:: console

    $ pip install -r requirements-dev.txt
    $ pip install -e .

The Numpy headers are required to run the rasterio setup script. Numpy has to
be installed (via the indicated requirements file) before rasterio can be
installed. See rasterio's Travis `configuration
<https://github.com/mapbox/rasterio/blob/master/.travis.yml>`__ for more
guidance.

Testing
-------

From the repo directory, run py.test

.. code-block:: console

    $ py.test

Documentation
-------------

See https://github.com/mapbox/rasterio/tree/master/docs.

License
-------

See LICENSE.txt

Authors
-------

See AUTHORS.txt

Changes
-------

See CHANGES.txt