# Plane

Provide functions for the creation and manipulation of Planes.

Planes are represented using a numpy.array of shape (4,). The values represent the plane equation using the values A,B,C,D.

The first three values are the normal vector. The fourth value is the distance of the origin from the plane, down the normal. A negative value indicates the origin is behind the plane, relative to the normal.

pyrr.plane.create(normal=None, distance=0.0, dtype=None)

  Creates a plane oriented toward the normal, at distance below the origin. If no normal is provided, the plane will by created at the origin with a normal of [0, 0, 1].

  Negative distance indicates the plane is facing toward the origin.

  Return type:

    numpy.array

  Returns:

    A plane with the specified normal at a distance from the origin of

  -distance.

pyrr.plane.create_from_points(vector1, vector2, vector3, dtype=None)

  Create a plane from 3 co-planar vectors.

  The vectors must all lie on the same plane or an exception will be thrown.

  The vectors must not all be in a single line or the plane is undefined.

  The order the vertices are passed in will determine the normal of the plane.

  Parameters:

    - vector1 (numpy.array) – a vector that lies on the desired plane.

    - vector2 (numpy.array) – a vector that lies on the desired plane.

    - vector3 (numpy.array) – a vector that lies on the desired plane.

  Raises:

    ValueError – raised if the vectors are co-incident (in a single line).

  Return type:

    numpy.array

  Returns:

    A plane that contains the 3 specified vectors.

pyrr.plane.create_from_position(position, normal, dtype=None)

  Creates a plane at position with the normal being above the plane and up being the rotation of the plane.

  Parameters:

    - position (numpy.array) – The position of the plane.

    - normal (numpy.array) – The normal of the plane. Will be normalized during construction.

  Return type:

    numpy.array

  Returns:

    A plane that crosses the specified position with the specified normal.

pyrr.plane.create_xy(invert=False, distance=0.0, dtype=None)

  Create a plane on the XY plane, starting at the origin with +Z being the up vector.

  The plane is distance units along the Z axis. -Z if inverted.

pyrr.plane.create_xz(invert=False, distance=0.0, dtype=None)

  Create a plane on the XZ plane, starting at the origin with +Y being the up vector.

  The plane is distance units along the Y axis. -Y if inverted.

pyrr.plane.create_yz(invert=False, distance=0.0, dtype=None)

  Create a plane on the YZ plane, starting at the origin with +X being the up vector.

  The plane is distance units along the X axis. -X if inverted.

pyrr.plane.distance(plane)

  Distance the plane is from the origin along its the normal.

  Negative value indicates the plane is facing the origin.

pyrr.plane.invert_normal(plane)

  Flips the normal of the plane.

  The plane is not changed in place.

  Return type:

    numpy.array

  Returns:

    The plane with the normal inverted.

pyrr.plane.normal(plane)

  Extracts the normal vector from a plane.

  Parameters:

    plane (numpy.array) – The plane.

  Return type:

    numpy.array

  Returns:

    The normal vector of the plane.

pyrr.plane.position(plane)

  Extracts the position vector from a plane.

  This will be a vector co-incident with the plane’s normal.

  Parameters:

    plane (numpy.array) – The plane.

  Return type:

    numpy.array

  Returns:

    A valid position that lies on the plane.