
This is the implementation of the whole automatic CMB detection framework with 3D FCN and 3D CNN,
as presented in the paper:

"""
"Automatic Detection of Cerebral Microbleeds from MR Images via 3D Convolutional Neural Networks."
Q. Dou*, H. Chen*, L. Yu, L. Zhao, J. Qin, D. Wang, V. Mok, L. Shi, P.A. Heng.
IEEE Transactions on Medical Imaging (TMI), 2016
"""
*** If you plan to use our code or data in your work, please cite this paper. ***

All rights preserved by The Chinese University of Hong Kong.
Our code is ONLY released for research purpose. Any commercial intention, please first contact qdou@cse.cuhk.edu.hk

--------------------------------------------------------------------------------------------

We release the implementations with a sub-dataset (20 subjects) and pre-trained 3D CNN models,
so that readers can try out our code and reproduce results described in the TMI paper.

We also provide the ground-truths of the subjects, so that you can evaluate the method's performance.
Readers can feel free to develop their own systems of CMB detection using our released dataset.

--------------------------------------------------------------------------------------------

Version-1.0
The project is mix-coded with Python and Matlab.

--------------------------------------------------------------------------------------------


Basic Requirements:

1. Theano Library installed (see http://deeplearning.net/software/theano/)
2. Cuda 7.0 installed for GPU acceleration
3. We tested that the code works under Python 2.7 and Matlab 2014a with Ubuntu 12.04
 
--------------------------------------------------------------------------------------------


Usage: 

"""In folder '~/demo/code/' Run the following scripts (IN ORDER) """
pre_process.m  : pre_process the .nii MR raw data to save into .mat files
fcn_wrapper.py : the 3D FCN to get the 3D score map in the first stage (GPU required)
post_process.m : post_processing of the 3D score map to generate the candidates in the first stage
3d_cnn.py      : the 3D CNN to discriminate the candidates in the second stage (GPU required)
final.m        : produce the final prediction results, by locating the centroids of the CMBs

Note: The whole workflow can be referred to Fig. 2 in the paper.
---------------------------------------------------------------------------------------------


Descriptions:

In folder '~/demo/data/'
./raw_data/     : The MR volumetric data, including 20 subjects
./ground_truth/ : CMB centroids voxel coordinates ground truth


In folder '~/demo/model/'
fine_tuned_params.pkl        : 3D FCN model in the 1st stage
fine_tuned_params_step2.pkl  : 3D CNN model in the 2nd stage


In the folder '~/demo/result/'
./mat_data/         : The MR volumes are converted into .mat format
./score_map/        : the score maps generated by fcn_wrapper.py
./score_map_cand/   : the candidate positions generated from the 3D score map
./final_prediction/ : prediction probabilities of candidates produced by 3d_cnn.py
./detection.mat     : the final detection results, each element in the cell corresponds to the locations of detected CMBs.




