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.
