Developer's Guide: Point Objects

Coordinate Systems | Coordinate Systems | Rect Objects

## Point Objects

Point objects represent 2D points or vectors--depending on how you interpret them; their internal representation is identical.

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.

Point objects are immutable.

### Constructors

There are two constructor functions:

`Point(x, y)`
`Point(sequence)`

  Return a point object with the coordinates x and y. If called with one argument, the argument must be a sequence of two numbers. This form is called a PointSpec

`Polar(r, phi)`
`Polar(phi)`

  Return a point object for the polar coordinates r and phi. If r is omitted, it defaults to 1.0.

### Attributes

A point object has two (read only) attributes:

`x`

  The X-coordinate of the point as a python float

`y`

  The Y-coordinate of the point as a python float

### Methods

A point object has these methods:

`normalized()`

  Return a unit vector pointing in the same direction. If the point's length is 0, raise a ZeroDivisionError.

`polar()`

  Return a tuple `(r, phi)` containing the polar coordinates of the point. phi is in the range -pi to pi. If r is 0, so is phi.

### Operators

Point objects implement both the number and the sequence protocol for Python objects. This allows the following operations:

Number Protocol

  `+P`

    The same as P.

  `-P`

    The negated vector P. The same as

    `Point(-P.x, -P.y)`

  `P1 + P2`

    The sum of the vectors P1 and P2. The same as

    `Point(P1.x + P2.x, P1.y + P2.y)`

  `P1 - P2`

    The difference of the vectors P1 and P2. The same as

    `Point(P1.x - P2.x, P1.y - P2.y)`

  `P1 * P2`

    The dot product of the vectors P1 and P2. The same as

    `P1.x * P2.x + P1.y * P2.y`

  `NUMBER * P`
  `P * NUMBER`

    The same as

    `Point(NUMBER * P.x, NUMBER * P.y)`

  `P / NUMBER`

    The same as

    `Point(P.x / NUMBER, P.y / NUMBER)`

  abs(P)

    The length of the vector P. The same as `math.hypot(P.x, P.y)`.

Sequence Protocol

  `len(P)`

    Always returns 2.

  `P[i]`

    For `i` either 0 or 1, this is the same as `P.x` or `P.y` respectively. For other values of i raise an IndexError exception.

  `tuple(P)`

    Return the coordinates of P as a tuple `(P.x, P.y)`.

  `x, y = P`

    Unpack the point `P`. Equivalent to `x, y = tuple(P)`

P, P1 and P2 are point objects, NUMBER is any number that can be converted to a float.

`abs`, `tuple`, `len` and `math.hypot` are the standard Python functions of that name.

### Constants

`NullPoint`

  This is `Point(0, 0)`

`PointType`

  The point type object.

### PointSpec

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 PointSpec instead.

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.

Coordinate Systems | Coordinate Systems | Rect Objects