EMXtalOrg $Id: README$ Release 1.0 beta (July 10, 2001) =========================================================================== EMXtalOrg =========================================================================== Contents -------- +Overview +Installation +Documentation & Support +Software License --------------------------------------------------------------------------- Overview --------------------------------------------------------------------------- The EMXtalOrg suite was written to provide a user-friendly interface to the electron microscopy (EM) 3-D merging program origtilt, which was written in user-unfriendly Fortran. It also serves to provide functions in the processing of crystalline EM image data after indexing and correction for the contrast transfer (CTF) effect. The current version uses amplitudes-and-phases (aph) data files from indexed, tilted EM images of two-dimensional (2D) protein crystals, such as those output by the SPECTRA indexing program included with the Integrated Crystallographic Environment (I.C.E.) suite (http://ncmi.bcm.tmc.edu/software/software.html). After merging the files in tilt_org and processing with aph_edit, a standard HKL-type file or several program-specific file-types can be output which can be used as input to a number of 3-D image processing and visualization programs including CCP4 (http:// www.dl.ac.uk/CCP/CCP4/main.html) and XtalView (http://www.scripps.edu/pub/dem-web/). The main distribution site for this package is: http://www.jasonya.com/emxtalorg/ --------------------------------------------------------------------------- Installation --------------------------------------------------------------------------- TiltOrg is written in Python 1.6 using the TkInter module which requires that Tcl/Tk 7.4 or better be installed. The Python interpreter can be obtained from http://www.python.org for most systems and Tk/Tcl can be obtained from http://www.scriptics.com. The python distribution includes instructions on how to enable the TkInter module (this involves recompiling Python using a C compiler) if it is not already enabled. Brief instructions on enabling the TkInter module are included at the end of this section. SGI systems come with distributions of both these components on the IRIX Freeware distribution CD, make sure when installing Python that you also install the Python source code so that additional Python modules can be enabled (such as the TkInter module). 1. EMXtalOrg is distributed as a tarred and gzipped file, to unpack it use the following commands: % gunzip emxtalorg.tgz % tar -vxf emxtalorg.tar 2. You will now have an emxtalorg directory containing the following sub-directories: ./emxtalorg/bin/ - core image processing programs (MRC) ./emxtalorg/doc/ - documentation for emxtalorg ./emxtalorg/python/ - Python source code for tilt_org and aph_edit ./emxtalorg/src/ - source code and build files for MRC programs 3. Modify the emxtalorg.pth file to reflect the location of the "python" subdirectory of the EMXtalOrg distribution directory. For example if the EMXtalOrg distribution directory is /usr/people/me/ the emxtalorg.pth file will look like this: /usr/people/me/emxtalorg/python 4. After modification place the file in Python's module search path. The "site-packages" subdirectory of the Python library directory is an appropriate place. Depending on your installation this may be found at /usr/local/lib/pythonX.X/site-packages (where X.X is the version of Python you are using, ie. 1.5, 2.1, etc.). 5. Include the emxtalorg/bin directory in your execution search path, from the example used above, include this line (modifying the path for your specific location): set path = ($path /usr/em/emxtalorg/bin/) 6. The Python programs require no compilation since Python is an interpreted language. MRC core programs, ORIGTILT(B, C12, D), ALLSPACE, FFTRANS, CREATE_TNF, and ICE_SKEW are provided with this distribution as pre-compiled binaries that run under SGI IRIX 5.3.x and 6.5.x. Currently the MRC core programs can be compiled with an f77 and C compiler (unfortunately I have not been able to get the GNU f77 compiler to work on these programs) and very primitive build files have been included in the emxtalorg/src and emxtalorg/ccp4 directories. A newer distribution of the MRC core processing programs which can be compiled under several flavors of UNIX including LINUX is available from the MRC by emailing jms@mrc-lmb.cam.ac.uk. Enabling the TkInter Module in Python ===================================== 1. Make sure that you have both the Python source code and Tcl/Tk installed. Python requires a C compiler in order to build (the GNU Project's C compiler, gcc, works just fine: http://www.gnu.org). 2. First find the Python build file in the Python source code directory ./Modules/Setup (if Python is installed on an SGI IRIX 6.5.x from the Freeware distribution disk this file's path is: /usr/freeware/src/Python-1.5.2/Modules/Setup) Open this file for editing. 3. Determine several things about your Tcl/Tk and X11 installations: A. Where the Tcl/Tk header files reside. B. Where the X11 header files reside. C. Where the Tcl/Tk libraries are. D. What versions of Tcl/Tk you have installed. This can be determined by looking at the end of the library filenames, e.g. libtk8.0.so means that the tk version is 8.0. E. Where the X11 libraries reside. From the example above (SGI IRIX 6.5.x, with both Tcl/Tk and X11 installed from SGI installation disks these are as follows): A. /usr/freeware/include B. /usr/include/X11 C. /usr/freeware/lib32 D. Tk version (e.g. 8.0), Tcl version (e.g. 8.0) E. /usr/lib32 4. In the Python Setup file (step 2 above) find the section with the description of the _tkinter module (you can search for the string "# The _tkinter module." if your are using Python version 1.5.x. Uncomment the lines containing the parameters determined in Step 3 above (remove the "#" at the start of the line) and change the paths or versions to reflect your installation (as determined above). Also uncomment several other lines as the instructions in the file state, see the example below. An example of the whole TkInter module description from the Setup file is shown below: note that there are several parts of this description that we don't use so can remain commented and thus un-enabled. # The _tkinter module. # # The TKPATH variable is always enabled, to save you the effort. TKPATH=:lib-tk # The command for _tkinter is long and site specific. Please # uncomment and/or edit those parts as indicated. If you don't have a # specific extension (e.g. Tix or BLT), leave the corresponding line # commented out. (Leave the trailing backslashes in! If you # experience strange errors, you may want to join all uncommented # lines and remove the backslashes -- the backslash interpretation is # done by the shell's "read" command and it may not be implemented on # every system. # *** Always uncomment this (leave the leading underscore in!): _tkinter _tkinter.c tkappinit.c -DWITH_APPINIT \ # *** Uncomment and edit to reflect where your Tcl/Tk headers are: -I/usr/freeware/include \ # *** Uncomment and edit to reflect where your X11 header files are: -I/usr/include/X11 \ # *** Or uncomment this for Solaris: # -I/usr/openwin/include \ # *** Uncomment and edit for Tix extension only: # -DWITH_TIX -ltix4.1.8.0 \ # *** Uncomment and edit for BLT extension only: # -DWITH_BLT -I/usr/local/blt/blt8.0-unoff/include -lBLT8.0 \ # *** Uncomment and edit for PIL (TkImaging) extension only: # -DWITH_PIL -I../Extensions/Imaging/libImaging tkImaging.c \ # *** Uncomment and edit for TOGL extension only: # -DWITH_TOGL togl.c \ # *** Uncomment and edit to reflect where your Tcl/Tk libraries are: -L/usr/freeware/lib32 \ # *** Uncomment and edit to reflect your Tcl/Tk versions: -ltk8.0 -ltcl8.0 \ # *** Uncomment and edit to reflect where your X11 libraries are: -L/usr/lib32 \ # *** Or uncomment this for Solaris: # -L/usr/openwin/lib \ # *** Uncomment these for TOGL extension only: # -lGL -lGLU -lXext -lXmu \ # *** Uncomment for AIX: # -lld \ # *** Always uncomment this; X11 libraries to link with: -lX11 5. From the Python source code base directory follow the README file's directions to compile Python with TkInter enabled. It's a good idea to use the "make install" command so that everything ends up in the correct place. 6. If there are problems with the compilation related to the TkInter module check the path specifications carefully- make sure that the library and include compilation specifications ("-L" or "-I"; "-l" for the versions) and that the libraries and include files exist. The example given above is dependent upon the IRIX distribution remaining the same, so don't depend on it. --------------------------------------------------------------------------- Documentation & Support --------------------------------------------------------------------------- Currently documentation for the EMXtalOrg suite is in the form of two files located in the emxtalorg/doc directory. The files are in three formats; MS Word 98 doc files, RTF-format files, and plain text files. An HTML version of the documentation will soon be available at the distribution site listed above. Additionally, clicking the "Help" button at the top of the TILT_ORG or APH_EDIT program windows will open a help window with slightly out-of-date information- this too will be updated in the next release. For questions or help not addressed in the documentation provided please email: emxtalorg-help@jasonya.com This is a beta-release. We have tested it in our laboratory but there are still minor bugs which must be fixed. If a bug is found please send an email with as much information as possible about the actions being performed, the type of data being operated on, output from the Python debugger (if any) and any other pertinent information to: emxtalorg-bugs@jasonya.com --------------------------------------------------------------------------- Software License --------------------------------------------------------------------------- Copyright (c) JEMWorks Software and Jason McDermott, 2001. All rights reserved. Permission to use, copy, modify, and distribute this software for any purpose without fee is hereby granted, provided that this entire notice is included in all copies of any software which is or includes a copy or modification of this software and in all copies of the supporting documentation for such software. The GNU Software license applies to the Python portion of this software and the source code provided is property of the Medical Research Council (MRC), please refer to that source code for licensing information or email jms@mrc-lmb.cam.ac.uk. DISCLAIMER This software is provided as is with no warranty, express or implied. Neither JEMWorks Software or Jason McDermott assumes any responsibility for the accuracy, completeness or usefulness of this software.