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 3x3 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 using the * operator (or the @ matrix multiplier operator for future releases) 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 ~ inverse operator.

>>> rev = ~fwd
>>> rev * fwd * (col, row)
(0.0, 99.99999999999999)

Module documentation¶

Affine transformation matrices.

The Affine package is derived from Casey Duncan’s Planar package. See the copyright statement below.

class affine.Affine(a, b, c, d, e, f, g=0.0, h=0.0, i=1.0)[source]¶

Two dimensional affine transform for 2D linear mapping.

Parallel lines are preserved by these transforms. Affine transforms can perform any combination of translations, scales/flips, shears, and rotations. Class methods are provided to conveniently compose transforms from these operations.

Parameters:

a (float) – Coefficients of the 3 x 3 augmented affine transformation matrix.
b (float) – Coefficients of the 3 x 3 augmented affine transformation matrix.
c (float) – Coefficients of the 3 x 3 augmented affine transformation matrix.
d (float) – Coefficients of the 3 x 3 augmented affine transformation matrix.
e (float) – Coefficients of the 3 x 3 augmented affine transformation matrix.
f (float) – Coefficients of the 3 x 3 augmented affine transformation matrix.
g (float, optional) – Coefficients of the 3 x 3 augmented affine transformation matrix.
h (float, optional) – Coefficients of the 3 x 3 augmented affine transformation matrix.
i (float, optional) – Coefficients of the 3 x 3 augmented affine transformation matrix.

a, b, c, d, e, f, g, h, i

Coefficients of the 3 x 3 augmented affine transformation matrix.

| x' |   | a  b  c | | x |
| y' | = | d  e  f | | y |
| 1  |   | g  h  i | | 1 |

g, h, and i are always 0, 0, and 1.

Type:: float

Notes

Multiplication of a transform and an (x, y) vector always returns the column vector that is the matrix multiplication product of the transform and (x, y) as a column vector, no matter which is on the left or right side. This is obviously not the case for matrices and vectors in general, but provides a convenience for users of this class.

The Affine package is derived from Casey Duncan’s Planar package. See the copyright statement.

almost_equals(other: Affine, precision: float | None = None) → bool[source]¶

Compare transforms for approximate equality.

Parameters:

other (Affine) – Transform being compared.
precision (float, default EPSILON) – Precision to use to evaluate equality.

Returns:

True if absolute difference between each element of each respective transform matrix < precision.

Return type:

bool

property column_vectors: tuple[tuple[float, float], tuple[float, float], tuple[float, float]]¶

The values of the transform as three 2D column vectors.

Returns:: Ordered (a, d), (b, e), (c, f).
Return type:: tuple of three tuple pairs

property eccentricity: float¶

The eccentricity of the affine transformation.

This value represents the eccentricity of an ellipse under this affine transformation.

Raises:: NotImplementedError – For improper transformations.

classmethod from_gdal(c: float, a: float, b: float, f: float, d: float, e: float) → Affine[source]¶

Use same coefficient order as GDAL’s GetGeoTransform().

Parameters:

c (float) – Parameters ordered by GDAL’s GeoTransform.
a (float) – Parameters ordered by GDAL’s GeoTransform.
b (float) – Parameters ordered by GDAL’s GeoTransform.
f (float) – Parameters ordered by GDAL’s GeoTransform.
d (float) – Parameters ordered by GDAL’s GeoTransform.
e (float) – Parameters ordered by GDAL’s GeoTransform.

Return type:

Affine

classmethod identity() → Affine[source]¶

Return the identity transform.

Return type:: Affine

property is_conformal: bool¶

True if the transform is conformal.

i.e., if angles between points are preserved after applying the transform, within rounding limits. This implies that the transform has no effective shear.

property is_identity: bool¶: True if this transform equals the identity matrix, within rounding limits.

property is_orthonormal: bool¶

True if the transform is orthonormal.

Which means that the transform represents a rigid motion, which has no effective scaling or shear. Mathematically, this means that the axis vectors of the transform matrix are perpendicular and unit-length. Applying an orthonormal transform to a shape always results in a congruent shape.

property is_rectilinear: bool¶

True if the transform is rectilinear.

i.e., whether a shape would remain axis-aligned, within rounding limits, after applying the transform.

itransform(seq: MutableSequence[Sequence[float]]) → None[source]¶

Transform a sequence of points or vectors in-place.

Parameters:: seq (mutable sequence)
Returns:: The input sequence is mutated in-place.
Return type:: None

classmethod permutation(*scaling: float) → Affine[source]¶

Create the permutation transform.

For 2x2 matrices, there is only one permutation matrix that is not the identity.

Parameters:: *scaling (any) – Ignored.
Return type:: Affine

classmethod rotation(angle: float, pivot: Sequence[float] | None = None) → Affine[source]¶

Create a rotation transform at the specified angle.

Parameters:

angle (float) – Rotation angle in degrees, counter-clockwise about the pivot point.
pivot (sequence of float (px, py), optional) – Pivot point coordinates to rotate around. If None (default), the pivot point is the coordinate system origin (0.0, 0.0).

Return type:

Affine

property rotation_angle: float¶

The rotation angle in degrees of the affine transformation.

This is the rotation angle in degrees of the affine transformation, assuming it is in the form M = R S, where R is a rotation and S is a scaling.

Raises:: UndefinedRotationError – For improper and degenerate transformations.

classmethod scale(*scaling: float) → Affine[source]¶

Create a scaling transform from a scalar or vector.

Parameters:: *scaling (float or sequence of two floats) – One or two scaling factors. A scalar value will scale in both dimensions equally. A vector scaling value scales the dimensions independently.
Return type:: Affine

classmethod shear(x_angle: float = 0.0, y_angle: float = 0.0) → Affine[source]¶

Create a shear transform along one or both axes.

Parameters:

x_angle (float) – Shear angles in degrees parallel to the x- and y-axis.
y_angle (float) – Shear angles in degrees parallel to the x- and y-axis.

Return type:

Affine

to_gdal() → tuple[float, float, float, float, float, float][source]¶

Return same coefficient order expected by GDAL’s SetGeoTransform().

Returns:: Ordered: c, a, b, f, d, e.
Return type:: tuple

to_shapely() → tuple[float, float, float, float, float, float][source]¶

Return affine transformation parameters for shapely’s affinity module.

Returns:: Ordered: a, b, d, e, c, f.
Return type:: tuple

classmethod translation(xoff: float, yoff: float) → Affine[source]¶

Create a translation transform from an offset vector.

Parameters:

xoff (float) – Translation offsets in x and y directions.
yoff (float) – Translation offsets in x and y directions.

Return type:

Affine

property xoff: float¶: Alias for ‘c’.

property yoff: float¶: Alias for ‘f’.

CHANGES¶

3.0rc4 (TBD)¶

Affine.__array__() has been deleted to remove a dependency on Numpy and associated typing annotations (#140). To convert an Affine instance to a Numpy array, do this: numpy.array(Affine()).reshape(3, 3).

3.0rc3 (2026-01-30)¶

The single file module affine.py has been moved to affine/__init__.py so that a py.typed file can be distributed in the same directory (#136).

3.0rc2 (2026-01-27)¶

3.0rc1 tagged the wrong commit. The distributions on PyPI have the correct version, but the GitHub release does not. This is fixed by 3.0rc2, which makes no other changes.

3.0rc1 (2026-01-26)¶

This is the first 3.0 release candidate. There are no significant changes since 3.0b1.

3.0b1 (2025-01-29)¶

Matrix multiplication with tuples of coordinate matrices, like the output of numpy.meshgrid(), has been restored (#126).

3.0a1 (2025-01-27)¶

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).
Add support for @ matrix multiplier methods (#122).

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 and rotation_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.

Authors¶

Casey Duncan
Sean Gillies
Denis Rykov
Juan Luis Cano Rodríguez
Kevin Wurster
Kirill Kouzoubov
Loïc Dutrieux
Michael Wess
Mike Taves
Nick Maxwell
Rotzbua
Ryan Grout
Steven Ring
Stuart Axon
Vincent Sarago

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.

Welcome to rasterio/affine’s documentation!¶

Affine¶

Usage¶

Usage with GIS data packages¶

Module documentation¶

CHANGES¶

3.0rc4 (TBD)¶

3.0rc3 (2026-01-30)¶

3.0rc2 (2026-01-27)¶

3.0rc1 (2026-01-26)¶

3.0b1 (2025-01-29)¶

3.0a1 (2025-01-27)¶

2.4.0 (2023-01-19)¶

2.4b1 (2023-01-18)¶

2.3.1 (2022-03-24)¶

2.3.0 (2019-09-04)¶

2.2.2 (2018-12-20)¶

2.2.1 (2018-06-04)¶

2.2.0 (2018-03-20)¶

2.1.0 (2017-07-12)¶

2.0.0.post1 (2016-05-20)¶

2.0b2 (2016-05-16)¶

2.0b1 (2016-05-16)¶

1.3.0 (2016-04-08)¶

1.2.0 (2015-06-01)¶

1.1.0 (2014-11-13)¶

1.0.1 (2014-10-20)¶

1.0 (2014-05-27)¶

Authors¶

License¶

Indices and tables¶

Table of Contents

This Page