Matrix — Pycairo documentation

# Matrix

## class Matrix()

class cairo.Matrix(xx: float = 1.0, yx: float = 0.0, xy: float = 0.0, yy: float = 1.0, x0: float = 0.0, y0: float = 0.0)

  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 `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 https://www.cairographics.org/cookbook/matrix_transform/

  __init__(xx: float = 1.0, yx: float = 0.0, xy: float = 0.0, yy: float = 1.0, x0: float = 0.0, y0: float = 0.0) → None
    Parameters:

      - xx – xx component of the affine transformation

      - yx – yx component of the affine transformation

      - xy – xy component of the affine transformation

      - yy – yy component of the affine transformation

      - x0 – X translation component of the affine transformation

      - y0 – Y translation component of the affine transformation

    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: float) → Matrix
    Parameters:

      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.

    Returns:

      a new Matrix set to a transformation that rotates by radians.

  invert() → Matrix | None
    Returns:

      If Matrix has an inverse, modifies Matrix to be the inverse matrix and returns None

    Raises:

      `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.

  multiply(matrix2: Matrix) → Matrix
    Parameters:

      matrix2 – a second 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.

  rotate(radians: float) → None
    Parameters:

      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.

    Initialize Matrix to a transformation that rotates by radians.

  scale(sx: float, sy: float) → None
    Parameters:

      - sx – scale factor in the X direction

      - sy – scale factor in the Y direction

    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.

  transform_distance(dx: float, dy: float) → tuple[float, float]
    Parameters:

      - dx – X component of a distance vector.

      - dy – Y component of a distance vector.

    Returns:

      the transformed distance vector (dx,dy), both float

    Transforms the distance vector (dx,dy) by Matrix. This is similar to `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.

  transform_point(x: float, y: float) → tuple[float, float]
    Parameters:

      - x – X position.

      - y – Y position.

    Returns:

      the transformed point (x,y), both float

    Transforms the point (x, y) by Matrix.

  translate(tx: float, ty: float) → None
    Parameters:

      - tx – amount to translate in the X direction

      - ty – amount to translate in the Y direction

    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.

  xx: float = Ellipsis

    xx component of the affine transformation

    Added in version 1.12.0.

  yx: float = Ellipsis

    yx component of the affine transformation

    Added in version 1.12.0.

  xy: float = Ellipsis

    xy component of the affine transformation

    Added in version 1.12.0.

  yy: float = Ellipsis

    yy component of the affine transformation

    Added in version 1.12.0.

  x0: float = Ellipsis

    X translation component of the affine transformation

    Added in version 1.12.0.

  y0: float = Ellipsis

    Y translation component of the affine transformation

    Added in version 1.12.0.