manual/trafo.rst

   1
   2 .. module:: trafo
   3
   4 *******************************************
   5 Module :mod:`trafo`: Linear transformations
   6 *******************************************
   7
   8
   9 With the  ``trafo`` module PyX supports linear transformations, which can  then
  10 be applied to canvases,  Bézier paths and other objects. It consists of the main
  11 class ``trafo`` representing a general linear transformation and subclasses
  12 thereof, which provide special operations like translation, rotation, scaling,
  13 and mirroring.
  14
  15
  16 Class :class:`trafo`
  17 ====================
  18
  19 The ``trafo`` class represents a general linear transformation, which is defined
  20 for a vector :math:`\vec{x}` as
  21
  22 .. math::
  23
  24    \vec{x}' = \mathsf{A}\, \vec{x} + \vec{b}\ ,
  25
  26 where :math:`\mathsf{A}` is the transformation matrix and :math:`\vec{b}` the
  27 translation vector. The transformation matrix must not be singular, *i.e.* we
  28 require :math:`\det \mathsf{A} \ne 0`.
  29
  30 Multiple ``trafo`` instances can be multiplied, corresponding to a consecutive
  31 application of the respective transformation. Note that ``trafo1*trafo2`` means
  32 that ``trafo1`` is applied after ``trafo2``, *i.e.* the new transformation is
  33 given  by :math:`\mathsf{A} = \mathsf{A}_1 \mathsf{A}_2` and :math:`\vec{b} =
  34 \mathsf{A}_1 \vec{b}_2 + \vec{b}_1`.  Use the ``trafo`` methods described below,
  35 if you prefer thinking the other way round. The inverse of a transformation can
  36 be obtained via the ``trafo`` method ``inverse()``, defined by the inverse
  37 :math:`\mathsf{A}^{-1}` of the transformation matrix and the translation vector
  38 :math:`-\mathsf{A}^{-1}\vec{b}`.
  39
  40 .. class:: trafo(matrix=((1,0),(0,1)), vector=(0,0))
  41
  42    create new ``trafo`` instance with transformation ``matrix`` and ``vector``
  43
  44 .. method:: apply(x, y)
  45
  46    apply ``trafo`` to point vector :math:`(\mathtt{x}, \mathtt{y})`.
  47
  48 .. method:: inverse()
  49
  50    returns inverse transformation of ``trafo``.
  51
  52 .. method:: mirrored(angle)
  53
  54    returns ``trafo`` followed by mirroring at line through :math:`(0,0)` with
  55    direction ``angle`` in degrees.
  56
  57 .. method:: rotated(angle, x=None, y=None)
  58
  59    returns ``trafo`` followed by rotation by ``angle`` degrees around point
  60    :math:`(\mathtt{x}, \mathtt{y})`, or :math:`(0,0)`, if not given.
  61
  62 .. method:: scaled(sx, sy=None, x=None, y=None)
  63
  64    returns ``trafo`` followed by scaling with scaling factor ``sx`` in
  65    :math:`x`\ -direction, ``sy`` in :math:`y`\ -direction
  66    (:math:`\mathtt{sy}=\mathtt{sx}`, if not given) with scaling center
  67    :math:`(\mathtt{x}, \mathtt{y})`, or :math:`(0,0)`, if not given.
  68
  69 .. method:: slanted(a, angle=0, x=None, y=None)
  70
  71    returns ``trafo`` followed by slant by ``angle`` around point
  72    :math:`(\mathtt{x}, \mathtt{y})`, or :math:`(0,0)`, if not given.
  73
  74 .. method:: translated(x, y)
  75
  76    returns ``trafo`` followed by translation by vector :math:`(\mathtt{x}, \mathtt{y})`.
  77
  78
  79 Subclasses of :class:`trafo`
  80 ============================
  81
  82 The ``trafo`` module provides a number of subclasses of the ``trafo`` class,
  83 each of which corresponds to one ``trafo`` method.
  84
  85 .. class:: mirror(angle)
  86
  87    mirroring at line through :math:`(0,0)` with direction ``angle`` in degrees.
  88
  89 .. class:: rotate(angle, x=None, y=None)
  90
  91    rotation by ``angle`` degrees around point :math:`(\mathtt{x}, \mathtt{y})`, or :math:`(0,0)`, if not given.
  92
  93 .. class:: scale(sx, sy=None, x=None, y=None)
  94
  95    scaling with scaling factor ``sx`` in :math:`x`\ -direction, ``sy`` in
  96    :math:`y`\ -direction (:math:`\mathtt{sy}=\mathtt{sx}`, if not given) with
  97    scaling center :math:`(\mathtt{x}, \mathtt{y})`, or :math:`(0,0)`, if not
  98    given.
  99
 100 .. class:: slant(a, angle=0, x=None, y=None)
 101
 102    slant by ``angle`` around point :math:`(\mathtt{x}, \mathtt{y})`, or :math:`(0,0)`, if not given.
 103
 104 .. class:: translate(x, y)
 105
 106    translation by vector :math:`(\mathtt{x}, \mathtt{y})`.
 107