# Class: GLViewer

## $3Dmol. GLViewer

#### new GLViewer(element, config)

  WebGL-based 3Dmol.js viewer
  Note: The preferred method of instantiating a GLViewer is through $3Dmol.createViewer

  ##### Parameters:

  Name | Type | Description
  --- | --- | ---
  `element` | Object | HTML element within which to create viewer

  `config`

  Object

  Object containing optional configuration for the viewer including:

  ###### 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 mouse handlers
  `backgroundColor` | string | Color of the canvas' background
  `camerax` | number |
  `hoverDuration` | number |
  `id` | string | id of the canvas
  `cartoonQuality` | number | default 5
  `row` |  |
  `col` |  |
  `rows` |  |
  `cols` |  |
  `canvas` |  |
  `viewers` |  |
  `minimumZoomToDistance` |  |
  `lowerZoomLimit` |  |
  `upperZoomLimit` |  |
  `antialias` | boolean |
  `control_all` | boolean |
  `orthographic` | boolean |

### Methods

#### addArrow(spec) → {$3Dmol.GLShape}

  Create and add arrow shape

  ##### Parameters:

  Name | Type | Description
  --- | --- | ---
  `spec` | ArrowSpec | Style specification

  ##### Returns:

  Type
    $3Dmol.GLShape

  ##### Example

      $3Dmol.download("pdb:4DM7",viewer,{},function(){

                        viewer.setBackgroundColor(0xffffffff);
                        viewer.addArrow({
                            start: {x:-10.0, y:0.0, z:0.0},
                            end: {x:0.0, y:-10.0, z:0.0},
                            radius: 1.0,
                            radiusRadio:1.0,
                            mid:1.0,
                            clickable:true,
                            callback:function(){
                                this.color.setHex(0xFF0000FF);
                                viewer.render( );
                            }
                        });
                        viewer.render();
                      });

#### addAsOneMolecule(data, format) → {$3Dmol.GLModel}

  Create and add model to viewer. Given multimodel file and its format,
  all atoms are added to one model

  ##### Parameters:

  Name | Type | Description
  --- | --- | ---
  `data` | string | Input data
  `format` | string | Input format (see FileFormats)

  ##### Returns:

  Type
    $3Dmol.GLModel

  ##### Example

      $.get('../test_structs/multiple.sdf', function(data){
                        viewer.addAsOneMolecule(data, "sdf");
                        viewer.zoomTo();
                        viewer.render();
                    });

#### addBox(spec) → {$3Dmol.GLShape}

  Create and add box shape. This method provides a shorthand
  way to create a box shape object

  ##### Parameters:

  Name | Type | Description
  --- | --- | ---
  `spec` | BoxSpec | Box shape style specification

  ##### Returns:

  Type
    $3Dmol.GLShape

  ##### Example

      viewer.addLine({color:'red',start:{x:0,y:0,z:0},end:{x:5,y:0,z:0}});
               viewer.addLine({color:'blue',start:{x:0,y:0,z:0},end:{x:0,y:5,z:0}});
               viewer.addLine({color:'green',start:{x:0,y:0,z:0},end:{x:0,y:0,z:5}});

               viewer.addBox({center:{x:0,y:0,z:0},dimensions: {w:3,h:4,d:2},color:'magenta'});
               viewer.zoomTo();
               viewer.rotate(45, {x:1,y:1,z:1});
               viewer.render();

#### addCurve(spec) → {$3Dmol.GLShape}

  Create and add Curve shape

  ##### Parameters:

  Name | Type | Description
  --- | --- | ---
  `spec` | CurveSpec | Style specification

  ##### Returns:

  Type
    $3Dmol.GLShape

  ##### Example

      viewer.addCurve({points: [{x:0.0,y:0.0,z:0.0}, {x:5.0,y:3.0,z:0.0}, {x:5.0,y:7.0,z:0.0}, {x:0.0,y:10.0,z:0.0}],
                                        radius:0.5,
                                        smooth: 10,
                                        fromArrow:false,
                                        toArrow: true,
                                        color:'orange',
                                        });
                    viewer.addCurve({points: [{x:-1,y:0.0,z:0.0}, {x:-5.0,y:5.0,z:0.0}, {x:-2,y:10.0,z:0.0}],
                                        radius:1,
                                        fromArrow:true,
                                        toArrow: false,
                                        color:'purple',
                                        });
                    viewer.zoomTo();
                    viewer.render();

#### addCustom(spec) → {$3Dmol.GLShape}

  Add custom shape component from user supplied function

  ##### Parameters:

  Name | Type | Description
  --- | --- | ---
  `spec` | CustomSpec | Style specification

  ##### Returns:

  Type
    $3Dmol.GLShape

  ##### Example

      function triangle(viewer) {
          var vertices = [];
          var normals = [];
          var colors = [];
          var r = 20;
          //triangle
          vertices.push(new $3Dmol.Vector3(0,0,0));
          vertices.push(new $3Dmol.Vector3(r,0,0));
          vertices.push(new $3Dmol.Vector3(0,r,0));

          normals.push(new $3Dmol.Vector3(0,0,1));
          normals.push(new $3Dmol.Vector3(0,0,1));
          normals.push(new $3Dmol.Vector3(0,0,1));

          colors.push({r:1,g:0,b:0});
          colors.push({r:0,g:1,b:0});
          colors.push({r:0,g:0,b:1});

          var faces = [ 0,1,2 ];

          var spec = {vertexArr:vertices, normalArr: normals, faceArr:faces,color:colors};
          viewer.addCustom(spec);
      }
                  triangle(viewer);
                  viewer.render();

#### addCylinder(spec) → {$3Dmol.GLShape}

  Create and add cylinder shape

  ##### Parameters:

  Name | Type | Description
  --- | --- | ---
  `spec` | CylinderSpec | Style specification

  ##### Returns:

  Type
    $3Dmol.GLShape

  ##### Example

      viewer.setBackgroundColor(0xffffffff);
                    viewer.addCylinder({start:{x:0.0,y:0.0,z:0.0},
                                        end:{x:10.0,y:0.0,z:0.0},
                                        radius:1.0,
                                        fromCap:1,
                                        toCap:2,
                                        color:'red',
                                        hoverable:true,
                                        clickable:true,
                                        callback:function(){ this.color.setHex(0x00FFFF00);viewer.render( );},
                                        hover_callback: function(){ viewer.render( );},
                                        unhover_callback: function(){ this.color.setHex(0xFF000000);viewer.render( );}
                                       });
                    viewer.addCylinder({start:{x:0.0,y:2.0,z:0.0},
                                        end:{x:0.0,y:10.0,z:0.0},
                                        radius:0.5,
                                        fromCap:false,
                                        toCap:true,
                                        color:'teal'});
                    viewer.addCylinder({start:{x:15.0,y:0.0,z:0.0},
                                        end:{x:20.0,y:0.0,z:0.0},
                                        radius:1.0,
                                        color:'black',
                                        fromCap:false,
                                        toCap:false});
                    viewer.render();

#### addIsosurface(data, spec) → {$3Dmol.GLShape}

  Construct isosurface from volumetric data. This is more flexible
  than addVolumetricData, but can not be used with py3Dmol.

  ##### Parameters:

  Name | Type | Description
  --- | --- | ---
  `data` | $3Dmol.VolumeData | volumetric data
  `spec` | IsoSurfaceSpec | Shape style specification

  ##### Returns:

  Type
    $3Dmol.GLShape

  ##### Example

      $.get('../test_structs/benzene-homo.cube', function(data){
                        var voldata = new $3Dmol.VolumeData(data, "cube");
                        viewer.addIsosurface(voldata, {isoval: 0.01,
                                                       color: "blue"});
                        viewer.addIsosurface(voldata, {isoval: -0.01,
                                                       color: "red"});
                        viewer.zoomTo();
                        viewer.render();
                      });

#### addLabel(text, options, sel, noshow) → {$3Dmol.Label}

  Add label to viewer

  ##### Parameters:

  Name | Type | Description
  --- | --- | ---
  `text` | string | Label text
  `options` | LabelSpec | Label style specification
  `sel` | AtomSelection | Set position of label to center of this selection
  `noshow` | boolean | if true, do not immediately display label - when adding multiple labels this is more efficient

  ##### Returns:

  Type
    $3Dmol.Label

  ##### Example

      $3Dmol.download("pdb:2EJ0",viewer,{},function(){

                        viewer.addLabel("Aromatic", {position: {x:-6.89, y:0.75, z:0.35}, backgroundColor: 0x800080, backgroundOpacity: 0.8});
                        viewer.addLabel("Label",{font:'sans-serif',fontSize:18,fontColor:'white',fontOpacity:1,borderThickness:1.0,
                                                 borderColor:'red',borderOpacity:0.5,backgroundColor:'black',backgroundOpacity:0.5,
                                                 position:{x:50.0,y:0.0,z:0.0},inFront:true,showBackground:true});
                        viewer.setStyle({chain:'A'},{cross:{hidden:true}});
                        viewer.setStyle({chain:'B'},{cross:{hidden:false,
                                                            linewidth:1.0,
                                                            colorscheme:'greenCarbon'}});
                        viewer.setStyle({chain:'C'},{cross:{hidden:false,
                                                            linewidth:1.0,
                                                            radius:0.5}});
                        viewer.setStyle({chain:'D'},{cross:{hidden:false,
                                                            linewidth:10.0}});
                        viewer.setStyle({chain:'E'},{cross:{hidden:false,
                                                            linewidth:1.0,
                                                            color:'black'}});

                        viewer.render();

                      });

#### addLine(spec) → {$3Dmol.GLShape}

  Create and add line shape

  ##### Parameters:

  Name | Type | Description
  --- | --- | ---
  `spec` | LineSpec | Style specification, can specify dashed, dashLength, and gapLength

  ##### Returns:

  Type
    $3Dmol.GLShape

  ##### Example

      $3Dmol.download("pdb:2ABJ",viewer,{},function(){

                        viewer.setViewStyle({style:"outline"});
                        viewer.setStyle({chain:'A'},{sphere:{hidden:true}});
                        viewer.setStyle({chain:'D'},{sphere:{radius:3.0}});
                        viewer.setStyle({chain:'G'},{sphere:{colorscheme:'greenCarbon'}});
                        viewer.setStyle({chain:'J'},{sphere:{color:'blue'}});
                        viewer.addLine({dashed:true,start:{x:0,y:0,z:0},end:{x:100,y:100,z:100}});
                        viewer.render();
                    });

#### addMesh(mesh, style) → {Number}

  Adds an explicit mesh as a surface object.

  ##### Parameters:

  Name | Type | Description
  --- | --- | ---
  `mesh` | $3Dmol.Mesh |
  `style` | Object |

  ##### Returns:

  surfid

  Type
    Number

#### addModel(data, format, options) → {$3Dmol.GLModel}

  Create and add model to viewer, given molecular data and its format

  ##### Parameters:

  Name | Type | Description
  --- | --- | ---
  `data` | string | Input data
  `format` | string | Input format ('pdb', 'sdf', 'xyz', 'pqr', or 'mol2')
  `options` | ParserOptionsSpec | format dependent options. Attributes depend on the input file format.

  ##### Returns:

  Type
    $3Dmol.GLModel

  ##### Example

      viewer.setViewStyle({style:"outline"});
                    $.get('data/1fas.pqr', function(data){
                        viewer.addModel(data, "pqr");
                        $.get("data/1fas.cube",function(volumedata){
                            viewer.addSurface($3Dmol.SurfaceType.VDW, {opacity:0.85,voldata: new $3Dmol.VolumeData(volumedata, "cube"), volscheme: new $3Dmol.Gradient.RWB(-10,10)},{});

                        viewer.render();
                        });
                        viewer.zoomTo();
                    });

#### addModels(data, format) → {Array.<$3Dmol.GLModel>}

  Given multimodel file and its format, add atom data to the viewer as separate models
  and return list of these models

  ##### Parameters:

  Name | Type | Description
  --- | --- | ---
  `data` | string | Input data
  `format` | string | Input format (see FileFormats)

  ##### Returns:

  Type
    Array.<$3Dmol.GLModel>

#### addModelsAsFrames(data, format) → {$3Dmol.GLModel}

  Create and add model to viewer. Given multimodel file and its format,
  different atomlists are stored in model's frame
  property and model's atoms are set to the 0th frame

  ##### Parameters:

  Name | Type | Description
  --- | --- | ---
  `data` | string | Input data
  `format` | string | Input format (see FileFormats)

  ##### Returns:

  Type
    $3Dmol.GLModel

  ##### Example

      $.get('../test_structs/multiple2.xyz', function(data){
                        viewer.addModelsAsFrames(data, "xyz");
                        viewer.animate({loop: "forward",reps: 1});
                        viewer.setStyle({stick:{colorscheme:'magentaCarbon'}});
                        viewer.zoomTo();
                        viewer.render();
                    });

#### addPropertyLabels(prop, sel, style)

  Add property labels. This will generate one label per a selected
  atom at the atom's coordinates with the property value as the label text.

  ##### Parameters:

  Name | Type | Description
  --- | --- | ---
  `prop` | string | property name
  `sel` | Object |

  `style`

  Object

  - @example
    $3Dmol.download("cid:5291",viewer,{},function(){
    viewer.setStyle({stick: {radius:.2}});
    viewer.addPropertyLabels("index",{not:{elem:'H'}}, {fontColor:'black',font: 'sans-serif', fontSize: 28, showBackground:false,alignment:'center'});
    viewer.zoomTo();
    viewer.render();
    });

#### addResLabels(sel, style, byframe)

  Add residue labels. This will generate one label per a
  residue within the selected atoms. The label will be at the
  centroid of the atoms and styled according to the passed style.
  The label text will be [resn][resi]

  ##### Parameters:

  Name | Type | Description
  --- | --- | ---
  `sel` | Object |
  `style` | Object |

  `byframe`

  boolean

  if true, create labels for every individual frame, not just current
  - @example
    $3Dmol.download("mmtf:2ll5",viewer,{},function(){
    viewer.setStyle({stick:{radius:0.15},cartoon:{}});
    viewer.addResLabels({hetflag:false}, {font: 'Arial', fontColor:'black',showBackground:false});
    viewer.zoomTo();
    viewer.render();
    });

#### addShape(shapeSpec) → {$3Dmol.GLShape}

  Add shape object to viewer

  ##### Parameters:

  Name | Type | Description
  --- | --- | ---
  `shapeSpec` | ShapeSpec | style specification for label

  See:
    - $3Dmol.GLShape

  ##### Returns:

  Type
    $3Dmol.GLShape

#### addSphere(spec) → {$3Dmol.GLShape}

  Create and add sphere shape. This method provides a shorthand
  way to create a spherical shape object

  ##### Parameters:

  Name | Type | Description
  --- | --- | ---
  `spec` | SphereShapeSpec | Sphere shape style specification

  ##### Returns:

  Type
    $3Dmol.GLShape

  ##### Example

      viewer.addSphere({center:{x:0,y:0,z:0},radius:10.0,color:'red'});

               viewer.render();

#### addStyle(sel, style)

  Add style properties to all selected atoms

  ##### Parameters:

  Name | Type | Description
  --- | --- | ---
  `sel` | AtomSelectionSpec | Atom selection specification
  `style` | AtomStyleSpec | style spec to add to specified atoms

  ##### Example

      $3Dmol.download('pdb:5IRE',viewer,{doAssembly: false},function(m) {
             viewer.setStyle({cartoon:{}});
             //keep cartoon style, but show thick sticks for chain A
             viewer.addStyle({chain:'A'},{stick:{radius:.5,colorscheme:"magentaCarbon"}});
             viewer.zoomTo();
             viewer.render();
             });

#### addSurface(type, style, atomsel, allsel, focus, surfacecallback) → {Promise}

  Add surface representation to atoms

  ##### Parameters:

  Name | Type | Description
  --- | --- | ---
  `type` | $3Dmol.SurfaceType | string | Surface type (VDW, MS, SAS, or SES)
  `style` | SurfaceStyleSpec | optional style specification for surface material (e.g. for different coloring scheme, etc)
  `atomsel` | AtomSelectionSpec | Show surface for atoms in this selection
  `allsel` | AtomSelectionSpec | Use atoms in this selection to calculate surface; may be larger group than 'atomsel'
  `focus` | AtomSelectionSpec | Optionally begin rendering surface specified atoms
  `surfacecallback` | function | function to be called after setting the surface

  ##### Returns:

  promise - Returns a promise that ultimately resovles to the surfid. Returns surfid immediately if surfacecallback is specified. Returned promise has a surfid field for immediate access.

  Type
    Promise

#### addUnitCell(Model) → {$3Dmol.GLShape}

  Create and add unit cell

  ##### Parameters:

  Name | Type | Description
  --- | --- | ---
  `Model` | GLModel | with unit cell information (e.g., pdb derived).

  ##### Returns:

  Line shape delineating unit cell.

  Type
    $3Dmol.GLShape

#### addVolumetricData(data, format, or) → {$3Dmol.GLShape}

  Construct isosurface from volumetric data in gaussian cube format

  ##### Parameters:

  Name | Type | Description
  --- | --- | ---
  `data` | String | Input file contents
  `format` | String | Input file format
  `or` | IsoSurfaceSpec | {VolumetricRenderSpec} spec - Shape style specification

  ##### Returns:

  Type
    $3Dmol.GLShape

  ##### Example

      $.get('data/bohr.cube', function(data) {

            viewer.addVolumetricData(data, "cube", {isoval: -0.01, color: "red", opacity: 0.95});
            viewer.setStyle({cartoon:{},stick:{}});
            viewer.zoomTo();
            viewer.render();
          });

#### addVolumetricRender(data, spec) → {$3Dmol.GLShape}

  Create volumetric renderer for volumetricData

  ##### Parameters:

  Name | Type | Description
  --- | --- | ---
  `data` | $3Dmol.VolumeData | volumetric data
  `spec` | VolumetricRenderSpec | specification of volumetric render

  ##### Returns:

  Type
    $3Dmol.GLShape

#### animate(options)

  Animate all models in viewer from their respective frames

  ##### Parameters:

  Name | Type | Description
  --- | --- | ---
  `options` | Object | can specify interval (speed of animation), loop (direction of looping, 'backward', 'forward' or 'backAndForth'), step interval between frames ('step'), and reps (numer of repetitions, 0 indicates infinite loop)

#### center(sel, animationDuration, fixedPath)

  Re-center the viewer around the provided selection (unlike zoomTo, does not zoom).

  ##### Parameters:

  Name | Type | Argument | Description
  --- | --- | --- | ---
  `sel` | Object | <optional> | Selection specification specifying model and atom properties to select. Default: all atoms in viewer
  `animationDuration` | number | <optional> | an optional parameter that denotes the duration of a zoom animation
  `fixedPath` | Boolean | <optional> | if true animation is constrained to requested motion, overriding updates that happen during the animation *

  ##### Example

      // if the user were to pass the animationDuration value to
                // the function like so viewer.zoomTo({resn:'STI'},1000);
              //   the program would center on resn 'STI' over the course
              //   of 1 second(1000 milleseconds).
       // Reposition to centroid of all atoms of all models in this
      //viewer glviewer.center();
          $.get('data/4csv.pdb', function(data) {
            viewer.addModel(data,'pdb');
            viewer.setStyle({cartoon:{},stick:{}});
            viewer.center();
            viewer.render(callback);
          });

#### clear()

  Clear scene of all objects

#### createModelFrom(sel, extract) → {$3Dmol.GLModel}

  Create a new model from atoms specified by sel.
  If extract, removes selected atoms from existing models

  ##### Parameters:

  Name | Type | Argument | Description
  --- | --- | --- | ---
  `sel` | Object |  | Atom selection specification
  `extract` | boolean | <optional> | If true, remove selected atoms from existing models

  ##### Returns:

  Type
    $3Dmol.GLModel

#### exportJSON(includeStyles, modelID) → {string}

  Export one or all of the loaded models into ChemDoodle compatible JSON.

  ##### Parameters:

  Name | Type | Description
  --- | --- | ---
  `includeStyles` | boolean | Whether or not to include style information.
  `modelID` | number | Optional parameter for which model to export. If left out, export all of them.

  ##### Returns:

  Type
    string

#### exportVRML()

  return a VRML string representation of the scene. Include VRML header information

  ##### Returns:

  VRML

#### fitSlab(sel)

  Adjust slab to fully enclose selection (default everything).

  ##### Parameters:

  Name | Type | Argument | Description
  --- | --- | --- | ---
  `sel` | Object | <optional> | Selection specification specifying model and atom properties to select. Default: all atoms in viewer

#### getFrame()

  Gets the current viewer frame.

#### getInternalState()

  Return object representing internal state of
  the viewer appropriate for passing to setInternalState

#### getModel(id) → {GLModel}

  Return specified model

  ##### Parameters:

  Name | Type | Argument | Default | Description
  --- | --- | --- | --- | ---
  `id` | number | <optional> | last model id | Retrieve model with specified id

  Default Value:
    - Returns last model added to viewer or null if there are no models

  ##### Returns:

  Type
    GLModel

  ##### Example

      // Retrieve reference to first GLModel added var m =
         $3Dmol.download("pdb:1UBQ",viewer,{},function(m1){
                        $3Dmol.download("pdb:1UBI", viewer,{}, function(m2) {
                          viewer.zoomTo();
                          m1.setStyle({cartoon: {color:'green'}});
                          //could use m2 here as well
                          viewer.getModel().setStyle({cartoon: {color:'blue'}});
                          viewer.render();
                      })
                    });

#### getNumFrames() → {number}

  Returns the number of frames that the model with the most frames in the viewer has

  ##### Returns:

  Type
    number

#### getPerceivedDistance() → {number}

  Return the z distance between the model and the camera

  ##### Returns:

  distance

  Type
    number

#### getView() → {Array.<number>}

  Returns an array representing the current viewpoint.
  Translation, zoom, and rotation quaternion.

  ##### Returns:

  [ pos.x, pos.y, pos.z, rotationGroup.position.z, q.x, q.y, q.z, q.w ]

  Type
    Array.<number>

#### isAnimated() → {boolean}

  Return true if viewer is currently being animated, false otherwise

  ##### Returns:

  Type
    boolean

#### linkViewer(otherview)

  Synchronize this view matrix of this viewer to the passed viewer.
  When the viewpoint of this viewer changes, the other viewer will
  be set to this viewer's view.

  ##### Parameters:

  Name | Type | Description
  --- | --- | ---
  `otherview` | $3Dmol.GLViewer |

#### mapAtomProperties(props,, sel)

  ##### Parameters:

  Name | Type | Description
  --- | --- | ---
  `props,` | Object | either array of atom selectors with associated props, or function that takes atom and sets its properties
  `sel` | AtomSelectionSpec | subset of atoms to work on - model selection must be specified here

#### pdbData(sel) → {string}

  Return pdb output of selected atoms (if atoms from pdb input)

  ##### Parameters:

  Name | Type | Argument | Description
  --- | --- | --- | ---
  `sel` | Object | <optional> | Selection specification specifying model and atom properties to select. Default: all atoms in viewer

  ##### Returns:

  PDB string of selected atoms

  Type
    string

#### pngURI()

  Return image URI of viewer contents (base64 encoded).

#### removeAllLabels()

  Remove all labels from viewer

  ##### Example

      $3Dmol.download("pdb:1ubq",viewer,{},function(){

                     viewer.addResLabels();
                     viewer.setStyle({},{stick:{}});
                     viewer.render( ); //show labels

                     viewer.removeAllLabels();
                     viewer.render(); //hide labels
              });

#### removeAllModels()

  Delete all existing models

#### removeAllShapes()

  Remove all shape objects from viewer

#### removeAllSurfaces()

  Remove all surfaces.

#### removeLabel(label)

  Remove label from viewer

  ##### Parameters:

  Name | Type | Description
  --- | --- | ---
  `label` | $3Dmol.Label | $3Dmol label

  ##### Example

      // Remove labels created in
               $3Dmol.download("pdb:2EJ0",viewer,{},function(){
                        var toremove = viewer.addLabel("Aromatic", {position: {x:-6.89, y:0.75, z:0.35}, backgroundColor: 0x800080, backgroundOpacity: 0.8});
                        viewer.addLabel("Label",{font:'sans-serif',fontSize:18,fontColor:'white',fontOpacity:1,borderThickness:1.0,
                                                 borderColor:'red',borderOpacity:0.5,backgroundColor:'black',backgroundOpacity:0.5,
                                                 position:{x:50.0,y:0.0,z:0.0},inFront:true,showBackground:true});
                        viewer.removeLabel(toremove);
                        viewer.render();

                      });

#### removeModel(model)

  Delete specified model from viewer

  ##### Parameters:

  Name | Type | Description
  --- | --- | ---
  `model` | $3Dmol.GLModel |

#### removeShape(shape)

  Remove shape object from viewer

  ##### Parameters:

  Name | Type | Description
  --- | --- | ---
  `shape` | $3Dmol.GLShape | Reference to shape object to remove

#### removeSurface(surf)

  Remove surface with given ID

  ##### Parameters:

  Name | Type | Description
  --- | --- | ---
  `surf` | number | surface id

#### render()

  Render current state of viewer, after
  adding/removing models, applying styles, etc.

#### resize()

  Resize viewer according to containing HTML element's dimensions

#### rotate(angle, axis, animationDuration, fixedPath)

  Rotate scene by angle degrees around axis

  ##### Parameters:

  Name | Type | Argument | Description
  --- | --- | --- | ---
  `angle` | number | <optional> | Angle, in degrees, to rotate by.
  `axis` | string | <optional> | Axis ("x", "y", "z", "vx", "vy", or "vz") to rotate around. Default "y". View relative (rather than model relative) axes are prefixed with v. Axis can also be specified as a vector.
  `animationDuration` | number | <optional> | an optional parameter that denotes the duration of the rotation animation. Default 0 (no animation)
  `fixedPath` | boolean | <optional> | if true animation is constrained to requested motion, overriding updates that happen during the animation *

  ##### Example

      $3Dmol.download('cid:4000', viewer, {}, function() {
            viewer.setStyle({stick:{}});
            viewer.zoomTo();
            viewer.rotate(90,'y',1);
            viewer.render(callback);
          });

#### selectedAtoms(sel) → {Array.<Object>}

  return list of atoms selected by sel

  ##### Parameters:

  Name | Type | Description
  --- | --- | ---
  `sel` | AtomSelectionSpec |

  ##### Returns:

  Type
    Array.<Object>

#### setAutoEyeSeparation() → {number}

  Used for setting an approx value of eyeSeparation. Created for calling by StereoViewer object

  ##### Returns:

  camera x position

  Type
    number

#### setBackgroundColor(hex, a)

  Set the background color (default white)

  ##### Parameters:

  Name | Type | Description
  --- | --- | ---
  `hex` | number | Hexcode specified background color, or standard color spec
  `a` | number | Alpha level (default 1.0)

  ##### Example

      viewer.setBackgroundColor(0x000000);

#### setClickable(sel, clickable, callback)

  Set click-handling properties to all selected atomsthis.

  ##### Parameters:

  Name | Type | Description
  --- | --- | ---
  `sel` | AtomSelectionSpec | atom selection to apply clickable settings to
  `clickable` | boolean | whether click-handling is enabled for the selection
  `callback` | function | function called when an atom in the selection is clicked

  ##### Example

      $3Dmol.download("cid:307900",viewer,{},function(){

                         viewer.setStyle({},{sphere:{}});
                         viewer.setClickable({},true,function(atom,viewer,event,container) {
                             viewer.addLabel(atom.resn+":"+atom.atom,{position: atom, backgroundColor: 'darkgreen', backgroundOpacity: 0.8});
                         });
                         viewer.render();
              });

#### setColorByElement(sel, colors)

  ##### Parameters:

  Name | Type | Description
  --- | --- | ---
  `sel` | AtomSelectionSpec |
  `colors` | type |

#### setColorByProperty(sel, prop, scheme)

  ##### Parameters:

  Name | Type | Description
  --- | --- | ---
  `sel` | AtomSelectionSpec |
  `prop` | type |
  `scheme` | type |

#### setContainer(element)

  Change the viewer's container element
  Also useful if the original container element was removed from the DOM.

  ##### Parameters:

  Name | Type | Description
  --- | --- | ---
  `element` | Object | string | Either HTML element or string identifier. Defaults to the element used to initialize the viewer.

#### setDefaultCartoonQuality()

  Set the default cartoon quality for newly created models. Default is 5.
  Current models are not affected.

#### setFrame(framenum) → {Promise}

  Sets the atomlists of all models in the viewer to specified frame.
  Shapes and labels can also be displayed by frame.
  Sets to last frame if framenum out of range

  ##### Parameters:

  Name | Type | Description
  --- | --- | ---
  `framenum` | number | fame index to use, starts at zero

  ##### Returns:

  Type
    Promise

#### setHeight(h)

  Set viewer height

  ##### Parameters:

  Name | Type | Description
  --- | --- | ---
  `h` | number | Height in pixels

#### setHoverable(sel, hoverable, hover_callback, unhover_callback)

  Set hoverable and callback of selected atoms

  ##### Parameters:

  Name | Type | Description
  --- | --- | ---
  `sel` | AtomSelectionSpec | atom selection to apply hoverable settings to
  `hoverable` | boolean | whether hover-handling is enabled for the selection
  `hover_callback` | function | function called when an atom in the selection is hovered over
  `unhover_callback` | function | function called when the mouse moves out of the hover area

  ##### Example

      $3Dmol.download("pdb:1ubq",viewer,{},function(){

                     viewer.setHoverable({},true,function(atom,viewer,event,container) {
                         if(!atom.label) {
                          atom.label = viewer.addLabel(atom.resn+":"+atom.atom,{position: atom, backgroundColor: 'mintcream', fontColor:'black'});
                         }
                     },
                     function(atom) {
                         if(atom.label) {
                          viewer.removeLabel(atom.label);
                          delete atom.label;
                         }
                      }
                     );
                     viewer.setStyle({},{stick:{}});
                     viewer.render();
              });

#### setHoverDuration(hoverDuration)

  Set the duration of the hover delay

  ##### Parameters:

  Name | Type | Argument | Description
  --- | --- | --- | ---
  `hoverDuration` | number | <optional> | an optional parameter that denotes the duration of the hover delay (in milliseconds) before the hover action is called

#### setInternalState()

  Overwrite internal state of the viewer with passed object
  which should come from getInternalState.

#### setLabelStyle(label, stylespec) → {$3Dmol.Label}

  Modify existing label's style

  ##### Parameters:

  Name | Type | Description
  --- | --- | ---
  `label` | $3Dmol.Label | $3Dmol label
  `stylespec` | Object | Label style specification

  ##### Returns:

  Type
    $3Dmol.Label

#### setLabelText(label, text) → {$3Dmol.Label}

  Modify existing label's text

  ##### Parameters:

  Name | Type | Description
  --- | --- | ---
  `label` | $3Dmol.Label | $3Dmol label
  `text` | String | Label text

  ##### Returns:

  Type
    $3Dmol.Label

#### setPerceivedDistance()

  Set the distance between the model and the camera
  Essentially zooming. Useful while stereo rendering.

#### setProjection()

  Set view projection scheme. Either orthographic or perspective.
  Default is perspective. Orthographic can also be enabled on viewer creation
  by setting orthographic to true in the config object.

  ##### Example

      viewer.setViewStyle({style:"outline"});
                    $.get('data/1fas.pqr', function(data){
                        viewer.addModel(data, "pqr");
                        $.get("data/1fas.cube",function(volumedata){
                            viewer.addSurface($3Dmol.SurfaceType.VDW, {opacity:0.85,voldata: new $3Dmol.VolumeData(volumedata, "cube"), volscheme: new $3Dmol.Gradient.RWB(-10,10)},{});
                        });
                        viewer.zoomTo();

                        viewer.setProjection("orthographic");
                        viewer.render(callback);
                    });

#### setSlab() → {Object}

  Get slab of view (contents outside of slab are clipped).

  ##### Returns:

  near/far

  Type
    Object

#### setSlab()

  Set slab of view (contents outside of slab are clipped). M
  Must call render to update.

  ##### Parameters:

  Type | Description
  --- | ---
  near |
  far |

#### setStateChangeCallback()

  Set a callback to call when the view has potentially changed.

#### setStyle(sel, style)

  Set style properties to all selected atoms

  ##### Parameters:

  Name | Type | Description
  --- | --- | ---
  `sel` | AtomSelectionSpec | Atom selection specification
  `style` | AtomStyleSpec | Style spec to apply to specified atoms

  ##### Example

      viewer.setBackgroundColor(0xffffffff);
             $3Dmol.download('pdb:5IRE',viewer,{doAssembly: false},function(m) {
              m.setStyle({chain:'A'},{'cartoon':{color:'spectrum'}});
              m.setStyle({chain:'C'},{'cartoon':{style:'trace',color:'blue'}});
              m.setStyle({chain:'E'},{'cartoon':{tubes:true,arrows:true,color:'green',opacity:0.75}});
              m.setStyle({chain:'B'},{'cartoon':{color:'red',opacity:0.5}});
              m.setStyle({chain:'D'},{'cartoon':{style:'trace',color:'grey',opacity:0.75}});
              m.setStyle({chain:'F'},{'cartoon':{arrows:true,color:'white'}});
             // viewer.addStyle({chain:'B'},{line:{}});
             viewer.zoomTo();
             viewer.render();
          });

#### setSurfaceMaterialStyle(surf, style)

  Set the surface material to something else, must render change

  ##### Parameters:

  Name | Type | Description
  --- | --- | ---
  `surf` | number | Surface ID to apply changes to
  `style` | SurfaceStyleSpec | new material style specification

#### setView(arg)

  Sets the view to the specified translation, zoom, and rotation.

  ##### Parameters:

  Name | Type | Description
  --- | --- | ---
  `arg` | Array.<number> | Array formatted identically to the return value of getView

#### setViewChangeCallback()

  Set a callback to call when the view has potentially changed.

#### setViewStyle()

  Set global view styles.

  ##### Example

      viewer.setViewStyle({style:"outline"});
                    $.get('data/1fas.pqr', function(data){
                        viewer.addModel(data, "pqr");
                        $.get("data/1fas.cube",function(volumedata){
                            viewer.addSurface($3Dmol.SurfaceType.VDW, {opacity:0.85,voldata: new $3Dmol.VolumeData(volumedata, "cube"), volscheme: new $3Dmol.Gradient.RWB(-10,10)},{});
                        });
                        viewer.zoomTo();
                        viewer.render(callback);
                    });

#### setWidth(w)

  Set viewer width

  ##### Parameters:

  Name | Type | Description
  --- | --- | ---
  `w` | number | Width in pixels

#### setZoomLimits()

  Set lower and upper limit stops for zoom.

  ##### Parameters:

  Type | Description
  --- | ---
  lower | limit on zoom in (positive number). Default 0.
  upper | limit on zoom out (positive number). Default infinite.

  ##### Example

      $.get("data/set1_122_complex.mol2", function(moldata) {
                      var m = viewer.addModel(moldata);
                      viewer.setStyle({stick:{colorscheme:"Jmol"}});
                      viewer.setZoomLimits(100,200);
                      viewer.zoomTo();
                      viewer.zoom(10); //will not zoom all the way
                      viewer.render();
                  });

#### spin(axis)

  Continuously rotate a scene around the specified axis.

  ##### Parameters:

  Name | Type | Argument | Description
  --- | --- | --- | ---
  `axis` | string | <optional> | Axis ("x", "y", "z", "vx", "vy", or "vz") to rotate around. Default "y". View relative (rather than model relative) axes are prefixed with v.

#### stopAnimate()

  Stop animation of all models in viewer

#### translate(x, y, animationDuration, fixedPath)

  Translate current view by x,y screen coordinates
  This pans the camera rather than translating the model.

  ##### Parameters:

  Name | Type | Argument | Description
  --- | --- | --- | ---
  `x` | number |  | Relative change in view coordinates of camera
  `y` | number |  | Relative change in view coordinates of camera
  `animationDuration` | number | <optional> | an optional parameter that denotes the duration of a zoom animation
  `fixedPath` | Boolean | <optional> | if true animation is constrained to requested motion, overriding updates that happen during the animation *

  ##### Example

      $.get('data/4csv.pdb', function(data) {
            viewer.addModel(data,'pdb');
            viewer.setStyle({cartoon:{},stick:{}});
            viewer.zoomTo();
            viewer.translate(200,50);
            viewer.rotate(90,'z');
            viewer.render(callback);
          });

#### translateScene(x, y, animationDuration, fixedPath)

  Translate current models by x,y screen coordinates
  This translates the models relative to the current view. It does
  not change the center of rotation.

  ##### Parameters:

  Name | Type | Argument | Description
  --- | --- | --- | ---
  `x` | number |  | Relative change in x screen coordinate
  `y` | number |  | Relative change in y screen coordinate
  `animationDuration` | number | <optional> | an optional parameter that denotes the duration of a zoom animation
  `fixedPath` | Boolean | <optional> | if true animation is constrained to requested motion, overriding updates that happen during the animation *

  ##### Example

      $.get('data/4csv.pdb', function(data) {
            viewer.addModel(data,'pdb');
            viewer.setStyle({cartoon:{},stick:{}});
            viewer.zoomTo();
            viewer.translateScene(200,50);
            viewer.rotate(90,'z'); // will no longer be around model center
            viewer.render(callback);
          });

#### vibrate(numFrames, amplitude, bothWays, arrowSpec)

  If atoms have dx, dy, dz properties (in some xyz files), vibrate populates each model's frame property based on parameters.
  Models can then be animated

  ##### Parameters:

  Name | Type | Description
  --- | --- | ---
  `numFrames` | number | number of frames to be created, default to 10
  `amplitude` | number | amplitude of distortion, default to 1 (full)
  `bothWays` | boolean | if true, extend both in positive and negative directions by numFrames
  `arrowSpec` | ArrowSpec | specification for drawing animated arrows. If color isn't specified, atom color (sphere, stick, line preference) is used.

#### zoom(factor, animationDuration, fixedPath)

  Zoom current view by a constant factor

  ##### Parameters:

  Name | Type | Argument | Description
  --- | --- | --- | ---
  `factor` | number | <optional> | Magnification factor. Values greater than 1 will zoom in, less than one will zoom out. Default 2.
  `animationDuration` | number | <optional> | an optional parameter that denotes the duration of a zoom animation
  `fixedPath` | Boolean | <optional> | if true animation is constrained to requested motion, overriding updates that happen during the animation

  ##### Example

      $.get('data/4csv.pdb', function(data) {
            viewer.addModel(data,'pdb');
            viewer.setStyle({cartoon:{},stick:{}});
            viewer.zoomTo()
            viewer.zoom(2,1000);
            viewer.render();
          });

#### zoomTo(sel, animationDuration, fixedPath)

  Zoom to center of atom selection. The slab will be set appropriately for
  the selection, unless an empty selection is provided, in which case there will be no slab.

  ##### Parameters:

  Name | Type | Argument | Description
  --- | --- | --- | ---
  `sel` | Object | <optional> | Selection specification specifying model and atom properties to select. Default: all atoms in viewer
  `animationDuration` | number | <optional> | an optional parameter that denotes the duration of a zoom animation
  `fixedPath` | Boolean | <optional> | if true animation is constrained to requested motion, overriding updates that happen during the animation *

  ##### Example

      $.get('data/1fas.pqr', function(data){
                        viewer.addModel(data, "pqr");
                        $.get("data/1fas.cube",function(volumedata){
                            viewer.addSurface($3Dmol.SurfaceType.VDW, {
                                opacity:0.85,
                                voldata: new $3Dmol.VolumeData(volumedata, "cube"),
                                volscheme: new $3Dmol.Gradient.Sinebow($3Dmol.getPropertyRange(viewer.selectedAtoms(),'charge'))
                            },{});

                        viewer.render();
                        });
                        viewer.zoomTo();
                      });