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 curve object displays straight lines between points, and if the points are sufficiently close together you get the appearance of a smooth curve. In addition to its basic use for displaying curves, the curve object has powerful capabilities for other uses, such as efficient plotting of functions.

Some attributes, such as pos and color, can be different for each point in the curve. These attributes are stored as numpy arrays. The numpy module for Python provides powerful array processing capabilities; for example, two entire arrays can be added together. Numpy arrays can be accessed using standard Python rules for referring to the nth item in a sequence (that is, seq[0] is the first item in seq, seq[1] is the second, seq[2] is the third, etc). For example, anycurve.pos[0] is the position of the first point in anycurve.

You can give curve an explicit list of coordinates enclosed in brackets, like all Python sequences. Here is an example of a 2D square:

square = curve(pos=[(0,0),(0,1),(1,1),(1,0),(0,0)])

Essentially, (1,1) is shorthand for (1,1,0). However, you cannot mix 2D and 3D points in one list.

Curves can have thickness, specified by the radius of a cross section of the curve (the curve has a thickness or diameter that is twice this radius):

curve(pos=[(0,0,0), (1,0,0), (2,1,0)], radius=0.05)

The default radius is 0, which draws a thin curve. A nonzero radius makes a "thick" curve, but a very small radius may make a curve that is too thin to see.

In the following example, the arange() function (provided by the Python numpy module, which is imported by the Visual module, gives a sequence of values from 0 to 20 in steps of 0.1 (not including the last value, 20).

c = curve( x = arange(0,20,0.1) ) # Draw a helix
c.y = sin( 2.0*c.x )
c.z = cos( 2.0*c.x )

The x, y, and z attributes allow curves to be used to graph functions easily:

curve( x=arange(100), y=arange(100)**0.5,

A function grapher looks like this (a complete program!), where "raw_input" is a Python function that accepts input typed in the Python Shell window:

eqn = raw_input('Equation in x: ')
x = arange( 0, 10, 0.1 )
curve( x=x, y=eval(eqn) )

Parametric graphing is also easy:

t = arange(0, 10, 0.1)
curve( x = sin(t), y = 1.0/(1+t),     z = t**0.5,
    red = cos(t), green = 0, blue = 0.5*(1-cos(t)) )

Three ways to specify the list of points

There are three ways you can specify the pos attribute for a curve, as a simple list of 3D points, as a 2D path using the paths library, or as a 2D Polygon object as long as it has only one contour (that is, no holes or separated pieces). Here are examples of each of these three kinds of path to be assigned to the pos attribute of a curve:

p3 = [(1,0,0), (2,1,-3), (2,5,3), (-1,4,0)] # 3D points

p2a = paths.rectangle(length=8) # 2D paths library

p2b = shapes.rectangle(width=6) +
      shapes.rectangle(pos=(0,4), width=2)

Contour p2a is created in the xz plane. If you say p2a = paths.rectangle(length=8, up=(0,0,1), the contour will be in the xy plane, perpendicular to the direction (0,0,1). You can learn more details in the description of the extrusion object.

The contour p2b is constructed from the Polygon objects created by the shapes library. Two rectangles have been added together to form a combined shape, with just one (outer) contour. This can be assigned to the pos attribute of an extrusion.

Technical note: What the paths library produces is not a Polygon object. If you want to create a path by combining Polygon objects using constructive geometry (as in adding two rectangles together to form the contour p2b), use the shapes library, which does create Polygon objects.

Here are the curve attributes:

pos[] Array of position of points in the curve: pos[0], pos[1], pos[2]....
The current number of points is given by len(curve.pos)

x[ ], y[ ], z[ ] Components of pos; each defaults to [0,0,0,0,...]

color[ ] Color of points in the curve

red[ ], green[ ], blue[ ] Color components of points in the curve

radius Radius of cross-section of curve
The default radius=0 makes a thin curve

material Material for a thick curve; see Materials for currently available options

Currently it is not possible to specify the opacity of a curve object.

Adding more points to a curve

Curves can be created incrementally with the append() function. A new point by default shares the characteristics of the last point. You can append pos, color, red, green, or blue, but not radius. For a single curve object, all of the curve must have the same radius.

spiral = curve( color = color.cyan )
for t in arange(0, 2*pi, 0.1):
    spiral.append( pos=(t,sin(t),cos(t)) )

One of the many uses of curves is to leave a trail behind a moving object. For example, if ball is a moving sphere, this will add a point to its trail:

trail = curve()
ball = sphere()
# .... Every time you update the position of the ball:

When appending to a curve, you can optionally choose to retain only the last N points, including the one you're adding:

trail.append(pos=ball.pos, retain=50) # last 50 points

Interpolation of colors

The curve machinery interpolates colors from one point to the next. If you want an abrupt change in color, add another point at the same location. In the following example, adding a blue point at the same location as the orange point makes the first segment be purely blue.

c= curve( pos=[(-1,0,0)], color=color.blue, ...)
c.append( pos=(0,0,0) ) # add a blue point (optional)
c.append( pos=(0,0,0), color=color.orange) # same point
c.append( pos=(1,0,0) ) # add orange point

In the image shown here, the upper thick curve, made without the optional blue point, has three pos and color points, blue, orange, orange, left to right, so the blue fades into the orange. The lower curve includes the optional blue point and has four pos and color points, blue, blue, orange, orange, so there is a sharp break between blue and orange.

colors abutting

Skipping points

Technical note: No matter how many points are in a curve, only 1000 are displayed, selected evenly over the full set of points, in order that the display of a very long curve doesn't slow down unacceptably.

See description of Additional Attributes available for all 3D display objects.