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.

Controlling One or More VPython Displays

Initially, there is one VPython display named scene. Display objects do not create windows on the screen unless they are used, so if you immediately create your own display object early in your program you will not need to worry about scene. If you simply begin creating objects such as sphere they will go into scene.

display() Creates a display with the specified attributes, makes it the selected display, and returns it. For example, the following creates another VPython display 600 by 200, with its upper left corner at the upper left corner of the screen (y is measured down from the top of the screen), with 'Examples of Tetrahedrons' in the title bar, centered on location (5,0,0), and with a background color of cyan filling the window.

scene2 = display(title='Examples of Tetrahedrons',
     x=0, y=0, width=600, height=200,
     center=(5,0,0), background=(0,1,1))

Exiting a VPython program

By default, one exits from a VPython program by clicking the close box on a display window (and the exit option described below lets you specify whether all windows close or just the display window that was clicked). You can also exit a VPython program under program control:


General-purpose options

select() Makes the specified display the "selected display", so that objects will be drawn into this display by default; e.g. scene.select()

Executing myscene = display.get_selected() returns a reference to the display in which objects are currently being created.

foreground Set color to be used by default in creating new objects such as sphere; default is white. Example: scene.foreground = (1,0,0)

background Set color to be used to fill the display window; default is black.

ambient Color of nondirectional ("ambient") lighting. Default is color.gray(0.2); for compatibility with earlier versions of VPython, this can be expressed as scene.ambient=0.2.

lights List of light objects created for this display. By default, scene.lights is this list:
   [distant_light(direction=(0.22, 0.44, 0.88), color=color.gray(0.8)),
   distant_light(direction=(-0.88, -0.22, -0.44), color=color.gray(0.3))]
These are equivalent to the default lights in VPython prior to version 5. For how to create your own distant and local lights, see Lighting.

To obtain camera position, see Mouse Interactions.

cursor.visible By setting scene.cursor.visible = False, the mouse cursor becomes invisible. This is often appropriate while dragging an object using the mouse. Restore the cursor with scene.cursor.visible = True. If scene is part of a wxPython window that includes other elements such as buttons, and you want to hide the cursor everywhere in a window named w, use w.cursor.visible = False (this does not currently work on a Macintosh).

objects A list of all the visible objects in the display; invisible objects and lights are not listed (scene.lights is a list of existing lights). For example, the following makes all visible boxes in the scene red:

    for obj in scene2.objects:
        if isinstance(obj, box):
            obj.color = color.red

window You can create a wxPython window with w = window(....) and place various widgets in it such as buttons and sliders, and VPython 3D graphics displays or graphs, like this:d = display(window=w, ....) or g = gdisplay(window=w, ....). You have to specify a wxPython window when you create the VPython display or gdisplay; you can't create a display and then later choose to assign d.window = w. The widgets description includes details on the attributes of a wxPython window object.

delete You can delete a display named d with d.delete() without stopping your program, then create a new display. The delete function deletes all the objects and lights before deleting the display itself. If the display is inside a wxPython window, the window and other widgets in the window remain. You can delete an entire wxPython window named w with all its widgets with w.delete(). You can delete all windows and displays with window.delete_all(). Note that it is window.delete_all(), not w.delete_all(), because the operation affects all windows, not one particular window.

stereo Stereoscopic option; scene.stereo = 'redcyan' will generate a scene for the left eye and a scene for the right eye, to be viewed with red-cyan glasses, with the red lens over the left eye. (There are also 'redblue' and 'yellowblue' options; note that objects that were not originally white may be somewhat dim.)

Setting scene.stereo = 'crosseyed' produces side-by-side images which if small enough can be seen in 3D by crossing your eyes but focusing on the screen (this takes some practice). Setting scene.stereo = 'passive' produces side-by-side images which if small enough can be seen in 3D by looking "wall-eyed", looking into the far distance but focusing on the screen (this too takes some practice), or by using inexpensive stereoscopic viewers.

scene.stereo = 'active'
will render alternating left eye/right eye images for viewing through shutter glasses if the graphics system supports quad buffered stereo. If stereo equipment is not available, setting the option has no effect. You can also use scene.stereo = 'passive' with quad buffered stereo for display using two polarized projectors (for stereo viewing using simple passive polarized glasses). Quad buffered 'active' stereo is only available on specialised graphics systems that have the necessary hardware and shutter glass connector, such as 120 Hz displays and NVIDIA Quadro graphics cards. It generates the illusion of depth by rendering each frame twice from slightly different viewpoints corresponding to the left and right eyes. Special shutter glasses are synchronised with the alternating images so that each eye sees only the matching frame, and your brain does the rest. It's called 'quad buffered' because there is an OpenGL buffer per eye, both double-buffered for smooth updating.

stereodepth By default, the front of the scene is located at the location of the physical screen, which reduces eye strain. Setting scene.stereodepth = 1 moves the center of the scene to the location of the physical screen, with the front half of the scene seeming to stick dramatically out of the screen. scene.stereodepth = 2 moves the scene fully in front of the physical screen, for maximally dramatic stereo effect.

Controlling the display

The attributes x, y, width, height, and title cannot be changed while a window is active; they are used to create a display, not to change one. If these parameters are such as to place part of the display off screen, the width and height are adjusted to fit all of the display onto the screen.

x, y Position of the display on the screen or within a wxPython window (pixels from upper left)

width, height Width and height of the display area in pixels: scene.height = 200 (includes title bar).

title Text in the window's title bar: scene.title = 'Planetary Orbit'

fullscreen Full screen option; scene2.fullscreen = True makes the display named scene2 take up the entire screen. If scene2 is part of a wxPython window that includes other elements such as buttons, scene2.fullscreen = True gives an error; if the window is named w, use w.fullscreen = True. Currently fullscreen has no effect on a Macintosh.

visible Make sure the display is visible; scene2.visible = True makes the display named scene2 visible. This is automatically called when new primitives are added to the display, or the mouse is referenced. Setting visible to False hides the display. If scene2 is part of a wxPython window that includes other elements such as buttons, scene2.visible = False gives an error; if the window is named w, use w.visible = False.

exit If sceneb.exit is False, the program does not quit when the close box of the sceneb display is clicked. The default is sceneb.exit = True, in which case clicking the close box does make the program quit. If sceneb is part of a wxPython window that includes other elements such as buttons, sceneb.exit = False has no effect; if the window is named w, use w.exit = False.

At times you may need to know how large is the display region inside a window: window.dwidthand window.dheight are the extra width and height of windows compared to the display region. 

Controlling the view

It is useful to run the VPython example program camera.py, which illustrates how the following display options affect the view the user sees. 

center Location at which the camera continually looks, even as the user rotates the position of the camera. If you change center, the camera moves to continue to look in the same "compass" direction toward the new center, unless you also change forward (see next attribute). Default (0,0,0).

autocenter scene.center is continuously updated to be the center of the smallest axis-aligned box containing the scene. This means that if your program moves the entire scene, the center of that scene will continue to be centered in the window.

forward Vector pointing in the same direction as the camera looks (that is, from the current camera location, given by scene.mouse.camera, toward scene.center). The user rotation controls, when active, will change this vector continuously. When forward is changed, the camera position changes to continue looking at center. Default (0,0,-1).

fov Field of view of the camera in radians. This is defined as the maximum of the horizontal and vertical fields of view. You can think of it as the angular size of an object of size range, or as the angular size of the longer axis of the window as seen by the user. Default pi/3.0 radians (60 degrees).

range The extent of the region of interest to the left or right of center. This is the inverse of scale, so use either range or scale depending on which makes the most sense in your program. Setting range to 10 is the same as setting it to (10,10,10). Setting range to (10,10,10) means that scene.center+scene.range will be at the right edge of a square window. A sphere of radius 10 will fill the window. A cubical box whose half-width is 10 will overfill the window, because the front of the box in 3D appears larger than the xy plane passing through scene.center, unless the field of view is very small.

scale A scaling factor which scales the region of interest into the sphere with unit radius. This is the inverse of range, so use either range or scale depending on which makes the most sense in your program. Setting scale to 0.1 is the same as setting it to (0.1,0.1,0.1) or setting range to (10,10,10).

 up A vector representing world-space up. This vector will always project to a vertical line on the screen (think of the camera as having a "plumb bob" that keeps the top of the screen oriented toward up). The camera also rotates around this axis when the user rotates "horizontally". By default the y axis is the up vector.

There is an interaction between up and forward, the direction that the camera is pointing. By default, the camera points in the -z direction (0,0,-1). In this case, you can make the x or y axes (or anything between) be the up vector, but you cannot make the z axis be the up vector, because this is the axis about which the camera rotates when you set the up attribute. If you want the z axis to point up, first set forward to something other than the -z axis, for example (1,0,0).

autoscale = False no automatic scaling (set range or scale explicitly); autoscale = True automatic scaling (default). It is often useful to let VPython make an initial display with autoscaling, then turn autoscaling off to prevent further automated changes.

userzoom = False user cannot zoom in and out of the scene

userzoom = True user can zoom (default)

userspin = False user cannot rotate the scene

userspin = True user can rotate (default)