ThreeB 1.1
|
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 */