<html> <head> <title>Developer's Guide: Point 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-4.html">Coordinate Systems </A></TD> <TD ALIGN="center"><A HREF="devguide-4.html">Coordinate Systems </A></TD> <TD ALIGN="right"><A HREF="devguide-6.html">Rect Objects </A></TD> </TR> </TABLE> <HR NOSHADE> <H2><FONT face="Helvetica,Arial"><A NAME="N1"></A>Point Objects </font></H2> <P>Point objects represent 2D points or vectors--depending on how you interpret them; their internal representation is identical.</P> <P>While such points could be represented by Python tuples, this special object type requires less memory and overloads some arithmetic operators. A point object is represented by two C `float' numbers, one for each cartesian coordinate.</P> <P>Point objects are immutable.</P> <H3><FONT face="Helvetica,Arial"><A NAME="N2"></A>Constructors</font></H3> <P>There are two constructor functions:</P> <P> <DL> <DT><B><A NAME="N3"></A><tt>Point(<i>x</i>, <i>y</i>)</tt></B><DD> <DT><B><A NAME="N4"></A><tt>Point(<i>sequence</i>)</tt></B><DD> <P>Return a point object with the coordinates <i>x</i> and <i>y</i>. If called with one argument, the argument must be a sequence of two numbers. This form is called a <A HREF="#N11">PointSpec</A></P> <DT><B><A NAME="N5"></A><tt>Polar(<i>r</i>, <i>phi</i>)</tt></B><DD> <DT><B><A NAME="N6"></A><tt>Polar(<i>phi</i>)</tt></B><DD> <P>Return a point object for the polar coordinates <i>r</i> and <i>phi</i>. If <i>r</i> is omitted, it defaults to 1.0.</P> </DL> </P> <H3><FONT face="Helvetica,Arial"><A NAME="N7"></A>Attributes</font></H3> <P>A point object has two (read only) attributes: <DL> <DT><B><CODE>x</CODE></B><DD> <P>The X-coordinate of the point as a python float</P> <DT><B><CODE>y</CODE></B><DD> <P>The Y-coordinate of the point as a python float</P> </DL> </P> <H3><FONT face="Helvetica,Arial"><A NAME="N8"></A>Methods</font></H3> <P>A point object has these methods:</P> <P> <DL> <DT><B><tt>normalized()</tt></B><DD> <P>Return a unit vector pointing in the same direction. If the point's length is 0, raise a ZeroDivisionError.</P> <DT><B><tt>polar()</tt></B><DD> <P>Return a tuple <CODE>(<i>r</i>, <i>phi</i>)</CODE> containing the polar coordinates of the point. <i>phi</i> is in the range -pi to pi. If <i>r</i> is 0, so is <i>phi</i>.</P> </DL> </P> <H3><FONT face="Helvetica,Arial"><A NAME="N9"></A>Operators</font></H3> <P>Point objects implement both the number and the sequence protocol for Python objects. This allows the following operations: <DL> <DT><B>Number Protocol</B><DD> <P> <DL> <DT><B><CODE>+<i>P</i></CODE></B><DD> <P>The same as <i>P</i>.</P> <DT><B><CODE>-<i>P</i></CODE></B><DD> <P>The negated vector <i>P</i>. The same as</P> <P><CODE>Point(-<i>P</i>.x, -<i>P</i>.y)</CODE></P> <DT><B><CODE><i>P1</i> + <i>P2</i></CODE></B><DD> <P>The sum of the vectors <i>P1</i> and <i>P2</i>. The same as</P> <P><CODE>Point(<i>P1</i>.x + <i>P2</i>.x, <i>P1</i>.y + <i>P2</i>.y)</CODE></P> <DT><B><CODE><i>P1</i> - <i>P2</i></CODE></B><DD> <P>The difference of the vectors <i>P1</i> and <i>P2</i>. The same as</P> <P><CODE>Point(<i>P1</i>.x - <i>P2</i>.x, <i>P1</i>.y - <i>P2</i>.y)</CODE></P> <DT><B><CODE><i>P1</i> * <i>P2</i></CODE></B><DD> <P>The dot product of the vectors <i>P1</i> and <i>P2</i>. The same as</P> <P><CODE><i>P1</i>.x * <i>P2</i>.x + <i>P1</i>.y * <i>P2</i>.y</CODE></P> <DT><B><CODE><i>NUMBER</i> * <i>P</i></CODE></B><DD> <DT><B><CODE><i>P</i> * <i>NUMBER</i></CODE></B><DD> <P>The same as</P> <P><CODE>Point(<i>NUMBER</i> * <i>P</i>.x, <i>NUMBER</i> * <i>P</i>.y)</CODE></P> <DT><B><CODE><i>P</i> / <i>NUMBER</i></CODE></B><DD> <P>The same as</P> <P><CODE>Point(<i>P</i>.x / <i>NUMBER</i>, <i>P</i>.y / <i>NUMBER</i>)</CODE></P> <DT><B>abs(<i>P</i>)</B><DD> <P>The length of the vector <i>P</i>. The same as <CODE>math.hypot(<i>P</i>.x, <i>P</i>.y)</CODE>.</P> </DL> </P> <DT><B>Sequence Protocol</B><DD> <P> <DL> <DT><B><CODE>len(<i>P</i>)</CODE></B><DD> <P>Always returns 2.</P> <DT><B><CODE><i>P</i>[<i>i</i>]</CODE></B><DD> <P>For <CODE><i>i</i></CODE> either 0 or 1, this is the same as <CODE><i>P</i>.x</CODE> or <CODE><i>P</i>.y</CODE> respectively. For other values of <i>i</i> raise an IndexError exception.</P> <DT><B><CODE>tuple(<i>P</i>)</CODE></B><DD> <P>Return the coordinates of <i>P</i> as a tuple <CODE>(<i>P</i>.x, <i>P</i>.y)</CODE>.</P> <DT><B><CODE>x, y = <i>P</i></CODE></B><DD> <P>Unpack the point <CODE><i>P</i></CODE>. Equivalent to <CODE>x, y = tuple(<i>P</i>)</CODE></P> </DL> </P> </DL> </P> <P><i>P</i>, <i>P1</i> and <i>P2</i> are point objects, <i>NUMBER</i> is any number that can be converted to a float.</P> <P><CODE>abs</CODE>, <CODE>tuple</CODE>, <CODE>len</CODE> and <CODE>math.hypot</CODE> are the standard Python functions of that name.</P> <H3><FONT face="Helvetica,Arial"><A NAME="N10"></A>Constants</font></H3> <P> <DL> <DT><B><CODE>NullPoint</CODE></B><DD> <P>This is <CODE>Point(0, 0)</CODE></P> <DT><B><CODE>PointType</CODE></B><DD> <P>The point type object.</P> </DL> </P> <H3><FONT face="Helvetica,Arial"><A NAME="N11"></A>PointSpec </font></H3> <P>While point objects are the standard representation for a point, it is sometimes inconvenient (particularly if you are computing the individual coordinates separately) to create a point object just because a function requires that argument type. Therefore, some functions also accept a <EM>PointSpec</EM> instead.</P> <P>An argument that is supposed to be a PointSpec can be either a point object or any sequence of two numbers. Here, number means any object that can be converted to a `double' in C. You could use e. g. a tuple of floats or ints instead of a point object.</P> <HR NOSHADE> <TABLE WIDTH="100%"> <TR> <TD ALIGN="left"><A HREF="devguide-4.html">Coordinate Systems </A></TD> <TD ALIGN="center"><A HREF="devguide-4.html">Coordinate Systems </A></TD> <TD ALIGN="right"><A HREF="devguide-6.html">Rect 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>
