Merge branch 'master' into gdal-typedefs

README.rst

@@ -69,7 +69,7 @@ Rasterio gives access to properties of a geospatial raster file.
     with rasterio.open('tests/data/RGB.byte.tif') as src:
         print(src.width, src.height)
         print(src.crs)
-        print(src.affine)
+        print(src.transform)
         print(src.count)
         print(src.indexes)
 

benchmarks/ndarray.py

@@ -49,7 +49,7 @@
 # Rasterio
 s = """
 with rasterio.open('tests/data/RGB.byte.tif') as src:
-    transform = src.affine
+    transform = src.transform
     proj = src.crs
     wkt = src.crs_wkt
     arr = src.read(1, masked=False)

docs/concurrency.rst

@@ -70,8 +70,6 @@ Here is the program in examples/concurrent-cpu-bound.py.
                 # The destination will be tiled, and we'll "process" the tiles
                 # concurrently.
                 meta = src.meta
-                del meta['transform']
-                meta.update(affine=src.affine)
                 meta.update(blockxsize=256, blockysize=256, tiled='yes')
                 with rasterio.open(outfile, 'w', **meta) as dst:
 

docs/georeferencing.rst

@@ -63,9 +63,3 @@ a pixel's image coordinates are ``x, y`` and its world coordinates are
 
 The ``Affine`` class has some useful properties and methods
 described at https://github.com/sgillies/affine.
-
-Earlier versions of Rasterio had a ``transform`` attribute which was a 6-element
-tuple. This usage is deprecated, please see https://github.com/mapbox/rasterio/issues/86 for details. 
-In Rasterio 1.0, the value of a  ``transform`` attribute will be an instance
-of ``Affine`` and the ``affine`` attribute will remain as an alias.
-

docs/migrating-to-v1.rst

@@ -0,0 +1,231 @@
+Migrating to Rasterio 1.0
+=========================
+
+
+affine.Affine() vs. GDAL-style geotransforms
+--------------------------------------------
+
+One of the biggest API changes on the road to Rasterio 1.0 is the full
+deprecation of GDAL-style geotransforms in favor of the `affine
+<https://github.com/sgillies/affine>`__ library.  For reference, an
+``affine.Affine()`` looks like:
+
+.. code-block:: python
+
+    affine.Affine(a, b, c,
+                  d, e, f)
+
+and a GDAL geotransform looks like:
+
+.. code-block:: python
+
+    (c, a, b, f, d, e)
+
+Fundamentally these two constructs provide the same information, but the
+``Affine()`` object is much more useful.
+
+Here's a history of this feature:
+
+1. Originally, functions with a ``transform`` argument expected a GDAL
+   geotransform.
+2. The introduction of the `affine <https://github.com/sgillies/affine>`__
+   library involved creating a temporary ``affine`` argument for
+   ``rasterio.open()`` and a ``src.affine`` property.  Users could pass an
+   ``Affine()`` to ``affine`` or ``transform``, but a GDAL geotransform passed
+   to ``transform`` would issue a deprecation warning.
+3. ``src.transform`` remained a GDAL geotransform, but issued a warning.  Users
+   were pointed to ``src.affine`` during the transition phase.
+4. Since the above changes, several functions have been added to Rasterio that
+   accept a ``transform`` argument.  Rather than add an ``affine`` argument to
+   each, the ``transform`` argument could be either an ``Affine()`` object or a
+   GDAL geotransform, the latter issuing the same deprecation warning.
+
+The original plan was to remove the ``affine`` argument + property, and assume
+that the object passed to ``transform`` is an ``Affine()``.
+However, after `further discussion
+<https://github.com/mapbox/rasterio/pull/763>`__ it was determined that
+since ``Affine()`` and GDAL geotransforms are both 6 element tuples users may
+experience unexplained errors and outputs, so an exception is raised instead to
+better highlight the error.
+
+Moving forward:
+
+* ``rasterio.open()`` will still accept ``affine`` and ``transform``, but the
+  former now issues a deprecation warning and the latter raises an exception if
+  it does not receive an ``Affine()``.
+* If ``rasterio.open()`` receives both ``affine`` and ``transform`` a warning
+  is issued and ``transform`` is used.
+* ``src.affine`` remains but issues a deprecation warning.
+* ``src.transform`` returns an ``Affine()``.
+* All other Rasterio functions with a ``transform`` argument now raise an
+  exception if they receive a GDAL geotransform.
+
+The features mentioned above that issue a deprecation warning will eventually
+be removed, but a timeline has not yet been developed.
+
+Tickets
+```````
+* `#86 <https://github.com/mapbox/rasterio/issues/86>`__ - Announcing the
+  plan to switch from GDAL geotransforms to ``Affine()``.
+* `#763 <https://github.com/mapbox/rasterio/pull/763>`__ - Implementation of the
+  migration and some further discussion.
+
+
+I/O Operations
+--------------
+
+Methods related to reading band data and dataset masks have changed in 1.0.
+
+
+Deprecated: ``rasterio.drivers()``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Previously users could register GDAL's drivers and open a datasource with:
+
+.. code-block:: python
+
+    import rasterio
+
+    with rasterio.drivers():
+
+        with rasterio.open('tests/data/RGB.byte.tif') as src:
+            pass
+
+but Rasterio 1.0 contains more interactions with GDAL's environment, so
+``rasterio.drivers()`` has been replaced with:
+
+.. code-block:: python
+
+    import rasterio
+    import rasterio.env
+
+    with rasterio.Env():
+
+        with rasterio.open('tests/data/RGB.byte.tif') as src:
+            pass
+
+Tickets
+```````
+
+* `#665 <https://github.com/mapbox/rasterio/pull/665>`__ - Deprecation of
+  ``rasterio.drivers()`` and introduction of ``rasterio.Env()``.
+
+Removed: ``src.read_band()``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The ``read_band()`` method has been replaced by ``read()``, which allows for
+faster I/O and reading multiple bands into a single ``numpy.ndarray()``.
+
+For example:
+
+.. code-block:: python
+
+    import numpy as np
+    import rasterio
+
+    with rasterio.open('tests/data/RGB.byte.tif') as src:
+        data = np.array(map(src.read_band, (1, 2, 3)))
+        band1 = src.read_band(1)
+
+is now:
+
+.. code-block:: python
+
+    import rasterio
+
+    with rasterio.open('tests/data/RGB.byte.tif') as src:
+        data = src.read((1, 2, 3))
+        band1 = src.read(1)
+
+Tickets
+```````
+
+* `# 83 <https://github.com/mapbox/rasterio/issues/83>`__ - Introduction of
+  ``src.read()``.
+* `#96 <https://github.com/mapbox/rasterio/issues/96>`__,
+  `#284 <https://github.com/mapbox/rasterio/pull/284>`__ - Deprecation of
+  ``src.read_band()``.
+
+
+Removed: ``src.read_mask()``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The ``src.read_mask()`` method produced a single mask for the entire datasource,
+but could not handle producing a single mask per band, so it was deprecated in
+favor of ``src.read_masks()``, although it has no direct replacement.
+
+Tickets
+```````
+
+* `#284 <https://github.com/mapbox/rasterio/pull/284>`__ - Deprecation of
+  ``src.read_masks()``.
+
+
+Moved: Functions for working with dataset windows
+-------------------------------------------------
+
+Several functions in the top level ``rasterio`` namespace for working with
+dataset windows have been moved to ``rasterio.windows.*``:
+
+* ``rasterio.get_data_window()``
+* ``rasterio.window_union()``
+* ``rasterio.window_intersection()``
+* ``rasterio.windows_intersect()``
+
+Tickets
+~~~~~~~
+
+* `#609 <https://github.com/mapbox/rasterio/pull/609>`__ - Introduction of
+  ``rasterio.windows``.
+
+
+Moved: ``rasterio.tool``
+------------------------
+
+This module has been removed completely and its contents have been moved to
+several different locations:
+
+.. code-block::
+
+    rasterio.tool.show()      -> rasterio.plot.show()
+    rasterio.tool.show_hist() -> rasterio.plot.show_hist()
+    rasterio.tool.stats()     -> rasterio.rio.insp.stats()
+    rasterio.tool.main()      -> rasterio.rio.insp.main()
+
+Tickets
+~~~~~~~
+
+* `#609 <https://github.com/mapbox/rasterio/pull/609>`__ - Deprecation of
+  ``rasterio.tool``.
+
+
+Moved: ``rasterio.tools``
+-------------------------
+
+This module has been removed completely and its contents have been moved to
+several different locations:
+
+.. code-block::
+
+     rasterio.tools.mask.mask()   -> rasterio.mask.mask()
+     rasterio.tools.merge.merge() -> rasterio.merge.merge()
+
+Tickets
+~~~~~~~
+
+* `#609 <https://github.com/mapbox/rasterio/pull/609>`__ - Deprecation of
+  ``rasterio.tools``.
+
+
+Removed: ``rasterio.warp.RESAMPLING``
+-------------------------------------
+
+Replaced with ``rasterio.warp.Resampling``
+
+
+Signature Changes
+-----------------
+
+For both ``rasterio.features.sieve()`` and ``rasterio.features.rasterize()`` the
+``output`` argument has been replaced with ``out``.  Previously the use of
+``output`` issued a deprecation warning.

docs/recipes/reproject.py

@@ -22,7 +22,6 @@
         profile.update({
             'crs': dst_crs,
             'transform': dst_affine,
-            'affine': dst_affine,
             'width': dst_width,
             'height': dst_height
         })
@@ -37,7 +36,7 @@
                     # Source parameters
                     source=src_array,
                     src_crs=src.crs,
-                    src_transform=src.affine,
+                    src_transform=src.transform,
                     # Destination paramaters
                     destination=dst_array,
                     dst_transform=dst_affine,

docs/resampling.rst

@@ -30,7 +30,7 @@ by ``x``, you need to *divide* the affine parameters defining the cell size by `
                              round(arr.shape[2] * 1.5)))
 
     # adjust the new affine transform to the 150% smaller cell size
-    aff = src.affine
+    aff = src.transform
     newaff = Affine(aff.a / 1.5, aff.b, aff.c,
                     aff.d, aff.e / 1.5, aff.f)
 
@@ -60,7 +60,7 @@ that differs from the resampling methods available in GDAL. This may not be appr
     newarr = zoom(arr, zoom=[1, 1.5, 1.5], order=3, prefilter=False)
 
     # Adjust original affine transform
-    aff = src.affine
+    aff = src.transform
     newaff = Affine(aff.a / 1.5, aff.b, aff.c,
                     aff.d, aff.e / 1.5, aff.f)
 

docs/windowed-rw.rst

@@ -177,7 +177,6 @@ a dataset:
         # window = ((3, 714), (13, 770))
 
         kwargs = src.meta.copy()
-        del kwargs['transform']
         kwargs.update({
             'height': window[0][1] - window[0][0],
             'width': window[1][1] - window[1][0],

docs/working_with_datasets.rst

@@ -37,7 +37,7 @@ coordinates to coordinates in that reference system.
 
     >>> src.crs
     {'init': u'epsg:32618'}
-    >>> src.affine
+    >>> src.transform
     Affine(300.0379266750948, 0.0, 101985.0,
            0.0, -300.041782729805, 2826915.0)
 
@@ -48,10 +48,10 @@ row)``.
 .. code-block:: python
 
     >>> col, row = 0, 0
-    >>> src.affine * (col, row)
+    >>> src.transform * (col, row)
     (101985.0, 2826915.0)
     >>> col, row = src.width, src.height
-    >>> src.affine * (col, row)
+    >>> src.transform * (col, row)
     (339315.0, 2611485.0)
 
 

examples/async-rasterio.py

@@ -27,8 +27,6 @@ def main(infile, outfile, with_threads=False):
             # concurrently.
 
             meta = src.meta
-            del meta['transform']
-            meta.update(affine=src.affine)
             meta.update(blockxsize=256, blockysize=256, tiled='yes')
             with rasterio.open(outfile, 'w', **meta) as dst:
 

examples/concurrent-cpu-bound.py

@@ -27,8 +27,6 @@ def main(infile, outfile, num_workers=4):
             # The destination will be tiled, and we'll "process" the tiles
             # concurrently.
             meta = src.meta
-            del meta['transform']
-            meta.update(affine=src.affine)
             meta.update(blockxsize=256, blockysize=256, tiled='yes')
             with rasterio.open(outfile, 'w', **meta) as dst:
 

examples/rasterio_polygonize.py

@@ -30,7 +30,7 @@ def main(raster_file, vector_file, driver, mask_value):
             {'properties': {'raster_val': v}, 'geometry': s}
             for i, (s, v)
             in enumerate(
-                shapes(image, mask=mask, transform=src.affine)))
+                shapes(image, mask=mask, transform=src.transform)))
 
         with fiona.open(
                 vector_file, 'w',
@@ -68,5 +68,5 @@ def main(raster_file, vector_file, driver, mask_value):
 
     name = main(args.input, args.output, args.output_driver, args.mask_value)
 
-    print subprocess.check_output(
-            ['ogrinfo', '-so', args.output, name])
+    print(subprocess.check_output(
+            ['ogrinfo', '-so', args.output, name]))