manual/trafo.rst

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