3Dmol.js 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