# Vector functions

## Common Vector Operations

Common Vector manipulation functions.

pyrr.vector.dot(v1, v2)

  Calculates the dot product of two vectors.

  Parameters:

    - v1 (numpy.array) – an Nd array with the final dimension being size 3. (a vector)

    - v2 (numpy.array) – an Nd array with the final dimension being size 3 (a vector)

  Return type:

    If a 1d array was passed, it will be a scalar. Otherwise the result will be an array of scalars with shape vec.ndim with the last dimension being size 1.

pyrr.vector.interpolate(v1, v2, delta)

  Interpolates between 2 arrays of vectors (shape = N,3) by the specified delta (0.0 <= delta <= 1.0).

  Parameters:

    - v1 (numpy.array) – an Nd array with the final dimension being size 3. (a vector)

    - v2 (numpy.array) – an Nd array with the final dimension being size 3. (a vector)

    - delta (float) – The interpolation percentage to apply, where 0.0 <= delta <= 1.0. When delta is 0.0, the result will be v1. When delta is 1.0, the result will be v2. Values inbetween will be an interpolation.

  Return type:

    A numpy.array with shape v1.shape.

pyrr.vector.length(vec)

  Returns the length of an Nd list of vectors or a single vector.

  Parameters:

    vec (numpy.array) –

    an Nd array with the final dimension being size 3 (a vector).

    Single vector:

        numpy.array([ x, y, z ])

    Nd array:

        numpy.array([
            [x1, y1, z1],
            [x2, y2, z2]
        ]).

  Return type:

    If a 1d array was passed, it will be a scalar. Otherwise the result will be an array of scalars with shape vec.ndim with the last dimension being size 1.

pyrr.vector.normalise(vec)

  normalizes an Nd list of vectors or a single vector to unit length.

  The vector is not changed in place.

  For zero-length vectors, the result will be np.nan.

  Parameters:

    vec (numpy.array) –

    an Nd array with the final dimension being vectors

        numpy.array([ x, y, z ])

    Or an NxM array:

        numpy.array([
            [x1, y1, z1],
            [x2, y2, z2]
        ]).

  Return type:

    A numpy.array the normalized value

pyrr.vector.normalize(vec)

  normalizes an Nd list of vectors or a single vector to unit length.

  The vector is not changed in place.

  For zero-length vectors, the result will be np.nan.

  Parameters:

    vec (numpy.array) –

    an Nd array with the final dimension being vectors

        numpy.array([ x, y, z ])

    Or an NxM array:

        numpy.array([
            [x1, y1, z1],
            [x2, y2, z2]
        ]).

  Return type:

    A numpy.array the normalized value

pyrr.vector.set_length(vec, len)

  Resizes an Nd list of vectors or a single vector to ‘length’.

  The vector is not changed in place.

  Parameters:

    vec (numpy.array) –

    an Nd array with the final dimension being size 3 (a vector).

    Single vector::

      numpy.array([ x, y, z ])

    Nd array::
      numpy.array([

        [x1, y1, z1], [x2, y2, z2]

      ]).

  Return type:

    A numpy.array of shape vec.shape.

pyrr.vector.squared_length(vec)

  Calculates the squared length of a vector.

  Useful when trying to avoid the performance penalty of a square root operation.

  Parameters:

    vec (numpy.array) – An Nd numpy.array.

  Return type:

    If one vector is supplied, the result with be a scalar. Otherwise the result will be an array of scalars with shape vec.ndim with the last dimension being size 1.

## Vector3

Provides functions for creating and manipulating 3D vectors.

pyrr.vector3.create(x=0.0, y=0.0, z=0.0, dtype=None)

pyrr.vector3.create_from_matrix44_translation(mat, dtype=None)

pyrr.vector3.create_from_vector4(vector, dtype=None)

  Returns a vector3 and the W component as a tuple.

pyrr.vector3.create_unit_length_x(dtype=None)

pyrr.vector3.create_unit_length_y(dtype=None)

pyrr.vector3.create_unit_length_z(dtype=None)

pyrr.vector3.cross(v1, v2)

  Calculates the cross-product of two vectors.

  Parameters:

    - v1 (numpy.array) – an Nd array with the final dimension being size 3. (a vector)

    - v2 (numpy.array) – an Nd array with the final dimension being size 3. (a vector)

  Return type:

    A np.array with shape v1.shape.

pyrr.vector3.generate_normals(v1, v2, v3, normalize_result=True)

  Generates a normal vector for 3 vertices.

  The result is a normalized vector.

  It is assumed the ordering is counter-clockwise starting at v1, v2 then v3:

      v1      v3
        \    /
          v2

  The vertices are Nd arrays and may be 1d or Nd. As long as the final axis is of size 3.

  For 1d arrays::

        >>> v1 = numpy.array( [ 1.0, 0.0, 0.0 ] )
        >>> v2 = numpy.array( [ 0.0, 0.0, 0.0 ] )
        >>> v3 = numpy.array( [ 0.0, 1.0, 0.0 ] )
        >>> vector.generate_normals( v1, v2, v3 )
        array([ 0.,  0., -1.])

  For Nd arrays::

        >>> v1 = numpy.array( [ [ 1.0, 0.0, 0.0 ], [ 1.0, 0.0, 0.0 ] ] )
        >>> v2 = numpy.array( [ [ 0.0, 0.0, 0.0 ], [ 0.0, 0.0, 0.0 ] ] )
        >>> v3 = numpy.array( [ [ 0.0, 1.0, 0.0 ], [ 0.0, 1.0, 0.0 ] ] )
        >>> vector.generate_normals( v1, v2, v3 )
        array([[ 0.,  0., -1.],
               [ 0.,  0., -1.]])

  Parameters:

    - v1 (numpy.array) – an Nd array with the final dimension being size 3. (a vector)

    - v2 (numpy.array) – an Nd array with the final dimension being size 3. (a vector)

    - v3 (numpy.array) – an Nd array with the final dimension being size 3. (a vector)

    - normalize_result (boolean) – Specifies if the result should be normalized before being returned.

pyrr.vector3.generate_vertex_normals(vertices, index, normalize_result=True)

  Generates a normal vector for each vertex.

  The result is a normalized vector.

  The index array should list the faces by indexing into the vertices array. It is assumed the ordering in index is counter-clockwise.

  The vertices and index arrays are Nd arrays and must be 2d, where the final axis is of size 3.

  An example::

        >>> vertices = numpy.array( [ [ 1.0, 0.0, 0.0 ], [ 0.0, 0.0, 0.0 ], [ 0.0, 1.0, 0.0 ] ] )
        >>> index = numpy.array( [ [ 0, 2, 1 ] ] )
        >>> vector.generate_vertex_normals( vertices, index )
        array([[ 0.,  0., 1.], [ 0.,  0., 1.], [ 0.,  0., 1.]])

  Parameters:

    - vertices (numpy.array) – an 2d array with the final dimension being size 3. (a vector)

    - index (numpy.array) – an Nd array with the final dimension being size 3. (a vector)

    - normalize_result (boolean) – Specifies if the result should be normalized before being returned.

class pyrr.vector3.index
  x = 0

    The index of the X value within the vector

  y = 1

    The index of the Y value within the vector

  z = 2

    The index of the Z value within the vector

class pyrr.vector3.unit
  x = array([1., 0., 0.])

    A vector of unit length in the X-axis. (1.0, 0.0, 0.0)

  y = array([0., 1., 0.])

    A vector of unit length in the Y-axis. (0.0, 1.0, 0.0)

  z = array([0., 0., 1.])

    A vector of unit length in the Z-axis. (0.0, 0.0, 1.0)

## Vector4

Provides functions for creating and manipulating 4D vectors.

pyrr.vector4.create(x=0.0, y=0.0, z=0.0, w=0.0, dtype=None)

pyrr.vector4.create_from_matrix44_translation(mat, dtype=None)

pyrr.vector4.create_from_vector3(vector, w=0.0, dtype=None)

pyrr.vector4.create_unit_length_w(dtype=None)

pyrr.vector4.create_unit_length_x(dtype=None)

pyrr.vector4.create_unit_length_y(dtype=None)

pyrr.vector4.create_unit_length_z(dtype=None)

class pyrr.vector4.index
  w = 3

    The index of the W value within the vector

  x = 0

    The index of the X value within the vector

  y = 1

    The index of the Y value within the vector

  z = 2

    The index of the Z value within the vector

class pyrr.vector4.unit
  x = array([1., 0., 0., 0.])

    A vector of unit length in the X-axis. (1.0, 0.0, 0.0, 0.0)

  y = array([0., 1., 0., 0.])

    A vector of unit length in the Y-axis. (0.0, 1.0, 0.0, 0.0)

  z = array([0., 0., 1., 0.])

    A vector of unit length in the Z-axis. (0.0, 0.0, 1.0, 0.0)