/usr/share/doc/python-cairo-dev/html/_sources/reference/matrix.txt is in python-cairo-dev 1.8.8-2.2.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 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.
|