Methods
-
createViewer(element, config) → {$3Dmol.GLViewer}
-
Create and initialize an appropriate viewer at supplied HTML element using specification in config
Parameters:
Name Type Description element
Object | string Either HTML element or string identifier
config
ViewerSpec Viewer specification
Returns:
GLViewer, null if unable to instantiate WebGL
- Type
- $3Dmol.GLViewer
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(); });
-
download(query, viewer, options, callback) → {$3Dmol.GLModel}
-
Load a PDB/PubChem structure into existing viewer. Automatically calls 'zoomTo' and 'render' on viewer after loading model
Parameters:
Name Type Description query
string String specifying pdb or pubchem id; must be prefaced with "pdb: " or "cid: ", respectively
viewer
$3Dmol.GLViewer Add new model to existing viewer
options
Object Specify additional options format: file format to download, if multiple are available, default format is pdb pdbUri: URI to retrieve PDB files, default URI is http://www.rcsb.org/pdb/files/
callback
function Function to call with model as argument after data is loaded.
Returns:
GLModel
- Type
- $3Dmol.GLModel
Example
viewer.setBackgroundColor(0xffffffff); $3Dmol.download('pdb:2nbd',viewer,{onemol: true,multimodel: true},function(m) { m.setStyle({'cartoon':{colorscheme:{prop:'ss',map:$3Dmol.ssColors.Jmol}}}); viewer.zoomTo(); viewer.render(callback); });
-
setColorByFunction(sel, func)
-
Parameters:
Name Type Description sel
type selection object
func
type 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(); });
Type Definitions
-
ArrowSpec
-
Arrow shape specification. Extends ShapeSpec
Properties:
Name Type Description start
$3Dmol.Vector3 end
$3Dmol.Vector3 radius
number radiusRatio
number ratio of arrow base to cylinder (1.618034 default)
mid
number relative position of arrow base (0.618034 default)
-
AtomSelectionSpec
-
Atom selection object. Used to specify what atoms should be selected. Can include any field from AtomSpec in which case atoms must equal the specified value.
All fields must match for the selection to hold. If values are provided as a list, then only one value of the list must match.Properties:
Name Type Description ...
AtomSpec any field from AtomSpec, values may be singletons or lists
model
GLModel a single model or list of models from which atoms should be selected
bonds
number overloaded to select number of bonds, e.g. {bonds: 0} will select all nonbonded atoms
predicate
function user supplied function that gets passed an {AtomSpec} and should return true if the atom should be selected
invert
boolean if set, inverts the meaning of the selection
byres
boolean if set, expands the selection to include all atoms of any residue that has any atom selected
expand
number expands the selection to include all atoms within a given distance from the selection
within
WithinSelectionSpec intersects the selection with the set of atoms within a given distance from another selection
Example
$3Dmol.download("pdb:2EJ0",viewer,{},function(){ viewer.addLabel("Aromatic", {position: {x:-6.89, y:0.75, z:0.35}, backgroundColor: 0x800080, backgroundOpacity: 0.8}); viewer.addLabel("Label",{font:'sans-serif',fontSize:18,fontColor:'white',fontOpacity:1,borderThickness:1.0, borderColor:'red',borderOpacity:0.5,backgroundColor:'black',backgroundOpacity:0.5, position:{x:50.0,y:0.0,z:0.0},inFront:true,showBackground:true}); viewer.setStyle({chain:'A'},{cross:{hidden:true}}); viewer.setStyle({chain:'B'},{cross:{hidden:false, linewidth:1.0, colorscheme:'greenCarbon'}}); viewer.setStyle({chain:'C'},{cross:{hidden:false, linewidth:1.0, radius:0.5}}); viewer.setStyle({chain:'D'},{cross:{hidden:false, linewidth:10.0}}); viewer.setStyle({chain:'E'},{cross:{hidden:false, linewidth:1.0, color:'black'}}); viewer.render(); });
-
AtomSpec
-
Atom representation. Depending on the input file format, not all fields may be defined.
Properties:
Name Type Description resn
string Parent residue name
x
number Atom's x coordinate
y
number Atom's y coordinate
z
number Atom's z coordinate
color
ColorSpec Atom's color, as hex code or built-in color string
surfaceColor
ColorSpec Hex code for color to be used for surface patch over this atom
elem
string Element abbreviation (e.g. 'H', 'Ca', etc)
hetflag
boolean Set to true if atom is a heteroatom
chain
string Chain this atom belongs to, if specified in input file (e.g 'A' for chain A)
resi
number Residue number
icode
number rescode
number serial
number Atom's serial id number
atom
string Atom name; may be more specific than 'elem' (e.g 'CA' for alpha carbon)
bonds
Array.<number> Array of atom ids this atom is bonded to
ss
string Secondary structure identifier (for cartoon render; e.g. 'h' for helix)
singleBonds
boolean true if this atom forms only single bonds or no bonds at all
bondOrder
Array.<number> Array of this atom's bond orders, corresponding to bonds identfied by 'bonds'
properties
Object Optional mapping of additional properties
b
number Atom b factor data
pdbline
string If applicable, this atom's record entry from the input PDB file (used to output new PDB from models)
clickable
boolean Set this flag to true to enable click selection handling for this atom
callback
function Callback click handler function to be executed on this atom and its parent viewer
invert
boolean for selection, inverts the meaning of the selection
-
AtomStyleSpec
-
Properties:
Name Type Description line
LineStyleSpec draw bonds as lines
cross
CrossStyleSpec draw atoms as crossed lines (aka stars)
stick
StickStyleSpec draw bonds as capped cylinders
sphere
SphereStyleSpec draw atoms as spheres
cartoon
CartoonStyleSpec draw cartoon representation of secondary structure
-
CartoonStyleSpec
-
Properties:
Name Type Description color
ColorSpec strand color, may specify as 'spectrum'
style
string style of cartoon rendering (trace, oval, rectangle (default), parabola, edged)
ribbon
boolean whether to use constant strand width, disregarding secondary structure; use thickness to adjust radius
arrows
boolean whether to add arrows showing beta-sheet directionality; does not apply to trace or ribbon
tubes
boolean whether to display alpha helices as simple cylinders; does not apply to trace
thickness
number cartoon strand thickness, default is 0.4
width
number cartoon strand width, default is secondary structure-dependent; does not apply to trace or ribbon
opacity
number set opacity from 0-1; transparency is set per-chain with a warning outputted in the event of ambiguity
In
nucleic acids, the base cylinders obtain their color from the atom to which the cylinder is drawn, which is 'N1' for purines (resn: 'A', 'G', 'DA', 'DG') and 'N3' for pyrimidines (resn: 'C', 'U', 'DC', 'DT'). The different nucleobases can therefore be distinguished as follows:
Example
$3Dmol.download("pdb:4ZD3",viewer,{},function(){ viewer.setBackgroundColor(0xffffffff); viewer.setViewStyle({style:"outline"}); viewer.setStyle({},{cartoon:{}}); viewer.render(); });
-
ColorschemeSpec
-
Properties:
Name Type Description greenCarbon
string 0x00FF00
cyanCarbon
string 0x00FFFF
magentaCarbon
string 0xFF00FF
yellowCarbon
string 0xFFFF00
whiteCarbon
string 0xFFFFFF
orangeCarbon
string 0xFF6600
purpleCarbon
string 0x100080
blueCarbon
string 0x0000FF
ssPyMOL
string PyMol secondary colorscheme
ssJmol
string Jmol secondary colorscheme
Jmol
string Jmol primary colorscheme
default
string default colorscheme
amino
string amino acid colorscheme
shapely
string shapely protien colorscheme
nucleic
string nucleic acid colorscheme
chain
string standard chain colorscheme
chainHetatm
string chain Hetatm colorscheme
prop
string atomSpec property. Example 'b'. See AtomSpec.
gradient
Gradient Allows the user to provide a gradient to the colorsheme. See example #3.
map
object map of a certain AtomSpec propery to a color.: {}} elementMap - Allows the user to provide a mapping of elements to colors to the colorscheme. This is shown in example #2 and it should be noted that this can be done with any properties, and not just 'elem'.
colorfunc
function Allows the user to provide a function for setting the colorshemes.See example #4.
Examples
$.get('../test_structs/benzene-homo.cube', function(data){ var voldata = new $3Dmol.VolumeData(data, "cube"); viewer.addIsosurface(voldata, {isoval: 0.01, color: "blue", alpha: 0.5, smoothness: 10}); viewer.addIsosurface(voldata, {isoval: -0.01, color: "red", smoothness: 5, opacity:0.5, wireframe:true, linewidth:0.1, clickable:true, callback: function() { this.opacity = 0.0; }}); viewer.setStyle({}, {stick:{}}); viewer.zoomTo(); viewer.render(); });
//Using a gradient with colorscheme. viewer.setViewStyle({style:"outline"}); viewer.setViewStyle({style:"outline"}); $.get('volData/1fas.pqr', function(data){ viewer.addModel(data, "pqr"); $.get("volData/1fas.cube",function(volumedata){ viewer.addSurface($3Dmol.SurfaceType.VDW, {opacity:0.85,voldata: new $3Dmol.VolumeData(volumedata, "cube"), volscheme: new $3Dmol.Gradient.RWB(-10,10)},{}); viewer.render(callback); }); viewer.zoomTo(); });
//Using a function in order to define the colors. $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(); });
-
ColorSpec
-
Color representation.
Properties:
Name Type Description 0xAF10AB
string any hex number
white
string 0xFFFFFF
silver
string 0xC0C0C0
gray
string 0x808080
grey
string 0x808080
black
string 0x000000
red
string 0xFF0000
maroon
string 0x800000
yellow
string 0xFFFF00
orange
string 0xFF6600
olive
string 0x808000
lime
string 0x00FF00
green
string 0x008000
aqua
string 0x00FFFF
cyan
string 0x00FFFF
teal
string 0x008080
blue
string 0x0000FF
navy
string 0x000080
fuchsia
string 0xFF00FF
magenta
string 0xFF00FF
purple
string 0x800080
-
CrossStyleSpec
-
Properties:
Name Type Description hidden
boolean do not show
linewidth
number radius
number scale
number scale radius by specified amount
colorscheme
ColorschemeSpec element based coloring
color
ColorSpec fixed coloring, overrides colorscheme
-
CustomShapeSpec
-
Specification for adding custom shape. Extends ShapeSpec.
Properties:
Name Type Description vertexArr
Array.<$3Dmol.Vector3> List of vertex positions
normalArr
Array.<$3Dmol.Vector3> List of normal vectors for each vertex
faceArr
Array.<number> List of triangles to build the custom shape. Each triangle is defined by the indices of 3 vertices in vertexArr, so the array length should be 3 times the number of faces.
color
ColorSpec | Array.<ColorSpec> Either a single color for the whole object or an array specifying the color at each vertex.
-
CylinderSpec
-
Cylinder shape specification. Extends ShapeSpec
Properties:
Name Type Description start
$3Dmol.Vector3 end
$3Dmol.Vector3 radius
number fromCap
boolean toCap
boolean -
FileFormats
-
File formats supported by 3Dmol.js
Properties:
Name Type Description cdjson,json
Chemical JSON format
cube
Gaussian cube format
gro
Gromacs topology format, need to add coordinates to resulting model.
mcif,cif
Crystallographic Information File, the successor to PDB that makes you miss the PDB file format
mmtf
Macromolecular Transmission Format, the successor to PDB that is totally awesome
mol2
Sybyl Mol2 format
pdb
The venerable Protein Data Bank format
pqr
Like PDB but with partial charges which are read into the partialcharge atom property
prmtop
Amber topology file, must add coordinates
sdf
MDL MOL format, supports muliple models and meta data
vasp
VASP format (CONTCAR, POSCAR)
xyz
XYZ cartesian coordinates format
-
IsoSurfaceSpec
-
Isosurface style specification
Properties:
Name Type Description isoval
number specifies the isovalue to draw surface at
color
ColorSpec solid color
opacity
number transparency, between 0 and 1
wireframe
boolean draw as wireframe, not surface
linewidth
number width of line for wireframe rendering
smoothness
number amount to smooth surface (default 1)
sel
AtomSelectionSpec selection around which to show data
coords
list coordinates around which to include data
seldist
number distance around selection/coords to include data [default = 2.0]
clickable
boolean if true, user can click on object to trigger callback
callback
function function to call on click
-
LabelSpec
-
Label type specification
Properties:
Name Type Description font
string font name, default sans-serif
fontSize
number height of text, default 18
fontColor
ColorSpec font color, default white
fontOpacity
number font opacity, default 1
borderThickness
number line width of border around label, default 0
borderColor
ColorSpec color of border, default backgroundColor
borderOpacity
string color of border
backgroundColor
ColorSpec color of background, default black
backgroundOpacity
string opacity of background, default 1
position
Object x,y,z coordinates for label
inFront
boolean always put labels in from of model
showBackground
boolean show background rounded rectangle, default true
fixed
boolean sets the label to change with the model when zooming
-
LineSpec
-
Line shape specification. Extends ShapeSpec (but defaults to wireframe)
Properties:
Name Type Description start
$3Dmol.Vector3 end
$3Dmol.Vector3 -
LineStyleSpec
-
Properties:
Name Type Description hidden
boolean do not show line
linewidth
number colorscheme
ColorschemeSpec element based coloring
color
ColorSpec fixed coloring, overrides colorscheme
-
ParserOptionsSpec
-
Parser options specification. Used to specify the options of a GLModel. Depending on the input file format, not all fields may be defined.
Properties:
Name Type Description duplicateAssemblyAtoms-
boolean Set to true if you wish to diplicate assembly atoms otherwise false ; supported by all
frames
boolean true if you want to add to a new frame and false otherwise ; supported by all
vibrate
object object specifying the vibration behavior ; supported by all
Properties
Name Type Description frames
number number of frames to be created, default to 10 ; supported by all
amplitude
number amplitude of distortion, default to 1 (full) ; supported by all
multimodel
boolean specifies weather or not multiple models are being defined ; supported by xyz,sdf, or mol2
onemol
boolean specifies weather or not the model is of one molecule ; Supported by xyz , sdf , mol2
keepH
boolean do not strip hydrogens ; supported by sdf,mol2
parseStyle
object used to define ChemDoodle styles ; upported by cdjson
doAssembly
boolean boolean dictating weather or not to do assembly ; supported by mcif
noSecondaryStructure
boolean boolean dictating the presence of a secondary structure ; supported by pdb
-
ShapeSpec
-
GLShape style specification
Properties:
Name Type Description color
ColorSpec solid color
alpha
number transparency
wireframe
boolean draw as wireframe, not surface
linewidth
number width of line for wireframe rendering
clickable
boolean if true, user can click on object to trigger callback
callback
function function to call on click
-
SphereSpec
-
Sphere shape specification. Extends ShapeSpec
Properties:
Name Type Description center
$3Dmol.Vector3 radius
number -
SphereStyleSpec
-
Properties:
Name Type Description hidden
boolean do not show atom
radius
number override van der waals radius
scale
number scale radius by specified amount
colorscheme
ColorschemeSpec element based coloring
color
ColorSpec fixed coloring, overrides colorscheme
-
StickStyleSpec
-
Properties:
Name Type Description hidden
boolean do not show
radius
number singleBonds
boolean draw all bonds as single bonds if set
colorscheme
ColorschemeSpec element based coloring
color
ColorSpec fixed coloring, overrides colorscheme
-
SurfaceStyleSpec
-
Properties:
Name Type Description opacity
number sets the transparency: 0 to hide, 1 for fully opaque
colorscheme
ColorschemeSpec element based coloring
color
ColorSpec fixed coloring, overrides colorscheme
voldata
$3Dmol.VolumeData volumetric data for vertex coloring
volscheme
$3Dmol.Gradient coloring scheme for mapping volumetric data to vertex color
map
Object specifies a numeric atom property (prop) and color mapping (scheme) such as $3Dmol.Gradient.RWB. Deprecated, use colorscheme instead.
Example
var setStyles = function(volumedata){ var data = new $3Dmol.VolumeData(volumedata, "cube"); viewer.addSurface("VDW", {opacity:0.85, voldata: data, volscheme: new $3Dmol.Gradient.RWB(-10,10)},{chain:'A'}); viewer.mapAtomProperties($3Dmol.applyPartialCharges); viewer.addSurface($3Dmol.SurfaceType.SAS, {map:{prop:'partialCharge',scheme:new $3Dmol.Gradient.RWB(-.05,.05)}, opacity:1.0},{chain:'B'}); viewer.addSurface($3Dmol.SurfaceType.VDW, {opacity:0.85,voldata: data, color:'red'},{chain:'C'}); viewer.addSurface($3Dmol.SurfaceType.SAS, {opacity:0.85,voldata: data, colorscheme:'greenCarbon'},{chain:'D'}); viewer.render(); }; $3Dmol.download("pdb:4DLN",viewer,{},function(){ $.get("volData/1fas.cube",setStyles); });
-
Vector3
-
3 dimensional vector
Properties:
Name Type Description x
number x coordinate
y
number y coordinate
z
number z coordinate
-
ViewerSpec
-
GLViewer input specification
Properties:
Name Type Description defaultcolors
Object map of elements to colors
nomouse
boolean if true, disable handling of mouse events
backgroundColor
ColorSpec color of background
-
WithinSelectionSpec
-
Within selection object. Used to find the subset of an atom selection that is within some distance from another atom selection. When added as a field of an AtomSelectionSpec, intersects the set of atoms in that selection with the set of atoms within a given distance from the given AtomSelectionSpec.
Properties:
Name Type Description distance
number the distance in angstroms away from the atom selection to include atoms in the parent selection
invert
boolean if set, selects atoms not within distance range for intersection
sel
AtomSelectionSpec the selection of atoms against which to measure the distance from the parent atom selection
Example
$3Dmol.download("pdb:2EJ0",viewer,{},function(){ viewer.addLabel("Aromatic", {position: {x:-6.89, y:0.75, z:0.35}, backgroundColor: 0x800080, backgroundOpacity: 0.8}); viewer.addLabel("Label",{font:'sans-serif',fontSize:18,fontColor:'white',fontOpacity:1,borderThickness:1.0, borderColor:'red',borderOpacity:0.5,backgroundColor:'black',backgroundOpacity:0.5, position:{x:50.0,y:0.0,z:0.0},inFront:true,showBackground:true}); viewer.setStyle({chain: 'A', within:{distance: 10, sel:{chain: 'B'}}}, {sphere:{}}); viewer.render(); });// stylizes atoms in chain A that are within 10 angstroms of an atom in chain B