Home

If you're new to Python
and VPython see more
Help at glowscript.org

Pictures of 3D objects

VPython GlowScript VPython and VPython 7

Using VPython to create 3D animations

VPython makes it unusually easy to write programs that generate navigable real-time 3D animations. It is based on the Python programming language which is widely used in introductory programming courses thanks to its clean design, and it is also widely used in science and business.

Classic VPython was originated by David Scherer in 2000. In 2011 David Scherer and Bruce Sherwood initiated the development of GlowScript, a similar programming environment but which runs in a browser. In 2014 it became possible to use RapydScript, a programming language very similar to Python, to support VPython programs in the GlowScript environment.

There is an overview of the project at
http://matterandinteractions.wordpress.com/2011/09/23/glowscript-3d-animations-in-a-browser/. The open source for this project is at https://github.com/BruceSherwood/glowscript.

There is also VPython 7 originated by John Coady in 2014 and under continuing development by John Coady, Ruth Chabay, Bruce Sherwood, Steve Spicklemire, and Matt Craig. It uses GlowScript VPython syntax but with standard Python, thereby providing access to standard Python modules. For details see vpython.org. Also of interest there is a discussion about plans for the future evolution of VPython.

This documentation describes both GlowScript VPython and VPython 7.

For a quick introduction, there are YouTube videos available in English and Spanish in the more extensive Help at glowscript.org, but be aware that for the current version of VPython the name of the module is "vpython", not "visual", and the graphics display is shown in a browser tab rather than in a bare window. (For GlowScript VPython, you can omit importing vpython.)

There is a series of GlowScript VPython tutorials by Rhett Allain at https://phys221.wordpress.com/vpython-tutorials/ in the context of predicting motion computationally, at the level of an introductory physics course. Using tools at trinket.io it is easy to add both editing and execution of GlowScript VPython to your own web pages, and Allain in his physics blog for Wired magazine has shown examples of this (https://www.wired.com/2015/04/dare-change-numerical-calculation/)

Getting started

To write and run a VPython program using this offline GlowScript VPython package:

* On line 1, type box(). Click Run to run your program. You will see a white box on a black background.

* Use the right button (or CTRL-drag left button) of the mouse to rotate the camera to view the scene from different angles.

* To zoom in and out use two buttons, or ALT/OPTION-drag, or the mouse scrollwheel. Touch screen: swipe or two-finger rotate; pinch/extend to zoom.

* Use SHIFT-drag to pan the scene.

* After making a change in the program, click Run to run the modified program.

* Click Save to save your work. You may be asked whether you do want to keep the file. The file will in your Download folder.

* Click Export to obtain a complied version of the program, then click Save to obtain an html version in your Download folder. If you doubleclick this html file, your program will run in your preferred browser. Click Restore to return to the VPython code.

* For more details, see the README file that is part of this package.

Using the text editor

There is a list of keyboard shortcuts for find, replace, etc. at
https://github.com/ajaxorg/ace/wiki/Default-Keyboard-Shortcuts/. While editing, press Ctrl-1 (Cmd-1 on Mac) to run your program in the same window. Press Ctrl-2 (Cmd-2 on Mac) to run your program in a separate window, which lets you view your program and its execution side by side. If you change your program, press Ctrl-2 again in the editor display to re-run the program with the new changes. GlowScript uses the ACE text editor. Because ACE doesn't work on mobile devices, a simpler editor is used there.

A particularly useful shortcut is Ctrl-/ (Cmd-/ on Mac). Select one or more lines in your program and use this keypress to toggle whether those lines are commented out or not. Also, select one or more lines and press Tab to indent or Shift-Tab to unindent.

It is recommended to use the Chrome browser for developing programs, as it provides the most useful error messages, though programs can be written and run in all browsers, including on smartphones and tablets. In some cases program errors are visible only if you press Shift-Ctrl-J to display the Chrome console.

Letting others run your programs

While viewing the text of your program at glowscript.org, click Share this program to see how to let other people run your program. For people to run your program by linking to it, the program must be in a public folder at glowscript.org or be exported to your own web site. In fact, the code available on the share page can simply be pasted into a file and saved with the extension ".html", and then you can run the program simply by doubleclicking the html file.

Descriptions of the options available in the left margin

Pictures of 3D objects: What the objects look like

Choose a 3D object: Details of cylinder, box, etc. Start with cylinder for an overview.

Work with 3D objects: Issues that apply to all 3D objects: color, material, etc.

Windows, Events, & Files: Creating/modifying windows; handling mouse/ keyboard events; reading/writing files

Vector operations: Magnitude, dot and cross product, rotation, etc.

Graphs: Making graphs of data.

factorial/combin: Special functions used in probability calculations.

Be sure to explore the many GlowScript VPython example programs available in the Demos folder that is included with this offline package..

In general, Python modules cannot be imported into VPython programs, because GlowScript VPython functions in a JavaScript environment. However, one can import the Python "random" module into a VPython program, provided by the RapydScript-NG tool that converts Python to JavaScript (one cannot use the form "from random import *" but must use "import random" or "import random as rr" (or other name) or "from random import randint, random" (or other list of functions).

CAUTION

Do not use "wait" or "_" as a variable name. All GlowScript languages (VPython, RapydScrpt, JavaScript) use "wait" or "_" as a special signal for the compilation process. This signal is inserted for you where needed.

For experienced programmers

As a convenience to novice programmers to provide everything that is needed to get started, VPython by default imports all of the VPython features and includes standard math functions such as sqrt. The documentation is written as though "from vpython import *" were present. Also provided are clock(), random(), and arange().

You can however import selectively, as shown in the following examples, which are compatible with VPython 7. (To help with converting from Classic VPython, VPython 6, you can refer to "vis" or "visual" instead of "vpython".)

import vpython
import vpython as vp # "vp" is any name of your choice
from vpython import box, color

When using the form "from vpython import .....", if canvas is not specified, it is added, as GlowScript VPython cannot run without canvas.

For those who have used Classic VPython

A few Classic VPython objects are not currently available in VPython: convex, faces, and frame. The objects vertex, triangle, and quad represent a more powerful alternative to faces. Many applications of frame can be handled with the compound object.

One way to deal with differences is to check the elements of the "version" variable that is available in all versions of VPython:

Classic VPython:    version is ['X.Y', 'release']
GlowScript VPython: version is ['X.Y', 'glowscript']
VPython 7:          version is ['X.Y.Z', 'jupyter']
and in VPython 7, the version of the GlowScript
graphics library is given by
                  GSversion is ['X.Y', 'glowscript']

The curve and points objects are somewhat different from Classic VPython. Note that now the list of points in a curve object is not a numpy array, so that a loop is required to change all of the points.

To handle mouse events one cannot use scene.getevent() but must use scene.bind(), which is available in all versions of VPython, starting with Classic VPython 6. Also available are scene.pause() and scene.waitfor('click') and related options.

In GlowScript VPython it is not possible to import arbitrary Python modules such as numpy, and any program that uses numpy will have to be modifed. However, loops are fast in the JavaScript language to which GlowScript programs compile, so if you are using numpy solely for the speed of array manipulation, you may be able to replace a numpy calculation easily and efficiently with a loop.

The difference between RapydScript and VPython programs in the GlowScript context is that the VPython option mimics important elements of the syntax and semantics of Classic VPython programs, whereas the RapydScript option implements the same semantics for 3D objects as that of JavaScript programs. For example, in a RapydScript program the sphere object has a size attribute but no radius attribute, and like box, the default bounding box of the sphere is 1x1x1. Also, changing the length of the axis in a RapydScript program has no effect on the size (except for an arrow, which has a special axis_and_length attribute), but in a VPython program, as in Classic VPython, changing the length of the axis also changes the length of the object (the first component of the object's size).

GlowScript by default processes VPython programs as though they had the following statements at the start of the program (which you don't need to include; they will be ignored):

from __future__ import division, print_function
from vpython import *

Many programs written in Classic VPython 6 will run in GlowScript VPython or VPython 7 without change after being run through a conversion program written in Python and available at glowscript.org/docs/GlowScriptDocs/VPtoGS.py. This program converts (x,y,z) => vector(x,y,z) and obj.x => obj.pos.x. These changes are necessary because GlowScript does not recognize (x,y,z) as a vector nor obj.x as a shorthand for obj.pos.x. The program also converts display => canvas and gdisplay => graph. The program also converts scene.mouse.getclick() => scene.waitfor('click'), which works in both environments.

In GlowScript VPython and VPython 7 you can use the shorthand "vec" for "vector". If you wish to use a GlowScript program containing "vec" in the Classic VPython environment, just add the statement "vec = vector" at the start of the program.

Credits

Salvatore di Dio demonstrated in his RapydGlow experiment how he was able to use the RapydScript Python-to-JavaScript compiler with GlowScript graphics. This inspired the implementation of the VPython (vpython.org) API at glowscript.org. He provided the file papercomp.js for operator overloading, based on the work of
    Jürg Lehni (PaperScript).
He also assembled support for operator overloading and the ability to write synchronous code in the file transform-all.js, based on the work of
    Bruno Jouhier (Streamline), and
    Marijn Haverbeke (Acorn.js).
Supporting the VPython API in a browser is possible thanks to the work of
    Alexander Tsepkov (RapydScript) and
    Charles Law (browser-based RapydScript).

In January 2017 the original RapydScript compiler was replaced with RapydScript-NG by Kovid Goyal, which comes closer to handling true Python syntax.

When the GlowScript project was launched in 2011 by David Scherer and Bruce Sherwood,
Scherer implemented operator overloading and synchronous code using libraries existing at that time. In 2015 it became necessary to upgrade to newer libraries because compilation failed on some browsers; Salvatore di Dio provided crucial help in this update. In January 2017 the operator overloading machinery was further updated.