Global

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.: {}} elementMap - 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]

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

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

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

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

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