The Viewer

The 3D molecules are managed and rendered by an instance of the viewer class. It serves as the main entry point for the protein viewer and is where most of the action happens. In the following, the full API of Viewer() is described. The methods are roughly categorized into the following sections:

Initialization and Configuration

class pv.Viewer(parentElement[, options])

Construct a new viewer, inserting it as the last child of parentElement. options is as dictionary that allows to control the initial settings for the viewer. Many of these settings can be changed later. The default options are chosen very restrictive on purpose. Valid options are:

  • width The width (in pixels) of the viewer. The special value ‘auto’ can be used to set the width to the width of the parent element. Defaults to 500.
  • height The height (in pixels) of the viewer. The special value ‘auto’ can be used to set the height to the height of the parent element. Defaults to 500.
  • antialias: whether full-scene antialiasing should be enabled. When available, antialiasing will use the built-in WebGL antialiasing. When not, it will fall back to a manual supersampling of the scene. Enabling antialiasing improve the visual results considerably, but also slows down rendering. When rendering speed is a concern, the antialias option should be set to false. Defaults to false.
  • quality the level of detail for the geometry. Accepted values are low, medium, and high. See quality() for a description of these values. Defaults to low.
  • slabMode sets the default slab mode for the viewer. See slabMode() for possible values. Defaults to ‘auto’.
  • background set the default background color of the viewer. Defaults to ‘white’. See Color Notations
  • atomDoubleClicked set the event handler for an atom double clicked event. When the parameter is a function it is added as a new ‘atomDoubleClicked’ event handler. See addListener() for details. If it is set to the special value ‘center’, an event listener is installed that centers the viewer on the double clicked atom, residue. The default is ‘center’.
  • atomClicked set the event handler for an atom double clicked event (see atomDoubleClicked). The default is null (no listener).
  • animateTime controls the default animation duration in milliseconds. By default, the animation is set to 0 (no animation). By setting it to higher values, rotation, zoom and shift are animated. Note that enabling this can have negative impact on performance, especially with large molecules and on low-end devices.
  • fog whether depth-cue (‘fog’) should be enabled. By default, fog is enabled. Pass false to disable fog.
  • fov the field of view in degrees. Default is 45 degrees.
  • outline whether outline rendering should be enabled. When enabled, outline rendering draws a uniformly colored outline around the mesh geometries to improve contrast. By default outline rendering is enabled.
  • outlineColor the color of the outline. Default is black. When outline rendering is disabled, setting this value has no effect.
  • outlineWidth the width of the outline in pixels. Default is 1.5. When outline rendering is disabled, setting this value has no effect.

The following code defines a new viewer. This can be done during page load time, before the DOMContentLoaded event has been emitted. Render objects can only be added once the DOMContentLoaded event has fired. Typically it’s best to put any object loading and display code into a DOMContentLoaded event handler.

// override the default options with something less restrictive.
var options = {
  width: 600,
  height: 600,
  antialias: true,
  quality : 'medium'
};
// insert the viewer under the Dom element with id 'gl'.
var viewer = pv.Viewer(document.getElementById('gl'), options);

viewer.on('viewerReady', function() {
  // add structure here
});
pv.Viewer.quality([value])

Gets (or sets) the default level of detail for the render geometry. This property sets the default parameters for constructing render geometry, for example the number of arcs that are used for tubes, or the number of triangles for one sphere. Accepted values are

  • low The geometry uses as few triangles as possible. This is the fastest, but also visually least pleasing option. Use this option, when it can be assumed that very large molecules are to be rendered.
  • medium provides a good tradeoff between visual fidelity and render speed. This options should work best for typical proteins.
  • high render the scene with maximum detail.

Changes to the quality only affect newly created objects/geometries. Already existing objects/geometries are not affected.

Rendering

This section describes the high-level API for displaying molecular structures on screen. The interface consists of render methods part of Viewer() which accept a name and a structure and create a graphical representation out of it. For example, to create a cartoon representation, the following code will do:

// creates a cartoon representation with standard parameters
var myCartoon = viewer.cartoon('molecule', myMolecule);

These methods will automatically add the object to the viewer, there is not need to call pv.Viewer.add() on the object.

pv.Viewer.lines(name, structure[, options])

Renders the structure (Mol(), or MolView()) at full connectivity level, using lines for the bonds. Atoms with no bonds are represented as small crosses. Valid options are:

  • color: the color operation to be used. Defaults to pv.color.byElement().
  • lineWidth: The line width for bonds and atoms. Defaults to 4.0
Returns:The geometry of the object.
pv.Viewer.points(name, structure[, options])

Renders the atoms of a structure (Mol(), or MolView()) as a point cloud. Valid options are:

  • color: the color operation to be used. Defaults to pv.color.byElement().
  • pointSize relative point size of the points to be rendered. Defaults to 1.0
Returns:The geometry of the object.
pv.Viewer.spheres(name, structure[, options])

Renders the structure (Mol(), or MolView()) at full-atom level using a sphere for each atom. Valid options are:

  • color: the color operation to be used. Defaults to pv.color.byElement().
  • sphereDetail: the number of horizontal and vertical arcs for the sphere. The default sphereDetail is determined by pv.Viewer.quality().
pv.Viewer.lineTrace(name, structure[, options])

Renders the protein part of the structure (Mol(), or MolView()) as a Carbon-alpha trace using lines. Consecutive carton alpha atoms are connected by a straight line. For a mesh-based version of the Carbon-alpha trace, see pv.Viewer.trace().

  • color: the color operation to be used. Defaults to uniform().
  • lineWidth: The line width for bonds and atoms. Defaults to 4.0
pv.Viewer.sline(name, structure[, options])

Renders the protein part of the structure (Mol(), or MolView()) as a smooth line trace. The Carbon-alpha atoms are used as the control points for a Catmull-Rom spline. For a mesh-based version of the smooth line trace, see pv.Viewer.tube().

  • color: the color operation to be used. Defaults to uniform().
  • lineWidth: The line width for bonds and atoms. Defaults to 4.0
  • strength: influences the magnitude of the tangents for the Catmull-Rom spline. Defaults to 0.5. Meaningful values are between 0 and 1.
  • splineDetail: Number of subdivision per Carbon alpha atom. The default value is is determined by pv.Viewer.quality().
pv.Viewer.trace(name, structure[, options])

Renders the structure (Mol(), or MolView()) as a carbon-alpha trace. Consecutive Carbon alpha atoms (CA) are connected by a cylinder. For a line-based version of the trace render style, see pv.Viewer.lineTrace(). Accepted options are:

  • color: the color operation to be used. Defaults to uniform().
  • radius: Radius of the tube. Defaults to 0.3.
  • arcDetail: number of vertices on the tube. The default is determined by pv.Viewer.quality().
  • sphereDetail number of vertical and horizontal arcs for the spheres.
pv.Viewer.tube(name, structure[, options])

Renders the structure (Mol(), or MolView()) as a smoothly interpolated tube.

  • color: the color operation to be used. Defaults to pv.color.bySS().
  • radius: Radius of the tube. Defaults to 0.3.
  • arcDetail: number of vertices on the tube. The default is determined by pv.Viewer.quality().
  • strength: influences the magnitude of the tangents for the Catmull-Rom spline. Defaults to 1.0. Meaningful values are between 0 and 1.
  • splineDetail number of subdivisions per Carbon-alpha atom. The default is termined by pv.Viewer.quality().
pv.Viewer.cartoon(name, structure[, options])

Renders the structure (Mol(), or MolView()) as a helix, strand coil cartoon. Accepted options are:

  • color: the color operation to be used. Defaults to pv.color.bySS().
  • radius: Radius of the tube profile. Also influences the profile thickness for helix and strand profiles. Defaults to 0.3.
  • arcDetail: number of vertices on the tube. The default is determined by pv.Viewer.quality().
  • strength: influences the magnitude of the tangents for the Catmull-Rom spline. Defaults to 1.0. Meaningful values are between 0 and 1.
  • splineDetail number of subdivisions per Carbon-alpha atom. The default is termined by pv.Viewer.quality().
pv.Viewer.renderAs(name, structure, mode[, options])

Function to render the structure in any of the supported render styles. This essentially makes it possible to write code that is independent of the particular chosen render style.

Arguments:
  • mode – One of ‘sline’, ‘lines’, ‘trace’, ‘lineTrace’, ‘cartoon’, ‘tube’, ‘spheres’, ballsAndSticks’
  • options – options dictionary passed to the chosen render mode. Refer to the documentation for the specific mode for a list of supported options.
Returns:

The created geometry object.

pv.Viewer.label(name, text, pos[, options])

Places a label with text at the given position in the scene

Arguments:
  • name – Uniquely identifies the label
  • text – The text to be shown
  • pos – An array of length 3 holding the x, y, and z coordinate of the label’s center.
  • options – Optional dictionary to control the font, text style and size of the label (see below)

Accepted options are:

  • font: name of the font. Accepted values are all HTML/CSS font families. Default is ‘Verdana’.
  • fontSize: the size of the font in pixels. Default is 24.
  • fontColor: the CSS color to be used for rendering the text. Default is black.
  • fontStyle the font style. Can by any combination of ‘italic’, ‘bold’. Default is ‘normal’.
Returns:the created label.
pv.Viewer.customMesh(name)

Creates a new object to hold user-defined collection of geometric shapes. For details on how to add shapes, see Drawing Geometric Shapes

Arguments:
  • name – uniquely identifies the custom mesh.
Returns:

A new pv.CustomMesh() instance.

Camera Positioning/Orientation

pv.Viewer.setCamera(rotation, center, zoom[, ms])

Function to directly set the rotation, center and zoom of the camera.

The combined transformation matrix for the camera is calculated as follows: First the origin is shifted to the center, then the rotation is applied, and lastly the camera is translated away from the center by the negative zoom along the rotated Z-axis.

Arguments:
  • rotation – Either a 4x4 or 3x3 matrix in the form of a one-dimensional array of length 16 or 9. It is up to the caller to ensure the matrix is a valid rotation matrix.
  • center – the new camera center.
  • zoom – distance of the eye position from the viewing center
  • ms – if provided and non-zero defines the animation time for moving/rotating/zooming the camera from the current position to the new rotation,center and zoom. If zero, the rotation/center and zoom factors are directly set to the desired values. The default is zero.
pv.Viewer.setRotation(rotation[, ms])

Function to directly set the rotation of the camera. This is identical to calling setCamera() with the current center and zoom values.

Arguments:
  • rotation – Either a 4x4 or 3x3 matrix in the form of a one-dimensional array of length 16 or 9. It is up to the caller to make sure the matrix is a rotation matrix.
  • ms – if provided and non-zero defines the animation time rotating the camera from the current rotation to the target rotation. If zero, the rotation is immediately set to the target rotation. The default is zero.
pv.Viewer.setCenter(center[, ms])

Function to directly set the center of view of the camera. This is identical to calling setCamera() with the current rotation and zoom values.

Arguments:
  • center – The new center of view of the “center”.
  • ms – if provided and non-zero defines the time in which the camera center moves from the current center the target center. If zero, the center is immediately set to the target center. The default is zero.
pv.Viewer.setZoom(zoom[, ms])

Function to directly set the zoom factor of the camera. This is identical to calling setCamera() with the current rotation and center values.

Arguments:
  • zoom – The distance of the camera from the “center”. Only positive values are allowed.
  • ms – if provided and non-zero defines the time in which the camera zoom level moves from thecurrent zoom level to the target zoom. If zero, the zoom is immediately set to the target zoom. The default is zero.
pv.Viewer.centerOn(obj)

Center the camera on a given object, leaving the zoom level and orientation untouched.

Arguments:
  • obj – Must be an object implementing a center method returning the center of the object, e.g. an instance of pv.mol.MolView(), pv.mol.Mol()
pv.Viewer.autoZoom()

Adjusts the zoom level such that all objects are visible on screen and occupy as much space as possible. The center and orientation of the camera are not modified.

pv.Viewer.fitTo(obj)

Adjust the zoom level and center of the camera to fit the viewport to a given object. The method supports fitting to selections, or arbitrary SceneNodes. To fit to a subset of atoms, pass the selection as the obj argument:

viewer.fitTo(structure.select({rname : 'RVP'});

To fit to an entire render objects, pass the object as the obj argument:

var obj = viewer.cartoon('obj', structure);
viewer.fitTo(obj);
Arguments:
pv.Viewer.spin(enable)
pv.Viewer.spin(speed[, axis])

Enable/disable spinning of the viewer around a screen axis.

The first signature enables/disables spinning with default parameters, the second allows to control the speed as well as the axis to rotate around.

Arguments:
  • enable – whether spinning should be enabled. When false, spinning is disabled. When true, spinning is enabled around the y axis with a default speed of Math.PI/8, meaning a full rotation takes 16 seconds.
  • axis – 3 dimensional axis to rotate around. The axes are in the screen coordinate system, meaning the X- and Y-axes are aligned to the screen’s X and Y axes and the Z axis points towards the camera’s eye position. The default rotation axis is [0,1,0]. The axis must be normalized.
  • speed – The number of radians per second to rotate. When positive, rotation is in counter-clockwise direction, when negative rotation is in clockwise direction.
Returns:

true when spinning is enabled, false if not.

Fog and Slab Modes

Proteins come in all sizes and shapes. For optimal viewing, some camera parameters must thus be adjusted for each molecule. Two of these parameters are the near and far clipping planes of the camera. Only geometry between the near and far clipping plane are visible on the screen. Geometry in front of the near and at the back of the far clipping planes are clipped away. Typically, the near and far clipping planes must be set such that contain all visible geometry in front of the camera. However, sometimes it is desired to only show a certain ‘slab’ of the molecule. To support both of these scenarios, PV has multiple modes, called slab modes.

pv.Viewer.slabMode(mode[,options)

Sets the current active slab mode of the viewer. mode must be one of ‘fixed’ or ‘auto’.

  • When slab mode is set to ‘auto’, the near and far clipping planes as well as fog are adjusted based on the visible geometry. This causes the clipping planes to be updated on every rotation of the camera, change of camera’s viewing center and when objects are added/removed.

  • When the slab mode is set to ‘fixed’, automatic adjustment of the near and far clipping planes as well as fog is turned off. The values are kept constant and can be set by the user. To set specific near and far clipping planes provide them in a dictionary as the option argument when calling slabMode:

    viewer.slabMode('fixed', { near: 1, far : 100 });
    

Viewer Events

Custom viewer event handlers can be registered by calling pv.Viewer.addListener(). These callbacks have the following form.

pv.Viewer.addListener(type, callback)
pv.Viewer.on(type, callback)
Arguments:
  • type – The type of event to listen to. Must be either ‘atomClicked’, ‘atomDoubleClicked’, or ‘viewerReady’.

When an event fires, callbacks registered for that event type are invoked with type-specific arguments. See documentation for the individual events for more details

Initialization Event (viewerReady)

Invoked when the viewer is completely initialized and is ready for displaying of structures. It’s recommended to put calls to any of the geometry-creating funtions into a viewerReady callback as they expect a completely constructed viewer. It’s however possible to start loading the structure data before ‘viewerReady’, as long as they are not added to the viewer.

Callbacks receive the initialized viewer as the first argument.

When the ‘viewerReady’ callback is registered after the page has finished loading, the event callback is directly invoked from addListener/on.

The following code example shows how to add a yellow sphere to the center of the scene:

// insert the viewer under the Dom element with id 'gl'.
var viewer = pv.Viewer(document.getElementById('gl'), options);

viewer.on('viewerReady', function(viewer) {
  var customMesh = viewer.customMesh('yellowSphere');
  customMesh.addSphere([0,0,0], 5, { color : 'yellow' });
});

Mouse Interaction Events (click, doubleClick)

Mouse selection events are fired when the user clicks or double clicks on the viewer.

The arguments of the callback function are picked, and originalEvent which is the original mouse event. Picked contains information about the scene nodes that was clicked/doubleClicked as well as target of the event. For representations of molecules, the target is always an atom, for custom meshes target is set to the user-specified data stored in the mesh when calling addTube(), or addSphere(). When no object was under the cursor, picked is null.

It also contains a transformation matrix, that if set needs to be applied to the atom’s position to get the correct position in global coordinates. This is illustrated in the second example below.

The following code simply logs the clicked atom to the console when an atom is clicked and does nothing otherwise.

viewer.addListener('click', function(picked) {
  if (picked === null) return;
  var target = picked.target();
  if (target.qualifiedName !== undefined) {
    console.log('clicked atom', target.qualifiedName(), 'on object',
                picked.node().name());
  }
});

The following code shows how to listen for double click events to either make the selection the focal point and center of zoom, or zoom out to the whole structure if the background is double clicked.

var structure = .... // point to what you want the default background selection to view
viewer.on('doubleClick', function(picked) {
  if (picked === null) {
    viewer.fitTo(structure);
    return;
  }
  viewer.setCenter(picked.pos(), 500);
});

Object Management

Multiple render objects can be displayed at once. To be able to refer to these objects, all objects need to be assigned a name that uniquely identifies them. Viewer() offers methods to conveniently add, retrieve objects, or remove them from the viewer.

pv.Viewer.add(name, obj)

Add a new object to the viewer. The object’s name property will be set to name, under which it can be referenced in the future. Typically, there is no need to call add, since the objecs will be automatically added to the viewer when they are created.

Returns:A reference to obj.
pv.Viewer.get(name)

Retrieve the reference to an object that has previously been added to the viewer. When an object matching the name could be found, it is returned. Otherwise, null is returned.

pv.Viewer.hide(globPattern)
pv.Viewer.show(globPattern)

Hide/show objects matching glob pattern. The render geometry of hidden objects is retrained, but is not longer visible on the screen, nor are they available for object picking.

pv.Viewer.rm(globPattern)

Remove objects matching glob pattern from the viewer.