Provided by: xbs_0-8_amd64 bug

NAME

       xbs - ball and stick molecule modeling

SYNOPSIS

       xbs     [-id] [-h] [-geo gg] [-sc x] [-color]
               [-t title] [-bw] [-st] [-rv] [-autocolor]
               [-hh]

DESCRIPTION

       xbs   uses  X-window  graphics  to produce ball-and-stick plots.  It reads coordinates and
       other data from an input file id.bs (e.g. ch4.bs) and  possibly  different  "frames"  with
       shifted  coordinates  from an auxillary move file Iid.mv (e.g. ch4.mv).  The default files
       are in.bs  and in.mv In the Debian distribution, see the example input files and script in
       /usr/share/doc/xbs/examples.

OPTIONS

       -geo gg
            set window geometry

       -sc x
            set scale factor

       -t title
            set window title

       -color
            use color

       -bw  b/w with smooth grays

       -st  b/w with stippled grays

       -rv  reverse colors

       -autocolor
            chose own colors

       -hh  long help

       -geo gg
            set window geometry

INPUT FORMAT

       In a simple case, a file ch4.bs could look like this:

        atom      C       0.000      0.000      0.000
        atom      H       1.155      1.155      1.155
        atom      H      -1.155     -1.155      1.155
        atom      H       1.155     -1.155     -1.155
        atom      H      -1.155      1.155     -1.155

        spec      C      1.000   0.7
        spec      H      0.700   1.00

        bonds     C     C    0.000    4.000    0.109   1.00
        bonds     C     H    0.000    3.400    0.109   1.00
        bonds     H     H    0.000    2.800    0.109   1.00

       This sets the coordinates in the format
         atom  species  x  y  z

       and how to draw each atomic species, in the format
         spec name radius color

       and how to draw bonds, in the format bonds name1 name2 min-length max-length radius color

       A move file contains additional frames like this:

         frame This is frame number two
       0.000       0.000       0.000     1.155      1.155      1.155 -1.155     -1.155      1.155
       1.155     -1.155     -1.155 -1.155      1.155     -1.155

       After the keyword 'frame' comes an indentifying string, then come the coordinates for  all
       the atoms. Line breaks can appear anywhere between the coordinates.

       Other  input  lines  are also possible, namely the lines which set parameters (see below).
       Example:  'inc  5'  sets the increment for the rotation to 5 degrees.

       In both files, lines starting with * and blank lines are comments.

USAGE

       After starting the program with 'xbs ch4' the plot can be controlled directly by  selected
       keys. For example, to rotate the molecule use the cursor keys and the keys "," and "." The
       last two were chosen because they are below "<" and ">" whch look like  arrows.   To  step
       through  the  frames  to show a "movie", use keys '[' and ']'.  A number of other keys are
       defined to function directly.  More complicated functions are done by pressing 'i' to  get
       an  input  line  and  then typing a command.  Use 'xbs -hh' to get information on keys and
       commands.

       Sizing: Keys '+' and '-' make the plot bigger or smaller.

       Perspective: Key p switches the perspective. Default is off.  For  pseudoperspective,  the
       sphere  sizes  depend  on  the  distance  to  the viewer but the positions on the page are
       unchanged.  For true perspective, the sizes and the positions both change.   The  strength
       of  the  perspective  effect  depends on the distance to the viewer, which is shown in the
       status line. It is changed with keys 'd' and 'D' or  can  be  set  directly  with  command
       'dist'.   (Note:  if  you come too close and put the viewpoint inside an atom, the program
       will try to color the whole universe, which takes very long).

       Lighting: command 'gramp slope middle' greys out the atoms in the back by  an  exponential
       ramp.  Command  'light  x  y  z' shades the atoms somewhat as if light shines along vector
       (x,y,z).  These commands only work in black/white mode. To switch back to normal coloring,
       enter 'gramp' or 'light' without arguments.

       Positioning:  Keypad  keys  8,6,4,2 move the plot about by an increment dpos (which can be
       set by the command 'dpos'). Keypad key '*' saves the current position as  'home'  (or  use
       command  'pos'  to  set  the  home  position  directly). Keypad key 7 moves the plot home.
       Positions are relative to the center of the window.

       Saving: command 'save' writes the data to a file (default Save.bs).  If there are multiple
       frames, a move file is also written.  The 'save' command has some options, see below.

       Printing:  the  command  'print'  writes  output to a postscript file, by default the file
       'Bs.ps'. A print file stays open until it is explicitly closed. In this way several  plots
       can  be  superimposed on the same page, using the keypad cursor keys to shift the subplots
       on the page. The 'print' command has some options, see below.

ONLINE HELP

       Typing 'xbs -h' and 'xbs -hh' gives short respectively long help.

       After starting xbs, key 'h' toggles an overview.  This  is  the  same  information  as  is
       obtained with 'xbs -hh'.

       On  the  input  line,  use  'help  print' or 'print ?' or even 'print -h' to get help on a
       specific command such as (in this case) print.  This help also shows any possible  options
       for the command.

       The space bar toggles extra information about the plot written into the window.

COMMANDS

       1. Color:

        -  A  color  is  specified either as a number between 0 and 1 (gray value), three numbers
       between 0 and 1 (red, green, blue values or RGB),  or  as  a  color  name  from  the  file
       /usr/lib/X11/rgb.txt (or similar).

        - In the input file, the color of each species or bond is set in these three ways.

        -  The  following  xbs  options are related to color: -color   enable colors (default) bw
       uses greys only -st      uses grays only, stippled from a few values -rv      reverse  all
       colors  -auto     choose  own  colors.  You can change these interactively with the update
       command.  For consistency, black is now 0 and white is 1. The -rv  option  switches  this.
       The  only reason for using -bw or -st is that the commands 'light' and 'gramp' do not work
       with colors.

        - The '-auto' option is used to color the atoms in some standard way.  These  colors  are
       set in routine 'set_auto_colors' in file subs.h.  Starting from the species label (ie. Pd3
       or Mg-a) the leading alpha part is extracted and capitalized  (ie.  PD  or  MG)  and  this
       string  is  used  to  select  a  color.  The idea is to put one's favorite colors into the
       routine and then recompile xbs.

        - The command 'color' changes the colors of atoms interactively,  ie.  'color  C*  green'
       changes  the  color  of  all  matching  species.   To show the color of a species, use the
       command without specifying a color (ie. 'color C1' or 'color C-a').

        - When data is saved with the 'save' command, the current colors (as  set  with  'color')
       are  saved  as  a  string.   With  'save -rgb' the RGB values are written instead of color
       names.  If the -rv option is used, the reversed colors are saved as RGB values.

       2. Some commands have options, eg. print, save, update.  For example:

       print -T  print and add some info as title

       print -t 'text .... ' print and put text as title

       update -rv       update but switch on reversing

       update +rv  update but switch off reversing

       update -bw  update but switch to black/white

       save -rgb   save with colors as rgb values

       save -step n  save with only every n'th frame
                        (good to compress a big .mv file).

       Use 'help update' etc on the input line to see the options.

       3. Pattern matching for atom labels: * matches any string, + any char.
            This can be used in the 'color' command and in the 'bonds' lines in  the  input  file
            (which  determine what bonds are drawn).  For example, 'bonds C* H*  ...' selects all
            bonds between
             atoms like C1 and H34 etc. and 'bonds * * ...' selects all pairs.

       4. Other miscellaneous changes:

             - Key 'a' displays the axis directions.

             - Key 'n' shows atom names or numbers. Key 'c' shows the coordinates.

             - To close a postscript print file, use command 'close'.

             - Command 'dup x y z' duplicates all atoms shifted by (x,y,z).

             - Command 'cut x y z a b' cuts to those atoms between a and b
               along the vector (x,y,z).

             - The input line has a history list to retrieve old commands.
               Use the up and down arrows when the input line is active.

             - On some systems, the backspace key does not work to edit the
               input line. Therefore the left-arrow key was defined to have
               the backspace function also.

AUTHOR

       M. Methfessel <methfessel@ihp-ffo.de>

FILES

       /usr/lib/xbs/in.bs        default data file

                                          August 3, 1998                                   XBS(1)