GLModel

GLModel represents a group of related atoms

Constructor

new GLModel()

Classes

GLModel

Methods

addAtomSpecs(customAtomSpecs)

add atomSpecs to validAtomSelectionSpecs

Parameters:
NameTypeDescription
customAtomSpecsArray

array of strings that can be used as atomSelectionSpecs
this is to prevent the 'Unknown Selector x' message on the console for the strings passed.
These messages are no longer generated as, in theory, typescript will catch problems at compile time.
In practice, there may still be issues at run-time but we don't check for them...

What we should do is use something like https://github.com/woutervh-/typescript-is to do runtime
type checking, but it currently doesn't work with our types...

Deprecated
  • Yes

addAtoms(newatoms)

Add list of new atoms to model. Adjusts bonds appropriately.

Parameters:
NameTypeDescription
newatomsArray.<AtomSpec>
Example
var atoms = [{elem: 'C', x: 0, y: 0, z: 0, bonds: [1,2], bondOrder: [1,2]}, {elem: 'O', x: -1.5, y: 0, z: 0, bonds: [0]},{elem: 'O', x: 1.5, y: 0, z: 0, bonds: [0], bondOrder: [2]}];

        viewer.setBackgroundColor(0xffffffff);
        var m = viewer.addModel();
        m.addAtoms(atoms);
        m.setStyle({},{stick:{}});
        viewer.zoomTo();
        viewer.render();

addFrame(atoms)

Add atoms as frames of model

Parameters:
NameTypeDescription
atomsArray.<AtomSpec>

atoms to be added

addMolData(data, format, options)

add atoms to this model from molecular data string

Parameters:
NameTypeDescription
datastring | ArrayBuffer

atom structure file input data string, for gzipped input use ArrayBuffer

formatstring

input file string format (e.g 'pdb', 'sdf', 'sdf.gz', etc.)

optionsParserOptionsSpec

format dependent options. Attributes depend on the input format

addPropertyLabels(prop, sel, viewer, options)

Create labels for atoms that show the value of the passed property.

Parameters:
NameTypeDescription
propString

property name

selAtomSelectionSpec
viewerGLViewer
optionsLabelSpec

addResLabels(sel, viewer, options, byframe)

Create labels for residues of selected atoms.
Will create a single label at the center of mass of all atoms
with the same chain,resn, and resi.

Parameters:
NameTypeDescription
selAtomSelectionSpec
viewerGLViewer
optionsLabelSpec
byframeboolean

if true, create labels for every individual frame, not just current; frames must be loaded already

assignBonds()

Assign bonds based on atomic coordinates.
This currently uses a primitive distance-based algorithm that does not
consider valence constraints and will only create single bonds.

atomIsSelected(atom, sel) → {boolean}

given a selection specification, return true if atom is selected.
Does not support context-aware selectors like expand/within/byres.

Parameters:
NameTypeDescription
atomAtomSpec
selAtomSelectionSpec
Returns:
Type: 
boolean

createMolObj()

param {AtomSpec[]} atoms

drawAtomClickSphere()

Register atom shaped click handlers

drawAtomCross(atom, geos)

Parameters:
NameTypeDescription
atomAtomSpec
geosRecord.<number, Geometry>

drawAtomSphere(atom, geo)

Parameters:
NameTypeDescription
atomAtomSpec
geoGeometry

drawBondLines(atom, atoms, geos)

Parameters:
NameTypeDescription
atomAtomSpec
atomsArray.<AtomSpec>
geosRecord.<number, Geometry>

enableContextMenu(sel, contextMenuEnabled)

enable context menu of selected atoms

Parameters:
NameTypeDescription
selAtomSelectionSpec

atom selection to apply hoverable settings to

contextMenuEnabledboolean

whether contextMenu-handling is enabled for the selection

expandAtomList()

returns a list of atoms in the expanded bounding box, but not in the current one

Bounding box:

[ [ xmin, ymin, zmin ],
[ xmax, ymax, zmax ],
[ xctr, yctr, zctr ] ]

exportVRML()

return a VRML string representation of the model. Does not include VRML header information

Returns:

VRML

getCrystData()

Returns crystallographic information if present.

getID() → {number}

Returns model id number

Returns:

Model ID

Type: 
number

getInternalState()

Return object representing internal state of
the model appropriate for passing to setInternalState

getNumFrames() → {number}

Returns model's frames property, a list of atom lists

Returns:
Type: 
number

getRadiusFromStyle(atom, style) → {number}

Parameters:
NameTypeDescription
atomAtomSpec
styleatomstyle
Returns:
Type: 
number

getSymmetries() → {Array.<Matrix4>}

Returns list of rotational/translational matrices if there is BIOMT data
Otherwise returns a list of just the ID matrix

Returns:
Type: 
Array.<Matrix4>

globj(group, Object)

manage the globj for this model in the possed modelGroup - if it has to be regenerated, remove and add

Parameters:
NameTypeDescription
groupObject3D
Object

options

hide()

Don't show this model in future renderings. Keep all styles and state
so it can be efficiencly shown again.

  • @see GLModel#show
Example
$3Dmol.download("pdb:3ucr",viewer,{},function(){
        viewer.setStyle({},{stick:{}});
        viewer.getModel().hide();
        viewer.render();
        });

removeAtoms(badatoms)

Remove specified atoms from model

Parameters:
NameTypeDescription
badatomsArray.<AtomSpec>

list of atoms

removegl(group)

Remove any renderable mol object from scene

Parameters:
NameTypeDescription
groupObject3D

selectedAtoms(sel) → {Array.<Object>}

return list of atoms selected by sel, this is specific to glmodel

Parameters:
NameTypeDescription
selAtomSelectionSpec
Returns:
Type: 
Array.<Object>
Example
$3Dmol.download("pdb:4wwy",viewer,{},function(){
              var atoms = viewer.selectedAtoms({chain:'A'});
              for(var i = 0, n = atoms.length; i < n; i++) {
                 atoms[i].b = 0.0;
              }
              viewer.setStyle({cartoon:{colorscheme:{prop:'b',gradient: 'roygb',min:0,max:30}}});
              viewer.render();
          });

setClickable(sel, clickable, callback)

Set clickable and callback of selected atoms

Parameters:
NameTypeDescription
selAtomSelectionSpec

atom selection to apply clickable settings to

clickableboolean

whether click-handling is enabled for the selection

callbackfunction

function called when an atom in the selection is clicked

setColorByElement(sel, colors)

given a mapping from element to color, set atom colors

Parameters:
NameTypeDescription
selAtomSelectionSpec
colorsobject

setColorByFunction(sel, func)

Parameters:
NameTypeDescription
selAtomSelectionSpec

selection object

funcfunction

function to be used to set the color

Deprecated
  • use setStyle and colorfunc attribute
Example
$3Dmol.download("pdb:4UAA",viewer,{},function(){
              viewer.setBackgroundColor(0xffffffff);
              var colorAsSnake = function(atom) {
                return atom.resi % 2 ? 'white': 'green'
              };

              viewer.setStyle( {}, { cartoon: {colorfunc: colorAsSnake }});

              viewer.render();
          });

setColorByProperty(sel, prop, scheme)

Parameters:
NameTypeDescription
selAtomSelectionSpec
propstring
schemeGradient | string

setCoordinates(str, format)

Set coordinates for the atoms from provided trajectory file.

Parameters:
NameTypeDescription
strstring | ArrayBuffer

contains the data of the file

formatstring

contains the format of the file (mdcrd, inpcrd, pdb, netcdf, or array). Arrays should be TxNx3 where T is the number of timesteps and N the number of atoms.

Example
let m = viewer.addModel()  //create an empty model
         m.addAtoms([{x:0,y:0,z:0,elem:'C'},{x:2,y:0,z:0,elem:'C'}]) //provide a list of dictionaries representing the atoms
         viewer.setStyle({'sphere':{}})
         m.setCoordinates([[[0.0, 0.0, 0.0], [2.0, 0.0, 0.0]], [[0.0, 0.0, 0.0], [2.8888888359069824, 0.0, 0.0]], [[0.0, 0.0, 0.0], [3.777777671813965, 0.0, 0.0]], [[0.0, 0.0, 0.0], [4.666666507720947, 0.0, 0.0]], [[0.0, 0.0, 0.0], [5.55555534362793, 0.0, 0.0]], [[0.0, 0.0, 0.0], [6.44444465637207, 0.0, 0.0]], [[0.0, 0.0, 0.0], [7.333333492279053, 0.0, 0.0]], [[0.0, 0.0, 0.0], [8.222222328186035, 0.0, 0.0]], [[0.0, 0.0, 0.0], [9.11111068725586, 0.0, 0.0]], [[0.0, 0.0, 0.0], [10.0, 0.0, 0.0]]],'array');
         viewer.animate({loop: "forward",reps: 1});
         viewer.zoomTo();
         viewer.zoom(0.5);
         viewer.render();

setCoordinatesFromURL(url, path) → {Promise}

Set coordinates from remote trajectory file.

Parameters:
NameTypeDescription
urlstring

contains the url where mdsrv has been hosted

pathstring

contains the path of the file (/filename)

Returns:
Type: 
Promise

setCrystData(a, b, c, alpha, beta, gamma)

Set crystallographic information using three angles and three lengths

Parameters:
NameTypeDescription
anumber

length of unit cell side

bnumber

length of unit cell side

cnumber

length of unit cell side

alphanumber

unit cell angle in degrees (default 90)

betanumber

unit cell angle in degrees (default 90)

gammanumber

unit cell angle in degrees (default 90)

setCrystMatrix(matrix)

Set the crystallographic matrix to the given matrix.

This function removes a, b, c, alpha, beta, gamma from
the crystal data.

Parameters:
NameTypeDescription
matrixMatrix3

unit cell matrix

setFrame(framenum) → {Promise}

Sets model's atomlist to specified frame
Sets to last frame if framenum out of range

Parameters:
NameTypeDescription
framenumnumber

model's atoms are set to this index in frames list

Returns:
Type: 
Promise

setHoverable(sel, hoverable, hover_callback, unhover_callback)

Set hoverable and callback of selected atoms

Parameters:
NameTypeDescription
selAtomSelectionSpec

atom selection to apply hoverable settings to

hoverableboolean

whether hover-handling is enabled for the selection

hover_callbackfunction

function called when an atom in the selection is hovered over

unhover_callbackfunction

function called when the mouse moves out of the hover area

setInternalState(state)

Overwrite the internal model state with the passed state.

Parameters:
NameTypeDescription
state

setStyle(sel, style, add)

Set atom style of selected atoms

Parameters:
NameTypeDescription
selAtomSelectionSpec
styleAtomStyleSpec
addboolean

if true, add to current style, don't replace

Example
$3Dmol.download("pdb:4UB9",viewer,{},function(){
              viewer.setBackgroundColor(0xffffffff);

              viewer.setStyle({chain:'A'},{line:{hidden:true,colorscheme:{prop:'b',gradient: new $3Dmol.Gradient.Sinebow($3Dmol.getPropertyRange(viewer.selectedAtoms(),'b'))}}});
              viewer.setStyle({chain:'B'},{line:{colorscheme:{prop:'b',gradient: new $3Dmol.Gradient.Sinebow($3Dmol.getPropertyRange(viewer.selectedAtoms(),'b'))}}});
              viewer.setStyle({chain:'C'},{cross:{hidden:true,colorscheme:{prop:'b',gradient: new $3Dmol.Gradient.Sinebow($3Dmol.getPropertyRange(viewer.selectedAtoms(),'b'))}}});
              viewer.setStyle({chain:'D'},{cross:{colorscheme:{prop:'b',gradient: new $3Dmol.Gradient.RWB($3Dmol.getPropertyRange(viewer.selectedAtoms(),'b'))}}});
              viewer.setStyle({chain:'E'},{cross:{radius:2.0,colorscheme:{prop:'b',gradient: new $3Dmol.Gradient.RWB($3Dmol.getPropertyRange(viewer.selectedAtoms(),'b'))}}});
              viewer.setStyle({chain:'F'},{stick:{hidden:true,colorscheme:{prop:'b',gradient: new $3Dmol.Gradient.RWB($3Dmol.getPropertyRange(viewer.selectedAtoms(),'b'))}}});
              viewer.setStyle({chain:'G'},{stick:{radius:0.8,colorscheme:{prop:'b',gradient: new $3Dmol.Gradient.ROYGB($3Dmol.getPropertyRange(viewer.selectedAtoms(),'b'))}}});
              viewer.setStyle({chain:'H'},{stick:{singleBonds:true,colorscheme:{prop:'b',gradient: new $3Dmol.Gradient.ROYGB($3Dmol.getPropertyRange(viewer.selectedAtoms(),'b'))}}});
              viewer.render();
          });

setSymmetries(list)

Sets symmetries based on specified matrices in list

Parameters:
NameTypeDescription
listArray.<Matrix4>

show()

Unhide a hidden model

Example
$3Dmol.download("pdb:3ucr",viewer,{},function(){
        viewer.setStyle({},{stick:{}});
        viewer.getModel().hide();
        viewer.render(  )
        viewer.getModel().show()
        viewer.render();
        });

toCDObject(whether) → {Object}

Convert the model into an object in the format of a ChemDoodle JSON model.

Parameters:
NameTypeDescription
whetherboolean

or not to include style information. Defaults to false.

Returns:
Type: 
Object

vibrate(numFrames, amplitude, bothWays, viewer, arrowSpec)

If model atoms have dx, dy, dz properties (in some xyz files), vibrate populates the model's frame property based on parameters.
Model can then be animated

Parameters:
NameTypeDescription
numFramesnumber

number of frames to be created, default to 10

amplitudenumber

amplitude of distortion, default to 1 (full)

bothWaysboolean

if true, extend both in positive and negative directions by numFrames

viewerGLViewer

required if arrowSpec is provided

arrowSpecArrowSpec

specification for drawing animated arrows. If color isn't specified, atom color (sphere, stick, line preference) is used.

Example
$3Dmol.download("pdb:4UAA",viewer,{},function(){
        viewer.setStyle({},{stick:{}});
        viewer.vibrate(10, 1);
        viewer.animate({loop: "forward",reps: 1});

        viewer.zoomTo();
              viewer.render();
          });