\chapter{Module trafo: linear transformations}

\label{trafo}

With the  \verb|trafo| module \PyX\ supports linear transformations, which can 
then be applied to canvases,  B\'ezier paths and other objects. It consists
of the main class \verb|trafo| representing a general linear
transformation and subclasses thereof, which provide special operations
like translation, rotation, scaling, and mirroring.

\section{Class trafo}

The \verb|trafo| class represents a general linear
transformation, which is defined for a vector $\vec{x}$ as
\[
  \vec{x}' = \mathsf{A}\, \vec{x} + \vec{b}\ ,
\]
where $\mathsf{A}$ is the transformation matrix and $\vec{b}$ the
translation vector. The transformation matrix must not be singular,
\textit{i.e.} we require $\det \mathsf{A} \ne 0$.



Multiple \verb|trafo| instances can be multiplied, corresponding to a
consecutive application of the respective transformation. Note that
\verb|trafo1*trafo2| means that \verb|trafo1| is applied after
\verb|trafo2|, \textit{i.e.} the new transformation is given 
by $\mathsf{A} = \mathsf{A}_1 \mathsf{A}_2$ and
$\vec{b} = \mathsf{A}_1 \vec{b}_2 + \vec{b}_1$.  Use the \verb|trafo|
methods described below, if you prefer thinking the other way round.
The inverse of a transformation can be obtained via the \verb|trafo|
method \verb|inverse()|, defined by the inverse $\mathsf{A}^{-1}$ of
the transformation matrix and the translation vector
$-\mathsf{A}^{-1}\vec{b}$.

The methods of the \verb|trafo| class are summarized in the following
table.

\medskip
\begin{tabularx}{\linewidth}{>{\hsize=.8\hsize}X>{\raggedright\arraybackslash\hsize=1.2\hsize}X}
\texttt{trafo} method & function \\
\hline
\texttt{\_\_init\_\_(matrix=((1,0),(0,1)),\newline
\phantom{\_\_init\_\_(}vector=(0,0)):} & create new \texttt{trafo}
instance with transformation \texttt{matrix} and \texttt{vector}.
\\
\texttt{apply(x, y)} & apply \texttt{trafo} to point vector
$(\mathtt{x}, \mathtt{y})$.\\
\texttt{inverse()} & returns inverse transformation of
\texttt{trafo}.\\
\texttt{mirrored(angle)} & returns \texttt{trafo} followed by mirroring
at line through $(0,0)$ with  direction \texttt{angle} in degrees.\\
\texttt{rotated(angle, \newline\phantom{rotate(}x=None, y=None)} &
returns \texttt{trafo} followed by rotation by \texttt{angle} degrees
around point $(\mathtt{x},
\mathtt{y})$, or $(0,0)$, if not given.\\
\texttt{scaled(sx, sy=None,\newline\phantom{scale(}x=None, y=None)} &
returns \texttt{trafo} followed by
scaling with scaling factor \texttt{sx} in $x$-direction, \texttt{sy} in
$y$-direction ($\mathtt{sy}=\mathtt{sx}$, if not given) with scaling
center $(\mathtt{x}, \mathtt{y})$, or $(0,0)$, if not given.\\
\texttt{translated(x, y)} & returns \texttt{trafo} followed by
translation by vector $(\mathtt{x}, \mathtt{y})$.\\
\texttt{slanted(a, angle=0, x=None, y=None)} & returns \texttt{trafo}
followed by XXX\\
\end{tabularx}
\medskip



\section{Subclasses of trafo}

The \verb|trafo| module provides a number of subclasses of
the \verb|trafo| class, each of which corresponds to one \verb|trafo|
method. They are listed in the following table:

\medskip
\begin{tabularx}{\linewidth}{>{\hsize=.7\hsize}X>{\raggedright\arraybackslash\hsize=1.3\hsize}X}
  \texttt{trafo} subclass & function \\
  \hline 
  \texttt{mirror(angle)} & mirroring at line through $(0,0)$
  with direction  \texttt{angle} in degrees.\\
  \texttt{rotate(angle, \newline\phantom{rotation(}x=None, y=None)} &
  rotation by \texttt{angle} degrees around point $(\mathtt{x},
  \mathtt{y})$, or $(0,0)$, if not given.\\
  \texttt{scale(sx, sy=None,\newline\phantom{scaling(}x=None, y=None)} &
  scaling with scaling factor \texttt{sx} in $x$-direction,
  \texttt{sy} in $y$-direction ($\mathtt{sy}=\mathtt{sx}$, if not
  given) with scaling
  center $(\mathtt{x}, \mathtt{y})$, or $(0,0)$, if not given.\\
  \texttt{translate(x, y)} &
  translation by vector $(\mathtt{x}, \mathtt{y})$.\\
  \texttt{slant(a, angle=0, x=None, y=None)} & XXX \\
\end{tabularx}
\medskip


% \section{Examples}



%%% Local Variables:
%%% mode: latex
%%% TeX-master: "manual.tex"
%%% End:
