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 Please refer to <a href="http://www.coxphysics.com/3b">the project website</a> for more information 00074 on the method. 00075 00076 The program (multispot5_headless) performs the 00077 analysis. This program needs to be run from the commandline. 00078 00079 \section Compiling 00080 00081 In order to compile the project, you will need to download and install the 00082 following libraries: 00083 <ul> 00084 <li> TooN http://www.edwardrosten.com/cvd/toon.html 00085 <li> libcvd http://www.edwardrosten.com/cvd/ 00086 <li> gvars3 http://www.edwardrosten.com/cvd/gvars3.html 00087 </ul> 00088 The program is portable and is well tested under Linux and OSX. It will also 00089 compile under Windows using cygwin or MinGW. 00090 00091 \section sExample Example of usage 00092 00093 We have provided a set of test data on the website. Download and unpack the zip 00094 file. It will create a new directory called test data with the collowing 00095 contents: 00096 @code 00097 test_data/AVG_test_data.bmp 00098 test_data/markup1.bmp 00099 img_000000000.fits 00100 img_000000001.fits 00101 img_000000002.fits 00102 ... 00103 img_000000299.fits 00104 @endcode 00105 00106 Then run the following command: 00107 00108 @code 00109 ./multispot5_headless --save_spots test_data/results.txt --log_ratios test_data/markup1.bmp test_data/img_000000* 00110 @endcode 00111 00112 The program will save the results in the file \c test_data/results.txt . The 00113 program will run indefinitely in the default setup, but you may view the 00114 results at any stage. There is no well defined stopping point for this type of 00115 algorithm, so it is advisable continuously monitor the resultant image, and 00116 stop the algorithm when the output image is no longer changing with time. After 00117 30 minutes on a fast PC (e.g. Core i7 975), the ring structure which is not 00118 resolved in the widefield image should be clearly visible. 00119 After about 75 mins, the finer details of the structure begin to approach those seen in Fig 2e 00120 in the associated paper. 00121 00122 You will have to process the results file further in order to view the results. 00123 Run the following command: 00124 @code 00125 awk '/PASS/{for(i=2; i <=NF; i+=4)print $(i+2), $(i+3)}' test_data/results.txt > test_data/coordinates.txt 00126 @endcode 00127 00128 The file <tt>test_data/coordinates.txt</tt> contains a long list of \f$(x, y)\f$ 00129 coordinates, representing possible spots positions. In order to view the 00130 results, load the data into a graph plotting program and create a scatter plot. 00131 NOTE: the axes are in pixel coordinates, so you will have to multiple any 00132 distances by the number of nm/pixel in order to get distances in nm. 00133 00134 00135 \section sExplaneExample Example usage explained 00136 00137 00138 \subsection ssTestdata Test Data 00139 00140 The 300 TIFF files in the test directory correspond to the data used for Fig. 2 00141 in the paper. Please refer to the paper for details on how the data was 00142 obtained. 00143 00144 The file <tt>AVG_test_data.bmp</tt> is a Z projection made using 00145 <a href="http://rsbweb.nih.gov/ij/">ImageJ</a>. 00146 00147 The file <tt>markup1.bmp</tt> is a mask indicating which area of the image to 00148 analyse. All perfectly black pixels are ignored, ecerything else is analysed. If 00149 you overlay <tt>markup1.bmp</tt> and <tt>AVG_test_data.bmp</tt> you can see 00150 which area the markup corresponds to. The markup file was created using 00151 <a hres="www.gimp.org">the GIMP</a>. 00152 00153 \subsection ssRunning Running the program 00154 00155 The general form for running the program is: 00156 00157 @code 00158 ./multispot5_headless [ --variable1 value1 [ --variable2 value 2 [ ... ] ] ] image1 image2 ... 00159 @endcode 00160 00161 so the example sets ths variable \c save_spots to \c test_data/results.txt and 00162 the variable \c log_ratios to \c test_data/markup1.bmp. The remaining 00163 arguments is the list of files to be analysed. 00164 00165 The program gets the markup in the filename given in the \c log_ratios variable 00166 (yes, the choice of name is very strange, and corresponds to a very old phase of 00167 development). The more sanely named variable \c save_spots is the filename in 00168 which the output is to be saved. 00169 00170 The program actually has a large number of variables which must be set. Most of 00171 them you probably don't want to change, but some of them you will want to 00172 change. The default values for these variables are stored in \c multispot5.cfg 00173 The format of this file should be mostly self explanatory. Everything after a \c 00174 // is a comment and is ignored. 00175 00176 Yu will probably want to change: 00177 <ul> 00178 <li> \c blur.mu 00179 00180 This is the prior over spot size, which is how the pixel size and microscope 00181 FWHM are represented. Some example values for a FWHM of 300nm/pix at 160 and 00182 100 nm/pix and for a FWHM of 270nm at 79nm per pixel. 00183 00184 If you have significantly largre or smaller pixels, the performance may be 00185 degraded. 00186 00187 <li> \c placement.uniform.num_spots 00188 00189 This is the initial number of spots to be placed down. Eventually, the algorithm 00190 will converge to a reasonable number of spots, even if this value is far off. 00191 The default value (15) is appropriate given the small area and dimness of the 00192 sample data. You will want to increase this number for larger areas of markup 00193 and relatively brighter regions. 00194 00195 If this number is more than 1000, then the algorithm will run very slowly and 00196 may take several days. 00197 00198 </ul> 00199 00200 Note that variables specified on the commandline override all variables in the 00201 configuration file. 00202 00203 The program can read FITS, BMP, PPM and PGM images. Depending on how it 00204 has been compiled, it can also read TIFF, PNG and JPEG images. 00205 The program cannot work on multi-image TIFF files. ImageJ can be used to split a 00206 multi-image TIFF into a collection of single image files. All the images loaded 00207 must be the same size. 00208 00209 \subsection ssExtract Extracting the data 00210 00211 The output file (in this case \c test_data/results.txt ) containing the results 00212 is in a format unsuitable for plotting directly, and must be extracted. The 00213 reason for this is that the output file contains enough information to 00214 seamlessly continue long runs which have been interrupted. The provided AWK 00215 program extracts the coordinates of the spots over all iterations and puts them 00216 in \c coordinated.txt. 00217 00218 00219 00220 */