DINO: Visualizing Structural Biology
Table of Contents
Previous
Next
User Manual

4 Scene and GUI

The expression scene refers to the contents of the main graphics window. In this section, interaction with the graphics window using the mouse and other input devices will be explained as well as the scene commands which allow customization of the global graphical properties. In addition, the (slim) graphical user interface will be discussed.

4.1 Scene Interaction

The viewpoint (camera position) can be interactively changed. DINO supports a number of input devices. Each input device can be characterized as having one or more axis, zero or more buttons and a combination of keyboard modifiers (SHIFT, CTRL, ALT) pressed.1 The following input devices are supported:

mouse

The mouse has two axis (left-right and up-down) and is expected to have three buttons (left, middle, right). The right button is reserved for the context-sensitive submenu (see "4.12 The GUI" on page 20).

Clicking2 on an atom with the left mouse-button will 'select' this atom:

Additionally, if SHIFT is pressed while clicking the atom, the atom label will toggle (first click show, second click hide ...). Depressing the left mouse-button longer than necessary for a click will no longer count as a click but as pressed. Table 2 (P. 13) shows the default mouse settings.

Mouse Mappings in Scene window

combination

function

LeftButton

rotate around x and y

MiddleButton

translate along z (slow and fast)

LeftButton + MiddleButton

rotate around z

LeftButton + SHIFT

translate along x and y

MiddleButton + SHIFT

move slab along z

LeftButton + MiddleButton + SHIFT

change slab width

 

spaceball

Dialbox Mappings in Scene window

slab width

slab translate

rotate z

translate z

rotate y

translate y

rotate x

translate x

A spaceball is a highly recommended, but slightly expensive input device that incorporates all six rotational and translational axis in one device. For exploring data, it is much more convenient than either the dialbox or the mouse. There is a spaceball that works on linux3.

 

dialbox

A standard dialbox has 8 dials (equals 8 axis). Rotation around and translation along x,y and z are mapped to six of these dials. The remaining two manipulate the front and back clipping planes (slab). One translates the slab along z, the other changes its width. For the standard SGI dialbox the mappings are displayed in Table 3 (P. 14) (see also " man dialwarp ").

4.2 Writing a snapshot of the current scene

The scene command write will save the current scene to a file in a variety of formats.

Syntax: [scene] write file.ext [-scale SCALE] [-accum N]

Because of its frequent usage, an alias has been automatically created, so scene can be omitted. The format is guessed from the extensions:

 

scene write output formats

extension

description

.png

standard PNG format, picture is an exact screen copy, usually smaller than TIFF file.

.tiff

standard TIFF format, picture is an exact screen copy

.pov

POVray (www.povray.org) output

.r3d

Raster3D format4

.ps

PostScript format

.rgb

SGIs RGB format, no longer supported in v0.8!

.tiff & .png : The -scale and -accum parameters are only applicable to TIFF and PNG output -scale is either an absolut number or an expression in percent,designated by a percentage sign. -accum will use the accumulation buffer to generate N images that are slightly offset from each other, causing an overall smoothing5. Supported values for N are 1(off), 2, 3, 4, 5, 6, 8, 9, 12, 16. The images are generated with offline rendering through an X-Windows pixmap. Since the largest pixmap size is X-Windows implementation dependent and also depends on the amount of RAM, a huge output file might crash the X-Server. 2000x2000 should work in most cases.

.pov : Persistance Of Vision is a powerful, generic raytracer. DINO writes two output files, one with extension .pov and one with extension .inc . The .pov file is meant to be user-editeable and it contains the lighting, fog and viewpoint definition as well as variables to change object properties, i.e. the applied texture, transparency etc. Stereo pairs can be generated with the same POV output, the .pov file contains information about this. For more information, please refer to the POV tutorial on the DINO homepage.

.r3d : Raster3D is another raytracing package, aimed specifically at protein structure. Note that Raster3D output does not preserve the perspective, so stereo pairs cannot be generated this way (see also scene set view below).

.ps : PostScript Level 2 output, transparency is not supported, and smoothly shaded triangles are approximated by subdivision into smaller, unicolored triangles. This format is suitable for schematic line drawings.

Example: write pict1.png -s 1000 -a 4
         write scene.pov

4.3 Setting scene properties

The scene command set allows the modification of scene properties, while get retrieves them:

Syntax: scene set PV[,PV...]
        scene get P

See Table 5 (P. 16) for a list of all scene properties.

Scene Properties

property

explanation

default

bg

Background color. Accepts a colorname or an explicit {r,g,b} value

black

center

Use with get to retrieve the current center of rotation. Set the center of rotation with the shortcut scene center

{0,0,0}

depthc

If this flag is true, depthcueing between the near and far clipping planes - modified with fogd - will be performed.

true

dither

boolean flag, if set will enable global dithering on displays with less than 24 bits of color buffer

true

eyedist

This float denotes the occular distance for stereo projection

150.0

far

z value of far clipping plane. This float should always be larger than 0 and always larger than near. Op can be =, += or -=

1000.0

fixz

If this flag is true, the clipping planes will move along any z-translation

true

fogd

Offset from fog to far clipping plane. Values are relative to (far-near) and can range from -1.0 to +1.0

0.0

fov

Field-of-view angle for perspective projection

25 (degrees)

mmat

Current modelview matrix (rotation and translation in one 4x4 matrix). See examples below

 

near

z value of near clipping plane. This float should always be larger than 0 and always smaller than far. You can use the operators += and -= to increase/decrease the value instead of setting it explicitly with =

1.0

ortho

Use this flag to activate an orthographic viewing matrix. The aspect ratio is automatically determined from the window size

no

persp

Use this flag to activate a perspective viewing matrix with a field-of-view angle of fov. The aspect ratio is automatically determined from the window size

yes

rot

Current 3x3 rotation matrix

identity

slabw

Width of slab (distance netween near and far clipping plane)

999.0

trans

Current translation vector as {x,y,z}

{0,0, -100}

view

This property can take any of the three values left, right, center (default). view=left resp. view=right switch to the left resp. right stereo viewpoint. This allows easy generation of stereo pictures (see example)

center

Examples

white background
scene set bg=white
generating stereo figures
scene set view=left // left view 
// increase -s number to get higher resolution
write l.png -s 1000
scene set view=right // right view 
write r.png -s 1000
scene set view=center 
// use montage or something to paste the two files l.png and r.png
// together, print them at a width of 13cm and you are done. I use
// the ImageMagick command: 
// montage +frame +label +shadow -geometry 100% 
//         -tile 2x1 l.png r.png s.png
// for cross-eyed stereo, swap left and right view
writing the current orientation matrix
echo [scene get mmat] > view 
// into file 'view' (e.g. to paste into a script)
writing the current orientation - more 'sophisticated'
echo scene set mmat=[scene get mmat] > view 
echo scene set near=[scene get near] >> view
echo scene set far=[scene get far] >> view
// after some commands, in new script, etc...
@view 
// restores orientation and clipping planes from file view!

4.4 Stereo Mode

On graphics hardware that supports stereo viewing6 the scene command stereo will toggle between stereo and mono mode.

Syntax: [scene] stereo

Due to its frequent usage, an alias is automatically created so scene can be omitted. To force stereo off, use stereo off or mono, to force it on use stereo on

Syntax: [scene] stereo off
        [scene] mono
        [scene] stereo on

Stereo hardware is a confusing and complicated chapter in its own. Please refer to the DINO homepage for machine specific problems and solutions.

For cross-eyed stereo display - also called split-screen stereo - use the split command to toggle between split-screen and normal stereo. Note that while in split-screen mode, scene write will write out the left and right image into a single file.

Syntax: scene split

4.5 Manipulating the scene

As mentioned above, rotation, translation and slabbing can be controlled by input devices. There are also some commands for this purpose:

Syntax: scene center {x,y,z}
        scene autoslab
        scene transx VALUE
        scene transy VALUE
        scene transz VALUE
        scene transm {x,y,z}
        scene rotx VALUE
        scene roty VALUE
        scene rotz VALUE
        scene rotm {{a,b,c},{d,e,f},{g,h,i}}
        scene reset

center : The center of rotation is set with center. This is usually combined with a recursive subprompt in the form:

Example: scene center [.ds] // center on dataset 
         scene center [.ds.obj] // center on the object

autoslab : moves the near resp. far clipping plane exactly to the boundaries of the currently visible objects.

trans* rot*: translates along resp. rotates around the given axis, while the matrix version ( transm / rotm ) applies a matrix to the current translation / rotation matrix7.

reset : returns the scene to its default state8.

 

The command grab will regain input from an input device (see "4.10 Input" on page 20).

Syntax: scene grab INPUTDEVICE

4.6 Current Point

Everytime the left mouse button is clicked in the graphics window, a single coordinate is stored in the shell variable $CP . The position of the mouse alone can only determine two out of three coordinates components: one can envision an infinite line perpendicular to the screen going through the mouse pointer. $CP is determined by calculating the intersection of this line with the near and far clipping plane and then using the middle of these two point. This is useful when looking at scalar fields, e.g. electron density, with a small slab width: Click anywhere into the density and call
scene center [$CP] .

4.7 Scene Stack

The program maintains a history of the selection. Every time an atom is selected in the graphics window, its name is pushed onto the scene stack. Following are commands to manipulate this scene stack.

Syntax: scene push ARG 
        scene pop 
        scene peek 
        scene clear

push : pushes ARG onto the stack

pop : retrieves the topmost value and removes it

peek : returns the topmost value without removing it

clear : erases the stack.

Why would this be useful ? As an example: Distance measurement of two consecutively selected atoms:

Example: push [[scene pop]]
         push [[scene pop]]
         opr - abs
         scene message Distance: [peek] Angstrom

The first two lines retrieve the selected atoms from the scene stack with [scene pop] and insert the name of the atom in the line. Because this result is again embraced with [] , it defaults to get xyz (see below). These coordinates are pushed onto the arithmetic shell stack, the difference is computed ( opr - )and then the length of the resulting vector ( opr abs ). The result is peek ed of the shell stack and displayed in the status bar of the graphics window. This is exactly how the command dist in the user menu is implemented.

Another example: centering on the middle of two atoms consecutively selected atoms

Example: push 0.5 [[scene pop]] [[scene pop]]
         opr + *
         scene center [pop]

4.8 Lighting

DINO supports the use of up to 8 lightsources. They are addressed as

Syntax: scene:lightn command [parameters]

where n is a number from zero to seven. Following is a list of commands to modify the lightsource settings, refer also to Table 6 (P. 19) for light properties.

The lighting contribution to each vertex is calculated from the direction of the lightrays emitted by a lightsource. The lightrays of a directional lightsource are all parallel. With a positional lightsource, however, the direction of the lightrays is different for each relative position of vertex and lightsource. In real world terms, the sun can be considered a directional lightsource, while a lamp is a positional one.

A global light is unaffected by the scene transformation, while a local light is rotated and translated along with the scene objects.

Attenuation is only valid for positional lights. It mimics the dimming of the light in respect to distance from the lightsource using the following formula, where f is the factor applied to the light-contribution, d is the distance of the vertex to the lightsource and kc, kl and kq are the attenuation properties:

Example: // place a local, positional light at {0, 0, 10}
         // with a linear attenuation of 0.1
         scene:light1 set pos={0,0,10,1}, local, kl=0.1
         scene:light1 on

For more information about lighting, please refer to an OpenGL manual (see reference section)

Light Properties

property

explanation

default light 0

default light 1-7

on off

flag if light is on of off

on

off

local

light position will move with the camera

 

 

global

light position is fixed

X

X

pos

vector is form {x,y,z,w}, where x,y and z are coordinates in space and w=0 denotes directional light and w=1 positional light

{0.1,0.2,1.0,0.0}

{0.0,0.0,1.0,0.0}

amb

ambient color contribution, can be given as scalar grayscale value or as color {r,g,b}

0.05

0.0

diff

diffuse color contribution, can be given as scalar grayscale value or as color {r,g,b}

0.6

1.0

spec

specular color contribution, can be given as scalar grayscale value or as color {r,g,b}

0.3

1.0

kc

constant attenuation factor

1.0

1.0

kl

linear attenuation factor

0.0

0.0

kq

quadratic attenuation factor

0.0

0.0

spotc

spot cutoff angle (0 to 90), 180 means no spot

180.0

180.0

spote

spot exponent

0.0

0.0

spotd

spot direction

{0,0,-1}

{0,0,-1}

4.9 Arbitrary Clipping Planes

In addition to the front and back clipping planes, an arbitrary clipping plane can be turned on. A plane is defined by an origin ( pos ) and the direction ( dir ) of the plane normal

Syntax: scene:clipN [on|off],[pos={x,y,z}],[dir={xn,yn,zn]
        scene:clipN grab DEVICE

N is the number of the clipping plane, currently only clip0 is implemented. The position defaults to {0,0,0} , the direction defaults to {0,0,1} A clipping plane can grab an input device to be rotated and translated arbitrarily (see "4.10 Input" on page 20).

4.10 Input

As mentioned above, there are three input devices supported in DINO: mouse, dials and spaceball. Internally, there are two input 'tables' for each device, called mouse and mouse2 , dials and dials2 and spaceball and spaceball2 . The *2 version is activated when cntrl is held down on the keyboard. Why would this be useful ? Each dataset as well as the scene contain a grab command, which reroutes the input info from an input device to that dataset or the scene. After startup, all input is routed to the scene, causing the camera position to be modified. If an input is routed to a dataset, however, its rotation/translation is modified, effectively leading to a rigid body rotation within the global coordinate system. In a situation where dataset A has grabbed mouse , the scene would still get input from mouse2 , so pressing cntrl while moving the mouse would cause a camera update and not a transformation of dataset A. This also applies to the dials and the spaceball.

4.11 Odds and Ends

A string can be displayed in the status bar of the graphics window:

Syntax: scene message MESSAGE

The command spin will toggle spinning of the objects, i.e. the continuation of the last mouse-induced rotation. False per default.

Syntax: scene spin

bench will continuously force screen updates and allows simple 'benchmarking' by displaying the fps in the status bar. Call bench again to turn off.

Syntax: bench

4.12 The GUI

The GUI in DINO is implemented only very rudimentary, a situation which will be improved upon as the program matures.

What is present so far is an object menu, which appears as a second window after startup. It contains a button scene, and will fill itself when datasets are loaded and objects created. Left-clicking on an object name will toggle its display, while right-clicking on an object-name, dataset-name or scene will cause a (context sensitive) submenu to appear.

In addition, the functionality of a user menu is implemented, but it is currently not customizable. It appears (as a popup) when right-clicking somewhere in the graphics-window.


1. In the current version the modification mapping of input is not supported, but this should change in a future version, so that the input is fully customizable.

2. Clicking in this context means pressing and releasing the button within 200 milliseconds

3. The spaceball is called Magellan(TM), is sold by Logitech(TM), and such a device was kindly lend to the author for implementing the spaceball code into the linux version of DINO by logicad3d(TM) ( http://www.logicad3d.com ).

4. Merrit & Bacon (1997) Meth. Enzymol. 277
http://www.bmsc.washington.edu/raster3d

5. From OpenGL Programming Guide 3rd Ed. Scene Antialiasing p. 451

6. Currently only SGI hardware stereo is supported in DINO

7. The rotation matrix is not verified (-> determinant==1) ! Expect weird things when using arbitrary values

8. transmat={0,0,-100}, rotmat=identity ({{1,0,0},{0,1,0},{0,0,1}}), near=1.0, far=1000.0