VMD-L Mailing List

From: Andrew Dalke (dalke_at_ks.uiuc.edu)
Date: Fri Jan 31 1997 - 12:10:02 CST

Hello,

  This is the second in a series of articles about VMD which I hope
prove to be useful to people on the mailing list. We are also working
on improving the documentation and many of these issues will be
included in the new User's Guide.

  This week's issue describes (with many examples) how to customize
the hot keys and the popup menu and replace the current section in the
manual titled:

 = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = =

             Customizing the Popup Menu and the Hot Keys

  There are many ways to configure VMD to suit your tastes. All you
have to do is get the code, modify it, and recompile. Okay, I am
kidding here. There are a lot of ways to tweak VMD without getting
down into the code, but they do require you to know some of the VMD
scripting language. The amount depends on how much you want to
change.

 = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = =

                                Hot Keys

  VMD comes with some default kot keys. When the mouse is in the
graphics display menu you can press 'r' to enter rotate mode, 's' for
scale and 't' for translate. The full list of default hot keys is:

        r, R enter rotate mode
        t, T enter translate mode
        s, S enter scaling mode
        0 query item
        1 pick atom
        2 pick bond (2 atoms)
        3 pick angle (3 atoms)
        4 pick dihedral (4 atoms)
        5 move atom
        6 move residue
        7 move fragment
        8 move molecule
        % apply linear force to atom (when connected to NAMD)
        ^ apply linear force to bond "
        & apply linear force to angle "
        * apply linear force to dihedral "
        x spin about x axis
        X rock about x axis
        y spin about y axis
        Y rock about y axis
        z spin about z axis
        Z rock about z axis
        +, f, F advance one frame
        -, b, B go back one frame
        ., > play animation forward
        ,, < play animation backward
        /, ? stop animation

When you press a key, VMD finds if there is a command associated with
that key then executes it. For instance, the '+' key is mapped to
"animate next" which advances all active molecules by one frame.

 = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = =

                        Adding New Hot Keys

  But there are a lot of keys left over, so we provided a way for you
to add new hot keys, or even override our own definitions. The
command is

        user add key <key> <new command>

Using the '+' example, the command would be

        user add key + animate next

Here are some of the commands people I know use, which you might want
to try. Odds are many will be made default hot keys in the final 1.2
release of VMD.

These are like the vi cursor control keys and let you rotate the
molecule around the x, y, or z axis by 2 degrees at a time:

                # rotate down with the 'j' key
                user add key j rot x by 2
                # rotate up with the 'k' key
                user add key k rot x by -2
                # rotate left with the 'l' key
                user add key l rot y by 2
                # rotate right with the 'h' key
                user add key h rot y by -2
                # rotate couterclockwise with the 'g' key
                user add key g rot z by 2
                # rotate clockwise with the 'G' key
                user add key G rot z by -2

Here is a quick way to scale in and out. These keys are similar to
those used in a lot of games:

                # make larger with the 'a' key
                user add key a scale by 1.1
                # make smaller with the 'z' key
                user add key z scale by 0.9

Reset the view (returns the "top" molecule to the center of the screen
and scaled to fit):

                user add key g display reset

Turns the Main menu off then on again. Not only is this the fastest
way to open the form, but by turning it off first, the form will end
up being the foremost window on the screen:

                user add key M {menu main off ; menu main on}

The command here is in braces because of the way the intepreter works.
If they were not there, VMD would see two commands, split at the
semicolon, as in:

                user add key M menu main off
                menu main on

 = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = =

                        Changes for the 1.2 release

  The current version (starting with 1.2b1) has support for extra
modifier keys; Alt and Control. However, it doesn't have support for
keys which don't have printable representations, like F9 or the Home
key. Following are some of the hot keys which will be possible:

Quit, but verify first:

                user add key Alt-q quit confirm

Quit, without verification:

                user add key Alt-Q quit

Open the Files, Graphics and Main form, using the method just
described:

                user add key Alt-f {menu files off; menu files on}
                user add key Alt-g {menu graphics off; menu graphics on}
                user add key Alt-m {menu main off ; menu main on}

For emacs users, here are controls similar to the earlier vi-like
commands:

                user add key Control-n rot x by 2
                user add key Control-p rot x by -2
                user add key Control-f rot y by 2
                user add key Control-b rot y by -2

Remember, these Alt- and Control commands are only available in the
vmd-1.2b1 or later versions of VMD. To get a "mailing list only"
sneak preview version of the latest binary, go to ftp.ks.uiuc.edu in
/pub/group/dalke, get vmd_IRIX5.Z, uncompress and chmod +X it, and
replace your current binary with it. Since this is internal test
code, you might want to keep a copy of the original version, just in
case there is a bug. For instance, in the binary available there
until today, the 'Control-' options did not work.

 = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = =

                        Changing the popup menu

  The popup menu, available when you press the right mouse button when
the mouse is in the graphics display, has many menus, and each menu
has several items. As with the hot keys, you can customize it by
adding more menus and items.

Menus in VMD are arranged hierarchically, starting from the main menu,
and each menu has a name. A menu contains items, which may be a
command, a check-box command, or a separator. New menus and the first
and last type of items may be added by a user.

To add a menu to the main pop-up menu, use:

        user add menu <name>

For example, I'll make a menu to load some of my most often used
structures:

        user add menu Favorites

Since there isn't anything in the menu, it doesn't appear in the popup
menu yet. To add items to the menu, use:

        user add subitem <menu> <name> <command>

I often load the structures "alanin.pdb" and "brH.pdb" and remotely
download the 9pti structure from the PDB FTP site, so I'll add:

        user add subitem Favorites BPTI {mol pdbload 9pti}
        user add subitem Favorites alanin {mol load pdb alanin.pdb}
        user add subitem Favorites bR {mol load pdb brH.pdb}

Enter these three lines then bring up the popup menu. You should see
the new menu item just above the "Help" lines. Unless you are me, the
last two items probably won't work, but the first one should. Try it
out.

You can also add a separator in the menu, using:

        user add subseparator <menu>

So if I want a separation between the first three molecules and the
fourth, the poliovirus 2PLV structure, you could do:

        user add subseparator Favorites
        user add subitem Favorites Polio {mol pdbload 2plv}

Sadly, the user modifiable popup menus are not hierarchical. There is
no way to add a submenu to one of your own menus. They can only be
added to the main popup menu. However, there is another place to add
new menu items, the 'User Commands' submenu of the main menu. "Where
is it?" you ask? It doesn't contain anything, so it isn't displayed.
You can add items to it just as you can to the main menu, but the
commands are slightly different. Why are the menus this way?
Frankly, I don't know. Anyone feel like improving them?

To add an item to the 'User Commands' menu:

        user add item <name> <command>

To add a separator to the 'User Commands' menu:

        user add separator

The usage is the same as their related commands, so I won't give a
detailed example, but to see how it works, try this:

        # Turn off the axis
        user add item {Axes Off} axes location off
        user add item {Axes On} axes location LowerLeft
        # a break
        user add separator
        # delete all the loaded molecule
        user add item {Zap Everything} {
                foreach molecule [molinfo list] {
                        mol delete $molecule
                }
        }

 = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = =

                                Examples

Here are some more extensive ways to use the popup menus that I've
heard people using.

  = = = = = = = = = = = = = = =

Here is a way to set the amount of transparency for the different
colors by using the pop-up menu. This is useful when fine tuning an
image:

        # Set the alpha value of the "transparent" materials
        proc set_transparency_value {alpha} {
                display update off
                # change the opaquicity of the transparent colors
                for {set color 17} {$color < 34} {incr color} {
                        color change alpha $color $alpha
                }
                # and the transparent color scale (66 to 97)
                for {set color 66} {$color < 98} {incr color} {
                        color change alpha $color $alpha
                }
                display update on
        }
        user add menu Transparency
        user add subitem Transparency 1.0 {set_transparency_value 1.0}
        user add subitem Transparency 0.9 {set_transparency_value 0.9}
        user add subitem Transparency 0.8 {set_transparency_value 0.8}
        user add subitem Transparency 0.7 {set_transparency_value 0.7}
        user add subitem Transparency 0.6 {set_transparency_value 0.6}
        user add subitem Transparency 0.5 {set_transparency_value 0.5}
        user add subitem Transparency 0.4 {set_transparency_value 0.4}
        user add subitem Transparency 0.3 {set_transparency_value 0.3}
        user add subitem Transparency 0.2 {set_transparency_value 0.2}
        user add subitem Transparency 0.1 {set_transparency_value 0.1}
        user add subitem Transparency 0.0 {set_transparency_value 0.0}

                
FYI, since this is a scripting language, the last 11 lines could be
replaced with:

        for {set i 1.0} {$i >= 0.0} {set i [expr $i - 0.1]} {
                eval "user add subitem Transparency $i {\
                        set_transparency_value $i}"
        }

  = = = = = = = = = = = = = = =

For the other detailed example of uses for the popup menu, here's a
way to make a menu contain information specific to a given molecule.
In this case, it will be one of the myoglobin structures from Joel
Berendzen included in the vmd distribution. Since I don't know where
you keep those files on your local disk, to use this example you'll
have to change the filename to fit your setup. You really should use
cut and paste for this. If you can't, don't worry about entering the
"Set View" item.

        # Create the submenu
        user add menu Myoglobin

        # Load the molecule, and print an error if
        user add subitem Myoglobin {Load MBCO} {
                set top [molinfo top]
                #### CHANGE THIS TO POINT TO YOUR LOCAL FILE ####
                mol load pdb mbco.pdb
                if {$top == [molinfo top] || $top == -1 } {
                        error "Could not load mbco.pdb"
                }
                # keep track of the most recently loaded MBCO
                set mbco_molid [molinfo top]
        }

        # set the view so you look at the heme
        # Don't worry too much about figuring out what this does,
        # I just want to show some of the things VMD can do
        user add subitem Myoglobin {Set View} {
                rotate stop
                display resetview
                molinfo $mbco_molid set \
  {center_matrix rotate_matrix scale_matrix global_matrix} {
    {{1 0 0 1.875311} {0 1 0 -6.642823} {0 0 1 3.179466} {0 0 0 1}}
    {{0.950469 -0.149586 -0.272456 0 } {0.282904 0.779412 0.559000 0 }
    {0.128737 -0.608391 0.783126 0 } {0 0 0 1 } } {{0.073577 0 0 0}
    {0 0.073577 0 0} {0 0 0.073577 0} {0 0 0 1}} {{1 0 0 0} {0 1 0 0}
    {0 0 1 0} {0 0 0 1}} }
        }

        user add subseparator Myoglobin

        # Turn on the backbone as a tube
        user add subitem Myoglobin {Backbone Tube} {
                mol color index
                mol selection protein
                mol representation tube 0
                mol addrep $mbco_molid
        }

        # turn on the Heme and the CO
        user add subitem Myoglobin {Heme and CO} {
                mol color name
                mol selection resname HEM
                mol representation licorice
                mol addrep $mbco_molid
                # get the FE as well
                mol selection resname HEM and name FE
                mol representation vdw 0.5
                mol addrep $mbco_molid
                # and the CO
                mol selection resname CO
                mol representation vdw 1.0
                mol addrep $mbco_molid
        }

        # turn on the two histidines near the heme
        user add subitem Myoglobin {HIS} {
                mol color resname
                mol selection resid 64 93
                mol representation lines
                mol addrep $mbco_molid
        }

        # show the myoglobin backbone in cylinders
        user add subitem Myoglobin {Cartoon} {
                mol color structure
                mol selection protein
                mol representation cartoon
                mol addrep $mbco_molid
        }
        user add subseparator Myoglobin

        # delete all the representations
        user add subitem Myoglobin {Delete Reps} {
                for {set i [molinfo $mbco_molid get numreps]} \
                                        {$i > 0} {incr i -1} {
                        mol delrep 0 $mbco_molid
                }
        }

 = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = =

                                The .vmdrc startup file

Finally, once you've defined all of these menus and hot keys, where
should you put them? The best place would be your .vmdrc . When VMD
starts up but just before control is passed back to the user, VMD
looks for that file in one of three locations, the local directory,
your home directory, and the main VMD installation directory. The
first file found is sourced, so a .vmdrc in the local directory
overrides the one in your home directory, etc.

As a hint to those that maintain VMD on their local site, if you want
to set up a local configuration file for others to use, make a file
(called, perhaps, .vmdrc.local) in the VMD installation directory.
Put the new commands in that file, and have those interested in
using the new commands add the line:

                source $env(VMDDIR)/.vmdrc.local

at the beginning of their own .vmdrc. Don't forget to add this line to
the installation version of .vmdrc as well.

 = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = =

                                                Andrew
                                                dalke_at_ks.uiuc.edu