If you're new to Python
and VPython: Introduction

A VPython tutorial

Pictures of 3D objects

What's new in VPython 6

VPython web site
VPython license
Python web site
Math module (sqrt etc.)
Numpy module (arrays)


This is documentation for Classic VPython (VPython 6), which continues to be available but is no longer supported. See vpython.org for information on installing VPython 7 or using GlowScript VPython. Documentation is available at glowscript.org by clicking Help.

The vector Object

The vector object is not a displayable object but is a powerful aid to 3D computations. Its properties are similar to vectors used in science and engineering. It can be used together with numpy arrays . (numpy is a module added to Python to provide high-speed computational capability through optimized array processing. The numpy module is imported automatically by Visual.)


Returns a vector object with the given components, which are made to be floating-point (that is, 3 is converted to 3.0).

Vectors can be added or subtracted from each other, or multiplied by an ordinary number. For example,

v1 = vector(1,2,3)
v2 = vector(10,20,30)
print(v1+v2) # displays <1 22 33>
print(2*v1)  # displays <2 4 6>

You can refer to individual components of a vector:

v2.x is 10, v2.y is 20, v2.z is 30

It is okay to make a vector from a vector: vector(v2) is still vector(10,20,30).

The form vector(10,12) is shorthand for vector(10,12,0).

A vector is a Python sequence, so v2.x is the same as v2[0], v2.y is the same as v2[1], and v2.z is the same as v2[2].

Vector functions

The following functions are available for working with vectors:

mag(A) = A.mag = |A|, the magnitude of a vector

mag2(A) = A.mag2 = |A|*|A|, the vector's magnitude squared

norm(A) = A.norm() = A/|A|, a unit vector in the direction of the vector

dot(A,B = A.dot(B) = A dot B, the scalar dot product between two vectors

cross(A,B) = A.cross(B), the vector cross product between two vectors

proj(A,B) = A.proj(B) = dot(A,norm(B))*norm(B), the vector projection of A along B

comp(A,B) = A.comp(B) = dot(A,norm(B)), the scalar projection of A along B

diff_angle(A,B) = A.diff_angle(B), the angle between two vectors, in radians

rotate(A,theta,B) = A.rotate(theta,B) = rotate(vector=A, angle=theta, axis=B), result of rotating A through theta around B

astuple(A) = A.astuple(), convert this vector to a tuple, much faster than using tuple(A)

Some examples:

mag( vector ) # calculates length of vector
mag(vector(1,1,1))  # = sqrt(3) = 1.732...
mag2(vector(1,1,1)) # = 3, the magnitude squared

You can also obtain the magnitude in the form v2.mag and the square of the magnitude as v2.mag2.

It is possible to reset the magnitude or the magnitude squared of a vector:

v2.mag = 5 # sets magnitude to 5; no change in direction
v2.mag2 = 2.7 # sets squared magnitude of v2 to 2.7

You can reset the magnitude to 1 with norm():

norm( vector ) # normalized; magnitude of 1
norm(vector(1,1,1)) = vector(1,1,1)/sqrt(3)

You can also write v1.norm(). For convenience, norm(vector(0,0,0)) is calculated to be vector(0,0,0).

To calculate the angle between two vectors (the "difference" of the angles of the two vectors).


You can also write v1.diff_angle(v2). For convenience, if either of the vectors has zero magnitude, the difference of the angles is calculated to be zero.

cross(A,B) gives the cross product of two vectors, a vector perpendicular to the plane defined by A and B, in a direction defined by the right-hand rule: if the fingers of the right hand bend from A toward B, the thumb points in the direction of the cross product. The magnitude of this vector is equal mag(A)*mag(B)*sin(diff_angle(A,B)).

dot(A,B) gives the dot product of two vectors, which is an ordinary number equal to mag(A)*mag(B)*cos(diff_angle(A,B)). If the two vectors are normalized, the dot product gives the cosine of the angle between the vectors, which is often useful.

You can also say vector1.cross(vector2) or vector1.dot(vector2)).

Rotating a vector

There is a function for rotating a vector:

v2 = rotate(v1, angle=theta, axis=(1,1,1))

The angle must be in radians. The default axis is (0,0,1), for a rotation in the xy plane around the z axis. There is no origin for rotating a vector. You can also write v2 = v1.rotate(angle=theta, axis=(1,1,1)). There is also a rotate capability for objects.

There are functions for converting between degrees and radians, where there are 2*pi radians in 360 degrees:

radians(360) is equivalent to 2*pi

degrees(2*pi) is equivalent to 360

Convenient conversion

For convenience VPython automatically converts (a,b,c) into vector(a,b,c), with floating-point values, when creating VPython objects: sphere.pos=(1,2,3) is equivalent to sphere.pos=vector(1.,2.,3.). However, using the form (a,b,c) directly in vector computations will give errors, because (a,b,c) isn't a vector; write vector(a,b,c) instead.

You can convert a vector vec1 to a Python tuple (a,b,c) by tuple(vec1) or by the much faster option vec1.astuple().