Chapter 1: Getting Started with O


The topics that are covered in this HowTo are:

1. Downloading

2. Installation

These first 2 steps should take just a few minutes. Essentially, you get the binary of the executable file you want (osx_ono or equivalent, say), and two zipped directories (data.zip and job.zip) by anonymous ftp from my public account at xray.bmc.uu.se

You put them all in a directory called o, say, make sure that o/bin, o/temp, o/job and o/data are in your path (as set in .cshrc or .login), and add the following lines to your .cshrc (if you use the t- or c-shell, else a bash equivalent)


setenv ODAT /whatever/o/data/

setenv OTMP /whatever/o/temp/

setenv OJOB /whatever/o/job/

alias ono /whatever/o/bin/osx86_ono

alias ow cd /whatever/o/work


And you are ready to go. If that was too short, detailed instructions follow.


3. Running the program

4. User interaction

5. Customisation

6. Web resources

7. O-related publications



1.1 Downloading O

Anybody can use O. There is no registration process, just pick it up. If you have any problems, you can contact me (alwyn@xray.bmc.uu.se), or send an email to o-info. I am particularly interested in any bugs that you may find. I always answer emails as soon as I see them. If you are waiting for a reply I am either away, never got the email, or sick.


People often ask what is the minimum hardware requirement for running O, and what is the ‘best’ system. I do not have a definitive answer for either question and if they exist, they will be changing continuously. O will (I think) run on any modern computer model running one of the operating systems that I support (see below). The performance, however, will depend on the exact hardware configuration. O works within a single thread, so buying a system with 2 or more CPUs will not help your O performance. If you are running other programs at the same time, you will see a performance boost with a multi-cpu (or multi-core) system. O cannot directly make use of more than one CPU but is able to ‘spawn’ tasks, so if you have multi-cores, try using the Job-system in O to refine your structure as you work, for example, but this is much-to-much detail for a beginner. The graphics card/processor (or lack of one) in your system does have an affect on performance, at least on graphics performance. Fortunately, all discrete graphics cards/processors have more than enough performance for many users but there are a few issues that you should know about:

1/ O uses the graphics API called OpenGL and your system must support and have the necessary libraries installed. Mac OSX users have this library installed on all systems, but Linux/Windows users will need to do some extra work if the right library is not installed.

2/ O uses the graphics windowing library called GLUT, and the same situation exists for OSX and other users.

3/ O supports various forms of stereoscopic viewing. The simple form (side-by-side) works out-of-the-box, as does certain screens that support so-called ‘stencil’ stereo. Quad-buffered stereo (aka ’stereo in a window’) is only supported by cards that support the OpenGL version. In the Windows/DirectX universe, there are numerous stereo options that will not be supported by O. At the moment, I don’t think there is a graphics option that supports quad-buffered stereo for Mac users, but there are options available for Linux and Windows users. Nvidia, for example, supports stereo for some of their more expensive cards under Linux and Windows OS’s.


 The current program (Ov14) is supported on the following systems:

osx86_ono - Intel version for Apple Macintosh OS X (Leopard and later)

lin64_ono - Linux 64-bit version on Intel/AMD processors.

win_ono.exec - Microsoft Windows version on Intel/AMD processors.


While earlier releases (Ov13 and earlier) have also been supported:

osx_ono - PowerPC version for Apple Macintosh.

sun86_ono - Sun Solaris version on AMD processors.

sg_X_ono - Silicon Graphics version, via X-windows.

and still could if needed.


I do not have a 32-bit Linux version at the moment, but it would be easy to make one if needed. The 64-bit version has been tested on Centos 6.3, Debian 6.0.6, OpenSuse 10.3, Red Hat (5.8, 6.3),  and Ubuntu (12.04, 10.10) distributions. I have only tested the Windows version on XP but I have seen it running on Windows 7.


Set your browser to ftp://xray.bmc.uu.se and then to pub and then alwyn. Complete O releases are kept in separate directories with obvious names such as v13.0 or v14.0 while so-called dot releases may contain only updated files relative to the respective full release. A kipaut directory (pronounced keep-out), which sometimes contains a development release of the program, may also exist. The directory for Ov14, for example, is a full release and contains two zipped directory files (data.zip, and job.zip), the runtime exec files supported by this release (lin64_ono, osx86_ono and win_ono.exe), and the actual data directory (which might be easier for some people to get). Now use your browser to get the data directory (or its zip’ed file), the job.zip directory file and the relevant runtime exec file. The various files are minute by today’s standards, the largest is the osx86_ono file (< 5Mbytes). The final unzipped data-directory will occupy ~8 Mbytes when expanded, so the largest O installation will need <15 Mbytes of disk storage. 

The contents of the kipaut directory will vary a lot, and might not exist or be empty. I do not promise to announce bugs concerning execs in this directory. If I find or am informed of a bug in the current release, I will announce it on o-info and on the ‘O in the works’ web page that is relevant for the release (see ‘Web resources’ below)



1.2 Installing O

For each full release of O, I encourage users to organise the following directory structure:

v14 the top directory level, which also contains the full release name and then 4 subdirectories

bin - to hold the runtime exec file(s)

data - the directory containing the numerous library files that O uses. This directory usually exists as a zipped file and as a directory on the ftp server.

job - the directory containing the templates needed to run the Job-system in O.

temp - the directory continuing files generated by the Undo-system in O.


In the following example, I have downloaded the 3 files that I need from the ftp server, and moved them to a directory where I want to make the installation on my OSX machine, I have then started the Terminal app.

% cd o/v14

% pwd

/Users/alwyn/o/v14

% ls -al

total 12120

drwxr-xr-x   5 alwyn  staff      170 Oct 23 13:40 .

drwx------@ 16 alwyn  staff      544 Oct 23 13:38 ..

-rw-r--r--@  1 alwyn  staff  1717110 Oct 23 13:38 data.zip

-rw-r--r--@  1 alwyn  staff    10160 Oct 23 13:39 job.zip

-r--------@  1 alwyn  staff  4469472 Oct 23 13:39 osx86_ono

% mkdir bin

% chmod 755 osx86_ono


I need to modify the file access information for the runtime exec file so that it can run from the Terminal application. Next, I will put it in the bin directory.

% mv osx86_ono bin

% ls -al

total 3400

drwxr-xr-x   6 alwyn  staff      204 Oct 23 13:42 .

drwx------@ 16 alwyn  staff      544 Oct 23 13:38 ..

-rw-r--r--@  1 alwyn  staff     6148 Oct 23 13:42 .DS_Store

drwxr-xr-x   3 alwyn  staff      102 Oct 23 13:41 bin

-rw-r--r--@  1 alwyn  staff  1717110 Oct 23 13:42 data.zip

-rw-r--r--@  1 alwyn  staff    10160 Oct 23 13:42 job.zip


I would normally just double-click on each of the 2 zip files in the FInder, but they can also be expanded at the Terminal.

% unzip data.zip

Archive:  data.zip

   creating: data/

  inflating: data/.DS_Store          

   creating: __MACOSX/

   creating: __MACOSX/data/

  inflating: __MACOSX/data/._.DS_Store  

  inflating: data/1.odb              

  inflating: data/1b23-.o        …. 

% unzip job.zip

Archive:  job.zip

   creating: job/

  inflating: job/eds_fetch           

  inflating: job/eds_fetch_1st.omac  

  inflating: job/eds_fetch_2nd.omac  

  inflating: job/lsq_brute           

  inflating: job/lsq_brute_1st.omac  

  inflating: job/lsq_brute_2nd.omac  

  inflating: job/ncs_imp             

  inflating: job/ncs_imp_1st.omac    

  inflating: job/ncs_imp_2nd.omac    

  inflating: job/refmac              

   creating: __MACOSX/job/…


A directory called __MACOSX is created for some reason, which can be deleted (it’s not left around if this is done from the Finder).  

% ls -al

total 3400

drwxr-xr-x    9 alwyn  staff      306 Oct 23 13:45 .

drwx------@  16 alwyn  staff      544 Oct 23 13:38 ..

-rw-r--r--@   1 alwyn  staff     6148 Oct 23 13:43 .DS_Store

drwxrwxr-x    6 alwyn  staff      204 Oct 23 13:45 __MACOSX

drwxr-xr-x    3 alwyn  staff      102 Oct 23 13:41 bin

drwxr-xr-x  101 alwyn  staff     3434 Sep 14 14:47 data

-rw-r--r--@   1 alwyn  staff  1717110 Oct 23 13:42 data.zip

drwxr-xr-x   21 alwyn  staff      714 Jul  7  2008 job

-rw-r--r--@   1 alwyn  staff    10160 Oct 23 13:42 job.zip

% cd bin

% ls -al

total 8736

drwxr-xr-x  3 alwyn  staff      102 Oct 23 13:41 .

drwxr-xr-x  9 alwyn  staff      306 Oct 23 13:45 ..

-rwxr-xr-x@ 1 alwyn  staff  4469472 Oct 23 13:39 osx86_ono


You also need a temporary-files directory that is used by the Undo-system in O, which can be in the same directory tree structure, e.g.

% cd ..

% pwd

/Users/alwyn/o/v14

% mkdir temp


The zip-files can be deleted if you want, but O is now ready to run. In the next line, I set the directory to somewhere to work (via an alias) and then start the version of the program that I have just downloaded.

% ow

% /Users/alwyn/o/v14/bin/osx86_ono  p2.o ';'

  O > This version of O is free for anyone to use.

  O > Contact alwyn@xray.bmc.uu.se if you have a problem.

  O > O version 14.0.0, Build 120914

  O > O is 3D graphics enabled

…..


A 3D window is created and we are up and running with this release of the program.

The directory names that you use must not contain any embedded spaces since O left shifts all file names.

The third line of text output by O always prints the version and buid date.



1.3. Running O

1.3.1 Unix-based OS’s

OSX users can use Mark Harris’ drag-and-drop system for running O (see his home pages http://xray.bmc.uu.se/markh/ostick.html for more details). However, I always run O from the Terminal application, and I do not update Mark’s program. O is a terminal-based computer program that for OS’s with a Unix underpinning (I.e. OSX and Linux) should be set up to minimise typing. This involves defining so-called environment variables and aliases, all of which can be pre-defined so that they are active when a Terminal window is created. I tend to work in the Unix t-shell, rather then the bash shell which is the default for OSX and many Linux distributions. Your default can be changed by some Unix wizardry in Linux or  from the ‘System Preferences’ in OSX. In the following, I force the use of my preferred shell by typing tcsh.

% tcsh

% cat .cshrc

….

setenv ODAT /Users/alwyn/o/v14/data/

setenv OTMP /Users/alwyn/o/v14/temp/

setenv OJOB /Users/alwyn/o/v14/job/

alias ono /Users/alwyn/o/bin/osx64_ono

alias ow cd /Users/alwyn/o/Teaching

% 


The file with the odd name .cshrc is invisible from the usual file browser (Finder), but gets activated when the user starts the Terminal application in the t-shell, or if the shell is activated. I have only listed the lines relevant to O in the above example, where three environment variables are defined, as well as two aliases. ODAT is the directory containing the various library files that O uses; OJOB is directory containing O’s Job templates;  OTMP is directory containing O’s temporary files (generated by the job system, by the undo commands, and many actions in the Master-Menu system).The OTMP directory must exist, but it does not have to be in the same directory as the ODAT directory as in the above example. The aliases allow me to start the current version of the program by typing just ono at the shell prompt, and to set a directory where I have the distributed P2 myelin files that I use in my teaching. The 2011 version of our crystallography course used the two files in the kipaut directory (p2map_2011.pdf and a zip-directory p2map.zip), both of which should be downloaded if you wish to follow the examples elsewhere on this site. The p2map directory contains many so-called macro instructions that together with the description in the PDF file, will take you through the experimental map (ano1.map) that I used to solve the structure of P2 myelin protein (Jones et al., 1987), as well as an improved that has been generated by cyclic three-fold averaging (av_5.map). The files and description used in the course have been simplified to guide the students through an exercise. When a user comes to carry out the tracing of their own new structure, I recommend the use of the Master-menu system described below. The experimental maps and P2 sequence can, of course, be used with master-menus but if you are serious, work with the ano1.map not the averaged map (the latter is too good).


O is able to read many standard crystallographic files. These include, for example, the coordinate files from the Protein Data Bank, and electron density files generated by popular crystallographic programs (X-PLOR, CNS, CCP4). To work with many different sorts of crystallographic, molecular, program-dependent information, O uses its own database structure; the ODB. ODB entries have a name, information type, size and a read-only attribute. ODB names are limited to 25 characters and cannot include embedded spaces. Data types can be integer, floating point real, six character and single character variables. The data can exist in a binary format, or as text. In both formats, the data is arranged as header information, associated data, header information, associated data etc until an end of file is reached. Users need only concern themselves with editable text ODB files. When you start O, the user either provides an ODB that has been generated by O during an earlier session, or O will prompt the user to read in the minimum database to allow the program to function. A fuller description of ODBs structure and format is given elsewhere, but for now we will assume their existence and that O needs them to work.

 

If everything is set up correctly, we can now start the program by typing the alias ono. In the following example, I have set the working directory to the p2map directory, started the program and then pressed the <return> key 4 times (I have also introduced text to indicate what has happened):

% ono 

  O > This version of O is free for anyone to use.

  O > Contact alwyn@xray.bmc.uu.se if you have a problem.

  O > O version 14.0.0, Build 120914

  O > O is 3D graphics enabled

  O > No dials

  O > Mono enabled only

  O > Gamepad disabled

  O > ODAT environment variable :/Users/alwyn/o/data/

  O > Undo files saved in /Users/alwyn/o/temp/

  O > O for Mac & Intel processors.

  O > Run line:

  O > Define an O file (terminate with blank):


Up to now, O has given information concerning the version, and a the values of a number of environment variables (described elsewhere) that we can skip over for now. The program is waiting for the user to define an ODB file from an old session, or from the O database. I hit a <return>


  O > Menu names are not defined.

  O > Enter file name [/Users/alwyn/o/data/menu.odb]:

The program has stopped again because it has checked for an ODB entry in it’s internal database and it is not there (we have not loaded anything yet!). This entry is required to be there otherwise O cannot continue. The program now prompts with a default file name for the needed ODB; O expects it to be in the ODAT directory and called menu.odb. Hitting a <return> accepts the prompt text between the square brackets.


  O >  menu.odb file for O version 13.1.0, 120828

  O >  Database compressed.

  O >  Database compressed.

  O >  Database compressed.

  O >  Database compressed.

  O >  Database compressed.

  O >  Database compressed.

  O >  Forsyth & Wells Scattering Factors Acta Cryst 12 (1959) 412-5

  O > Startup file was never loaded


Most of the above text comes from comment lines in the menu.odb file, but the program has stopped again after reading in this ODB because it finds something else is missing, and O knows where it should be so it prompts:

  O > Enter file name [/Users/alwyn/o/data/startup.odb]:

  O >  startup.odb file for O v12 080508

  O >  Guess Matrix with PRO

  O >  terminal arcade codes loaded

  O >  3 button mouse, double and single pixel line widths

  O > Lsq definition defaults are taken.

  O > Making default Bones colours

  O > Default fog values have been defined

  O > These are in ODB .ogl_light entries 14-16

  O > An ODB is missing, it is updated with a default.

  O > Number of mouse buttons     3

  O > Stereochemistry file was never loaded


Again, something is missing and the program waits for user input. You might wonder why I keep this data in 3 separate files, and the answer is that they contain different kinds of data that I periodically have to update. The user could also change things in these files (at their own risk, of course), but I have to change them sometimes. The menu.odb file is updated whenever I develop new commands, the startup.odb is rarely changed, while the stereo_chem.odb contains stereo-chemical information that can be expanded every time I meet a new new residue. This gets changed less often than it used to since in Ov13, I allowed dictionary information to be stored in the user’s O database on a per residue basis (see ‘A-Z of O’  Refi_gener).

  O > Enter file name [/Users/alwyn/o/data/stereo_chem.odb]:

  O >  stereochemistry dictionary, PDB remediated names, IUPAC phosphates

  O >  Recent changes:

  O >  100401 PRO Phi -63 -> -60

  O >  100226 more PRO flattening

  O >  100118 OXT residue

  O >  081009 ALA rsr definitions

  O >  080912 single letter codes for protein and nucleic acid

  O >  0808020 ATP,NDP

  O >  080807 flat PRO & PO4

  O > read ok

  O > Connectivity used is : all

  O > Maximum linkage distance = 2.00

  O >  There were   53 residues.

  O >              642 atoms.

  O > The usual on_startup macro will be activated

  O > ****************************************************

  O > Warning, program version does not match the database

  O > Database is: O version 13.1.0

  O > Read in new startup.odb & menu.odb files!

  O > ****************************************************

The above is a warning, but sometimes one can get problems mixing old ODBs and new program versions. At its simplest, an old database generated with one version of O will not have the names (and possibly data) of the new O commands that are supported in a newer release (see ‘Updating an old User Database’ below)


  O > ODAT in use : /Users/alwyn/o/data/

  O >  There are       0 molecular objects

  O > Making visibility data structures.

  O > Making visibility data structures.

 As4> ......No message from the O administrator........


The remaining text comes about because the directory p2map contains a file called on_startup that is interpreted as a set of macros, which in this case load in two electron density maps:

 Fm>

 Fm> Map type is DSN6

 Fm>

 Fm> Parameters as read from the map file:

 Fm> Grid .................        76        82        48

 Fm> Origin ...............         0         0         0

 Fm> Extent ...............        77        83        49

 Fm> Fast, medium, slow....         X         Y         Z

 Fm> Cell axes ............     91.80     99.50     56.50

 Fm> Cell angles ..........     90.00     90.00     90.00

 Fm> No reslicing of map necessary

 Fm> Prod .................     20.00

 Fm> Plus .................         0

 Fm> Min, max, RMS ......   0.00000   8.35000   0.95545

 Fm> Scale ................     1.000

 Fm> Symmetry information may be used

 Fm>  O-style symm-ops for spacegroup P212121

 Fm> 4 symmetry operators

 Fm>

 Fm> Map type is DSN6

 Fm>

 Fm> Parameters as read from the map file:

 Fm> Grid .................       100       110        64

 Fm> Origin ...............         0         0         0

 Fm> Extent ...............       100       110        64

 Fm> Fast, medium, slow....         X         Y         Z

 Fm> Cell axes ............     91.80     99.50     56.50

 Fm> Cell angles ..........     90.00     90.00     90.00

 Fm> No reslicing of map necessary

 Fm> Prod .................      3.90

 Fm> Plus .................       116

 Fm> Min, max, RMS ...... -29.74359  35.64103   7.57806

 Fm> Scale ................     1.000

 Fm> Symmetry information may be used

 Fm>  O-style symm-ops for spacegroup P212121

 Fm>  Database compressed.

 Fm> 4 symmetry operators

 New> Min, max, RMS ......  -3.92496   4.70318   1.00061

 New> Number of mouse buttons     3


A new window will appear that contains some magenta coloured text at the top and 3 boxes of text.

Image


These are also windows but their background colour is black. The three boxes were drawn because the on_startup file contained O instructions to open these particular windows and to place them where they appear. WIthout an on_startup file in the directory, the maps would not have been loaded, and the 3 windows would not have got drawn. More information on using on_startup files is given elsewhere. The 3 lines of text at the top of the screen always appear, although the user can turn them on and off by typing the F2 key. They allow the user to interact with the program, and the program to interact with the user.


If you want to follow the course exercise, get p2map_2011.pdf and follow the instructions. Have fun!


1.3.2 Microsoft Windows OS’s

The version of O that runs under Microsoft Windows (XP, Vista, 7) has a number of differences compared to Unix-based versions. These differences arise because there are no equivalents to environment variables and a few other systems-related issues. Unfortunately, some of these ‘differences’ may represent ignorance on my part, especially since I stopped using Windows as my main computer once Apple released the beta-version of OSX. Now day-to-day work is made on an Intel-based Apple system, hence the ono alias (above) points towards osx86_ono .


Although the Windows release has no access to various Unix-related features and subroutine calls, I have tried to keep the spirit of the Unix-based programs. The definition of the O data directory, for example, cannot be made with an environment variable. It is instead made by reading into the user’s database an ODB entry containing this information. There is a file odat_db.odb in the data directory with an example of how to do this (this would need to be edited to reflect the location of the user’s own directory):


! reading file

.odat t 1 50

C:/alwyn/o/data/

! done


I usually use a Windows shortcut to the O exec file, in order to start O. There is an example of such a shortcut in the data directory (this is a binary file, so no point listing it here). Experienced Windows users probably know about shortcuts; select the O exec file, right click and choose ‘Make shortcut’. You should place a shortcut in each directory from which you run O, but make sure it correctly defines the 'start in' directory. The Windows release of O also differs in how one specifies the use of a stereo-visual. In this release, one adds the text ‘-st’ to the run line in the short cut.


O uses the OpenGL and GLUT for graphics-related calls. Windows users may need to pick up the relevant dll’s, either from me or the Internet.


Double clicking on the shortcut creates a terminal window where the user can start answering O’s prompts for defining a file. The Spawn and $ commands in O use the Unix shell and, therefore, do not work. Since the O Job-system also spawns commands, this system is also not supported.



1.4 User interaction

O is an interactive computer graphics program and, broadly speaking, this is accomplished via the terminal window and/or the 3D window. The program is highly configurable, and can be used without the 3D window, for example. At the other extreme, once the program has been started, the user could do almost all of her/his work in the 3D window. Usually, however, the user interacts with the program in both windows.


1.4.1 At the terminal

O functions are activated by keywords, pull-down menus or macros containing a group of keywords. These instructions can be generated by typing in the terminal window or the 3D window. The 3D window offers other possibilities that include pull-down and pop-up menus that get activated by a pointing device. All typing takes place by non-blocking terminal event handling. Most keywords take the form of pdb_read ,for example, and contain underscore characters. This particular command is activated if the user types pdb_r or pd_r or numerous other possibilities. What is typed must be sufficient to uniquely define the keyword. So typing just p_r would not be enough since there is also a command paint_ramp. Commands are case insensitive and cannot contain the space character.


Many keywords require data input, and again O gives the user some flexibility in how to enter this information. If just the keyword is entered (either at the 3D window, or at the terminal window), the user will be prompted for the extra data. 


 O > pdb_rea

 Util> PDB file :1crn.pdb

 Util> O associated molecule name:1crn

 Util>  Remove hydrogens ? [y]/n :

 Util>  Save CNS/XPLOR SEGIDs ? [y]/n :

 Util>  Combine SEGID & residue name ? y/[n] :

 Util>  Database compressed.

…..


If the user knows what data is to be entered, it can be typed on the same line as the keyword. e.g.


O > pdb_re 1crn.pdb 1crn ;;;


will read in the coordinates of crambin and give the molecule the name 1crn. The semicolons indicate a <return> would have been entered at the respective prompt.


Multiple keywords and /or data can be on the same line, e.g.


O > pdb_re 1crn.pdb 1crn ;;; mol 1crn ca ; end


is enough to read in crambin, make and display an object of just the CA atoms in the 3D window. Again the ';' in the above line indicates to the O-parser that the user would hit a <return> if prompted, and would be the equivalent of accepting the default (in this case a zone describing all the molecule). Special care must be taken with the input of text where buried spaces are allowed. Such input can be delimited by double quote characters (").


The parser recognises 4 special characters, @, !, # and $. The '@' character before a keyword specifies a macro file of commands. All characters following a '!' on a line are treated as comments. The special character, '#', is mainly used in macros. The character string between a pair of #'s will be written to the terminal and be replaced by whatever is typed at the terminal. This allows macros to prompt for terminal input. A word starting with a $ is recognised as a symbol and will be expanded by the parser. For example, the macro draw_mol contains the following commands


% cat draw_mol

! macro to draw a sphere of atoms of user defined radius

mol $my_mol centre_atom a131 c1

spher #Define sphere radius:#

end_object


It would be activated in O by typing


O > @draw_mol

As3> Prompt> Define sphere radius:10


and would make an object of all atoms within a sphere centred on a particular atom of a particular residue (the radius defined by the user at run time as 10) for the molecule defined by the symbol my_mol.


It can be useful to know this level of detail in O but many users build and refine their structures without ever making a macro. The most frequently used commands are available from the 3D window via the graphics user interface. Some functionality, however, is only available from the terminal interface. The directory command, for example, gives detailed information of the user’s database and I only ever use it at the terminal interface. This is a rather nitty-gritty command that is very useful to know about. The Lsq-commands, on the other hand, are more complex and work at a much higher level. They allow one to evaluate similarity between different molecules, defining axes and generating operators that can be applied to 3D objects, or to actual coordinates. They have been used for more than 20 years from the terminal and I still see no good reason to make a GUI equivalent option. The MasterMenu system is part of the graphics interface that I recommend using and here quite complicated macros have been developed that a normal user can use without worrying about the intricacies involved. If you want to peak under the hood, however, the files are available in the ODAT directory, and an introduction provided in the description of the MasterMenu system.


1.4.2 In 3D

O creates only one window, and it is drawn in 3D. The user is able to change the size by clicking on a corner and dragging (this is OS dependent). O always starts with a fixed size of 1024x768 pixels. Although most of the O window is devoted to the display of molecular objects (and associated data), some space is devoted to a simple graphical user interface (GUI). The view into the 3D space of your structure is either square (using the height or width, whichever is the smaller) or rectangular (using the full size of the window) - see ‘Personalising O’ for details on how to do this. At first glance, the GUI would appear to be drawn in 2D; it is just text after all. In fact, the GUI is also drawn in 3D space but with my default black backgrounds, this is not so noticeable. Here is the basic GUI with no other menus open:


Image


1.4.3 Keyboard input

It is up to the user to decide how keyboard input is to be treated when the 3D O window has focus. By default, alpha-numeric keystrokes are entered on the first line at the top of the O window and parsed just as if it were entered in the terminal window. If incomplete, a prompt will be made to the Terminal window. For example, if the the user types mess in the O window, the following appears in the Terminal window

O > Message [Dont worry, be happy.]:

and the program waits for input. 

Some non-printing characters have special functions; in particular the arrow keys are used to control  actions within the ‘Dial Menu’ window (see below);  the <esc> key activates a macro @on_escape, which by default quits the program without saving the contents of the user's database (the user might want to create his/her own macro, to disable this drastic response); some function keys are mapped to O actions (although some are of only historical interest)

F1 - controls quad-buffered stereo on/off if supported by the hardware.

F2 - controls text (menus, prompts etc) on/off

F3 - changes a line drawing mode. This is only of interest to TAJ,

F4 - activates side-by-side, or stencil stereo. Atoms can be identified with the mouse pointer in either image

F6 - activates different fogging options.This is only of interest to TAJ,

F11 - is only used on SG machines. Those with very old versions of OpenGL must hit this key to get the correct 3D effect.

F12 - lists the present function key settings on the terminal window. 

N.B. By default, OS X uses the F9-F12 keys for its own purposes!


If the arcade option is ON (‘A-Z of O’, Arcade_option command), keyboard input is processed to generate input controlling virtual dials and other viewing operations. This feature makes it easy to connect to O hardware that generate character input, such as devices from X-Arcade (solidly built box of joysticks and buttons, now alas in only one, large size, but still available at http://www.xgaming.com for $130),  Belkin (e.g. Nostromo SpeedPad n52, but may not be in production), and Griffin Technology (the PowerMate dial; still available at http://store.griffintechnology.com/desktop/powermate at a price of $45). The latter has a new PowerMate application for setting up the functionality associated with the dial and I have tested it on OSX 10.8 (Mountain Lion). However, it is not my favourite dial-like device; I prefer the SpaceNavigator from http://www.3dconnexion.com although at $75 it is $30 more expensive, but works perfectly under OSX without any extra drivers (see the Customisation section for how to do this).


The O GUI also supports pop-up windows that are allowed to have text input when the relevant window has focus. Keyboard input gets appended to the existing input text on the relevant line (L & R arrow keys are ignored but the <Backspace> key can delete existing text).


1.4.4 Interactive prompt (line 2)

When the user is concentrating on her/his work, interactive prompts would be distracting if sent to the terminal.Instead they are sent to the second line in the 3D window. In the above image, we see the Centre_ID command has been activated, and this prompts the user to ‘ID an atom to define the screen centre.’


1.4.5 ID message information (line 3)

This line shows the ID message information associated with the last identified atom. It can be customised via an O database entry, .message_template. This entry contains lines of text that will be concatenated to form the string to be displayed.  Certain predefined format strings will be shown, but atom and residue properties can be included as well. The atom or residue property names must be at the beginning of a line and be written in full. This is best illustrated by an example and here is the default message template :

.message_template t 9 40

%MOLNAM %RESNAM %Restyp %ATMNAM, xyz =

atom_xyz

; B =

atom_b

; Z =

atom_z

atom_bone

;

residue_2ry_struc

 

This could generate a string like this in the ID text atom message line:


HCAC 43 Ser CA, xyz = -22.06 4.02 37.76 ; B = 25.86 ; Z = 6 ;


ODB entries must be given on separate lines, and if an ODB datablock does not exist, it is simply ignored. In the example above, the atom_bone property value is shown when a skeleton atom is picked, and the element number is shown when a normal atom is picked.No secondary structure nor skeleton data was output because no such ODB entries existed in the user database for this molecule. 


Format strings which can be expanded in the template include:

%MOLNAM Name of current molecule

%RESNAM Name of current residue

%RESTYP Residue type of current residue

%ATMNAM Name of picked atom

%R1 Residue-type in one-letter code

 

The case of the letters in the format string is important and controls the case of the output text. For example, %RESTYP expands to TYR, %Restyp expands to Tyr, and %ReStyp expands to TyR.

 

1.4.6 Active commands (line 4)

O does not prevent a user from activating multiple commands; it’s often a good thing to be doing. The fourth line in the GUI shows what commands are active (Centre_ID in the above image). This line is also useful for the user to see the order in which a Yes/No command is processed. Active commands can be cleared with the Clear_flag command.


1.4.7 O pull-down menu (line 5)

A pull-down system is drawn which can be activated by a pointing device. If one uses a a three button mouse, the left button is used to interact with the pull-down menus. The pull-down is activated by positioning the mouse pointer over some menu text, pressing the left mouse button (say) and then moving the mouse with the button still depressed. Alternatively, the menu can be controlled by button click and release actions. For example, to exit the program and saving the current database, click-release on the text ‘Controls’, a window appears under the text, click-release on text ‘Stop’. Alternatively, one could have first clicked on ‘Controls’, kept the mouse button pressed, moved the mouse down to ‘Stop’ and released the mouse. As the mouse moved or as you clicked, the text and the background changed colour. The command is only activated on a mouse release.


Image


Some of the pull-downs generate new windows. These can be ‘glued’ in position or can be set free. Windows that can be freed have a little green square in the top left corner. 


Image


If you click there, the square changes to solid green, and a second solid red square appears in the top right corner. If you click on the green square and move your mouse, the window will follow. 


Image


The yellow square, at the bottom right corner, indicates that this window has focus and will be displayed above other windows. This is shown more dramatically in the next image where there are now 2 open menus and a 3D object


Image


The ‘Paint mol.’ menu still has focus so it is above the ‘Dial Menu’ but since all of the menu windows take on a limited range of Z-values (the out of plane coordinate), they appear sandwiched between the b-sheets of the 3D sketch of P2 myelin protein. 

Such free GUI windows can also be opened and positioned with the Window_open command. I usually open a few windows when starting O, in particular the window that contains all 3D objects that have been generated, the user specific menu, and the window showing all Virtual A-Ds. This can be done by inserting O commands in the user’s on_startup file (see ‘Personalising O’ for more details on this file) like this:


window_open object_menu -1.3 -0.1

window_open user_menu .95 0.9

window_open dial_menu -1.3 .4


Image


In the object window, those that are ‘on’ are indicated by green text, those that are ‘off’ have magenta text. Similarly in the Dial window, the A-D affected by the keyboard arrows is shown in green text (or reverse highlight if the mouse is depressed in the window). The text in the Dial menu will change, expanding and contracting as the user activates and deactivates O commands that expect A-D input. The width of text windows also changes as the contents of the window or text font change. All O pulldowns are described in the relevant section of ‘A-Z of O’. The above images were generated for the purpose of illustrating the 3D nature of the GUI, and more usually such menus would be located on the left or right side of the 3D window.


1.4.8 Input devices: Dials, Mouse and Keyboard

When the first high performance graphics work stations became available at the end of the 1970s and the beginning of the 1980s, these very expensive systems were sold with often very elegant dial boxes that usually contained 8 dials. My favourite came from Evans & Sutherland with their Picture System 300 system and had individual LEDs for each dial that could be programmed. These dial boxes cost as much as a modern day laptop but they were built to last! Ones that worked with old Silicon Graphics and DEC workstations are stilled supported by O in some OS releases, as are some dial-like devices, gamepads and joysticks. All versions of O, however, are able to process inputs that are generated by 20 virtual dials, a mouse, and a keyboard. The first 8 virtual dials control transformations that are applied to the 3D objects generated by O; the X, Y & Z rotations to be applied, the zoom, the X, Y & Z translational shifts and the slabbing function. Other inputs can be generated as O commands are activated and deactivated. For example, if the user wishes to affect a torsional rotations about a set of bonds, the necessary virtual dials are allocated as needed and then released when done. The current set of in use dials are drawn in the ‘Dial Menu’ menu, which is available as part of the pull-down windowing system. Inputs to these logical devices can also be generated by the mouse (via the ‘Dial Menu’), the keyboard (the arrow keys can be used to choose the dial and to input changes), as well as real dials, gamepads/joysticks, SpaceBall-related devices, and devices that generate keyboard events. 


Dials are supported in the SG, AXP, Apple OSX and Linux versions of O. O assumes there are 8 dials, of which 4 are permanently assigned to controlling the rotation, while the other 4 are assigned to virtual dials as is appropriate. The Dial_next and Dial_last commands can be used to redefine the mapping between the virtual and real dials. The user must use the DIALS environment variable to indicate that they are available. The user can customise the appearance of text at the bottom of the 3D window to show the mapping between virtual and real dials.


O can be used with a three or single (only Apple used these, and thankfully they’ve stopped) button mouse. A 3-button mouse is preferred but my laptop, for example, has only a single ‘button’.


1.4.9 Three button mouse controls

The right mouse button controls the view when it is depressed and in the 3D window. Moving the mouse then rotates the picture in the direction of motion. To rotate the view around the vertical axis, slide the mouse to the right or left. To rotate around the horizontal axis, slide the mouse up or down. If the right and middle buttons are depressed at the same time, the picture rotates around a third axis, perpendicular to the screen. Moving the mouse down rotates the picture clockwise, and moving it up rotates it anti-clockwise. The middle button when depressed by itself, controls both zoom and clipping. Up-down for zoom, and right-left for clipping. The left button is used for identifying atoms and activating O’s pull-down windowing system. Mouse button actions change if the <ctrl>-key is depressed. If the mouse is moved after first depressing the <ctrl>-key and then the mouse right button, the 3D window will usually pan horizontally and vertically as the mouse is moved. However, if the grab commands are active, the motion is used to change the orientation of the fragment/residue by rotations around the horizontal and vertical screen axes.


1.4.10 Single button mouse

A press and release triggers an atom identification. A press while over a window in the pull-down system activates the windowing system, otherwise the motion is treated as a rotation. If the <ctrl>-key is depressed, and then the mouse button depressed, motion is usually mapped to panning. If the <alt>-key is pressed instead, the mouse can be used for zooming (up/down motion) and clipping (left/right motion). If the Grab-commands are active, however, depressing just the <ctrl>-key and then the mouse, the motion is used to change the orientation of the fragment/residue by rotations around the horizontal and vertical screen axes. Keeping <ctrl> and <alt> keys pressed will map mouse motion to a rotation around an axis perpendicular to the screen.


1.4.11 Keyboard

Some function keys are mapped to O actions (although some are of only historical interest)

F1 - controls quad-buffered stereo on/off if supported by the hardware.

F2 - controls text (menus, prompts etc) on/off

F3 - changes a line drawing mode. This is only of interest to TAJ,

F4 - activates side-by-side, or stencil stereo. Atoms can be identified with the mouse pointer in either image

F6 - activates different fogging options.This is only of interest to TAJ,

F11 - is only used on SG machines. Those with very old versions of OpenGL must hit this key to get the correct 3D effect.

F12 - lists the present function key settings on the terminal window. 

N.B. By default, OS X uses the F9-F12 keys for its own purposes!


The keyboard <esc>-key activates a macro @on_escape. The macro that is distributed in the menu.odb file quits the program without saving the contents of the user's database. The user can (of course) create his/her own macro, to disable this drastic response.


The first 8 logical dial inputs (controlling views, zoom etc) are available via mouse shortcuts, the others can be activated with the keyboard <arrow>-keys. The up and down <arrows> move through the possible virtual dial inputs (the current one is indicated in the ‘Dial Menu’ with inverse background colour when selected by the mouse or otherwise green), while the left/right <arrows> trigger inputs. The user can also use the mouse to click in the ‘Dial Menu’ window to specify the active input. As virtual dials are activated and released, the ‘Dial Menu’ expands, shrinks and changes contents.


The keyboard <ctrl> and <alt>-keys are used in conjunction with the mouse to control the view and with the Grab-commands to apply rotations to the grabbed atoms. If the user moves the mouse outside the 3D window when <ctrl> is pressed, and then the key is released, and then the mouse moved back into the window, O thinks that the <ctrl> is still depressed and acts accordingly. Just press the <ctrl>-key again, and release it.


1.4.12 Gamepad/Dials/Pucks

The Apple OSX version of O supports gamepad input under the control of an environment variable GAMEPAD. However, very few of the gamepads that I have tested actually work with Apple's GLUT-based implementation. In fact, only my Microsoft Joystick works according to the specification, which is almost embarrassing. The 3D-Connexion devices, however, work as if they are Spaceballs and Apple’s OpenGL implementation actually has real call-backs for them. You do not need to install any drivers, just plug and play. One warning though, I’ve only tried the cheap ones called the SpaceNavigator and SpaceTraveler. I would guess the expensive pucks will work but I don’t know for sure. I actually have a puck but it has a serial connection and I’m not going to spend more money on one of them.


SG systems support dials (both SG versions), and puck (GLUT version) input devices. The last version of O for SG systems was Ov13


SG and AXP-style dials work under OS X and Linux thanks to David Gohara. You'll need a serial to USB adaptor. Apple stopped using serial input many moons ago, and the old dial-boxes use serial connections. I used the IOGear GUC232A which took 2-3 weeks to get delivered, here in the wild North. OS X users will need to install their driver, Linux users do not have to install anything extra. David has written a library to read these dials that works with OS X & Linux’s low level system routines, not GLUT. You can find more information on model parts etc, his homepage:


http://www.sbgrid.org/osx.php?hardware=1&id=1


You need to tell O that dials are connected via an environment variable, like this if you use SG dials:


% setenv DIALS SG


or like this for AXP versions:


% setenv DIALS AXP


In my use of David’s routines, I have hard-wired the port, which should not cause any problem. If you unplug the dials, reset the environment variable. I've tried my historical assortment of serial devices in the USB adaptor, but my Spaceball, Spacemouse did not register changes to the ball/puck.


Griffin Technology sell a single dial USB device called the PowerMate that works fine with OS X, at least (most recently tested with OS X 10.8), but it is also supposed to work with various flavours of Windows. Their software generates keyboard input that depends on which way you turn the dial. For it to work with O (OS X), you need to download the latest PowerMate application and battle with the settings. I managed to get the 'Global Settings' in their applet to trigger sending right and left arrow key strokes. This makes it behave as if you are using the keyboard arrows to control the dial inputs. I've not tested the Windows version yet. Griffin also used to support multiple dials but I’ve not looked into it.


X-Arcade (http://www.xgaming.com) make a series of input devices that are really SOLID. They work by generating characters and should, therefore, work on any system. They are large, and made out of wood (and metal)! I’ll post a picture of 2 player model with my Mac Air sometime, but an older picture is available ‘A-Z of O’ under the Arcade_setup description. They seem to have stopped making the single joystick device.


Last but not least, every graphics system has a keyboard. If the user switches to arcade mode (see ‘A-Z of OArcade_setup), the keyboard and mouse become a powerful pair of input devices. 


I have quite a few old dial boxes, and various other input devices. The only one I actually use is the  3D-Connexion SpaceNavigator, which I set up on my iMac with a reduced set of degrees of freedom - I use just 2 out of the 6- with a sensitivity that I find appropriate. I am tempted to buy a SpaceMouse Pro but I’m cheap.


1.5 Customisation

The O database allows me to store default values for almost everything that is done in the program. For example, all the keywords that users work with, are entries in the ODB and if you want to make your own set, feel free. Similarly, all of the windows that are generated in the 3D O window are described in detail (text, colours etc) in the ODB. I have never had complaints from colour blind users, but it is straightforward to change things if my choice of colour is not appropriate. Most people do not change my defaults, but some things must or should be set by the user.


1.5.1 Environment variables

Two environment variables must be set under all circumstances since they reflect the users’s setup and file system:

ODAT directory containing O’s dictionaries.

OTMP directory containing O’s temporary files (generated by the job system and by the undo commands).


Five more can be set if you want to use the relevant functionality:

OJOB directory containing O’s Job templates.

STEREO to load the stereo-specific graphics visual if set to ON .

DIALS to read dials if set to value SG or AXP .

GAMEPAD to read a gamepad (OSX & Linux) if set t ON .

O3D if set to ‘NO’, O will not generate a 3D graphics window.


1.5.2 When starting O

The macro @on_startup is activated as soon as O starts. The following example opens and positions three of the most frequently used pull-down windows to the left and right within the 3D O window; reads in a pair of maps with suitable names, levels and space group information; opens the associated FastMap slider windows to control the drawing of the electron density; and then leaves just the CA objects visible


window_open object_menu -1.3 -0.1

window_open user_menu .95 0.9

window_open dial_menu -1.3 .4


! read in 2 different maps

fm_file ano1.map mir p212121

fm_set mir 50. ;; 1.5 ;

fm_dr ;


fm_file av_5.map av p212121

fm_mult av ;

fm_set ; ; ; ; 1.5 ;

fm_dr ;


! Open the FastMap sliders

window_open density_1 −0.95 −0.6

window_open density_2  0.55 −0.6


! switch off all CA objects

vis * ;

vis *_ca on


All O users should have a customised @on_startup macro in each of their working directories,


1.5.3 ID message information

The third line in the 3D O window shows the ID message information associated with the last identified atom. It can be customised via an O database entry, .message_template. This entry contains lines of text that will be concatenated to form the string to be displayed.  Certain predefined format strings will be shown, but atom and residue properties can be included as well. The atom or residue property names must be at the beginning of a line and be written in full. This is best illustrated by an example and here is the default message template :

.message_template t 9 40

%MOLNAM %RESNAM %Restyp %ATMNAM, xyz =

atom_xyz

; B =

atom_b

; Z =

atom_z

atom_bone

;

residue_2ry_struc

 

This could generate a string like this in the ID text atom message line:


HCAC 43 Ser CA, xyz = -22.06 4.02 37.76 ; B = 25.86 ; Z = 6 ;


ODB entries must be given on separate lines, and if an ODB datablock does not exist, it is simply ignored. In the example above, the atom_bone property value is shown when a skeleton atom is picked, and the element number is shown when a normal atom is picked.No secondary structure nor skeleton data was output because no such ODB entries existed in the user database for this molecule. 


Format strings which can be expanded in the template include:

%MOLNAM Name of current molecule

%RESNAM Name of current residue

%RESTYP Residue type of current residue

%ATMNAM Name of picked atom

%R1 Residue-type in one-letter code

 

The case of the letters in the format string is important and controls the case of the output text. For example, %RESTYP expands to TYR, %Restyp expands to Tyr, and %ReStyp expands to TyR.


This ODB will not be changed so often but if I calculate any new residue properties (e.g. the average B-factor of each residue, or Pep-flips, for example) I would modify the template accordingly.


The text that is drawn in 3D close to the actual atom that has been identified, can also be customised by defining an ODB entry .id_template that contains your preferred definitions. In the absence of the template, which is the default, only the residue name and atom name is displayed at the atom. The following template would display the molecule, residue and atom names whenever you make an ID:


.id_template t 1 40

%MOLNAM %RESNAM  %ATMNAM


and look like this after identifying a couple of atoms:


Image


where both atoms belong to molecule P2, residue A132 and have atom names O1 and C1.


1.5.4 Changing OpenGL Variables

O has 2 ODB entries that affect the rendering of graphics primitives and the interaction with the user. In Ov11, these were extended to give you better control of depth cueing, better mouse control, change the shape of the 3D viewing window, and control the behaviour upon issuing centring commands.


O > db_kill *ogl*

Heap> Deleted .OGL_LIGHT

Heap> Deleted .OGL_OPTIONS

O > wr .OGL_LIGHT ;; 

.OGL_LIGHT R 16 (8(1x,f8.4)) 

   0.0000   1.0000   1.0000   0.3000   0.0000  15.0000   0.0000   0.0000

   1.0000   1.0000  15.0000 -20.0000   2.0000   0.0000   2.5000   0.0000


The .ogl_light ODB contains lighting information that can be set with the Sketch_light command (entries 1-12) and fogging information (13-16). In Ov11 and later, you can control depth cueing affects by modifying the fog-related variables. Entries 13-14 are start and end fogging values for the line-based objects, while 15-16 are for solid objects. These have a marked influence on the objects! For example, where is a surface, and cartoon of P2 myelin with the default solid fog levels of 2.5/0.


Image

and now with 1.0/0. 


Image

The fog values that you use depend on your taste and what you are trying to show. If you do not like my default settings, just write out the ODB entry, modify it as appropriate and include it in your own startup.odb file.

The values that you prefer may also depend on the background colour (set with Screen_colour ‘A-Z of O’).


The .ogl_options ODB also contains a few new entries that might be of interest:


O > wr .OGL_OPTIONS ;;

.OGL_OPTIONS              I         14 (20(1x,i3))                             

   3  20  10   1   2   3   0  50   1   0   0   1 100   0


Entry 1 defines the number of mouse buttons.

Entries 2 & 3 define the line width for atomic and map objects scaled by 10

Entries 4-6 allows one to reassign the mouse buttons to the mouse action. In the above, button 1 is assigned to the left most button, button 2 to the middle and 3 to the right-most button.

Entry 7 ????

Entry 8 is the chip constant, setting to 0 means that centred atoms will jump to the screen centre (Ov10 and earlier versions worked like this), using 50 is a nice glide through space to the new centre, something larger would be too lazy. Using a larger value increases the number of steps taken on chipping from the old centre to the new one. O calculates how long it needs to make a refresh, so the total glide time is independent of the complexity of the images being displayed. In very complex images, though, there will be fewer steps.

Entry 9 is set to 0 for a square shaped window into the 3D world, else a rectangular one. 

Entry 10 controls which fonts are used in the pull-down windowing system. Values in the range 0-7 are allowed, and the default is 0. These corresponds to fonts Helvetica 12, fixed width 8 by 13, fixed width 9 by 15, Helvetica 10, Helvetica 12, Helvetica 18, Times Roman 10 and Times Roman 24. Fonts can also be changed by using the master-menu system. 

Entry 11 controls the display of Dial-related text and the behaviour of the ‘Dial Menu’. If this entry is set to 0, the the up/down arrows moves up and down in the the ‘Dial Menu’, and no dials-related text is seen at the bottom-centre of the 3D window. If the DIALS environment variable is set, this entry has the value of 1 or 2 (for SG, AXP, respectively), the dials-related text is displayed at the bottom, centre of the screen and the arrow keys control the natural movement in this window rather than the ‘Dial Menu’ window (where the movement is now down-up). If you prefer this way (the old way) of working, you can set to non-zero even if you do not have dials. Default, however, is to use the up/down arrows to move naturally in the ‘Dial Menu’ window. 

Entry 12 controls the Bell sound. With a value of 0, the bell is off, and 1 it is on. O issues a bell sound as a warning on some occasions. You may find it annoying.

Entry 13???

Entry 14???


1.5.5 ID text

O can be configured with the .id_message template to modify the actual text that gets displayed when an atom is identified (see above). The user can also control how many text items are displayed per object and the colour. This information is stored in the ODB entry .MOLEC_OBJ_INTEGER and has an immediate effect when the relevant entry is changed. By default, ID text is drawn at 3 atoms per object, and is coloured red. The number of atoms is stored in entry 9 in the ODB, and the colour I(as a packed RGB triplet) in entry 8. To change the number to 5 atoms per object, one would use the Db_Set_data command as follows:


O > d_s_d .MOLEC_OBJ_INTEGER  9 9 2


And now only 2 atoms pr object would be displayed. Since the colour is encoded as a packed triplet of RGB values, changing it is best done in multiple steps by first defined the default colour to the Paint-commands, listing it as a packed triplet, and then setting the necessary item in the ODB:


O > Paint_colour sky_blue

O > wr  .ACTIVE_COLOUR  ;;      

.ACTIVE_COLOUR            I          1 (10(1x,i7))                             

 3316172

O > d_s_d .MOLEC_OBJ_INTEGER  8 8  3316172



1.5.6 Default FastMap units in density slider windows.

FastMaps have two modes for how the real-time density slider changes the contouring level. When a new map is read in (Fm_file) or generated (HKL_Fourier), the current default mode is taken. This is stored in .fm_real entry 2 with allowed values 0.0 or non-zero for absolute or RMS units of density, respectively. If .fm_real does not exist or is deleted, the default is set to 0.0 . The mode can later be changed for any map via the Fm_mode command (see 'A-Z of O').


Electron density maps are usually read or made using the so-called FastMap systems (there is an older set of Map-commands that I no longer use). The user can modify the contouring level via the FastMap slider window and is able to work in absolute units (electrons/cubic Å) or in RMS-units. The default value that is used when the map is read or otherwise created in O is controlled by the second item in the .fm_real ODB vector. This default value can, of course, be changed by the user with the Db_set_d command


The following will set the default to RMS units:

O > d_s_d .fm_real 2 2 1.


while the following sets the mode back to absolute units:

O > d_s_d .fm_real 2 2 0.


If the .fm_real ODB is deleted or does not exist, the default mode is set to use absolute units. In experimental maps, as well as calculated maps of type 2|Fo|-|Fc|, the RMS value of the whole map is often a good starting point for inspecting the electron density. This is not the case in |Fo|-|Fc| maps; use the Water_profile command to decide what is reasonable.


1.5.7 Arcade and Spaceball actions

O can work in a mode where key strokes to the 3D window do not get parsed as O commands, rather they are evaluated as interactive control codes. This so-called arcade mode is fully described in Arcade_setup in 'A-Z of O' and the default mapping is:


O > wr .ARCADE_CODES ;;

.ARCADE_CODES             T         16         24

q GRAB_ROT_X    -3.00000

w GRAB_ROT_X     3.00000

a GRAB_ROT_Y    -3.00000

s GRAB_ROT_Y     3.00000

z GRAB_ROT_Z     3.00000

x GRAB_ROT_Z    -3.00000

e DIAL_05       -0.20000

r DIAL_05        0.20000

d DIAL_06        0.20000

f DIAL_06       -0.20000

c DIAL_07        0.20000

v DIAL_07       -0.20000

1 DIAL_04       -1.00000

2 DIAL_04        1.00000

3 DIAL_08       -1.00000

4 DIAL_08        1.00000


WIth this mapping, the user would control the view with the mouse, but use the a block of keys to the left of the keyboard to rotate Grab’ed frgaments, 1-4 to zoom and clip the scene view, and 6 more to translate the view  (not so important in my opinion).


OS X versions of O also support the 3D-Connexion ‘dial’ devices. The implementation is similar to the arcade mode, but the assignments are specified in a different ODB called ‘.SPACEBALL_CODES’ for all 6 of the outputs generated by the device. I have only taken 2 of them as default: 


 O > wr .SPACEBALL_CODES ;;

.SPACEBALL_CODES          T          6         25

rx DIAL_01        1.00000

ry                1.00000

rz DIAL_02        1.00000

tx                1.00000

ty                1.00000

tz                1.00000


This sort of device generates 3 rotations ( I call them rx, ry, rz) and 3 translations (tx, ty, tz) but I found that accepting more than 2 degrees of freedom was too much for me. With the default assignments, twisting the ‘dial’ causes a rotation about the vertical axis in the O graphics window, while ‘pushing’ on it causes a rotation about the horizontal axis. You might prefer other ways of interacting with these devices. As with the arcade codes, you can also assign inputs to Grab rotations. So this might be an alternative assignment when using Grab_build:


O > wr .SPACEBALL_CODES ;;

.SPACEBALL_CODES          T          6         25

rx GRAB_ROT_X        1.00000

ry GRAB_ROT_Y        1.00000

rz GRAB_ROT_Z        1.00000

tx                1.00000

ty                1.00000

tz                1.00000


The float is a multiplicative scale factor. The action text must be capitals (oops, sorry).

N.B. You do not need to install any drivers for this device to work under OS X


1.5.8 User menu

This was once the most important thing for a user to customise. Now I have tried to persuade people to use the Mast-Menu system, although some customisation is still possible (see below). Since I think it is useful for a user to understand how this works, I will explain it but I still hope you use the Master-Menu approach,

The user can set up a menu of commands or a list of macros to supplement O's pull-down system. They exist in a ODB entry called .menu and can be separated by menu colouring commands. An ODB entry could be generated in the user’s file system with a text editor to look like this:


.menu t 7 50

colour_text green

Save

Stop

Quit

colour_text red

@next_residue

@last_residue


If the file were called my_menu.odb ,for example, it could be read into O by issuing ‘read my_menu.odb’ and the user menu window would change to this:


Image


The green text items are O commands, the red text are (presumably) O macros since they start with ‘@’.


If the user works with the Master-Menu, the Rebuild-Menu allows for customisation via the ‘User specific’ blind:

Image


This in turn expands the menu with the contents of the ODB called user_specific . The default contents contain comment lines with the text ‘Not defined’:


O > wr USER_SPECIFIC ;;

USER_SPECIFIC             T          5         72

<Not defined> !                                                         

<Not defined> !                                                         

<Not defined> !                                                         

<Not defined> !                                                         

<Not defined> !     


If you wanted to add a Quit-option to the menu, you could do it by creating a file (user.odb say), which contained this text:


user_specific t 2 50

colour_text red

<Quit without saving> Quit


First close the ‘User specific’ blind, then read in the new ODB


O > read user.odb 


and the menu should change to this once the blind is expanded:


Image


1.5.9 O system macros in ODB 

There are a number of macros in the ODB that O runs under certain circumstances. These macros are defined in the menu.odb file and some of them could be modified to the user’s advantage. Here they are ordered according to the usefulness of being changed:


@on_escape macro is activated when the user types the <esc>-key on the keyboard. In the distribution, this causes the program to Quit without saving the database:

@on_escape t 2 50

print "quit, nothing saved" 

quit

This is a rather dramatic action for some people and you might want to modify it.


@on_centre is a centring-related macro. The numerous commands that re-define the screen centre in O all activate the @on_centre macro. The distributed macro updates just the current map:

@on_centre t 1 50

fm_dr ;

The ‘active’ map is the one currently selected in the Density-pulldown/Density window, or by the last Fm_Setup, Fm_draw, or Fm_file command.


@on_stereo_chem is the stereochemistry restraint generation macro. A number of commands activate the generation of stereo-chemical restraints (Pdb_read, ...). The distributed macro assumes there is a continuous chain of residues, without breaks:

@on_stereo_chem t 1 50

refi_gener ;;

O tries to recognise breaks in the chain but this might be a better way of ensuring there are no incorrectly defined restraints,


The rest are unlikely to be of much interest to the average user.


@on_baton_yes

When using the Baton_build command, the following macro is drawn when the user hits Yes. In the distribution, a new contour is made of the current electron density map

@on_baton_yes t 1 50

fm_dr ;


@on_graph_pick 

On picking in the Graph window (Graph 'Graph it' Pull-down), the following macro is activated

@on_graph_pick t 1 50

cen_atom ${.id_m} ${.id_r} ${.id_a}

The distribution macro centres on the Ca atom of the residue, or on the atom identified


@on_rama_pick 

On picking a symbol on the Ramachandran plot (Graph Rama Pull-down), the following macro is activated

@on_rama_pick t 1 50

cen_atom ${.id_m} ${.id_r} ${.id_a}

The distribution macro centres on the Ca atom of the residue


TRACE-related macros

This macro is activated whenever O wants to update the TRACE molecule to show all atoms:

@on_trace_draw t 6 50

mol trace 

sel_off trace ;

sel_prop residue_traced = 1 on

sel_vis

db_kill trace_connectivity

zon ; end


and the following is activated to show only central atoms:


@on_trace_draw_ca t 6 50

mol trace 

sel_off trace ;

sel_prop residue_traced = 1 on

sel_vis

db_kill trace_connectivity

ca ; end


For proteins, these macros show a poly-alanine and CA representation, respectively.


The Decor_show macro:

See Decor_show in ‘A-Z of O’ for more details. This macros is distributed showing the fit of 5 differently sized amino-acids (Phe, Arg, Leu, Val, Ser) to the poly-alanine TRACE :

@on_autofit t 5 50

mol scarg z ; end

mol scphe z ; end

mol scleu z ; end

mol scval z ; end

mol scser z ; end


Display/Paint Menu Pulldown macros:

There are a number of distribution macros that paint the user molecule as follows:

Paint by atom: by Z-value so that carbons are yellow, nitrogens blue, oxygens red, sulphurs green, a number of others magenta: 

@pt_by_atom t 3 50

pai_case ; 4 6 7 8 16 yellow blue red green

pai_case ; 3 9 15 17 magenta magenta magenta 

pai_case ; 2 35 53 magenta magenta


Those atoms not defined in the macro remain unchanged (default yellow).


Paint red->blue: my favourite rainbow colouring scheme:

@pt_red_blue t 1 50

paint_ramp ; ; red blue

Most people use the alternate scheme, but this is mine. I first used rainbow colouring in about 1984!


Paint blue-> red: alternate rainbow colouring scheme:

@pt_blue_red t 1 50

paint_ramp ; ; blue red


Paint by B: paint according to the temperature factor of each atom:

@pt_by_b t 1 50

paint_ramp atom_b ; blue 1 0 0