|
XBSA Manual
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).
- i -- activate input line
- h -- show/hide help screen (tip: to read help you may
need to shrink your molecule with - or
move it around).
- space -- show/hide information about settings and molecule.
- 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.
- , . -- rotate molecule in plane.
- + - -- enlarge/shrink your molecule (zoom).
- KP: 8 6 4 2 -- translate molecule up, right,
left, down by using keypad keys in numerical keypad mode.
- KP: 7 -- shift molecule to home position.
- KP: * -- set home position (you can return to it by KP:7).
- r -- redraw the screen.
- n -- toggle atom numbers, symbols, no symbols.
- c -- show/hide XYZ coordinates of atoms
- N -- show/hide bond lengths.
- w -- wire/ball mode.
- g -- gray/bw.
- b -- show/erase bonds.
- l -- bonds as cylinders/lines.
- p -- perspective (off, pseudo, true)
- a -- show/hide axes (100-X, 010-Y, 001-Z)
- s -- line shadows on/off
- x -- pixmap buffer.
- d D -- distance to screen (d -- far, D -- closer)
- ] [ -- step frames forward and backwards.
- A -- animate 1,2,..N,1,2,3...
- C -- animate 1,2,..N,N-1,N-2...
- < > -- 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...
- { } -- to to first/last frame.
- \ | -- mark(\) frame, goto(|) to marked frame.
- U -- update from currently opened input file.
- Q -- quit.
|