![]() |
RasTop 1.3. Help
|
![]() |
![]() |
![]() |
![]() |
||||||||||||||||||||
![]() |
Using RasMol Machine compatibilityRasMol runs on wide range of architectures and operating systems including Microsoft Windows, Apple Macintosh, UNIX and VMS systems. UNIX and VMS versions require an 8, 24 or 32 bit colour X Windows display (X11R4 or later). The X Windows version of RasMol provides optional support for a hardware dials box and accelerated shared memory communication (via the XInput and MIT-SHM extensions) if available on the current X Server. The program reads in a molecule coordinate file and interactively displays the molecule on the screen in a variety of colour schemes and molecule representations. Currently available representations include depth-cued wireframes, 'Dreiding' sticks, spacefilling (CPK) spheres, ball and stick, solid and strand biomolecular ribbons, atom labels and dot surfaces. The X Windows version of RasMol provides optional support for a hardware dials box and accelerated shared memory communication (via the XInput and MIT-SHM extensions) if available on the current X Server. Working with the source, modifying RasMolRasMol is an evolutive project with an almost open source (please read the important Notices). RasMol is mostly written in C and can be compiled on any C compiler. Running RasMol Under UNIX or VMSTo start RasMol from either the UNIX or VMS prompt, type the command 'rasmol'. This command can be followed by an optional filename. By default, immediately upon starting, the program displays the following message to identify the version number and display depth of the running program. There will be some variation in this message depending on your choice of platform: RasMol Molecular Renderer Roger Sayle, August 1995 Copyright (C) Roger Sayle 1992-1999 Version 2.7.1 June 1999 Copyright (C) Herbert J. Bernstein 1998-1999 *** See "help notice" for further notices *** [32-bit version] Immediately underneath this banner message appears the program's command line prompt
'RasMol>'. If the program is being executed under the X Window System, the program
determines the type of the display being used. If the screen has either an 8 bit or 24 bit
colour frame buffer, RasMol creates another window, which is used to display menu options
and the rendered images. If a suitable screen is not available, RasMol may only be used
from the command line. Commands may be typed to manipulate the model, and to output the
generated image to a raster file. If the program is run under the X Window System environment with a suitable colour
screen, RasMol creates an additional window to display the rendered molecule
interactively, as it is manipulated. If RasMol is not run under the X Window System, the
program displays the message 'No suitable display detected!'. RasMol may be instructed not
to display a graphics window by using the command line option '-nodisplay'. This is
particularly useful for running RasMol as a background or batch process. It is possible to specify either a coordinate filename or a script filename or both on
the UNIX/VMS command line. A script file may be specified by adding the option '-script
<filename>' to the command line. A molecule coordinate file may be specified by
placing its name on the command line, optionally preceded by a file format option. If no
format option is given, the specified coordinate file is assumed to be in PDB, CIF or
mmCIF format. Valid format options include '-pdb', '-mdl', '-mol2', '-xyz', '- alchemy',
'-charmm', '-mopac' and '-cif' which correspond to Protein Data Bank format, Molecular
Design Limited's Mol file format, Tripos's Sybyl Mol2 file format, MSC's XMOL XYZ file
format, Tripos's Alchemy file format, CHARMm file format, J. P. Stewart's MOPAC file
format and IUCr CIF or mmCIF file format, respectively. If both a coordinate file and a
script file are specified on the command line, the molecule is loaded first, then the
script commands are applied to it. If either file is not found, the program displays the
error message 'Error: File not found!' and the user is presented the RasMol prompt. In order to leave RasMol, the user can type the command quit or exit at the RasMol prompt, and the program will return the user to the familiar unix prompt. Alternatively, if a prompt other than the main RasMol prompt is being displayed, the user may hit control-C (^C) to leave the program. The message '***Quit***' will be output to the terminal, before the usual unix prompt is redisplayed. The program may also be terminated by selecting the Quit menu option, on the bottom of the main menu. Running RasMol Under Microsoft WindowsTo start RasMol under Microsoft Windows, double click on the RasMol icon in the program manager. When RasMol first starts, the program displays a single main window (the display window) with a black background on the screen and provides the command line window minimized as a small icon at the bottom of the screen. The command line or terminal window may be opened by double clicking on this RasMol icon. It is possible to specify either a coordinate filename or a script filename or both on the windows command line. A script file may be specified by adding the option '-script <filename>' to the command line. A molecule coordinate file may be specified by placing its name on the command line, optionally preceded by a file format option. If no format option is given, the specified coordinate file is assumed to be in PDB, CIF or mmCIF format. Valid format options include '-pdb', '-mdl', '-mol2', '-xyz', '- alchemy', '-charmm', '-mopac' and '-cif' which correspond to Protein Data Bank format, Molecular Design Limited's Mol file format, Tripos's Sybyl Mol2 file format, MSC's XMOL XYZ file format, Tripos's Alchemy file format, CHARMm file format, J. P. Stewart's MOPAC file format and IUCr CIF or mmCIF file format, respectively. If both a coordinate file and a script file are specified on the command line, the molecule is loaded first, then the script commands are applied to it. If either file is not found, the program displays the error message 'Error: File not found!' and the user is presented the RasMol prompt. Running RasMol on the Apple Macintosh/PPCTo start RasMol on the Macintosh, double click on the RasMol icon using Finder. When RasMol first starts, the program displays two windows, the top window (with the black background) is the graphics or canvas window and the window underneath it (with the white background) is the RasMol command line window. RasMol on the Macintosh may also be started by double clicking on a file owned/created by the application with the signature 'RSML'. This will start up RasMol and pass the selected file to be loaded. There is no way of specifying the file format on the command line with a Macintosh so RasMol attempts to determine the file format by inspecting the file's type signature. Files with type signature 'RSML' are assumed to be RasMol scripts, files of type 'mMOL' are assumed to be MDL Mol files and all other types (principally 'TEXT') are assumed to be in PDB format. Unlike other versions of RasMol it is impossible to specify both a script and a coordinate file simultaneously. Dragging and dropping multi-file 'movie' scripts onto aliases or copies of the RasMol application file may fail due to confusion about which is the correct script folder. Double-clicking on a script may lead to similar problems if copies are present. Note that because on a Macintosh only one 'instance' of an application may be running at any one time, if you were double click on another file owned by 'RSML', the running copy of RasMol would zap its molecule and load the newly specified file. RasMol's WindowOn all platforms RasMol displays two windows, the main graphics or canvas window with a black background and a command line or terminal window. At the top of the graphics window (or at the top of the screen for the Macintosh) is the RasMol menu bar. The contents of the menu bar change from platform to platform to support the local user interface guidelines; however, all platforms support the 'File', 'Display', 'Colours', 'Export' and 'Options' pull-down menus. The Main graphics window also has two scroll bars, one on the right and one at the bottom, that may be used to rotate the molecule interactively. While the mouse pointer is located within the graphics area of the main display window, the mouse pointer is drawn as a cross-hair cursor, to enable the 'picking' of objects being displayed; otherwise the mouse pointer is drawn as an arrowhead. Any characters that are typed at the keyboard while the display window is in 'focus' (meaning active or foreground) are redirected to the command line in the terminal window. Hence you do not need continually to switch focus between the command line and graphics windows. The display window may be resized at any point during the session. This has the effect of simply rescaling the image displayed on the canvas. RasMol imposes limits on the size of the display window such that the window must be large enough to display the menu and scroll bars and yet small enough to fit on a single screen. Attempts to enlarge the screen may fail owing to insufficient memory on the host machine, in which case RasMol reports the error message 'Renderer Error: Unable to allocate frame buffer!' or some similar error. On eight bit displays, when the number of colours required by the program exceeds the number of free colours on the screen, the program uses its own colourmap. This has the effect of temporarily displaying all windows other than the display window in false colours while the mouse pointer is within the display windows. If the mouse pointer is moved outside the display windows, the original colours of the other windows return, and the image on the canvas is shown in 'false colour'. Once the number of colours required by the program drops again, the presentation of colours returns to normal. MouseHere is a summary of RasMol's mouse click-and-drag controls. The 'set mouse' command mode defaults to 'set mouse rasmol', which gives the controls summarized below. However, there are also 'set mouse insight' and 'set mouse quanta' modes (not shown below).
*On some Macs, the Option (Alt) key has the same effect Dial BoxesIf RasMol detects a 'dials box' attached to the user's workstation, it also allows the
molecule to be manipulated interactively by the dials. Once RasMol starts up, it labels
the LED displays above each dial, 'ROTATE X', 'ROTATE Y', 'ROTATE Z' and 'ZOOM' across the
top row from left to right, and 'TRANS X', 'TRANS Y', 'TRANS Z' and 'SLAB' from left to
right across the bottom row. Rotating any of the knobs will automatically transform and
redisplay the molecule interactively. The dials only have effect while the mouse pointer
is within the display window. If more than one application is using the dials box at a
time, care must be taken to remember the dial labels assigned by each program, as each
application may overwrite the dial-label LEDS. The rotation about the X and Y axes automatically updates the indicators on the appropriate scroll bars. All the rotation dials rotate the molecule 180 degrees for a complete revolution of the dial. All the remaining dials clamp their values to permissible ranges; turning these dials past their limits has no effect. The centre of rotation of the molecule may be changed using the 'centre' command on the command line, or the command 'set picking centre' followed by a mouse click. The 'ZOOM' dial allows the interactive zooming of the molecule between 10% and 200% of the original default magnification. Rotating the dial clockwise magnifies the molecule and anticlockwise shrinks it. A complete revolution of the dial corresponds to a 100% change in scale. The 'SLAB' dial, which is only effective when slabbing is enabled, allows the user to move the front z-clipping plane from the nearest point on the molecule to the furthest. A complete rotation of the SLAB dial corresponds to moving the clipping plane half the distance between the front and back of the molecule. Turning the SLAB knob clockwise moves the clipping plane closer to the viewer (increasing the number of objects displayed), and turning it anticlockwise moves it further away (preventing more objects from being displayed). Slabbing mode is enabled by typing the command 'slab on' on the command line or toggling the slab option on the options menu. Translation along the X and Y axis allows the centre of the molecule to be moved within the canvas area of the screen. Rotation and zooming are still performed relative to the centre of rotation and the molecule, respectively, which may often not be at the centre of the canvas. The TRANS Z dial currently has no effect. Scroll BarsThe scroll bar across the bottom of the canvas area is used to rotate the molecule about the y-axis, i.e. to spin the nearest point on the molecule left or right; and the scroll bar to the right of the canvas rotates the molecule about the x-axis, i.e. the nearest point up or down. Each scroll bar has an 'indicator' to denote the relative orientation of the molecule, which is initially positioned in the centre of the scroll bar. These scroll bars may be operated in either of two ways. The first is by clicking any mouse button on the dotted scroll bar background to indicate a direct rotation relative to the current indicator position; the second is by clicking one of the arrows at either end of the scroll bar to rotate the molecule in fixed sized increments. Rotating the molecule by the second method may cause the indicators on the scroll bars to wrap around from one end of the bar to the other. A complete revolution is indicated by the indicator travelling the length of the scroll bar. The angle rotated by using the arrows depends upon the current size of the display window. PickingIn order to identify a particular atom or bond being displayed, RasMol allows the users to 'pick' objects on the screen. The mouse is used to position the cross-hair cursor over the appropriate item, and then any of the mouse buttons is depressed. Provided that the pointer is located close enough to a visible object, the program determines the identity of the nearest atom to the point identified. The program will display, in the terminal window, the atom's type, serial number, residue name and residue number. If the atom is a member of a named chain, the chain identifier is also displayed. Two examples of the output generated by selecting an atom are displayed below: Atom: CA 349 Group: SER 70 The first line describes the alpha carbon of the serine-70 amino acid in a protein. The unique Protein Data Bank serial number for this atom is 349. The following line describes the oxygen atom in a water molecule attached to the P chain of the main molecule. The word 'Hetero' distinguishes heterogeneous molecules (such as cofactors) from the residues in the main molecule, noted by 'Group'. [These two atoms are referred to by the two atom expressions 'SER70.CA' and 'HOH205:P.O', respectively, when using the RasMol commands 'select' and 'restrict'.] Clicking the mouse on an atom can be used not only to identify it, but also to find the coordinates, the distances between two atoms (or to display a distance monitor), the bond angle defined by three atoms, the torsion angle defined by four atoms, to toggle labels on or off, or to specify the centre of rotation. See the 'set picking' command for details. Startup Inititalisation FilesEach time RasMol is started, it searches for an initialisation file of commands to run before the command prompt is presented to the user. The file is called .rasmolrc on UNIX systems, and RASMOL.INI on VMS and Microsoft Windows Systems. The format and execution of this file is identical to that of the RasMol script command. RasMol first looks for the initialisation file in the current directory and if it is
not found will look for it in the user's home directory. On all systems the environment
variable HOME may be used to name the user's home directory. If no personal
initialisation file is found the program looks for the file rasmolrc (or RASMOLRC)
in the RasMol system directory pointed to by the environment variable RASMOLPATH.
This directory should also contain the on-line help file rasmol.hlp. On UNIX
systems RASMOLPATH is typically set to be '/usr/local/lib/rasmol'. Unlike the command 'script ".rasmolrc"', the program will not generate an error message if the file is not found. The system rasmolrc file is commonly used by system managers to display information about the local installation and who to contact for help. Such system rasmolrc files will contain RasMol 'echo' commands detailing a telephone number or e-mail address to be used for contacting somebody for local assistance. Command LineRasMol allows the execution of interactive commands typed at the RasMol prompt in the terminal window. Characters typed into either the terminal or the display window are processed on the command line. Each command must be given on a separate line terminated by a newline or carriage return character. Keywords are case insensitive and may be entered in both lower and upper case letters. All whitespace (space, tab and formfeed) characters are ignored, except to separate the keyword and the arguments of a command. Blank lines (those containing only whitespace) are ignored. There is an internal restriction that command lines are limited to a maximum of 256 characters. Strings may be delimited by matching single or double quotation marks. Placing a hash '#' character anywhere outside quotes terminates the line. RasMol will ignore the rest of the line, which may be used to comment on the command. If a syntax error is detected on entering an interactive command, RasMol indicates the location of the error on the command line by placing the '^' character under the offending word or character, and writing an error message on the following line. If a command is not recognised by RasMol, the program will generate an 'Unrecognised command!' error and redisplay the main prompt. If surplus information is given at the end of a command line, RasMol will execute the recognised command, but issue the warning message 'Warning: Ignoring rest of command!'. Some commands may prompt the user for more information. These commands display a different prompt and are discussed in the command reference. Whenever RasMol outputs diagnostic or error messages to the screen owing to selecting options from the menu or picking objects on the screen, the current command line is cleared. The prompt is redisplayed after any text has been displayed. Command Line EditingRasMol allows basic editing of the command line. Pressing either backspace, delete or ^H (Control-H) will delete the previous character, and the key ^D may be used to delete the character under the cursor. Several characters may be used to move the cursor along the command line. The characters ^B, ^F, ^A and ^E move the cursor back a single character, forward a single character, to the beginning of the line and to the end of the line, respectively. When the cursor is not at the end of the command line, typed characters are inserted into the line and do not overwrite existing characters. After a command line has been edited, a newline or carriage return will enter the entire line, regardless of where the cursor is positioned. Because RasMol is unable to move the cursor up to the previous line, care must be taken when editing commands that wrap over several lines. In the event that another process overwrites or corrupts the command line, the character ^L may be used to redisplay the line on the screen. RasMol maintains a history of recently used commands, so that the user never needs to
type the same commands repeatedly. Typing ^P (Control-P) on the command line will display
the previous command in the history and ^N will display the following command. These
commands may be edited using the features described below. Moving forward or backward
through the command history undoes the modifications made to the current line. The number
of commands retained in the history depends upon their length. RasMol can retain more
short command lines and fewer long ones. Users with the Microsoft Windows version or the X windows version and with 'vt100' or compatible terminals (such as an 'xterm') can use the cursor control characters on the keyboard to abbreviate the control keys. The right and left cursor keys have the same affect as ^F and ^B, moving the cursor forward and back a single character, respectively. Similarly, the up and down cursor keys have the same function as ^P and ^N, producing the previous and next entries in the command history, respectively. Users with the Macintosh version can use the four 'arrow keys' to move up and down through previous command line entries; and back and forth within a single command line statement. Hitting 'return' or 'enter' at any time will result in the execution of the current, e.g. selected or edited, command line contents. Inter-Process Communication (IPC)RasMol supports Inter Process Communication (IPC) in one form or another on all platforms. Under Microsoft Windows, IPC is implemented using Dynamic Data Exchange (DDE), on the MacIntosh IPC is implemented using Apple Events and on X Windows systems IPC is implemented using John Ousterhaut's Tcl/Tk communication protocol. When RasMol starts up on an X window system it registers itself with the X window Server as a Tcl interpreter. From within a Tcl application such as 'wish', you can use the Tcl command 'winfo interps' to determine the currently register interpreters on that display. The first instance of RasMol registers itself as 'rasmol', the second as 'rasmol #2', the third as 'rasmol #3' and so on. The Tcl interpreter can easily send a command to rasmol using the built-in 'send' command. RasMol interprets the string parameter to the send command not as a Tcl function to execute but as a RasMol command. Hence, typing 'send {rasmol} {background red}' into the wish interpreter will cause RasMol's display window to change colour. Using the same encoding as Microsoft's DDE Execute protocol, multiple commands may be sent in a single 'send' by placing the consecutive commands in square brackets. RasMol will execute all of the commands in a 'send' before refreshing the screen. Under Microsoft Windows, RasMol supports a complete DDE protocol. The simplest layers of the protocol may be accessed by sending a DDE Execute command to application 'RasWin' and any topic. This will start a DDE conversation with the most recently launched instance of RasMol. Although any topic name can be used, the use of 'System' and/or 'RemoteControl' are recommended. Once again the contents of the execute package consists of a string for RasMol to execute. If the first non-whitespace character is an open bracket, the string is interpreted to be a sequence of consecutive commands enclosed in square brackets; otherwise the string consists of just a single command. Commands in square brackets may optionally be separated by whitespace and/or semi- colons. RasMol can also act as a 'data server' supporting hot, cold and warm links. Currently supported DDE items include 'Name', 'Image', 'Pick', 'Count' which denotes the Molecule name, the currently displayed image (in Microsoft DIB format), the atom expression of the last picked atom (or an empty string) and the number of selected atoms, respectively. Using a hot or warm link on the 'Pick' item, for example, allows an application such as Microsoft Word, Excel or Visual Basic to respond each time the user clicks on an atom in RasMol. RasMol on the Apple Macintosh supports AppleEvents. Currently the only supported AppleEvents are the four 'core' events, Open Application, Open Document, Print Document and Quit. However, because OpenDocument determines its actions by the file's type signature this can be used to implement generic IPC. Because RasMol for the Macintosh treats all files of type 'RSML' as scripts, the sending application need only place all the commands to be executed in a temporary file, set the type of the file to 'RSML' and then send RasMol an OpenDocument AppleEvent with the file as parameter. Help filesThe RasMol help facility can be accessed by typing "help <topic>" or "help <topic> <subtopic>" from the command line. A complete list of RasMol commands may be displayed by typing "help commands". A single question mark may also be used to abbreviate the keyword "help". Please type "help notices" for important notices. Depending the architechture, separate help systems are also available.
|