Developer's Guide: Transformation Objects

Rect Objects | Coordinate Systems | Curve Objects

## Transformation Objects

A transformation object, a trafo object or trafo for short, represents an affine 2D transformation. Such a transformation is given by 6 numbers: m11, m21, m21, m22, v1 and v2. These coefficients are given in the same order as for a PostScript transformation matrix.

To apply a trafo to an object you can simple call the trafo with that object as argument. For details, see the section ``Operators'' below.

Trafo objects are immutable.

If such a transformation T is applied to the point (x, y) you get

                / x \   / m11 m12 \ / x \   / v1 \
            T * |   | = |         | |   | + |    |
                \ y /   \ m21 m22 / \ y /   \ v2 /

or, in homogeneous coordinates:

                / x \   / m11 m12 v1 \ / x \
                |   |   |            | |   |
            T * | y | = | m21 m22 v2 | | y |
                |   |   |            | |   |
                \ 1 /   \ 0   0   1  / \ 1 /

### Constructors

The following functions create trafo objects:

`Trafo(m11, m21, m21, m22, v1, v2)`

  The generic constructor: return the transformation given by the coordinates m11, m21, m21, m22, v1 and v2. These coefficients are given in the same order as for a PostScript transformation matrix.

`Scale(factorx[, factory])`

  Return a trafo object for a scaling by the factors factorx (in x-direction) and factory (in y-direction). If omitted, factory defaults to the value of factorx.

  Equivalent to `Trafo(factorx, 0, 0, factory, 0, 0)`.

`Translation(offset)`
`Translation(offset_x, offset_y)`

  Return a trafo object for a translation by offset (a PointSpec) or (offset_x, offset_y). Equivalent to `Trafo(1, 0, 0, 1, offset_x, offset_y)`.

`Rotation(angle[, center])`
`Rotation(angle[, center_x, center_y])`

  Return a trafo object for a rotation through the angle angle (counter clockwise in radians) about the center point center or (center_x, center_y). center must be a PointSpec. If center is omitted it defaults to the origin.

  Equivalent to

      	s = sin(angle);
      	c = cos(angle);
      	offx = cx - c * center_x + s * center_y;
      	offy = cy - s * center_x - c * center_y;
      	Trafo(c, s, -s, c, offx, offy);

### Attributes

A trafo object has six (read only) attributes:

`m11`, `m21`, `m12`, `m22`
`v1`, `v2`

  The coefficients of the trafo as python floats.

### Methods

`DocToWin(point)`
`DocToWin(x, y)`

  Transform the point and return the result as a tuple of ints. point is a PointSpec. This function is used to transform document coordinates to window coordinates, hence the name. (Normally, if you want to transform a point, you call the trafo object directly)

`DTransform(point)`
`DTransform(x, y)`

  Treat the point as a vector and transform it, that is, don't add `v1` and `v2`. point is a PointSpec.

`inverse()`

  Return the inverse transformation of self. If self cannot be inverted raise the `SingularMatrix` exception.

`coeff()`

  Return the coefficients of the trafo as a tuple (m11, m21, m21, m22, v1, v2).

`matrix()`

  Return the matrix coefficients of the trafo (`m11`, ..., `m22`) as a tuple. The same as `coeff()[:4]`.

`offset()`

  Return the translation coefficients as a point object.

### Operators

Since a transformation is a mapping in the mathematical sense, it is convenient to make trafo objects callable, so you can treat them like functions or methods. Depending on the type of the argument the results are different:

`trafo(point)`
`trafo(x, y)`

  Return the transformed point. Point can be any PointSpec.

`trafo(othertrafo)`

  Return the composition of both trafos.

`trafo(rect)`

  Return the smallest rect object that contains the transformed corners of the rect object rect.

  `InfinityRect` and `EmptyRect` are returned unchanged.

### Constants

`Identity`

  The identity transformation (`Trafo(1, 0, 0, 1, 0, 0)`)

`IdentityMatrix`

  A tuple containing the coefficients of the identity matrix. The same as `Identity.matrix()`

`TrafoType`

  The trafo type object.

`SingularMatrix`

  Exception raised by the `inverse()` method.

Rect Objects | Coordinate Systems | Curve Objects