Working with the Chimera Extension Manager

Chimera extensions typically can be divided into two parts: data manipulation and user interface. For example, the code in Toolbar Buttons defines a function which changes the display status of some atoms. This is the data manipulation part of that extension. The code also creates a toolbar button that invokes the function when pressed. This is the user interface part of the extension.

Data manipulation code may often be reused when building a new extension, but user interface code typically is not. Separating the parts into multiple source files simplifies reusing the data manipulation code, but complicates managing the extension as a unit. Fortunately, Python supports the package concept for just this purpose.

A Python package consists of a set of modules (.py files) stored in the same directory in the file system. One of the modules must be named __init__.py, which is the initialization module that is automatically executed when the package is imported. By convention, Chimera extension packages implement the data manipulation code in __init__.py. Implementors of new functionality can access the data manipulation code by:

import extension

where extension is the name of the package.

The package integrates its functionality into the Chimera extension manager by including a special module named ChimeraExtension.py in the package, and following a particular protocol within that module. Namely, for each separate function the package wants to offer through the extension manager, a class derived from chimera.extension.EMO (Extension Management Object) must be defined in the module and an instance registered with the extension manager.

The code in Toolbar Buttons is organized in such a manner below:

Example ToolbarButtonExtension/__init__.py

The contents of ToolbarButtonExtension/__init__.py is identical to the first section of code in Toolbar Buttons, with the exception that module os is not imported.

import re

import chimera

def mainchain():


MAINCHAIN = re.compile("^(N|CA|C)$", re.I)
for m in chimera.openModels.list(modelTypes=[chimera.Molecule]):


for a in m.atoms:


a.display = MAINCHAIN.match(a.name) != None


Example ToolbarButtonExtension/ChimeraExtension.py

ChimeraExtension.py derives a class from chimera.extension.EMO to define how functionality defined in __init__.py may be invoked by the Chimera extension manager.

import chimera.extension


Class MainChainEMO is the derived class.
class MainChainEMO(chimera.extension.EMO):


Return the actual name of the extension.
def name(self):


return 'Backbone'


Return the short description that typically appears as balloon help or in the Tools preference category.
def description(self):


return 'display only protein backbone'


Return the categories in which this extension should appear. It is either a list or a dictionary. If it is a dictionary then the keys are the category names and the values are category-specific descriptions (and the description() method above is ignored).
def categories(self):


return ['Utilities']


Return the name of a file containing an icon that may be used on the tool bar to provide a shortcut for launching the extension.
def icon(self):


return self.path('mainchain.tiff')


Invoke the extension. Note that when this method is called, the content of "__init__.py" is not available. To simplify calling functions, the EMO provides a module method that locates modules in the extension package by name; if no name is supplied, the "__init__.py" module is returned.
def activate(self):


Call the mainchain function in the "__init__.py" module.
self.module().mainchain()


Register an instance of MainChainEMO with the Chimera extension manager.
chimera.extension.manager.registerExtension(MainChainEMO(__file__))


Running the Example

The example code files and ToolbarButton.tiff must be saved in a directory named ToolbarButtonExtension. To run the example, start chimera, bring up the Tools preference category (via the Preferences entry in the Favorites menu; then choosing the "Tools" preference category), use the Add button to add the directory above the ToolbarButtonExtension directory. A MainChain entry should appear under the Utilities tools category.