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