Documents > 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 styles just like the rest of the objects in the ChemDoodle Web Components library. The following styles are global shape styles that will affect all shapes. Specific styles 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 styles:

  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:

<script>
  let transformerDistance = new ChemDoodle.TransformCanvas3D('transformDistance', 200, 200);
  // set up styles
  transformerDistance.styles.set3DRepresentation('Ball and Stick');
  transformerDistance.styles.backgroundColor = 'black';
  transformerDistance.styles.atoms_displayLabels_3D = true;
  transformerDistance.styles.shapes_color = '#fff';
  // read in a water molecule
  let 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
  let 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 styles 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:

<script>
  let transformerAngle = new ChemDoodle.TransformCanvas3D('transformAngle', 200, 200);
  // set up styles
  transformerAngle.styles.set3DRepresentation('Ball and Stick');
  transformerAngle.styles.backgroundColor = 'black';
  transformerAngle.styles.atoms_displayLabels_3D = true;
  transformerAngle.styles.shapes_color = '#fff';
  // read in a water molecule
  let 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
  let 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 styles 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:

<script>
  let transformTorsion = new ChemDoodle.TransformCanvas3D('transformTorsion', 200, 200);
  // set up styles
  transformTorsion.styles.set3DRepresentation('Ball and Stick');
  transformTorsion.styles.backgroundColor = 'black';
  transformTorsion.styles.atoms_displayLabels_3D = true;
  transformTorsion.styles.shapes_color = '#fff';
  // read in molecule
  let 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
  let 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 styles 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:

let mol = ...;
// 30 is typically an acceptable resolution
let 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
let sas = new ChemDoodle.structures.d3.SASSurface(mol.atoms, 1.4, 30);
let ses = new ChemDoodle.structures.d3.SESSurface(mol.atoms, 1.4, 30);

Here is a full example of rendering a surface:

<script>
  let transformSurface = new ChemDoodle.TransformCanvas3D('transformSurface', 200, 200);
  // set up styles
  transformSurface.styles.set3DRepresentation('Ball and Stick');
  transformSurface.styles.backgroundColor = 'black';
  transformSurface.styles.atoms_displayLabels_3D = true;
  // read in molecule
  let 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
  let surface = new ChemDoodle.structures.d3.VDWSurface(mol.atoms, 10);
  // add the shape to the scene
  transformSurface.addShape(surface);
</script>

The following styles 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 2 or 3 Array data structures. The first two arrays are lengths (a, b, and c in Angstroms) and angles (alpha, beta, and gamma in radians), and they are required. The third array is the offset for the unit cell in ABC coordinates; if not provided, the default offset will be [0, 0, 0] to start the unit cell at the origin. The following example shows how to do this:

<script>
  let transformUnitCell = new ChemDoodle.TransformCanvas3D('transformUnitCell', 200, 200);
  // set up styles
  transformUnitCell.styles.set3DRepresentation('Ball and Stick');
  transformUnitCell.styles.backgroundColor = 'black';
  transformUnitCell.styles.atoms_displayLabels_3D = true;
  transformUnitCell.styles.shapes_color = '#fff';
  // create a gold atom
  let mol = new ChemDoodle.structures.Molecule();
  mol.atoms.push(new ChemDoodle.structures.Atom('Au'));
  // create a cubic unit cell
  // offset by [-.5, -.5, -.5] to center the gold atom at the origin within the unit cell
  let unitCell = new ChemDoodle.structures.d3.UnitCell([1, 1, 1], [Math.PI/2, Math.PI/2, Math.PI/2], [-.5, -.5, -.5]);
  // add the objects to the scene
  transformUnitCell.loadContent([mol], [unitCell]);
</script>

Get your work done with our popular desktop software.

ChemDoodle 2D
ChemDoodle 3D