ThreeB 1.1
|
This project contains the reference implementation of the 3B microscopy analysis method, and an ImageJ plugin. Please refer to the project website for more information on the method.
To get started with analysing data, the ImageJ plugin is probably the most suitable piece of software. This can be obtained from the the project website.
This project contains the cource code for the commandline program and the ImageJ plugin.
The program (multispot5_headless) performs the analysis. This program needs to be run from the commandline.
In order to compile the project, you will need to download and install the following libraries:
The program is portable and is well tested under Linux and OSX. It will also compile under Windows using cygwin or MinGW.
The program can be built using the usual method for compiling under Linux:
./configure && make
We have provided a set of test data on the website. Download and unpack the zip file. It will create a new directory called test data with the collowing contents:
test_data/AVG_test_data.bmp test_data/markup1.bmp img_000000000.fits img_000000001.fits img_000000002.fits ... img_000000299.fits
Then run the following command:
./multispot5_headless --save_spots test_data/results.txt --log_ratios test_data/markup1.bmp test_data/img_000000*
The program will save the results in the file test_data/results.txt
. The program will run indefinitely in the default setup, but you may view the results at any stage. There is no well defined stopping point for this type of algorithm, so it is advisable continuously monitor the resultant image, and stop the algorithm when the output image is no longer changing with time. After 30 minutes on a fast PC (e.g. Core i7 975), the ring structure which is not resolved in the widefield image should be clearly visible. After about 75 mins, the finer details of the structure begin to approach those seen in Fig 2e in the associated paper.
The ImageJ can load a results file and perform a reconstruction.
Alternatively, you can process the results file further in order to view the results. Run the following command:
awk '/PASS/{for(i=2; i <=NF; i+=4)print $(i+2), $(i+3)}' test_data/results.txt > test_data/coordinates.txt
The file test_data/coordinates.txt
contains a long list of coordinates, representing possible spots positions. In order to view the results, load the data into a graph plotting program and create a scatter plot. NOTE: the axes are in pixel coordinates, so you will have to multiple any distances by the number of nm/pixel in order to get distances in nm.
The 300 TIFF files in the test directory correspond to the data used for Fig. 2 in the paper. Please refer to the paper for details on how the data was obtained.
The file AVG_test_data.bmp
is a Z projection made using ImageJ.
The file markup1.bmp
is a mask indicating which area of the image to analyse. All perfectly black pixels are ignored, ecerything else is analysed. If you overlay markup1.bmp
and AVG_test_data.bmp
you can see which area the markup corresponds to. The markup file was created using the GIMP.
The general form for running the program is:
./multispot5_headless [ --variable1 value1 [ --variable2 value 2 [ ... ] ] ] image1 image2 ...
so the example sets ths variable save_spots
to test_data/results.txt
and the variable log_ratios
to test_data/markup1.bmp
. The remaining arguments is the list of files to be analysed.
The program gets the markup in the filename given in the log_ratios
variable (yes, the choice of name is very strange, and corresponds to a very old phase of development). The more sanely named variable save_spots
is the filename in which the output is to be saved.
The program actually has a large number of variables which must be set. Most of them you probably don't want to change, but some of them you will want to change. The default values for these variables are stored in multispot5.cfg
The format of this file should be mostly self explanatory. Everything after a is
a comment and is ignored.
You will probably want to change:
blur.mu
This is the prior over spot size, which is how the pixel size and microscope FWHM are represented. Some example values for a FWHM of 300nm/pix at 160 and 100 nm/pix and for a FWHM of 270nm at 79nm per pixel.
If you have significantly largre or smaller pixels, the performance may be degraded.
placement.uniform.num_spots
This is the initial number of spots to be placed down. Eventually, the algorithm will converge to a reasonable number of spots, even if this value is far off. The default value (15) is appropriate given the small area and dimness of the sample data. You will want to increase this number for larger areas of markup and relatively brighter regions.
If this number is more than 1000, then the algorithm will run very slowly and may take several days.
Note that variables specified on the commandline override all variables in the configuration file.
The program can read FITS, BMP, PPM and PGM images. Depending on how it has been compiled, it can also read TIFF, PNG and JPEG images. The program cannot work on multi-image TIFF files. ImageJ can be used to split a multi-image TIFF into a collection of single image files. All the images loaded must be the same size.
The output file (in this case test_data/results.txt
) containing the results is in a format unsuitable for plotting directly, and must be extracted. The reason for this is that the output file contains enough information to seamlessly continue long runs which have been interrupted. The provided AWK program extracts the coordinates of the spots over all iterations and puts them in coordinates.txt
.
The plugin is provided pre-compiled from the project website.
There are two ways of building the plugin, manual and automatic. If you want to make changes to the plugin, then use manual building. If you want to autoamtically build the plugin for several platforms, then use automatic building.
The basic build instructions are the same as for the commandline program. You will also need the JDK (Java Development Kit) and ImageJ installed.
You will have to locate where your system has installed the JDK. If it is not in /usr/lib/jvm/java-6-openjdk/include, you will have to specify the path:
First configure the system:
./configure --with-imagej=/path/to/ImageJ/ij.jar --with-jni=/path/to/jdk/include
You will also need to make sure that the JDK programs (javac, havah, etc) are in your path.
To build the JAVA part:
make three_B.jar
To build the plugin (on Linux):
make libthreeB_jni.so DYNAMIC_PLUGIN=1
Note that if you do not specify DYNAMIC_PLUGIN
, then the makefile will try to build a plugin with some dependencies statically linked in which will almost certainly fail unless you have set the system up to support such an operation.
On MinGW:
make threeB_jni.dll
Now copy three_B.jar and libthreeB_jni.so into your ImageJ plugins directory.
The automatic build method is very slow and is designed to be able to repeatably build plugins for 32 and 64 bit Linux and Windows. It is also designed to build the plugin with as many static dependencies as possible so that only a single DLL/so needs to be shipped per system.
The script operates by building a temporary install of Ubuntu 10.04 LTS, and using that to compile all variants of the plugin.
You will need a Debian based system (or a system on which the command debootstrap
works) and root access.
Tha automatic build system makes use of cLAPACK, rather than LAPACK as the LAPACK part is not speed critical and it is easier to build CLAPACK without additional external dependencies.
To build, run the following commands:
#First make a tar.gz of the source code bash make_dist.sh #Now execute the automatic build process bash build_plugin.sh
The build takes a long time, and you should probably edit build_plugin.sh
to point the installer at an Ubuntu mirror somewhere near to where you are.
At the end of the build, the script will print out a directory name like:
dist-123908
A fresh copy of the plugin DLL and shared object will be present in that directory named.