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:

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:

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

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.

• set get : modify or retrieve light properties
• on off : shortcut for set on resp. set off
• local : shortcut for set local
• global : shortcut for set global
• show : display information about light

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)

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.