1Migrating to Rasterio 1.0 2========================= 3 4 5affine.Affine() vs. GDAL-style geotransforms 6-------------------------------------------- 7 8One of the biggest API changes on the road to Rasterio 1.0 is the full 9deprecation of GDAL-style geotransforms in favor of the `affine 10<https://github.com/sgillies/affine>`__ library. For reference, an 11``affine.Affine()`` looks like: 12 13.. code-block:: python 14 15 affine.Affine(a, b, c, 16 d, e, f) 17 18and a GDAL geotransform looks like: 19 20.. code-block:: python 21 22 (c, a, b, f, d, e) 23 24Fundamentally these two constructs provide the same information, but the 25``Affine()`` object is more useful. 26 27Here's a history of this feature: 28 291. Originally, functions with a ``transform`` argument expected a GDAL 30 geotransform. 312. The introduction of the `affine <https://github.com/sgillies/affine>`__ 32 library involved creating a temporary ``affine`` argument for 33 ``rasterio.open()`` and a ``src.affine`` property. Users could pass an 34 ``Affine()`` to ``affine`` or ``transform``, but a GDAL geotransform passed 35 to ``transform`` would issue a deprecation warning. 363. ``src.transform`` remained a GDAL geotransform, but issued a warning. Users 37 were pointed to ``src.affine`` during the transition phase. 384. Since the above changes, several functions have been added to Rasterio that 39 accept a ``transform`` argument. Rather than add an ``affine`` argument to 40 each, the ``transform`` argument could be either an ``Affine()`` object or a 41 GDAL geotransform, the latter issuing the same deprecation warning. 42 43The original plan was to remove the ``affine`` argument + property, and assume 44that the object passed to ``transform`` is an ``Affine()``. 45However, after `further discussion 46<https://github.com/mapbox/rasterio/pull/763>`__ it was determined that 47since ``Affine()`` and GDAL geotransforms are both 6 element tuples users may 48experience unexplained errors and outputs, so an exception is raised instead to 49better highlight the error. 50 51Before 1.0b1: 52 53* ``rasterio.open()`` will still accept ``affine`` and ``transform``, but the 54 former now issues a deprecation warning and the latter raises an exception if 55 it does not receive an ``Affine()``. 56* If ``rasterio.open()`` receives both ``affine`` and ``transform`` a warning 57 is issued and ``transform`` is used. 58* ``src.affine`` remains but issues a deprecation warning. 59* ``src.transform`` returns an ``Affine()``. 60* All other Rasterio functions with a ``transform`` argument now raise an 61 exception if they receive a GDAL geotransform. 62 63Tickets 64``````` 65* `#86 <https://github.com/mapbox/rasterio/issues/86>`__ - Announcing the 66 plan to switch from GDAL geotransforms to ``Affine()``. 67* `#763 <https://github.com/mapbox/rasterio/pull/763>`__ - Implementation of the 68 migration and some further discussion. 69 70 Beginning in 1.0b1: 71 72* In ``rasterio.open`` "affine" will no longer be an alias for the 73 transform keyword argument. 74* Dataset objects will no longer have an affine property. 75* The transform keyword argument and property is always an instance of the 76 ``Affine`` class. 77 78 79I/O Operations 80~~~~~~~~~~~~~~ 81 82Methods related to reading band data and dataset masks have changed in 1.0. 83 84Beginning with version 1.0b1, there is no longer a ``read_mask`` method, only 85``read_masks``. Datasets may be opened in read-write "w+" mode when their 86formats allow and a warning will be raised when band data or masks are read 87from datasets opened in "w" mode. 88 89Beginning with 1.0.0, the "w" mode will become write-only and reading data or 90masks from datasets opened in "w" will be prohibited. 91 92 93Deprecated: ``rasterio.drivers()`` 94---------------------------------- 95 96Previously users could register GDAL's drivers and open a datasource with: 97 98.. code-block:: python 99 100 import rasterio 101 102 with rasterio.drivers(): 103 104 with rasterio.open('tests/data/RGB.byte.tif') as src: 105 pass 106 107but Rasterio 1.0 contains more interactions with GDAL's environment, so 108``rasterio.drivers()`` has been replaced with: 109 110.. code-block:: python 111 112 import rasterio 113 import rasterio.env 114 115 with rasterio.Env(): 116 117 with rasterio.open('tests/data/RGB.byte.tif') as src: 118 pass 119 120Tickets 121``````` 122 123* `#665 <https://github.com/mapbox/rasterio/pull/665>`__ - Deprecation of 124 ``rasterio.drivers()`` and introduction of ``rasterio.Env()``. 125 126Removed: ``src.read_band()`` 127~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 128 129The ``read_band()`` method has been replaced by ``read()``, which allows for 130faster I/O and reading multiple bands into a single ``numpy.ndarray()``. 131 132For example: 133 134.. code-block:: python 135 136 import numpy as np 137 import rasterio 138 139 with rasterio.open('tests/data/RGB.byte.tif') as src: 140 data = np.array(map(src.read_band, (1, 2, 3))) 141 band1 = src.read_band(1) 142 143is now: 144 145.. code-block:: python 146 147 import rasterio 148 149 with rasterio.open('tests/data/RGB.byte.tif') as src: 150 data = src.read((1, 2, 3)) 151 band1 = src.read(1) 152 153Tickets 154``````` 155 156* `# 83 <https://github.com/mapbox/rasterio/issues/83>`__ - Introduction of 157 ``src.read()``. 158* `#96 <https://github.com/mapbox/rasterio/issues/96>`__, 159 `#284 <https://github.com/mapbox/rasterio/pull/284>`__ - Deprecation of 160 ``src.read_band()``. 161 162 163Removed: ``src.read_mask()`` 164~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 165 166The ``src.read_mask()`` method produced a single mask for the entire datasource, 167but could not handle producing a single mask per band, so it was deprecated in 168favor of ``src.read_masks()``, although it has no direct replacement. 169 170Tickets 171``````` 172 173* `#284 <https://github.com/mapbox/rasterio/pull/284>`__ - Deprecation of 174 ``src.read_mask()``. 175 176 177Moved: Functions for working with dataset windows 178------------------------------------------------- 179 180Several functions in the top level ``rasterio`` namespace for working with 181dataset windows have been moved to ``rasterio.windows.*``: 182 183* ``rasterio.get_data_window()`` 184* ``rasterio.window_union()`` 185* ``rasterio.window_intersection()`` 186* ``rasterio.windows_intersect()`` 187 188Tickets 189``````` 190 191* `#609 <https://github.com/mapbox/rasterio/pull/609>`__ - Introduction of 192 ``rasterio.windows``. 193 194 195Moved: ``rasterio.tool`` 196------------------------ 197 198This module has been removed completely and its contents have been moved to 199several different locations: 200 201.. code-block:: 202 203 rasterio.tool.show() -> rasterio.plot.show() 204 rasterio.tool.show_hist() -> rasterio.plot.show_hist() 205 rasterio.tool.stats() -> rasterio.rio.insp.stats() 206 rasterio.tool.main() -> rasterio.rio.insp.main() 207 208Tickets 209``````` 210 211* `#609 <https://github.com/mapbox/rasterio/pull/609>`__ - Deprecation of 212 ``rasterio.tool``. 213 214 215Moved: ``rasterio.tools`` 216------------------------- 217 218This module has been removed completely and its contents have been moved to 219several different locations: 220 221.. code-block:: 222 223 rasterio.tools.mask.mask() -> rasterio.mask.mask() 224 rasterio.tools.merge.merge() -> rasterio.merge.merge() 225 226Tickets 227``````` 228 229* `#609 <https://github.com/mapbox/rasterio/pull/609>`__ - Deprecation of 230 ``rasterio.tools``. 231 232 233Removed: ``rasterio.warp.RESAMPLING`` 234------------------------------------- 235 236This enum has been replaced by ``rasterio.warp.Resampling``. 237 238Removed: dataset's ``ul()`` method 239---------------------------------- 240 241This method has been replaced by the ``xy()`` method. 242 243Signature Changes 244----------------- 245 246For both ``rasterio.features.sieve()`` and ``rasterio.features.rasterize()`` the 247``output`` argument has been replaced with ``out``. Previously the use of 248``output`` issued a deprecation warning. 249 250Deprecation of dataset property set_* and get_* methods 251------------------------------------------------------- 252 253Methods get_crs, set_crs, set_nodatavals, set_descriptions, set_units, and 254set_gcps are deprecated and will be removed in version 1.0. They have been 255replaced by fully settable dataset properties `crs`, `nodatavals`, 256`descriptions`, `units`, and `gcps`. 257 258In the cases of units and descriptions, set_band_unit and set_band_description 259methods remain to support the rio-edit-info command. 260 261Creation Options 262---------------- 263 264Rasterio no longer saves dataset creation options to the metadata of created 265datasets and will ignore such metadata starting in version 1.0. Users may opt 266in to this by setting RIO_IGNORE_CREATION_KWDS=TRUE in their environments. 267