Visual Specifications

Visual specifications define how graphics in the ChemDoodle Web Components library are rendered. Together they form a style sheet that can control your entire page in a global context, or finely control how a single atom or bond is drawn.

The VisualSpecifications Object

A VisualSpecifications object is automatically created for each Canvas when it is initialized. This object contains a list of specifications that will define how the Canvas will render its content. These specifications can be any type of data, from booleans to numbers to strings and arrays. All content rendered by the ChemDoodle Web Components library will have corresponding specifications in the VisualSpecifications object. This way, you have full control over the graphics. A full list of the specifications is described in the API.

You can also manually create an individual VisualSpecifications object by calling its constructor as shown in the following code:

1
2
3
<script>
  var mySpecs = new ChemDoodle.structures.VisualSpecifications();
</script>

You may be wondering why this is useful, as this new object will not be linked to any graphics. In the ChemDoodle Web Components library, specifications can be linked to more than just a Canvas. Specifications can be set globally for the entire webpage, for each Canvas, or to precisely define graphics for each individual graphical object.

Defining Specifications Globally

To define visual specifications globally, for an entire webpage, just set the specification from the API for the ChemDoodle global variable with the “default_” string before the specification name. The following source code shows how to set the global specifications to render all 2D Canvases in ACS Document 1996 style. Unless further overridden, as described in the following sections, all 2D Canvases will render their content with that definition.

1
2
3
4
5
6
7
8
9
10
<script>
  ChemDoodle.default_bondLength_2D = 14.4;
  ChemDoodle.default_bonds_width_2D = .6;
  ChemDoodle.default_bonds_saturationWidth_2D = .18;
  ChemDoodle.default_bonds_hashSpacing_2D = 2.5;
  ChemDoodle.default_atoms_font_size_2D = 10;
  ChemDoodle.default_atoms_font_families_2D = ["Helvetica", "Arial", "sans-serif"];
  ChemDoodle.default_atoms_displayTerminalCarbonLabels_2D = true;
  ChemDoodle.default_atoms_useJMOLColors = true;
</script>

Of course, we can do this for the 3D specifications as well to control the WebGL Canvases in a global manner.

Defining Specifications for a Canvas

A Canvas‘s VisualSpecifications object will be created automatically when the Canvas is initialized. This VisualSpecifications object can be accessed as the Canvas.specs parameter. The following source demonstrates how to set ACS Document 1996 style to an individual Canvas.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
<script>
  var myCanvas = new ChemDoodle.ViewerCanvas('myCanvas', 150, 150);
  //the width of the bonds should be .6 pixels
  myCanvas.specs.bonds_width_2D = .6;
  //the spacing between higher order bond lines should be 18% of the length of the bond
  myCanvas.specs.bonds_saturationWidth_2D = .18;
  //the hashed wedge spacing should be 2.5 pixels
  myCanvas.specs.bonds_hashSpacing_2D = 2.5;
  //the atom label font size should be 10
  myCanvas.specs.atoms_font_size_2D = 10;
  //we define a cascade of acceptable font families
  //if Helvetica is not found, Arial will be used
  myCanvas.specs.atoms_font_families_2D = ["Helvetica", "Arial", "sans-serif"];
  //display carbons labels if they are terminal
  myCanvas.specs.atoms_displayTerminalCarbonLabels_2D = true;
  //add some color by using JMol colors for elements
  myCanvas.specs.atoms_useJMOLColors = true;
  myCanvas.emptyMessage = 'No Data Loaded!';
  var caffeineMolFile = 'Molecule Name\n  CHEMDOOD08070920033D 0   0.00000     0.00000     0\n[Insert Comment Here]\n 14 15  0  0  0  0  0  0  0  0  1 V2000\n   -0.3318    2.0000    0.0000   O 0  0  0  1  0  0  0  0  0  0  0  0\n   -0.3318    1.0000    0.0000   C 0  0  0  1  0  0  0  0  0  0  0  0\n   -1.1980    0.5000    0.0000   N 0  0  0  1  0  0  0  0  0  0  0  0\n    0.5342    0.5000    0.0000   C 0  0  0  1  0  0  0  0  0  0  0  0\n   -1.1980   -0.5000    0.0000   C 0  0  0  1  0  0  0  0  0  0  0  0\n   -2.0640    1.0000    0.0000   C 0  0  0  4  0  0  0  0  0  0  0  0\n    1.4804    0.8047    0.0000   N 0  0  0  1  0  0  0  0  0  0  0  0\n    0.5342   -0.5000    0.0000   C 0  0  0  1  0  0  0  0  0  0  0  0\n   -2.0640   -1.0000    0.0000   O 0  0  0  1  0  0  0  0  0  0  0  0\n   -0.3318   -1.0000    0.0000   N 0  0  0  1  0  0  0  0  0  0  0  0\n    2.0640   -0.0000    0.0000   C 0  0  0  2  0  0  0  0  0  0  0  0\n    1.7910    1.7553    0.0000   C 0  0  0  4  0  0  0  0  0  0  0  0\n    1.4804   -0.8047    0.0000   N 0  0  0  1  0  0  0  0  0  0  0  0\n   -0.3318   -2.0000    0.0000   C 0  0  0  4  0  0  0  0  0  0  0  0\n  1  2  2  0  0  0  0\n  3  2  1  0  0  0  0\n  4  2  1  0  0  0  0\n  3  5  1  0  0  0  0\n  3  6  1  0  0  0  0\n  7  4  1  0  0  0  0\n  4  8  2  0  0  0  0\n  9  5  2  0  0  0  0\n 10  5  1  0  0  0  0\n 10  8  1  0  0  0  0\n  7 11  1  0  0  0  0\n  7 12  1  0  0  0  0\n 13  8  1  0  0  0  0\n 13 11  2  0  0  0  0\n 10 14  1  0  0  0  0\nM  END\n> <DATE>\n07-08-2009\n';
  var caffeine = ChemDoodle.readMOL(caffeineMolFile);
  //the bond lengths should be 14.4 pixels
  caffeine.scaleToAverageBondLength(14.4);
  myCanvas.loadMolecule(caffeine);
</script>

Defining Specifications for Individual Objects

For even further control, a VisualSpecifications object can be defined to the specs parameter for any Atom or Bond. This can be useful if you want to highlight a portion of the structure, or finely tune the graphics rendering. In the following example, a Canvas is created to show caffeine, with double bonds colored red and with the nitrogen attached to the double bond drawn in bold.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
<script>
  var myCanvas = new ChemDoodle.ViewerCanvas(name, 150, 150);
  // set up the specifications to be assigned to the double bonds
  var doubleBondSpecs = new ChemDoodle.structures.VisualSpecifications();
  doubleBondSpecs.bonds_color = 'red';
  // set up the specifications to be assigned to the one nitrogen
  var nitrogenSpecs = new ChemDoodle.structures.VisualSpecifications();
  nitrogenSpecs.atoms_font_bold_2D = true;
  // caffeine data
  var caffeineMolFile = 'Molecule Name\n  CHEMDOOD08070920033D 0   0.00000     0.00000     0\n[Insert Comment Here]\n 14 15  0  0  0  0  0  0  0  0  1 V2000\n   -0.3318    2.0000    0.0000   O 0  0  0  1  0  0  0  0  0  0  0  0\n   -0.3318    1.0000    0.0000   C 0  0  0  1  0  0  0  0  0  0  0  0\n   -1.1980    0.5000    0.0000   N 0  0  0  1  0  0  0  0  0  0  0  0\n    0.5342    0.5000    0.0000   C 0  0  0  1  0  0  0  0  0  0  0  0\n   -1.1980   -0.5000    0.0000   C 0  0  0  1  0  0  0  0  0  0  0  0\n   -2.0640    1.0000    0.0000   C 0  0  0  4  0  0  0  0  0  0  0  0\n    1.4804    0.8047    0.0000   N 0  0  0  1  0  0  0  0  0  0  0  0\n    0.5342   -0.5000    0.0000   C 0  0  0  1  0  0  0  0  0  0  0  0\n   -2.0640   -1.0000    0.0000   O 0  0  0  1  0  0  0  0  0  0  0  0\n   -0.3318   -1.0000    0.0000   N 0  0  0  1  0  0  0  0  0  0  0  0\n    2.0640   -0.0000    0.0000   C 0  0  0  2  0  0  0  0  0  0  0  0\n    1.7910    1.7553    0.0000   C 0  0  0  4  0  0  0  0  0  0  0  0\n    1.4804   -0.8047    0.0000   N 0  0  0  1  0  0  0  0  0  0  0  0\n   -0.3318   -2.0000    0.0000   C 0  0  0  4  0  0  0  0  0  0  0  0\n  1  2  2  0  0  0  0\n  3  2  1  0  0  0  0\n  4  2  1  0  0  0  0\n  3  5  1  0  0  0  0\n  3  6  1  0  0  0  0\n  7  4  1  0  0  0  0\n  4  8  2  0  0  0  0\n  9  5  2  0  0  0  0\n 10  5  1  0  0  0  0\n 10  8  1  0  0  0  0\n  7 11  1  0  0  0  0\n  7 12  1  0  0  0  0\n 13  8  1  0  0  0  0\n 13 11  2  0  0  0  0\n 10 14  1  0  0  0  0\nM  END\n> <DATE>\n07-08-2009\n';
  var caffeine = ChemDoodle.readMOL(caffeineMolFile);
  // loop through the structure to find the objects to assign the specs to
  for(var i = 0, ii=caffeine.bonds.length; i<ii; i++){
    var b = caffeine.bonds[i];
    if(b.bondOrder==2){
      // found a double bond, so assign the correct specs
      b.specs = doubleBondSpecs;
      // since we are looking for a nitrogen in a double bond, we can just check inside this loop
      // if either constituent atoms are nitrogen, then set the correct specs
      if(b.a1.label=='N'){
        b.a1.specs = nitrogenSpecs;
      }
      if(b.a2.label=='N'){
        b.a2.specs = nitrogenSpecs;
      }
    }
  }
  myCanvas.loadMolecule(caffeine);
</script>

Using the VisualSpecifications object in the ChemDoodle Web Components library will provide you with complete control over all aspects of your graphics.