Controlling One or More Visual Display Windows

Initially, there is one Visual display window 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 Visual display window 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))

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 Visual, 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 Visual 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. Currently has no effect on Linux.

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

show_rendertime If you set scene.show_rendertime = True, in the lower left corner of the display you will see something like "cycle: 27 render: 5", meaning 27 milliseconds between renderings of the scene, taking 5 milliseconds to render, in which case 22 out of 27 milliseconds were devoted to executing your Python statements.

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).

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, and scene.stereo will have the value 'nostereo'. 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 PCs with CRT 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. 'Passive' stereo requires a video card that can drive two monitors, or two projectors.)

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 window

The window attributes x, y, width, height, title, and fullscreen cannot be changed while a window is active; they are used to create a window, not to change one. If you want to modify any of these window attributes, first make the window invisible, make the changes, and then make the window visible again. This creates a new window with the new attributes; all existing objects are still part of the new window.

x, y Position of the window on the screen (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. In this case there is no close box visible; press Escape to exit.
(There is currently a bug in the fullscreen option for Linux; the Escape key has no effect. If you use the fullscreen option on Linux, be sure to program a mouse or keyboard input for quitting the program.)

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.

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.

Controlling the view

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 away from center along each axis. 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,0,0) 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 Visual 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)