|
|
XBSA - X windows Ball-and-Stick Program by M. Methfessel Nov. 1995 with
small additions by Jan Labanowski, 1997
This manual is based in large part on the original README file written by
the original author: Michael Methfessel, methfessel@ihp-ffo.de, Institute
for Semiconductor Physics, PO Box 409, D-15204 Frankfurt (Oder), Germany.
Jan Labanowski (jkl@ccl.net) introduced some new commands and written the
HTML version of the manual. If in doubt, look up the original README file
The XBSA program is a derivative of the original XBS program and contains
few extensions which allow animation of a series of frames and option to
query geometry (distances, angles, and coordinates). It displays Ball and
Stick figures of molecules under X-window system. It is fairly portable,
small, and what is more important, it comes with the source code which is
available under GNU Public License. Therefore it is free, and without many
restrictions -- except, you cannot resell it, but you can modify it, and
redistribute it for free. If you do not see a binary for your machine in the
bin directory (or if the binary does not work) try to compile it. The
(instructions (file INSTALL) are provided in the source directory
(./xbsa/src).
File Formats
XBS uses its own format for representing molecules. It is simple and much
more flexible than other formats in use. You have more flexibility to
highlight specific atoms or bonds with different colors by editing the input
file. The utility (written by Jan Labanowski) is provided to convert the
popular XYZ XMol format to the format required by XBS
The XBS may use one or two files with the same base name, but different
extensions, .bs, and .mv respectively. It is called as:
xbsa filename
where filename is a file name without extension. The .bs file always needs
to be present. It contains the following sections:
* atom coordinates,
* atom specifications (symbol, radius, and color for each atom),
* list of different bonds
* optionally list of commands to modify the program action.
Example:
* ch3ohv.OUT -113.54919315
atom C 0.050065 0.665047 0.000000
atom O 0.050065 -0.767876 0.000000
atom H -0.912101 -1.005927 0.000000
atom H 1.090132 0.995415 0.000000
atom H -0.439468 1.081620 0.886605
atom H -0.439468 1.081620 -0.886605
spec C 0.495 0.18 0.31 0.31
spec O 0.405 0.80 0.36 0.36
spec H 0.375 0.97 0.97 1.00
bonds C O 0.150 2.250 0.15 0.50
bonds C H 0.109 1.635 0.11 0.50
bonds O H 0.105 1.575 0.11 0.50
Lines which start with asterisk * are treated as comments and you can also
use empty lines for better readability. While units of length are assumed to
be Angstroms, they actually need not be, if you use other units
consistently. Also, the symbols need not be chemical element symbols, but
all symbols need to be defined in the .bs file.
Lines starting with atom tag have a general format:
atom symbol X Y Z
and provide atom symbol and Cartesian coordinates for each atom in the
molecule.
Lines with spec tag have a format:
spec symbol color
and provide information how atoms with a given symbol should be displayed.
The first number is the radius of a ball for a given atom symbol. The last
portion of the line provides color for this atom. The color can be specified
as a degree of white (0 - white, 1 - black), the triple of numbers
representing RGB (Red, Green, Blue) components of color, or the official X11
windows color name as given in /usr/lib/X11/rgb.txt on your system). So the
entry for oxygen, O, in the above example could have been also as:
spec O 0.405 0.80
which would be a gray oxygen atom, or
spec 0 0.405 IndianRed
which represents the same color as
spec O 0.405 0.80 0.36 0.36
original entry.
The bonds lines have a general format of:
bond symbol1 symbol2 min max radius color
and entries denote:
* symbol1, symbol2 -- the atom symbols which form the bond. Note that by
denoting some atoms with special symbols, you can create special
effects for them even if there are other bonds between these elements
in the molecule,
* min bond length, max bond length -- only bonds whose length is within
this range are displayed,
* radius of a cylinder representing the bond,
* color -- specified in the same manner as for atom specs as described
above.
The XBSA program checks if the file name.bs exists, and if not, program
exits with error. Then it checks if the name.mv (move file) is present. The
name.mv contains additional frames which can be used for animation. Its
format is much simpler than the name.bs. The frames are represented by the
list of Cartesian coordinates in exactly the same order as in the name.bs
file but without any other information. Each frame begins from the line
starting with the word frame followed by optional comment. You can list
several triples of Cartesian coordinates on the same line, or each number on
a separate line. For example, the 2 frames which corresponds to the .bs
example above could be:
frame * ch3ohv.5 step 1
0.0717 0.6629 0.0000
0.0349 -0.7571 0.0000
-0.8753 -1.1941 0.0000
1.0858 1.0819 0.0000
-0.4589 1.0730 0.8671
-0.4589 1.0730 -0.8671
frame * ch3ohv.5 step 2
0.0912 0.6609
0.0000 0.0213 -0.7473 0.0000
-0.8422 -1.3639 0.0000 1.0819 1.1600 0.0000
-0.4765 1.0652 0.8496 -0.4765
1.0652 -0.8496
XBSA command line options
There are several options which can be entered on the command line:
* -hh long help
* -geo WIDTHxHEIGHT+/-XOFF+/-YOFF is analogous to the standard xview
option available in Xwindow system. It provides the size if the window
in pixels (WIDTH and HEIGHT) and offsets (in pixels) of the window on
the screen(XOFF and YOFF). Positive XOFF specifies the distance of the
left edge of the window from the left edge of the display. Negative
XOFF is the distance of right edge of the window from the right edge of
the display. Positive YOFF is the distance of the top edge of the
window from the top edge of the display, and negative YOFF gives
distance from the bottom of the distance to the bottom of the window.
* -sc x scales the initial image by x (you can resize it later) which can
be smaller or larger than 1.0.
* -t title provides the title (displayed on its upper frame) for the
window. If title contains spaces, be sure to embrace it with single or
double quotes.
* -color Use color for display (it is a default).
* -bw Use black and white, and shades of gray to represent color.
* -rv Reverse colors given in the atom/bond type definitions.
* -autocolor Choose own colors (i.e., disregard colors from your input
file and use colors which are automatically assigned by XBSA.
XBSA keyboard commands
There are two modes for entering commands in XBSA:
* Input line mode which allows you to enter longer commands and
parameters. This mode is initiated by a keystroke i on the keyboard.
When you strike i the prompt will appear in the window asking for
input. If you are in the line input mode, you can also retrieve the
previous commands by using keypad cursor keys. The following keyboard
commands implemented:
help topic
provides help on a given topic (if available).
inc n
change the rotation increment to n degrees (default increment is
90 degrees, i.e., orthogonal views).
time n
enter time (in milliseconds) for how long each frame should stay
on the screen during animation (default is 200 ms).
pos x y
move the molecule by x and y pixels at current view (negative
values move left/down, positive right/up). To return to original
position type pos 0 0.
dpos x
set shift increment to x when using keypad 2468 keys.
dist d
set distance from the molecule to the observer (i.e., plane of the
screen). Has effect only when perspective is requested with the p
keystroke.DO NOT MAKE IT TOO SMALL OR YOU WILL NEED TO REBOOT THE
COMPUTER -- YOU HAVE TO BE OUTSIDE THE MOLECULE, OR PROGRAM WILL
TRY TO PAINT ALL UNIVERSE AND WILL CRASH THE XMANAGER!!!
rfac fac
scale all atomic radii by a factor fac (e.g., 0.5 or 1.5).
bfac fac
this scales the diameter of cylinders representing bonds by the
factor suppled (e.g., 0.5 or 1.0).
scale fac
scales the plot, but this time the factor is given in %, i.e.,
scale 50 will make the molecule occupy 50% of the page, and scale
100 will make it occupy the whole page.
gramp slope midpoint
available only in b/w mode, assigns different shades of gray
depending on the distance of the atom from the observer.
light x y z
provides position of light source. The atoms closer to the light
source a lighter, and the ones further from it are darker
step n
every n-th frame will be shown during frame scan with [ and ]
keystrokes or animations with C or A.
dup x y z
duplicates all atoms shifted by increments x, y, and z.
cut x y z a b
planar cat. The atoms which are contained between planes at
position a and b along vector given by x, y, and z are deleted.
frm n
go to frame n.
color pat color
query the color (if color is not given), or change the color by
providing color. For example
color C*
will list the color chosen for carbon atoms, and
color C* blue (or color C* 0 0 1)
will change all carbon atoms to the blue color.
save fname
save current settings in files fname.bs and fname.mv (if more than
one frame). The fname.mv include all the information about
modification made to the molecule interactively.
update fname
read in the fname.bs and fname.mv (if present) replacing the
previous molecule data. The updateaccepts options, e.g.: update
+rv will switch off reversing, update -rv will switch reversing
on, and update -bw will read but the file but switch to a black
and white mode.
print fname
saves the PostScript picture of current view of the molecule in
the file fname.ps. The PostScript picture can be annotated
automatically by XBSA by providing option -T, e.g., print -T
mymol, or you can place your own title for the picture by using
the -t 'my own title' option, e.g.,
print -t 'This is the famous water molecule' h2o
which will place the picture and your text in the h2o.ps file. You
can print several frames to the same file (e.g. different
orientations or an orthogonal view in different color/wireframe
representation (keystroke l), however, after you are done with
printing to a file, you need to close the file with a close
command. When you print to the closed print file again, you will
overwrite its original contents -- be careful.
close
close the print file. When you print to this file again after
closing it, its contents will be overwritten.
* Keystroke mode in which certain active keys perform specific functions
(KP means a key on the keypad).
o i -- activate input line
o h -- show/hide help screen (tip: to read help you may need to
shrink your molecule with - or move it around).
o space -- show/hide information about settings and molecule.
o cursor -- cursor arrows on the keypad rotate molecule out of plane
(up/down, left/right). You can change rotation increment by using
inc d command.
o , . -- rotate molecule in plane.
o + - -- enlarge/shrink your molecule (zoom).
o KP: 8 6 4 2 -- translate molecule up, right, left, down by using
keypad keys in numerical keypad mode.
o KP: 7 -- shift molecule to home position.
o KP: * -- set home position (you can return to it by KP:7).
o r -- redraw the screen.
o n -- toggle atom numbers, symbols, no symbols.
o c -- show/hide XYZ coordinates of atoms
o N -- show/hide bond lengths.
o w -- wire/ball mode.
o g -- gray/bw.
o b -- show/erase bonds.
o l -- bonds as cylinders/lines.
o p -- perspective (off, pseudo, true)
o a -- show/hide axes (100-X, 010-Y, 001-Z)
o s -- line shadows on/off
o x -- pixmap buffer.
o d D -- distance to screen (d -- far, D -- closer)
o ] [ -- step frames forward and backwards.
o A -- animate 1,2,..N,1,2,3...
o C -- animate 1,2,..N,N-1,N-2...
o < > -- animate backwards or forward -- useful with A type
animation.
< -- N,N-1,N-2...2,1,N,N-1...
> -- 1,2,3...N-1,N,1,2,3...
o { } -- to to first/last frame.
o \ | -- mark(\) frame, goto(|) to marked frame.
o U -- update from currently opened input file.
o Q -- quit.
|
