1
.. include:: common.txt
6
.. module:: pygame.math
7
:synopsis: pygame module for vector classes
9
| :sl:`pygame module for vector classes`
11
!!!EXPERIMENTAL!!! Note: This Modul is still in development and the ``API``
12
might change. Please report bug and suggestions to pygame-users@seul.org
14
The pygame math module currently provides Vector classes in two and three
15
dimensions, Vector2 and Vector3 respectively.
17
They support the following numerical operations: vec+vec, vec-vec, vec*number,
18
number*vec, vec/number, vec//number, vec+=vec, vec-=vec, vec*=number,
19
vec/=number, vec//=number. All these operations will be performed elementwise.
20
In addition vec*vec will perform a scalar-product (a.k.a. dot-product). If you
21
want to multiply every element from vector v with every element from vector w
22
you can use the elementwise method: ``v.elementwise()`` ``\*`` w
26
.. function:: enable_swizzling
28
| :sl:`globally enables swizzling for vectors.`
29
| :sg:`enable_swizzling() -> None`
31
Enables swizzling for all vectors until ``disable_swizzling()`` is called.
32
By default swizzling is disabled.
34
.. ## pygame.math.enable_swizzling ##
36
.. function:: disable_swizzling
38
| :sl:`globally disables swizzling for vectors.`
39
| :sg:`disable_swizzling() -> None`
41
Disables swizzling for all vectors until ``enable_swizzling()`` is called.
42
By default swizzling is disabled.
44
.. ## pygame.math.disable_swizzling ##
48
| :sl:`a 2-Dimensional Vector`
49
| :sg:`Vector2() -> Vector2`
50
| :sg:`Vector2(Vector2) -> Vector2`
51
| :sg:`Vector2(x, y) -> Vector2`
52
| :sg:`Vector2((x, y)) -> Vector2`
54
Some general information about the Vector2 class.
58
| :sl:`calculates the dot- or scalar-product with the other vector`
59
| :sg:`dot(Vector2) -> float`
65
| :sl:`calculates the cross- or vector-product`
66
| :sg:`cross(Vector2) -> float`
68
calculates the third component of the cross-product.
70
.. ## Vector2.cross ##
74
| :sl:`returns the euclidic length of the vector.`
75
| :sg:`length() -> float`
77
calculates the euclidic length of the vector which follows from the
78
Pythagorean theorem: ``vec.length()`` ==
79
``math.sqrt(vec.x**2 + vec.y**2)``
81
.. ## Vector2.length ##
83
.. method:: length_squared
85
| :sl:`returns the squared euclidic length of the vector.`
86
| :sg:`length_squared() -> float`
88
calculates the euclidic length of the vector which follows from the
89
Pythagorean theorem: ``vec.length_squared()`` == vec.x**2 + vec.y**2 This
90
is faster than ``vec.length()`` because it avoids the square root.
92
.. ## Vector2.length_squared ##
96
| :sl:`returns a vector with the same direction but length 1.`
97
| :sg:`normalize() -> Vector2`
99
Returns a new vector that has length == 1 and the same direction as self.
101
.. ## Vector2.normalize ##
103
.. method:: normalize_ip
105
| :sl:`normalizes the vector in place so that its length is 1.`
106
| :sg:`normalize_ip() -> None`
108
Normalizes the vector so that it has length == 1. The direction of the
109
vector is not changed.
111
.. ## Vector2.normalize_ip ##
113
.. method:: is_normalized
115
| :sl:`tests if the vector is normalized i.e. has length == 1.`
116
| :sg:`is_normalized() -> Bool`
118
Returns True if the vector has length == 1. Otherwise it returns False.
120
.. ## Vector2.is_normalized ##
122
.. method:: scale_to_length
124
| :sl:`scales the vector to a given length.`
125
| :sg:`scale_to_length(float) -> None`
127
Scales the vector so that it has the given length. The direction of the
128
vector is not changed. You can also scale to length 0. If the vector is
129
the zero vector (i.e. has length 0 thus no direction) an
130
ZeroDivisionError is raised.
132
.. ## Vector2.scale_to_length ##
136
| :sl:`returns a vector reflected of a given normal.`
137
| :sg:`reflect(Vector2) -> Vector2`
139
Returns a new vector that points in the direction as if self would bounce
140
of a surface characterized by the given surface normal. The length of the
141
new vector is the same as self's.
143
.. ## Vector2.reflect ##
145
.. method:: reflect_ip
147
| :sl:`reflect the vector of a given normal in place.`
148
| :sg:`reflect_ip(Vector2) -> None`
150
Changes the direction of self as if it would have been reflected of a
151
surface with the given surface normal.
153
.. ## Vector2.reflect_ip ##
155
.. method:: distance_to
157
| :sl:`calculates the euclidic distance to a given vector.`
158
| :sg:`distance_to(Vector2) -> float`
160
.. ## Vector2.distance_to ##
162
.. method:: distance_squared_to
164
| :sl:`calculates the squared euclidic distance to a given vector.`
165
| :sg:`distance_squared_to(Vector2) -> float`
167
.. ## Vector2.distance_squared_to ##
171
| :sl:`returns a linear interpolation to the given vector.`
172
| :sg:`lerp(Vector2, float) -> Vector2`
174
Returns a Vector which is a linear interpolation between self and the
175
given Vector. The second parameter determines how far between self an
176
other the result is going to be. It must be a value between 0 and 1 where
177
0 means self an 1 means other will be returned.
179
.. ## Vector2.lerp ##
183
| :sl:`returns a spherical interpolation to the given vector.`
184
| :sg:`slerp(Vector2, float) -> Vector2`
186
Calculates the spherical interpolation from self to the given Vector. The
187
second argument - often called t - must be in the range [-1, 1]. It
188
parametrizes where - in between the two vectors - the result should be.
189
If a negative value is given the interpolation will not take the
190
complement of the shortest path.
192
.. ## Vector2.slerp ##
194
.. method:: elementwise
196
| :sl:`The next operation will be performed elementwize.`
197
| :sg:`elementwise() -> VectorElementwizeProxy`
199
Applies the following operation to each element of the vector.
201
.. ## Vector2.elementwise ##
205
| :sl:`rotates a vector by a given angle in degrees.`
206
| :sg:`rotate(float) -> Vector2`
208
Returns a vector which has the same length as self but is rotated
209
counterclockwise by the given angle in degrees.
211
.. ## Vector2.rotate ##
213
.. method:: rotate_ip
215
| :sl:`rotates the vector by a given angle in degrees in place.`
216
| :sg:`rotate_ip(float) -> None`
218
Rotates the vector counterclockwise by the given angle in degrees. The
219
length of the vector is not changed.
221
.. ## Vector2.rotate_ip ##
225
| :sl:`calculates the angle to a given vector in degrees.`
226
| :sg:`angle_to(Vector2) -> float`
228
Returns the angle between self and the given vector.
230
.. ## Vector2.angle_to ##
234
| :sl:`returns a tuple with radial distance and azimuthal angle.`
235
| :sg:`as_polar() -> (r, phi)`
237
Returns a tuple (r, phi) where r is the radial distance, and phi is the
240
.. ## Vector2.as_polar ##
242
.. method:: from_polar
244
| :sl:`Sets x and y from a polar coordinates tuple.`
245
| :sg:`from_polar((r, phi)) -> None`
247
Sets x and y from a tuple (r, phi) where r is the radial distance, and
248
phi is the azimuthal angle.
250
.. ## Vector2.from_polar ##
252
.. ## pygame.math.Vector2 ##
256
| :sl:`a 3-Dimensional Vector`
257
| :sg:`Vector3() -> Vector3`
258
| :sg:`Vector3(Vector3) -> Vector3`
259
| :sg:`Vector3(x, y, z) -> Vector3`
260
| :sg:`Vector3((x, y, z)) -> Vector3`
262
Some general information about the Vector3 class.
266
| :sl:`calculates the dot- or scalar-product with the other vector`
267
| :sg:`dot(Vector3) -> float`
273
| :sl:`calculates the cross- or vector-product`
274
| :sg:`cross(Vector3) -> float`
276
calculates the cross-product.
278
.. ## Vector3.cross ##
282
| :sl:`returns the euclidic length of the vector.`
283
| :sg:`length() -> float`
285
calculates the euclidic length of the vector which follows from the
286
Pythagorean theorem: ``vec.length()`` ==
287
``math.sqrt(vec.x**2 + vec.y**2 + vec.z**2)``
289
.. ## Vector3.length ##
291
.. method:: length_squared
293
| :sl:`returns the squared euclidic length of the vector.`
294
| :sg:`length_squared() -> float`
296
calculates the euclidic length of the vector which follows from the
297
Pythagorean theorem: ``vec.length_squared()`` == vec.x**2 + vec.y**2 +
298
vec.z**2 This is faster than ``vec.length()`` because it avoids the
301
.. ## Vector3.length_squared ##
303
.. method:: normalize
305
| :sl:`returns a vector with the same direction but length 1.`
306
| :sg:`normalize() -> Vector3`
308
Returns a new vector that has length == 1 and the same direction as self.
310
.. ## Vector3.normalize ##
312
.. method:: normalize_ip
314
| :sl:`normalizes the vector in place so that its length is 1.`
315
| :sg:`normalize_ip() -> None`
317
Normalizes the vector so that it has length == 1. The direction of the
318
vector is not changed.
320
.. ## Vector3.normalize_ip ##
322
.. method:: is_normalized
324
| :sl:`tests if the vector is normalized i.e. has length == 1.`
325
| :sg:`is_normalized() -> Bool`
327
Returns True if the vector has length == 1. Otherwise it returns False.
329
.. ## Vector3.is_normalized ##
331
.. method:: scale_to_length
333
| :sl:`scales the vector to a given length.`
334
| :sg:`scale_to_length(float) -> None`
336
Scales the vector so that it has the given length. The direction of the
337
vector is not changed. You can also scale to length 0. If the vector is
338
the zero vector (i.e. has length 0 thus no direction) an
339
ZeroDivisionError is raised.
341
.. ## Vector3.scale_to_length ##
345
| :sl:`returns a vector reflected of a given normal.`
346
| :sg:`reflect(Vector3) -> Vector3`
348
Returns a new vector that points in the direction as if self would bounce
349
of a surface characterized by the given surface normal. The length of the
350
new vector is the same as self's.
352
.. ## Vector3.reflect ##
354
.. method:: reflect_ip
356
| :sl:`reflect the vector of a given normal in place.`
357
| :sg:`reflect_ip(Vector3) -> None`
359
Changes the direction of self as if it would have been reflected of a
360
surface with the given surface normal.
362
.. ## Vector3.reflect_ip ##
364
.. method:: distance_to
366
| :sl:`calculates the euclidic distance to a given vector.`
367
| :sg:`distance_to(Vector3) -> float`
369
.. ## Vector3.distance_to ##
371
.. method:: distance_squared_to
373
| :sl:`calculates the squared euclidic distance to a given vector.`
374
| :sg:`distance_squared_to(Vector3) -> float`
376
.. ## Vector3.distance_squared_to ##
380
| :sl:`returns a linear interpolation to the given vector.`
381
| :sg:`lerp(Vector3, float) -> Vector3`
383
Returns a Vector which is a linear interpolation between self and the
384
given Vector. The second parameter determines how far between self an
385
other the result is going to be. It must be a value between 0 and 1 where
386
0 means self an 1 means other will be returned.
388
.. ## Vector3.lerp ##
392
| :sl:`returns a spherical interpolation to the given vector.`
393
| :sg:`slerp(Vector3, float) -> Vector3`
395
Calculates the spherical interpolation from self to the given Vector. The
396
second argument - often called t - must be in the range [-1, 1]. It
397
parametrizes where - in between the two vectors - the result should be.
398
If a negative value is given the interpolation will not take the
399
complement of the shortest path.
401
.. ## Vector3.slerp ##
403
.. method:: elementwise
405
| :sl:`The next operation will be performed elementwize.`
406
| :sg:`elementwise() -> VectorElementwizeProxy`
408
Applies the following operation to each element of the vector.
410
.. ## Vector3.elementwise ##
414
| :sl:`rotates a vector by a given angle in degrees.`
415
| :sg:`rotate(Vector3, float) -> Vector3`
417
Returns a vector which has the same length as self but is rotated
418
counterclockwise by the given angle in degrees around the given axis.
420
.. ## Vector3.rotate ##
422
.. method:: rotate_ip
424
| :sl:`rotates the vector by a given angle in degrees in place.`
425
| :sg:`rotate_ip(Vector3, float) -> None`
427
Rotates the vector counterclockwise around the given axis by the given
428
angle in degrees. The length of the vector is not changed.
430
.. ## Vector3.rotate_ip ##
434
| :sl:`rotates a vector around the x-axis by the angle in degrees.`
435
| :sg:`rotate_x(float) -> Vector3`
437
Returns a vector which has the same length as self but is rotated
438
counterclockwise around the x-axis by the given angle in degrees.
440
.. ## Vector3.rotate_x ##
442
.. method:: rotate_x_ip
444
| :sl:`rotates the vector around the x-axis by the angle in degrees in place.`
445
| :sg:`rotate_x_ip(float) -> None`
447
Rotates the vector counterclockwise around the x-axis by the given angle
448
in degrees. The length of the vector is not changed.
450
.. ## Vector3.rotate_x_ip ##
454
| :sl:`rotates a vector around the y-axis by the angle in degrees.`
455
| :sg:`rotate_y(float) -> Vector3`
457
Returns a vector which has the same length as self but is rotated
458
counterclockwise around the y-axis by the given angle in degrees.
460
.. ## Vector3.rotate_y ##
462
.. method:: rotate_y_ip
464
| :sl:`rotates the vector around the y-axis by the angle in degrees in place.`
465
| :sg:`rotate_y_ip(float) -> None`
467
Rotates the vector counterclockwise around the y-axis by the given angle
468
in degrees. The length of the vector is not changed.
470
.. ## Vector3.rotate_y_ip ##
474
| :sl:`rotates a vector around the z-axis by the angle in degrees.`
475
| :sg:`rotate_z(float) -> Vector3`
477
Returns a vector which has the same length as self but is rotated
478
counterclockwise around the z-axis by the given angle in degrees.
480
.. ## Vector3.rotate_z ##
482
.. method:: rotate_z_ip
484
| :sl:`rotates the vector around the z-axis by the angle in degrees in place.`
485
| :sg:`rotate_z_ip(float) -> None`
487
Rotates the vector counterclockwise around the z-axis by the given angle
488
in degrees. The length of the vector is not changed.
490
.. ## Vector3.rotate_z_ip ##
494
| :sl:`calculates the angle to a given vector in degrees.`
495
| :sg:`angle_to(Vector3) -> float`
497
Returns the angle between self and the given vector.
499
.. ## Vector3.angle_to ##
501
.. method:: as_spherical
503
| :sl:`returns a tuple with radial distance, inclination and azimuthal angle.`
504
| :sg:`as_spherical() -> (r, theta, phi)`
506
Returns a tuple (r, theta, phi) where r is the radial distance, theta is
507
the inclination angle and phi is the azimuthal angle.
509
.. ## Vector3.as_spherical ##
511
.. method:: from_spherical
513
| :sl:`Sets x, y and z from a spherical coordinates 3-tuple.`
514
| :sg:`from_spherical((r, theta, phi)) -> None`
516
Sets x, y and z from a tuple (r, theta, phi) where r is the radial
517
distance, theta is the inclination angle and phi is the azimuthal angle.
519
.. ## Vector3.from_spherical ##
523
.. ## pygame.math.Vector3 ##
added
removed
docs/reST/ref/math.rst
