KINFMT54.TXT - Kinemage format  LIST OF KEYWORDS, etc. for MAGE_5.4:
      (best read in Courier or other non-proportional font, with
             page wide enough for 75-character lines)
    Meant for kinemage authors, or for programmers.


  Key to annotation flags in this file:
->  should not be used by authors in distributed kinemages.
$   annotations for programmers (authors should not use features $ marked).
$-> programmers need NOT use these: will NOT be supported in the future.
('i' stands for an integer, 'f' for a floating-point number)

Note: Keywords can have additional characters beyond those the MAGE parser
    actually recognizes.  As a matter of style and long term robustness,
    however, authors should use fully spelled out keywords.
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.
         Carriage returns are omitted except for paragraphs or lists, to
         allow text wrap when windows are resized.
    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
 @xytranslation:synonym. Use one ot these for authored 2D kinemages;  
            readers can toggle xy scrolling mode with keyboard "f".

$ @multibin i   Archaic: once used to improve fineness of hidden-line
            removal, now optimized and built in.  Do nothing, but
            recognize as valid, since lots of old files use @multibin.

    [Section below distinguishes things that are the author's business to specify for how a kinemage should be viewed, at least initially, from things that are reader's choice for viewing.  E.g.: line quality (thinline, etc.), and perspective are author's choices, while stereo or enlarged font size are a reader's choice. The idea that readers would develop preferences for viewing kinemages in general seemed reasonable when associated with limitations of early computers, but has now been rejected because the reader should try a kinemage, at least to start with, the way the author specified.]

-> @keepstereo  Obsolete: Invokes stereo, for rest of session 
             (can be turned off manually).
             Authors should NOT set this in a distributed kinemage;
             readers can still toggle keepstereo using keyboard "s". 

-> @stereoangle f  Changes stereo angle (default is 6 degrees, wall-eye).
             Authors should NOT set this in a distributed kinemage.
             Readers can toggle cross-eye/wall-eye using keyboard "c"
             or change parameters using menu.  

-> @keepthinline  Obsolete: Invoked thinline for rest of session (speeds
             rotation, esp.on early PC's). Authors should NOT set this
             in a distributed kinemage; instead use single-kinemage form
             @thinline.  Readers can select thinline using keyboard "t". 

-> @keepperspective Obsolete: Invoked perspective, for rest of session.
             ("@keepperspec" actually recognized by parser)
             Authors should NOT set this in a distributed kinemage;
             instead use single-kinemage form: @perspective.
             Readers can toggle perspective using keyboard "p".
         
@noscale     Initial scaling and centering will not be done. (Watch out!)
@scale f     Reads in scaling factor to be used, and initial scaling 
             and centering will not be done. (Watch out!)

@zclipoff    Kinemage comes up with zclip OFF. 
             (Lets zslab control depth cueing without clipping image)
             Zclip toggle button always available anyway.

$ @ignore    Mage ignores everything until another valid keyword is found.
             (Historically used to let MAGE and CHAOS share input files.)

$-> @pickcenter  kinemage will come up with pickcenter ON (Beware!)
             Pickcenter toggle button always available anyway.
$-> @zoomonly  Obsolete, now dummied. Zoom slider always available anyway.
$-> @sideclip  Obsolete, now dummied. Sideclipping always done anyway.

@plotonly (before all points) Gives 2-D plot with no rotation, and no 
             limit on number of points
          (after all points) Gives no-erase "kaleidoscope" image; rotation
             smears.  Readers can toggle "kaleidoscope" using keyboard 'k'

------------
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

$-> @zclip  Archaic synonym for zslab

@center f f f   X, y, and z of center of rotation and center of screen 
                 (in orig. coords.)
 @1center f f f:  synonym
@2center f f f   Center for View2
  . . . .
@60center f f f

@matrix f f f f f f f f f      3x3 orientation matrix for startup view
                on same or following line(s)
 @1matrix f f f f f f f f f:  synonym
@2matrix f f f f f f f f f     3x3 orientation matrix for View2:
@3matrix        a11,a12,a13,a21,a22,a23,a31,a32,a33
@4matrix        operation:
@5matrix                 x,y,z       | a11, a12, a13 |      x',y',z'
@6matrix                         X   | a21, a22, a23 |  =
@7matrix                             | a31, a32, a33 |
  . . . .
@60matrix f f f f f f f f f


------------
@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".

@command {...}  String is read in, to be the command line presented in
     remote-update dialog as the possible command line to be sent.

@localrotation f f f f f f f f f  Rotation matrix applied to part of file.
     ("@localrotat" actually recognized by parser) 
     ("@localmatrix": synonym)
                 Coordinates are changed during input and stored changed.

@endlocalrotation  Ends part to be rotated; use if more items follow
     ("@endlocalrot" actually recognized by parser) 
     ("@endlocalmatrix":synonym) 

        [Note that local transformations (and bond rotations) are the ONLY
     things in the kinemage format that need to be ended explicitly.]

@localcenter f f f  Centering translation: puts center of rotation at point
  ("@localprecenter":synonym)
     If a localrotation is specified, translation done first.
     Coordinates are changed during input and stored changed.
@localpostcenter f f f Centering translation: puts center of rotation at
     point.  If a localrotation is specified, translation done after.

@endlocalcenter  Ends scope of localcenter,localprecenter,localpostcenter.
     ("@endlocalcen" actually recognized by parser)
  ("@endlocalprecenter":synonym)
     ("@endlocalprecen" actually recognized by parser)
  ("@endlocalpostcenter":synonym)
     ("@endlocalpostcen" actually recognized by parser)

     [Note that this sequence:
          @localprecenter x,y,z 
          @localrotation... 
          @localpostcenter -x,-y,-z 
            intervening groups,subgroups,lists, etc.
          @endlocalcenter
          @endlocalrotation
     will do rotation of intervening stuff around the point x,y,z
     If modified kinemage is written out, it has the changed coordinates.]

---------------
-> @fontsizeinfo i  Font size for the information line (pointID & distance)
-> @fontsizelabel i  Font size for labellist items    
-> @fontsizeword i   Font size for wordlist items    
     -> These font size controls should not be used by authors in 
     distributed kinemages, since fonts vary from machine to machine.
     They are useful for setting up a presentation on a particular
     computer,  but usually reader (or lecturer) changes them from menu.

$-> @specialps   Do non-clipped floating point recalculation for PostScript
     output, done now by PostScript output control dialog box.
     Obsolete: this is now how Postscript is always done.

@listcolordominant  Lets author determine that list color will come up
     toggled so that it over-rides point color.  Reader can always toggle
     this state with keyboard "l" (el).
   ("@listcolordom " actually recognized by parser)

->@projection   Obsolete: sets flag so construct4 extends line or dot by
     cos of angle, thus plotting onto a plane (film) rather than a sphere.
     Now controlled in the construct dialog box.
$->@constructdot  Obsolete: sets flag so construct4 makes a dot rather than
     drawing a line to the constructed point.
     Now controlled in the construct dialog box.


-----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.
 [Note that for Mage 4.4 and later a < > comment, if present,
        is what will be shown on the info line]

@wordlist { }  [param...]     List of words; button name in {}.
  {pointID} <wordy stuff> 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
        <limit of 255 characters; can have newlines, as below>
  {pointID} <string line 1
  string line 2> 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.


$ @vector == @vectorlist      Short form is what parser recognizes,
$ @label  == @labellist         but authors should use full form.
$ @dot    == @dotlist         A number of old kinemages use short form,
$ @word   == @wordlist         so need to preserve this.
$ @ball   == @balllist     

----------------

-----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 boxes, and appear on the
     button panel below heirarchical-object buttons and above markers, etc.

off       Object will start out turned off (button box NOT checked)
 $-> "-"   Obsolete symbol for "off"

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).

$-> "*"  Obsolete symbol for "animate" for a group,
        Obsolete symbol for "dominant" for a subgroup
        Obsolete symbol for "off" for a list

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 { }

<  >  Totally ignored comment if with parameters. Not stored, so lost when
        kinemage written out from MAGE.  (comment stored only if in TEXT
        region, in a wordlist, or preceding an individual point triple)
        Can have "<" or ">" in text if done as "\<" or "\>"

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

      [The following wordlist parameters should not be used by authors
      until we get better descriptions and defaults for the fonts on
      various platforms.
$  font= i  (wordlists only) Coded integer for font to be used.
$  face= i  (wordlists only) Coded integer for font face to be used.
-> size= i  (wordlists only) Coded integer for font size to be used.
    Font size as parameter to a wordlist only affects that wordlist, so 
    though computer specific, does not mess up general machine defaults.] 

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 ]