Merge pull request #20 from jpdefrutos/master

README.md

@@ -5,13 +5,13 @@
 <div align="center">
 
 <h1 align="center">DDMR: Deep Deformation Map Registration</h1>
-<h3 align="center">Train smarter, not harder: learning deep abdominal CT registration on scarce data</h3>
+<h3 align="center">Learning deep abdominal CT registration through adaptive loss weighting and synthetic data generation</h3>
  
 # ⚠️***WARNING: Under construction*** 
 
-**DDMR** was developed by SINTEF Health Research. The corresponding manuscript describing the framework has been submitted to [PLOS ONE](https://journals.plos.org/plosone/) and the preprint is openly available on [arXiv](https://arxiv.org/abs/2211.15717).
+**DDMR** was developed by SINTEF Health Research. The corresponding manuscript describing the framework has been published in [PLOS ONE](https://journals.plos.org/plosone/) and the manuscript is openly available [here](https://journals.plos.org/plosone/article?id=10.1371/journal.pone.0282110).
+
 
- 
 </div>
 
 ## 💻 Getting started
@@ -24,8 +24,27 @@ source venv/bin/activate
 
 2. Install requirements:
 ```
-pip install -r requirements.txt
+pip install /path/to/clone/.
+```
+
+## 🤖 How to use
+Use the following CLI command to register images
+```
+ddmr --fixed path/to/fixed_image.nii.gz --moving path/to/moving_image.nii.gz --outputdir path/to/output/dir -a <anatomy> --model <model> --gpu <gpu-number> --original-resolution
 ```
+where:
+* anatomy: is the type of anatomy you want to register: B (brain) or L (liver)
+* model: is the model you want to use:
+    + BL-N (baseline with NCC)
+    + BL-NS (baseline with NCC and SSIM)
+    + SG-ND (segmentation guided with NCC and DSC)
+    + SG-NSD (segmentation guided with NCC, SSIM, and DSC)
+    + UW-NSD (uncertainty weighted with NCC, SSIM, and DSC)
+    + UW-NSDH (uncertainty weighted with NCC, SSIM, DSC, and HD).
+* gpu: is the GPU number you want to the model to run on, if you have multiple and want to use only one GPU
+* original-resolution: (flag) whether to upsample the registered image to the fixed image resolution (disabled if the flag is not present)
+
+Use ```ddmr --help``` to see additional options like using precomputed segmentations to crop the images to the desired ROI, or debugging.
 
 ## 🏋️‍♂️ Training
 
@@ -48,21 +67,25 @@ python EvaluationScripts/evaluation.py
 ## ✨ How to cite
 Please, consider citing our paper, if you find the work useful:
 <pre>
-@misc{perezdefrutos2022ddmr,
-    title = {Train smarter, not harder: learning deep abdominal CT registration on scarce data},
-    author = {Pérez de Frutos, Javier and Pedersen, André and Pelanis, Egidijus and Bouget, David and Survarachakan, Shanmugapriya and Langø, Thomas and Elle, Ole-Jakob and Lindseth, Frank},
-    year = {2022},
-    doi = {10.48550/ARXIV.2211.15717},
-    publisher = {arXiv},
-    copyright = {Creative Commons Attribution 4.0 International},
-    note = {preprint on arXiv at https://arxiv.org/abs/2211.15717}
+@article{perezdefrutos2022ddmr,
+    title = {Learning deep abdominal CT registration through adaptive loss weighting and synthetic data generation},
+    author = {Pérez de Frutos, Javier AND Pedersen, André AND Pelanis, Egidijus AND Bouget, David AND Survarachakan, Shanmugapriya AND Langø, Thomas AND Elle, Ole-Jakob AND Lindseth, Frank},
+    journal = {PLOS ONE},
+    publisher = {Public Library of Science},
+    year = {2023},
+    month = {02},
+    volume = {18},
+    doi = {10.1371/journal.pone.0282110},
+    url = {https://doi.org/10.1371/journal.pone.0282110},
+    pages = {1-14},
+    number = {2}
 }
 </pre>
 
 ## ⭐ Acknowledgements
 This project is based on [VoxelMorph](https://github.com/voxelmorph/voxelmorph) library, and its related publication:
 <pre>
-@article{VoxelMorph2019,
+@article{balakrishnan2019voxelmorph,
     title={VoxelMorph: A Learning Framework for Deformable Medical Image Registration}, 
     author={Balakrishnan, Guha and Zhao, Amy and Sabuncu, Mert R. and Guttag, John and Dalca, Adrian V.},
     journal={IEEE Transactions on Medical Imaging},