Welcome to rasterio/affine’s documentation!¶
This is the documentation of the latest development version at https://github.com/rasterio/affine .
Affine¶
Matrices describing 2D affine transformation of the plane.
The Affine package is derived from Casey Duncan’s Planar package. Please see the copyright statement in src/affine.py.
Usage¶
The 3 x 3 augmented affine transformation matrix for transformations in two dimensions is illustrated below.
| x' | | a b c | | x |
| y' | = | d e f | | y |
| 1 | | 0 0 1 | | 1 |
Matrices can be created by passing the values a, b, c, d, e, f
to the
affine.Affine
constructor or by using its identity()
,
translation()
, scale()
, shear()
, and rotation()
class methods.
>>> from affine import Affine
>>> Affine.identity()
Affine(1.0, 0.0, 0.0,
0.0, 1.0, 0.0)
>>> Affine.translation(1.0, 5.0)
Affine(1.0, 0.0, 1.0,
0.0, 1.0, 5.0)
>>> Affine.scale(2.0)
Affine(2.0, 0.0, 0.0,
0.0, 2.0, 0.0)
>>> Affine.shear(45.0, 45.0) # decimal degrees
Affine(1.0, 0.9999999999999999, 0.0,
0.9999999999999999, 1.0, 0.0)
>>> Affine.rotation(45.0) # decimal degrees
Affine(0.7071067811865476, -0.7071067811865475, 0.0,
0.7071067811865475, 0.7071067811865476, 0.0)
These matrices can be applied to (x, y)
tuples to obtain transformed
coordinates (x', y')
.
>>> Affine.translation(1.0, 5.0) * (1.0, 1.0)
(2.0, 6.0)
>>> Affine.rotation(45.0) * (1.0, 1.0)
(1.1102230246251565e-16, 1.414213562373095)
They may also be multiplied together to combine transformations.
>>> Affine.translation(1.0, 5.0) * Affine.rotation(45.0)
Affine(0.7071067811865476, -0.7071067811865475, 1.0,
0.7071067811865475, 0.7071067811865476, 5.0)
Usage with GIS data packages¶
Georeferenced raster datasets use affine transformations to map from image
coordinates to world coordinates. The affine.Affine.from_gdal()
class
method helps convert GDAL GeoTransform,
sequences of 6 numbers in which the first and fourth are the x and y offsets
and the second and sixth are the x and y pixel sizes.
Using a GDAL dataset transformation matrix, the world coordinates (x, y)
corresponding to the top left corner of the pixel 100 rows down from the
origin can be easily computed.
>>> geotransform = (-237481.5, 425.0, 0.0, 237536.4, 0.0, -425.0)
>>> fwd = Affine.from_gdal(*geotransform)
>>> col, row = 0, 100
>>> fwd * (col, row)
(-237481.5, 195036.4)
The reverse transformation is obtained using the ~
operator.
>>> rev = ~fwd
>>> rev * fwd * (col, row)
(0.0, 99.99999999999999)
Installation¶
Wheels and source distributions are published to the Python Package Index and can be installed by, for example, pip.
pip install affine
Documentation¶
The documentation source in docs/ is hosted at https://affine.readthedocs.io/.
Development and Testing¶
The project uses tox and pytest. See the tox.ini and pyproject.toml files for configuration of those tools. Affine is largely complete and is not actively developed.
CHANGES¶
3.0a1 (TBD)¶
Type hint annotations for functions and methods are complete (#121).
Affine raises ValueError if initialized with values for g, h, and i that are not 0.0, 0.0, and 1.0, respectively (#117).
Python version support was changed to 3.9+ (#110).
Switch from namedtuple to attrs for implementation of the Affine class and use functools.cached_property(), which absolutely requires Python 3.8+ (#111).
Source was moved to a single-module affine.py in the src directory (#112).
Add numpy __array__ interface (#108).
2.4.0 (2023-01-19)¶
Package is marked as Python 3 only, two instances of “%” string formatting are replaced by f-strings (#96).
2.4b1 (2023-01-18)¶
Elimination of Python 2/3 compatibility code in __gt__ (#94).
Addition of optional keyword arguments for __new__, solving an issue with Dask (#92).
Addition of some type hints for float arguments and return types (#87).
Python version support is now 3.7-3.11 (#82).
Faster __new__ and from_gdal methods (#78).
2.3.1 (2022-03-24)¶
Bug fixes:
Return NotImplemented for both ValueError and TypeError in __mul__ to support fallback to __rmul__ in more cases (gh-71).
2.3.0 (2019-09-04)¶
Deprecations:
Right multiplication like vector * matrix is deprecated and will raise AffineError in version 3.0.0.
Bug fixes:
Change signature of Affine constructor to help users of PyCharm (#45).
The Affine class docstring has been improved.
2.2.2 (2018-12-20)¶
Affine.itransform computed the wrong results for arrays with rotation or shear (#40). This is fixed (#41).
2.2.1 (2018-06-04)¶
Docstring improvements (#37).
2.2.0 (2018-03-20)¶
Addition of permutation matrix (#35).
2.1.0 (2017-07-12)¶
Addition of new
eccentricity
androtation_angle
properties (#28).
2.0.0.post1 (2016-05-20)¶
This is the final 2.0.0 release. The post-release version segment is used because we accidentally uploaded a 2.0.0 to PyPI before the beta releases below.
2.0b2 (2016-05-16)¶
Bug fix: restore
Affine __rmul__
even though it permits dubious vector * matrix expressions (#27).
2.0b1 (2016-05-16)¶
Breaking change: precision used in properties like
is_conformal
is no longer a global module attribute, but an Affine class or instance attribute (#19, #20).Breaking change:
is_degenerate
property is now exact and not subject to a level of precision (#23).Breaking change: we have reversed our sense of rotation, a positive angle now rotates a point counter-clockwise about the pivot point (#25).
Bug fix: a bug in matrix-vector multiplication had been reversing the direction of rotation and is now fixed (#25).
1.3.0 (2016-04-08)¶
is_degenerate predicate is precise, not approximate (#22).
1.2.0 (2015-06-01)¶
Enable pickling of Affine objects (#14).
Sort out the mixed up shearing parameters (#12).
1.1.0 (2014-11-13)¶
Add loadsw/dumpsw world file utilities (#6).
Travis-CI and Coveralls config and web hooks added (#10).
1.0.1 (2014-10-20)¶
set_epsilon() now actually sets module EPSILON (#4).
add AUTHORS.txt.
1.0 (2014-05-27)¶
Code ported from Casey Duncan’s Planar package.
from_gdal() class method added.
License¶
Copyright (c) 2014, Sean C. Gillies
All rights reserved.
Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are met:
* Redistributions of source code must retain the above copyright
notice, this list of conditions and the following disclaimer.
* Redistributions in binary form must reproduce the above copyright
notice, this list of conditions and the following disclaimer in the
documentation and/or other materials provided with the distribution.
* Neither the name of Sean C. Gillies nor the names of
its contributors may be used to endorse or promote products derived from
this software without specific prior written permission.
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
POSSIBILITY OF SUCH DAMAGE.