| DINO: Visualizing Structural Biology |
|
User Manual
|
The structural biology data consists of basic elements which are specifically related to each other. In the structure dataset, the basic element is the atom, which is usually organized into residues, which in turn are optionally organized as chains, which in turn are optionally organized into models. In the scalar field and the surface topography, each grid point is the basic element, arranged into a regular 3-dimensional array (scalar field) or 2-dimensional plane (surface topography). The basic element of the surface is the vertex (coordinate in 3D space), which is organized into faces (triangles). A key property of all elements - apart from dataset specific ones - is that they all have a defined position in space.
A dataset can be thought of as a block of memory that holds the data. To visualize the data, objects are created from the dataset, which are displayed in the graphics window. Just as there is no limit to the number of datasets that can be loaded, there is no limit to the number if objects that can be created from a single dataset.
Now we have three different layers of the data: the dataset, the object and the individual data element. The object and the element always belong to a specific dataset. The three layers are addressed (given commands) in the following way:
dataset : the name of the dataset, preceded with a dot, then the command with its (optional) parameters
.dataset command [parameters ...]
object : dot-datasetname-dot-objectname command (optional) parameters
.dataset.object command [parameters ...]
data element : dot-datasetname-colon-element command (optional) parameters. This is only implemented so far for the structure dataset (see below)
.dataset:element command [parameters ...]
Wildcards (* and ?) can be used in the dataset and object names to match multiple datasets resp. objects. For example, to hide all objects with one command use
.*.* hide
The following scheme outlines the basic steps for displaying your data:
Example: load myo.pdb .myo new -name prot -sel rnum=1:146 scene center [.myo.prot] .myo.prot set color=cyan -sel aname=C* .myo.prot render custom,sr=0.25,bw=0.15
After a dataset is loaded objects can be created from it. This is accomplished with the dataset command new . During object creation the name and type of the object as well as object properties can be set and a selection can be applied.
Syntax: .dataset new [-name N] [-type T] [-selection SEL] [-set S]
As a default, the name of the dataset is used and all elements are selected. The default type and object properties depend on the dataset (see below).
The scene, dataset, objects and elements are all characterized by properties, e.g. the background color, the selection mode, the object color, the position in space, etc.
When an object is created from a dataset, some element properties are shared and some are copied. To retrieve the shared properties, the data-element command get is used. To modify the shared properties, the dataset command set is employed, optionally with a selection. To modify a copied property, the object command set or the dataset command set is used; usage on the dataset level will change the default.
// retrieve shared property (e.g. bfac) .struct:A.114.CA get bfac
// set shared property (e.g. rtype) .struct set rtype=helix -sel rnum=1:14,20:35
// set copied property (e.g. color) .struct.obj set color=green -sel ele=C // for object only .struct set color=green -sel ele=C // default coloring
The different properties are described in tables below, specifiying wether they belong to the dataset, object or element.
DINO features a powerful selection syntax. A selection consists of one or more PVs connected by logical operators and (or & ) and or (or | ) , optionally grouped by parenthesis ( ). A PV is in principle build up from a property, and operator and one or more (comma-separated) values and can be lead by a not (or ! ).
There are three principle types of PV used for selection:
ele=C rnum=1,4,7,8 anum=1:1000 bfac<30
6<>{12.0,3.6,-39.7} 10<>.struct.obj
Following is a collection of selection statements to clarify the sytnax:
.struct new -sel rnum=1:100 // select residues 1 to 100 .struct new -sel not chain=C,D,E // all except chains C,D and E .struct new -sel (rnum=7,12,43 & !aname=C,N,O) .scal new -sel 10<>[.struct.obj] // select around center of object .scal new -sel 10<>.struct.obj // select around limits of object .surf new -sel .a,.b,.c // effectively merges three objects
An object can be modified with the commands renew and set . Former carries similar functionality as the dataset command new , expect the name and type are fixed, and the selection and object properties will default to current selection and properties of the object if not explicetly specified.
Syntax: .dataset.object renew [-selection SEL] [-set S]
Calling renew without any parameter re-creates the object, which is sometimes useful, e.g. after the dataset restriction changes (see below).
The command set can be used on datasets and objects to modify properties with a comma seperated list of PVs, either in the context of renew or by itself:
Syntax: .dataset.object set PV1[,PV2 ...] [-selection SEL] [-range RANGE]
It can optionally carry the flags -selection and/or -range . If a selection is used, only the properties of the matching elements will be modified:
Example: // color all carbon atoms of this structure object in cyan .struct.all set color=cyan -sel aname=C*
The option -range allows to linearly map a property of the same or another dataset to an object property (usually color). Up to three properties for -range need to be specified: src , prop and val .
Syntax: .ds.obj set color=color1:color2 -range [src=SRC][,prop=PROP][,val=VAL1:VAL2]
The range properties have the following meaning:
src : The source dataset where to get the property from. If this is omitted or just a single dot, then the dataset of the object is used.
prop : The property from the dataset which is used for mapping, this is specific to each dataset (see below). If omitted, the default mappable property for the specific dataset is used.
val : A range which is to be mapped. Values outside this range are ignored. If omitted, the value range used is undefined.
In the tables below the R column denotes a property that can be used for applying a range: the structure dataset for instance allows bfac , so to color a structure object according to b-factor one would use
Example: .strc.obj set color=blue:red -range prop=bfac,val=0:80 // note that 'src' is not needed
The way an object is displayed in the graphics window is managed with the commands render and material .
Syntax: .ds.obj render PV[,PV] .ds.obj material [amb=COL],[diff=COL],[spec=COL],[shin=N],[EMM=COL]
The render properties are explained in more detail in the individual dataset sections below.
The material properties characterise how the objects interact with the light sources. COL is either a full {r,g,b} triplet or a single (grey) value. N is a number between 0 and 128.
amb : defines how much of the ambient lightsource component is reflected from the material; ambient reflection is independent of the position of the light
diff : defines how much of the diffuse lightsource component is reflected from the material; diffuse reflection is dependent on the position of the light
spec : defines how much of the specular lightsource component is reflected from the material; specular reflection produces highlights
shin : shininess component, determines the brightness and size of the highlight, the higher the number, the brighter and narrower the highlight.
emm : simulates light emmision, but does not act as a lightsource
For more information concering material properties and the interaction with the lightsources, consult an OpenGL reference (e.g. OpenGL Programming Manual 3rd Ed pp201).
Elements in the dataset can be restricted, so that they are not taken into account during subsequent commands.
Syntax: .dataset restrict SELECTION
All elements that do NOT match the selection are excluded from the dataset. To unrestrict the dataset, call restrict with * as selection.
Example: .myo restrict not rname=HEM // this residue is excluded .myo restrict * // restriction is off
A restriction in one dataset can have an effect on other datasets as well (see e.g. attachment below). The default is an unrestricted dataset.
Each dataset can be transformed individually with a rotation and a translation inside the global coordinate system. There are the following ways to transform:
Syntax: .dataset set rot={{a,b,c},{d,e,f},{g,h,i}},trans={x,y,z}
Syntax: .dataset rotN angle .dataset transN value
Syntax: .dataset grab INPUTDEVICE
INPUTDEVICE is one of mouse , mouse2 , dials , dials2 , spaceball , spaceball2 (see "4.10 Input" on page 20).
To reset or fix the transformation:
Syntax: .dataset reset .dataset fix
reset will set the transformation back to identity. fix will apply the transformation to the dataset elements and then set the transformation back to identity.
There are two ways to create a dataset: loading a file or issuing the new command. Currently, the geometric primitives dataset can only be created with new and all others (structure, scalar field, surface, topography) must be loaded from a file.
Syntax: load file.ext [-type T] [-name N] [-swap]
The type is guessed from the extension (see Table 7 (P. 26)) or can be explicitly set with the -type flag. Files can be gzipped, this will be recognized and the file gunzipped on the fly (adding the .gz extension to file.ext is not necessary). If no name is given, the filename without extension will be used. The option -swap swaps the binary values from LSB to MSB or vice versa. Use this when exchanging binary files between platforms that have a different byte order (e.g. SGI and Linux). See Table 7 (P. 26) for all supported formats.