3D Shapes

Just like for 2D Canvases, shapes can be added to 3D Canvases to create complex figures. These may be descriptions, measurements or something else. This document covers the different types of 3D shapes and how to use them.

Managing Shapes

3D shapes can be added to 3D Canvases in a couple ways. The first is by adding a single shape by using the Canvas.addShape() function which takes a single shape object as a parameter. Use this function when you want to add to a figure that is already set up. The second method is by using the Canvas.loadContent() function which takes an array of Molecules and an array of Shapes as parameters. Use this when you want to initialize a figure based on a preconfigured set of Molecules and Shapes, such as when reading a reaction file.

You can remove a shape from a 3D Canvas by using the Canvas.removeShape() function which takes the shape to be removed as parameter.

Shapes can be controlled with visual specifications just like the rest of the objects in the ChemDoodle Web Components library. The following visual specifications are global shape specifications that will affect all shapes. Specific visual specifications are covered in the individual shape sections below.

  1. shapes_color – The color string to be used to render shapes.
  2. shapes_lineWidth – The line width used to render shapes.
  3. shapes_pointSize – The point size used to render shapes (such as surface Dot representations).

Those shapes that also render text can be controlled by these text visual specifications:

  1. text_font_size – Font size.
  2. text_font_families – Font families, this is an array of String objects.
  3. text_font_bold – True if the font is bold.
  4. text_font_italic – True if the font is italic.
  5. text_text_color – Font color.
  6. text_font_stroke_3D – 3D scenes typically have different colored backgrounds, so this stroke will add contrast to the text vs the background.

Shapes

3D Shape List

Distance

A Distance renders a graphical line between two atoms and displays the distance in Ångstroms. The Distance constructor takes two Atom data structures (although you can use any object that defines an x, y and z) to render the distance between. The following example shows how to do this:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
<script>
  var transformerDistance = new ChemDoodle.TransformCanvas3D('transformDistance', 200, 200);
  // set up visual specifications
  transformerDistance.specs.set3DRepresentation('Ball and Stick');
  transformerDistance.specs.backgroundColor = 'black';
  transformerDistance.specs.atoms_displayLabels_3D = true;
  transformerDistance.specs.shapes_color = '#fff';
  // read in a water molecule
  var water = new ChemDoodle.io.JSONInterpreter().molFrom({"a":[{"x":0,"y":-0.2633,"i":"a0","l":"O"},{"x":-0.8109999999999999,"y":0.2633,"i":"a1","l":"H"},{"x":0.8109999999999999,"y":0.2633,"i":"a2","l":"H"}],"b":[{"b":0,"e":1,"i":"b0"},{"b":0,"e":2,"i":"b1"}]});
  // create a distance object between the hydrogen atoms
  var distance = new ChemDoodle.structures.d3.Distance(water.atoms[1], water.atoms[2]);
  // add the objects to the scene
  transformerDistance.loadContent([water], [distance]);
</script>


The following visual specifications can be used to modify how distances are drawn:

  1. measurement_update_3D – a boolean to control whether the measurement should recalculate every time the scene is repainted, this is false by default.
  2. measurement_displayText_3D – a boolean to control whether to display or not display the text measurement.

Angle

An Angle renders a graphical arc between three atoms representing the angle and displays the angle in degrees. The Angle constructor takes three Atom data structures to render the distance between. The order of the three Atoms is important and must be defined from one end of the angle to the other. The following example shows how to do this:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
<script>
  var transformerAngle = new ChemDoodle.TransformCanvas3D('transformAngle', 200, 200);
  // set up visual specifications
  transformerAngle.specs.set3DRepresentation('Ball and Stick');
  transformerAngle.specs.backgroundColor = 'black';
  transformerAngle.specs.atoms_displayLabels_3D = true;
  transformerAngle.specs.shapes_color = '#fff';
  // read in a water molecule
  var water = new ChemDoodle.io.JSONInterpreter().molFrom({"a":[{"x":0,"y":-0.2633,"i":"a0","l":"O"},{"x":-0.8109999999999999,"y":0.2633,"i":"a1","l":"H"},{"x":0.8109999999999999,"y":0.2633,"i":"a2","l":"H"}],"b":[{"b":0,"e":1,"i":"b0"},{"b":0,"e":2,"i":"b1"}]});
  // create a angle object between the hydrogen atoms
  var angle = new ChemDoodle.structures.d3.Angle(water.atoms[1], water.atoms[0], water.atoms[2]);
  // add the objects to the scene
  transformerAngle.loadContent([water], [angle]);
</script>


The following visual specifications can be used to modify how angles are drawn:

  1. measurement_update_3D – a boolean to control whether the measurement should recalculate every time the scene is repainted, this is false by default.
  2. measurement_angleBands_3D – this integer defines the resolution of the arc.
  3. measurement_displayText_3D – a boolean to control whether to display or not display the text measurement.

Torsion

A Torsion renders a graphical arc between four atoms representing the torsion and displays the torsion in degrees. The Torsion constructor takes four Atom data structures to render the distance between. The order of the four Atoms is important and must be defined from one end of the torsion to the other. The following example shows how to do this:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
<script>
  var transformTorsion = new ChemDoodle.TransformCanvas3D('transformTorsion', 200, 200);
  // set up visual specifications
  transformTorsion.specs.set3DRepresentation('Ball and Stick');
  transformTorsion.specs.backgroundColor = 'black';
  transformTorsion.specs.atoms_displayLabels_3D = true;
  transformTorsion.specs.shapes_color = '#fff';
  // read in molecule
  var mol = new ChemDoodle.io.JSONInterpreter().molFrom({"a":[{"x":-2.18,"y":0.0553,"i":"a0","l":"Cl"},{"x":-0.49420000000000003,"y":-0.584,"i":"a1"},{"x":0.49420000000000003,"y":0.584,"i":"a2"},{"x":2.18,"y":-0.0553,"i":"a3","l":"Cl"},{"x":-0.3366,"y":-1.1932,"i":"a4","l":"H","z":0.89},{"x":-0.3366,"y":-1.1932,"i":"a5","l":"H","z":-0.89},{"x":0.3366,"y":1.1932,"i":"a6","l":"H","z":-0.89},{"x":0.3366,"y":1.1932,"i":"a7","l":"H","z":0.89}],"b":[{"b":0,"e":1,"i":"b0"},{"b":1,"e":2,"i":"b1"},{"b":2,"e":3,"i":"b2"},{"b":1,"e":4,"i":"b3"},{"b":1,"e":5,"i":"b4"},{"b":2,"e":6,"i":"b5"},{"b":2,"e":7,"i":"b6"}]});
  // create a torsion object between the chlorine atoms
  var torsion = new ChemDoodle.structures.d3.Torsion(mol.atoms[0], mol.atoms[1], mol.atoms[2], mol.atoms[3]);
  // add the objects to the scene
  transformTorsion.loadContent([mol], [torsion]);
</script>


The following visual specifications can be used to modify how torsions are drawn:

  1. measurement_update_3D – a boolean to control whether the measurement should recalculate every time the scene is repainted, this is false by default.
  2. measurement_angleBands_3D – this integer defines the resolution of the arc.
  3. measurement_displayText_3D – a boolean to control whether to display or not display the text measurement.

Surface

A Surface represents a three dimensional area of chemical meaning given a set of atoms. More succinctly, a surface is an object that wraps some atomic distance. There are 3 types of surfaces available in the ChemDoodle Web Components:

  1. Solvent Accessible Surface (SASSurface)
  2. Solvent Excluded (Connolly) Surface (SESSurface)
  3. van der Waals Surface (VDWSurface)

The class names are provided in the parenthesis in this list. A surface can be instantiated by invoking their constructors. Both the SASSurface and SESSurface require a probe radius value in their constructors, while the VDWSurface does not. The following code shows how to create each of the surfaces from a molecule:

1
2
3
4
5
6
var mol = ...;
// 30 is typically an acceptable resolution
var vdw = new ChemDoodle.structures.d3.VDWSurface(mol.atoms, 30);
// make sure SAS and SES surfaces have probeRadius values, 1.4 is typically used for water
var sas = new ChemDoodle.structures.d3.SASSurface(mol.atoms, 1.4, 30);
var ses = new ChemDoodle.structures.d3.SESSurface(mol.atoms, 1.4, 30);

Here is a full example of rendering a surface:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
<script>
  var transformSurface = new ChemDoodle.TransformCanvas3D('transformSurface', 200, 200);
  // set up visual specifications
  transformSurface.specs.set3DRepresentation('Ball and Stick');
  transformSurface.specs.backgroundColor = 'black';
  transformSurface.specs.atoms_displayLabels_3D = true;
  // read in molecule
  var mol = new ChemDoodle.io.JSONInterpreter().molFrom({"a":[{"x":0.6211,"i":"a0","y":1.7604,"z":-0.2843,"l":"Cl"},{"x":-0.5948,"i":"a1","y":2.9636,"z":0.1308},{"x":-1.9015,"i":"a2","y":2.6746,"z":0.1493},{"x":-3.2932,"i":"a3","y":4.1783,"z":0.6587,"l":"I"},{"x":-2.5611,"i":"a4","y":0.9239,"z":-0.2752,"l":"Br"},{"x":-0.2637,"i":"a5","y":3.9671,"z":0.3776,"l":"H"}],"b":[{"b":0,"e":1,"i":"b0"},{"b":1,"e":2,"i":"b1","o":2},{"b":2,"e":3,"i":"b2"},{"b":2,"e":4,"i":"b3"},{"b":1,"e":5,"i":"b4"}]});
  // load in the molecule first, so that coordinates for the surface are after centering
  transformSurface.loadMolecule(mol);
  // create a van der Waals surface object of the entire molecule
  // we are using a low quality resolution (10) just to show render this example quickly and load the documentation
  var surface = new ChemDoodle.structures.d3.VDWSurface(mol.atoms, 10);
  // add the shape to the scene
  transformSurface.addShape(surface);
</script>


The following visual specifications can be used to modify how surfaces are rendered:

  1. surfaces_display – a boolean to control whether the surfaces are to be rendered or not, this is true by default.
  2. surfaces_alpha – this value, between 0 and 1, defines the alpha value of the surface. A value of 0 means the surface is invisible, and a value of 1 means the surface is completely opaque. The default value is .5.
  3. surfaces_style – this string defines the representation of the surface; the possible values are ‘Dots’, ‘Mesh’ and ‘Solid’. ‘Solid’ is the default value.
  4. surfaces_color – this is the color surfaces are rendered with; ‘white’ is the default.
  5. surfaces_materialAmbientColor_3D – this is the ambient color the shader uses to render surfaces.
  6. surfaces_materialSpecularColor_3D – this is the specular color the shader uses to render surfaces.
  7. surfaces_materialShininess_3D – this positive integer is the shininess the shader uses to render surfaces.

Unit Cell

A Unit Cell renders a rectangular prism bounds. The UnitCell constructor takes 8 Array data structures (each of length 3 of numbers representing a point x,y,z) in an object wrapper representing the 8 corners of the rectangular prism named accordingly. The following example shows how to do this:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
<script>
  var transformUnitCell = new ChemDoodle.TransformCanvas3D('transformUnitCell', 200, 200);
  // set up visual specifications
  transformUnitCell.specs.set3DRepresentation('Ball and Stick');
  transformUnitCell.specs.backgroundColor = 'black';
  transformUnitCell.specs.atoms_displayLabels_3D = true;
  transformUnitCell.specs.shapes_color = '#fff';
  // create a gold atom
  var mol = new ChemDoodle.structures.Molecule();
  mol.atoms.push(new ChemDoodle.structures.Atom('Au'));
  // create a cubic unit cell
  var unitCell = new ChemDoodle.structures.d3.UnitCell({o:[-.5,-.5,-.5],x:[.5,-.5,-.5],y:[-.5,.5,-.5],z:[-.5,-.5,.5],xy:[.5,.5,-.5],xz:[.5,-.5,.5],yz:[-.5,.5,.5],xyz:[.5,.5,.5]});
  // add the objects to the scene
  transformUnitCell.loadContent([mol], [unitCell]);
</script>