GRAPHICS 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
GRAPHX COMMAND SUMMARY Initializing: GRAPhx [XXSZ iwidth]** [XYSZ iheight]** [NODBuff]++ [NOWIndow]** 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] - [OFF] [LABEls] [AXES] COLor color-name [brightfactor] [COMP] atom-selection NONE RED BLACk YELLow GREEn WHITe BLUE CYAN MAGEnta GRAY ORANge BROWn 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 DEFault-colors 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: RESet SCAle factor [MOL/LAB] [REP int] BOXsize size [MOL/LAB] CENter [atom-selection] MAXwindow 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
DETAILED COMMAND DESCRIPTION ------------------------------------------------------------------- GRAPhx [XXSZ iwidth]** [XYSZ iheight]** [NODBuff]++ [NOWIndow]** 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] - [OFF] [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 Examples: 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: NONE RED BLACk YELLow GREEn WHITe BLUE CYAN MAGEnta GRAY ORANge BROWn 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. Examples: 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-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 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. Examples: ! the first atom of each residue is labeled by name with normal text LBL RESN COLOR CYAN ! the first atom of each residue in the segment MAIN is labeled ! by name and number with very small text LBL RESN RESID FIRST SELE SEGID MAIN END SIZE VSMALL ! all oxygen atoms are labeled by charge with small text LBL CHARGE SELE TYPE O* END COLOR CHAR ! all alpha-carbons are labeled by the weight vector with medium text LBL WEIGHT SELE TYPE CA END SIZE MEDIUM ! 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 LBL SELE TYPE CA END USER ! show the location of formal charges on amino acid side chains LBL USER - SELE RESN ASP .AND. TYPE CG END SIZE LARGE COLOR GREEN LBL USER - SELE RESN GLU .AND. TYPE CD END SIZE LARGE COLOR GREEN LBL USER + SELE RESN ARG .AND. TYPE CZ END SIZE LARGE COLOR GREEN LBL USER + SELE RESN LYS .AND. TYPE NZ END SIZE LARGE COLOR GREEN ------------------------------------------------------------------- LINe iwidth (bonds or vectors; pixels) Set the line width for bonds & vectors, in pixels (integer). Example: 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 HBSTYLE COLOR ORANGE WIDTH 4 DASH 4 (N.B. DASH 0 = solid line) 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 Examples: 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% ------------------------------------------------------------------- DEFault-colors Restore the default color assignments, based on element type. Example: default ------------------------------------------------------------------- AXEs [XLIM xmin xmax] [YLIM ymin ymax] [ZLIM zmin zmax] [DEFAult] 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. Example: 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. ------------------------------------------------------------------- OFF Disable all graphics and exit the graphics subcommand parser; see also the END command. ------------------------------------------------------------------- RESet 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. ------------------------------------------------------------------- MAXwindow 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). Examples: 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 coordinates. Examples: 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. Examples: 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. Examples: zcue 10 ! zcue from -10 to +10 zcue -4 8 zcue auto ------------------------------------------------------------------- AUTo [ON/OFF] 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. ------------------------------------------------------------------- ERAse [ON/OFF] 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 ------------------------------------------------------------------- HELp 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. Example: exe /com/ld ! list the current directory (aegis) exe /bin/ls ! list the current directory (unix) Equivalent to the SYSTem command (miscom.doc) ------------------------------------------------------------------- END 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. end open unit 12 read file name dyn.trj.10 merge draw firstu 12 nunit 1 graphics Overlays can be created (on screen only) by preceding the END command in the above example with ERAse OFF.
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. INTERACTIVE KEYSTOKE SUMMARY ================================================= 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 **
Screen Output Facility PLOt UNIT n [INIT | TERM] 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. ------------------------------------------------------------------- PLUto UNIT n 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 ). Example: 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. graphics scale .5 rot 0 90 open unit 50 write card name molecule.fdat pluto unit 50 ------------------------------------------------------------------- MAKE UNIT n 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. -------------------------------------------------------------------
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 ftp.x.org (7) MPEG -- mpegencode and mpegplay produce and replay animations; multiple images in PBM format can be combined into a movie
NIH/NHLBI/LBC Computational Biophysics Section
FDA/CBER/OVRR Biophysics Laboratory