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.

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.

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>