<html>
<head>
<title>Developer's Guide: Transformation Objects
</title>
</head>
<body bgcolor=white text=black link=blue vlink=navy alink=red>
<TABLE WIDTH="100%">
<TR>
<TH ALIGN="left" WIDTH="33%"><img SRC="Images/arrow-left.png" WIDTH="16" HEIGHT="16" ALIGN="top" ALT="Prev"></TH>
<TH ALIGN="center" WIDTH="33%"><img SRC="Images/arrow-up.png" WIDTH="16" HEIGHT="16" ALIGN="top" ALT="Up"></TH>
<TH ALIGN="right" WIDTH="33%"><img SRC="Images/arrow-right.png" WIDTH="16" HEIGHT="16" ALIGN="top" ALT="Next"></TH>
</TR>
<TR>
<TD ALIGN="left"><A HREF="devguide-6.html">Rect Objects
</A></TD>
<TD ALIGN="center"><A HREF="devguide-4.html">Coordinate Systems
</A></TD>
<TD ALIGN="right"><A HREF="devguide-8.html">Curve Objects
</A></TD>
</TR>
</TABLE>
<HR NOSHADE>
<H2><FONT face="Helvetica,Arial"><A NAME="N1"></A>Transformation Objects
</font></H2>
<P>A transformation object, a trafo object or trafo for short, represents
an affine 2D transformation. Such a transformation is given by 6
numbers: <i>m11</i>, <i>m21</i>, <i>m21</i>, <i>m22</i>, <i>v1</i> and
<i>v2</i>. These coefficients are given in the same order as for a
PostScript transformation matrix.</P>
<P>To apply a trafo to an object you can simple call the trafo with that
object as argument. For details, see the <A HREF="#N9">section
``Operators''</A> below.</P>
<P>Trafo objects are immutable.</P>
<P>If such a transformation <i>T</i> is applied to the point (<i>x</i>,
<i>y</i>) you get</P>
<P>
<PRE>
/ x \ / m11 m12 \ / x \ / v1 \
T * | | = | | | | + | |
\ y / \ m21 m22 / \ y / \ v2 /
</PRE>
or, in homogeneous coordinates:</P>
<P>
<PRE>
/ x \ / m11 m12 v1 \ / x \
| | | | | |
T * | y | = | m21 m22 v2 | | y |
| | | | | |
\ 1 / \ 0 0 1 / \ 1 /
</PRE>
</P>
<H3><FONT face="Helvetica,Arial"><A NAME="N2"></A>Constructors</font></H3>
<P>The following functions create trafo objects:
<DL>
<DT><B><A NAME="N3"></A><tt>Trafo(<i>m11</i>, <i>m21</i>, <i>m21</i>, <i>m22</i>, <i>v1</i>, <i>v2</i>)</tt></B><DD>
<P>The generic constructor: return the transformation given by the
coordinates <i>m11</i>, <i>m21</i>, <i>m21</i>, <i>m22</i>, <i>v1</i>
and <i>v2</i>. These coefficients are given in the same order as
for a PostScript transformation matrix.</P>
<DT><B><A NAME="N4"></A><tt>Scale(<i>factorx</i>[, <i>factory</i>])</tt></B><DD>
<P>Return a trafo object for a scaling by the factors <i>factorx</i>
(in x-direction) and <i>factory</i> (in y-direction). If omitted,
<i>factory</i> defaults to the value of <i>factorx</i>.</P>
<P>Equivalent to <CODE>Trafo(<i>factorx</i>, 0, 0, <i>factory</i>, 0, 0)</CODE>.</P>
<DT><B><A NAME="N5"></A><tt>Translation(<i>offset</i>)</tt></B><DD>
<DT><B><tt>Translation(<i>offset_x</i>, <i>offset_y</i>)</tt></B><DD>
<P>Return a trafo object for a translation by <i>offset</i> (a <A HREF="devguide-5.html#N11">PointSpec</A>) or (<i>offset_x</i>, <i>offset_y</i>).
Equivalent to <CODE>Trafo(1, 0, 0, 1, <i>offset_x</i>,
<i>offset_y</i>)</CODE>.</P>
<DT><B><A NAME="N6"></A><tt>Rotation(<i>angle</i>[, <i>center</i>])</tt></B><DD>
<DT><B><tt>Rotation(<i>angle</i>[, <i>center_x</i>, <i>center_y</i>])</tt></B><DD>
<P>Return a trafo object for a rotation through the angle
<i>angle</i> (counter clockwise in radians) about the center
point <i>center</i> or (<i>center_x</i>, <i>center_y</i>).
<i>center</i> must be a <A HREF="devguide-5.html#N11">PointSpec</A>. If
<i>center</i> is omitted it defaults to the origin.</P>
<P>Equivalent to
<PRE>
s = sin(angle);
c = cos(angle);
offx = cx - c * center_x + s * center_y;
offy = cy - s * center_x - c * center_y;
Trafo(c, s, -s, c, offx, offy);
</PRE>
</P>
</DL>
</P>
<H3><FONT face="Helvetica,Arial"><A NAME="N7"></A>Attributes</font></H3>
<P>A trafo object has six (read only) attributes:
<DL>
<DT><B><CODE>m11</CODE>, <CODE>m21</CODE>, <CODE>m12</CODE>, <CODE>m22</CODE></B><DD>
<DT><B><CODE>v1</CODE>, <CODE>v2</CODE></B><DD>
<P>The coefficients of the trafo as python floats.</P>
</DL>
</P>
<H3><FONT face="Helvetica,Arial"><A NAME="N8"></A>Methods</font></H3>
<P>
<DL>
<DT><B><tt>DocToWin(<i>point</i>)</tt></B><DD>
<DT><B><tt>DocToWin(<i>x</i>, <i>y</i>)</tt></B><DD>
<P>Transform the point and return the result as a tuple of ints.
<i>point</i> is a <A HREF="devguide-5.html#N11">PointSpec</A>. This function
is used to transform document coordinates to window coordinates,
hence the name. (Normally, if you want to transform a point, you
<A HREF="#N9">call the trafo object directly</A>)</P>
<DT><B><tt>DTransform(<i>point</i>)</tt></B><DD>
<DT><B><tt>DTransform(<i>x</i>, <i>y</i>)</tt></B><DD>
<P>Treat the point as a vector and transform it, that is, don't add
<CODE>v1</CODE> and <CODE>v2</CODE>. <i>point</i> is a <A HREF="devguide-5.html#N11">PointSpec</A>.</P>
<DT><B><tt>inverse()</tt></B><DD>
<P>Return the inverse transformation of self. If self cannot be
inverted raise the <CODE>SingularMatrix</CODE> exception.</P>
<DT><B><tt>coeff()</tt></B><DD>
<P>Return the coefficients of the trafo as a tuple (<i>m11</i>,
<i>m21</i>, <i>m21</i>, <i>m22</i>, <i>v1</i>, <i>v2</i>).</P>
<DT><B><tt>matrix()</tt></B><DD>
<P>Return the matrix coefficients of the trafo (<CODE>m11</CODE>, ...,
<CODE>m22</CODE>) as a tuple. The same as <CODE>coeff()[:4]</CODE>.</P>
<DT><B><tt>offset()</tt></B><DD>
<P>Return the translation coefficients as a point object.</P>
</DL>
</P>
<H3><FONT face="Helvetica,Arial"><A NAME="N9"></A>Operators
</font></H3>
<P>Since a transformation is a mapping in the mathematical sense, it is
convenient to make trafo objects callable, so you can treat them like
functions or methods. Depending on the type of the argument the results
are different:
<DL>
<DT><B><CODE>trafo(<i>point</i>)</CODE></B><DD>
<DT><B><CODE>trafo(<i>x</i>, <i>y</i>)</CODE></B><DD>
<P>Return the transformed point. Point can be any <A HREF="devguide-5.html#N11">PointSpec</A>.</P>
<DT><B><CODE>trafo(<i>othertrafo</i>)</CODE></B><DD>
<P>Return the composition of both trafos.</P>
<DT><B><CODE>trafo(<i>rect</i>)</CODE></B><DD>
<P>Return the smallest <A HREF="devguide-6.html">rect object</A> that
contains the transformed corners of the rect object <i>rect</i>.</P>
<P><CODE>InfinityRect</CODE> and <CODE>EmptyRect</CODE> are returned unchanged.</P>
</DL>
</P>
<H3><FONT face="Helvetica,Arial"><A NAME="N10"></A>Constants</font></H3>
<P>
<DL>
<DT><B><CODE>Identity</CODE></B><DD>
<P>The identity transformation (<CODE>Trafo(1, 0, 0, 1, 0, 0)</CODE>)</P>
<DT><B><CODE>IdentityMatrix</CODE></B><DD>
<P>A tuple containing the coefficients of the identity matrix. The
same as <CODE>Identity.matrix()</CODE></P>
<DT><B><CODE>TrafoType</CODE></B><DD>
<P>The trafo type object.</P>
<DT><B><CODE>SingularMatrix</CODE></B><DD>
<P>Exception raised by the <CODE>inverse()</CODE> method.</P>
</DL>
</P>
<HR NOSHADE>
<TABLE WIDTH="100%">
<TR>
<TD ALIGN="left"><A HREF="devguide-6.html">Rect Objects
</A></TD>
<TD ALIGN="center"><A HREF="devguide-4.html">Coordinate Systems
</A></TD>
<TD ALIGN="right"><A HREF="devguide-8.html">Curve Objects
</A></TD>
</TR>
<TR>
<TH ALIGN="left" WIDTH="33%"><img SRC="Images/arrow-left.png" WIDTH="16" HEIGHT="16" ALIGN="top" ALT="Prev"></TH>
<TH ALIGN="center" WIDTH="33%"><img SRC="Images/arrow-up.png" WIDTH="16" HEIGHT="16" ALIGN="top" ALT="Up"></TH>
<TH ALIGN="right" WIDTH="33%"><img SRC="Images/arrow-right.png" WIDTH="16" HEIGHT="16" ALIGN="top" ALT="Next"></TH>
</TR>
</TABLE>
</body>
</html>
