Tutorial > Editor3D Canvas

The 3D Editor works in all browsers, including IE11+, Edge, Safari, Opera, Chrome and Firefox, as well as Mobile Safari and Chrome for Android.

The EditorCanvas3D component is a tool for viewing and manipulating 3D structures with an interface. It is built from the ChemDoodle desktop application and optimized for both desktop browsers and mobile devices. This is the most professional web based 3D editor tool available, as expected from the universal chemical drawing standard, and it is free and open source under the GPL license!

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

1. Installation
2. Initializing the 3D Editor
3. Options
4. Additional Setup
5. Mobile Support
6. iChemLabs Cloud Services
7. Input/Output of Complex Content
8. User Guide

Installation

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

<!--these two are required by the ChemDoodle Web Components library-->
<link rel="stylesheet" href="[path]/ChemDoodleWeb.css" type="text/css">
<script type="text/javascript" src="[path]/ChemDoodleWeb.js"></script>
<!--these two are required by the EditorCanvas3D plugin-->
<link rel="stylesheet" href="[path]/jquery-ui-1.11.4.custom.css" type="text/css">
<script type="text/javascript" src="[path]/ChemDoodleWeb-uis.js"></script>

The EditorCanvas3D class is provided in the ChemDoodleWeb-uis.js file. This plugin requires one library, jQuery UI, that powers the interface elements of the 3D editor. jQuery UI requires the CSS file provided and the JavaScript library is included in the ChemDoodle scope through the ChemDoodleWeb-uis.js file.

jQuery UI Image Folder

In addition to the three additional URI resources required by the 3D editor, there is one folder of images provided in the uis folder of the download. This 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.

3D Editor Toolbar Icons

The icons for the 3D editor are embedded directly in the ChemDoodleWeb-uis.js file source itself as data URIs, so there is no need to host those images. Please note that the ChemDoodleWeb-uis.js icons (that you see in the toolbars) are iChemLabs Proprietary and may only be used in projects using ChemDoodle Web Components.

Initializing the 3D Editor

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

new ChemDoodle.EditorCanvas3D(name, width, height, options);

The parameters are defined as follows:

• name - is the id of the <canvas> component in the HTML page.
• width - defines the width of the EditorCanvas3D in pixels.
• height - defines the height of the EditorCanvas3D in pixels.
• options - is an object that contains the option name/value pairs, as covered in the next section.

Options

The options object is just a generic object that contains names and values for options. It is created in the following way:

<script>
  let obj = {option1:value1, option2:value2};
</script>

You can include the right side of the assignment directly in the EditorCanvas3D constructor.

The following options are controllable:

• isMobile - is a boolean and optimizes the EditorCanvas3D for use on mobile devices; if not declared, this option will automatically default to the appropriate value by checking the ChemDoodle.featureDetection.supports_touch() function; only set this if you are forcing behavior (for debugging for instance).
• useServices - is a boolean and should be true if you are registered with us to use iChemLabs cloud services to power popular 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 3D editor interface. If you are an academic organization, we will provide free access to our services. Otherwise, our rates are very reasonable, please contact us for options. By default this is false.
• includeToolbar - is a boolean and is true by default. Set this to false to remove the toolbar, such as when creating your own interface to the EditorCanvas3D <canvas> (such as in a mobile app).

Additional Setup

In addition to just calling the constructor, you may wish to also set the following common 3D editor options, which will change the graphics to improve the user experience. The following code is the exact code used to initialize the EditorCanvas3D at the top of this page:

<script>
  // initialized the EditorCanvas3D
  let editor = new ChemDoodle.EditorCanvas3D('editor', 500, 300, {useServices:true});
  // set the default representation to 'Ball and Stick'
  editor.styles.set3DRepresentation('Ball and Stick');
  // if you changed the scene and need it rebuild, you may also want to call setupScene() which is commented out here
  // editor.setupScene();
  // however, you can instead use one of the Canvas.load... functions to pre-populate the canvas with content, then you don't need to call repaint
  editor.repaint();
</script>

We do not preload a Molecule into the 3D editor, 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.

Mobile Support

While the 3D editor is modeled after the popular ChemDoodle desktop application, we have also spent a lot of time and effort optimizing the 3D editor for mobile use. In mobile browsers, there is no such thing as a hover event, so the EditorCanvas3D class makes some changes to allow users to interact with molecules by touching the screen. The EditorCanvas3D class also implements gesture events that allow for much more complex functionality. This includes the pinch gesture, which will scale the content.

Of course, everything works intuitively and is easy to learn. Just go to this page on your WebGL enabled iPad, iPhone or Android device to test the 3D editor 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 3D editor take advantage of this, such as the clean function. If you have any requests for specific functionality that is not currently provided, please view our support options.

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. Otherwise, our rates are very reasonable, please contact us for options and begin accessing the ChemDoodle API today!

In addition to accessing our servers, our customers get priority feature requests, priority support and access to our development builds. Don't miss this chance to take advantage of the universal chemical drawing standard. Contact us today.

Input/Output of Complex Content

To handle the input and output of complex content, you should use the native ChemDoodle JSON format. This format is covered in detail here.

User Guide

For user instructions to draw structures and figures with the ChemDoodle Web 3D Editor, please see the 3D Editor demo.