KINFMT.TXT - Kinemage format LIST OF KEYWORDS, etc. for MAGE_5.4 and above: (best read in Courier or other non-proportional font, with page wide enough for 75-character lines) This is an edited version meant for student kinemage authors. For a more complete description of current and obsolete kinemage formats see KINFMT54.TXT on the official kinemage website (http://kinemage.biochem.duke.edu). ('i' stands for an integer, 'f' for a floating-point number) Official definition of keywords are in lower case; however, the Mage parser converts potential keywords, so that upper case should work. All Mage keywords are defined to start with \n@: i.e. @ is the first character of a new line. This will avoid problems with email addresses where @ is used but never as the first char of a line. However, early Mage versions were permissive about this, so there may be trouble with early kinemages. TEXT Parser (MAGEFILE.c)------------ @text Whatever follows is put in TEXT WINDOW, until @kinemage or EOF. Valid only when MAGE first opens a kin file. No other @keywords recognized until an @kinemage is encountered, except @mage f where f is the mage version. This keyword will be recognized even if it comes before @text when mage first opens a kin file. Within text region: *{ }* Delineates "go to" setups: when reader clicks inside, MAGE goes to kinemage & view specified and turns on or off master buttons as specified. e.g. *{Kinemage 6, View 2, with master= {side ch} on}* short form: *{Kin 6, v 2, m= {side ch} on}* *{Q: }* Delineates "Questions": when reader clicks inside, question dialog box comes up. Note: MAGE adds question number and a line where answer will appear. e.g. *{Q: What is your name?}* @mage f MAGEVERSION for version control comments @kinemage i Starts a new kinemage; numbers should be positive, unique, and increase monotonically. KINEMAGE Parser (MAGEINPT.c) ------------ Mage filters the input character stream: passes only tab,LF,CR control characters, all ascii charaters above 32 and less than 127. This should allow a kinemage to be interpretable no matter how saved by a word processor program, but it is a lot better to save kinemages as plain text. @kinemage i Ends current and starts a new kinemage; numbers should be positive, unique, and increase monotonically. @mage f MAGEVERSION for version control comments, can go anywhere. @caption What follows goes in CAPTION WINDOW, until next valid keyword. -------------- Input controls determine what is in the GRAPHICS WINDOW and adjust the appropriate items in the menus and button panel: @onewidth Makes all lines 2 pixels wide (if omitted, width depends on z). @thinline Makes all lines 1 pixel wide (good for superpositions). Default is multiwidth depth cueing from 1 in back to 5 closest to viewer. @perspective Replaces normal orthographic projection. Kinemage style guide: do NOT use for molecules, use with geometric objects where the eye expects perspective. @whitebkg White background, not black (uses alternate color palette) @whiteback: synonym @compare Makes side-by-side comparison of animate groups. @flat Makes mouse-drag control 2D scrolling instead of 3D rotation ------------ Maximum number of views = 60 in Mage 5.4, specified with the following information: @viewid {string} String identifying startup view (max characters = 15) (appears on VIEWS menu) @1viewid {}: synonym @2viewid {string} String identifying View2 (appears on VIEWS menu) . . . . @60viewid {string} [Zoom and span are exclusive alternative ways of setting magnification. On input, Mage calculates scale so that zoom of 1.0 nearly fills window with entire object. Span is good for precalculated closeup views, with a scale independent of overall object size.] @zoom f Scaling bias for startup view (default 1.0 nearly fills window) @1zoom f: synonym @2zoom f Scaling bias for View2 . . . . @60zoom f @span f adjusts Scaling so that startup view is f units across window. @2span f adjusts Scaling for View2 . . . . adjustment is to lessor of window height or width. @60span f @zslab i Zslab (depth of window in and out of screen) in startup view @1zslab 1: synonym @2zslab i Zslab for View2 . . . . @60zslab i ------------ @master {} Master declaration: lets author specify order of master buttons no matter what order they are actually first used. Otherwise, order is that of first use. Cosmetic - not necessary, but convenient for standard layouts like presentation of contact dot calculations. @lens f Sets radius of sphere of enhanced detail at center of image. Corresponding lists with parameter "lens" then pass their items for display only when within that sphere. This state is always in effect with a default radius (7.0 in Mage 5.4) for lists with the "lens" parameter. Readers can toggle this behavior with keyboard "e". --------------- -----Graphics: Hierarchical Display Objects---------------------------- A redraw of the graphics does a pass through the hierarchy, displaying only those objects flagged as "on" (== checked button box). @group { } [param...] High-level display object. Group parameters must be on same line as keyword. Button name in {}, up to 14 char., (max = indicator + 14), indicator space before name is blank or has animate indicator "*" or 2animate indicator "%". Its "button" has on/off indicating check mark box. @subgroup { } [param...] Mid-level display object. $-> ("@set": obsolete synonym) Subgroup parameters must be on same line as keyword. Button name in {}, up to approx. 10 char. (max = 15 but limited by width of button panel). Its "button" (_indented) has on/off indicating check mark box. @xxxlist { } [param...] List of low-level display objects. xxx == vector,label,dot,ball,sphere,triangle,ribbon,word List parameters must be on same line as keyword. Button name in {}, up to approx. 9 char. (max = 15 but limited by width of button panel). Its "button" (_ _indented) has on/off indicating check mark box. Items in the list are on following lines. [Internally, points can be a type that overrides their list type, which is used by MAGE (in the "New Group" of reader-drawn objects) but is not at present specifiable in the kinemage file itself. In actual usage, the points in vector, triangle, & ribbon lists group into P,L,L sets like poly-lines, triangles, etc. Note that pruning actually works on poly-lines, so can wipe out a whole Calpha list!] ------------ Attributes of individual items in a list: {pointID}, P, < >, etc. precede the x,y,z triple to which they belong: [attributes] x, y, z They can be either lower or upper case. Attributes not relevant to type of list are ignored. Each field within a list item must be ended: A number (x, y, or z) can be ended by a space, comma, or newline A '}' or '>' ends its field, for a PointID or comment One-character attributes (eg 'U') need white space to end them except 'P' is a special case, {pointID} Shown on info line when point picked Up to 255 char, stored efficiently in offset, indexed array. P (Point) begins new line segment (required if inside vectorlist, presumed at beginning of list), L (Line) means vector drawn from previous point (L is the default, so not required) M moveto == P synonym D drawto == L synonym U Unpickable, used on shortened or extended lines where distance measurements would be confusing (can be overridden with 'superpick' on Edit menu) B Forces line shortening by radius given as this vectorlist param; alternate way of shortening vectors for an accompanying balllist. < > Anything between < > is stored as comment attribute of the point. <> comment should precede its point triple, for correct writeout. Up to 255 char, stored efficiently in offset, indexed array. $ ' ' Anything between single quotes is ignored. Historical relic of shared MAGE and CHAOS files, unfortunately embedded in some distributed kinemage labellists. All colors are their own attribute names, for point color which is by default dominant over list color - though that can be controlled by input keyword @listcolordominant or by toggle of keyboard "l" (el). Line or point attribute of width: width1 == thin width2 == 2 pixels wide width3 width4 width5 width6 width7 (limit is 3 bits, stored along with point's color info) Color and width for a line is determined by the drawto point attributes. Radius of a ball or sphere at this point: r= f ----- @vectorlist { } [param...] list of lines, button name in {} { } P x, y, z Individual vectorlist item, { } L x, y, z pointID in {}, shown on info line when point picked { } L x, y, z { } P x, y, z { } L x, y, z (Can have more than one on a line) @dotlist { } [param...] list of dots, button name in {} { } x, y, z Individual dotlist item, pointID in {}, shown on info line when point picked @labellist { } [param...] List of labels, button name in {} { } x, y, z Individual labellist item. The pointID in {} is written on screen as label at that point. PointID also shown on info line when point picked. @wordlist { } [param...] List of words; button name in {}. {pointID} x, y, z Individual wordlist item PointID in {}, shown on info line when point picked. String in < > placed on screen starting at x,y,z {pointID} x, y, z (Multiple lines accepted) Within string, < or > needs "\<" or "\>"; "{}" will subscript contents and "}{" will superscript @balllist { } [param...] List of balls, button name in {}. { } x, y, z Individual balllist item (pointID in {}, shown on info line when point picked) Makes colored disk with small highlight disk to simulate a ball. Illusion requires impinging vectors to be shortened by ball radius. This is done automatically if balllist in same group, and before any vectorlists with vectors to these points. @trianglelist { } [param...] Overlapping list of point triples for triangles; first 3 make first triangle and each successive point defines a new triangle with the 2 previous points. Making a completely unconnected triangle currently requires starting a new trianglelist. If update rate in Mage is too slow, trianglelist will temporarily be shown as vectors. @ribbonlist { } [param...] Overlapping list of point triples as above, except that the triangles are dealt with in pairs which are given a common normal and are colored by a highlighted lighting model rather than depth-cued. If update rate in Mage is too slow, the ribbonlist will temporarily be shown as "cross-tie" vectors. A backbone ribbon is shown in Mage with both a vectorlist for the splines of the two edges and a ribbonlist of successive lines across between the edges. Rendered as rectangular segments. ---------------- -----PARAMETERS (optional) for Graphics Objects @group,@subgroup, @___list: (in any order, between keyword and line end master= { } Master button, will control all objects with same { } in their master parameters. {12 char max} MAGE creates a button for each unique master= { }, which when toggled resets the show-flag for all objects with that particular master= { }. Master buttons have on/off indicating check mark boxes, and appear on the button panel below the heirarchical-object buttons and above markers, etc. off Object will start out turned off (button box NOT checked) dominant No buttons for objects below in heirarchy (for groups, subgroups) nobutton No button for this object (esp. useful for groups) animate Group in an animation series (only for groups; group button shows *) 2animate Group in 2nd animated series (only for groups; group button shows %) ("animat", "2animat" actually recognized by parser, so "animation" works) ANIMATE (2ANIMATE) button created whenever there are 2 or more groups flagged with animate (2animate). moview= i Use view i (only for animate groups, and takes effect only when that group is turned on by an "animate" control) instance= { } Repeats the previous list, subgroup, or group that had the unique exact name given in { } lens Special display flag: points in this list will only show within center lens (default radius = 7.0, reset with @lens f). Subgroups and lists inherit this parameter. static Makes this display object immune to rotation, scaling, view, etc., but can be turned on & off by buttons or animation, and adjusts with window size ---Parameters only used with lists: color= string (for any type of list) String is color name (default white) Currently defined color names (see Kin.1 of Demo5_4b.kin) are: red,green,blue,cyan,yellow,magenta,white,pink,orange,purple,sky, brown,gray,gold,yellowtint,sea,pinktint,bluetint,greentint,hotpink. Each color name == a number in a lookup table (in the above order). $ rust==orange, skyblue==sky, seagreen==sea, paleyellow==yellowtint nozclip Avoids zclip discrimination for items in this list; used to let something stand out in a surround of clipped objects. detail puts this list under control of level of detail which is controlled by update rate, settable by a pull down menu. radius= f (balllist) Radius of the balls in this balllist. (default = .2) Vectorlists after balllists within a group will have appropriate vectors shortened to make the illusion that disks are balls. $ radius= f (vectorlist) "radius" to shorten vectors at a point flagged with a B. (see vectorlist param. B) radius= f (labellist) Lets label "float" forward on surface of ball or sphere, but revert to center point if ball/sphere turned off [width= i (vectorlist) linewidth overrides general linewidth control, & is in turn overridden by individual drawTo point's line width. NOT yet implemented in 5.4: prototyped for 5.5+ ] 1bondrot f n = 1-9: Next two points define an axis. Then allows hierarchical rotation (level 1>2>3...) about that axis, of all following points until another rotation of the same level, or lower n, is specified. f is starting value of torsion angle (default = 0.0), used to position slider and as label above it. MAGE creates a slider to right of button panel for each rotation; maximum is 10 rotation axes. (EOF or "@vectorlist {dummy} 0bondrot 0.0" ends scope of all rotations) Can be off, with no button, quite hidden. 2bondrot f .... 9bondrot f 0bondrot f Ends scope of rotations. Example of rotation setup for an Ile sidechain: @subgroup {sc rotat} @vectorlist {chi1} color= sea 1bondrot -162.7 {ca ile 13} P 10.458 10.692 -.195 {cb ile 13} 9.952 10.935 1.283 {cb ile 13} P 9.952 10.935 1.283 {cg2 ile 13} 8.509 11.472 1.366 @vectorlist {chi2} color= sea 2bondrot 87.1 {cb ile 13} P 9.952 10.935 1.283 {cg1 ile 13} 10.024 9.657 2.032 {cg1 ile 13} P 10.024 9.657 2.032 {cd1 ile 13} 11.44 9.503 2.645 @vectorlist {dummy} nobutton 0bondrot 0.0 ____________________________________________ [In its capacity as a graphics workbench, Mage recognizes a number of keywords and parameters used in experimental kinemages but not defined as part of the official kinemage format. For example, hplot and vplot are used for successively plotting value of last two rotations (on command) onto a screen plane overlay, e.g. phi-psi plots. The parameters Lbrotoptions 1-10 are used for both precession geometry and docking, while @control, @parameter f, precession, selection, samescope2, etc. are needed for the non-Eulerian angles of a precesssion camera. Therefore, the following parameters are reserved for such special uses: screen, hplot, vplot, Lbrotoptions 1-10, precession, selection, x-zrotation, x-ztranslation, phirotation, psirotation, samescope2-4 Similarly, the following keywords are reserved for such special uses: @control, @parameter f, @beginselect, @endselect, @copyright, @title ]