Chemtool(5 Apr 2002)

NAME
Chemtool Version 1.5

SYNOPSIS
chemtool [<filename>]

DESCRIPTION
Chemtool is a program for drawing organic molecules and exporting them as a X bitmap, PicTeX, Xfig, SVG, MDL or EPS file. It runs under the X Window System using the GTK widget set.

An older version (1.1.8) that requires only the standard Athena Widget Set (Xlib) is still available for situations where GTK cannot be installed for some reason. In principle, all features added since 1.1.8 could be back-ported to the Xlib-based version if necessary.

USAGE
In all drawing and editing modes, mouse button one (usually the left button) is used to mark or draw objects, while button three (the right button) can be used to delete objects of the current type. The middle button is mainly used in the bond drawing modes where it allows fast changing of bondtypes. Starting with version 1.5, the default storage directory for datafiles, and the filename extension to use, can be saved via a configuration dialog. Drawing of bonds:

Bonds can be drawn in 4 different angle settings (hexagon with 30deg. intervals, two pentagons with 72deg. intervals (different orientation), and a 45deg. i octagon). (Intermediate angles are possible in all of these modes as well - just ignore the marker points in this case).

All bonds are initially drawn as single lines (or the linetype that is preselected from the pull-down menu of bond types in the menubar) that can be converted to other types later. Pressing the middle mousebutton on a bond increments its type code (see below), while pressing the third (usually the right) button deletes the bond next to the cursor position. The available bond types are :

single bond

double bond

double bond (shorter line on the other side)

centered double bond

triple bond

wedge-shaped bond

dashed wedge-shaped bond

wavy line

half arrow

regular arrow

wide bond

circle

dotted line

overlapping single bond (which cuts out a segment from any bond it crosses)

Semiaumomatic drawing of rings:

Rings of 3 to 12 members can be drawn easily by holding down the Ctrl key while drawing a line. This line will then become the first segment of a ring that is automatically drawn in clockwise direction. The size of the ring defaults to that appropriate for the selected drawing mode (i.e. 5, 6 or 8 sides), but it can be set on a per-ring basis by pressing Ctlr-<number> before drawing the ring, where numbers 3-9 correspond to 3 to 9-membered rings, while 0 to 2 select 10, 11 and 12-membered rings, respectively.

Newly drawn rings can be deleted by pressing Ctrl and mouse button 3 together.

Drawing of curved lines:

Curved lines for objects like arrows or orbital lobes can be drawn in spline curve mode by specifing four control points that form a bounding polygon (startpoint, two points on either side of the peak, endpoint). Of the regular bondtypes available in the Style menu, the 'single line', 'semiarrow', arrow and 'dashed line' retain their usual function, while the 'wide line' type is used to denote a filled polygon. The control points are only visible in Move mode, where they can be dragged around to change the form of a curve after it is drawn.

Setting bond style:

In bond style mode, clicking on any bond in the diagram changes its representation to the type selected in the pull-down menu next to the The additional bond type available in the pulldown menu,
    curved arrow
is only available for drawing. It is actually a shortcut for one of the curve drawing functions described above, with the second and third control points automatically generated. As such, it can not be converted to or from any of the conventional bond types. (One can, however, convert it to any of the other curve types, e.g. to change the type of arrowhead). The shape of the arrow will usually need to be adjusted by shifting the control point that appears alongside it in 'Move' mode. Inserting text: Text written into the text box can be positioned with the cursor and may appear left, middle or right-aligned in the drawing. There are two special characters to be used for sub- and superscripting the following character:
        '^' to shift up     (e.g. N^+)
        '_' to shift down    (e.g. CH_3)
The control character '|' is used to itializise the following character, as in |t-Bu.

A bold fonttype, typically used for numbering compounds, can be selected by preceding the character with a '#'.

The special character '@' switches to symbol mode, which uses the standard X11 symbol font. All alphabetic keys produce the corresponding greek characters in this mode, and several other symbols are available if their standard latin1 equivalents are already mapped onto the keyboard:
    yen -> infinity hyphen -> uparrow macron -> downarrow

The symbols 'plusminus' and 'registered' (trademark) are already in the standard font, although they are not normally available on the keyboard. Use the following commands (or add the declarations to your .xmodmaprc ) to make them available via <AltGr>+<Key> (<RightAlt>+<Key>):
             xmodmap -e 'keysym r = r R registered' \
             -e 'keysym o = o O yen' \
             -e 'keysym p = p P plusminus' \
             -e 'keysym u = u U hyphen' \
             -e 'keysym d = d D macron'
(this leads to AltGr-P = plusminus, AltGr-R = registered in normal mode and AltGr-O = infinity, AltGr-U = uparrow, AltGr-D = downarrow in symbol font).

For 'dots-and-crosses' diagrams, the following mappings to the symbol font might be useful: acute -> cross (e.g. keysym x = x X acute) middle dot -> filled dot (e.g. keysym d = d D periodcentered) (using the degree sign for the open dot).

When you want to use symbols as sub- or superscripts, place the sub- or superscripting character before the '@' character, e.g. K_@a . Centering: If there is not enough space for your molecule you can put it in the middle of the sheet with the center button. Exporting to foreign formats: You can export your molecules as an X bitmap, an encapsulated postscript file, an input file for Brian Smith' XFig program, an MDL ver. 2000 molfile for data exchange with commercial packages, an SVG file for XHTML web pages, or in the PicTeX format for direct inclusion in LaTeX documents. The PicTeX and Postscript output functions rely on the fig2dev program from the transfig package.

You can create the outputs in different sizes according to the current zoom scale. Postscript and PicTeX files can also be created at arbitrary scales selectable on the export file menu.

To include the PicTeX-file in your LaTeX document, you will need the pictex macro package. Depending on the versions you use, you might also have to load the 'color' package in the preamble of your LaTeX file. If you experience 'TeX capacity exceeded' error messages, increase the extra_mem_bot parameter in your texmf.cnf file (usually in /usr/share/texmf/web2c, /usr/local/texmf or /etc/texmf). Pictex is known for its unusual (by tex standards) memory requirements, and the standard settings do not account for this (although you may find a comment a la 'change this if you use pictex' in the texmf.cnf file). Something like extra_mem_bot=400000 should not hurt on any moderately modern system. Printing drawings: Since version 1.5, direct printing of diagrams to a Postscript-capable printing device (or more typically a print queue running ghostscript) is possible. The paper size, magnification, printer name and the print command to use (currently either lp or lpr) can be stored in the Configuration Dialog. Selecting all or parts of a drawing for transformations: Using the 'Mark' button, you can easily select parts of the current drawing by enclosing them with a 'rubberband' rectangle. The selected parts will appear highlighted in blue and are immediately available for

moving:
    simply drag the fragment to the desired position with the mouse while holding down the left mouse button

rotating:
    horizontal movement of the mouse translates to smooth rotation around the pivot point selected when pressing the mouse button

flipping
    (mirroring) the fragment about a horizontal or vertical mirror plane through its center: this is performed by clicking on the appropriate menu button

copying
    clicking on the 'Copy' menu button creates an exact copy of the selected fragment slightly offset to the original. The mark is automatically transfered to the new copy.

rescaling:
    horizontal mouse movement is translated into a smooth increase or decrease of size of the marked fragment

deleting
    to delete the marked fragment, simply click the third (usually the right) mouse button after it is highlighted.

optimizing:
    clicking on the 'bucket and broom' symbol invokes a function that removes overlapping (duplicate) bonds and labels from the drawing.

Adding previously saved figures: To add another molecule from a previously saved chemtool drawing, select it in the file selection window that comes up when you press the 'Add' button. Single clicking on any filename in the list displays a small preview of the molecule to aid in selection. The newly added molecule is automatically made active so that it can be repositioned as desired. Adding one of the predefined templates: Pressing the 'Templates' button opens a second window with a small collection of predefined structures. Simply click on the preview of the desired molecule to add it to your drawing. The Template window can be kept open throughout a chemtool session - if it is hidden by another window, you can move it to the front by clicking the 'Template' button in chemtool again. The data in the template system differ from normal chemtool drawings only by the fact that they are stored within the program, and in a slightly awkward format (x and y coordinates listed separately in the source file templates.h). These are meant to provide a convenient basis set available to all users, but not individually extendable (you can use the 'Add' function for your own structures). Please let us know if you want specific molecules added to the templates - their name or ideally a regular chemtool drawing file is all we need. (send email to martin@ruby.chemie.uni-freiburg.de) Importing foreign file formats: Chemtool provides functions for importing files in both the PDB format used by the Protein Database (and by most molecular modeling packages) and the proprietary MDL molfile format used by ISISdraw and understood by other structure drawing packages and database frontends. As both are 3D file formats, while chemtool only handles 2D projections, imported molecules are read into a temporary storage at first and displayed in blue on the canvas. This 3D representation can then be rotated using the mouse. Only after pressing the Return key on the keyboard is it converted into the final 2D projection that can be edited. While such a 3d import is in progress, all normal drawing and editing functions are disabled. With MDL molfile import, the carbon atom labels are automatically discarded. For PDB import, the amount of labeling can be chosen in the file selection dialog, which offers retention of either all labels, only those of non-hydrogen atoms, or only the non-numeric part of the labels. Determining sum formula and molecular weight: Since development version 1.3a7, the distribution contains a helper program, cht, by Radek Liboska (Prague) to calculate sum formula and (exact) molecular weight from a chemtool drawing file. It is also available from within chemtool to calculate these data for the current structure or a marked fragment of it. Cht can be misled by duplicate bonds ( chemtool does not remove overlapping bonds, such as they might result from fusing ring systems, automatically) and by the 'aromatic ring' symbol, so you should avoid these and check the plausibility of the generated sum formula where possible. Drawing functions not available within Chemtool: For features not currently supported by chemtool, like color or general line-drawing functions, getting Brian Smith's XFig drawing package from www-epb.lbl.gov/xfig is highly recommended. About the only thing it does not offer is support for 'chemical' linetypes and drawing angles - which is why chemtool was written as a sort of companion program. (There will probably be more of the most sorely needed drawing options added to chemtool over time, but duplicating the more general-purpose features of xfig seems rather pointless.)

LICENSE
Chemtool and its companion program Cht are available under the terms of the GNU General Public License (see the file 'COPYING' in the package). This software comes with ABSOLUTELY NO WARRANTY.

AUTHORS
Thomas Volk (original author and maintainer up to 1.1.1) Thomas.Volk@student.uni-ulm.de Dr. Martin Kroeker (maintainer and primary author since 1.1.2) martin@ruby.chemie.uni-freiburg.de or mk@daveg.com Radek Liboska, PhD liboska@uochb.cas.cz Michael Banck mbanck@gmx.net
Webpage:    http://www.uni-ulm.de/~s_tvolk
Alternative site and Development versions: http://ruby.chemie.uni-freiburg.de/~martin/chemtool/chemtool.html

SEE ALSO
cht(1), xfig(1), transfig(1)