ThreeB 1.1
documentation.h
Go to the documentation of this file.
00001 ///@file documentation.h Doxygen documentation bits
00002 
00003 /// @defgroup gDebug Useful debugging functions.
00004 
00005 /// @defgroup gUtility General utility functions.
00006 
00007 /// @defgroup gHMM Generic hidden Markov model solver.
00008 ///
00009 /// The notation follows `A tutorial on hidden Markov models and selected applications in speech recognition', Rabiner, 1989
00010 ///
00011 
00012 /// @defgroup gStorm Storm classes
00013 
00014 // @defgroup gMultiSpotDrift Storm classes specific to multispot processing with drift
00015 
00016 /// @defgroup gStormImages Storm imagery classes (basic image processing)
00017 
00018 // @defgroup gGraphics Graphical display
00019 
00020 // @defgroup gUserInterface General user interface classes
00021 
00022 /// @file multispot5.cc Fit spots to the data
00023 
00024 /// @file multispot5_headless.cc FitSpots driver for entierly headless (batch) operation
00025 
00026 /// @file multispot5_gui.cc FitSpots driver for interactive (GUI) operation and debugging
00027 
00028 ///@file mt19937.h Mersenne twister interface code
00029 
00030 ///@file randomc.h 
00031 
00032 ///@file mersenne.cpp Agner Fogg's Mersenne Twister implementation.
00033 
00034 /// @file debug.h  Debugging bits
00035 
00036 /// @file debug.cc Debugging bits
00037 
00038 /// @file utility.h Utility bits.
00039 
00040 /// @file utility.cc Utility bits.
00041 
00042 /// @file storm_imagery.cc Code dealing with storm imagery (low level).
00043 
00044 /// @file storm_imagery.h Code dealing with storm imagery (low level).
00045 
00046 /// @file storm.h Code dealing with storm imagery (high level).
00047 
00048 /// @file forward_algorithm.h Contains an implementation fo the forward algorithm.
00049 
00050 
00051 /// @defgroup gMultiSpot Storm classes specific to multispot processing
00052 // 
00053 // Having completely smooth drift is too memory intensive.
00054 // 
00055 // The drift model is linear, approximated as piecewise constant.  Generally there
00056 // are <i>F</i> frames and these are divided up into <i>S</i> steps. The equation
00057 // for finding the step \e s from the frame \e i is:
00058 // \f[
00059 // i    s = \lfloor \frac{f S}{F} \rfloor.
00060 // \f]
00061 // The inverse is defined to be:
00062 // \f[
00063 //  f \approx \frac{s + \frac{1}{2}}{S}F
00064 // \f]
00065 //
00066 
00067 
00068 /** \mainpage 3B Microscopy Analysis
00069 
00070 \section sIntro Introduction
00071 
00072 This project contains the reference implementation of the 3B microscopy analysis method,
00073 and an ImageJ plugin.
00074 Please refer to <a href="http://www.coxphysics.com/3b">the project website</a> for more information
00075 on the method.
00076 
00077 To get started with analysing data, the <a href="http://rsbweb.nih.gov/ij/">ImageJ</a> plugin is
00078 probably the most suitable piece of software. This can be obtained from the  <a href="http://www.coxphysics.com/3b">the project website</a>.
00079 
00080 This project contains the cource code for the commandline program and the ImageJ plugin.
00081 
00082 The program (multispot5_headless) performs the
00083 analysis. This program needs to be run from the commandline.
00084 
00085 \section sCMD Commandline Program
00086 
00087 \subsection sCmdComp Compiling
00088 
00089 In order to compile the project, you will need to download and install the
00090 following libraries:
00091 <ul>
00092 <li> TooN http://www.edwardrosten.com/cvd/toon.html
00093 <li> libcvd http://www.edwardrosten.com/cvd/
00094 <li> gvars3 http://www.edwardrosten.com/cvd/gvars3.html
00095 </ul>
00096 The program is portable and is well tested under Linux and OSX. It will also
00097 compile under Windows using cygwin or MinGW.
00098 
00099 The program can be built using the usual method for compiling under Linux:
00100 @code
00101 ./configure && make 
00102 @endcode
00103 
00104 \subsection sExample Example of usage
00105 
00106 We have provided a set of test data on the website. Download and unpack the zip
00107 file. It will create a new directory called test data with the collowing
00108 contents:
00109 @code 
00110 test_data/AVG_test_data.bmp
00111 test_data/markup1.bmp
00112 img_000000000.fits
00113 img_000000001.fits
00114 img_000000002.fits
00115 ...
00116 img_000000299.fits
00117 @endcode
00118 
00119 Then run the following command:
00120 
00121 @code
00122 ./multispot5_headless --save_spots test_data/results.txt --log_ratios test_data/markup1.bmp test_data/img_000000*
00123 @endcode
00124 
00125 The program will save the results in the file \c test_data/results.txt . The
00126 program will run indefinitely in the default setup, but you may view the
00127 results at any stage.  There is no well defined stopping point for this type of
00128 algorithm, so it is advisable continuously monitor the resultant image, and
00129 stop the algorithm when the output image is no longer changing with time. After
00130 30 minutes on a fast PC (e.g. Core i7 975), the ring structure which is not
00131 resolved in the widefield image should be clearly visible.
00132 After about 75 mins, the finer details of the structure begin to approach those seen in Fig 2e
00133 in the associated paper.
00134 
00135 The ImageJ can load a results file and perform a reconstruction.
00136 
00137 
00138 Alternatively, you can process the results file further in order to view the results.
00139 Run the following command:
00140 @code
00141 awk '/PASS/{for(i=2; i <=NF; i+=4)print $(i+2), $(i+3)}' test_data/results.txt > test_data/coordinates.txt
00142 @endcode
00143 
00144 The file <tt>test_data/coordinates.txt</tt> contains a long list of \f$(x, y)\f$
00145 coordinates, representing possible spots positions. In order to view the
00146 results, load the data into a graph plotting program and create a scatter plot.
00147 NOTE: the axes are in pixel coordinates, so you will have to multiple any
00148 distances by the number of nm/pixel in order to get distances in nm.
00149 
00150 
00151 \subsection sExplaneExample Example usage explained
00152 
00153 
00154 \subsubsection ssTestdata Test Data
00155 
00156 The 300 TIFF files in the test directory correspond to the data used for Fig. 2
00157 in the paper. Please refer to the paper for details on how the data was
00158 obtained.
00159 
00160 The file <tt>AVG_test_data.bmp</tt> is a Z projection made using 
00161 <a href="http://rsbweb.nih.gov/ij/">ImageJ</a>.
00162 
00163 The file <tt>markup1.bmp</tt> is a mask indicating which area of the image to
00164 analyse. All perfectly black pixels are ignored, ecerything else is analysed. If
00165 you overlay <tt>markup1.bmp</tt> and <tt>AVG_test_data.bmp</tt> you can see
00166 which area the markup corresponds to. The markup file was created using 
00167 <a hres="www.gimp.org">the GIMP</a>.
00168 
00169 \subsubsection ssRunning Running the program
00170 
00171 The general form for running the program is:
00172 
00173 @code
00174 ./multispot5_headless [ --variable1 value1 [ --variable2 value 2 [ ... ] ] ] image1 image2 ... 
00175 @endcode
00176 
00177 so the example sets ths variable \c save_spots to \c test_data/results.txt and
00178 the variable \c log_ratios to \c test_data/markup1.bmp.  The remaining
00179 arguments is the list of files to be analysed.
00180 
00181 The program gets the markup in the filename given in the \c log_ratios variable
00182 (yes, the choice of name is very strange, and corresponds to a very old phase of
00183 development). The more sanely named variable \c save_spots is the filename in
00184 which the output is to be saved.
00185 
00186 The program actually has a large number of variables which must be set. Most of
00187 them you probably don't want to change, but some of them you will want to
00188 change. The default values for these variables are stored in \c multispot5.cfg
00189 The format of this file should be mostly self explanatory. Everything after a \c
00190 // is a comment and is ignored.
00191 
00192 You will probably want to change:
00193 <ul>
00194 <li> \c blur.mu
00195 
00196 This is the prior over spot size, which is how the pixel size and microscope
00197 FWHM are represented. Some example values for a FWHM of 300nm/pix at 160 and
00198 100 nm/pix and for a FWHM of 270nm at 79nm per pixel. 
00199 
00200 If you have significantly largre or smaller pixels, the performance may be
00201 degraded.
00202 
00203 <li> \c placement.uniform.num_spots
00204 
00205 This is the initial number of spots to be placed down. Eventually, the algorithm
00206 will converge to a reasonable number of spots, even if this value is far off.
00207 The default value (15) is appropriate given the small area and dimness of the
00208 sample data. You will want to increase this number for larger areas of markup
00209 and relatively brighter regions.
00210 
00211 If this number is more than 1000, then the algorithm will run very slowly and
00212 may take several days.
00213 
00214 </ul>
00215 
00216 Note that variables specified on the commandline override all variables in the
00217 configuration file.
00218 
00219 The program can read FITS, BMP, PPM and PGM images. Depending on how it
00220 has been compiled, it can also read TIFF, PNG and JPEG images.
00221 The program cannot work on multi-image TIFF files. ImageJ can be used to split a
00222 multi-image TIFF into a collection of single image files. All the images loaded
00223 must be the same size.
00224 
00225 \subsubsection ssExtract Extracting the data
00226 
00227 The output file (in this case  \c test_data/results.txt ) containing the results
00228 is in a format unsuitable for plotting directly, and must be extracted. The
00229 reason for this is that the output file contains enough information to
00230 seamlessly continue long runs which have been interrupted. The provided AWK
00231 program extracts the coordinates of the spots over all iterations and puts them
00232 in \c coordinates.txt.
00233 
00234 \section sPlugin ImageJ plugin
00235 
00236 The plugin is provided pre-compiled from the project website.
00237 
00238 There are two ways of building the plugin, manual and automatic. If you want to
00239 make changes to the plugin, then use manual building. If you want to
00240 autoamtically build the plugin for several platforms, then use automatic
00241 building.
00242 
00243 \subsection sManual Manual
00244 
00245 The basic build instructions are the same as for the commandline program.
00246 You will also need the JDK (Java Development Kit) and  ImageJ installed.
00247 
00248 You will have to locate where your system has installed the JDK. If it is 
00249 not in /usr/lib/jvm/java-6-openjdk/include, you will have to specify the path:
00250 
00251 First configure the system:
00252 @code
00253 ./configure --with-imagej=/path/to/ImageJ/ij.jar --with-jni=/path/to/jdk/include
00254 @endcode
00255 
00256 You will also need to make sure that the JDK programs (javac, havah, etc) are in
00257 your path.
00258 
00259 To build the JAVA part:
00260 @code
00261 make three_B.jar
00262 @endcode
00263 
00264 
00265 To build the plugin (on Linux):
00266 @code
00267 make libthreeB_jni.so DYNAMIC_PLUGIN=1
00268 @endcode
00269 Note that if you do not specify \c DYNAMIC_PLUGIN, then the makefile will try to
00270 build a plugin with some dependencies statically linked in which will almost
00271 certainly fail unless you have set the system up to support  such an operation.
00272 
00273 On MinGW:
00274 @code
00275 make threeB_jni.dll
00276 @endcode
00277 
00278 Now copy three_B.jar and libthreeB_jni.so into your ImageJ plugins directory.
00279 
00280 
00281 \subsection sAutoBuild Automatic Build
00282 
00283 The automatic build method is very slow and is designed to be able to repeatably 
00284 build plugins for 32 and 64 bit Linux and Windows. It is also designed to build
00285 the plugin with as many static dependencies as possible so that only a single
00286 DLL/so needs to be shipped per system.
00287 
00288 The script operates by building a temporary install of Ubuntu 10.04 LTS, and
00289 using that to compile all variants of the plugin. 
00290 
00291 You will need a Debian based system (or a system on which the command \c
00292 debootstrap works) and root access.
00293 
00294 Tha automatic build system makes use of cLAPACK, rather than LAPACK as the
00295 LAPACK part is not speed critical and it is easier to build CLAPACK without
00296 additional external dependencies.
00297 
00298 To build, run the following commands:
00299 @code
00300 #First make a tar.gz of the source code
00301 bash make_dist.sh
00302 
00303 #Now execute the automatic build process
00304 bash build_plugin.sh
00305 @endcode
00306 
00307 The build takes a long time, and you should probably edit \c build_plugin.sh to
00308 point the installer at an Ubuntu mirror somewhere near to where you are.
00309 
00310 At the end of the build, the script will print out a directory name like:
00311 @code
00312 dist-123908
00313 @endcode
00314 
00315 A fresh copy of the plugin DLL and shared object will be present in that
00316 directory named.
00317 
00318 
00319 */