
# Deep Learning Registration for Cardiac Motion Tracking

## Introduction
Deep learning network-based registration method applied on cardiac motion tracking from cardiac MR images (cMRI).
If you use this code or part of this code, please consider citing the following papers:
 Qiu, H., Qin, C., Le Folgoc, L., Hou, B., Schlemper, J., Rueckert, D.:   
 **Deep Learning for Cardiac Motion Estimation: Supervised vs. Unsupervised Training**  
 [STACOM Workshop, MICCAI 2019.](https://doi.org/10.1007/978-3-030-39074-7_20)  
 (STACOM19 version of the code can be found in branch [`stacom19`](https://github.com/qiuhuaqi/cardiac-motion/tree/stacom19))

 Qin, C., Bai, W., Schlemper, J., Petersen, S.E., Piechnik, S.K., Neubauer, S., Rueckert, D.:  
 **Joint learning of motion estimation and segmentation for cardiac MR image sequences**  
 [MICCAI 2018](https://doi.org/10.1007/978-3-030-00934-2_53)

## Instructions
### Dependencies
Code developed and tested on Ubuntu 16.04 & 18.04 operating systems, using Python 3.6 and Pytorch 1.0.

To install the Python dependencies, run the following in the root directory of the repo after cloning the repo:
```
pip3 install -r requirements.txt
```
CUDA and cuDNN are required (tested with CUDA `9.0.176` and cuDNN `7.1.4`). 
The code should work with any CUDA and cuDNN versions supported by Pytorch 1.0. Please refer to Pytorch and NVIDIA websites.


### Running
The code works on a model-directory-basis. Training, testing and inference of a model are all based on the model directory of this model. 
Logs, trained models, testing and inference results are all saved in the model directory. 

Training:
```
python cardiac_motion/train.py --gpu [gpu_num] --model_dir [path_to_model_dir]
```

Testing (on the end-diastolic and end-systolic frames): 
```
python cardiac_motion/eval.py --gpu [gpu_num] --model_dir [path_to_model_dir] --restore_file [file_name_of_saved_model]
```

Inference (on all frames of the sequences):
```
python cardiac_motion/inference.py --gpu [gpu_num] --model_dir [path_to_model_dir] --data_dir [path_to_data_dir]
```

Most setting parameters related to data or model are specified in the `params.json` file, which should be supplied in the model directory. 
This file is parsed into attributes of the object `params` in the code to pass the parameters. An example of this file is provided in the repo root directory.

## Trained models
Models trained on cardiac MR image data from the [UK Biobank Imaging Study](https://imaging.ukbiobank.ac.uk/) is available. 
Please feel free to email us to enquire if you are interested.

## Contact us
If you have any question regarding the paper or the code, feel free to open an issue in this repo or email us at:
huaqi.qiu15@imperial.ac.uk


	a/README.md		b/README.md
1	# Deep Learning Registration for Cardiac Motion Tracking	1	# Deep Learning Registration for Cardiac Motion Tracking
2		2
3	## Introduction	3	## Introduction
4	Deep learning network-based registration method applied on cardiac motion tracking from cardiac MR images (cMRI).	4	Deep learning network-based registration method applied on cardiac motion tracking from cardiac MR images (cMRI).
5	If you use this code or part of this code, please consider citing the following papers:	5	If you use this code or part of this code, please consider citing the following papers:
6	> Qiu, H., Qin, C., Le Folgoc, L., Hou, B., Schlemper, J., Rueckert, D.:	6	Qiu, H., Qin, C., Le Folgoc, L., Hou, B., Schlemper, J., Rueckert, D.:
7	> Deep Learning for Cardiac Motion Estimation: Supervised vs. Unsupervised Training	7	Deep Learning for Cardiac Motion Estimation: Supervised vs. Unsupervised Training
8	> [STACOM Workshop, MICCAI 2019.](https://doi.org/10.1007/978-3-030-39074-7_20)	8	[STACOM Workshop, MICCAI 2019.](https://doi.org/10.1007/978-3-030-39074-7_20)
9	> (STACOM19 version of the code can be found in branch [`stacom19`](https://github.com/qiuhuaqi/cardiac-motion/tree/stacom19))	9	(STACOM19 version of the code can be found in branch [`stacom19`](https://github.com/qiuhuaqi/cardiac-motion/tree/stacom19))
10		10
11	> Qin, C., Bai, W., Schlemper, J., Petersen, S.E., Piechnik, S.K., Neubauer, S., Rueckert, D.:	11	Qin, C., Bai, W., Schlemper, J., Petersen, S.E., Piechnik, S.K., Neubauer, S., Rueckert, D.:
12	> Joint learning of motion estimation and segmentation for cardiac MR image sequences	12	Joint learning of motion estimation and segmentation for cardiac MR image sequences
13	> [MICCAI 2018](https://doi.org/10.1007/978-3-030-00934-2_53)	13	[MICCAI 2018](https://doi.org/10.1007/978-3-030-00934-2_53)
14		14
15	## Instructions	15	## Instructions
16	### Dependencies	16	### Dependencies
17	Code developed and tested on Ubuntu 16.04 & 18.04 operating systems, using Python 3.6 and Pytorch 1.0.	17	Code developed and tested on Ubuntu 16.04 & 18.04 operating systems, using Python 3.6 and Pytorch 1.0.
18		18
19	To install the Python dependencies, run the following in the root directory of the repo after cloning the repo:	19	To install the Python dependencies, run the following in the root directory of the repo after cloning the repo:
20	```	20	```
21	pip3 install -r requirements.txt	21	pip3 install -r requirements.txt
22	```	22	```
23	CUDA and cuDNN are required (tested with CUDA `9.0.176` and cuDNN `7.1.4`).	23	CUDA and cuDNN are required (tested with CUDA `9.0.176` and cuDNN `7.1.4`).
24	The code should work with any CUDA and cuDNN versions supported by Pytorch 1.0. Please refer to Pytorch and NVIDIA websites.	24	The code should work with any CUDA and cuDNN versions supported by Pytorch 1.0. Please refer to Pytorch and NVIDIA websites.
25		25
26		26
27	### Running	27	### Running
28	The code works on a model-directory-basis. Training, testing and inference of a model are all based on the model directory of this model.	28	The code works on a model-directory-basis. Training, testing and inference of a model are all based on the model directory of this model.
29	Logs, trained models, testing and inference results are all saved in the model directory.	29	Logs, trained models, testing and inference results are all saved in the model directory.
30		30
31	Training:	31	Training:
32	```	32	```
33	python cardiac_motion/train.py --gpu [gpu_num] --model_dir [path_to_model_dir]	33	python cardiac_motion/train.py --gpu [gpu_num] --model_dir [path_to_model_dir]
34	```	34	```
35		35
36	Testing (on the end-diastolic and end-systolic frames):	36	Testing (on the end-diastolic and end-systolic frames):
37	```	37	```
38	python cardiac_motion/eval.py --gpu [gpu_num] --model_dir [path_to_model_dir] --restore_file [file_name_of_saved_model]	38	python cardiac_motion/eval.py --gpu [gpu_num] --model_dir [path_to_model_dir] --restore_file [file_name_of_saved_model]
39	```	39	```
40		40
41	Inference (on all frames of the sequences):	41	Inference (on all frames of the sequences):
42	```	42	```
43	python cardiac_motion/inference.py --gpu [gpu_num] --model_dir [path_to_model_dir] --data_dir [path_to_data_dir]	43	python cardiac_motion/inference.py --gpu [gpu_num] --model_dir [path_to_model_dir] --data_dir [path_to_data_dir]
44	```	44	```
45		45
46	Most setting parameters related to data or model are specified in the `params.json` file, which should be supplied in the model directory.	46	Most setting parameters related to data or model are specified in the `params.json` file, which should be supplied in the model directory.
47	This file is parsed into attributes of the object `params` in the code to pass the parameters. An example of this file is provided in the repo root directory.	47	This file is parsed into attributes of the object `params` in the code to pass the parameters. An example of this file is provided in the repo root directory.
48		48
49	## Trained models	49	## Trained models
50	Models trained on cardiac MR image data from the [UK Biobank Imaging Study](https://imaging.ukbiobank.ac.uk/) is available.	50	Models trained on cardiac MR image data from the [UK Biobank Imaging Study](https://imaging.ukbiobank.ac.uk/) is available.
51	Please feel free to email us to enquire if you are interested.	51	Please feel free to email us to enquire if you are interested.
52		52
53	## Contact us	53	## Contact us
54	If you have any question regarding the paper or the code, feel free to open an issue in this repo or email us at:	54	If you have any question regarding the paper or the code, feel free to open an issue in this repo or email us at:
55	huaqi.qiu15@imperial.ac.uk	55	huaqi.qiu15@imperial.ac.uk
56		56