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

  • title: string to be used to the window title
  • width, height: dimensions of the window in pixels
  • center: the point at which the camera will always face
  • background: an (r,g,b) tuple to use for the background; (1,1,1) is white, (0,0,0) is black

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

  • pos: typically the position of the center of the object, though this varies.
  • color: specify using (r,g,b) tuples
  • x,y,z: alternative method of accessing/updating pos
  • visible: whether or not the object is visible in the scene
  • display: which window is showing the object

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:

  • pos: the 3D coordinates of the mouse click, projected onto the plane parallel to the screen and passing through the windows' center attribute.
  • pick: the object clicked on, if any


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.

vpython_overview.txt · Last modified: 2007/09/05 23:22 by smittal
Recent changes RSS feed Creative Commons License Donate Powered by PHP Valid XHTML 1.0 Valid CSS Driven by DokuWiki