Introduction to the gfx Module

For the course of this tutorial, we assume that you have DNG up and running.

As already mentioned in the Introduction to the mol Module, the basic representation of molecular structures, sequences, images are completely independent from the graphical rendering. Thus, to display it on the screen, we first have to create a graphical representation of the object. This is illustrated for the entity below, but follows a similar scheme for density maps, surfaces and other types of data.

pdb = io.LoadPDB('/path/to/molecule.pdb')
go = gfx.Entity('PROTEIN', pdb)

The last command is not mandatory, but very convenient to center the camera on the object.

The Scene

The scene is the central registry for graphical objects and manages rendering parameters. Among other parameters, it is used to setup the lighting, fog, background color and the camera. The scene is a singleton, meaning that there is only one scene available. The instance can be accessed via gfx.Scene(). Because the scene is so important and commonly used, the scene is also available as the scene variable in the interactive python shell as well as from scripts. In fact, this is the preferred way to use functionality of the scene. As an easy example, let’s change the background color:


Now, the color of the screen has changed to white. To set it back to black, simply assign gfx.BLACK to the background property.

Objects are added to the scene by calling Scene.Add(). Once added to the scene, the objects will be rendered automatically. Since all the graphical objects have a name that identifies them, they can be retrieved by name and manipulated:

# retrieving the previously added protein
obj = scene['PROTEIN']
# set color of the protein to red

The last command assigns a uniform red color to all atoms.

The Graphical Entity

Now let’s look at the graphical entity in more detail. The graphical entity is responsible for the rendering of EntityHandle and EntityView instances.

Render Modes

Molecules are rendered in different representations. Some representations show the structure at atomic detail (connectivity level display styles), while others simplify the structure significantly (trace-based display styles).

To change the display mode of an entity programmatically, use the Entity.SetRenderMode() method:

# render the molecule with an interpolated line trace
# switch back to simple line rendering
# switch to helix-strand-coil cartoon

It is also possible to change the render mode of only a part of the structure. To display the ligand with balls and sticks and everything else in cartoon mode, we make use of the query language to select everything that is not part of the protein. Remember from above, that we stored our molecule in the pdb variable.

not_protein = pdb.Select('peptide=false')
obj.SetRenderMode(gfx.CUSTOM, not_protein)

The Basics of Coloring

The color of each atom can be set individually. The simplest coloring scheme is to set all atoms to the same color:


Assigning colors based on selections is also possible. To reproduce the well-known CPK coloring, 4 consecutive coloring operations are sufficient:

obj.SetColor(gfx.WHITE, 'ele=C')
obj.SetColor(gfx.BLUE, 'ele=N')
obj.SetColor(gfx.RED, 'ele=O')
obj.SetColor(gfx.YELLOW, 'ele=S')

But because this is such a common task, the entity provides a built-in method to color the atoms by element:


As already seen above, the coloring operations can be chained to achieve the desired effect. For example, sometimes one wants to apply conventional CPK coloring to the protein and then change the color of C-alpha atoms to pink:

obj.SetColor(gfx.Color(1, 0, 1), 'aname=CA and ele=C')

Internally, the chain of calls to the coloring methods is stored as a list of coloring operations that is reapplied sequentially. This makes sure that the coloring remains when changing render modes or updating the geometry of the molecule. This storage scheme has one drawback. Consider the following code:

for i in range(100):

While the code obviously achieves the desired effect, it is far from optimal because all of the 100 color operations are applied every time the graphical entity needs an update. When you see a slow down in rendering after playing around with the coloring operations, consider calling Entity.ClearColorOps() and reapply only the set of coloring operations that are required to achieve your rendering.

Coloring the Entity By Property

The most complex but also most powerful coloring method is Entity.ColorBy(), which allows to color atoms by a numeric property. This property can either be a built-in property such as atomic b-factor, charge, residue number or be custom properties assigned by the user or an algorithm and be defined at any level (chain, residue, atom). The naming of the built-in properties is identical to the properties available in query language. For example, to achieve a heat-map coloring for b-factors:

# will color the atoms by the atomic b-factor, setting atoms with
# a temperature factor of 0 to blue and atoms with a temperature factor of
# 100 and higher to red. Values in between are linearly interpolated.
obj.ColorBy('abfac', gfx.BLUE, gfx.RED, 0, 100)

Fine-tuning the Coloring

The HSC render mode uses two colors to color the secondary structure elements. The main color affects the top and bottom of extended and the outside of helical elements. The detail color is used for the inner side of helices and the rim of extended elements. This color is changed with Entity.SetDetailColor().


Enter search terms or a module, class or function name.


Documentation is available for the following OpenStructure versions:

(Currently viewing dev) / 2.8 / 2.7 / 2.6 / 2.5 / 2.4 / 2.3.1 / 2.3 / 2.2 / 2.1 / 2.0 / 1.9 / 1.8 / 1.7.1 / 1.7 / 1.6 / 1.5 / 1.4 / 1.3 / 1.2 / 1.11 / 1.10 / 1.1

This documentation is still under heavy development!
If something is missing or if you need the C++ API description in doxygen style, check our old documentation for further information.