label3d (1) - Midas delegate for displaying 3-D labels

LABEL3D(1)UCSF

NAME

label3d - Midas delegate for displaying 3-D labels

MIDAS COMMAND SYNTAX

Command: delegate start ll label3d

DESCRIPTION

Label3d is a MidasPlus delegate that generates MIDAS object files which contain character labels composed of move and draw commands. The built-in MIDAS atom labels are fixed- size characters which appear left-to-right across the display. Because the character labels that label3d generates are MIDAS objects, they may be translated, rotated and scaled in three dimensions in the same manner as molecules. An additional benefit of being MIDAS objects is that these character labels may be shown by ribbonjr(1) and neon(1).

     Label3d is a program designed to run in conjunction with
     MIDAS using the MidasPlus delegate mechanism.  The standard
     way that label3d is invoked is for the user to start a MIDAS
     session and issue the MIDAS command
          delegate start ll label3d
     which runs label3d and tells MIDAS to pass commands
     beginning with ll through to label3d for further processing.
     The complete set of commands that label3d can handle are
     described in the COMMANDS section of this manual page.

EXAMPLE

A few typical uses of label3d are demonstrated in this section. It is assumed throughout this section that the standard PDB file 1alc (A-lactalbumin) has been opened for display in MIDAS and is the molecule of interest for labeling purposes. For purposes of clarity, label3d command names will be shown in full though shortened forms of the command names are accepted by label3d. The acceptable short form of the command name will be emboldened for emphasis.

Setting up for labeling

     The first thing is to start the label3d delegate with the
     command:
          delegate start ll label3d
     You should receive a reply indicating the delegate started
     normally.  After issuing the above command, all commands
     prefaced with ll will be handled by the label3d delegate,
     while other commands will be processed by MIDAS.  If the
     reply states that the delegate failed to start properly, it
     may be that label3d had been invoked earlier in the session
     but not stopped with the label3d command stop (see finishing
     labeling, below).  Typing
          ~makemark label
     will allow the delegate to be started normally.

     Next, the fonts that will be used must be opened.  This
     example will be using two fonts, which would be opened with
     the commands:
          ll open r roman-c
          ll open g greek-c
     The available fonts are described fully in the FONTS section
     of this document.  Opening a font makes it the current font,
     so after the above commands are executed the current font is
     greek.

Making a label

     To make an example label, which is associated with a
     specific atom, use the command:
          ll label #0:41@CD1 Label text
     This would display the string Label text (in greek!) near
     atom CD1 of residue 41 of model 0.

Changing label attributes

     As mentioned above, the current font is greek, so to change
     the label text to roman, issue the command:
          ll use r
     The text initially starts with its lower left corner near
     the anchor atom.  To change the justification so that the
     center of the right edge of the label is near the atom, use
     the command:
          ll justify right center
     If the label were too close to the structure, it could be
     moved away with the command:
          ll offset -1 0
     which would move the label 1 angstrom to the left (positive
     x moves right, positive y moves up, positive z [optional]
     moves closer).

     The label could then be made a little smaller with the
     command:
          ll scale 0.9
     If, instead, you wanted to make all labels that use the
     current font to be smaller, you would use the command:
          ll scalefont 0.9
     Finally, to color the label light blue, the following two
     commands could be used (the first of which is a standard
     MIDAS command):
          colordef lblue 0.0 0.7 1.0
          ll color lblue

Making a multi-font label

To make the label ``B sheet,'' start with the command:: ll label #0:43@N b Note that there is a trailing space at the end of the above command, so that the text that will be appended later (``sheet'') will have a space separating it from ``B.'' The attributes of the new label could now be set with: ll justify right bottom ll use g colordef dgreen 0.0 0.6 0.0 ll color dgreen The remainder of the label would be appended with: ll append sheet The appended part of the label would be set to roman font and the entire label given additional space from the structure with the commands: ll use r ll offset -2 0

Making a title

     Since titles are not associated with any particular atom,
     one creates a title at the origin with a command such as:
          ll label Structure
     and use scale and position to size and position it:
          ll scale 2
          ll position 14 -6 35
     The above position command places the title in the lower
     right area of the screen and (due to the positive z) in
     front of the molecule.  This z positioning is useful in
     stereo views.

Finishing labeling

It is rarely desirable to stop the label3d delegate since the label positions then can no longer be updated to compensate for model rotations. However, occasionally the user may wish to remove all current labels and start over. In this case, do not use the MIDAS delegate stop command. Instead, use the label3d command stop. This allows the label3d delegate to issue some cleanup commands to MIDAS before stopping. Unless these cleanup commands are executed, a new label3d delegate cannot be started. Note that the stop command will remove all current labels.

MIDAS cannot restore delegates to the state they were in when a MIDAS session is saved. If it is necessary to save a session involving a label3d delegate, the delegate's state will have to be recorded with the label3d save command, and restored in the restarted session with the source command. Both these commands are described in detail in the COMMANDS section of this manual page.

COMMANDS

     When label3d is acting as a delegate for MIDAS (as shown in
     the DESCRIPTION section), the user can give it commands by
     typing
          ll label_command
     in the MIDAS command window.  The list of commands is given
     below in alphabetical order.  Note that the command names
     can be shortened to the minimum number of characters need to
     distinguish the command from other label3d commands.  For
     example, append could be shortened to a or scalefont could
     be shortened to scalef.

append value: Append the string value to the current label. This creates a multi-font label, and makes the newly appended part the current label. Subsequent commands such as color and use will only affect the new addition. To make some intermediate part of a multi- font label become the current label, use the label command described below.

close font_name: Close the font named font_name. If any label is currently displayed using the specified font, label3d reports the error and the font is not closed.

color midas_color_name: Make the current label be drawn using color midas_color_name, which must already be defined in MIDAS.

justify ( left | center | right ) [ ( top | center | bottom ) ]: Set the justification mode of the current label. If the vertical justification is not specified, the current vertical justification is retained. Labels are initially justified left/bottom.

label label_ref [ display_value ]: Make the label whose reference name is label_ref the current label. If no such label exists, create such a label. If display_value is supplied, make that the value shown for the label. If not, and the label did not previously exist, make label_ref the display value.

The label reference name is a any sequence of characters that does not include `[' or `]'. The brackets are reserved for referencing different components of a multi-font label. For example, name[1] refers to the second component of the multi-font label name (the index is zero-based). To create a multi-font label, see the append command above.

A newly created label is displayed in the current color (or white, if no color has been set) using the current font. To change these defaults, use the color and use commands.

The lower left-hand corner of the label is considered its starting point. Labels whose reference name matches a MIDAS atom specifier have starting coordinates that are the same as its atom; other labels have starting coordinates at the origin by default, but may be changed using the position command. The starting coordinates of all labels with reference names matching MIDAS atom specifiers are updated from MIDAS every time a command is processed by label3d.

The MIDAS object move/draw commands for a label are constructed by adding the label starting coordinates and offset to the coordinates found in the character descriptions (see open). Consecutive characters in a string are offset in the x dimension by the width of the left character plus a small inter-character spacing; no offsets are added in either the y or z dimension. The move/draw commands for all labels are recomputed every time a command is processed by label3d.

list ( label | font ): List all labels or fonts.

offset x y [ z ]: Change the starting position of the current label by adding an offset of (x,y,z) angstroms. If z is not provided, zero is used in its place. This command is useful for repositioning the label when it hides or is hidden behind important atoms. Repeated use of this command is not cumulative; i.e., the new offset overrides the old offset rather than being added to it.

open font_name directory: Read character descriptions from directory directory and place them in a new font named font_name. The newly opened font becomes the current font. If directory is not an absolute path (i.e. it does not start with a `/') then the system font directory will be searched for directory. Fonts available in the system font directory are described in the FONTS section of this document.

          The character descriptions are stored in files whose
          names are either single-lettered, or begin with `0' and
          consist of all numeric digits.  Files with single-
          letter names contain descriptions for the corresponding
          letters; files with names composed of all numeric
          digits contain descriptions for the characters with the
          corresponding octal ASCII values.  Character
          descriptions are simply move-and-draw commands in MIDAS
          object file format.  For example:
               .m 0 0 0
               .d 0 1 0

position x y [ z ]: Set the starting coordinates of the current label to be (x,y,z) in angstroms. If z is not provided, zero is used in its place. Note that this command has no effect if the current label's reference name matches a MIDAS atom specifier, as the label coordinates will be updated automatically.

save filename: Write out a series of commands to file filename. When this file is processed by the source command (see below), the same fonts and labels that existed when the save command was executed will be created.

scale sx [ sy ]: Scale the current label by sx in the x dimension, and sy in the y dimension. If sy is missing, it is set equal to sx.

scalefont sx [ sy ]: Scale the current font by sx in the x dimension, and sy in the y dimension. If sy is missing, it is set equal to sx.

source filename: Read commands from file filename and execute them.

stop: Terminate label3d. Note that this command should be used instead of the MIDAS delegate stop command so that label3d can issue some necessary cleanup commands to MIDAS before exiting. Also note that this command will remove all labels!

unlabel [ label_ref ]: Destroy the label named label_ref. If label_ref is omitted, the current label is destroyed.

update: Update is a do-nothing command that may be used when model positions have changed and the position or orientation of labels need to be updated.

use font_name: Make the current label be displayed using font font_name.

FONTS

The font data provided with label3d was derived from the public domain distribution of the Hershey Fonts. A variety of font faces, font sizes, and levels of detail are provided.

     The font faces are:
     Name      Description
     roman     Roman
     greek     Greek
     italic    Italic
     script    Script (cursive)
     cyril     Cyrillic
     gothgr    Gothic German
     gothgb    Gothic English
     gothit    Gothic Italian

     The font sizes and level of detail are:
     Name      Description
     p         Plain (very small, no lower case letters)
     s         Simplex (plain, normal size, no serifs)
     d         Duplex (normal size, no serifs, doubled lines)
     c         Complex (normal size, serifs, doubled lines)
     t         Triplex (normal size, serifs, tripled lines)
     cs        Complex small (as Complex, but smaller than normal size)

Not all font faces are available in all the types. The cross-table of availability is: p s d c t cs roman +o +o +o +o +o +o greek +o +o +o +o italic +o +o +o script +o +o cyril +o all gothic +o

The name used to open the font with the label3d open command is made by composing the font face name with the type name, separated by a hyphen. So the roman font face in the complex type would be referred to as ``roman-c.''

Typically one would use the the most detailed type available for the font face unless a very large number of labels are going to be used, when perhaps a simpler type might be employed.

BUGS

Good vector fonts are hard to come by.

FILES

     /usr/local/midas/resource/label3d/fonts     system font
     directory

AUTHOR

Conrad Huang, Computer Graphics Laboratory, UCSF

Eric Pettersen, Computer Graphics Laboratory, UCSF (Hershey

font conversion)

ACKNOWLEDGEMENTS

The Hershey Fonts were originally created by Dr. A. V. Hershey while working at the U. S. National Bureau of Standards. The format of the Font data distribution (not the format used by label3d) was originally created by:

James Hurt

Cognition, Inc.

900 Technology Park Drive

Billerica, MA 01821