This document is for OpenStructure version 2.5, the latest version is 2.8 !

The Graphical Entity

Note

This document describes the API of the Entity and related classes. For an overview of the graphical entity, see Introduction to the gfx Module.

Render Modes

The entity supports different render modes. They are depicted in the following images together with the options they support. To change the render mode of the full entity or part of the entity, use the Entity.SetRenderMode() method.

Render Modes at the Connectivity Level

SIMPLE
../../_images/simple.png

Renders bonds as lines and single atoms as crosses.

CPK
../../_images/cpk.png

Renders atoms as spheres with radii proportional to their van der Waals radius.

CUSTOM
../../_images/custom.png

Render Modes at the Trace Level

TUBE
../../_images/tube.png

Renders a smooth backbone trace with circular profiles.

SLINE
../../_images/sline.png

Renders a smooth backbone trace with lines.

TRACE
../../_images/trace.png

Renders the Calpha atoms connected by tubes.

LINE_TRACE
../../_images/line_trace.png

Renders the Calpha connected by lines.

HSC
../../_images/hsc.png

Renders a helix/strand/coil cartoon.

Render Options

line_width

The line width. Defaults to 1.0

type:

float

aa_lines

Controls whether antialiased lines are enabled. Only available when compiled with shaders. Defaults to false.

type:

bool

draw_bond_order

Controls whether double/triple bonds are drawn as multiple lines. This requires that the bond order information has been assigned. As of now, only the RuleBasedBuilder assigns this information.

Defaults to off.

type:

bool

bond_order_distance

The distance between the lines depicting higher order bonds.

Loading and Displaying an Entity

This code examples shows how to load a structure and display it on the screen. It also shows how to programmatically combine different render modes in one graphical entity.

# remove all objects from scene, just in case
scene.RemoveAll()
# Load chain A of SDH
ent = io.LoadPDB('data/sdh.pdb', restrict_chains='A')

# create graphics object
go = gfx.Entity('SDH', ent)
# set rendermode of full graphical object to interpolated spline
go.SetRenderMode(gfx.SLINE)
# select sidechains (including bond to C-alpha and N in case of proline)
sidechains = ent.Select('aname!=CA,C,N,O', mol.EXCLUSIVE_BONDS)
# set rendering of sidechains to simple
go.SetRenderMode(gfx.SIMPLE, sidechains)

# add object to scene
scene.Add(go)

# center the scene on the geometric center of the SDH
scene.CenterOn(go)

print('Demo 1: loading and displaying a pdb file')

Entity API Reference

class Entity(name, entity)
class Entity(name, render_mode, entity)

Graphical representation of entities.

Parameters:
  • name (str) – Name of the entity.

  • render_mode – One of the Render Modes. Defaults to SIMPLE.

  • entity (EntityView, or EntityHandle) – The entity. Only atoms and bonds that part part of the entity view (or handle) are rendered.

name

The name of the entity. Read-only. Also available as GetName()

Type:

str

selection

The selection of the entity is rendered with a green halo. As a shortcut, the property an also be set as a string. The following two statements are identical:

go.selection = query
go.selection = go.view.Select(query)
Type:

EntityView

center

The geometric center of the graphical entity. Read-only.

Type:

Vec3

SetRenderMode(render_mode)
SetRenderMode(render_mode, view, keep=False)

Changes the render mode of the graphical entity. The first signature changes the render mode of all atoms and bonds, whereas the second only changes the display of atoms/bonds that are part of the view. If keep is set to false, the atoms and bonds that are part of the view will only be displayed in the new render mode. If keep is set to true, the atoms and bonds will be rendered with the new render mode in addition to whatever render mode they were rendered previously.

Parameters:
SetColor(color, selection='')

Sets the atoms matching the selection predicates to color.

Parameters:
  • color (Color) – The new color

  • selection (str) – A valid query

ColorByElement()

Apply CPK coloring coloring to atoms. This will color the carbon atoms in white, nitrogen in blue, oxygen in red, phosphorous in pink and sulfur in yellow.

ColorBy(prop, color1, color2, min, max, hint='U')
ColorBy(prop, color1, color2, hint='U')
ColorBy(prop, gradient, min, max, hint='U')
ColorBy(prop, gradient, hint='U')

Colors the entity by mapping a numeric property to a color. This property can be a built-in a property such as atomic b-factor, charge, residue number or be a custom property 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.

In case a generic property is undefined for a certain element, the property value of min is used for that element.

Parameters:
  • prop (str) – The name of the numeric property

  • color1 (Color) – Color corresponding to min value

  • color2 (Color) – Color corresponding to max value

  • gradient (Gradient) – The gradient to be used

  • hint (str) – When prop refers to a generic property, hint must be set to the hierarchy level at which the property is defined.

UpdatePositions()

Tells the graphical entity to update its vertex arrays. Use this function when you modified coordinates of the underlying EntityHandle and would like to see the changes on the screen.

See:

UpdateViews()

UpdateView()

Tells the graphical object to recalculate all views and vertex arrays. Use this function when you added new chains, residues, atoms or bonds to the entity and would like to see the changes on the screen.

See:

UpdatePositions()

Search

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

Contents

Documentation is available for the following OpenStructure versions:

dev / 2.8 / 2.7 / 2.6 / (Currently viewing 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.