1Reading Datasets
2================
3
4.. todo::
5
6    * Discuss and/or link to topics
7        - supported formats, drivers
8        - vsi
9        - tags
10        - profile
11        - crs
12        - transforms
13        - dtypes
14
15
16Dataset objects provide read, read-write, and write access to raster data files
17and are obtained by calling ``rasterio.open()``. That function mimics Python's
18built-in ``open()`` and the dataset objects it returns mimic Python ``file``
19objects.
20
21.. code-block:: python
22
23    >>> import rasterio
24    >>> src = rasterio.open('tests/data/RGB.byte.tif')
25    >>> src
26    <open DatasetReader name='tests/data/RGB.byte.tif' mode='r'>
27    >>> src.name
28    'tests/data/RGB.byte.tif'
29    >>> src.mode
30    'r'
31    >>> src.closed
32    False
33
34If you try to access a nonexistent path, ``rasterio.open()`` does the same
35thing as ``open()``, raising an exception immediately.
36
37.. code-block:: python
38
39    >>> open('/lol/wut.tif')
40    Traceback (most recent call last):
41     ...
42    FileNotFoundError: [Errno 2] No such file or directory: '/lol/wut.tif'
43    >>> rasterio.open('/lol/wut.tif')
44    Traceback (most recent call last):
45     ...
46    rasterio.errors.RasterioIOError: No such file or directory
47
48Datasets generally have one or more bands (or layers). Following the GDAL
49convention, these are indexed starting with the number 1. The first band of
50a file can be read like this:
51
52.. code-block:: python
53
54    >>> array = src.read(1)
55    >>> array.shape
56    (718, 791)
57
58The returned object is a 2-dimensional Numpy ndarray. The representation of
59that array at the Python prompt is a summary; the GeoTIFF file that
60Rasterio uses for testing has 0 values in the corners, but has nonzero values
61elsewhere.
62
63.. code-block:: python
64
65    >>> from matplotlib import pyplot
66    >>> pyplot.imshow(array, cmap='pink')
67    <matplotlib.image.AxesImage object at 0x...>
68    >>> pyplot.show()  # doctest: +SKIP
69
70
71.. image:: http://farm6.staticflickr.com/5032/13938576006_b99b23271b_o_d.png
72
73Instead of reading single bands, all bands of the input dataset can be read into
74a 3-dimensonal ndarray. Note that the interpretation of the 3 axes is
75``(bands, rows, columns)``. See
76:ref:`imageorder` for more details on how to convert to the ordering expected by
77some software.
78
79.. code-block:: python
80
81    >>> array = src.read()
82    >>> array.shape
83    (3, 718, 791)
84
85
86In order to read smaller chunks of the dataset, refer to :ref:`windowrw`.
87
88
89The indexes, Numpy data types, and nodata values of all a dataset's bands can
90be had from its ``indexes``, ``dtypes``, and ``nodatavals`` attributes.
91
92.. code-block:: python
93
94    >>> for i, dtype, nodataval in zip(src.indexes, src.dtypes, src.nodatavals):
95    ...     print(i, dtype, nodataval)
96    ...
97    1 uint8 0.0
98    2 uint8 0.0
99    3 uint8 0.0
100
101To close a dataset, call its ``close()`` method.
102
103.. code-block:: python
104
105    >>> src.close()
106    >>> src
107    <closed DatasetReader name='tests/data/RGB.byte.tif' mode='r'>
108
109After it's closed, data can no longer be read.
110
111.. code-block:: python
112
113    >>> src.read(1)
114    Traceback (most recent call last):
115     ...
116    ValueError: can't read closed raster file
117
118This is the same behavior as Python's ``file``.
119
120.. code-block:: python
121
122    >>> f = open('README.rst')
123    >>> f.close()
124    >>> f.read()
125    Traceback (most recent call last):
126     ...
127    ValueError: I/O operation on closed file.
128
129As Python ``file`` objects can, Rasterio datasets can manage the entry into
130and exit from runtime contexts created using a ``with`` statement. This
131ensures that files are closed no matter what exceptions may be raised within
132the the block.
133
134.. code-block:: python
135
136    >>> with rasterio.open('tests/data/RGB.byte.tif', 'r') as one:
137    ...     with rasterio.open('tests/data/RGB.byte.tif', 'r') as two:
138    ...         print(two)
139    ...     print(one)
140    ...     raise Exception("an error occurred")
141    ...
142    <open DatasetReader name='tests/data/RGB.byte.tif' mode='r'>
143    <open DatasetReader name='tests/data/RGB.byte.tif' mode='r'>
144    Traceback (most recent call last):
145      File "<stdin>", line 5, in <module>
146    Exception: an error occurred
147    >>> print(two)
148    <closed DatasetReader name='tests/data/RGB.byte.tif' mode='r'>
149    >>> print(one)
150    <closed DatasetReader name='tests/data/RGB.byte.tif' mode='r'>
151
152Format-specific dataset reading options may be passed as keyword arguments. For
153example, to turn off all types of GeoTIFF georeference except that within the
154TIFF file's keys and tags, pass `GEOREF_SOURCES='INTERNAL'`.
155
156.. code-block:: python
157
158    >>> with rasterio.open('tests/data/RGB.byte.tif', GEOREF_SOURCES='INTERNAL') as dataset:
159    ...     # .aux.xml, .tab, .tfw sidecar files will be ignored.
160
161