3. Spacial coordinates — Turberfield utilities guide 0.34.0

# Turberfield utilities guide 0.34.0

## 3. Spacial coordinates

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

class `turberfield.utils.homogeneous.` `Homogeneous`

  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__`(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

  `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.