The 3D visualization window

Creating a window

A window is created automatically when a 3D object is instantiated, but a window can be explicitly instantiated with the display() function. Parameters are

These properties can be changed at any time; changes will be reflected in the associated window.

Adding objects to the scene

Instantiated objects are added to the most recently created window by default. If no window has been created, one will be automatically instantiated and bound to the variable scene.

The objects available are listed in the vpython documentation. Attributes common to all objects are

Again, updating these attributes will update the 3D window(s) in real time.


Animation is done by repeatedly updating the attributes of objects visible in the 3D window. The visual module provides a function rate that can be used to control the animation framerate; for example, adding a rate(30) to a loop will cause the body of the loop to be executed at most 30 times per second.


A sequence of points can be plotted as a line in 3D space using the curve object. The pos, x, y, z, and color attributes are now sequences that allow each point in the curve to have varying position and color. New points can be added to the curve with the append(pos=(x,y,z),…) method.

User interaction

I will use scene as the variable for the display window.

Mouse Interaction

The attribute scene.mouse.clicked contains the number of waiting mouse input events. A mouse-click events can be retrieved from the queue with the scene.mouse.getclick() function. This function will block and wait for user input if no events are in the queue.

The object returned by getclick() has several useful attributes:


Controls in VPython are shown in a separate window that behaves independently of any other displays. All control functions and objects are in the visual.controls package; haphazard from visual.controls import * imports are not recommended.

Creating the control window and adding controls

A control window is created using the controls() function. Parameters for the controls() function are mostly similar to the display() function, but details are available at

Controls are instantiated like other objects; when positioning controls keep in mind that the default configuration of the controls window has (0,0) centered on the screen, with the upper left being (-100,-100) and the lower right being (100,100). Available controls are button, slider, toggle, and menu; I have only used sliders, but the other elements should behave similarly.

The most important attribute of a control is action; this specifies the function that will be called when the control is interacted with. This function can then read the values of the slider/toggle and update the scene as appropriate. Lambda functions are often used in the documentation, but are not required.

The controls won't actually be interactive, however, unless you call the .interact() method of the control window periodically to process user input. The .interact() method is non-blocking, so it can be combined with other interactivity options and should be used with the rate() function.