Documentation file for MAGE version 5.4, Feb. 1999 To explore a kinemage, just: *Rotate by dragging. *Identify by clicking. *Buttons: on/off data structures, animate. *Pulldown menus: choose view or new kinemage. Read the text window, for author's suggestions. A "kinemage" (kinetic image) is an authored illustration presented as an interactive computer display. Operations on the displayed kinemage respond immediately: the entire image can be rotated in real time, parts of the display can be turned on or off, points can be identified by picking them, and the change between different forms can be animated. The image can be recentered, zoomed, put in stereo, or the front and back clipped away; distances, angles, and dihedrals can be measured. The kinemage can be edited on-screen: colors changed, multiple viewpoints saved, button names edited, lines pruned away or new ones drawn, etc. A kinemage is prepared and specified by the author(s) of a journal article, lecture, class lesson, or a research "notebook" in order to better communicate ideas that depend on 3-D information. Viewpoint, emphasis, and selection are an integral part of a kinemage just as they are for any successful presentation or study. A distinguishing characteristic of kinemages is the plain text file of commented display lists and accompanying explanations, which serve as the distribution form as well as an easily modified, human-readable, human-editable represention. Kinemages are viewed and explored in an openended way by the reader or lecturer using a simple graphics program, such as the one described here (called MAGE) which presently runs on Macintosh, IBM-type PC, and various UNIX computers. A Java 'Magelet' can show small kinemages interactively on Web sites. A utility called PREKIN helps authors prepare kinemages based on coordinates in Protein Data Bank format. Earlier versions of MAGE are described in the Richardson & Richardson article in the first issue of Protein Science (Jan. 1992) and in TIBS vol. 19, pp.135-8 (1994). Updated program versions of MAGE and associated helper programs, many kinemage examples, and the official kinemage format description (file KinFmt54.txt) are available free from the Web site (or the anonymous FTP site) at HTTP://KINEMAGE.BIOCHEM.DUKE.EDU. This documentation file contains three sections: a) Brief instructions for running MAGE to look at kinemages. b) Features of MAGE. c) Suggestions for trouble-shooting. * * * * * * * * * * * * * * * * a) Getting started on the MAC: Separate compiled versions are available for the power-Mac (PPC) and earlier Macs (68K) as well as a combined executable (FAT) that should operate in a native manner on either type of Macintosh. No program "installation" is needed. Double-click on one of the *.kin files that has a "helix-on-page" icon or on the MAGE application icon (or, drag the file icon and drop it on the program icon). [For information on changing icons, see section c.5 below.] Getting started on the PC: You need Windows NT or Windows95 or later. (There is a frozen older version, MAGE_4_5.exe that runs on Windows 3.1). If you are currently 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 "associate" files ending in .kin with MAGE_x_y.exe, then double-clicking on the .kin file will invoke MAGE. Make sure this uses your lastest version of MAGE. Getting started on UNIX systems: Separate compiled versions are available for SGI, Linux, etc, but all require X-Windows and Motif libraries. Source and sample makefiles are available on the anonymous FTP or Web site at kinemage.biochem.duke.edu. Command line execution from an X-Window: either just type 'mage' (or however you have named the current working version) or 'mage file.kin' (or, do the drag and drop procedures of your system). Once started, if not invoked with a kinemage file, then select "Open New File" from the "File" menu. Once a kinemage is open, read some or all of the scrollable text, click on the graphics window to select and bring it forward, 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 Demo5_4a.kin file contains example kinemages and a tutorial for readers; file Demo5_4b.kin gives examples relevant for authors of kinemages, and Make_kin.txt is a more extensive authoring tutorial. Many example kinemages are also available on our Web site and can be looked at for ideas. Old *.kin files are compatible with new program versions, but new files might 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.) Our Web site not only makes available the latest distribution versions of Mage, but also the previous one or two versions to insure useful continuity if there are difficulties with the latest version. Please email reports of difficulties, requests for help, etc. to mage@kinemage.biochem.duke.edu. Looking at Kinemages over the WEB: There are kinemages on many Web sites, links to which are given at http://kinemage.biochem.duke.edu. You can of course transfer those *.kin files to your own computer and then view them as above. However, if you want Mage to act as a built-in part of your browser, then merely follow the instructions in your Web browser to define Mage as a helper application, with ".kin" as its signal file extension. * * * * * * * * * * * * * * * * b) FEATURES of MAGE There are versions of MAGE for IBM-type PC, Macintosh, and UNIX computers. Although copying, loading, and starting them depends on the operating system (see part a), once inside MAGE they 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 5/6 of the screen gives combined rotations around the horizontal (x) and vertical (y) axes. Starting with the cursor arrow in the top 1/6 of the screen gives rotation in the plane of the screen around the third (z) axis. (Notice that the cursor looks slightly different when you hold down the mouse in those two areas.) Another major feature is that the kinemage file which specifies the display list is in readable and editable plain ascii text, so in addition to the on-screen graphics editing features, authors can iteratively construct and modify kinemages using their favorite word processor (save 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, labels, balls, spheres, and triangles. Each point (whether atom, label, sphere, etc.) 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 in the kinemage file by a "U" preceding the point triple. These are used primarily for the ends of shortened H-bonds. Since such positions are not atom locations, it is better that they not be pickable for distance measurements. If you do need to pick one, however, that can be done by turning on the "superpick" function on the "Edit" menu.] The text window contains the author's explanation of the kinemages in this file; scroll down to read it, or click on any of the windows to bring them forward. At the top of the text window there is usually a title and author and a Table of Contents with a one-line description of what is in each kinemage. If you find a piece of the text set off with *{ }*, then clicking within that region will either take you to a particular kinemage and view in the graphics window, if that was the type of specification, or if it was a question then the click will bring up a dialog box in which to answer the question, including using previously-picked points or distances from the graphics window if appropriate. After answering the questions, you can write out a file with all the questions and answers (under "File"). Since a kinemage is defined and designed to be an authored illustration, matters of presentation divide logically between those that are the author's business (like initial viewpoint and colors) and those that are the province of the reader (like stereo). Although the reader can over-ride author specified conditions (indeed, the reader can more or less completely reauthor the kinemage), the expectation is that the reader will honor the author's intent at least for an initial look. Of course, the very act of looking at an interactive graphics display alters at least the viewpoint. In the extreme, the reader completely re-authors the kinemage - the mode of standard graphics programs, except that the resulting kinemage conveniently retains the result. 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 3-tiered hierachical organization, specified by the author with keywords @group; @subgroup; and @vectorlist, @dotlist, @labellist, @balllist, @spherelist, @trianglelist, @ribbonlist, or @wordlist. In addition there are "master" buttons, which can control any number of groups, subgroups, and lists, thus providing a way of grouping display-objects that is orthogonal to the group-subgroup-list heirarchy. An author sets up master buttons by adding the parameter "master= {masterbuttonname}" to each @vectorlist (or dotlist, subgroup, etc.) line for the objects to be controlled together. The master buttons appear after all the group buttons, and from the reader's point of view they act just like any other button. (When master buttons are used, typically the individual list buttons are supressed by making their groups dominant.) 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 groups (flagged on the button panel with * or %). An "Animate" button should always be tried if it is present; alternatively, type 'a' (or 'b') on the keyboard. 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 line that specifies the animation, which will then use View n. Three buttons standardly appear below the graphics object 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. (Other buttons appear in this region when additional functions are enabled.) 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. There is an "undo pickcenter" under the Views pulldown menu. 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 Window systems: 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, like scrolling toward more text. 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 putative 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 menu bar, or else move the window left and then drag out the lower right corner of the window. Pulldown 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 or by keyboard commands. (See various items under the Help menu.) Some menu features result in additional check-buttons. Some menu choices deal with mechanics, such as the "Show text", "Show caption", and "Show graphics" items under the "Help" 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 many (up to sixty in version 5.4) different orientations of a kinemage (using the keywords @viewid, @zoom, @matrix, @2matrix, @2center, etc.); these show up as View1, View2, View3, etc. under the Views pulldown menu. A checkmark appears next to the one you last chose, and there can be a short label for each view. Also, the reader can 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 "Keep current view..." function, on the Edit menu, sets the current orientation matrix and values of zoom, center, and slab to whichever numbered view is specified, and lets you give it a label (view-ID). "Stereo on" from the Display pulldown menu, invokes side-by-side stereo; alternatively, type 's' on the keyboard. 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 was based on a display width of 400 on early, small, monitors. Although this varied in absolute distance on different monitors, in most cases it is reasonably close to correct eye separation (you may need to sit further back from a large screen). Display size is now adjusted with respect to screen size and you may wish to experiment both with actual display size and with the stereo angle and separation which can be altered by invoking "stereo angle" on the "Display" menu. 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.) 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 before any groups, and putting the parameter "animate" on each of the groups to be compared. A reader can also change mode between animation and side-by-side comparison, by enabling or disenabling "compare" on the Display menu (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. Specific keys on the keyboard make it possible to invoke thinline ("t", for faster rotation, or to distinguish details), to turn on stereo ("s"), to toggle between normal and cross-eye stereo ("c"), or to turn on perspective ("p"). In the stereo case (a pure reader's option) 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 "s" key again. The "l" (el) key switches between colors defined for each point (if they are in the file) and the usual definition of one color for each list. The "e" key turns off or on the "lens" function that shows details only near the last picked center (often used for contact dots or for H atoms). If you forget which key controls what, look it up under "MAGE Key Shortcuts" on the Help pulldown menu. Menu item "Onewidth", on the Display 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 helps for multiple superimposed NMR models. "Perspective" (@perspective) is useful if the object has foreshortened straight lines, but the default of non-perspective, orthographic projection seems to be best for molecules. "White Background", with a different color palette on a white field, is useful for certain kinemages such as 3-D graphs; "Black&White" gives pure black on white, to make B&W illustrations by writing a Postscript file (see below) or with a bitmap screen capture utility. "Measures" (on the Tools menu) is a natural extension of the point-ID and distance functions to include angles and dihedrals, 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 2, 3, 4, 5, and 6 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 below) and then pasted into the kinemage file (renamed and recolored) to become a permanent part of it. The "Find" function (Tools menu) lets you search for particular strings in the point-ID'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. "Change color" is the most frequently used function on the Edit menu. When its button is turned on, a pick brings up a scrollable list of colors for resetting the color of the picked display object. You can see the effect of the new color on screen before accepting it. [Beware of system-specific problems in correctly positioning a partial scrolling menu - check that the selection is the one you wanted before letting go.] "Draw new" (Edit menu) enables a set of different tools for adding new lines or labels to the kinemage (and then later writing them out). Buttons will be added to the panel for these tools, only one of which can be turned on at a time. The "Draw new setup" dialog box may be needed to set some options, such as shortened lines. When the drawline tool is invoked, MAGE will add green lines 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 these tools). The "drawline" 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 "Draw new setup" dialog box. For hydrogen bonds, it is suggested to shorten them by 0.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" tools work like an inverse "measures": for instance, 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. You can copy an existing piece of geometry (say, to add a Cbeta to a Gly), by measuring it and then turning on "Construct4" to reproduce it at the new position. "Construct5" is a similar set of tools that include options such as drawing the shortest perpendicular to two lines. The "dragline" tool lets you click and drag from a pre-existing point, moving in the plane of the screen (for example, to place a label out away from any atom). If the "Labels" button is on, then the point-ID of any point picked will be displayed on the screen at that point. The contents of such a label can later be edited, either with "ShowObjectProperties" (see below) or in the file itself. The total set of drawn lines and/or labels can be written out using the "draw_new parts" choice under "Save special..." of the File pulldown menu. Warning: if "draw new" is turned off from the Edit menu, then all drawn lines or labels will be removed. The Edit menu has several other functions that allow on-screen graphics editing of the kinemage. "Prune" turns on buttons marked 'punch' and 'prune', (which allow you respectively to delete the two vectors attached to a picked point, or to delete all vectors in the same P,L,L,L sequence as the picked point), and also an 'undo p' button which works for about 10 steps back. "Show Object Properties" lets you see and edit almost all characteristics of a display object. The most frequently useful are to edit the button names, delete entire display objects, or set "dominant' parameters that hide buttons for lower subgroups or lists. The contents of a label can be edited by this mechanism (you will usually need to turn off the molecule so that the pick chooses the label rather than an atom). Animation can be set up by editing a "*" (or "%" for 2animate) into the space at the beginning of each of the relevant group names. The Display and Tools Menus include a variety of useful features. For instance, "Graphics Fonts" lets you increase the size of characters for the on-screen labels or information line, which helps the audience read numbers when you measure distances in an interactive lecture. If "XYZ point" is on, the coordinates of each point picked are written at the top of the screen. "Gnomon" displays a 3-D cursor at the current center, with axes along the original coordinate axes. "Count" will say how many drawn items are currently displayed, out of the total in this kinemage. "Flatland" changes mouse-dragging into a 2-D scrolling motion. "Kaleidoscope" is purely for diversion - it turns off the screen-refresh, so that rotation smears the objects and colors across the image. The "Kluges" submenu, under Tools, includes features that are highly specialized, esoteric, and/or in testing. MAGE can rotate around as many as 10 bonds, if a rotatable sidechain (with or without mutation) has been specified in PREKIN (see tutorial file Make_kin.txt for an example of how to do this). The rotations are controlled by an additional panel of scrollbars, with starting and current angle values shown, and the rotated parts can be written out either in kinemage or in PDB format. An "Update remote" facility lets MAGE send a command line (and coordinates) to another program like PREKIN or PROBE, and append returned graphics objects to the current kinemage. The text and caption windows are editable while in MAGE, by setting "Text editable" (Edit menu). (Omit returns, to allow text wrap when windows are resized.) After editing a kinemage to your satisfaction, "Save as" (File menu) will write out the entire file, including both current text, current kinemage, and any other kinemages in the current kinemage input file, and then reopen the newly written kinemage so continuous editing and saving can be done. (If something like an append has been done that changes the current input file, just the current text and kinemage are written and MAGE is not reset to the new file.) Other save functions allow writing out just part of a kinemage (such as one view, or the new objects made with "drawnew"). A 2-D image of the graphics window can be written out as a Postscript-format file with 'write Postscript' under the "File" menu. It produces a generic Postscript file readable by most programs; on the Mac, for instance, it can be read into Adobe Illustrator or sent to a laser printer by the Downloader utility. Save a bitmap image with any screen capture utility - e.g., on a Mac type "shift apple 4" & drag the new cursor: saves "Picture 1" on hard disk; "shift cntrl apple 4" saves to clipboard. * * * * * * * * * * * * * * * * c) The following are suggestions for TROUBLE-SHOOTING problems with kinemages: 1) MAGE VERSIONS - Are you using an up-to-date version of the program? MAGE continues to change substantially, including new features and correction of errors. Older versions should preferably be 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 banner window that first comes up when you start MAGE without an initial file, or select "about MAGE" from the Help menu. When you update versions on the PC, remember to "associate" the new application with the *.kin file extension. UNIX systems have an explicit sequence of search "Paths", the directory with the desired version of mage named in the way you type it must be an entry in your search path. Check your .cshrc (or .login) file in your home directory. The most reliable source of updated program versions is the Web or FTP site maintained by David Richardson at kinemage.biochem.duke.edu. 2) a) Weird COLORS - MAGE works best with 256 colors. 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. If it is set to more than 256 colors, then MAGE will try to change the color setting itself and restore it upon exit. Some X-server-clients in UNIX systems don't get the MAGE palette to the program correctly; no general fix is known. On the "Change Color" pulldown menu: on some systems, the visual position of the color list can be incorrect until the item is selected. If so, watch the label after you select it. 3) MEMORY - If your computer is having memory problems, first make sure no other applications are running. Restarting the computer helps under some circumstances. On a 640x480 monitor MAGE needs 950K of application memory to run in color, and more for larger monitors. These days there are many kinemages that need 6000K and even a few that use over 20000K. For large kinemages, MAGE now reallocates memory dynamically. If it cannot manage to get enough, it will give an error message. The Mac system limits a program to an individual preferred size; to change this, you need to quit MAGE, select the MAGE application, use "Get Info" to increase the minimum and preferred program memory, and try again. If you use the graphics window-expansion button (upper right corner) on a large screen but the window fails to expand, one cause may be insufficient program memory. 4) MULTI-TASKING - Crashes can sometimes 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. 5) ICONS - If you edit a *.kin file, its icon will very likely be that of your word processor program (however, remember to save it as a text file, NOT a formatted word-processor file). The ownership is not a problem, since any of these plain text file types can be opened from inside MAGE, or dragged and dropped. [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 "Creator" field to say "MAGE".] Double-clicking on the *.txt files on a Mac will launch SimpleText if it is present; alternatively most such files can be opened by MAGE. Text files longer than 32K cannot be handled by SimpleText or MAGE; use a word processor to look at them. 6) 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 point-ID'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 Tools menu will help identify lines. Wild lines could perhaps be caused by a bad copy of the file. 7) BALL&STICKs look odd - If the vectors are not truncated correctly at the balls, it means they precede the balls in your kinemage file. Move the balllist to be in the same group but BEFORE the relevant vectorlists. 9) ONLY TEXT in the text window, nothing in graphics window. This might be a file like this one that only has text information, or might be a kinemage file whose text field is too long. If the text is longer than 32600 characters, MAGE will put that limited number of characters into its text window, but then silently neglects the rest of the kinemage.