draw

VMD offers a way to display user-defined objects built from graphics primitives such as points, lines, cylinders, cones, spheres, triangles, and text. Since these are displayed in the scene just like all other graphics, they can also be exported to the various ray tracing formats, 3-D printers, etc. User-defined graphics can be used to draw a box around a molecule, draw an arrow between two atoms, place a text label somewhere in space, or to test a new method for visualizing a molecule.

The draw command is a straight Tcl function which is meant to simplify the interface to the graphics command as well as provide a base for extensions to the standard graphics primitives. The format of the draw command is:

• draw command [arguments]

The draw command is equivalent (in most cases) to graphics top command [arguments], in that it simply adds graphics primitives to the top molecule, saving you the trouble of typing an extra argument. However, draw extends graphics in two ways. First, if no molecule exists, draw creates one for you automatically. Second, draw can be extended with user-defined drawing commands. This is done by defining for a function of the form vmd_draw_$command. If the function exists, it is called with the first parameter as the molecule index and the rest as the arguments from the original draw call. Here's an example which extends the draw command to include an ``arrow'' primitive.

proc vmd_draw_arrow {mol start end} {
    # an arrow is made of a cylinder and a cone
    set middle [vecadd $start [vecscale 0.9 [vecsub $end $start]]]
    graphics $mol cylinder $start $middle radius 0.15
    graphics $mol cone $middle $end radius 0.25
}

After entering this command into VMD, you can use a command such as draw arrow {0 0 0} {1 1 1} to draw an arrow. In addition to defining new commands, user-defined drawing commands can also be used to override existing commands. For example, if you define vmd_draw_sphere, then draw sphere {0 0 0} will call your sphere routine, not the one from graphics.

Here's a quick way to add your own label to an atom selection. This function take the selection text and the labels that atom (in the top molecule) with the given string. It returns with an error if more anything other than one atom is selected.

proc label_atom {selection_string label_string} {
    set sel [atomselect top $selection_string]
    if {[$sel num] != 1} {
        error "label_atom: '$selection_string' must select 1 atom"
    }
    # get the coordinates of the atom
    lassign [$sel get {x y z}] coord
    # and draw the text
    draw text $coord $label_string
}