Global

Methods

AlertBox(config)

Add alert messages to different panels

Parameters:

Name	Type	Description
config	Object	Configuraiton for alert box display

ContextMenu()

Creates the panel for manipulation of labels on the viewport

ModelToolbar()

ModelToolbar is part of $3Dmol.UI to edit or change the model loaded into the viewer

Property(key, value)

Property object used in property menu

Parameters:

Name	Type	Description
key	String	Name of the atom property
value	*	Value of the property

Selection()

Card for manipulation of a selection form and related styles

SelectionBox(icon) → {Object}

Selection box creates the UI panel to manipulate selections and style that are drawn
on the viewport

Parameters:

Name	Type	Description
icon	$3Dmol.UI.Icons	takes the svg code for the icon that is to be used to display selection box

Returns:

Jquery element of div

Type

Object

setLocation(parent, child, x_type, y_type, x_offset, y_offset)

Sets the location of the element relative to the parseInt
as per position types

Parameters:

Name	Type	Description
parent	Object	jquery object
child	Object	jquery object
x_type	String	'left|right'
y_type	String	'top|bottom'
x_offset	Number	Offset x values in pixels
y_offset	Number	Offset y values in pixels

setPosition(jquery, left, top)

Sets the css position property left and top for the element

Parameters:

Name	Type	Description
jquery	object	html element
left	number	: css left property
top	number	: css top peroperty

StyleBox(selId, side)

Creates StyleBox for listing out different styles inside the selection

Parameters:

Name	Type	Description
selId	String	Id of the selection for which the style box is created
side	String	Alignment of text inside the box

Surface()

Creates cards for manipulation of surface

SurfaceMenu()

Creates UI panel for surface manipulations

Type Definitions

ArrowSpec

Arrow shape specification. Extends ShapeSpec

Properties:

Name	Type	Description
start	$3Dmol.Vector3
end	$3Dmol.Vector3
radius	number
color	ColorSpec
hidden	boolean
radiusRatio	number	ratio of arrow base to cylinder (1.618034 default)
mid	number	relative position of arrow base (0.618034 default)
midpos	number	position of arrow base in length units, if negative positioned from end instead of start. Overrides mid.

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. Integer numerical ranges are supported as strings.
model	GLModel	a single model or list of models from which atoms should be selected. Can also specify by numerical creation order. Reverse indexing is allowed (-1 specifies last added model).
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
and	Array.<AtomSelectionSpec>	take the intersection of the provided lists of {AtomSelectionSpec}s
or	Array.<AtomSelectionSpec>	take the union of the provided lists of {AtomSelectionSpec}s
not	AtomSelectionSpec	take the inverse of the provided {AtomSelectionSpec}

Example

$3Dmol.download("pdb:2EJ0",viewer,{},function(){
                  viewer.setStyle({chain:'B'},{cartoon:{color:'spectrum'}});
                  viewer.setStyle({chain:'B',invert:true},{cartoon:{}});
                  viewer.setStyle({bonds: 0},{sphere:{radius:0.5}}); //water molecules
                  viewer.setStyle({resn:'PMP',byres:true,expand:5},{stick:{colorscheme:"greenCarbon"}});
                  viewer.setStyle({resi:["91-95","42-50"]},{cartoon:{color:"green",thickness:1.0}});
                  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
clicksphere	ClickSphereStyleSpec	invisible style for click handling only

BoxSpec

Box shape specification. Extends ShapeSpec

Properties:

Name	Type	Description
corner	$3Dmol.Vector3	bottom corner of box
center	$3Dmol.Vector3	alternative to corner: center of box
dimensions	Object	{w:width, h:height, d:depth}; can be either scalars or vectors (for not-axis aligned boxes)

CartoonStyleSpec

A visualization of protein or nucleic acid secondary structure. Applying this to other molecules will not show anything.

Properties:

Name	Type	Description
color	ColorSpec	strand color, may specify as 'spectrum' which will apply reversed gradient based on residue number
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
	string	color>Carbon - use default element colors but with carbon set to specify html color string
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 colorscheme. Is either a $3Dmol.Gradient object or the name of a built-in gradient (rwb, roygb, sinebow)
	min	min value for gradient
	max	max value for gradient
	mid	mid point value for gradient (for rwb)
map	object	map of a certain AtomSpec property to a color of the form {'prop': 'elem', map:$3Dmol.elementColors.greenCarbon} Allows the user to provide a mapping of elements to colors to the colorscheme. This can be done with any properties, and not just 'elem'.
colorfunc	function	Allows the user to provide a function for setting the colorschemes.

Example

//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( {chain:'A'}, { cartoon: {colorfunc: colorAsSnake }});
                  viewer.setStyle( {chain:'B'}, { stick: {colorscheme: 'yellowCarbon'}});

                  viewer.render();
              });

ColorSpec

Color representation.

Properties:

Name	Type	Description
0xAF10AB	string	any hex number
	string	color name>

CrossStyleSpec

Properties:

Name	Type	Description
hidden	boolean	do not show
linewidth	number	deprecated due to vanishing browser support
radius	number
scale	number	scale radius by specified amount
colorscheme	ColorschemeSpec	element based coloring
color	ColorSpec	fixed coloring, overrides colorscheme
opacity	number	opacity, must be the same for all atoms in the model

CurveSpec

Curve shape specification. Extends ShapeSpec

Properties:

Name	Type	Description
points	$3Dmol.Vector3	list of (x,y,z) points to interpolate between to make curve
smooth	number	amount of interpolation
radius	number
fromArrow	boolean	if an arrow should be drawn at the start
toArrow	boolean	if an arrow should be drawn at the end

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	$3Dmol.CAP	0 for none, 1 for flat, 2 for round
toCap	$3Dmol.CAP	0 for none, 1 for flat, 2 for round
dashed	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 multiple 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 No longer supported by most browsers
smoothness	number	amount to smooth surface (default 1)
coords	list	coordinates around which to include data; use viewer.selectedAtoms() to convert an AtomSelectionSpec to coordinates
seldist	number	distance around coords to include data [default = 2.0]
voldata	$3Dmol.VolumeData	volumetric data for vertex coloring, can be VolumeData object or raw data if volformat is specified
volscheme	$3Dmol.Gradient	coloring scheme for mapping volumetric data to vertex color, if not a Gradient object, show describe a builtin gradient one by providing an object with gradient, min, max, and (optionally) mid fields.
volformat	string	format of voldata if not a $3Dmol.VolumeData object
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	$3Dmol.Vector3	x,y,z coordinates for label
screenOffset	$3Dmol.Vector2	x,y pixel offset of label from position
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
useScreen	boolean	position is in screen (not model) coordinates which are pixel offsets from upper left corner.
backgroundImage	Object	An element to draw into the label. Any CanvasImageSource is allowed.
alignment	string	how to orient the label w/respect to position: topLeft (default), topCenter, topRight, centerLeft, center, centerRight, bottomLeft, bottomCenter, bottomRight
frame	number	if set, only display in this frame of an animation

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	deprecated due to vanishing browser support
colorscheme	ColorschemeSpec	element based coloring
color	ColorSpec	fixed coloring, overrides colorscheme
opacity	number	opacity, must be the same for all atoms in the model

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
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 ; supported by cdjson
doAssembly	boolean	boolean dictating weather or not to do assembly ; supported by mcif
duplicateAssemblyAtoms-	boolean	Set to true if you wish to duplicate assembly atoms otherwise false ; supported by all formats with symmetries. Not duplicating will result in faster rendering but it will not be possible to individually style symmetries.
normalizeAssembly	boolean	shift symmetry mates so their centroid is in the unit cell
dontConnectDuplicatedAtoms	boolean	do not detect bonds between symmetries generated with duplicateAssemblyAtoms (cif only - other formats never make bonds between symmetries)
noSecondaryStructure	boolean	boolean dictating the presence of a secondary structure ; supported by pdb
noComputeSecondaryStructure	boolean	do not compute ss ; supported by pdb
altLoc	string	which alternate location to select, if present; '*' to load all ; supported by pdb
assemblyIndex	number	index of the assembly in symmetry ; supported by mmtf
assignBonds	boolean	for formats without explicit bonds (e.g. PDB, xyz) infer bonding (default true).

ShapeSpec

GLShape style specification

Properties:

Name	Type	Description
color	ColorSpec	solid color
alpha	number	transparency
wireframe	boolean	draw as wireframe, not surface
hidden	boolean	if true, do not display object
linewidth	number	width of line for wireframe rendering No longer supported by most browsers
clickable	boolean	if true, user can click on object to trigger callback
callback	function	function to call on click
frame	number	if set, only display in this frame of an animation

SphereShapeSpec

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
opacity	number	opacity, must be the same for all atoms in the model

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
opacity	number	opacity, must be the same for all atoms in the model

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, can be VolumeData object or raw data if volformat is specified
volscheme	$3Dmol.Gradient	coloring scheme for mapping volumetric data to vertex color, if not a Gradient object, show describe a builtin gradient one by providing an object with gradient, min, max, and (optionally) mid fields.
volformat	string	format of voldata if not a $3Dmol.VolumeData object
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("data/1fas.cube",setStyles);
                });

UnitCellStyleSpec

Unit Cell shape specification.

Properties:

Name	Type	Description
box	LineStyleSpec	line style used to draw box
astyle	ArrowSpec	arrow specification of "a" axis
bstyle	ArrowSpec	arrow specification of "b" axis
cstyle	ArrowSpec	arrow specification of "c" axis
alabel	string	label for a axis
alabelstyle	LabelSpec	label style for a axis
blabel	string	label for b axis
blabelstyle	LabelSpec	label style for b axis
clabel	string	label for c axis
clabelstyle	LabelSpec	label style for c axis

Vector3

3 dimensional vector

Properties:

Name	Type	Description
x	number	x coordinate
y	number	y coordinate
z	number	z coordinate

ViewerGridSpec

Grid GLViewer input specification

Properties:

Name	Type	Description
rows	number	number of rows in grid
cols	number	number of columns in grid
control_all	boolean	if true, mouse events are linked

ViewerSpec

GLViewer input specification

Properties:

Name	Type	Description
callback	function	Callback function to be immediately executed on this viewer
defaultcolors	Object	Object defining default atom colors as atom => color property value pairs for all models within this viewer
nomouse	boolean	Whether to disable disable handling of mouse events. If you want to use your own mouse handlers, set this then bind your handlers to the canvas object. The default 3Dmol.js handlers are available for use: 'mousedown touchstart': viewer._handleMouseDown, 'DOMMouseScroll mousewheel': viewer._handleMouseScroll 'mousemove touchmove': viewer._handleMouseMove
backgroundColor	string	Color of the canvas background
backgroundAlpha	number	Alpha transparency of canvas background
camerax	number
hoverDuration	number
id	string	id of the canvas
cartoonQuality	number	default 5
row	number
col	number
rows	number
cols	number
canvas
viewers
minimumZoomToDistance
lowerZoomLimit
upperZoomLimit
antialias	boolean
control_all	boolean
orthographic	boolean
disableFog	boolean	Disable fog, default to false

VolumetricRendererSpec

VolumetricRenderer style specification

Properties:

Name	Type	Description
transferfn	list	list of objects containing @color, @opacity and @value properties to specify color per voxel data value
subsamples	number	number of times to sample each voxel approximately (default 5)

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.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