1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
|
<!DOCTYPE html>
<html>
<head>
<meta http-equiv="Content-type" content="text/html;charset=UTF-8">
<link rel="stylesheet" type="text/css" href="../ch5m3d.css" />
<title>CH5M3D</title>
</head>
<body >
<h1>About CH5M3D</h1>
<p> </p>
<p class="QCHeader">
<strong>CH<sub>5</sub>M<sub>3D</sub> Version 1.2.5</strong>
</p>
<p class="center">
<a href="http://sourceforge.net/projects/ch5m3d/"
name="SourceForge Project Homepage">Project Homepage</a>
</p>
<h3>Description</h3>
<p class="indent">
This program uses a combination of HTML5 and javascript to interactively draw 3-dimensional
structures of small molecules.
</p>
<h3>License</h3>
<p class="indent">
<div class="logo"><img src="gplv3-88x31.png" width="88" height="31" alt="GNU GPL Logo" /></div>
This program is free software: you can redistribute it and/or modify it under the terms of the
GNU General Public License as published by the Free Software Foundation, either version 3 of the
License, or (at your option) any later version.
</p>
<p class="indent">
This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even
the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU General Public License for more details.
</p>
<p class="indent">
To view a copy of the GNU General Public License, see
<a href="http://www.gnu.org/licenses/gpl.html">http://www.gnu.org/licenses/gpl.html</a>.
</p>
<h3 style="clear:both;">Author</h3>
<p class="author">
Dr. Clarke Earley<br />
Associate Professor of Chemistry<br />
Kent State University at Stark<br />
cearley@kent.edu
</p>
<h3>Acknowledgements</h3>
<p class="indent">
The support of Kent State University at Stark is gratefully acknowledged.
</p>
<p class="clear"> </p>
<h1>CH5M3D Overview</h1>
<p class="indent">
This web interface has been developed to allow users to create and visualize 3-dimensional drawings of simple
molecules without requiring the download of any additional software. In addition to creating structures, users
can also load existing XYZ formatted files (such as those generated by
<a href="http://openbabel.org/wiki/Main_Page">Open Babel</a>) containing 3-dimensional coordinates. A small
selection of .xyz formatted files is available from the
<a href="https://sourceforge.net/projects/ch5m3d/">project home page</a>.
</p>
<p class="indent">
Once molecules are created or read from a file, users can examine geometry information (bond lengths, angles,
and dihedral angles) and modify these structures. Routines to perform a crude geometry optimization and a simple
calculation of atomic charges are also available.
</p>
<p class="indent">
This web interface relies on HTML5 (in particular, the HTML5 Canvas), and as such requires a
<a href="browser.html">modern web browser</a> to run. The advantage of this approach is the no additional
plugins or Java is required to use this program. Support for mobile devices is currently only partially implemented,
but is planned to be included in future versions.
</p>
<h3>Screenshots</h3>
<div class="screenshot">
<a href="InitialView.png" name="Initial View of Interface">
<img src="InitialView_thumb.png" width="200" height="174" alt="Initial View of Interface" /></a><br />
Initial view of CH5M3D Interface
</div>
<div class="screenshot">
<a href="labels.png" name="Image with labels added" />
<img src="labels_thumb.png" width="200" height="178" alt="Image with labels added" /></a><br />
Image with labels added
</div>
<div class="screenshot">
<a href="highlighting.png" name="Image with highlighting" />
<img src="highlighting_thumb.png" width="200" height="160" alt="Image with highlighting" /></a><br />
Image with highlighting
</div>
<div class="screenshot">
<a href="DrawMode.png" name="Draw Mode Interface" />
<img src="DrawMode_thumb.png" width="200" height="170" alt="Draw Mode interface" /></a><br />
Draw Mode interface
</div>
<div class="screenshot">
<a href="charges.png" name="Example of charge calculation" />
<img src="charges_thumb.png" width="200" height="158" alt="Example of charge calculation" /></a><br />
Example of charge calculation
</div>
<p class="clear"> </p>
<h1>Installation</h1>
<p class="indent">
This "program" can be downloaded as a single zip file containing the following files.</p>
<ul>
<li><strong>index.html</strong> - The main HTML file loaded by a web browser.</li>
<li><strong>ch5m3d.js</strong> - The javascript code required to generate the web interface.</li>
<li><strong>ch5m3d.css</strong> - CSS code controlling the appearance of the web pages.</li>
<li><strong>documentation.pdf</strong> - A PDF version of the documentation.</li>
<li><strong>doc/</strong> - A directory containing html documentation files and the GNU license.</li>
<li><strong>molecules/</strong> - A directory containing a small number of .xyz formatted
files of molecular coordinates.</li>
<li><strong>variations/</strong> - A directory containing a few html files that illustrate different ways
that web pages can use the javascript code to provide different views.</li>
<li><strong>qchem/</strong> - A directory containing a php files and support files that provide a simple
front-end interface to the quantum mechanical program GAMESS. (Note that it is very unlikely that this
will work without modification).</li>
</ul>
<h3>Testing</h3>
<p class="indent">
A live version of this program is available at the
<a href="http://ch5m3d.sourceforge.net/">Project Web page</a> on SourceForge. Note that a
<a href="browser.html">suitable web browser</a> that supports HTML5 is required to run this program.
</p>
<h3>Installation on a Web Server</h3>
<p class="indent">
No special steps are required to install this program on a web server other than placing the "unzipped"
directory tree in a location where it can be accessed by the web server. All file locations are coded
as "relative" directories, so the actual path/directory location for these files does not matter.
<p class="indent">
If it is desired to change the relative location of any of these files, note that <strong>index.html</strong>
assumes that <strong>ch5m3d.js</strong> and <strong>ch5m3d.css</strong> are both located in the same directory
as <strong>index.html</strong>. All of the documentation files assume that <strong>ch5m3d.css</strong>
is located "up" one directory (../ch5m3d.css).
</p>
<h1>Supported Web Browsers</h1>
<p class="indent">
The interactive drawing window used on this website requires HTML5, which is NOT supported by version 8
or lower of Microsoft Internet Explorer. To use this site, you will need to use a browser that
supports the Canvas element and a few other features of HTML5. Listed below are several freely available
web browsers that should work with this interface.
</p>
<ul>
<li><a href="https://www.mozilla.org/en-US/firefox/new/">Mozilla Firefox</a> - Available for Microsoft Windows,
Apple, Linux, and Android.</li>
<li><a href="https://www.google.com/intl/en/chrome/browser">Google Chrome</a> - Available for Microsoft Windows,
Apple, Linux, Android, and iOS.</li>
<li><a href="http://www.opera.com/browser/download/">Opera</a> - While not as popular, is available for Microsoft
Windows, Apple, Linux, Android, and iOS.</li>
<li><a href="https://www.apple.com/safari/">Apple Safari</a> - Should already be installed on current Mac
computers.</li>
</ul>
<p class="indent">
Currently, touch screen devices are NOT fully supported by this interface. While the web page will load, several
important tasks do not function properly on tablets or other touch screen devices.
</p>
<h1>User Interface: View Mode</h1>
<p class="indent">
The image below shows the initial view that should be presented when this page is first loaded.
The most important sections are labeled in red. Upon initially loading this page, you should be
in <strong>View Mode</strong>, indicated by both the highlighted
<input type='button' value="View Mode" style="background-color: lightskyblue;"/>
<strong>[View Mode]</strong>
tab and the text "View Mode" displayed below this button. You can switch between
<strong>View Mode</strong> and <strong>Draw Mode</strong> at any time by selecting the appropriate tab.
</p>
<div style="text-align: center">
<img src="Areas.png" width="440" height="388"
alt="View Mode Interface with sections labeled" />
</div>
<p class="indent">
Initially, the methane molecule (CH<sub>4</sub>) should be displayed in the
<strong>Drawing Window</strong>. While in View mode, you can use your mouse/pointer to perform the
following tasks.
</p>
<ul>
<li><strong>Rotate Molecule</strong> - Move the pointer to any blank portion of the Drawing Window
and hold the mouse button down. Dragging the pointer should cause the molecule to rotate. To stop
rotation, simply release the mouse button. Simultaneously pressing <strong><Shift></strong>
while dragging the mouse pointer will cause the molecule to rotate around the z-axis. It is
also possible to 'translate' a molecule by pressing the <strong><Ctrl></strong> key
while dragging the mouse.</li>
<li><strong>Zoom</strong> - If a mouse scroll wheel is available, this can be used to either zoom-in
or zoom-out the current view.</li>
<li><strong>Identify Atom</strong> - Move the pointer over any atom in a molecule and click on this
atom to select. The Elemental symbol followed by a number should be displayed. The number is the
position of the atom in the set of coordinates for this molecule, starting at 1. If the
<input type='button' value="Charges" /> <strong>[Charges]</strong>
button is active, then the calculated charge on this atom will also be displayed.</li>
<li><strong>Highlight Atom</strong> - Move the pointer over any atom in a molecule, hold down the
<strong><Shift></strong> key and click on this atom. A semitransparent yellow circle should
appear over this atom. <Shift>-click on this atom a second time to turn off the highlight.
Any number of atoms may be highlighted. The
<input type='button' value="Reset View" /> <strong>[Reset View]</strong>
button may also be used to remove all highlights.</li>
<li><strong>Measure Bond Lengths</strong> - Move the pointer to the first atom of the bond and select.
The label for this atom should appear in the upper-right corner of the display window. Then, move
the pointer to the second atom and select this atom. The bond length (in Angstroms) will be shown
at the top right of the drawing window.</li>
<li><strong>Measure Bond Angles</strong> - By selecting three atoms, the bond angle (in degrees)
around the central atom (the second atom selected) will be shown.</li>
<li><strong>Measure Dihedral Angles</strong> - By selecting four atoms, the dihedral angle
(in degrees) will be shown. For example, if all four atoms lie in a plane, the dihedral angle will
be either 0° or 180°.</li>
</ul>
<p class="indent">
For all of the operations, clicking on a blank portion of the screen will clear the list of selected
atoms and allow you to start measuring a different set of lengths/angles. Clicking on the same atom
twice will cause the atom list to be reset and this selected atom will be placed as the first atom on
the list.
</p>
<p class="indent">
To the right of the <strong>Drawing Window</strong> are several buttons. These provide the following
options:
</p>
<ul>
<li><input type='button' value="Show coordinates" /> <strong>[Show coordinates]</strong>
This button will print the coordinates in .xyz format in the <strong>Information Window</strong>.
For security reasons, it is not possible for javascript to write files to a user's computer.
To save the coordinates of molecules created using this program, it is required that users open a
text editor, copy the coordinates from the <strong>Information Window</strong> into their editor
and save this as an .xyz file. When saving this file, but sure that it is saved as an unformatted
text file.</li>
<li><input type='button' value="Labels" /> <strong>[Labels]</strong>
This button toggles the display of labels (elemental symbols) for each atom.</li>
<li><input type='button' value="Charges" /> <strong>[Charges]</strong>
Selecting this button causes a crude computation of atomic charge to be performed. Charges are shown
as semi-transparent spheres around each atom. Negative charges are shown in red, and positive charges
are shown as blue spheres. The intensity of these colors is used to indicate the magnitude of the charges.
This charge calculation is based on a combination of formal charges and electronegativity differences.
In addition, the dipole moment of the molecule based on these approximate point charges is displayed in
the Information window near the bottom of the screen. Note that these calculated charges should <i>not</i>
be considered to be accurate values but instead treated as a crude, first approximation.</li>
<li><input type='button' value="Reset View" /> <strong>[Reset View]</strong>
This button centers and rescales the molecule to fit the display, and removes all highlights.</li>
<li><input type='button' value="Browse..." /> <strong>[Browse...]</strong>
By selecting this button, users can load .xyz formatted files. Files of this format can be generated
using the <a href="http://openbabel.org/wiki/Main_Page">Open Babel</a> program. A few sample .xyz files
are available in the <strong>molecules</strong> folder on the
<a href="http://sourceforge.net/projects/ch5m3d/files/">CH5M3D Web site</a>.</li>
</ul>
<p class="indent">
To <strong>save an image</strong> of a molecule, first rotate the molecule to get it into the desired
orientation. Then, perform a right-click using the mouse pointer and select "Save Image As...".
</p>
<h1>User Interface: Keyboard and Mouse</h1>
<p class="indent">
While most common operations can be performed using only a mouse, a few operations require a
combination of both keyboard and mouse. Note that these operations only work in <strong>View Mode</strong>.
Note that in these descriptions, the screen is assumed to show the X-axis (horizontal) and the Y-axid (vertical),
with the Z-axis coming "out" of this plane. The possible combinations and their results are outlined below.
</p>
<ul>
<li>Selecting a blank portion of the screen:<ul>
<li><strong>Mouse only</strong> - Dragging the mouse results in rotating the molecule around the
X- and Y-axes.</li>
<li><strong><Shift> + Mouse</strong> - Rotation will occur around the Z-axis.</li>
<li><strong><Ctrl> + Mouse</strong> - The molecule will be translated along the X- and Y-axes.</li>
</ul>
<li>Selecting a single atom:<ul>
<li><strong>Mouse only</strong> - The label for this atom is shown. (If the charges button is pressed,
the calculated charge on this atom is also shown).</li>
<li><strong><Shift> + Mouse</strong> - The selected atom is highlighted. If this atom is already highlighted,
this operation will cause the highlight to be removed.</li>
</ul>
</ul>
<p class="indent">
A
<input type='button' value="Reset View" /> <strong>[Reset View]</strong>
button is provided that will allow automatic re-scaling and re-centering of the molecule. This button will also
remove all highlights from the displayed structure.
</p>
<h1>Drawing Molecules</h1>
<p class="indent">
In Draw Mode, you have the option of adding or deleting atoms and/or bonds to any structure shown in the
display window. The image below shows the buttons initially displayed when first entering Draw Mode.
</p>
<p class="center">
<img src="DrawButtons.png" width="234" height="406" alt="Draw Mode Buttons" />
</p>
<h3>Rotating the Entire Molecule</h3>
<p class="indent">
In draw mode, you can rotate the molecule in the same manner as performed in View mode by selecting a
blank portion of the screen and "dragging" the pointer.
</p>
<h3>Adding Atoms</h3>
<p class="indent">
Initially, a subset of the periodic table is shown, with Carbon highlighted. To add a methyl group to the
methane molecule shown, click on any of the hydrogen atoms. By default, the atom added is assumed to be
sp<sup>3</sup> hybridized. To add a CH<sub>2</sub> group, select
<input type='button' value="sp2" /> <strong>[sp2]</strong>
before clicking on an H.
</p>
<p class="indent">
In general, clicking on any atom will convert the atom into the selected element type shown on the
periodic table. If the selected atom has only one bond, the new atom is added with a reasonable value
for the bond length and the appropriate number of hydrogen atoms added. If the selected atom has two or
more bonds, it is replaced with the new atom type, but bond distances are not changed and additional
hydrogen atoms are not added.
</p>
<p class="indent">
Hydrogen is an exception to this pattern. If H is selected on the periodic table, clicking on any atom
will add a single H atom (it will not replace the atom with H).
</p>
<h3>Adding Metals</h3>
<p class="indent">
Initially, only a subset of the periodic table is shown, with main group elements (excluding the noble gases)
displayed. To add any of the remaining elements, select the <strong>Metals</strong> link above Oxygen/Fluorine.
To revert back to showing only main group elements, select the <strong>Organic</strong> link.
<h3>Deleting Atoms</h3>
<p class="indent">
To delete an atom, select the
<input type='button' value="Delete Atom" /> <strong>[Delete Atom]</strong>
button, then click on the atom to be removed. This atom and any hydrogen atoms attached to this atom
should be removed.
</p>
<h3>Adding Bonds</h3>
<p class="indent">
To add a bond, place the pointer on the first atom and press down (but do not release). Drag the pointer
to the second atom, then release the mouse. A bond should be shown connecting these atoms. Note that when
adding bonds, the number of bonded atoms increases, so it may be necessary to delete one or more atoms.
</p>
<h3>Removing Bonds</h3>
<p class="indent">
Deleting bonds is done in a similar manner. Select
<input type='button' value="Delete Bond" /> <strong>[Delete Bond]</strong>,
then place the pointer on the first atom and press down (but do not release). Drag the pointer
to the second atom, then release the mouse. The bond connecting these atoms should be removed.
</p>
<h3>Rotating Around a Bond</h3>
<p class="indent">
It is also possible to rotate around bonds. To do this, first press the
<input type='button' value="Rotate Bond" /> <strong>[Rotate Bond]</strong>
button. Then move the mouse pointer over the first atom, press and hold the mouse button, "drag" to
the second bonded atom and release the mouse button. (Note that if the atoms are not bonded, rotation
will not behave as expected). A new view of the molecule will be displayed with the molecule oriented
so that you are looking "down" the selected bond. The second atom selected will be in front, eclipsing
the first atom selected.
</p>
<p class="indent">
To rotate around this bond, use the mouse pointer to select a blank portion of the drawing window and
"drag" the pointer while holding the mouse button down. To get out of bond rotation mode, press the
<input type='button' value="Rotate Bond" /> <strong>[Rotate Bond]</strong>,
which should change color to indicate that it is no longer active.
</p>
<h3>Undo</h3>
<p class="indent">
When significant changes are made to the molecule (atoms added, atoms deleted, rotation about bonds, etc.),
the molecular coordinates are saved. Currently, ten sets of saved coordinates are saved. Pressing the
<input type='button' value="Undo" /> <strong>[Undo]</strong>
button restores the most recent set of coordinates. This may be repeated up to the the limit of saved
sets of coordinates. There is also a
<input type='button' value="Redo" /> <strong>[Redo]</strong>
button, that reverses the effects of the <strong>Undo</strong>.
</p>
<h3>Structure Optimization</h3>
<p class="indent">
At the bottom of the Draw mode window is an
<input type='button' value="Optimize Structure" /> <strong>[Optimize Structure]</strong>
button. This button will cause a crude geometry optimization to be performed. It is not necessary to use
this, but it can be useful when significant changes have occurred. This is most common when H atoms have
been added or when bonds have been added or removed. At this point, the optimization routine is very crude,
and it may be necessary to optimize a structure multiple times before a reasonable structure is obtained.
</p>
<h1>File Format for Molecules</h1>
<p class="indent">
Currently, the only format supported by this program for reading molecular coordinates is the .xyz format.
These files can be created using the <a href="http://openbabel.org/">Open Babel</a> program. Sample files
in this format are available in the <a href="../molecules">molecules</a> directory.
</p>
<h3>Example</h3>
<p class="indent">
On the default page is a
<input type='button' value="Show coordinates" /> <strong>[Show coordinates]</strong>
button that displays coordinates for the current molecule in the information box at the bottom of the
screen. An example of the output produced for the methane molecule is:
</p>
<PRE><CODE>
5
CH4 (16.04 g/mol) in xyz format: From CH5M3D
C 0.0000 0.0000 0.0000
H 0.8740 0.6180 0.0000
H -0.8740 0.6180 0.0000
H 0.0000 -0.6180 0.8740
H 0.0000 -0.6180 -0.8740
</CODE></PRE>
<p class="indent">
The first line contains the number of atoms in the molecule.
</p>
<p class="indent">
The second line is a comment. This line must be present, but can be blank or contain any text.
</p>
<p class="indent">
The remaining lines contain the elemental symbol (1-3 characters) and x, y, z cartesian coordinates. All of these
values are separated by one or more spaces.
</p>
<p class="indent">
This program attempts to be flexible in reading these files, and does not require data to be present in specific
columns. The one restriction that is enforced is that files must be named with the extension ".xyz".
</p>
<h1>Description of Variations</h1>
<p class="indent">
The following files are provided with this distribution to illustrate different ways that this interface
can be used.
</p>
<h3>Pre-load</h3>
<p class="indent">
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.
</p>
<h3>Chooser</h3>
<p class="indent">
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.
</p>
<h3>Gallery</h3>
<p class="indent">
This page loads a list of files from the server and displays each of these in a separate division along with a
description. Each of the molecules can be rotated independently and information displayed. However, the user
cannot change any of these structures.
</p>
<h3>Viewer (only)</h3>
<p class="indent">
This page allows loading and viewing of molecules from files stored on the user's computer, but does not allow
for any editting of these structures.
</p>
<h3>View 2 Windows</h3>
<p class="indent">
This page illustrates that more than one molecule can be loaded on a page. This page also does not allow
for any editting of either structure. To switch between active windows, use the mouse to click on any portion
of a drawing canvas.
</p>
<h3>Two Windows</h3>
<p class="indent">
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 <strong>View Mode</strong> and <strong>Draw Mode</strong> are enabled, so
either (or both) of the structures being displayed can be altered.
</p>
<h3>Javascript</h3>
<p class="indent">
This page illustrates how a user might create a simple function that interacts with functions contained within
the CH5M3D library to gather information about the active molecule and interact with (alter) this structure. In
this example, mirror images of a chiral molecule are generated with the user chosing the mirror plane to use.
</p>
<h3>Quantum Chemistry Interface</h3>
<p class="indent">
This page illustrates a simple interface that has been used to create input files for the quantum mechanical program
<a href="http://www.msg.chem.iastate.edu/gamess/index.html">GAMESS</a>.
This page makes calls to several PHP files, and uses a very simple authorization scheme. To view this page, use the
username "<strong>admin</strong>" and the password "<strong>password</strong>".</p>
<p class="indent">
Because this interface makes calls to the underlying operating system, it is unlikely that this interface will work
without modification. All of the files used to create this page are located in the qchem subdirectory.
</p>
</body>
</html>
|
