Introduction

The TxBR 3.0 installer is a Bash script that builds and installs TxBR 3.0 and most of TxBR 3.0's dependencies in a directory off the current working directory. The installer does not require root access to install TxBR 3.0 or any of its dependencies, nor do it or the version of TxBR 3.0 so installed require any modification of resource configuration files (e.g., .bashrc, .cshrc) to execute properly.

Preliminaries

To use the TxBR 3.0 installer, you will need a Unix-like operating system (e.g., a Linux distribution) with the following:

– A GUI/desktop environment (e.g., GNOME or KDE),
– The Bourne-again shell (bash), the C shell (csh or tcsh), and the basic set of Unix utilities (e.g., tar, gzip, tee, cat, sed, etc.),
– The basic components of the GNU toolchain, i.e., GNU make, GNU m4, and the GNU Compiler Collection (GCC), including the C, C++, and GFortran compilers,
– 2GB of free disk space in the current working directory.

The TxBR 3.0 installer file itself is ~133MB. The installation of TxBR 3.0 produced by the installer is ~1GB.

The only operating systems on which the TxBR 3.0 installer is currently known to work are recent 64-bit versions of Red Hat Enterprise Linux (>= version 5.0), CentOS (>= version 5.0), and Ubuntu (>= version 8.0). This does not mean that these are the only operating systems on which the TxBR 3.0 installer will work. The TxBR 3.0 development team is in the process of testing other hardware platforms and operating systems.

For a list of current outstanding issues with the TxBR 3.0 installer, please see the text beneath the header "Issues".

Install

N.B.: Read these instructions thoroughly before you download the installer. The Unix command prompt is indicated by a dollar sign: $. The TxBR 3.0 installer builds and installs TxBR 3.0 in a directory off the current working directory; the name of this new directory is TxBR-3.0.

1. It is highly recommended that you shut down all other applications before running the TxBR 3.0 installer. The TxBR 3.0 installer compiles a number of complicated software components and the chance of failure on an untested hardware platform and/or operating system will be high. If you have already attempted to install TxBR 3.0 using the TxBR 3.0 installer, before repeating these installation steps, you will need to delete the existing TxBR 3.0 installation directory as described beneath the header "Uninstall".

2. Open a new terminal window from the desktop.

3. Download the installer. (Instructions on how to do this are below, beneath the heading "Download". Recall that you were told to read these instructions before you download the installer.)

4. To run the installer, execute the following command from the directory containing the installer:

$ ./TxBR-3.0.installer.sh

As the installer builds and installs TxBR 3.0 and its dependencies, it will print copious amounts of information to the terminal. Please be patient: even on a fast machine, the installer can take well over an hour to finish; on a fast machine that is experiencing heavy usage, installation can take as long as four hours.

5. When the installer has finished, it will return control to the command prompt. For sanity's sake, verify that the last two lines of output (printed above the command prompt) look something like this:

END: TxBR version 3.0.5: Tue Aug  3 17:10:01 PDT 2010
END: Manual TxBR 3.0 install: Tue Aug  3 17:10:01 PDT 2010
$

An error has definitely occurred if you see something like this:

build.sh: There has been an unrecoverable error.
$

Unfortunately, there may be unforeseen error conditions that do not produce this message, or even return control to the command prompt. To stop the install process at any time, hold down the control key and press the C key. This should return control to the command prompt. If this does not work, try holding down the control key and pressing the Z key. If this returns control to the command prompt, you will need to kill the job you just suspended. You can do this by forcibly exiting the terminal window:

$ exit
exit
There are stopped jobs.
$ exit

If holding down the control key and pressing the Z key does not return control to the command prompt, or if executing the exit shell built-in twice in a row does not close the terminal window, try closing the terminal window using the GUI close button. If that doesn't work, try logging off. If you can't log off, contact your system administrator. If you are the system administrator...

In the event of an installer error, read the instructions printed below the heading "Contact".

Download

Because the installer is a Bash script, you should manually save the link target rather than follow the link to the target (i.e., left clicking on it). If your browser produces a strange-looking page of text that resembles this,

#!/bin/bash

INSTALLER_FILENAME=$0
#INSTALLER_FILENAME="TxBR-3.0.installer.sh" #DEBUG.
#INSTALLER_FILENAME="package_TxBR-3.0.installer_stub.sh" # DEBUG.
PACKAGE_FILENAME="TxBR-3.0.package.tar.gz"
PACKAGE_DIRNAME="TxBR-3.0"

INSTALLER_FILEPATH="$INSTALLER_FILENAME"
PACKAGE_FILEPATH="$PACKAGE_FILENAME"
PACKAGE_DIRPATH="$PACKAGE_DIRNAME"

trap "echo \"$INSTALLER_FILENAME: There has been an unrecoverable error.\" ; exit" ERR

if [[ -e $PACKAGE_FILEPATH ]]; then
    echo "\$PACKAGE_FILEPATH=\"$PACKAGE_FILEPATH\" exists."
    exit 1
fi

if [[ -e $PACKAGE_DIRPATH ]]; then
    echo "\$PACKAGE_DIRPATH=\"$PACKAGE_DIRPATH\" exists."
    exit 1
fi

... ... ...

(the "... ... ..." means an ellipsis of great extent), followed by a bit more text and an astounding quantity of gibberish, you will need to manually save the link target. To do this in Firefox, right click on the link and select "Save

As..." in the context menu. To do this in Internet Explorer... you aren't using Windows

are you?

TxBR 3.0 installer: TxBR-3.0.installer.sh (~133MB) (N.B.: See note below.)

The TxBR 3.0 installer contains, and builds and installs locally in the following order, these components:

TxBR 3.0 installer (EPD-based)

Our apologies, but the TxBR 3.0 installer described above is currently under development. There is an older, more stable version of the TxBR 3.0 installer, the TxBR 3.0 installer (EPD-based), which is (rather unsurprisingly) based upon the Enthought

Python Distribution (EPD). Unfortunately, due to Enthought's licensing restrictions, this version of the TxBR 3.0 installer requires some additional steps.

Beneath the heading "Install", replace the download step with the following steps:

3.1. Download the TxBR-3.0 installer (EPD-based). (Instructions on how to do this are below, beneath the heading "Download". Recall that you were told to read these instructions before you download the installer.)

3.2. Place the relevant version of the EPD installer in your home directory (i.e., in a Unix-like OS, the directory given by the environment variable $HOME). (N.B.: Currently, the only supported version of EPD is 6.2-2 x86_64, which means the file name of the EPD installer will be epd-6.2-2-rh5-x86_64.sh. To acquire the EPD installer, visit http://www.enthought.com/.)

Beneath the heading "Install", replace the execute step with the following step:

4. To run the installer, execute the following command from the directory containing the installer:

$ ./TxBR-3.0.installer.epd_based.sh

Download TxBR 3.0 installer (EPD-based)

TxBR 3.0 installer (EPD-based): TxBR-3.0.installer.epd_based.sh (~91MB) (N.B.: Bash script – in Firefox, right click on link and select "Save

As..." in the context menu)

The TxBR 3.0 installer (EPD-based) contains, and builds and installs locally in the following order, these components (N.B.: A notable exception to the preceding description is the entry for the Enthought Python Distribution, which only indicates the relevant EPD version and its position in the build process. A suitable EPD is not included in the TxBR 3.0 installer (EPD-based) itself.):

Test

There is an easy way to check the integrity of an install of TxBR 3.0.

1. Familiarize yourself with the tomographic reconstruction process in general and running TxBR 3.0 in particular by reading the relevant pages linked to the TxBR 3.0 homepage.

2. If you do not have a terminal window open, open a new terminal window.

3. Change your working directory to the root directory of the TxBR 3.0 installation. If you installed TxBR 3.0 off your home directory, execute the following:

$ cd $HOME/TxBR-3.0

4. Run the alignment step on the sample dataset by executing the following script:

$ ./txbr_align.sh

N.B.: Depending on your system setup, the graphs may not be displayed. See the text beneath the header "Issues". If you do not have LaTeX installed, you will see the following error at the end of this step:

Traceback (most recent call last):
  File "/home/akulo/TxBR-3.0/TxBR/usr/local/TxBR/scripts/txbr_align.py", line 214, in <module>
    main()
  File "/home/akulo/TxBR-3.0/TxBR/usr/local/TxBR/scripts/txbr_align.py", line 202, in main
    alignment.process( structureToInitialize )
  File "/home/akulo/TxBR-3.0/TxBR/usr/local/TxBR/lib/txbr/align/contalign.py", line 949, in process
    self.solveGaugeAmbiguity()
  File "/home/akulo/TxBR-3.0/TxBR/usr/local/TxBR/lib/txbr/align/contalign.py", line 1050, in solveGaugeAmbiguity
    basename=serie.basename, model=self.model() )
  File "/home/akulo/TxBR-3.0/TxBR/usr/local/TxBR/lib/txbr/align/gauge.py", line 144, in calc_rotation_axis
    txbr.utilities.plotGaugeCharacterizarion( ellipses, tgts_x, limits, directory=directory, basename=basename, model=model )
  File "/home/akulo/TxBR-3.0/TxBR/usr/local/TxBR/lib/txbr/utilities/txbrplot.py", line 353, in plotGaugeCharacterizarion
    saveAndLinkPlot( directory, basename, "ellipses", model )
  File "/home/akulo/TxBR-3.0/TxBR/usr/local/TxBR/lib/txbr/utilities/txbrplot.py", line 42, in saveAndLinkPlot
    pylab.savefig( current_file, format='png' )
  File "/home/akulo/TxBR-3.0/TxBR/usr/local/lib/python2.6/site-packages/matplotlib/pyplot.py", line 356, in savefig
    return fig.savefig(*args, **kwargs)
  File "/home/akulo/TxBR-3.0/TxBR/usr/local/lib/python2.6/site-packages/matplotlib/figure.py", line 1032, in savefig
    self.canvas.print_figure(*args, **kwargs)
  File "/home/akulo/TxBR-3.0/TxBR/usr/local/lib/python2.6/site-packages/matplotlib/backend_bases.py", line 1476, in print_figure
    **kwargs)
  File "/home/akulo/TxBR-3.0/TxBR/usr/local/lib/python2.6/site-packages/matplotlib/backends/backend_agg.py", line 358, in print_png
    FigureCanvasAgg.draw(self)
  File "/home/akulo/TxBR-3.0/TxBR/usr/local/lib/python2.6/site-packages/matplotlib/backends/backend_agg.py", line 314, in draw
    self.figure.draw(self.renderer)
  File "/home/akulo/TxBR-3.0/TxBR/usr/local/lib/python2.6/site-packages/matplotlib/artist.py", line 46, in draw_wrapper
    draw(artist, renderer, *args, **kwargs)
  File "/home/akulo/TxBR-3.0/TxBR/usr/local/lib/python2.6/site-packages/matplotlib/figure.py", line 773, in draw
    for a in self.axes: a.draw(renderer)
  File "/home/akulo/TxBR-3.0/TxBR/usr/local/lib/python2.6/site-packages/matplotlib/artist.py", line 46, in draw_wrapper
    draw(artist, renderer, *args, **kwargs)
  File "/home/akulo/TxBR-3.0/TxBR/usr/local/lib/python2.6/site-packages/matplotlib/axes.py", line 1735, in draw
    a.draw(renderer)
  File "/home/akulo/TxBR-3.0/TxBR/usr/local/lib/python2.6/site-packages/matplotlib/artist.py", line 46, in draw_wrapper
    draw(artist, renderer, *args, **kwargs)
  File "/home/akulo/TxBR-3.0/TxBR/usr/local/lib/python2.6/site-packages/matplotlib/axis.py", line 742, in draw
    tick.draw(renderer)
  File "/home/akulo/TxBR-3.0/TxBR/usr/local/lib/python2.6/site-packages/matplotlib/artist.py", line 46, in draw_wrapper
    draw(artist, renderer, *args, **kwargs)
  File "/home/akulo/TxBR-3.0/TxBR/usr/local/lib/python2.6/site-packages/matplotlib/axis.py", line 196, in draw
    self.label1.draw(renderer)
  File "/home/akulo/TxBR-3.0/TxBR/usr/local/lib/python2.6/site-packages/matplotlib/text.py", line 518, in draw
    bbox, info = self._get_layout(renderer)
  File "/home/akulo/TxBR-3.0/TxBR/usr/local/lib/python2.6/site-packages/matplotlib/text.py", line 280, in _get_layout
    clean_line, self._fontproperties, ismath=ismath)
  File "/home/akulo/TxBR-3.0/TxBR/usr/local/lib/python2.6/site-packages/matplotlib/backends/backend_agg.py", line 148, in get_text_width_height_descent
    texmanager = self.get_texmanager()
  File "/home/akulo/TxBR-3.0/TxBR/usr/local/lib/python2.6/site-packages/matplotlib/backend_bases.py", line 374, in get_texmanager
    from matplotlib.texmanager import TexManager
  File "/home/akulo/TxBR-3.0/TxBR/usr/local/lib/python2.6/site-packages/matplotlib/texmanager.py", line 72, in <module>
    class TexManager:
  File "/home/akulo/TxBR-3.0/TxBR/usr/local/lib/python2.6/site-packages/matplotlib/texmanager.py", line 94, in TexManager
    _dvipng_hack_alpha = dvipng_hack_alpha()
  File "/home/akulo/TxBR-3.0/TxBR/usr/local/lib/python2.6/site-packages/matplotlib/texmanager.py", line 68, in dvipng_hack_alpha
    raise RuntimeError('Could not obtain dvipng version')
RuntimeError: Could not obtain dvipng version

5. Run the filtering step on the sample dataset by executing the following script:

$ ./txbr_filter.sh

6. Run the back-projection step on the sample dataset by executing the following script:

$ ./txbr_bckprj.sh

7. Run the combine and display back-projection step on the sample dataset by executing the following script:

$ ./txbr_bckprj.finalize.sh

If everything is installed properly, you should see an IMOD Zap window containing a double-tilt reconstruction of the sample dataset.

In the event of a test error, read the instructions printed below the heading "Contact".

Environment

Before running TxBR 3.0 on your own dataset, you will need to set up the TxBR 3.0 environment. If you installed TxBR 3.0 off your home directory, execute the following in a terminal window to set up the TxBR 3.0 environment:

$ source $HOME/TxBR-3.0/setup_TxBR-3.0_env.sh

This will produce output similar to the following (as above, the "... ... ..." means an ellipsis of great extent):

BEGIN: Set up TxBR environment: Wed Aug  4 15:18:56 PDT 2010
BEGIN: Set up TxBR initial environment: Wed Aug  4 15:18:56 PDT 2010
$PATH="/home/txbruser/TxBR-3.0/TxBR/usr/local/bin:/usr/bin:/bin"
$LIBRARY_PATH="/home/txbruser/TxBR-3.0/TxBR/usr/local/lib:/usr/lib64:/usr/lib:/lib"
$LD_LIBRARY_PATH="/home/txbruser/TxBR-3.0/TxBR/usr/local/lib:/usr/lib64:/usr/lib:/lib"
$PKG_CONFIG_PATH="/home/txbruser/TxBR-3.0/TxBR/usr/local/lib/pkgconfig"
$MANPATH="/man:"
END: Set up TxBR initial environment: Wed Aug  4 15:18:56 PDT 2010
BEGIN: Set up Python environment: Wed Aug  4 15:18:56 PDT 2010
$TXBR_PYTHON_VERSION="python2.6" (POST: Python)
$TXBR_PYTHON_EXECUTABLE="/home/txbruser/TxBR-3.0/TxBR/usr/local/bin/python" (POST: Python)
$TXBR_PYTHON_LIB_DIR="/home/txbruser/TxBR-3.0/TxBR/usr/local/lib/python2.6" (POST: Python)
$TXBR_PYTHON_INCLUDE_DIR="/home/txbruser/TxBR-3.0/TxBR/usr/local/include/python2.6" (POST: Python)
$PYTHONPATH="/home/txbruser/TxBR-3.0/TxBR/usr/local/lib/python2.6/site-packages" (POST: Python)
END: Set up Python environment: Wed Aug  4 15:18:56 PDT 2010
... ... ...
END: Set up TxBR environment: Wed Aug  4 15:18:57 PDT 2010
$

You will now be able to run TxBR 3.0 from within that terminal window. Other terminal windows opened from the desktop will not be able to run TxBR 3.0 unless the environment has been set up in the above manner.

Uninstall

To uninstall TxBR 3.0, simply remove the installation directory. If you installed TxBR 3.0 off your home directory, execute the following:

$ rm -fr $HOME/TxBR-3.0

Issues

1. Building Tk requires the X11 development libraries.

2. Generating the plots during the alignment step with matplotlib requires LaTeX.

3. Some of TxBR 3.0's dependencies may require Perl.

4. TxBR 3.0 depends on IMOD. The TxBR 3.0 installer installs a precompiled version of IMOD locally, which should not conflict with any existing install of IMOD. If you already have a version of IMOD installed and working on your system, then your chances of having the TxBR 3.0 installer succeed are much improved. If you do not have a version of IMOD installed, then successfully installing one of the precompiled versions of IMOD on your system (which may or may not mean installing some of IMOD's software requirements on your system) will improve the chances of the TxBR 3.0 installer succeeding.

5. Operating systems that do not support shared libraries may not be able to use the TxBR 3.0 installer in its current form.

6. The components built and installed by the installer have some overlap and are not linked together in the most efficient manner possible.

– Various versions of BLAS/LAPACK are built and installed in different locations by different components at least two or three different times.
– matplotlib claims to support wxPython version >= 2.8 as a backend (in the context of matplotlib, a "backend" is a means of generating 2D graphics and displaying them), but, when advanced graphics are built and installed, matplotlib refuses to link properly with the included wxPython component, which is version 2.8.11.0.

Contact

If you are contacting us about an error, please include a description of your hardware platform (i.e., processor type), your operating system (including major version number), and a brief description of the error and the events leading up to it. If possible, include a sample of the trailing end of the output printed in the terminal window. If including this output is not possible, please explain why it is not possible to include it. It would be very helpful if you did not delete the directory tree created by the TxBR 3.0 installer, as it contains extensive error logs that may enable us to pinpoint the problem with minimal fuss. Please send all error reports to Alex Kulungowski at the e-mail address akulo_AT_ncmir_DOT_ucsd_DOT_edu.