| 1 |
<?xml version="1.0" ?> |
| 2 |
<!DOCTYPE html |
| 3 |
PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" |
| 4 |
"DTD/xhtml1-strict.dtd"> |
| 5 |
|
| 6 |
<html xmlns="http://www.w3.org/1999/xhtml"> |
| 7 |
<head> |
| 8 |
<link href="css/style.css" rel="stylesheet" type="text/css"/> |
| 9 |
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8"/> |
| 10 |
<title>Creating custom templates</title> |
| 11 |
</head> |
| 12 |
<body> |
| 13 |
<h2>How to run BKChem from outside</h2> |
| 14 |
|
| 15 |
<p>Starting from version <b>0.9.0-pre1</b> it is possible to import bkchem from |
| 16 |
a script and operate it from outside. This short article should help you getting started.</p> |
| 17 |
|
| 18 |
<h3>Word of warning</h3> |
| 19 |
<p>The possibility to run bkchem from a script adds the used a really powerful tool. |
| 20 |
However, keep in mind that the API is not yet very stable, badly documented and many convenience |
| 21 |
features are missing. Therefore you should be warned that it might be very |
| 22 |
frustrating to write such scripts and they may even not work with further versions on BKChem.</p> |
| 23 |
|
| 24 |
|
| 25 |
<h3>Creating the simple script</h3> |
| 26 |
|
| 27 |
<p>I will demonstrate the process in calling bkchem from outside on a simple script. |
| 28 |
It will take a filename of a bkchem file from the command line, open it, recolor all |
| 29 |
double bonds to red, save the result and quit. You can find the script |
| 30 |
<a href="scripts/script1.py">here</a>.</p> |
| 31 |
|
| 32 |
<p>At the very beginning of the script we just check for the filename to process:</p> |
| 33 |
|
| 34 |
<pre> |
| 35 |
import sys |
| 36 |
|
| 37 |
# at first we check the command line |
| 38 |
if len( sys.argv) <= 1: |
| 39 |
print "you have to supply a filename" |
| 40 |
sys.exit() |
| 41 |
</pre> |
| 42 |
|
| 43 |
<p>The most important part comes now - it shows the general approach |
| 44 |
to the problem of calling bkchem from another application:</p> |
| 45 |
|
| 46 |
<pre> |
| 47 |
# then we import bkchem and threading |
| 48 |
from bkchem.bkchem import bkchem |
| 49 |
import threading |
| 50 |
|
| 51 |
# bkchem.myapp is the application instance |
| 52 |
app = bkchem.myapp |
| 53 |
|
| 54 |
# we need to set batch mode = 1 if we want to suppress some interactive warnings, |
| 55 |
# questions and mouse events |
| 56 |
app.in_batch_mode = 1 |
| 57 |
|
| 58 |
# now we start the application in a separate thread to be able to manipulate it |
| 59 |
t = threading.Thread( target=app.mainloop, name='app') |
| 60 |
t.setDaemon( 1) |
| 61 |
t.start() |
| 62 |
</pre> |
| 63 |
|
| 64 |
<p>The initial import depends on how you have installed BKChem. You can either make a symlink |
| 65 |
or copy of the entire bkchem tree to the directory where this script is saved or you |
| 66 |
can do a source code installation (on linux) and the package will be found by python automatically. |
| 67 |
In the former case the import shown above applies, in the latter the import statement is only |
| 68 |
<i>from bkchem import bkchem</i> (because only part of the directory tree is saved under |
| 69 |
the python site-packages directory).</p> |
| 70 |
|
| 71 |
<p>Because bkchem is a Tkinter application it has its own mainloop that runs all the |
| 72 |
time the application exists. Therefor you have to run it in another thread in order to |
| 73 |
be able to use it. Some other remarks are in the comments.</p> |
| 74 |
|
| 75 |
<p>The code that does the actual work is pretty simple and straightforward:</p> |
| 76 |
|
| 77 |
<pre> |
| 78 |
# here comes the actual code |
| 79 |
|
| 80 |
# we load the file |
| 81 |
app.load_CDML( sys.argv[1]) |
| 82 |
|
| 83 |
# we take all molecules from the current paper, find all the double bonds, |
| 84 |
# change their color to red and |
| 85 |
for mol in app.paper.molecules: |
| 86 |
for bond in mol.bonds: |
| 87 |
if bond.order == 2: |
| 88 |
bond.line_color = "#aa0000" |
| 89 |
bond.redraw() |
| 90 |
|
| 91 |
# finally we save the result and quit |
| 92 |
app.save_CDML() |
| 93 |
app.destroy() |
| 94 |
</pre> |
| 95 |
|
| 96 |
<p>We load the file, do the transformation, save the file and quit.</p> |
| 97 |
|
| 98 |
<h3>Last word</h3> |
| 99 |
|
| 100 |
<p>In the directory <i>doc</i> you can find an automatically generated documentation |
| 101 |
of the BKChem API. It is not yet very stable, certainly not nice and polished, however |
| 102 |
its the only one I can offer at this time :).</p> |
| 103 |
|
| 104 |
<p>In any case you can simply ask me. The only limitation is that I will not answer |
| 105 |
questions in the direction "What is python and how to make it print "hello world"?". |
| 106 |
Also please use the bkchem mailing list for such questions so that everybody interested |
| 107 |
can benefit from the discussion.</p> |
| 108 |
|
| 109 |
</body> |
| 110 |
</html> |