3Dmol.js Documentation GLModel

# addAtomSpecs(customAtomSpecs)

add atomSpecs to validAtomSelectionSpecs

Parameters:

Name Type Description

Name	Type	Description
`customAtomSpecs`	`Array`	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...

customAtomSpecs

Array

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

View Source GLModel.ts, line 3060

# addAtoms(newatoms)

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

Parameters:

Name	Type	Description
`newatoms`	`Array.<AtomSpec>`

View Source GLModel.ts, line 2846

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:

Name	Type	Description
`atoms`	`Array.<AtomSpec>`	atoms to be added

View Source GLModel.ts, line 2756

# addMolData(data, format, options)

add atoms to this model from molecular data string

Parameters:

Name	Type	Description
`data`	`string` \| `ArrayBuffer`	atom structure file input data string, for gzipped input use ArrayBuffer
`format`	`string`	input file string format (e.g 'pdb', 'sdf', 'sdf.gz', etc.)
`options`	`ParserOptionsSpec`	format dependent options. Attributes depend on the input format

View Source GLModel.ts, line 2788

# addPropertyLabels(prop, sel, viewer, options)

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

Parameters:

Name	Type	Description
`prop`	`String`	property name
`sel`	`AtomSelectionSpec`
`viewer`	`GLViewer`
`options`	`LabelSpec`

View Source GLModel.ts, line 3008

# 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:

Name	Type	Description
`sel`	`AtomSelectionSpec`
`viewer`	`GLViewer`
`options`	`LabelSpec`
`byframe`	`boolean`	if true, create labels for every individual frame, not just current; frames must be loaded already

View Source GLModel.ts, line 3020

# 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:

Name	Type	Description
`atom`	`AtomSpec`
`sel`	`AtomSelectionSpec`

View Source GLModel.ts, line 2798

Returns:

Type: boolean

# createMolObj()

param {AtomSpec[]} atoms

View Source GLModel.ts, line 877

# drawAtomClickSphere()

Register atom shaped click handlers

View Source GLModel.ts, line 458

# drawAtomCross(atom, geos)

Parameters:

Name	Type	Description
`atom`	`AtomSpec`
`geos`	`Record.<number, Geometry>`

View Source GLModel.ts, line 156

# drawAtomSphere(atom, geo)

Parameters:

Name	Type	Description
`atom`	`AtomSpec`
`geo`	`Geometry`

View Source GLModel.ts, line 442

# drawBondLines(atom, atoms, geos)

Parameters:

Name	Type	Description
`atom`	`AtomSpec`
`atoms`	`Array.<AtomSpec>`
`geos`	`Record.<number, Geometry>`

View Source GLModel.ts, line 297

# enableContextMenu(sel, contextMenuEnabled)

enable context menu of selected atoms

Parameters:

Name	Type	Description
`sel`	`AtomSelectionSpec`	atom selection to apply hoverable settings to
`contextMenuEnabled`	`boolean`	whether contextMenu-handling is enabled for the selection

View Source GLModel.ts, line 2903

# 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 ] ]

View Source GLModel.ts, line 1690

# exportVRML()

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

View Source GLModel.ts, line 2960

Returns:

VRML

# getCrystData()

Returns crystallographic information if present.

View Source GLModel.ts, line 2679

# getID() → {number}

Returns model id number

View Source GLModel.ts, line 2730

Returns:

Model ID

Type: number

# getInternalState()

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

View Source GLModel.ts, line 2663

# getNumFrames() → {number}

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

View Source GLModel.ts, line 2738

Returns:

Type: number

# getRadiusFromStyle(atom, style) → {number}

Parameters:

Name	Type	Description
`atom`	`AtomSpec`
`style`	`atomstyle`

View Source GLModel.ts, line 133

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

View Source GLModel.ts, line 2713

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:

Name	Type	Description
`group`	`Object3D`
`Object`		options

View Source GLModel.ts, line 2954

# hide()

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

@see GLModel#show

View Source GLModel.ts, line 2983

Example

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

# removeAtoms(badatoms)

Remove specified atoms from model

Parameters:

Name	Type	Description
`badatoms`	`Array.<AtomSpec>`	list of atoms

View Source GLModel.ts, line 2853

# removegl(group)

Remove any renderable mol object from scene

Parameters:

Name	Type	Description
`group`	`Object3D`

View Source GLModel.ts, line 2967

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

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

Parameters:

Name	Type	Description
`sel`	`AtomSelectionSpec`

View Source GLModel.ts, line 2830

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:

Name	Type	Description
`sel`	`AtomSelectionSpec`	atom selection to apply clickable settings to
`clickable`	`boolean`	whether click-handling is enabled for the selection
`callback`	`function`	function called when an atom in the selection is clicked

View Source GLModel.ts, line 2885

# setColorByElement(sel, colors)

given a mapping from element to color, set atom colors

Parameters:

Name	Type	Description
`sel`	`AtomSelectionSpec`
`colors`	`object`

View Source GLModel.ts, line 2911

# setColorByFunction(sel, func)

Parameters:

Name	Type	Description
`sel`	`AtomSelectionSpec`	selection object
`func`	`function`	function to be used to set the color

Deprecated:

use setStyle and colorfunc attribute

View Source GLModel.ts, line 2938

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:

Name	Type	Description
`sel`	`AtomSelectionSpec`
`prop`	`string`
`scheme`	`Gradient` \| `string`

View Source GLModel.ts, line 2919

# setCoordinates(str, format)

Set coordinates for the atoms from provided trajectory file.

Parameters:

Name	Type	Description
`str`	`string` \| `ArrayBuffer`	contains the data of the file
`format`	`string`	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.

View Source GLModel.ts, line 3046

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:

Name	Type	Description
`url`	`string`	contains the url where mdsrv has been hosted
`path`	`string`	contains the path of the file (/filename)

View Source GLModel.ts, line 3029

Returns:

Type: Promise

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

Set crystallographic information using three angles and three lengths

Parameters:

Name	Type	Description
`a`	`number`	length of unit cell side
`b`	`number`	length of unit cell side
`c`	`number`	length of unit cell side
`alpha`	`number`	unit cell angle in degrees (default 90)
`beta`	`number`	unit cell angle in degrees (default 90)
`gamma`	`number`	unit cell angle in degrees (default 90)

View Source GLModel.ts, line 2692

# setCrystMatrix(matrix)

Set the crystallographic matrix to the given matrix.

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

Parameters:

Name	Type	Description
`matrix`	`Matrix3`	unit cell matrix

View Source GLModel.ts, line 2703

# setFrame(framenum) → {Promise}

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

Parameters:

Name	Type	Description
`framenum`	`number`	model's atoms are set to this index in frames list

View Source GLModel.ts, line 2748

Returns:

Type: Promise

# setHoverable(sel, hoverable, hover_callback, unhover_callback)

Set hoverable and callback of selected atoms

Parameters:

Name	Type	Description
`sel`	`AtomSelectionSpec`	atom selection to apply hoverable settings to
`hoverable`	`boolean`	whether hover-handling is enabled for the selection
`hover_callback`	`function`	function called when an atom in the selection is hovered over
`unhover_callback`	`function`	function called when the mouse moves out of the hover area

View Source GLModel.ts, line 2895

# setInternalState(state)

Overwrite the internal model state with the passed state.

Parameters:

Name	Type	Description
`state`

View Source GLModel.ts, line 2671

# setStyle(sel, style, add)

Set atom style of selected atoms

Parameters:

Name	Type	Description
`sel`	`AtomSelectionSpec`
`style`	`AtomStyleSpec`
`add`	`boolean`	if true, add to current style, don't replace

View Source GLModel.ts, line 2876

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:

Name	Type	Description
`list`	`Array.<Matrix4>`

View Source GLModel.ts, line 2722

# show()

Unhide a hidden model

See:

GLModel#hide

View Source GLModel.ts, line 2998

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:

Name	Type	Description
`whether`	`boolean`	or not to include style information. Defaults to false.

View Source GLModel.ts, line 2946

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:

Name	Type	Description
`numFrames`	`number`	number of frames to be created, default to 10
`amplitude`	`number`	amplitude of distortion, default to 1 (full)
`bothWays`	`boolean`	if true, extend both in positive and negative directions by numFrames
`viewer`	`GLViewer`	required if arrowSpec is provided
`arrowSpec`	`ArrowSpec`	specification for drawing animated arrows. If color isn't specified, atom color (sphere, stick, line preference) is used.

View Source GLModel.ts, line 2779

Example

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

3Dmol.js

# new GLModel()

Classes

Methods

# addAtomSpecs(customAtomSpecs)

Parameters:

# addAtoms(newatoms)

Parameters:

Example

# addFrame(atoms)

Parameters:

# addMolData(data, format, options)

Parameters:

# addPropertyLabels(prop, sel, viewer, options)

Parameters:

# addResLabels(sel, viewer, options, byframe)

Parameters:

# atomIsSelected(atom, sel) → {boolean}

Parameters:

# createMolObj()

# drawAtomClickSphere()

# drawAtomCross(atom, geos)

Parameters:

# drawAtomSphere(atom, geo)

Parameters:

# drawBondLines(atom, atoms, geos)

Parameters:

# enableContextMenu(sel, contextMenuEnabled)

Parameters:

# expandAtomList()

# exportVRML()

# getCrystData()

# getID() → {number}

# getInternalState()

# getNumFrames() → {number}

# getRadiusFromStyle(atom, style) → {number}

Parameters:

# getSymmetries() → {Array.<Matrix4>}

# globj(group, Object)

Parameters:

# hide()

Example

# removeAtoms(badatoms)

Parameters:

# removegl(group)

Parameters:

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

Parameters:

Example

# setClickable(sel, clickable, callback)

Parameters:

# setColorByElement(sel, colors)

Parameters:

# setColorByFunction(sel, func)

Parameters:

Example

# setColorByProperty(sel, prop, scheme)

Parameters:

# setCoordinates(str, format)

Parameters:

Example

# setCoordinatesFromURL(url, path) → {Promise}

Parameters:

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

Parameters:

# setCrystMatrix(matrix)

Parameters:

# setFrame(framenum) → {Promise}

Parameters:

# setHoverable(sel, hoverable, hover_callback, unhover_callback)

Parameters:

# setInternalState(state)

Parameters:

# setStyle(sel, style, add)

Parameters:

Example

# setSymmetries(list)

Parameters:

# show()

Example