Merge branch 'dev' into feature/vinn

INSTALL.md

@@ -33,7 +33,7 @@ Our [README](README.md) explains how to run FastSurfer (for the full pipeline yo
 This is very similar to Singularity. Assuming you have Docker installed (by a system admin) you just need to pull one of our pre-build Docker images from dockerhub:
 
 ```
-docker pull deepmi/fastsurfer:gpu
+docker pull deepmi/fastsurfer:gpu-v1.1.1
 ```
 
 Our [README](README.md) explains how to run FastSurfer (for the full pipeline you will also need a FreeSurfer .license file !) and you can find details on how to build your own Images here: [Docker](docker/README.md) and [Singularity](singularity/README.md). 
@@ -75,6 +75,7 @@ Install dependencies into a new environment:
 
 ```
 conda env create -f /fastsurfer/fastsurfer_env_gpu.yml 
+conda activate fastsurfer_gpu
 ```
 
 (in the above step you can select from other fastsurfer...yml files for CPU and recon-surf-only versions).
@@ -138,7 +139,7 @@ To run the full pipeline, install also FreeSurfer v7.2 according to their [Instr
 
 ### Docker (currently only Intel)
 
-Docker can be used on Intel Macs as it should be similarly fast than a native install there.
+Docker can be used on Intel Macs as it should be similarly fast as a native install there.
 
 First install Docker Desktop for Mac from https://docs.docker.com/get-docker/
 Start it and under Preferences -> Resources set Memory to 15 GB (or the largest you have, if you are below 15GB, it may fail). Pull one of our pre-compiled Docker containers. For that open a terminal window and copy this command:

README.md

@@ -1,5 +1,5 @@
-[![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/Deep-MI/FastSurfer/blob/master/Tutorial/Tutorial_FastSurferCNN_QuickSeg.ipynb)
-[![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/Deep-MI/FastSurfer/blob/master/Tutorial/Complete_FastSurfer_Tutorial.ipynb)
+[![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/Deep-MI/FastSurfer/blob/stable/Tutorial/Tutorial_FastSurferCNN_QuickSeg.ipynb)
+[![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/Deep-MI/FastSurfer/blob/stable/Tutorial/Complete_FastSurfer_Tutorial.ipynb)
 
 # Overview
 
@@ -38,21 +38,21 @@ List them by running the following command:
 * --t1: T1 full head input (not bias corrected, global path). The network was trained with conformed images (UCHAR, 256x256x256, 1 mm voxels and standard slice orientation). These specifications are checked in the eval.py script and the image is automatically conformed if it does not comply.
 
 ### Required for docker
-* --fs_license: Path to FreeSurfer license key file. Register (for free) at https://surfer.nmr.mgh.harvard.edu/registration.html to obtain it if you do not have FreeSurfer installed so far. Strictly necessary if you use Docker, optional for local install (your local FreeSurfer license will automatically be used)
+* --fs_license: Path to FreeSurfer license key file. Register (for free) at https://surfer.nmr.mgh.harvard.edu/registration.html to obtain it if you do not have FreeSurfer installed so far. Strictly necessary if you use Docker, optional for local install (your local FreeSurfer license will automatically be used).
 
 ### Network specific arguments (optional)
 * --seg: Global path with filename of segmentation (where and under which name to store it). The file can be in mgz, nii, or nii.gz format. Default location: $SUBJECTS_DIR/$sid/mri/aparc.DKTatlas+aseg.deep.mgz
-* --weights_sag: Pretrained weights of sagittal network. Default: ../checkpoints/Sagittal_Weights_FastSurferCNN/ckpts/Epoch_30_training_state.pkl
-* --weights_ax: Pretrained weights of axial network. Default: ../checkpoints/Axial_Weights_FastSurferCNN/ckpts/Epoch_30_training_state.pkl
-* --weights_cor: Pretrained weights of coronal network. Default: ../checkpoints/Coronal_Weights_FastSurferCNN/ckpts/Epoch_30_training_state.pkl
+* --weights_sag: Pretrained weights of sagittal network. Optional, will download checkpoint if missing.
+* --weights_ax: Pretrained weights of axial network. Optional, will download checkpoint if missing.
+* --weights_cor: Pretrained weights of coronal network. Optional, will download checkpoint if missing.
 * --seg_log: Name and location for the log-file for the segmentation (FastSurferCNN). Default: $SUBJECTS_DIR/$sid/scripts/deep-seg.log
-* --clean_seg: Flag to clean up FastSurferCNN segmentation
+* --clean_seg: Flag to clean up NN segmentation
 * --run_viewagg_on: Define where the view aggregation should be run on. 
                     By default, the program checks if you have enough memory to run the view aggregation on the gpu. 
                     The total memory is considered for this decision. 
                     If this fails, or you actively overwrote the check with setting "--run_viewagg_on cpu", view agg is run on the cpu. 
                     Equivalently, if you define "--run_viewagg_on gpu", view agg will be run on the gpu (no memory check will be done).
-* --device <str>: Device to run segmentation ("cpu","cuda"), default cuda which is Nvidia GPU
+* --device <str>: Select device for NN segmentation ("cpu", "cuda"), where cuda (default) means Nvidia GPU, you can select which one "cuda:1".
 * --batch: Batch size for inference. Default: 8. Lower this to reduce memory requirement
 * --order: Order of interpolation for mri_convert T1 before segmentation (0=nearest, 1=linear(default), 2=quadratic, 3=cubic)
 
@@ -125,7 +125,7 @@ After pulling one of our images from Dockerhub, you do not need to have a separa
 To run FastSurfer on a given subject using the provided GPU-Docker, execute the following command:
 
 ```bash
-docker pull deepmi/fastsurfer:gpu
+docker pull deepmi/fastsurfer:gpu-v1.1.1
 docker run --gpus all -v /home/user/my_mri_data:/data \
                       -v /home/user/my_fastsurfer_analysis:/output \
                       -v /home/user/my_fs_license_dir:/fs_license \
@@ -142,11 +142,13 @@ Docker flags:
 * The --rm flag takes care of removing the container once the analysis finished. 
 * The --user XXXX part should be changed to the appropriate user id (a four-digit number; can be checked with the command "id -u" on linux systems). All generated files will then belong to the specified user. Without the flag, the docker container will be run as root.
 
-run_fastsurfer.sh flags:
+FastSurfer Flags to pass through:
 * The fs_license points to your FreeSurfer license which needs to be available on your computer in the my_fs_license_dir that was mapped above. 
 * Note, that the paths following --fs_license, --t1, and --sd are inside the container, not global paths on your system, so they should point to the places where you mapped these paths above with the -v arguments. 
 * A directory with the name as specified in --sid (here subject2) will be created in the output directory. So in this example output will be written to /home/user/my_fastsurfer_analysis/subject2/ . Make sure the output directory is empty, to avoid overwriting existing files. 
 
+You can also run a CPU-Docker with very similar commands. See [Docker/README.md](Docker/README.md) for more details.
+
 ### Example 4: FastSurfer Singularity
 After building the Singularity image (see instructions in ./Singularity/README.md), you also need to register at the FreeSurfer website (https://surfer.nmr.mgh.harvard.edu/registration.html) to acquire a valid license (for free) - just as when using Docker. This license needs to be passed to the script via the --fs_license flag.
 
@@ -165,16 +167,17 @@ singularity exec --nv -B /home/user/my_mri_data:/data \
                       --parallel
 ```
 
-Singularity flags:
+Singularity Flags:
 * The `--nv` flag is used to access GPU resources. 
 * The -B commands mount your data, output, and directory with the FreeSurfer license file into the Singularity container. Inside the container these are visible under the name following the colon (in this case /data, /output, and /fs_license). 
 
-run_fastsurfer.sh flags:
+FastSurfer Flags to pass through:
 * The fs_license points to your FreeSurfer license which needs to be available on your computer in the my_fs_license_dir that was mapped above. 
 * Note, that the paths following --fs_license, --t1, and --sd are inside the container, not global paths on your system, so they should point to the places where you mapped these paths above with the -B arguments. 
 * A directory with the name as specified in --sid (here subject2) will be created in the output directory. So in this example output will be written to /home/user/my_fastsurfer_analysis/subject2/ . Make sure the output directory is empty, to avoid overwriting existing files. 
 
-                               
+You can run the Singularity equivalent of CPU-Docker by building a Singularity image from the CPU-Docker image and excluding the `--nv` argument in your Singularity exec command.
+
 ## System Requirements
 
 Recommendation: At least 8GB CPU RAM and 8GB NVIDIA GPU RAM ```--batch 1 --run_viewagg_on gpu```  
@@ -183,7 +186,6 @@ Minimum: 8 GB CPU RAM and 2 GB GPU RAM ```--batch 1 --run_viewagg_on cpu```
 
 CPU-only: 8 GB CPU RAM (much slower, not recommended) ```--device cpu --batch 4``` 
 
-
 ## FreeSurfer Downstream Modules
 
 FreeSurfer provides several Add-on modules for downstream processing, such as subfield segmentation ( [hippocampus/amygdala](https://surfer.nmr.mgh.harvard.edu/fswiki/HippocampalSubfieldsAndNucleiOfAmygdala), [brainstrem](https://surfer.nmr.mgh.harvard.edu/fswiki/BrainstemSubstructures), [thalamus](https://freesurfer.net/fswiki/ThalamicNuclei) and [hypothalamus](https://surfer.nmr.mgh.harvard.edu/fswiki/HypothalamicSubunits) ) as well as [TRACULA](https://surfer.nmr.mgh.harvard.edu/fswiki/Tracula). We now provide symlinks to the required files, as FastSurfer creates them with a different name (e.g. using "mapped" or "DKT" to make clear that these file are from our segmentation using the DKT Atlas protocol, and mapped to the surface). Most subfield segmentations require `wmparc.mgz` and work very well with FastSurfer,  so feel free to run those pipelines after FastSurfer. TRACULA requires `aparc+aseg.mgz` which we now link, but have not tested if it works, given that [DKT-atlas](https://mindboggle.readthedocs.io/en/latest/labels.html) merged a few labels. You should source FreeSurfer 7.2 to run these modules.