Plan for replacing GDAL transform arrays with Affine instances

[sgillies]

The Goal

In Rasterio versions up to 0.8, GDAL geotransform arrays were used throughout: in the internals when calling GDAL functions and in the Rasterio Python interfaces. In Rasterio 1.0 GDAL's arrays will be for internal use only and Rasterio will deal in instances of affine.Affine or 6-element tuples that can be converted directly to instances of that class.

The Plan

Arguments

In the methods and functions with transform arguments, we will try to support both the new objects and the GDAL geotransform arrays up until 1.0 by sniffing sequences for characteristic signs of being a GDAL array. Here's the function to be used:

def tastes_like_gdal(t):
    return t[2] == t[4] == 0.0 and t[1] > 0 and t[5] < 0

Geospatial rasters very rarely have non-zero rotation coefficients and GDAL has them at indexes 2 and 4. GDAL puts the pixel sizes at indexes 1 and 5 and the later should be negative. When a GDAL geotransform argument is received, Rasterio will raise a future warning like this:

$ python -Wall examples/reproject.py
/Users/sean/code/rasterio/rasterio/__init__.py:100: FutureWarning: GDAL-style transforms are deprecated and will not be supported in Rasterio 1.0.
  FutureWarning)

Note that deprecation warnings get ignored unless warnings are turned on with the -W option.

Return Values

For the methods and properties that return a transformation object, we need a different approach. Starting with version 0.9, properties like .transform will raise a deprecation warning. We will also add parallel .affine property, values of which are instances of affine.Affine. At version 1.0, we will switch the values of .transform over to affine.Affine and leave the .affine attribute as a deprecated alias.

This plan will finish for Rasterio the harmonization proposed in #80.

cc @brendan-ward @mwtoews @AsgerPetersen

[johanvdw]

What is the recommended way to have code working with both rasterio 0.36 and the 1.0* releases?

I currently use dst.affine, which works fine under both versions, but generates a shitload of warning on 1.0*. Do I really have to check for the rasterio version and adopt the behaviour?

[johanvdw]

I dislike checking for a version, so I came up with this solution, may be useful for others.

from affine import Affine
...
if isinstance(dst.transform, Affine):
    transform = dst.transform
else:
    transform = dst.affine  # for compatibility with rasterio 0.36