##### pygame documentation

Pygame Home || Help Contents || Reference Index

Most useful stuff: Color | display | draw | event | font | image | key | locals | mixer | mouse | Rect | Surface | time | music | pygame

Advanced stuff: cursors | joystick | mask | sprite | transform | BufferProxy | freetype | gfxdraw | midi | PixelArray | pixelcopy | sndarray | surfarray | math

Other: camera | controller | examples | fastevent | scrap | tests | touch | version

`pygame.math`
  pygame module for vector classes

  The pygame math module currently provides Vector classes in two and three dimensions, `Vector2` and `Vector3` respectively.

  They support the following numerical operations: `vec+vec`, `vec-vec`, `vec*number`, `number*vec`, `vec/number`, `vec//number`, `vec+=vec`, `vec-=vec`, `vec*=number`, `vec/=number`, `vec//=number`.

  All these operations will be performed elementwise. In addition `vec*vec` will perform a scalar-product (a.k.a. dot-product). If you want to multiply every element from vector v with every element from vector w you can use the elementwise method: `v.elementwise() * w`

  The coordinates of a vector can be retrieved or set using attributes or subscripts

      v = pygame.Vector3()

      v.x = 5
      v[1] = 2 * v.x
      print(v[1]) # 10

      v.x == v[0]
      v.y == v[1]
      v.z == v[2]

  Multiple coordinates can be set using slices or swizzling

      v = pygame.Vector2()
      v.xy = 1, 2
      v[:] = 1, 2

  New in pygame 1.9.2pre.

  Changed in pygame 1.9.4: Removed experimental notice.

  Changed in pygame 1.9.4: Allow scalar construction like GLSL Vector2(2) == Vector2(2.0, 2.0)

  Changed in pygame 1.9.4: `pygame.math` pygame module for vector classes required import. More convenient `pygame.Vector2` and `pygame.Vector3`.

  pygame.math.Vector2
    a 2-Dimensional Vector
    Vector2() -> Vector2
    Vector2(int) -> Vector2
    Vector2(float) -> Vector2
    Vector2(Vector2) -> Vector2
    Vector2(x, y) -> Vector2
    Vector2((x, y)) -> Vector2

    Some general information about the `Vector2` class.

    dot()
      calculates the dot- or scalar-product with the other vector
      dot(Vector2) -> float
    cross()
      calculates the cross- or vector-product
      cross(Vector2) -> Vector2

      calculates the third component of the cross-product.

    magnitude()
      returns the Euclidean magnitude of the vector.
      magnitude() -> float

      calculates the magnitude of the vector which follows from the theorem: `vec.magnitude() == math.sqrt(vec.x**2 + vec.y**2)`

    magnitude_squared()
      returns the squared magnitude of the vector.
      magnitude_squared() -> float

      calculates the magnitude of the vector which follows from the theorem: `vec.magnitude_squared() == vec.x**2 + vec.y**2`. This is faster than `vec.magnitude()` because it avoids the square root.

    length()
      returns the Euclidean length of the vector.
      length() -> float

      calculates the Euclidean length of the vector which follows from the Pythagorean theorem: `vec.length() == math.sqrt(vec.x**2 + vec.y**2)`

    length_squared()
      returns the squared Euclidean length of the vector.
      length_squared() -> float

      calculates the Euclidean length of the vector which follows from the Pythagorean theorem: `vec.length_squared() == vec.x**2 + vec.y**2`. This is faster than `vec.length()` because it avoids the square root.

    normalize()
      returns a vector with the same direction but length 1.
      normalize() -> Vector2

      Returns a new vector that has `length` equal to `1` and the same direction as self.

    normalize_ip()
      normalizes the vector in place so that its length is 1.
      normalize_ip() -> None

      Normalizes the vector so that it has `length` equal to `1`. The direction of the vector is not changed.

    is_normalized()
      tests if the vector is normalized i.e. has length == 1.
      is_normalized() -> Bool

      Returns True if the vector has `length` equal to `1`. Otherwise it returns `False`.

    scale_to_length()
      scales the vector to a given length.
      scale_to_length(float) -> None

      Scales the vector so that it has the given length. The direction of the vector is not changed. You can also scale to length `0`. If the vector is the zero vector (i.e. has length `0` thus no direction) a `ValueError` is raised.

    reflect()
      returns a vector reflected of a given normal.
      reflect(Vector2) -> Vector2

      Returns a new vector that points in the direction as if self would bounce of a surface characterized by the given surface normal. The length of the new vector is the same as self's.

    reflect_ip()
      reflect the vector of a given normal in place.
      reflect_ip(Vector2) -> None

      Changes the direction of self as if it would have been reflected of a surface with the given surface normal.

    distance_to()
      calculates the Euclidean distance to a given vector.
      distance_to(Vector2) -> float
    distance_squared_to()
      calculates the squared Euclidean distance to a given vector.
      distance_squared_to(Vector2) -> float
    lerp()
      returns a linear interpolation to the given vector.
      lerp(Vector2, float) -> Vector2

      Returns a Vector which is a linear interpolation between self and the given Vector. The second parameter determines how far between self and other the result is going to be. It must be a value between `0` and `1` where `0` means self and `1` means other will be returned.

    slerp()
      returns a spherical interpolation to the given vector.
      slerp(Vector2, float) -> Vector2

      Calculates the spherical interpolation from self to the given Vector. The second argument - often called t - must be in the range `[-1, 1]`. It parametrizes where - in between the two vectors - the result should be. If a negative value is given the interpolation will not take the complement of the shortest path.

    elementwise()
      The next operation will be performed elementwise.
      elementwise() -> VectorElementwiseProxy

      Applies the following operation to each element of the vector.

    rotate()
      rotates a vector by a given angle in degrees.
      rotate(angle) -> Vector2

      Returns a vector which has the same length as self but is rotated counterclockwise by the given angle in degrees. (Note that due to pygame's inverted y coordinate system, the rotation will look clockwise if displayed).

    rotate_rad()
      rotates a vector by a given angle in radians.
      rotate_rad(angle) -> Vector2

      Returns a vector which has the same length as self but is rotated counterclockwise by the given angle in radians. (Note that due to pygame's inverted y coordinate system, the rotation will look clockwise if displayed).

      New in pygame 2.0.0.

    rotate_ip()
      rotates the vector by a given angle in degrees in place.
      rotate_ip(angle) -> None

      Rotates the vector counterclockwise by the given angle in degrees. The length of the vector is not changed. (Note that due to pygame's inverted y coordinate system, the rotation will look clockwise if displayed).

    rotate_ip_rad()
      rotates the vector by a given angle in radians in place.
      rotate_ip_rad(angle) -> None

      DEPRECATED: Use rotate_rad_ip() instead.

      New in pygame 2.0.0.

      Deprecated since pygame 2.1.1.

    rotate_rad_ip()
      rotates the vector by a given angle in radians in place.
      rotate_rad_ip(angle) -> None

      Rotates the vector counterclockwise by the given angle in radians. The length of the vector is not changed. (Note that due to pygame's inverted y coordinate system, the rotation will look clockwise if displayed).

      New in pygame 2.1.1.

    angle_to()
      calculates the angle to a given vector in degrees.
      angle_to(Vector2) -> float

      Returns the angle between self and the given vector.

    as_polar()
      returns a tuple with radial distance and azimuthal angle.
      as_polar() -> (r, phi)

      Returns a tuple `(r, phi)` where r is the radial distance, and phi is the azimuthal angle.

    from_polar()
      Sets x and y from a polar coordinates tuple.
      from_polar((r, phi)) -> None

      Sets x and y from a tuple (r, phi) where r is the radial distance, and phi is the azimuthal angle.

    project()
      projects a vector onto another.
      project(Vector2) -> Vector2

      Returns the projected vector. This is useful for collision detection in finding the components in a certain direction (e.g. in direction of the wall). For a more detailed explanation see Wikipedia.

      New in pygame 2.0.2.

    copy()
      Returns a copy of itself.
      copy() -> Vector2

      Returns a new Vector2 having the same dimensions.

      New in pygame 2.1.1.

    update()
      Sets the coordinates of the vector.
      update() -> None
      update(int) -> None
      update(float) -> None
      update(Vector2) -> None
      update(x, y) -> None
      update((x, y)) -> None

      Sets coordinates x and y in place.

      New in pygame 1.9.5.

  pygame.math.Vector3
    a 3-Dimensional Vector
    Vector3() -> Vector3
    Vector3(int) -> Vector3
    Vector3(float) -> Vector3
    Vector3(Vector3) -> Vector3
    Vector3(x, y, z) -> Vector3
    Vector3((x, y, z)) -> Vector3

    Some general information about the Vector3 class.

    dot()
      calculates the dot- or scalar-product with the other vector
      dot(Vector3) -> float
    cross()
      calculates the cross- or vector-product
      cross(Vector3) -> Vector3

      calculates the cross-product.

    magnitude()
      returns the Euclidean magnitude of the vector.
      magnitude() -> float

      calculates the magnitude of the vector which follows from the theorem: `vec.magnitude() == math.sqrt(vec.x**2 + vec.y**2 + vec.z**2)`

    magnitude_squared()
      returns the squared Euclidean magnitude of the vector.
      magnitude_squared() -> float

      calculates the magnitude of the vector which follows from the theorem: `vec.magnitude_squared() == vec.x**2 + vec.y**2 + vec.z**2`. This is faster than `vec.magnitude()` because it avoids the square root.

    length()
      returns the Euclidean length of the vector.
      length() -> float

      calculates the Euclidean length of the vector which follows from the Pythagorean theorem: `vec.length() == math.sqrt(vec.x**2 + vec.y**2 + vec.z**2)`

    length_squared()
      returns the squared Euclidean length of the vector.
      length_squared() -> float

      calculates the Euclidean length of the vector which follows from the Pythagorean theorem: `vec.length_squared() == vec.x**2 + vec.y**2 + vec.z**2`. This is faster than `vec.length()` because it avoids the square root.

    normalize()
      returns a vector with the same direction but length 1.
      normalize() -> Vector3

      Returns a new vector that has `length` equal to `1` and the same direction as self.

    normalize_ip()
      normalizes the vector in place so that its length is 1.
      normalize_ip() -> None

      Normalizes the vector so that it has `length` equal to `1`. The direction of the vector is not changed.

    is_normalized()
      tests if the vector is normalized i.e. has length == 1.
      is_normalized() -> Bool

      Returns True if the vector has `length` equal to `1`. Otherwise it returns `False`.

    scale_to_length()
      scales the vector to a given length.
      scale_to_length(float) -> None

      Scales the vector so that it has the given length. The direction of the vector is not changed. You can also scale to length `0`. If the vector is the zero vector (i.e. has length `0` thus no direction) a `ValueError` is raised.

    reflect()
      returns a vector reflected of a given normal.
      reflect(Vector3) -> Vector3

      Returns a new vector that points in the direction as if self would bounce of a surface characterized by the given surface normal. The length of the new vector is the same as self's.

    reflect_ip()
      reflect the vector of a given normal in place.
      reflect_ip(Vector3) -> None

      Changes the direction of self as if it would have been reflected of a surface with the given surface normal.

    distance_to()
      calculates the Euclidean distance to a given vector.
      distance_to(Vector3) -> float
    distance_squared_to()
      calculates the squared Euclidean distance to a given vector.
      distance_squared_to(Vector3) -> float
    lerp()
      returns a linear interpolation to the given vector.
      lerp(Vector3, float) -> Vector3

      Returns a Vector which is a linear interpolation between self and the given Vector. The second parameter determines how far between self an other the result is going to be. It must be a value between `0` and `1`, where `0` means self and `1` means other will be returned.

    slerp()
      returns a spherical interpolation to the given vector.
      slerp(Vector3, float) -> Vector3

      Calculates the spherical interpolation from self to the given Vector. The second argument - often called t - must be in the range `[-1, 1]`. It parametrizes where - in between the two vectors - the result should be. If a negative value is given the interpolation will not take the complement of the shortest path.

    elementwise()
      The next operation will be performed elementwise.
      elementwise() -> VectorElementwiseProxy

      Applies the following operation to each element of the vector.

    rotate()
      rotates a vector by a given angle in degrees.
      rotate(angle, Vector3) -> Vector3

      Returns a vector which has the same length as self but is rotated counterclockwise by the given angle in degrees around the given axis. (Note that due to pygame's inverted y coordinate system, the rotation will look clockwise if displayed).

    rotate_rad()
      rotates a vector by a given angle in radians.
      rotate_rad(angle, Vector3) -> Vector3

      Returns a vector which has the same length as self but is rotated counterclockwise by the given angle in radians around the given axis. (Note that due to pygame's inverted y coordinate system, the rotation will look clockwise if displayed).

      New in pygame 2.0.0.

    rotate_ip()
      rotates the vector by a given angle in degrees in place.
      rotate_ip(angle, Vector3) -> None

      Rotates the vector counterclockwise around the given axis by the given angle in degrees. The length of the vector is not changed. (Note that due to pygame's inverted y coordinate system, the rotation will look clockwise if displayed).

    rotate_ip_rad()
      rotates the vector by a given angle in radians in place.
      rotate_ip_rad(angle, Vector3) -> None

      DEPRECATED: Use rotate_rad_ip() instead.

      New in pygame 2.0.0.

      Deprecated since pygame 2.1.1.

    rotate_rad_ip()
      rotates the vector by a given angle in radians in place.
      rotate_rad_ip(angle, Vector3) -> None

      Rotates the vector counterclockwise around the given axis by the given angle in radians. The length of the vector is not changed. (Note that due to pygame's inverted y coordinate system, the rotation will look clockwise if displayed).

      New in pygame 2.1.1.

    rotate_x()
      rotates a vector around the x-axis by the angle in degrees.
      rotate_x(angle) -> Vector3

      Returns a vector which has the same length as self but is rotated counterclockwise around the x-axis by the given angle in degrees. (Note that due to pygame's inverted y coordinate system, the rotation will look clockwise if displayed).

    rotate_x_rad()
      rotates a vector around the x-axis by the angle in radians.
      rotate_x_rad(angle) -> Vector3

      Returns a vector which has the same length as self but is rotated counterclockwise around the x-axis by the given angle in radians. (Note that due to pygame's inverted y coordinate system, the rotation will look clockwise if displayed).

      New in pygame 2.0.0.

    rotate_x_ip()
      rotates the vector around the x-axis by the angle in degrees in place.
      rotate_x_ip(angle) -> None

      Rotates the vector counterclockwise around the x-axis by the given angle in degrees. The length of the vector is not changed. (Note that due to pygame's inverted y coordinate system, the rotation will look clockwise if displayed).

    rotate_x_ip_rad()
      rotates the vector around the x-axis by the angle in radians in place.
      rotate_x_ip_rad(angle) -> None

      DEPRECATED: Use rotate_x_rad_ip() instead.

      New in pygame 2.0.0.

      Deprecated since pygame 2.1.1.

    rotate_x_rad_ip()
      rotates the vector around the x-axis by the angle in radians in place.
      rotate_x_rad_ip(angle) -> None

      Rotates the vector counterclockwise around the x-axis by the given angle in radians. The length of the vector is not changed. (Note that due to pygame's inverted y coordinate system, the rotation will look clockwise if displayed).

      New in pygame 2.1.1.

    rotate_y()
      rotates a vector around the y-axis by the angle in degrees.
      rotate_y(angle) -> Vector3

      Returns a vector which has the same length as self but is rotated counterclockwise around the y-axis by the given angle in degrees. (Note that due to pygame's inverted y coordinate system, the rotation will look clockwise if displayed).

    rotate_y_rad()
      rotates a vector around the y-axis by the angle in radians.
      rotate_y_rad(angle) -> Vector3

      Returns a vector which has the same length as self but is rotated counterclockwise around the y-axis by the given angle in radians. (Note that due to pygame's inverted y coordinate system, the rotation will look clockwise if displayed).

      New in pygame 2.0.0.

    rotate_y_ip()
      rotates the vector around the y-axis by the angle in degrees in place.
      rotate_y_ip(angle) -> None

      Rotates the vector counterclockwise around the y-axis by the given angle in degrees. The length of the vector is not changed. (Note that due to pygame's inverted y coordinate system, the rotation will look clockwise if displayed).

    rotate_y_ip_rad()
      rotates the vector around the y-axis by the angle in radians in place.
      rotate_y_ip_rad(angle) -> None

      DEPRECATED: Use rotate_y_rad_ip() instead.

      New in pygame 2.0.0.

      Deprecated since pygame 2.1.1.

    rotate_y_rad_ip()
      rotates the vector around the y-axis by the angle in radians in place.
      rotate_y_rad_ip(angle) -> None

      Rotates the vector counterclockwise around the y-axis by the given angle in radians. The length of the vector is not changed. (Note that due to pygame's inverted y coordinate system, the rotation will look clockwise if displayed).

      New in pygame 2.1.1.

    rotate_z()
      rotates a vector around the z-axis by the angle in degrees.
      rotate_z(angle) -> Vector3

      Returns a vector which has the same length as self but is rotated counterclockwise around the z-axis by the given angle in degrees. (Note that due to pygame's inverted y coordinate system, the rotation will look clockwise if displayed).

    rotate_z_rad()
      rotates a vector around the z-axis by the angle in radians.
      rotate_z_rad(angle) -> Vector3

      Returns a vector which has the same length as self but is rotated counterclockwise around the z-axis by the given angle in radians. (Note that due to pygame's inverted y coordinate system, the rotation will look clockwise if displayed).

      New in pygame 2.0.0.

    rotate_z_ip()
      rotates the vector around the z-axis by the angle in degrees in place.
      rotate_z_ip(angle) -> None

      Rotates the vector counterclockwise around the z-axis by the given angle in degrees. The length of the vector is not changed. (Note that due to pygame's inverted y coordinate system, the rotation will look clockwise if displayed).

    rotate_z_ip_rad()
      rotates the vector around the z-axis by the angle in radians in place.
      rotate_z_ip_rad(angle) -> None

      DEPRECATED: Use rotate_z_rad_ip() instead.

      Deprecated since pygame 2.1.1.

    rotate_z_rad_ip()
      rotates the vector around the z-axis by the angle in radians in place.
      rotate_z_rad_ip(angle) -> None

      Rotates the vector counterclockwise around the z-axis by the given angle in radians. The length of the vector is not changed. (Note that due to pygame's inverted y coordinate system, the rotation will look clockwise if displayed).

      New in pygame 2.1.1.

    angle_to()
      calculates the angle to a given vector in degrees.
      angle_to(Vector3) -> float

      Returns the angle between self and the given vector.

    as_spherical()
      returns a tuple with radial distance, inclination and azimuthal angle.
      as_spherical() -> (r, theta, phi)

      Returns a tuple `(r, theta, phi)` where r is the radial distance, theta is the inclination angle and phi is the azimuthal angle.

    from_spherical()
      Sets x, y and z from a spherical coordinates 3-tuple.
      from_spherical((r, theta, phi)) -> None

      Sets x, y and z from a tuple `(r, theta, phi)` where r is the radial distance, theta is the inclination angle and phi is the azimuthal angle.

    project()
      projects a vector onto another.
      project(Vector3) -> Vector3

      Returns the projected vector. This is useful for collision detection in finding the components in a certain direction (e.g. in direction of the wall). For a more detailed explanation see Wikipedia.

      New in pygame 2.0.2.

    copy()
      Returns a copy of itself.
      copy() -> Vector3

      Returns a new Vector3 having the same dimensions.

      New in pygame 2.1.1.

    update()
      Sets the coordinates of the vector.
      update() -> None
      update(int) -> None
      update(float) -> None
      update(Vector3) -> None
      update(x, y, z) -> None
      update((x, y, z)) -> None

      Sets coordinates x, y, and z in place.

      New in pygame 1.9.5.

Edit on GitHub