kiva.affine module

Functions for affine matrices.

Copyright

Space Telescope Science Institute

License

BSD Style

Author

Eric Jones, Enthought, Inc., eric@enthought.com

These affine operations are based coordinate system transformations, not translations of pts, etc. To translate a point, you multiply it by the affine transform matrix:

             a    b    0
[x, y, 1] *  c    d    0 = [x', y', 1]
             tx   ty   1

This is the opposite order of multiplication from what many are accustomed to.

Here is a useful link:

http://mathworld.wolfram.com/AffineTransformation.html

Notes

I’m not using a class because of possible speed implications. Currently the affine transform is a 3x3 array. Other tools use a 6-tuple of (a, b, c, d, tx, ty) to represent the transform because the other 3 array entries are constant. Other code should call methods from this module instead of manipulating the array, in case the implementation is changed at some future date.

kiva.affine.affine_from_rotation(angle)

Returns an affine transform rotated by angle in radians.

kiva.affine.affine_from_scale(sx, sy)

Returns an affine transform providing the given scaling.

kiva.affine.affine_from_translation(x, y)

Returns an affine transform with the given translation.

kiva.affine.affine_from_values(a, b, c, d, tx, ty)

Return the affine matrix corresponding to the values

The result is the array::

[ a b 0 ] [ c d 0 ] [ tx ty 1 ]

kiva.affine.affine_identity()

Returns a new identity affine_transform object.

kiva.affine.affine_params(m)

Returns the a, b, c, d, tx, ty values of an affine transform.

kiva.affine.concat(transform, other)

Returns the concatenation of transform with other. This is simply transform pre-multiplied by other.

kiva.affine.invert(m)

Returns the inverse of the transform, m.

kiva.affine.is_identity(m)

Tests whether an affine transform is the identity transform.

kiva.affine.rotate(transform, angle)

Rotates transform by angle in radians.

Rotation is done using the following formula:

 cos(x)  sin(x)  0       a  b   0
-sin(x)  cos(x)  0   *   c  d   0 =
   0       0     1      tx ty   1

 cos(x)*a+sin(x)*b   cos(x)*b+sin(x)*d    0
-sin(x)*a+cos(x)*c  -sin(x)*b+cos(x)*d    0
         tx                  ty           1

where x = angle.

kiva.affine.scale(transform, sx, sy)

Returns a scaled version of the transform by the given values.

Scaling is done using the following formula:

sx  0  0     a  b  0      sx*a sx*b  0
0  sy  0  *  c  d  0  =   sy*c sy*d  0
0   0  1    tx ty  1       0    0    1

kiva.affine.transform_point(ctm, pt)

Returns pt transformed by the affine transform, ctm.

kiva.affine.transform_points(ctm, pts)

Transforms an array of points using the affine transform, ctm.

kiva.affine.translate(transform, x, y)

Returns transform translated by (x, y).

Translation:

1  0  0      a   b   0         a          b        0
0  1  0   *  c   d   0  =      c          d        0
x  y  1     tx  ty   1     x*a+y*c+y  x*b+y*d+ty   1

kiva.affine.trs_factor(m)

Factors a matrix as if it is the product of translate/rotate/scale matrices applied (i.e., concatenated) in that order. It returns:

tx,ty,sx,sy,angle

where tx and ty are the translations, sx and sy are the scaling values and angle is the rotational angle in radians.

If the input matrix was created in a way other than concatenating t/r/s matrices, the results could be wrong. For example, if there is any skew in the matrix, the returned results are wrong.

Needs Test!

kiva.affine.tsr_factor(m)

Factors a matrix as if it is the product of translate/scale/rotate matrices applied (i.e., concatenated) in that order. It returns:

tx, ty, sx, sy, angle

where tx and ty are the translations, sx and sy are the scaling values and angle is the rotational angle in radians.

If the input matrix was created in a way other than concatenating t/s/r matrices, the results could be wrong. For example, if there is any skew in the matrix, the returned results are wrong.

Needs Test!