Ubuntu Manpage: chemtool - chemical structures editor

NAME

       chemtool - chemical structures editor

SYNOPSIS

       chemtool [filename]

DESCRIPTION

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

       The  program  offers  essentially  unlimited undo/redo, two text fonts plus symbols, seven
       colors, drawing at several zoom scales, and square and hexagonal backdrop grids for easier
       alignment.

EXAMPLES

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 30° intervals, two
pentagons with 72° intervals (different orientation), and a 45° i octagon). (Intermediate
angles are possible in all of these modes as well - just ignore the marker points in this
case).

The bond style chooser in the center of the button bar determines the type of bond that is
drawn - initially, this is a single bond. If you want to change the type of a bond later,
either click on it with the middle button of your mouse to advance to the next type(s), or
select the appropriate type in the chooser and then switch to bondtype mode and pick all
bonds that you want to change over to the new type. (The color used for the bond is
updated at the same time if necessary.) Pressing the middle mousebutton on a bond when in
'Bondtype' mode reverses the direction of that bond.

Using the third (usually the right) mouse 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 (flanking lines shorter than central)

• triple bond (with equal line lengths)

• quadruple 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)

• light pi orbital lobe

• dark pi orbital lobe

Semiautomatic 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
specifying 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 Type button.

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. Text size and color is selectable from a fixed
list of choices. 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 italicise 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).

Circled versions of the plus and minus signs for denoting ionic charge are available as @+
and @- .

When you want to use symbols as sub- or superscripts, place the sub- or superscripting
character before the '@' character, e.g. K_@a .

In text mode, the right mouse button deletes the label at the cursor position. Changing
the size, font or color of a label can be done by left-clicking on it after choosing the
desired combination of settings. When the text entry box above the drawing area is empty,
only the settings are updated without changing the contents of the label, otherwise the
label text is replaced as well. If you want to copy the text of an existing label to the
text entry box, click on it with the middle mouse button.

Labeling shortcuts
In all bond drawing modes, several keyboard shortcuts are available to add atom symbols
without having to leave drawing mode. The label is placed at the current drawing position
(the endpoint of the last line drawn, or the spot last clicked on).

The keys 'c','h','n','o','s','p' and 'r' insert the corresponding capital letter, 'l'
(lowercase L) inserts 'Cl', while '1', '2', '3' insert CH,CH_2 and CH_3, respectively. The
asterisk key (*) inserts a filled circle.

Pressing the space bar once allows you to enter arbitrary labels, which will be placed at
the current position when you press the Return key.

Drawing electron pairs
The keys of the numeric keypad can be used to draw short 'electron pair' lines next to an
element symbol - if one imagines the element symbol to be sitting on the central '5' key,
each key draws the appropriate electron pair for its position. When used together with the
Shift key, two dots are drawn instead of a line - simply delete one of the dots again if
you need an odd number of electrons.

Numbering atoms
For quick numbering of the atoms in a molecule, switch to one of the text modes, hold down
the Control key and pick each atom in succession with the left mouse button. Numbering
starts at 1, and the sequence can be reset at any time by clicking the right mouse button.
If you need to use your own numbering scheme, clicking the middle button (while still
holding down the Control key) makes it pick up whatever number is in the text entry field.

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, a PNG or EMF image, an encapsulated
postscript file, an input file for Brian Smith' xfig(1) 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, PNG, EMF and
Postscript output functions rely on the fig2dev81) program from the transfig(1) package
and are only available when this program was detected on startup. If the fig2sxd(1)
program is installed, an additional export option is available for OpenOffice SXD format.
Likewise, if the (open)babel program is installed, an additional Export menu providing
access to all filetypes supported by this tool becomes available.

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.

An option in the configuration menu can be set to call fig2dev in international language
mode, which will automatically render any text written in the alternate (Times) font using
the postscript font appropriate for the current locale (currently Croatian, Cyrillic,
Czech, Hungarian, Japanese, Korean, Polish). See the fig2dev documentation for details.

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(1), lpr(1)
or kprinter(1)) 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.

If you need to add atoms outside of the rectangular area to your selection, simply draw
another rubberband around them while holding down the Ctrl key.

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. (If you only need to move individual atoms or
bonds, you can simply pick and drag them in 'Move' mode without having to mark
them first).

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
transferred 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.

framing choosing one of the icons from the drop-down list of frame and bracket styles
draws the corresponding object, e.g. a pair of round parentheses, around the
highlighted fragment.

optimizing clicking on the 'bucket and broom' symbol invokes a function that removes
overlapping (duplicate) bonds and labels from the drawing and straightens
lines that are almost horizontal or vertical.

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.

If you want to add it to a predefined position on another molecule, you can mark that
attachment site by left-clicking on it instead of dragging the marker rectangle. A small
green dot will appear at what is now the reference position for the new part. If you save
molecules with such a marker set, it will in turn define their attachment site when they
are added to another drawing.

Adding one of the predefined templates:
Selecting 'Templates' from the 'Tools' menu opens a second window with a small collection
of predefined structures. Simply click on the image 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 selecting the 'Template' menu
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.

If the program babel is installed - either the original version written by Pat Walters or
the more recent OpenBabel effort - chemtool will automatically offer a menu option for
importing from any of the file formats this supports.

Determining sum formula and molecular weight:
The distribution contains a helper program, cht(1), 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 general line-drawing functions,
getting Brian Smith's XFig drawing package 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