diff options
Diffstat (limited to 'doc/reference/matrix.rst')
| -rw-r--r-- | doc/reference/matrix.rst | 181 |
1 files changed, 181 insertions, 0 deletions
diff --git a/doc/reference/matrix.rst b/doc/reference/matrix.rst new file mode 100644 index 0000000..cb3ec3e --- /dev/null +++ b/doc/reference/matrix.rst @@ -0,0 +1,181 @@ +.. _matrix: + +****** +Matrix +****** + +.. currentmodule:: cairo + + +class Matrix() +============== + +*Matrix* is used throughout cairo to convert between different coordinate +spaces. A *Matrix* holds an affine transformation, such as a scale, rotation, +shear, or a combination of these. The transformation of a point (x,y) is +given by:: + + x_new = xx * x + xy * y + x0 + y_new = yx * x + yy * y + y0 + +The current transformation matrix of a :class:`Context`, represented as a +*Matrix*, defines the transformation from user-space coordinates to device-space +coordinates. + +Some standard Python operators can be used with matrices: + +To read the values from a *Matrix*:: + + xx, yx, xy, yy, x0, y0 = matrix + +To multiply two matrices:: + + matrix3 = matrix1.multiply(matrix2) + # or equivalently + matrix3 = matrix1 * matrix2 + +To compare two matrices:: + + matrix1 == matrix2 + matrix1 != matrix2 + +For more information on matrix transformation see http://www.cairographics.org/matrix_transform + + +.. class:: Matrix(xx = 1.0, yx = 0.0, xy = 0.0, yy = 1.0, x0 = 0.0, y0 = 0.0) + + :param xx: xx component of the affine transformation + :type xx: float + :param yx: yx component of the affine transformation + :type yx: float + :param xy: xy component of the affine transformation + :type xy: float + :param yy: yy component of the affine transformation + :type yy: float + :param x0: X translation component of the affine transformation + :type x0: float + :param y0: Y translation component of the affine transformation + :type y0: float + + Create a new *Matrix* with the affine transformation given by *xx, yx, xy, + yy, x0, y0*. The transformation is given by:: + + x_new = xx * x + xy * y + x0 + y_new = yx * x + yy * y + y0 + + To create a new identity matrix:: + + matrix = cairo.Matrix() + + To create a matrix with a transformation which translates by tx and ty in the X and Y dimensions, respectively:: + + matrix = cairo.Matrix(x0=tx, y0=ty) + + To create a matrix with a transformation that scales by sx and sy in the X and Y dimensions, respectively:: + + matrix = cairo.Matrix(xx=sy, yy=sy) + + + .. classmethod:: init_rotate(radians) + + :param radians: angle of rotation, in radians. The direction of rotation + is defined such that positive angles rotate in the direction from the + positive X axis toward the positive Y axis. With the default axis + orientation of cairo, positive angles rotate in a clockwise direction. + :type radians: float + :returns: a new *Matrix* set to a transformation that rotates by *radians*. + + + .. method:: invert() + + :returns: If *Matrix* has an inverse, modifies *Matrix* to be the + inverse matrix and returns *None* + :raises: :exc:`cairo.Error` if the *Matrix* as no inverse + + Changes *Matrix* to be the inverse of it's original value. Not all + transformation matrices have inverses; if the matrix collapses points + together (it is *degenerate*), then it has no inverse and this function + will fail. + + + .. method:: multiply(matrix2) + + :param matrix2: a second matrix + :type matrix2: cairo.Matrix + :returns: a new *Matrix* + + Multiplies the affine transformations in *Matrix* and *matrix2* + together. The effect of the resulting transformation is to first apply + the transformation in *Matrix* to the coordinates and then apply the + transformation in *matrix2* to the coordinates. + + It is allowable for result to be identical to either *Matrix* or *matrix2*. + + + .. method:: rotate(radians) + + :param radians: angle of rotation, in radians. The direction of rotation + is defined such that positive angles rotate in the direction from the + positive X axis toward the positive Y axis. With the default axis + orientation of cairo, positive angles rotate in a clockwise direction. + :type radians: float + + Initialize *Matrix* to a transformation that rotates by *radians*. + + .. method:: scale(sx, sy) + + :param sx: scale factor in the X direction + :type sx: float + :param sy: scale factor in the Y direction + :type sy: float + + Applies scaling by *sx, sy* to the transformation in *Matrix*. The + effect of the new transformation is to first scale the coordinates by + *sx* and *sy*, then apply the original transformation to the + coordinates. + + .. method:: transform_distance(dx, dy) + + :param dx: X component of a distance vector. + :type dx: float + :param dy: Y component of a distance vector. + :type dy: float + :returns: the transformed distance vector (dx,dy) + :rtype: (float, float) + + Transforms the distance vector *(dx,dy)* by *Matrix*. This is similar to + :meth:`.transform_point` except that the translation components of + the transformation are ignored. The calculation of the returned vector + is as follows:: + + dx2 = dx1 * a + dy1 * c + dy2 = dx1 * b + dy1 * d + + Affine transformations are position invariant, so the same vector always + transforms to the same vector. If *(x1,y1)* transforms to *(x2,y2)* then + *(x1+dx1,y1+dy1)* will transform to *(x1+dx2,y1+dy2)* for all values + of *x1* and *x2*. + + + .. method:: transform_point(x, y) + + :param x: X position. + :type x: float + :param y: Y position. + :type y: float + :returns: the transformed point (x,y) + :rtype: (float, float) + + Transforms the point *(x, y)* by *Matrix*. + + .. method:: translate(tx, ty) + + :param tx: amount to translate in the X direction + :type tx: float + :param ty: amount to translate in the Y direction + :type ty: float + + Applies a transformation by *tx, ty* to the transformation in + *Matrix*. The effect of the new transformation is to first translate the + coordinates by *tx* and *ty*, then apply the original transformation to the + coordinates. |