Global

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

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

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

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

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

Curve shape specification. Extends ShapeSpec

Properties:

Name	Type	Description
]	$3Dmol.Vector3	points - 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

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

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

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

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 ; supported 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
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

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

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("data/1fas.cube",setStyles);
                });

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