Last updated September 4, 2003. The most recent copy of the FAQ is at http://www.cgl.ucsf.edu/chimera/docs/ProgrammersGuide/faq.html
The Chimera Programmer's Reference manual is automatically generated from comments in the code and is not of much use. The Programming Examples are a good source of information. The C++ header files for the Chimera objects are useful but are not currently distributed. You can request the header files from chimera-dev@cgl.ucsf.edu. The archived Chimera development mailing list is at http://www.cgl.ucsf.edu/pipermail/chimera-dev.
Commands available at the type-in command line are almost all implemented in the Midas module's __init__.py file. You can use the commands for convenience in implementing the same functionality in your extension. For example, to color iron atoms red:
import Midas
Midas.color('red', '@/element=Fe')
A few commands related to processing command text (e.g. handling files of commands) are in Midas.midas_text. One in particular, makeCommand(), allows you to use command-line syntax directly instead of determining the proper arguments to a Midas module function. So the above example of coloring atoms red would look like this using makeCommand():
import Midas
from Midas.midas_text import makeCommand
exec makeCommand("color red @/element=Fe")
Camera always points in -z direction. There is no way to rotate it.
>>> v = chimera.viewer >>> c = v.camera >>> print c.center (5.9539999961853027, -2.186500072479248, 10.296500205993652) >>> c.center = (3, 2.5, 10) # to translate camera >>> v.scaleFactor = 1.5 # to zoom camera
The Xform object model.openState.xform gives the rotation and translation for a model.
>>> om = chimera.openModels >>> mlist = om.list() >>> m = mlist[0] >>> xf = chimera.Xform() >>> axis = chimera.Vector(1, 0, 0) >>> angle = 90 # degrees >>> xf.rotate(axis, angle) >>> print m.openState.xform # 3x3 rotation matrix # last column is translation 0.982695 0.121524 0.139793 -1.07064 0.0250348 0.660639 -0.750287 6.83425 -0.183531 0.740803 0.646164 6.35578 >>> m.openState.globalXform(xf)
Another method to change the transform
>>> xf.premultiply(m.openState.xform) # changes xf >>> m.openState.xform = xf
To rotate relative to data axes use
>>> m.openState.localXform(xf)
or
>>> xf.multiply(m.openState.xform) # changes xf >>> m.openState.xform = xf
import Midas Midas.copy(file='/home/goddard/hoohoo.png', format='PNG') # format can be 'PNG', 'BMP', 'EPS','GIF', 'JPEG', 'PDF', 'PPM', 'TIFF'
>>> xf = model.openState.xform # xf is a copy of the model's Xform matrix. >>> xf.zRotate(45) # This will not rotate the model.
>>> c = model.atoms[0].color # c is the MaterialColor object for the atom >>> c.ambientDiffuse = (1,0,0) # The Atom color changes immediately to red.
Some Chimera objects returned as attributes are always copies, some are always references to the uncopied object. Objects that are always copied include Xform, Vector, Point, BBox, Element, MolResId, Coord, .... Objects that are never copied include Atom, Bond, PseudoBond, CoordSet, Molecule, Residue, RibbonStyle, .... These objects that are not copied do not have any any method for copying them. In order to know if an object type is passed by value is to look at the Chimera C++ header files. Classes without a WrapPy base class are copied. Those with a WrapPy base class are not copied. This base class is part of the C++ to Python interface generation.
Volume viewer isosurfaces are Surface_Model objects defined by the _surface.so C++ module. The Surface_Model interface is given in the surfmodel.h source code file. By default these surfaces use OpenGL (1,1-alpha) blending. This means the color for a triangle is added to an image plus the transparency (= 1-alpha) times the color from triangles in back of this one. As the transparency becomes greater, the brightness of the triangle does not diminish. In fact, more shows through from behind the triangle so it appears brighter. The specular highlights stay bright even if the triangle is black and fully tranparent. In Chimera 1730 a Surface_Model attribute transparency_blend_mode was added to allow the more common (alpha,1-alpha) blend mode. This is like the above mode but the triangle color is multiplied by alpha before being added to the image. For highly transparent triangles alpha is close to zero, and the triangle and specular highlights become dim.
MSMS molecular surface models use (alpha, 1-alpha) blending. They also use a 2 pass algorithm which is faster than sorting all the triangles by depth, but gives the strictly correct appearance only when the viewer looks through at most 2 surface layers.
VRML models use (alpha,1) blending. That is they multiply triangle color by alpha, but add in all of the color from triangles further back without reducing it by the transparency factor. This is like complete transparency, where the triangle colors are just scaled by the alpha value. This is horrible looking unless you want complete transparency.
The Chimera architecture only correctly displays transparency when at most one transparent model is shown. Any number of opaque models can also be shown. If two transparent models are shown, one will be drawn after the other. This will make one appear as if it is drawn entirely on top of another even if they in actuality intersect. The rearmost model, may in fact appear to be in front. This is because Chimera sorts the triangles by depth within a single model as needed for rendering transparency, but is not able to sort triangles by depth across multiple models.
The openState attribute of a Model controls whether that model
is active for motion ('.active'), and contains the model's
transformation matrix ('.xform') and center of rotation
('.cofr'). Since some models must move in synchrony
(e.g. a molecule and its surface), OpenState instances may shared
among multiple models. If you create a model that needs a shared
openState with another model, then when adding your model
to the list of open models with chimera.openModels.add(),
you should use the 'sameAs' keyword to specify that other model.
In the 1700 release, Chimera uses a substantial amount of memory to hold molecular data, but does not have any large memory leaks to the best of our knowledge (i.e. as structures are closed their memory usage will be reclaimed). However, the memory is reclaimed by a task that runs during idle times, so therefore scripts that loop through many structures, opening and closing them, will have their memory use grow continuously until the script finishes. This will often cause the script to fail as the Chimera process runs out of memory.
You can cause the memory-reclamation task to run during your script by calling:
chimera.update.checkForChanges()
In post-1700 releases and snapshots, checkForChanges() is called automatically
when models are opened or closed, so you will not need to insert these
calls into your code.
11) Getting the size of a volume data set.
Here's some code to find the size of a volume data set.
import VolumeViewer d = VolumeViewer.volume_dialog() d0 = d.data_sets[0] # There may be more than one data set opened # You could look at each one's name (= file name) # to find the one you want. data = d0.data # This is a Grid_Data object defined in # VolumeData/griddata.py xsize, ysize, zsize = data.size