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

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

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

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

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

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

Cylinder shape specification. Extends ShapeSpec

Properties:
Name Type Description
start $3Dmol.Vector3
end $3Dmol.Vector3
radius number
fromCap boolean

0 for none, 1 for flat, 2 for round

toCap boolean

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)

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

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

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

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