4. Spacial coordinates — Turberfield utilities guide 0.43.0

# Turberfield utilities guide 0.43.0

## 4. Spacial coordinates

The `homogeneous` module provides a coordinate system for physics and game simulations.

class turberfield.utils.homogeneous.Homogeneous(seq, point=None)

  This class implements homogeneous coordinates. A good textbook like Hill and Kelley will explain how these can be used to represent both points and vectors in graphical applications.

  The class acts like a standard Python tuple. You need not create instances of this class directly; use the factory functions below instead.

  static __new__(cls, seq, point=None)

    Class level constructor. Creates a tuple, but adds the phi coordinate if required.

    Parameters:

      - seq (a sequence) – contains the data for the array.

      - point (an optional value) – should be 0 for a vector, 1 for a point, or None to preserve the existing representation.

    Returns:

      a new object.

    Return type:

      Homogeneous

  property magnitude

    A property which gives the magnitude of a Homogeneous vector (position vector in the case of a point).

    Return type:

      number.

The module consists of several functions which operate on Homogeneous coordinates to support 2D or 3D geometric calculations.

turberfield.utils.homogeneous.point(*args)

  Use this factory function to create homogeneous points.

  Parameters:

    args – coordinates for the point.

  Returns:

    a new point object.

  Return type:

    Homogeneous

turberfield.utils.homogeneous.vector(*args)

  Use this factory function to create homogeneous vectors.

  Parameters:

    args – coordinates for the vector.

  Returns:

    a new vector object.

  Return type:

    Homogeneous

turberfield.utils.homogeneous.posvector(point)

  Returns the position vector of a point.

  Parameters:

    point (Homogeneous) – a point.

  Returns:

    a new vector object.

  Return type:

    Homogeneous

turberfield.utils.homogeneous.normalise(vec)

  Scales a vector so its magnitude is unity.

  Parameters:

    vec (Homogeneous) – a vector.

  Returns:

    a new vector object.

  Return type:

    Homogeneous

  Requires:

    vec to be a vector.

turberfield.utils.homogeneous.dot(one, tother)

  Calculates the dot product of two vectors.

  Parameters:

    - one (Homogeneous) – a vector.

    - tother (Homogeneous) – a vector.

  Returns:

    the scalar product.

  Return type:

    number.

turberfield.utils.homogeneous.cross(one, tother)

  Calculates the cross product of two vectors. Works in 3D only.

  Parameters:

    - one (Homogeneous) – a vector.

    - tother (Homogeneous) – a vector.

  Returns:

    a vector.

  Return type:

    Homogeneous.

turberfield.utils.homogeneous.premultiply(hom, *rows)

  Performs a matrix transformation M{Mp} on a point or vector. The matrix is supplied as a number of tuples, each one being a row of the transformation matrix. The matrix must be properly sized to match a homogeneous array, ie: to transform a 3D (4-element) point, you need four rows each containing four values.

  Parameters:

    - hom (Homogeneous) – a point or vector.

    - rows (tuples) – matrix data.

  Returns:

    a point or vector.

  Return type:

    Homogeneous.

  Requires:

    there must be as many rows as there are elements in hom, and each must be the length of hom.

turberfield.utils.homogeneous.maxpick(one, tother)

  Performs elementwise comparison of two points or vectors and keeps the larger of each corresponding element.

  Parameters:

    - one (Homogeneous) – a point or vector.

    - tother (Homogeneous) – a point or vector.

  Returns:

    a point or vector.

  Return type:

    Homogeneous.

turberfield.utils.homogeneous.minpick(one, tother)

  Performs elementwise comparison of two points or vectors and keeps the smaller of each corresponding element.

  Parameters:

    - one (Homogeneous) – a point or vector.

    - tother (Homogeneous) – a point or vector.

  Returns:

    a point or vector.

  Return type:

    Homogeneous.