- Open Access
CH5M3D: an HTML5 program for creating 3D molecular structures
Journal of Cheminformatics volume 5, Article number: 46 (2013)
Interactive programs that accurately represent the 3-dimensional structure of molecules are an important tool for modern chemistry. While displaying the structure of biological systems such as proteins is one of the more obvious applications, representation of smaller molecules is also important, particularly in education. To give just a few recent examples, computer graphics has been used by students to visualize the stereochemical nature of molecules , crystal structures have been used to illustrate aromatic properties , and a web-based tutorial has been developed for understanding pericyclic reactions . A review of approximately 30 apps for visualizing molecular structures on mobile devices was recently published .
In 2012, it was noted by the authors of the Avogadro program  that “the field of molecular graphics is dominated by viewers with little or no editing capabilities” . While Avogadro certainly does much to rectify this situation, our interest is in providing a web-based tool for students to view and modify small molecules. While students can certainly download and install Avogadro or another stand-alone program to create 3-dimensional structures, most of these students will not be consistently using this type of program for an extended period of time. For this reason, a free or low cost, web-based program was sought that would be usable on a range of platforms. There appears to be very few freely-available web-based programs that provide the ability to interactively view and edit molecular structures.
Given the fact that Java applets require a separate download, we were most interested in applications using HTML5. In addition to Molecular Calculator, a couple of programs are currently available that use HTML5 to interactively view 3-dimensional structures of molecules. The authors of the JSMol library have created an HTML5 page  illustrating some of the capabilities of this library, including the ability to use WebGL. CanvasMol  is a demonstration site showing some of the capabilities of HTML5. Fred Ackers  has published code combining HTML5 with WebGL to produce a 3D Molecular Viewer. One of the most well-developed HTML5 molecular graphics programs is ChemDoodle , which has web components for drawing of two-dimensional structures and viewing of three-dimensional structures. With the exception of Molecular Calculator, these programs do not offer the ability to edit/build 3D molecular structures.
While not all web browsers currently support HTML5, freely-available web browsers that do support this are available on all major platforms, including most mobile devices. While support for touch screen devices was not a primary design consideration, this program has been tested and works with some limitations on a variety of mobile devices. More complete support is planned to be included in future versions.
Library development and mouse behavior
Atomic coordinates can be read from files in the XYZ format. This format is described on the OpenBabel website . Every attempt was made to be as flexible as possible in reading these files, and spacing/column alignment is not crucial. Note that this format does not include any bond connectivity information. Upon successful reading of atomic coordinates, interatomic distances for all pairs of atoms are calculated, and if this distance is less than 1.2 times the sum of the covalent radii for these atoms, a bond is created. No attempt is made to determine the bond order in the current version of this library. If this capability is added in future versions, it will be necessary to add the ability to read and write files in a format that includes connectivity information. Preliminary support for reading MDL’s MOL format (which includes bonding information) is implemented in this library.
The HTML5 Canvas is used to display “ball-and-stick” structures of molecules with the size of atoms based on their covalent radii. It is assumed that atomic spheres do not overlap. Because the canvas element is two-dimensional, atoms are sorted by depth and drawn from back-to-front. To draw a molecule, the backmost atom is drawn using the “arc” element and filled using radial gradients to give the illusion of depth for each sphere. Colors for all elements are the same as those used in the Jmol  program. Bonds are drawn from this sphere to all connected atoms in front of this atom as lines originating from the point of intersection of the surface of the sphere and the bond for the back atom and terminating at the atomic center for the front atom. This process is then repeated until all atoms and bonds in the compound have been drawn.
This library was designed to be used with small molecules, and very few attempts were made to optimize this program for speed. No limits are placed on the array dimensions in this library, so the number of atoms that can be displayed is technically only limited by available memory. While structures containing a few thousand atoms can easily be viewed, it takes a noticeable amount of time to display large structures, and interacting with compounds of this size (rotations, etc.) is too slow to be practical. Because display and editing of large molecules is not necessary for the primary intended audience, it was not considered worthwhile to include WebGL in the initial release of this library. Implementation of WebGL would enable hardware-acceleration and allow larger molecules to be visualized, and it is possible that this will be added in future versions of this library. One simple technique has been implemented to optimize the display of larger molecules. Implementation of radial gradients is computationally expensive. For this reason, atoms are drawn without gradients in molecules containing over 250 atoms.
User interaction with molecules is accomplished using the mouse or related pointing device. Event listeners are set up for common mouse and touch events (mouse down, mouse up, mouse move, and mouse wheel). The action resulting from triggering of these events depends on the currently active 'mode’. It was decided early in development to define separate “View” and “Draw” modes. In View mode, the molecule cannot be changed, so mouse behavior is limited to rotation of the entire molecule or selecting atoms to provide information. Rotations around the x- and y-axes are performed by dragging the mouse pointer, starting on a blank portion the active canvas. Simultaneously pressing the [Shift] key allows rotation around the z-axis, while pressing the [Ctrl] key allows translations in the xy-plane. Rotation angles are based on the amount of horizontal and vertical movement of the mouse, with new molecular coordinates calculated based on standard matrix transformations. Selecting an atom provides information about this atom (elemental symbol and position in molecular coordinate list by default). If additional atoms are selected, bond lengths, angle, and dihedral angles can be viewed. Selecting an atom while pressing the [Shift] key toggles highlighting of the selected atom.
In Draw mode, the molecule can be changed, and the mouse is used to add, delete, or change atoms and to add or delete bonds. Switching between View and Draw modes is typically controlled by the user selecting a button which calls either the viewmode() or drawmode() function. The default behavior in Draw mode is to add atoms or bonds. By default, carbon atoms will be added, but this can be changed by a call to the pickElem function passing the symbol of the desired element as the parameter. For example, to change to adding nitrogen atoms, the function call would be:
To aid in selecting elements, a function is called during initialization that looks for a division within the web page with an id of 'ptable’. If this division is found, this function will write the HTML code necessary to create a periodic table with each elemental symbol defined as a button that makes the appropriate call to the pickElem() function when selected. By default, only main group elements are shown initially, but a full periodic table is also available to allow any element to be selected, which allows building of both organic and inorganic structures.
In general, selecting an individual atom changes that atom into whichever element is currently active. If the atom selected has two or more bonds, only the element type is changed. If the atom has only one bond, then the selected atom is deleted and the new atom added at a distance set as the sum of the covalent radii of the bonded atoms. For p-block elements only, the program will also attempt to add a suitable number of hydrogen atoms at appropriate positions. Bond lengths for these hydrogen atoms are determined based on covalent radii, and bond angles are determined by the user selectable hybridization, which by default is set as sp3. The number of hydrogen atoms to add (up to a maximum of three) is determined assuming that atoms obey the octet rule and is calculated from the equation:
If the active element is hydrogen, a different procedure is used. Selecting any atom will attempt to add a single hydrogen atom to this atom at a bond distance determined by the covalent radii and in a position intended to minimize interactions with other bonded atoms. Because no other atoms are moved, the result of this action is often not ideal. A very crude geometry optimization routine has been implemented, but this code is not optimized and is being actively developed to improve its speed and performance. This optimization is not a true molecular mechanics optimization, but simply optimizes bond lengths based on covalent radii, bond angles based on simple VSEPR theory, and minimizes torsional stress by changing dihedral angles.
In Draw mode, rotation of the entire molecule can be performed by “dragging” the pointer starting from a blank portion of the drawing canvas. Rotation about the z-axis is accomplished by holding the [Shift] key down during the rotation. Rotation of fragments about bonds is also possible as long as the selected bond is not part of a ring. Bonds can be added by holding the mouse pointer down on one atom and dragging the pointer to a second atom. If mistakes are made, an “Undo” function is available. This has been implemented as a simple stack, so a limited number of both “Undo” and “Redo” operations (currently 10) are possible.
To change the mouse behavior to delete atoms or bonds, a call is made to the pickElem function with a parameter of 'Delete’ or 'DelBond’. When deleting atoms, attached hydrogen atoms are also removed. To return back to the add atoms/bonds mode, pickElem is called with the desired elemental symbol.
Multiple molecules can be displayed on the same web page, and there is no hard-coded limit to the number of windows that can be placed on each page. The only requirement is that each window has a unique 'id’. The activeWin function associates a set of molecular coordinates with a canvas, and is used by all functions controlling the display of molecules, including all mouse/pointer functions. “Mouse” events are defined for each canvas, so “clicking” anywhere on any canvas can be used to set the active canvas for all user input. As a result, a single set of user interface controls (such as buttons) may be used regardless of the number of canvas elements placed on a page.
Installation on a web server requires copying the unpacked archive to a location that can be read by the server. No modifications of any of these files should be required, and the only permission required is read access. In some installations, it might be convenient to create a link to this directory.
Results and discussion
Included web pages
Several fully functional, sample web pages are included with this package that illustrate different ways that HTML pages can access this library. In the root directory of this package is a default web page named index.html, which demonstrates most of the main features of this library. By default, an image of the methane (CH4) molecule is displayed. A “browse” button is provided to allow the user to load files in the.xyz format, and a few sample files are included in the molecules subdirectory.
Figure 1 provides an illustration of images created by this program. The display of atomic labels, as shown in the structure of D-glucopyranose (upper left), is accomplished using the “Labels” button. Individual atoms, such as the carbon and nitrogen atoms of peptide bonds, can be highlighted (in light yellow) by holding down the [Shift] key when selecting an atom. In the image of zinc blende (lower right), “bonds” were created between the eight corner atoms to emphasize the unit cell in this structure.
A number of additional web pages are included in a subdirectory named “variations” that illustrate different ways that this library can be used. These include:
Pre-load: This simple page loads and displays the structure of a molecule from a file stored on the server. The name of this file is part of the web page HTML and cannot be changed by the user. While the molecule can be rotated and information displayed, the user cannot change this structure.
Chooser: This page allows the user to select the file to be viewed from a list of files stored on the server using either buttons or from a drop-down select list. While the molecule can be rotated and information displayed, the user cannot alter any of these structures.
Gallery: This page loads a list of files stored on the server and displays each of these in a separate division along with descriptions. Each of the molecules can be rotated independently and information displayed. However, the user cannot change any of these structures.
Viewer (only): This page allows loading and viewing of molecules from files stored on the user’s computer, but does not allow for any editing of these structures.
View 2 Windows: This page illustrates that more than one molecule can be loaded on a page. This page also does not allow for any editing of either structure. To switch between active windows, use the mouse to click on any portion of a drawing canvas.
Two Windows: This page illustrates that more than one molecule can be loaded on a page, and that these windows do not have to be the same size. In this view, both View Mode and Draw Mode are enabled, so either (or both) of the structures being displayed can be altered.
Creating web pages
Many of the CH5M3D library routines need to be run after the page has been read by the browser. This can be accomplished by adding the following line to the < body > statement:
As illustrated in Figure 2, the HTML code required to create simple web pages is minimal. The most important HTML5 element required to use this program is the Canvas object, which provides the drawing window for showing the molecule. This element must be given a unique identifier using the “id” tag. The dimensions of this canvas are set by the HTML declaration, and can be adjusted as desired. While a square canvas is usually preferred, the width and height are not required to be identical.
This is all the information required to create an interactive display, which by default will display the structure of the methane molecule. The first feature necessary to make this a useful application is the ability to load and view different structures. In some situations, it might be preferred to automatically load specific 3-dimensional molecular coordinates from files stored on the web server, while in other cases users could be given the option to load files stored on their computer. Currently, only.xyz files (such as those created by Open Babel ) containing cartesian coordinates are supported. A small selection of.xyz formatted files is available from the project home page, and the format of these files is described both in the documentation and on the Open Babel website.
Reading files from the user’s computer is accomplished using the HTML5 FileReader function. The ch5m3d.js initialize function creates a “listener” for an object with an id of “molfile”. When the user selects a file, the change in this object is detected and the appropriate routines are called to read and display the molecule. To implement this type of file reader on a web page, a statement similar to the following can be used, which will create a familiar “Browse” button allowing users to select any file stored on their computer. No filtering is performed, so users can select any type of file, including files that do not contain molecular coordinates and files in unsupported formats. Files with an incorrect extension are ignored with a warning message to the user.
We have described development of a library that allows for the easy creation of web pages providing the ability to display and edit both organic and inorganic molecular structures. Installation is simple and does not require any special permissions on the web server. Users benefit from not having to install any additional software, and the web pages are viewable on a wide range of browsers across different operating systems. While this library does not include as many features as more full-featured applications such as Jmol, this library is relatively small (≈ 75 kb) and can easily be extended to provide a range of capabilities. While the most recent version of this program is available on the project homepage, a demonstration of this program is available at the end of the full-text HTML version of this article [Additional file 1].
Availability and requirements
Abraham M, Varghese V, Tang H: Using molecular representations to aid student understanding of stereochemical concepts. J Chem Educ. 2010, 87 (12): 1425-1429. 10.1021/ed100497f.
Box VGS: Using molecular modeling to understand some of the more subtle aspects of aromaticity and antiaromaticity. J Chem Educ. 2011, 88 (7): 898-906. 10.1021/ed100408s.
McRae C, Karuso P, Liu F: ChemVoyage: a web-based, simulated learning environment with scaffolding and linking visualization to conceptualization. J Chem Educ. 2012, 89 (7): 878-883. 10.1021/ed200533u.
Libman D, Huang L: Chemistry on the go: review of chemistry apps on smartphones. J Chem Educ. 2013, 90 (3): 320-325. 10.1021/ed300329e.
Hanwell MD, Curtis DE, Lonie DC, Vandermeersch T, Zurek E, Hutchison GR: Avogadro: an advanced semantic chemical editor, visualization, and analysis platform. J Cheminformatics. 2012, 4: 17-10.1186/1758-2946-4-17.
ECCE - Extensible Computational Chemistry Environment. http://ecce.pnl.gov/,
Jensen JH, Kromann JC: The Molecular Calculator: A Web Application for Fast Quantum Mechanics-Based Estimation of Molecular Properties. J Chem Educ. 2013, 90 (8): 1093-1095. 10.1021/ed400164n.
JME Molecular Editor. http://www.molinspiration.com/jme/,
O’Boyle NM, Banck M, James CA, Morley C, Vandermeersch T, Hutchison GR: Open Babel: An open chemical toolbox. J Cheminformatics. 2011, 3: 33-10.1186/1758-2946-3-33.
The support of Kent State University at Stark is gratefully acknowledged.
The author declares that he has no competing interests.
About this article
Cite this article
Earley, C.W. CH5M3D: an HTML5 program for creating 3D molecular structures. J Cheminform 5, 46 (2013) doi:10.1186/1758-2946-5-46
- Molecular editor
- Molecular graphics