This description of the kinemage format, which is taken from Mage's internal help, is very terse and may be incomplete in places. A more complete treatment in included in the KiNG documentation as format-kinemage.pdf, which covers all of the core functionality that Mage and KiNG share. For more information on the format, email Dr. David Richardson (dcr@kinemage.biochem.duke.edu) or Ian Davis (iwd@duke.edu).


Kinemage format from Mage's help:

Kinemage format keywords
Group,Subgroup,List parameters
Hypertext help


keywords ^TOP^


keywords start with @
alternates sometimes shown, but preferred form is listed first
@keyword {text characters} are those enclosed in {}
See 'Properties' listing for object keyword parameters and point attributes
--------text section------
@ of a real keyword must be first character of a new line
keywords here are set in by a space so this text can be read in Mage
@text starts text section
@mage #.## MAGE version (can come before @text),
only keyword recognized WITHIN text section
@kinemage # ESSENTIAL keyword to end text and start kinemage input
--------------------------
--------kinemage input----
# indicates an integer needed, #.## a floating point number.
@start control for reading from a sustained active pipe: start a frame
recognized by pipe handler code
@frame # frame number of image from a sustained active pipe, override
@finish control for reading from a sustained active pipe: finish a frame
@done control for reading from a sustained active pipe, close pipe

@mage #.##
@prekin #.##
@caption --->chars to caption until next recognized keyword---
@text --->any text appended until next recognized keyword (5_75+)

---MAGE object hierarchy: group, subgroup, list, (sets of points) points
points can be in connected line sets, or specify triangles, spheres, etc.
@group {name} [parameters... all on one line...]
@subgroup {name} [parameters... all on one line...] (@set)
@____list {name} [parameters... all on one line...]
some type of list is ESSENTIAL for a kinemage
@vectorlist (@vector)
@labellist (@label)
@wordlist (@word)
@dotlist (@dot)
@balllist (@ball)
@spherelist (@sphere)
@trianglelist (@triangle)
@ribbonlist (@ribbon)
@arrowlist (@arrow)
@marklist (@mark)
@ringlist (@ring)
@fanlist (@fan)

---MAGE points---follow @____list line on the next line
{pointID} [attributes... separated by spaces, commas, new-lines, etc.] x y z
--trailing triple: x,y,z defines scope of a point, x,y,z only required thing
----table cells only: 'tablecell' or 'noxyz' can stand for triple
Generally, list type determines meaning of all its points,
but point attributes can force different meanings within a list
for advanced, special purpose, complicated kinemages.

@kinemage # ends this kinemage input
@noscale
@scale #.##
@compare side-by-side of sequential animate groups, overrides stereo
stereo is reader's choice: menu and keyboard s key
@stereoangle #.## + for wall-eye, - for cross-eye, also under menu control
+ vs - toggled by keyboard c key
@onewidth default is multiwidth, also menu control
@thinline
@perspective
@plotonly
@flat @xytranslation
@pickcenter
@zclipoff
@whitebackground (@whiteback) (@whitebkg)
@viewid {string} @1viewid {string}
@2viewid {string}
...
@##viewid {string}
@zoom #.## @1zoom #.##
@2zoom #.##
...
@##zoom #.##
@span #.## @1span #.##
@2span #.##
...
@##span #.##
@center #.## #.## #.## @1center #.## #.## #.##
@2center #.## #.## #.##
...
@##center #.## #.## #.##
@matrix #.## #.## #.## #.## #.## #.## #.## #.## #.## @1matrix ...
@2matrix #.## #.## #.## #.## #.## #.## #.## #.## #.##
...
@##matrix #.## #.## #.## #.## #.## #.## #.## #.## #.##
@zslab # @1zslab # @zclip # @1zclip #
@2zslab # @2zclip #
... ...
@##zslab # @##zclip #
@ztran # @1ztran #
@2ztran #
...
@##ztran #

@localrotation #.## #.## #.## #.## #.## #.## #.## #.## #.##
a.k.a: @localrotat ... @localmatrix ...
@endlocalrotation @endlocalrot @endlocalmatrix
@localprecenter #.## #.## #.## @localcenter ... applied before matrix
@localpostcenter #.## #.## #.## applied after matrix
@endlocalcenter @endlocalcen @endlocalprecen @endlocalpostcen

@gnomon #.## #.## #.## #.## #.## #.## #.## #.## #.## #.## #.## #.##
place after the @group... line: to belong to that group
points on 3 axes and center (ok if each on separate line)
used by Docking routines to track change to a mobile group
MAGE will add to existing gnomon info or create anew if needed

@fontsizeinfo # @fontsizeinfo #
@fontsizelabels # @fontsizelabel #
@fontsizewords # @fontsizeword #
@tablefontsize # @fontsizetable #
@tableblackbkg black background (and blk bkg palette) for table
@tablewrap # number of columns across before wrap line below
@tablewrap auto-wrap first implemented in Java Mage
@tablewrapdecades auto-wrap # columns rounded down to 10's
@tablecolscale #.## scale calculated column width
@tablemarkradius #.## square marker radius for table selected graphics points
@tablefancore #.## inner radius of table value fan on graphics point
@tablefanradius #.## outer radius of table fan at a graphics point,
this is multiplied by point radius to represent the cell value

@beginselect keyword starts selection range, re: bondrot selection
@endselect keyword ends selection range, re: bondrot selection

(@beginemphasis prototype use only: starts selected range of emphasis)
(@endemphasis prototype use only: ends selected range of emphasis)

@listcolordominant @listcolordom usually point color is dominant: key 'l'
@lens #.## parameter of lens radius for lists marked "lens": key 'e'

@minutes #.## timed test of #.## minutes, results automatically written.
@drawline enables draw new function only for lines between points
@drawlabel enables draw new function only for labels (=pointID) at points
@drawball enables draw new function only for balls at points
(lines, labels, balls are inclusive! See list params answer & result: )
(scoring done only on answerlist type: limited to one type as of Sept 02)
@drawnew enables all draw new functions, useful for practice, etc.
(answer list without @minutes allows user to see scored result)
KINEMAGE menu items enabled to allow users to score and proceed in tests
@nosavealert NOT warn user about new drawings before doing next kinemage
@bigfonts sets toggle (w key) ON
@shortline #.## absolute amount to shorten each end of a new draw line

@comment {xxx yy z} character string just transfered unused to output
@command {xxx yy z} character string to be used for remote update cmd
@control creates a control button Lcontrol, which toggles Lcontrolon
@title {arbitrary kinemage title}
@copyright {date and author(s) }
@mapfile {filename.xmap} optional actual name to use for kin3Dcont
must be before any @group... line to apply to whole kinemage
@pdbfile {filename.pdb} optional actual name to use for prekin or probe
must be before any @group... line to apply to whole kinemage
@grouppdbfile {filename.pdb} specific group pdb to use for prekin or probe
must follow @group... line to apply to that group

--- masters ---
@colorset {name} color unique name and standard color as char strings
usage: @____list {listname} color= {name} ... anywhere in kinemage

@master {name} * forces named master buttons in inputed order
where * is one or more attributes optionally following {name}
"indent" "space" "on" "off" on off particular for pointmaster
@pointmaster 'C' {name} character 'C' associated with master= {name}
usage: {ptID} 'C' #.## #.## #.##

--- aspects ---
@1aspect {name-of-1st} (necessary to define for point aspect colors)
@2aspect {name-of-2nd}
...
@26aspect {name-of-26th}
points can have up to 16 color-codes in parentheses (ABC...)
positions invoked as the order of the numbers # of @#aspect {name}
but each position can have any one of the 26 capital letter color codes
codes in MAGE-HELP/Make kinemage: Internally generated palette kinemage. , Use "]" and "[" keys to cycle through aspects.

@nowfind {string} invokes FIND, input on the fly from an appended file
e.g.append 3 lines to search for string: @start @nowfind {string} @finish
as outputed by File/Save Special/pointID to file

@parameter #.## get up to 10 parameters to play with, e.g. diffractometer

@fullrgbpalette
{ #} #, #, #, {comment} matches: File/Save Special/palette to file
...
first # is 0-255 index of entry, then R,G,B 0-255, (comment ignored)
arbitrary number of entries, 251-254 ignored, entry color name NOT changed

-----obselete or violating reader's prerogatives----------
(@float #.##)
(@integer #)
(@ignore) allowed kinemage file to also be a, e.g., PS300 CHAOS display file
(@keepstereo) valid reader's choice but over-ridden by author's compare
(@keepthinline) artifact as author's choice, reader can use keyboard 't'
(@keepperspective) (@keepperspec) artifact as author's choice, keyboard 'p'
(@specialps) obselete: PostScript output now on menu
(@projection) construct line length * 1/cos(angle): now menu choice
(@constructdot) construct line puts dot instead of a line: now menu choice
(@multibin (#)) obselete, no effect
(@zoomonly) obselete, no effect
(@sideclip) obselete, no effect

END

parameters ^TOP^


--------mage group parameters------
@group {name} [param...]
animate (*prefix)
2animate (%prefix)
off
dominant (no buttons for member subgroups and lists)
nobutton (for this group)
recessiveon (dominant if off, recessive if on)
collapsable collapsible synonyms for recessiveon
master= {name} (common master name) (see NOTES)
instance= {name} (name of a proceeding group) (see NOTES)
clone= {name} (name of a proceeding group) (see NOTES)
moview # (number of a Menu VIEW)
lens (applied to member points)
float (obselete now always do floating point perspective calc:
--- parameters for table groups ---
table (members put into table, invokes Mage to make a table window)
header (members are column headers of table: use labellist or wordlist)
(each table row is a group, uses labellist,wordlist,fanlist)
(point coords meaningless in a table: use "tablecell" for "x,y,z")
table pick picks graphics point with same pointID

--------mage subgroup parameters------
@subgroup {name} [param...]
off
dominant (no buttons for member lists)
nobutton (for this subgroup)
recessiveon (dominant if off, recessive if on)
collapsable collapsible synonyms for recessiveon
master= {name} (common master name) (see NOTES)
instance= {name} (name of a proceeding subgroup) (see NOTES)
clone= {name} (name of a proceeding subgroup) (see NOTES)
lens (applied to member points)

--------mage list types------
vectorlist (Point x,y,z -->Line x,y,z -->Line x,y,z ...)
labellist (pointID displayed at x,y,z)
wordlist ( ,inc. new lines, displayed at x,y,z)
dotlist (line width # pixels at x,y,z
balllist( (disk [highlight] [shortened lines], center at x,y,z)
spherelist (stacked disks [highlight] [shortened lines] at x,y,z)
trianglelist (filled-in triangle)
ribbonlist (sets of 2 filled-in triangles have same normal)
arrowlist (Tail point x,y,z -->Head x,y,z with 4 tines ...)
marklist (screen-oriented squares around x,y,z)
ringlist (screen-oriented annulus around x,y,z)
fanlist (table member: screen-oriented, weighted feathers)
(weighted feathers radiate from x,y,z of asociated graphics point)
(@tablefancore #.## inner radius of table value fan on graphics point
(@tablefanradius #.## outer radius of table fan at a graphics point,

--------mage list parameters------
@_____list {name} [param...]
off
nobutton (for this list)

answer (list used as answer key with @minutes timed test)
(answer dominant nobutton off (hide answer key from user))
(answer must have point types of lines, labels, balls as test asks)
(answer list can be made with drawnew function in Mage.)
(see @minutes, @drawline, @drawlabel, @drawball ... )
result (list from drawnew of an earlier mage run to be scored vs. answer)

color= name colour= name (mage palette named colors)
master= {name} (common master name) (see NOTES)
instance= {name} (name of a proceeding list) (see NOTES)
clone= {name} (name of a proceeding list) (see NOTES)
lens (applied to member points)
detail
radius= # (ball, sphere, mark, ring, arrow-head vane length)
angle= # (arrow-head tine angle)
width= # (pixel width of lines)
static (dynamic rotations not applied to members of this list)
nozclip (applied to points in this list)
nohi nohighlight
face (for characters in wordlist)
font (for characters in wordlist)
size (for characters in wordlist)

--------list parameters for bond rotations--------
see @beginselect and @endselect for artificial scope
otherwise scope of bondrot is from first point of list to last point
before bondrot of equal or lower number, or end of file
Starting angle is arbitrary as far as MAGE is concerned,
should be actual dihedral
Ganged rotations distinguished by listname
(phirotation) obselete March 2002 (flags a ganged rotation)
bondrot #.# (starting angle, one of ganged rotations)
0bondrot #.# (starting angle, trunk)
1bondrot #.# (starting angle, first branch)
2bondrot #.# (starting angle, later branch)
3bondrot #.# (starting angle, ...)
4bondrot #.# (starting angle)
5bondrot #.# (starting angle)
6bondrot #.# (starting angle)
7bondrot #.# (starting angle)
8bondrot #.# (starting angle)
9bondrot #.# (starting angle)
March 2002: recognize up to 20bondrot levels, accept up to 100 bondrots
(99bondrot prototype for monotonically continuing branch from last n)
parameter (Lbrotoption 1)
precession (Lbrotoption 2)
selection (Lbrotoption 3)
xrotation (Lbrotoption 4)
yrotation (Lbrotoption 5)
zrotation (Lbrotoption 6)
xtranslation (Lbrotoption 7)
ytranslation (Lbrotoption 8)
ztranslation (Lbrotoption 9)
samescope2 (2 bondrots have the same scope as first of 2)
samescopt3 (3 bondrots have the same scope as first of 3)
samescope4 (4 bondrots have the same scope as first of 4)
hplot (bondrot value plotted horizontally)
vplot (bondrot value plotted vertically)
zplot (bondrot value plotted in&out, perpendicular to screen)
pattern c... (MAXBONDPATT==37 characters== 0...A or R,Y,G on UNIX slider)
phirotation (Lbrotoption 10 ganged rotation of same-named bondrot lists)

--------mage point attributes------
point attributes are usually separated by white space
as a matter of style and ease of editing, do separate all by white space
but sometimes worth maximal compression to use storage, transmission, etc.
thus whitespace as separator and as field delineator a bit tricky.
----------points---follow @____list line on the next line:
{pointID} [attributes...separated by spaces, commas, new-lines, etc.] x y z
{ final } does not require white space before next attribute.
--trailing triple: x,y,z defines scope of a point, x,y,z only required item
x y z fields delineated by non-numeric whitespace blank , ; : cr lf tab
----table cells only: 'tablecell' or 'noxyz' can stand for triple
saved and outputted for all point types
written to screen for wordlists, written in cell in table groups
if present, written in lower left screen when label is picked
--------single character flags, all except P need trailing white space
P defines new beginning of Point-->Line-->Line-->...polyline in vectorlist
P synonyms are p M m i.e. in Move-->Draw, exception: P ends itself
presumed for first point of a vectorlist. L for 'Line' not essential.
L synonyms are l D d
U (or u) flags point as unpickable, see menu superpick item
B (or b) ball at this point in a vectorlist
S (or s) sphere at this point in a vectorlist
R (or r) screen oriented ring at this point in a vectorlist
Q (or q) screen oriented square at this point in a vectorlist
A (or a) arrow on this point of a vectorlist
T (or t) point is to be interpreted as part of a triangle in a vectorlist

'C' single quotes around character(s) identifying pointmaster(s),
case sensitive, declare before use earlier in kinemage
to avoid single char master name or master-name conflict:
@pointmaster 'C' {name} character 'C' associated with master= {name}

--------multiple character attributes------- need surrounding white space
colorname any of mage palette color names;
colorname! (exclaimation point) forces use of point color.

width1 (or thin) for forced one pixel wide lines
width2 (width#, where #= 1...7) forced # pixel wide lines
Effective pen width = line width specified by point width or list width
where point width is dominant over list width setting.
When not specified, multi-width mode uses pen width for depth cueing
but some display objects (rings and marks) default to a const.

r= f point radius for points that are balls, spheres, rings, etc,
also used for arrow vane length (vane angle is list angle).

dummy (or DUMMY) point is NOT used for setting min,max x,y,z extents
tablecell (or noxyz or NOXYZ) substitutes for x, y, z triple
ghost (or GHOST) point is seen but not in special output (like PDB)

NOTES:
master:
The same master can refer to groups,subgroups,lists, each of which can
have multiple masters, but only 32 unique masters total.
Multiple masters are restrictive: all have to be ON for object to be ON
instance:
Object merely redisplayed at original coordinates, color can be different
but inherits masters, etc.
clone:
Object actually copied, can have changed coords, etc. new object in output.

mage commandline options:
COMMANDLINE, NO GUI, postscript output of each animation view:
mage filename.kin -postscript
produces: filename.kin.1.eps , filename.kin.2.eps , ... for n animate views

COMMANDLINE, NO GUI, meager help to standard out:
mage -help

COMMANDLINE, NO GUI, chronological list of changes to standard out:
mage -changes

COMMANDLINE options along with GUI:
-fontinfo dumps font possibilities to UNIX console
-medium forces use of meduim font for menus, dialogs, text: OK 1024x768
-large forces use of largest font: TOO BIG FOR <= 1024x768 SCREEN!
-macular == -jeremy chooses medium or large font based on screen size
-small forces use of small font, the old default (before 031127)


Capture the foo (besides game mode)
menu:Tools/Kludges/foo in cavity
Pick point for initial foo, grow in cavity, surface the foo.
Foo will coat a surface, and not puff out into the void.
Note: use Show Object Properties: group ignorable (by the foo).
For proper VdW size use: prekin -atomradii ...

END

hypertext ^TOP^


--------mage hypertext help------
The hypertext capabilities of MAGE text has two interrelated functions.
One is for a system of questions presented to the reader that are each
answered in a dialog box that gives the reader access to information from
the most recently picked points.
The other is facility to instruct MAGE to move around in the kinemage
by jumps to specific kinemages and views, find pointID text strings, turn
on and off masters, and reset bond rotations. Of course, these moves can
be part of a scheme of questions. However, they confer an enormous power
to the reader, particularly because the text, including the hypertext, can
be edited during the session!
For Questions, kinemage number and View number are carried forward from
the last time they were set during the linear input of the TEXT window
material. Thus kinemage and view can be presumed for the go-to-graphics
option of a new question. However, if these are to re-defined for the
current question, this must be done before any master-button or FIND
controls are specified. This dependence on the order of controls is
NOT hypertext-like and might frustrate the reader/lecturer if they try to
jump around in the text. The author must balance readability and flow
of the text with robustness.

Format: starts with '*{' includes [options] ends with '}*'
Questions start with Q: but Mage keeps track of the question number.
*{Q: text of question... }*
Thus, if the second question in the kinemage is:
*{Q: Which is the active Ser?}*
Mage shows this in the text, with room for the answer in the underlined space
*{Q: 2 Which is the active Ser?}*___________________________

Change instructions to Mage include:
*{kinemage #, view #, alloff, master={name} on, find {string} }*
abreviations: kinemage kin k, view v, master m, find f
'alloff' turns all masters off, masters are individually set 'on' or 'off'

Bond rotations can be set (and edited and reset!):
*{rot={name 1} #.#, rot={name 2} #.# ...}* abr: 'rot=','rot ','r '
where 'name 1' == the bondrot identifier string seen on the slider bar
and #.# is the new value for that rotation angle
If Update by PROBE active, hypertext 'rot' triggers an update.
PREKIN after version 5.74 makes hypertext commands
for rot/mutated residues

END