##### 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 | Overlay | PixelArray | pixelcopy | sndarray | surfarray | math Other: camera | cdrom | 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 version 1.9.2pre.

  Changed in version 1.9.4: Removed experimental notice.

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

  Changed in version 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.

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

      New in version 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.

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

      Rotates the vector counterclockwise by the given angle in radians. The length of the vector is not changed.

      New in version 2.0.0.

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

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

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

      New in version 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.

    `rotate_ip_rad`()
      rotates the vector by a given angle in radians in place.
      rotate_ip_rad(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.

      New in version 2.0.0.

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

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

      New in version 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.

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

      Rotates the vector counterclockwise around the x-axis by the given angle in radians. The length of the vector is not changed.

      New in version 2.0.0.

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

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

      New in version 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.

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

      Rotates the vector counterclockwise around the y-axis by the given angle in radians. The length of the vector is not changed.

      New in version 2.0.0.

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

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

      New in version 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.

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

      Rotates the vector counterclockwise around the z-axis by the given angle in radians. The length of the vector is not changed.

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

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

  `pygame.math.``enable_swizzling`()
    globally enables swizzling for vectors.
    enable_swizzling() -> None

    DEPRECATED: Not needed anymore. Will be removed in a later version.

    Enables swizzling for all vectors until `disable_swizzling()` is called. By default swizzling is disabled.

    Lets you get or set multiple coordinates as one attribute, eg `vec.xyz = 1, 2, 3`.

  `pygame.math.``disable_swizzling`()
    globally disables swizzling for vectors.
    disable_swizzling() -> None

    DEPRECATED: Not needed anymore. Will be removed in a later version.

    Disables swizzling for all vectors until `enable_swizzling()` is called. By default swizzling is disabled.

Edit on GitHub