@text
Documentation file for MAGE, version 2.5 A "kinemage" (kinetic image) is a scientific illustration presented as an interactive computer display. MAGE is a display program, which presently runs on Macintosh and IBM-PC computers, to view and explore kinemages. An early version of MAGE is described in the Richardson & Richardson article in the first issue of Protein Science (Jan. '92). The kinemage format is defined in that article, and although there are now more keywords and parameters, the basic definitions have been stable. This documentation file contains three sections: a) Brief instructions for using MAGE to look at kinemages; b) Features of MAGE; c) Suggestions for trouble-shooting. * * * * * * * * * * * * * * * * a) Brief INSTRUCTIONS for looking at kinemages on the MAC: Double-click on one of the *.kin files that has a "helix-on-page" icon or on the MAGE application icon (or, in System 7, drag the file icon and drop it on the program icon), and follow instructions as they appear. Read some or all of the scrollable text, click in the rear window to see the graphics, and rotate the image by dragging the mouse. Try the "Animate" button if there is one, select author-set views under the "Views" pulldown menu, and go to a new kinemage under the "Kinemage" pulldown. "Open File" under the "File" pulldown menu lets one open a new kinemage file, and "Quit" lets one exit from MAGE. (If you can't get the program running, please read the "Trouble-shooting" section below!) Brief INSTRUCTIONS for looking at kinemages on the PC: If you are still in DOS, then go to the diskette or appropriate directory and issue the command: "win mage_x_y.exe" ("x.y" is the version number). This will invoke windows and put you in MAGE, where you can select File from the menu. If already in windows, use the file manager to display the kinemage directory, then double-click on mage_x_y.exe. If you "asssociate" files ending in .kin with mage_x_y.exe, then double-clicking on the .kin file will invoke MAGE. If you have a MAGE entry in the Program Manager (a MAGE icon is provided for this) make sure it invokes the lastest version of MAGE. When running PC MAGE, proceed past the first banner window, read some or all of the scrollable text, click in the rear window to see the graphics, and rotate the image by dragging the mouse. Try the "Animate" button if there is one, select author-set views under the "Views" pulldown menu, and go to a new kinemage under the "Kinemage" pulldown. "Open File" under the "File" pulldown menu lets one open a new kinemage file, and "Quit" lets one exit from MAGE. (If you can't get the program running, please read the "Trouble-shooting" section below!) The Demo2_4a.kin file contains example kinemages and a tutorial. A table of contents for the present set of kinemage files will be found in a *.TOC file. As always, old *.kin files are compatible with the new program, but new files will not work well with older programs. Important: OLD VERSIONS OF MAGE SHOULD BE REMOVED COMPLETELY from your system, to avoid possible problems or confusion. (On the PC, you will also need to change the executable "associated" with the .kin extension.) * * * * * * * * * * * * * * * * b) FEATURES of MAGE There are versions of MAGE for both PC-type and Macintosh computers. Although copying, loading, and starting them depends on the operating system (see part a), once inside MAGE the two versions are nearly indistinguishable. The main feature of MAGE is interactive rotations to help visualize objects in 3ĞD. Holding the mouse button down while the cursor arrow is in the graphics window will rotate the kinemage as the mouse is moved. Starting this in the lower 3/4 of the screen gives combined rotations around the horizontal (x) and vertical (y) axes. Starting with the cursor arrow in the top 1/4 of the screen gives rotation in the plane of the screen around the third (z) axis. Another major feature is that the kinemage file which specifies the display list is readable and editable plain ascii text, so authors can iteratively construct and modify kinemages, using their favorite wordprocessor (save it as a plain "text" file!). PREKIN is a utility program to do an initial construction of a kinemage from an atomic coordinate file in Brookhaven Protein Data Bank format. However, MAGE can display anything that can be specified as lines, dots, and labels. Each point, be it atom, label, or dot, can be picked by clicking the mouse button when the arrow cursor is on the point. An identifying string for that point, specified by the author (usually the atom name), is displayed on the screen, and the distance from the previously picked point is shown. The exception is "unpickable points", which are specified by a "U" preceding the point triple. These are used primarily for the ends of shortened H-bonds or for the ends of 3-D crosses used as atom markers; since such positions are not atom locations, it is better that they not be pickable for distance measurements. MAGE displays to the right side of the graphics area a set of labeled check-buttons to select what graphics objects will actually be displayed. These follow a three-tiered hierachical organization, specified by the author with keywords @group, @subgroup, and @vectorlist or @dotlist or @labellist. In addition there are "master" buttons, which can control any number of groups, subgroups, and vectorlists thus providing a way of grouping display-objects that is orthogonal to the group-subgroup-vectorlist heirarchy. An author sets up master buttons by adding the parameter "master= {masterbuttonname}" to the top line of ,e.g., each relevant vectorlist; MAGE makes a master button for each different masterbuttonname. They appear after all the group buttons, and from the reader's point of view, they act just like any other button. If there is more than one group with the parameter "animate" (or "2animate") then an "animate" ("2animate" ) button is created that steps in turn through all such marked buttons (flagged with an *). The "ANIMATE" button should always be tried if it is present. Animations can show conformational changes, build up objects cumulatively in steps, switch among color-schemes, show a sequence of logical steps, or provide a tour where viewpoint as well as object selection is changed between steps (changing viewpoint is specified by adding a parameter "moview= n" to the animation line, which will then use View n). Three buttons standardly appear below the graphics objects buttons: one to toggle on and off markers that show the last two pick-points, one to turn on or off pickcentering, and another to toggle the z-clip function off or on. When the "pickcenter" button is on, the image will be recentered around each new point clicked with the mouse. To avoid unintended jumps, leave pickcenter off except when you are actively using it. (Other buttons appear in that region when other functions are enabled.) Three vertical scrollbars to the right of the button area of the graphics window control the zoom scale factor, the z-slab thickness, and the z-translation. The defaults are such that in most cases all you need do is change the zoom factor. The scrollbars work like others on the Mac or in Windows: either click on the arrows for small changes, or click or hold in the open part of the bar for larger changes, or drag the slider. The value of the parameter is displayed at the top of the scrollbar; moving the slider downward increases the parameter. If the "zclip" button is turned off, then the z-slab is inoperative and the entire depth of the object will be displayed, although depth cuing is still relative to the clipping planes. The graphics window can be expanded to better fill the screen: either click on the expansion symbol at the right end of its top bar (Mac), or else move window to the top left, and then drag out the lower right corner of the window. Pull-down menus from the top menu-bar invoke additional features built into MAGE; some of these can also be invoked by keywords in the display list (kinemage) file. Some menu features result in additional check-buttons, as do certain author specified options in the kinemage file. Some menu choices deal with mechanics, such as the "Show text", "Show caption", and "Show graphics" items under the "Window" menu which can be used to bring front any of these windows if they get lost behind the others. "Next" and "Choose" under the "KINEMAGE" menu let one progress through the individual kinemages of a particular kinemage file. Authors can specify up to nine different orientations of a kinemage (using the keywords @matrix, @zoom, @2matrix, @2center, etc.); these show up as View1, View2, View3, etc. under the "VIEWS" pulldown menu, and a checkmark appears next to the one you last chose. Also, the reader can now specify a view (with the "set reader view" command on the "Other" menu) and return to it at any time during a session by choosing "Reader's view" on the VIEWS menu. These views store the values of zoom, center, slab, etc. as well as orientation. The "save view" function, also on the "Other" menu, puts the current orientation matrix and values of zoom, center, and slab out to a file for authors to incorporate into their kinemages. "Stereo on" from the "Other" pulldown menu, invokes side-by-side stereo. This divides the graphics window in half vertically, with left and right images differing by a 6 degree rotation. Such side-by-side stereo can be used with a suitable viewer, or else just by relaxing your eyes to focus toward infinity, letting the two images drift together until they overlap, and then focusing on the fused image to see 3-D. Each half-screen is clipped at the centerline as well as the edges, so that the stereo can be used with large, or even zoomed, images. The 200-pixel separation between left and right halves varies in absolute distance on different monitors, but in most cases it is reasonably close to correct eye separation. If you wish to experiment, the stereo angle and separation can be altered by invoking "stereo angle" on the "Kludges" submenu. For example, if the depth looks exaggerated to you, then make the stereo angle somewhat smaller. (Switching from wall-eye to cross-eye stereo is much more conveniently done by typing 'c' on the keyboard, which takes the negative of the current stereo angle.) Such changes remain in effect until the program is quit and restarted. "Stereo on" is reset off when a new kinemage is loaded unless @keepstereo is specified in a .kin file, or by typing "s" on the keyboard. The split screen is sometimes used for a side-by-side comparison of two different things, rather than for stereo. This is specified by an author using the keyword @compare and otherwise setting up as for an animation. A reader can also change mode between animation and side-by-side comparison, by enabling or disenabling "compare" on the Kludges submenu (note that stereo and compare are incompatible, so when one is on the other will be grayed out). Rotation will move both objects in the same way, keeping them lined up. Toggles controlled by specific keys on the keyboard make it possible to invoke thinline ("t", for faster rotation on the PC), to turn on stereo ("s"), to change between normal and cross-eye stereo ("c"), or to turn on perspective ("p"). In each case the option will stay in force between kinemages, for an entire MAGE session, but can be turned off at any time by hitting the same key again. Menu item "onewidth", on the "Options" menu, (keyword @onewidth in a kinemage file) over-rides additional depth-cuing by line thickness as well as color saturation for a particular kinemage, and "thinline" (@thinline) makes the lines very thin, which is useful for multiple superimposed structures or to speed up rotation. "Perspective" (@perspective) is useful if the object is regular enough to have recognizable size depth cues or foreshortened straight lines, but the default of non-perspective, orthographic projection seems to be best for molecules. "white bkg", with a different color palette on a white field, is useful for certain kinemages such as 3-D graphs; "B&W monitor" simulates the default mode for black and white monitors, to make black-and-white illustrations by screen capture and printing (screencapture is not yet built into MAGE, but there are many inexpensive utilities available). "Measures", selected under the "Other" menu, is a natural extension of the point-ID and distance functions to include angles and dihedrals, also reported on the "information line" at the bottom of the graphics window. Reported values are the point-ID for the last point picked, the distance between the last two points, the angle defined by the last three points, and the dihedral defined by the last four points. It is possible, therefore, to pick successive points along the polypeptide backbone and see successively the values of phi, psi, and omega dihedral angles. (Note that the dihedral refers to the central bond of the 4 points, so that it seems to lag behind where you are currently picking.) The measure function displays white lines between the points it is currently using, and displays red dots that are the averages of the last two, the last three, and the last four points picked. These points can themselves be picked, so that you can use them to recenter the image, to measure distances, or as the ends of drawn lines (you probably want to turn off the "measures" button before using those points for another purpose). For example, you can add a helix axis to the display by invoking measures and picking 4 Calpha atoms at one end of the helix, turning the measures button off and drawline on (with a "shorten line" value of, say, -2.5 A) and picking the 4-point average dot; then turn the drawline button off and measures back on and repeat the process at the other end of the helix. Such new lines may be written out to a file (see paragraph below) and then pasted into the kinemage file (renamed and recolored) to become a permanent part of it. "Draw new", under the "Other" pulldown menu, brings up a dialog box that lets you enable 4 different tools for adding new lines or labels to the kinemage (and then later writing them out). Buttons for all 4 tools will be added to the panel, but you can choose which one starts out turned on and set various options in the dialog box. When the drawline tool is invoked, MAGE will add a green line to the display between each alternate pair of points picked. They can be erased, one at a time in reverse order, by clicking on "eraselast" in the button panel (this applies to objects drawn by all 4 tools). The "drawlineon" button on the button panel will enable or disenable the drawing of new lines without effecting previous lines (in order to use mouse-clicks for other purposes). The lines can be drawn either shorter or longer than the distance between picked points, according to the value chosen in the dialog box. For hydrogen bonds, it is suggested to shorten them by .7 Angstroms, and to check the "unpickable" box. To lengthen lines (e.g., for a rotation axis or a helix axis), give a negative "shorten line" value. The "construction" tool works like an inverse "measures": you pick 3 points in succession and are then given a dialog box in which to specify the length, angle, and dihedral for a new line to a 4th point. The "dragline tool lets you click and drag from a pre-existing point, moving in the plane of the screen. If the "Labels" button is on, then the pointID of any point clicked on will be displayed on the screen at that point. The total set of drawn lines and/or labels can be written out to a file with the "Write file" option in the drawline dialog box. If "draw new" is turned off from the menu, then all drawn lines or labels will be removed. The "find" function under the "Other" pulldown menu lets you search for particular strings in the pointID's, so for instance you could locate the point whose ID contained both "ca" and "195". "Find" works just like a mouse-click, so depending on what functions are currently enabled, it could put a marker on the point, recenter on it, label it, draw a line to it, etc. For those with non-standard needs or preferences, it is possible to increase the maximum number of atoms allowable (currently 3500), with a choice in the initial copyright-banner dialog box. * * * * * * * * * * * * * * * * c) The following are suggestions for TROUBLE-SHOOTING problems with kinemages: 1) MULTI-TASKING - Although MAGE is very user-friendly, it does not like other programs. Current versions of MAGE may not work if another program is running, including "Inits" or "Applets" that are actively running in the background. Crashes can therefore be caused by incompatibilities with some "Init" files on the Mac or "Applets" on the PC. To check out that possibility for the Mac, try restarting with the shift key held down (to disable all inits) and try MAGE again. 2) COLORS - Is your monitor set to show 256 colors? MAGE works best with 256 colors, no more and no less. On the Mac, if your monitor is set to 16 colors, 16 grays, or 256 grays MAGE will produce a display depth-cued in gray shades, and for any fewer bits it will be limited to pure black and white. Setting to more than 256 colors produces highly flaky behavior, but should give an error message. To change the color settings of your monitor (Mac), pull down the apple at left of menubar and release at "control panel." In the box that comes up, click on the "monitors" icon. Select "colors" rather than "grays," and "256" rather than a smaller or larger number. Put the box away by clicking in the square at its upper left. 3) MAGE VERSIONS - Are you using an up-to-date version of the program? MAGE has changed substantially over the past several years, including correction of errors. Any older versions should be TOTALLY REMOVED from your system, since they can be invoked unintentionally when you double-click on a *.kin file. To tell which version is running, check the date and version number in the window that first comes up when you start MAGE. MAGE should run on any Macintosh with any system version, but will run on a PC only with Windows version 3.1. When you update versions on the PC, remember to "associate" the new application with the *.kin file extension. 4) RUNNING MAGE - If you have any problems, the most reliable way of viewing a *.kin file is to double-click on the MAGE icon (the hand holding out a helix) and then open the file from inside the program. The *.kin files as distributed (with a helix-on-page icon) will launch MAGE and read themselves in if you double-click them, but they may launch another version of MAGE if there is more than one present on your system. If you are sure you have no other program versions, then it is fine to double-click the *.kin files, or to drag and drop them onto the program icon (for Mac System 7). 5) MEMORY - If your computer is having memory problems, first make sure no other applications are running. MAGE needs 950K of application memory to run in color, and about 400K in black-and-white. On a black-and-white Macintosh system with limited memory, select the MAGE icon, choose "Get Info" under the File menu, and change "Memory Current Size" to match available memory. Restarting the computer helps under some circumstances. If you are using Mac System 6, it is worth trying to run under Finder rather than Multi-Finder. 6) ICONS Any *.kin file created by PREKIN is initially a plain text file (icon = blank page on the Mac) that won't launch any application, and if you edit a *.kin file, it will then be "owned" by your word processor (however, remember to save it as a text file, not a formatted word-processor file). However, that is not a problem, since any of these plain text file types can be opened from inside MAGE. [For Mac aficionados, it is possible to produce the helix-on-page icon for a *.kin file by using ResEdit or FileTyper to modify the "resource fork" to say "MAGE".] If the *.kin files on the distribution diskette do not show the helix-on-page icon, then you probably have, or once had, an intermediate version of MAGE on your system. Throw away all old copies of MAGE and rebuild your desktop by holding down both the option and the apple keys while restarting the computer. Double-clicking on the *.txt or *.doc files on a Mac will launch TeachText if it is on your system; alternatively they can be opened from some other word processor or by MAGE. Files longer than 32K show blank-page icons on a Mac and cannot be handled by TeachText or inside MAGE; use a word processor to look at them. 7) MISSING WINDOWS - If you lose the text window behind an expanded graphics window, bring it forward with "Show text" under "Windows" on the menubar. 8) WILD LINES ON DISPLAY - If you have edited a *.kin file and it is now behaving strangely, that is most likely to be either a) because you saved it as a word-processor rather than plain text file (just bring it up again and re-save it); or b) that the point triples are out of register because you either omitted a curly bracket or are missing a delimiter (blank, comma, or carriage return) between a number and a curly bracket or between two numbers. Click on the ends of any strange lines in the display to get their pointID's and/or identify their set by color or by turning things on and off, and then look for problems in that part of the file. Turning on "XYZ point" on the "Kludges" submenu will help identify lines. Wild lines could perhaps be caused by a bad copy of the file.