CHARMM c24 graphx.doc

File: Graphx ]-[ Node: Top
Up: (commands.doc) -=- Next:


Graphics is a subparser of charmm, invoked by via the GRAPH command.
All of the miscellaneous commands (miscom.doc), coordinate commands
(corman.doc), and internal coordinate commands (intcor.doc)
are available from the GRAPHX> prompt.  Only the 1st three characters are
used for primary graphics commands, but many of the options require
the 1st four characters.

     The graphics facility has been extended to provide general X11
support, as well as the original Apollo GPR screen display; a
NODISPLAY version can also be built, which will generate all of the
derived files.  The other major enhancement is the production of
PostScript output files, in either color or grayscale; both X11 and
PostScript use the Apollo imaging model.  Additional information on X11
usage tips and compiling for X11 are given at the end of this document.

     Option keywords are indicated by the use of upper case; lower
case terms are variable values, generally real numbers, but decimal
points are not required.  Triplets ( x y z ) are position dependent;
omitted values are assumed to be zero.

     Through this document, note the following;

      * = graphics default option
     ++ = Apollo GPR only
     ** = X11 only

         Items marked  ** developmental ** may have bugs.

* Menu:

* Summary::       Syntax and Command Summary
* Description::   Detailed Command Description with Examples
* Interactive::   Interactive Graphics (Apollo Only)
* Output::        Output Utility
* Addendum::      X11 Usage and Compiling Tips, Other Useful Programs

File: Graphx ]-[ Node: Summary
Up: Top -=- Previous: Top -=- Next: Description

                       GRAPHX COMMAND SUMMARY


GRAPhx  [XXSZ iwidth]** [XYSZ iheight]**  [NODBuff]++

These commands are available within the graphics subcommand parser:

miscellaneous-command-spec         ! see *note miscom:(miscom.doc).
IC        ic-subcommand-spec       ! see *note intcor:(intcor.doc).
COOR      coor-subcommand-spec     ! see *note corman:(corman.doc).

These commands affect what is viewed:

DISplay [ON]* [MAIN]* [COMP] [BOND]* [VECT] [ATOM] [TEXT] [HBONds] -
              [LABEls] [AXES] 

COLor color-name [brightfactor] [COMP] atom-selection
      PURPle TURQuoise    CHARtreuse  DKBLue
          (or an integer from 0 to 15)

LBL  label-type  label-atoms  SIZE label-size COLOr label-color
   label-type  = INIT SEGId RESN RESId TYPE CHEM CHARge WEIGht USER user-label
   label-atoms = FIRSt and/or atom-selection
   label-size  = VSMAll SMALl MEDIum LARGe                   default: SMALL
   label-color = color-name ( see COLOR command above ... )  default: YELLOW
   user-label  = up to 8 characters

LINe iwidth         :: bonds or vectors; pixels
HBStyle  [COLOR color-name]  [WIDTH iwidth]  [DASH idash]  :: HBOND style
RADii [DEFaults] [PARam] atom-scale [bond-scale] atom-sel
AXEs  [XLIM xmin xmax] [YLIM ymin ymax] [ZLIM zmin zmax]
      [DEFAult]  (all limits set to -25, +25 A)
STEreo [ON/OFF] [dist] [angle]
DRAw [atom-selection]
FULl   ++           :: use full screen graphics
INTer  ++           :: interactive mode; E to exit, ? for help
TEXt [text-body]    :: display a title
FONT [ VSMAll | SMALl | MEDIum | LARGe ]  :: text font; default MEDIUM
OFF                 :: disable all graphics and exit (see END, below).

These commands change the view only:

SCAle  factor [MOL/LAB] [REP int]
BOXsize size  [MOL/LAB]
CENter [atom-selection]
POInt  x y z
ROTate rx ry rz  [MOL/LAB] [REP int]
TRAnslate x y z  [MOL/LAB] [REP int]
ZCLip [low] high
ZCUe [ [low] high ]/[AUTO]

These commands do not affect the display:

AUTo [ON*/OFF]      :: redraw after every command
BITmap [file]  ++   :: save screen to a bitmap file
ERAse [ON*/OFF]     :: screen clear prior to next drawing
HELp                :: provides a command listing
PRImary        ++   :: forces primary buffer use
EXEcute pathname    :: execute a program; no arguments are passed
END                 :: exit from command parser only; preserve window

NOTE: the UNIT must be OPENed first...

PLOt  UNIT n [INIT | TERM]                          :: HPGL plot file
PLUto UNIT n                                        :: PLUTO FDAT file
MAKE  UNIT n                                        :: LIGHT .atm file.
PSC   UNIT n [COLOr] [BWREv] [PORTrait] [INIT|TERM] :: PostScript file

File: Graphx ]-[ Node: Description
Up: Top -=- Previous: Summary -=- Next: Interactive



GRAPhx  [XXSZ iwidth]** [XYSZ iheight]**   [NODBuff]++

Invoked from the main CHARMM command parser; if already initialized
(i.e. GRAPHX ... END) the previous graphic states are retained.

The XXSZ and XYSZ options set the X11 window width and height for
the duration of the graphics session; a window resize is NOT passed
back to graphics code at this time.

The NOWIndow option suppresses the X11 window for batch mode or remote
usage; ideal for making PostScript files, etc.

The NODBuff option disables Apollo GPR hardware double-buffering,
and may only be used either the 1st time or after graphics termination
with the OFF subcommand.  The default is whatever the workstation
will allow.  Display updates will be slower, since a software
double-buffer is employed.  Intended for debugging; Apollo only.


DISplay [ON*]  [MAIN*] [COMP] [VECT] [ATOM] [BOND*] [TEXT] [HBONds] -
               [LABEls] [AXES]

Turns the display of various graphic features on or off; the default
is DISPLAY ON MAIN BOND TEXT which will show the connectivity of
the atoms in main coordinate set, using the default CHARMM title.
The options are:

ON/OFF         enable or disable the display of one of the features
MAIN*          the main coordinate set; displayed as default
COMP           the comparison coordinate set; both may be displayed
BOND*          atom connectivity as atom-colored half-bonds; default
ATOM           filled circles using current radius (see RADII)
VECT           display atom terminated vectors
TEXT*          title display
HBONDS         current HBOND list, using double width lines
LABELS         residue names, atom types, user labels ...
AXES           lab frame axes; + end solid, labeled; - end dashed


display atom on          ! enable atom display; MAIN assumed
display text             ! toggles title display
display hbonds off       ! disable H-bond display


COLor color-name [brightfactor] [COMP] atom-selection

Sets the color of individual atoms according to the atom
selection, using one of the color names below:

      PURPle TURQuoise    CHARtreuse  DKBLue

The color applies to the main coordinate set unless COMP is
specified; brightfactor is a relative intensity, 0.0 -- 1.0

Setting all atoms to WHITE, and using the brightfactor gives the
best control over how PostScript grayscale output will look on the
printed page; note that NONE is background, BLACK is the basic carbon
color is really gray, and WHITE will be black in PostScript output.


     All carbons for segment s are colored cyan:

color cyan sele type c* .and. segid s end

     Colored based on weighting array:

color green .1 sele prop 1 .gt. 1.0 end
color green .2 sele prop 1 .gt. 2.0 end


LBL  label-type  label-atoms  SIZE label-size  COLOR label-color
   label-atoms = FIRST* and/or atom-selection
   label-color = color-name ( see COLOR command above; default: YELLOW )
   user-label  = up to 8 characters

The LBL command identifies which atoms are to be labeled, what
atom attributes are to be included in the label, and the relative
size of the labels; the defaults are marked with an asterisk [*].

The INIT option clears all labels, and any other options are ignored.

One or more the following attributes may be included in the label,
by simply including the keyword(s) in the LBL statement:

      SEGId       segment name (from GENErate; A4)
      RESN        residue name (from the RTF; A4)
      RESId       residue ID, a numeral (A4)
      TYPE        atom type, e.g. N, CA, CB ...  (A4)
      CHEM        atom parameter type code (A4)
      CHARge      atomic charge (G12.4)
      WEIGht      value stored in the weight vector (G12.4)
      USER        arbitrary user-specified text (A8)

The label length (24 bytes) is such that all attributes may NOT be
displayed simulaneously; in particular, CHARge and WEIGht may not be
displayed at the same time for the same atom.

SIZE is specified by one the keywords VSMALL, SMALL, MEDIUM, LARGE,
with a default of SMALL.  The COLOR keyword allows setting the label
color, using the same color names as the COLor command; the default
label color is yellow.  Each use of the LBL command can create a group
of labels of a different size and color, for atoms which don't overlap
with any previous label atom selections.

The blank delimited word following the keyword USER, up to 8 characters, allows
the use of any text string as a label for the selected atoms.

The default is to label the first atom of each residue; an atom
selection overrides this, unless the FIRSt keyword is present;
in this case, the first atom of each selected residue is labeled.


! the first atom of each residue is labeled by name with normal text

! the first atom of each residue in the segment MAIN is labeled
! by name and number with very small text

! all oxygen atoms are labeled by charge with small text

! all alpha-carbons are labeled by the weight vector with medium text

! enter a null label; may be used to selectively "blank" labels
! in this case, all alpha-carbon labels are set to a string of blanks
! for display efficiency, LBL INIT is preferable

! show the location of formal charges on amino acid side chains


LINe iwidth  (bonds or vectors; pixels)

Set the line width for bonds & vectors, in pixels (integer).


line 2


HBStyle  [COLOR color-name]  [WIDTH iwidth]  [DASH idash] 

Set the style for representing HBONDS; color-name is as for the
COLOR command, and iwidth and idash are integers in pixel units.
Specifying HBSTYLE alone resets to the default style, which is
equivalent to


If at least one option (COLOR, WIDTH, or DASH) is specified, the
remaining options are unchanged; thus HBSTYLE COLOR WHITE will
not reset the WIDTH to 4 pixels, but leave it as it was.


RADii [DEFaults] [PARam] scale [bond] atom-sel

Sets the radius for displaying atoms, and for output files produced
by the PLOT, PSC, XMOLE, and MAKE commands.  The options are:

     scale          required if no other options are specified, and
                    assumed to be 1.0 if omitted; performs a relative
                    scale if used by itself, or scales the radii set
                    by the DEFAULT or PARAM options

     DEFAULTS       set radii to a convenient size for display, based
                    on atom type ( C, N, O, ... )

     PARAM          use VDW radii

     bond           value for bond radii for LIGHT program (see MAKE)

     atom-sel       atom selection to apply the radii command to


rad 0.8                       ! reduces radii to 80% of current value
radii param .5                ! set radii to 50% of VDW
radii param .5  .15           ! bond radii to 0.15 A
rad 1.5 sele type H* end      ! enlarge all H atoms by 50%



Restore the default color assignments, based on element type.




AXEs  [XLIM xmin xmax] [YLIM ymin ymax] [ZLIM zmin zmax]

Changes the length of the displayed axes; the default, which is
restored via the DEFAult keyword, is -25 to +25 A for each dimension.
Only the axes lines specified are changed, e.g. AXES ZLIM -5 5 only
changes the endpoints of the Z axes line.


STEreo [ON/OFF] [dist] [angle]

Invoke side-by-side stereo mode for screen display and for output
files produced by the PLOT and MAKE commands, when the ON keyword
is used, or when stereo is off.  The  dist  option controls the
separation between the two images; the  angle  option specifies
the parallax angle for left and right eye views.  The OFF keyword
is used to return to mono mode, and is assumed if the command is
used while in stereo mode.  The default angle is 7 degrees, but the
dist parameter defaults to an interval derived from the window width;
wider windows are best for stereo.


stereo on 16.0 7 


DRAw [atom-selection]

Forces a redraw when AUTO mode is off; also used to to change which
set of atoms is currently being displayed.  All display modes and
output files from PLOT, PSC, PLUTO, XMOLE, and MAKE commands use this
atom selection.  The initial selection is all atoms and may be restored via:

draw sele all end


FULL      ++ (Apollo only)

Use full screen graphics, without an input window; most useful for
photography, when the display is controlled from another workstation.
The X equivalent would be  GRAPH XXSZ 1280 XYSZ 1024 on most displays.


TEXT [ text-body | "text-body" ]

Supply the text for the title display; quotes override the conversion
to all upper case, and a null entry clears the current title.  The
quotes are removed, and are not displayed as part of the title; the
current CHARMM title is the default graphics title.


FONt [ VSMAll | SMALl | MEdium | LArge ]

Change the title font to one of four sizes; the initial setting
is MEDIUM, as is the default if no size is specified.



Disable all graphics and exit the graphics subcommand parser; see
also the END command.



Restores view settings to the program defaults ( scale, translation
and rotations).


SCAle  factor [MOL/LAB] [REP int]

Change the Angstrom/pixel scale factor; initially, 1 A = 32 pixels.
The repeat factor can provide an ersatz zoom effect.  The default is
the LAB frame (i.e. scale is done relative to screen center rather
then the system center).


BOXsize size  [MOL/LAB]

Set the viewing 'box' to (size)x(size), in Angstroms.


CENter [atom-selection]

Move the selected atoms to the center of display space.



Scales the molecule to fit in the display window.


POInt  x y z

The point specified by  x y z  becomes the center of display space.


ROTate rx ry rz  [MOL/LAB] [REP int]

Apply a rotation to the viewing transform; does not affect the
coordinates.  The default is the LAB frame (i.e. a Z rotation
always spins the screen).  If the MOL (molecule) frame is used,
then the rotation will be about the origin of the molecular coordinate
system (i.e. does not depend on the current view matrix).
(NOTE1: the ROTate command uses a left handed system, multiply rotation
angles by -1 as necessary).
(NOTE2: if more than one rotation angle is given as nonzero, then the
rotations will occur sequentially, first x, then y, and then z).


rot 0 90       ! rotate by 90 deg around the y axis
rotate 180     ! rotate by 180 deg around the x axis
rot 90 0 90    ! rotate by 90 deg around x, then 90 deg around z


TRAnslate x y z  [MOL/LAB] [REP int]

Apply a translation to the viewing transform; does not affect the


tran 2 9.5     ! translate +2 A along x axis, +9.5 along y axis
tra 0 0 4      ! translate +4 axis along the z axis


ZCLip [low] high

Set hither and yon clip limits; atoms outside the limits are not
displayed, whether selected or not.


zclip 10       ! atoms outside z = ( -10 .. +10 ) are not displayed
zclip -5 10


ZCUe [[low] high ]/[AUTO]

Controls the z coordinate range over which depth cueing will be
applied.  AUTO use the displayed atom coordinates to set the limits.


zcue 10        ! zcue from -10 to +10
zcue -4 8
zcue auto



Enables or disables automatic redraw after every command; the
initial setting is ON, and the command functions as a toggle.
AUTO OFF is useful for making multiple changes without the
time required for a redraw.



Enables or disables a screen clear prior to the next drawing; the
initial setting is ON, and the command functions as a toggle.
ERASE OFF is useful for overlaying trajectory frames or other
related collections of structures.  Possibly best used with AUTO OFF,
and using DRAW for each structure.  Also applies to PLOT and PSC
commands; the file is not closed until one of the following:

  (1) PSC/PLOT command with TERMinate keyword; only correct method
  (2) the UNIT is CLOSEd; no title or page eject, etc.
  (3) the program terminates; no title or page eject, etc.

Usage example which creates an overlay of 50 consecutive trajectory frames
(coord traj open on unit 20; .ps file open on unit 12):

erase off
psc unit 12 init
set n 1
label frmlp
coor read file unit 20 ifile -1
psc unit 12
let n += 1
if n .lt. 50 goto frmlp
psc unit 12 term



List the available commands and syntax.


PRImary         ++ (Apollo only)

Forces use of the primary graphics buffer on hardware double-buffer
displays; needed to avoid blank images when using  /com/cpscr  to save
screen images for printing, e.g. with the Tektronix 4693DX color printer.
The Apollo screen dump  /com/cpscr  only saves bit planes 0-7 to the
bitmap file.


EXEcute pathname

Execute a program w/o arguments.


exe /com/ld         ! list the current directory  (aegis)
exe /bin/ls         ! list the current directory  (unix)

Equivalent to the SYSTem command (miscom.doc)



Exit from command parser only; allows other CHARMM commands to be
performed w/o losing the current display.  Re-invoking graphics
does not re-initialize the graphics settings.  Useful for trajectory
movies using MERGE DRAW, e.g.

open unit 12 read file name dyn.trj.10
merge draw firstu 12 nunit 1

Overlays can be created (on screen only) by preceding the END command in
the above example with ERAse OFF.

File: Graphx ]-[ Node: Interactive
Up: Top -=- Previous: Description -=- Next: Output

                    Inteactive Graphics Mode

INTer   ++ (Apollo only; X11 equivalent may be developed)

Enter full screen interactive mode, which allows the keyboard to be
used to manipulate the structure; also allows DN10000 stereo mode.
Keystrokes are case-sensitive, e.g.  key [SHIFT]-[E] to exit.

E                exit interactive mode
CTRL-A           toggle AUTO mode
a/A              atom display ON/OFF
b                save bitmap to file screen.img
c/C              center / MASS weighted center
d                forced redraw (AUTO off)
h/H              H-bond display ON/OFF
lN               line width N; N=[1-9]  (2 keys)
m                maximum window
CTRL-R           graphics state reset
rNN              set rot inc  in deg    (3 keys)
tN               set tran inc in A,0=10 (2 keys)
vN               set radii to .N*VDW    (2 keys)
z                auto zcue over mol coord
CTRL-Z           zcue off
[<--][-->]       X translation
[^][v]           Y translation
NEXT WNDW        +Z translation, SHIFT for -Z
<-- -->          X axis rotation
^ v              Y axis rotation
SHIFT ^ v        Z axis rotation
s                toggle side-by-side stereo
S                toggle hardware stereo (DN10000)
F1,F1S           scale by  1.05 / 0.95
F2,F2S           scale by  1.25 / 0.80
F3,F3S           scale by  2.00 / 0.50
HELP or ?        display help screen

N.B.  <--, -->, ^, v  indicate cursor arrow keys

      ** developmental **

File: Graphx ]-[ Node: Output
Up: Top -=- Previous: Interactive -=- Next: Addendum

                      Screen Output Facility


Writes out an HPGL plot file using the current atom selection and
view transform.  The UNIT must be OPENed first ( recommended file
extension  .hp ).  Use of more than 6 colors is not recommended;
the color translation is:

plotter    screen
 pen 1     black (light gray)    gray
 pen 2     red
 pen 3     green                 chartreuse
 pen 4     blue                  dkblue         turquoise
 pen 5     magenta               purple
 pen 6     yellow                orange
 pen 7     cyan                  brown
 pen 8     white

Atom display on the plotter is also fairly primitive (filled circles)
and is not intended for space-filling radii, but for a simplistic ball
and stick type drawing with small atom radii. 

The INIT keyword forces device initialization in ERASE OFF mode, and
should only be used in that context; it is not normally required.  In the
same way, TERM is used only to terminate a PLOT file in ERASE OFF mode;
only the title text and end-of-file data is written to the file, so all
structures should already be drawn.  See the ERASE command for a PSC
example demonstrating the use of ERASE OFF with INIT and TERM keywords.


PSC UNIT n [COLOr] [PORTrait] [BWREverse] [INIT | TERM]

Writes out a PostScript display file using the current viewing transform
and selected atoms; the default is grayscale in landscape mode, and may
be changed using the COLOr and/or PORTrait keywords.  Colors are direct
translations of the RGB color map used for Apollo and X11 displays, or
arbitrary conversions to grayscale.  Direct control over grayscale may be
achieved by setting all atoms to COLOR WHITE, and using the 'brightfactor'
option of the COLOR command to set the various gray levels; note that full
WHITE is black, since the background (paper) is white in grayscale mode.
The default background is black in COLOR mode, but may changed to white
with BWREverse keyword; atoms or text colored white on the screen will be
printed in black.  As always, the UNIT must be opened first (recommended
file extension .ps).

The INIT keyword forces device initialization in ERASE OFF mode, and should
only be used in that context; it is not normally required.  Likewise, the
TERM keyword writes the final part of the PostScript file in ERASE OFF mode,
and does not draw the structure; only the graphics title and the final few
PostScript commands are written to the file.  See the ERAse command for
additional details and a usage example.



Writes out atom coordinates and connectivity based on the current atom
selection and view transform, in CSD FDAT format.  WARNING: 999 atom limit!

Stereo mode settings are ignored, as are radii and color.  Also, atoms
should be renamed to their element types to get proper radii, etc within
pluto (e.g. CA is not carbon alpha, it's calcium).  As with PLOT, the
UNIT must be opened first ( recommended file extension  .fdat ).


rename atom C1 sele type C  end
rename atom C2 sele type CA end
rename atom N1 sele type N  end
rename atom O1 sele type O  end
rename atom H1 sele type H1 end
   ! etc., etc., etc.
scale .5
rot 0 90
open unit 50 write card name molecule.fdat
pluto unit 50



Writes atom coordinates, radii, and color to a file formatted for
the LIGHT program (available from the N.I.H.) which produces nice
ray-traced images using current stereo settings and view transform.

A 1280x1024 window is the optimum size for best scaling and centering
of the image produced by LIGHT.

The UNIT must be opened first; the LIGHT program requires that an
extension of .atm be use for the file name.


File: Graphx ]-[ Node: Addendum
Up: Top -=- Previous: Output -=- Next: Top

                          X11 Usage Tips

On some workstations, the graphics display colors will only be
correct when that window has "focus".

The recommended "focus" policy is pointer-has-focus, i.e. the active
window is whichever one the mouse pointer is in; this permits typing
graphics commands in a mostly obscured terminal window (xterm, winterm,
hpterm, aixterm, etc.).  The alternative is to "lower" the text command
window via the window manager.  Automatic "topping" of the window with
focus is not recommended.

Although the graphics display window can be resized, the size change is
not currently passed back to the drawing routines.

                       X11 Compiling Problems

     The default assumptions are:

(1) required include files (Xlib.h, Xutil.h) reside in /usr/include/X11

(2) the library libX11.a resides in /usr/lib

These files *must* exist for the X11 graphics to be compiled, and of
course the keyword XDISPLAY must be in the pref.dat file.  If the files
are NOT in the standard places (such as under HP-UX), the compile option
-I may be needed to point to the directory with the include files, and
the corresponding -L option may be needed to point to the directory which
contains libX11.a for the final link step.

                   Other Useful Programs (all "freeware")

(1) ghostscript -- besides allowing on screen preview of PostScript files
prior to printing, this useful utility can convert the .ps files output by
the PSC command to other formats (e.g. GIF, PBM) and can also be used to make
an "encapsulated" PostScript (EPS) file.  Available via FTP from almost any
software archive that distributes GNU software (Free Software Foundation).

(2) xfig -- this X11-based technical drawing package can read EPS files, and
provides an ideal way to do "pasteup" of PostScript files from diverse sources
into a composite figure.  Available via FTP from sites carrying X11 software;
hardware specific sites may have versions pre-configured for SGI, HP, etc.

(3) pbmplus, netpbm -- this suite of bitmap manipulation programs offers the
best looking conversion to GIF files, using a PBM file from ghostscript as an
intermediate file type.  The names pbmplus and netpbm indicate minor variants
of the same suite, with netpbm being more recent, according to UseNet lore.
Available at the MIT X11 site, and similar FTP sites.

(4) light -- a ray-tracing program written by BR Brooks at NIH, which uses
the file format ouput by the graphics MAK command; used to produce movies
and slick-looking single images for presentations.  Contact the author.

(5) gnuplot -- 2D and 3D graphics, with X11 and PostScript support (and about
50 other output devices as well); useful for time series plots, etc., which
can be combined with molecular graphics via xfig (see above).  Available at
most GNU sites.

(6) ImageMagick -- a powerful suite of image manipulation programs, including
animation capabilities; available at

(7) MPEG -- mpegencode and mpegplay produce and replay animations; multiple
images in PBM format can be combined into a movie

CHARMM .doc Homepage

Information and HTML Formatting Courtesy of:

NIH/DCRT/Laboratory for Structural Biology
FDA/CBER/OVRR Biophysics Laboratory