Sketcher Canvas

The full web sketcher works in all browsers, including IE9, Safari, Opera, Chrome and Firefox, as well as Mobile Safari and Android Browser.

The SketcherCanvas component is a complete and full-featured chemical sketcher. It is built from the ChemDoodle desktop application and optimized for both browsers and mobile devices. This is the most professional web based sketcher available, and it is free and open source under the GPL license!

This page is more complex than others to cover the functionality of the sketcher. It is comprised of the following sections:

  1. Installation
  2. Initializing the Sketcher
  3. Additional Setup
  4. Using the Sketcher
  5. Sketcher Buttons
  6. Sketcher Shortcuts
  7. Mobile Option
  8. iChemLabs Cloud Services

Installation

To simplify the ChemDoodle Web Components library, the SketcherCanvas component is provided as a plugin. In order to use the SketcherCanvas class, you need to link a few additional files as URI resources on your webpage that are provided in the ChemDoodle Web Components download:

1
2
3
4
5
6
7
8
9
<!--these four are required by the ChemDoodle Web Components library-->
<meta http-equiv="X-UA-Compatible" content="chrome=1">
<link rel="stylesheet" href="[path]/ChemDoodleWeb.css" type="text/css">
<script type="text/javascript" src="[path]/ChemDoodleWeb-libs.js"></script>
<script type="text/javascript" src="[path]/ChemDoodleWeb.js"></script>
<!--these three are required by the SketcherCanvas plugin-->
<link rel="stylesheet" href="[path]/jquery-ui-1.8.7.custom.css" type="text/css">
<script type="text/javascript" src="[path]/jquery-ui-1.8.7.custom.min.js"></script>
<script type="text/javascript" src="[path]/ChemDoodleWeb-sketcher.js"></script>

The SketcherCanvas plugin is provided in the ChemDoodleWeb-sketcher.js file. This plugin requires one library, jQuery UI, that powers the interface elements of the sketcher. jQuery UI is composed of two parts, a CSS file and a Javascript file.

Icons and Images Folders

In addition to the three additional URI resources required by the sketcher, there are two folders of images provided in the sketcher folder of the download. The first folder is called images and contains the corresponding images for the jQuery UI CSS file. This folder should be placed in the same folder that the jQuery UI CSS file is placed on your server. The second folder is called icons and contains icons for the SketcherCanvas component, such as the button icons. This folder can be placed anywhere on your server, and then the path to this folder is specified in the SketcherCanvas constructor. Please note that the SketcherCanvas icons (in the icons folder) are iChemLabs Proprietary and may only be used in projects using ChemDoodle Web Components.

Initializing the Sketcher

The SketcherCanvas class is a child of the Canvas class, so working with it is the same as with working with any other Canvas in the ChemDoodle Web Components library. To initialize it, we just call its constructor, which places it into the HTML page:

1
new ChemDoodle.SketcherCanvas(name, width, height, iconPath, isMobile, useServices);

The parameters are defined as follows:

  • name – is the id of the <canvas> component in the HTML page.
  • width – defines the width of the SketcherCanvas in pixels.
  • height – defines the height of the SketcherCanvas in pixels.
  • iconPath – is a string and defines the path to the url on your server that contains the button icons for the sketcher. These icons are provided in the download.
  • isMobile – is a boolean and optimizes the SketcherCanvas for use on mobile devices; this feature is covered below.
  • useServices – is a boolean and should be true if you are registered with us to use iChemLabs cloud services to power popular sketcher features. If you do not want to use iChemLabs cloud services, then set this parameter to false, and any features that use iChemLabs cloud services will be removed from the sketcher interface. If you are an academic organization, we will provide free access to our services. Just contact us to register your origins (domains) with our server. Otherwise, our rates are very reasonable, please view our support options.

Additional Setup

In addition to just calling the constructor, you may wish to also set the following common sketcher options, which will change the graphics to suit user expectations. The following code is the exact code used to initialize the SketcherCanvas at the top of this page:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
<script>
  // changes the default JMol color of hydrogen to black so it appears on white backgrounds
  ChemDoodle.ELEMENT['H'].jmolColor = 'black';
  // darkens the default JMol color of sulfur so it appears on white backgrounds
  ChemDoodle.ELEMENT['S'].jmolColor = '#B9A130';
  // initializes the SketcherCanvas
  var sketcher = new ChemDoodle.SketcherCanvas('sketcher', 500, 300, '/resources/images/icons/', ChemDoodle.featureDetection.supports_touch(), true);
  // sets terminal carbon labels to display
  sketcher.specs.atoms_displayTerminalCarbonLabels_2D = true;
  // sets atom labels to be colored by JMol colors, which are easy to recognize
  sketcher.specs.atoms_useJMOLColors = true;
  // the following two settings add overlap clear widths, so that some depth is introduced to overlapping bonds
  sketcher.specs.bonds_clearOverlaps_2D = true;
  sketcher.specs.bonds_overlapClearWidth_2D = 2;
  // the component needs to be repainted here because we do not call the <em>Canvas.loadMolecule()</em> function
  sketcher.repaint();
</script>

You will notice a few things. First, we do not load a Molecule into the sketcher, although we can if we want to using the Canvas.loadMolecule() function, just like we would with any other Canvas. Because we do not call this function, we have to call the Canvas.repaint() function instead to update the drawing after changing the settings. Secondly, you will notice that there is a little circle in the middle of the sketcher. This is a carbon atom and defines the start of a structure; the entire ChemDoodle family of sketchers works in this fashion.

Using the Sketcher

The sketcher controls are modeled from the ChemDoodle desktop application. Those familiar with the ChemDoodle desktop application will immediately be comfortable drawing structures in a SketcherCanvas component.

The most basic sketcher input is received from mouse events. All aspects of the ChemDoodle desktop application are present, from locking bond lengths and angles, to the optimize zone to fragment previews. More information about how to use the ChemDoodle family of sketchers can be found in the ChemDoodle user guide.

In addition to mouse input, there are buttons and keyboard shortcuts that are described in the following sections.

It should also be noted that the SketcherCanvas component is optimized for drawing a single discrete molecule. There are not many websites that require the need to draw multiple discrete molecules at once, so a SketcherCanvas component allows one and only one structure to be drawn at any given time to simplify the application. Because there is only one molecule at a time, there is no need for a lasso function, as the molecule can be fully manipulated without it. This greatly simplifies a user’s experience and makes it much faster to draw molecules without confusing the user with unnecessary functions. If your site requires multiple molecules to be drawn at once, please contact us to discuss possible solutions.

Sketcher Buttons

The buttons presented on top of the sketcher provide functionality as described by the following list. It should also be noted, that in all states, the user can use the mouse wheel to scale the sketcher rendering. Users can also click and drag on the background, with nothing hovered, to move the entire molecule. If the shift key is held while dragging the background, the entire molecule will be rotated. Double-clicking on the background will center the molecule.


Open File – This button pops up a window that allows a user to paste in the contents of an MDL MOLFile to be loaded into the sketcher.


Save File – If iChemLabs cloud services are used, then this button will open a file dialog to allow users to save any of the 24 chemical file formats that ChemDoodle supports. Otherwise, this button pops up a window displaying MDL MOLFile content for the molecule in the sketcher that can be pasted into a text editor and saved with a .mol extension.


MolGrabber – This button pops up a window displaying a MolGrabberCanvas component that can be used to search the ChemExper, ChemSpider and PubChem databases for molecules of interest and then load them into the sketcher. This feature is only accessible through iChemLabs cloud services.


Zoom In – Increases the rendering scale of the sketcher.


Zoom Out – Decreases the rendering scale of the sketcher.


Clear – Clears the sketcher, leaving a single carbon atom.


Erase – Puts the sketcher into erase mode. Highlighting an atom and clicking will remove that atom and any small disconnected fragments, leaving the largest fragment remaining. Highlighting a bond and clicking will only have an effect if that bond is part of a ring, and in that case it will remove that bond.


Move – Puts the sketcher into move mode. Highlighting an atom or bond and then pressing the mouse down and dragging will translate those objects.


Clean – Cleans the structure in 2D. This feature is only accessible through iChemLabs cloud services.


Undo – Undoes the last performed action.


Redo – Redoes the last undone action.


Calculator – Calculates various descriptors for the drawn structure. This feature is only accessible through iChemLabs cloud services.


Labels – After an element has been selected, hover an atom and click to change that atom’s label to the selected element symbol.


Periodic Table – Pops up a periodic table to select a symbol. After a symbol has been selected, hover an atom and click to change that atom’s label to the selected element symbol. Press the Close button to close it.


Bonds – After a bond type has been selected, hover an atom and press the mouse down to begin drawing a new bond of that type. Drag and place the preview to the preferred position and then release the mouse to place the bond. The optimize zone (blue circle) is provided to help place the bond in the optimal position when the mouse pointer is within the bounds of the circle. Hover a bond and click to change that bond’s type to the selected type. The single bond tool is special and will add to bond orders instead of overriding them. Hold down the shift key to modify standard lengths and hold down the alt key to modify standard angles.


Rings – After a ring type has been selected, hover an atom and press the mouse down to begin drawing a new ring of that type. Drag and place the preview to the preferred position and then release the mouse to place the ring. The optimize zone (blue circle) is provided to help place the ring in the optimal position when the mouse pointer is within the bounds of the circle. Hover a bond and press the mouse down to begin drawing a ring from that bond. Drag the preview to either side of the bond and then release the mouse to place the ring. Hold down the shift key to modify standard lengths and hold down the alt key to modify standard angles.


Charges – After a charge sign has been selected, hover an atom and click the mouse to add or subtract from that atom’s charge amount.


Lone Pairs – After a lone pair icon has been selected, hover an atom and click the mouse to add or remove a lone pair from that atom.

Group Buttons

At the end of some button groups, there is a small button with a downwards facing arrow. This means that there are more options available for this button set. Just click on this downwards facing arrow and select an option. The button adjacent to the downwards facing arrow will pick up this option and will be automatically selected for use.

Sketcher Shortcuts

Just like in the desktop version of ChemDoodle, the SketcherCanvas implements a copious amount of keyboard shortcuts. In addition to the listed shortcuts, you can also use the arrow keys to nudge the molecule. All keyboard shortcuts will work regardless of the state or mode the sketcher is in.

Modifier Shortcuts

Modifier shortcuts are executed by holding down the system meta key, which is ctrl on Windows and Linux and command on Mac OS X.

n Clears the sketcher, leaving a lone carbon atom.
o Pops up a window to load a chemical file.
s Pops up a window to save the structure in the sketcher in a chemical format.
y Redoes the last undone action.
z Undoes the last performed action.
+ Zooms in.
- Zooms out.

When Atoms are Hovered

When an atom is hovered, the following shortcuts will be active. An atom is hovered if the mouse is close enough to the atom such that the atom is surrounded by an amber circle.

Alphabet Cycles the hovered atom’s label through the element symbols that begin with that letter of the alphabet.
Digits Adds a carbon chain with length equal to the digit pressed in the most optimal orientation. The 0 key will add a chain of length 10.
Shift+Digits Adds a ring with number of sides equal to the digit pressed (3+) in the most optimal orientation.
Delete/Backspace Removes the current atom and any attached bonds and any small attached fragments, leaving the largest fragment remaining.
+/- Increase/Decrease the charge amount of the atom.

When Bonds are Hovered

When a bond is hovered, the following shortcuts will be active. A bond is hovered if the mouse is close enough to the center of the bond such that the bond is encapsulated by two amber semicircles.

Digits Changes the bond’s order to the digit. Only 1-3 work.
Shift+Digits Adds a ring with number of sides equal to the digit pressed (3+) in the most optimal orientation.
Delete/Backspace Removes the current bond if and only if that bond is a member of a ring.
f Flip the bond orientation.

Mobile Option

While we have discussed desktop-based implementation of the SketcherCanvas component, this class is also optimized for mobile use. In mobile browsers, there is no such thing as a hover event, so the SketcherCanvas class makes some changes to allow users to draw molecules by touching the screen. The SketcherCanvas class also implements gesture events that allow for much more complex functionality. This includes the pinch gesture, which will scale the molecule and the twist gesture, which will rotate the molecule.

To optimize the SketcherCanvas component for mobile devices, you need to pass in a true value for the isMobile parameter in the constructor. You may have noticed that we sent in the result of the ChemDoodle.featureDetection.supports_touch() function for this parameter. This function checks if the browser supports touch events, and if it does, is a mobile browser.

Just go to this page on your iPad, iPhone or Android device to test the sketcher above for mobile interfaces.

iChemLabs Cloud Services

The ChemDoodle Web Components library has full access to the entire ChemDoodle API through AJAX. Therefore, any and all functionality provided in the desktop version of ChemDoodle is instantly accessible through this library. Some of the functions in the sketcher take advantage of this, such as the clean function. If you have any requests for specific functionality that is not currently provided, view our support options for custom development.

In order to use iChemLabs cloud services, your origins (domains) must be recognized by our servers. If you are an academic organization, we will provide free access to our server resources. Just contact us to register your origins with our server. Otherwise, our rates are very reasonable, please view our support options and begin accessing the ChemDoodle API today!

In addition to accessing our servers, our customers get priority feature requests, priority support, free custom development quotes and access to our development builds. Don’t miss this chance to participate in the next generation of chemical informatics on the web. Contact us now.