
pygame.math
 pygame module for vector classes
— a 2Dimensional Vector — a 3Dimensional Vector — globally enables swizzling for vectors. — globally disables swizzling for vectors. The pygame math module currently provides Vector classes in two and three dimensions,
Vector2
andVector3
respectively.They support the following numerical operations:
vec+vec
,vecvec
,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 scalarproduct (a.k.a. dotproduct). 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 convenientpygame.Vector2
andpygame.Vector3
. pygame.math.Vector2¶
 a 2Dimensional VectorVector2() > Vector2Vector2(int) > Vector2Vector2(float) > Vector2Vector2(Vector2) > Vector2Vector2(x, y) > Vector2Vector2((x, y)) > Vector2
— calculates the dot or scalarproduct with the other vector — calculates the cross or vectorproduct — returns the Euclidean magnitude of the vector. — returns the squared magnitude of the vector. — returns the Euclidean length of the vector. — returns the squared Euclidean length of the vector. — returns a vector with the same direction but length 1. — normalizes the vector in place so that its length is 1. — tests if the vector is normalized i.e. has length == 1. — scales the vector to a given length. — returns a vector reflected of a given normal. — reflect the vector of a given normal in place. — calculates the Euclidean distance to a given vector. — calculates the squared Euclidean distance to a given vector. — returns a linear interpolation to the given vector. — returns a spherical interpolation to the given vector. — The next operation will be performed elementwise. — rotates a vector by a given angle in degrees. — rotates a vector by a given angle in radians. — rotates the vector by a given angle in degrees in place. — rotates the vector by a given angle in radians in place. — calculates the angle to a given vector in degrees. — returns a tuple with radial distance and azimuthal angle. — Sets x and y from a polar coordinates tuple. — projects a vector onto another. — Sets the coordinates of the vector. Some general information about the
Vector2
class. dot()¶
 calculates the dot or scalarproduct with the other vectordot(Vector2) > float
 cross()¶
 calculates the cross or vectorproductcross(Vector2) > Vector2
calculates the third component of the crossproduct.
 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 thanvec.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 thanvec.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 to1
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 to1
. 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 to1
. Otherwise it returnsFalse
.
 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 length0
thus no direction) aValueError
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
and1
where0
means self and1
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
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.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.
 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.
 update()¶
 Sets the coordinates of the vector.update() > Noneupdate(int) > Noneupdate(float) > Noneupdate(Vector2) > Noneupdate(x, y) > Noneupdate((x, y)) > None
Sets coordinates x and y in place.
New in pygame 1.9.5.
 pygame.math.Vector3¶
 a 3Dimensional VectorVector3() > Vector3Vector3(int) > Vector3Vector3(float) > Vector3Vector3(Vector3) > Vector3Vector3(x, y, z) > Vector3Vector3((x, y, z)) > Vector3
— calculates the dot or scalarproduct with the other vector — calculates the cross or vectorproduct — returns the Euclidean magnitude of the vector. — returns the squared Euclidean magnitude of the vector. — returns the Euclidean length of the vector. — returns the squared Euclidean length of the vector. — returns a vector with the same direction but length 1. — normalizes the vector in place so that its length is 1. — tests if the vector is normalized i.e. has length == 1. — scales the vector to a given length. — returns a vector reflected of a given normal. — reflect the vector of a given normal in place. — calculates the Euclidean distance to a given vector. — calculates the squared Euclidean distance to a given vector. — returns a linear interpolation to the given vector. — returns a spherical interpolation to the given vector. — The next operation will be performed elementwise. — rotates a vector by a given angle in degrees. — rotates a vector by a given angle in radians. — rotates the vector by a given angle in degrees in place. — rotates the vector by a given angle in radians in place. — rotates a vector around the xaxis by the angle in degrees. — rotates a vector around the xaxis by the angle in radians. — rotates the vector around the xaxis by the angle in degrees in place. — rotates the vector around the xaxis by the angle in radians in place. — rotates a vector around the yaxis by the angle in degrees. — rotates a vector around the yaxis by the angle in radians. — rotates the vector around the yaxis by the angle in degrees in place. — rotates the vector around the yaxis by the angle in radians in place. — rotates a vector around the zaxis by the angle in degrees. — rotates a vector around the zaxis by the angle in radians. — rotates the vector around the zaxis by the angle in degrees in place. — rotates the vector around the zaxis by the angle in radians in place. — calculates the angle to a given vector in degrees. — returns a tuple with radial distance, inclination and azimuthal angle. — Sets x, y and z from a spherical coordinates 3tuple. — projects a vector onto another. — Sets the coordinates of the vector. Some general information about the Vector3 class.
 dot()¶
 calculates the dot or scalarproduct with the other vectordot(Vector3) > float
 cross()¶
 calculates the cross or vectorproductcross(Vector3) > Vector3
calculates the crossproduct.
 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 thanvec.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 thanvec.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 to1
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 to1
. 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 to1
. Otherwise it returnsFalse
.
 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 length0
thus no direction) aValueError
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
and1
, where0
means self and1
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
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.0.0.
 rotate_x()¶
 rotates a vector around the xaxis 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 xaxis 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 xaxis 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 xaxis 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 xaxis by the angle in degrees in place.rotate_x_ip(angle) > None
Rotates the vector counterclockwise around the xaxis 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 xaxis by the angle in radians in place.rotate_x_ip_rad(angle) > None
Rotates the vector counterclockwise around the xaxis 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.0.0.
 rotate_y()¶
 rotates a vector around the yaxis 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 yaxis 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 yaxis 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 yaxis 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 yaxis by the angle in degrees in place.rotate_y_ip(angle) > None
Rotates the vector counterclockwise around the yaxis 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 yaxis by the angle in radians in place.rotate_y_ip_rad(angle) > None
Rotates the vector counterclockwise around the yaxis 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.0.0.
 rotate_z()¶
 rotates a vector around the zaxis 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 zaxis 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 zaxis 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 zaxis 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 zaxis by the angle in degrees in place.rotate_z_ip(angle) > None
Rotates the vector counterclockwise around the zaxis 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 zaxis by the angle in radians in place.rotate_z_ip_rad(angle) > None
Rotates the vector counterclockwise around the zaxis 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).
 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 3tuple.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.
 update()¶
 Sets the coordinates of the vector.update() > Noneupdate(int) > Noneupdate(float) > Noneupdate(Vector3) > Noneupdate(x, y, z) > Noneupdate((x, y, z)) > None
Sets coordinates x, y, and z in place.
New in pygame 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