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