# 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)
  `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

  ##### 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.
  `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` | 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
  `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
  `alabel` | LabelSpec | label style for a axis
  `blabel` | string | label for b axis
  `blabel` | LabelSpec | label style for a axis
  `clabel` | string | label for c axis
  `clabel` | LabelSpec | label style for a 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
  `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