Merge pull request #414 from dkuegler/feature/doc/3T

Update documentation for 2.2 Release

EDITING.md

@@ -30,8 +30,8 @@ Therefore, currently three types of edits are possible:
 Instead of using the original scan as input, you can perform a bias field correction as a pre-processing step. This can also be achieved by running the *asegdkt module* twice (using different subject ids). The second time you input the bias field corrected image ```orig_nu.mgz```
 that was provided from the first run. This can help brighten up some regions and improve segmentation quality for some difficult cases.
 
-- Step_1: In first iteration of field correction method run full pipeline as follows: 
-   ```
+- Step 1: In first iteration of field correction method run full pipeline as follows: 
+   ```bash
    # Source FreeSurfer
    export FREESURFER_HOME=/path/to/freesurfer
    source $FREESURFER_HOME/SetUpFreeSurfer.sh
@@ -43,18 +43,18 @@ that was provided from the first run. This can help brighten up some regions and
    # Run FastSurfer
    ./run_fastsurfer.sh --t1 $datadir/subjectX/t1-weighted-nii.gz \
                     --sid subjectX --sd $fastsurferdir \
-                    --parallel --threads 4
-   ```
-- Step_2: Run pipeline again for the second time, however this time input the bias field corrected image i.e ```orig_nu.mgz``` instead of original input image which was produced in first iteration. The file ```orig_nu.mgz``` can be found in output directory in mri subfolder. The output produced from the second iteration can be saved in a different output directory for comparative analysis with the output produced in first iteration.
+                    --parallel --threads 4 --3T
    ```
+- Step 2: Run pipeline again for the second time, however this time input the bias field corrected image i.e ```orig_nu.mgz``` instead of original input image which was produced in first iteration. The file ```orig_nu.mgz``` can be found in output directory in mri subfolder. The output produced from the second iteration can be saved in a different output directory for comparative analysis with the output produced in first iteration.
+   ```bash
     # Run FastSurfer
    ./run_fastsurfer.sh --t1 $datadir/subjectX/t1-weighted-nii.gz \
                     --sid subjectX --sd $fastsurferdir \
-                    --parallel --threads 4
+                    --parallel --threads 4 --3T
    ```
 
-- Step_3: Run freeview or visualization 
-   ``` 
+- Step 3: Run freeview or visualization 
+   ```bash 
    freeview /path/to/output_directory/orig_nu.mgz
    ``` 
    Note: ```orig_nu.mgz``` file is not a segmented file, for segmentation load ```aparc.DKTatlas+aseg.deep.edited.mgz``` in freeview.
@@ -64,20 +64,20 @@ that was provided from the first run. This can help brighten up some regions and
 
 You can manually edit ```aparc.DKTatlas+aseg.deep.mgz```. This is similar to aseg edits in FreeSurfer. You can fill-in undersegmented regions (with the correct segmentation ID). To re-create the aseg and mask run the following command before continuing with other modules:
 
-- Step_1: Assuming that you have run the full fastsurfer pipeline once as described in method_1 and succesfully produced segmentations and surfaces
-- Step_2: Execute this command where reduce_to_aseg.py is located
-   ```
-   python3 reduce_to_aseg.py -i sid/mri/aparc.DKTatlas+aseg.deep.edited.mgz 
-                             -o sid/mri/aseg.auto_noCCseg.mgz 
-                             --outmask sid/mri/mask.mgz 
+- Step 1: Assuming that you have run the full fastsurfer pipeline once as described in method_1 and succesfully produced segmentations and surfaces
+- Step 2: Execute this command where reduce_to_aseg.py is located
+   ```bash
+   python3 reduce_to_aseg.py -i sid/mri/aparc.DKTatlas+aseg.deep.edited.mgz \ 
+                             -o sid/mri/aseg.auto_noCCseg.mgz \
+                             --outmask sid/mri/mask.mgz \
                              --fixwm
    ```
    Assuming you have edited ```aparc.DKTatlas+aseg.deep.edited.mgz``` in freeview, step_2 will produce two files i.e ```aseg.auto_noCCseg.mgz``` and ```mask.mgz ``` in the specified output folder. The ouput files can be loaded in freeview as a load volume. Edit-->load volume
 
-- Step_3: For this step you would have to copy segmentation files produced in step_1, edited file ```aparc.DKTatlas+aseg.deep.edited.mgz``` and re-created file produced in step_2 in new output directory beforehand. 
+- Step 3: For this step you would have to copy segmentation files produced in step_1, edited file ```aparc.DKTatlas+aseg.deep.edited.mgz``` and re-created file produced in step_2 in new output directory beforehand. 
 
    In this step you can then run surface module as follows:
-   ```
+   ```bash
    # Source FreeSurfer
    export FREESURFER_HOME=/path/to/freesurfer
    source $FREESURFER_HOME/SetUpFreeSurfer.sh
@@ -89,7 +89,7 @@ You can manually edit ```aparc.DKTatlas+aseg.deep.mgz```. This is similar to ase
    # Run FastSurfer
    ./run_fastsurfer.sh --t1 $datadir/subjectX/t1-weighted-nii.gz \
                      --sid subjectX --sd $fastsurferdir \
-                     --parallel --threads 4
+                     --parallel --threads 4 \
                      --surf_only
    ```
    Note: ```t1-weighted-nii.gz``` would be the original input mri image.
@@ -99,11 +99,11 @@ You can manually edit ```aparc.DKTatlas+aseg.deep.mgz```. This is similar to ase
 ## 3. Brainmask Edits: 
 When surfaces go out too far, e.g. they grab dura, you can tighten the mask directly, just edit ```mask.mgz```and start the *surface module*. 
 
-- Step_1: Assuming that you have run the full fastsurfer pipeline once as described in method_1 and succesfully produced segmentations and surfaces
-- Step_2: Edit ```mask.mgz``` file in freeview
-- Step_3: Run the pipeline again in order to get the surfaces but before running the pipeline again do not forget to copy all the segmented files in to new input and output directory. 
+- Step 1: Assuming that you have run the full fastsurfer pipeline once as described in method_1 and succesfully produced segmentations and surfaces
+- Step 2: Edit ```mask.mgz``` file in freeview
+- Step 3: Run the pipeline again in order to get the surfaces but before running the pipeline again do not forget to copy all the segmented files in to new input and output directory. 
    Note: The files in output folder should be pasted in the subjectX folder, the name of subjectX should be the same as it was used in step_1 otherwise it would raise an error of missing files even though the segmentation files exists in output folder.
-   ```
+   ```bash
    # Source FreeSurfer
    export FREESURFER_HOME=/path/to/freesurfer
    source $FREESURFER_HOME/SetUpFreeSurfer.sh
@@ -115,7 +115,7 @@ When surfaces go out too far, e.g. they grab dura, you can tighten the mask dire
    # Run FastSurfer
    ./run_fastsurfer.sh --t1 $datadir/subjectX/t1-weighted-nii.gz \
                      --sid subjectX --sd $fastsurferdir \
-                     --parallel --threads 4
+                     --parallel --threads 4 \
                      --surf_only
    ```
 

INSTALL.md

@@ -21,7 +21,7 @@ Non-NVIDIA GPU architectures (Apple M1, AMD) are not officially supported, but e
 
 Assuming you have singularity installed already (by a system admin), you can build an image easily from our Dockerhub images. Run this command from a directory where you want to store singularity images:
 
-```
+```bash
 singularity build fastsurfer-gpu.sif docker://deepmi/fastsurfer:latest
 ```
 Additionally, [the Singularity README](Singularity/README.md) contains detailed directions for building your own Singularity images from Docker.
@@ -33,7 +33,7 @@ Our [README](README.md#example-2--fastsurfer-singularity) explains how to run Fa
 
 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:
 
-```
+```bash
 docker pull deepmi/fastsurfer:latest
 ```
 
@@ -48,7 +48,7 @@ In a native install you need to install all dependencies (distro packages, FreeS
 
 You will need a few additional packages that may be missing on your system (for this you need sudo access or ask a system admin):
 
-```
+```bash
 sudo apt-get update && apt-get install -y --no-install-recommends \
       wget \
       git \
@@ -58,7 +58,7 @@ sudo apt-get update && apt-get install -y --no-install-recommends \
 
 If you are using **Ubuntu 20.04**, you will need to upgrade to a newer version of libstdc++, as some 'newer' python packages need GLIBCXX 3.4.29, which is not distributed with Ubuntu 20.04 by default.
 
-```
+```bash
 sudo add-apt-repository -y ppa:ubuntu-toolchain-r/test
 sudo apt install -y g++-11
 ```
@@ -73,7 +73,7 @@ If you are using pip, make sure pip is updated as older versions will fail.
 
 We recommend to install conda as your python environment. If you don't have conda on your system, an admin needs to install it:
 
-```
+```bash
 wget --no-check-certificate -qO ~/miniconda.sh https://repo.continuum.io/miniconda/Miniconda3-py38_4.11.0-Linux-x86_64.sh
 chmod +x ~/miniconda.sh
 sudo ~/miniconda.sh -b -p /opt/conda && \
@@ -83,7 +83,7 @@ rm ~/miniconda.sh
 #### 3. FastSurfer
 Get FastSurfer from GitHub. Here you can decide if you want to install the current experimental "dev" version (which can be broken) or the "stable" branch (that has been tested thoroughly):
 
-```
+```bash
 git clone --branch stable https://github.com/Deep-MI/FastSurfer.git
 cd FastSurfer
 ```
@@ -92,7 +92,7 @@ cd FastSurfer
 
 Create a new environment and install FastSurfer dependencies:
 
-```
+```bash
 conda env create -f ./fastsurfer_env_gpu.yml 
 conda activate fastsurfer_gpu
 ```
@@ -101,17 +101,17 @@ If you do not have an NVIDIA GPU, replace `./fastsurfer_env_gpu.yml`  with the c
 If you only want to run the surface pipeline, replace `./fastsurfer_env_gpu.yml` with the reconsurf-only environment file `./fastsurfer_env_reconsurf.yml`.
 
 Next, add the fastsurfer directory to the python path (make sure you have changed into it already):
-```
+```bash
 export PYTHONPATH="${PYTHONPATH}:$PWD"
 ```
 
 This will need to be done every time you want to run FastSurfer, or you need to add this line to your `~/.bashrc` if you are using bash, for example:
-```
+```bash
 echo "export PYTHONPATH=\"\${PYTHONPATH}:$PWD\"" >> ~/.bashrc
 ```
 
 You can also download all network checkpoint files (this should be done if you are installing for multiple users):
-```
+```bash
 python3 FastSurferCNN/download_checkpoints.py --all
 ```
 
@@ -128,15 +128,15 @@ We have successfully run the segmentation on an AMD GPU (Radeon Pro W6600) using
 
 Build the Docker container with ROCm support.
 
-```
-docker build --rm=true -t deepmi/fastsurfer:amd -f ./Docker/Dockerfile_FastSurferCNN_AMD .
+```bash
+python Docker/build.py --device rocm --tag my_fastsurfer:rocm
 ```
 
 You will need to add a couple of flags to your docker run command for AMD, see [the Readme](README.md#example-1--fastsurfer-docker) for `**other-docker-flags**` or `**fastsurfer-flags**`:
-```
+```bash
 docker run --cap-add=SYS_PTRACE --security-opt seccomp=unconfined --device=/dev/kfd \
         --device=/dev/dri --group-add video --ipc=host --shm-size 8G \
-        **other-docker-flags** deepmi/fastsurfer:amd \
+        **other-docker-flags** my_fastsurfer:rocm \
                 **fastsurfer-flags**
 ```
 Note, that this docker image is experimental, uses a different Python version and python packages, so results can differ from our validation results. Please do visual QC.
@@ -158,7 +158,7 @@ Start it and set Memory to 15 GB under Preferences -> Resources (or the largest
 
 Second, pull one of our Docker containers. Open a terminal window and run:
 
-```
+```sh
 docker pull deepmi/fastsurfer:latest
 ```
 
@@ -173,7 +173,7 @@ On modern Macs with the Apple Silicon M1 or M2 ARM-based chips, we recommend a n
 If you do not have git and a recent bash (version > 4.0 required!) installed, install them via the packet manager, e.g. brew.
 This installs brew and then bash:
 
-```
+```sh
 /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
 brew install bash
 ```
@@ -183,37 +183,37 @@ Make sure you use this bash and not the older one provided with MacOS!
 #### 2. Python
 Create a python environment, activate it, and upgrade pip. Here we use pip, but you should also be able to use [conda](#2-conda--for-python-): 
 
-```
+```sh
 python3 -m venv $HOME/python-envs/fastsurfer 
 source $HOME/python-envs/fastsurfer/bin/activate
 python3 -m pip install --upgrade pip
 ```
 
 #### 3. FastSurfer and Requirements
 Clone FastSurfer:
-```
+```sh
 git clone --branch stable https://github.com/Deep-MI/FastSurfer.git
 cd FastSurfer
 export PYTHONPATH="${PYTHONPATH}:$PWD"
 ```
 
 
 Install the FastSurfer requirements
-```
+```sh
 python3 -m pip install -r requirements.mac.txt
 ```
 
 If this step fails, you may need to edit ```requirements.mac.txt``` and adjust version number to what is available. 
 On newer M1 Macs, we also had issues with the h5py package, which could be solved by using brew for help (not sure this is needed any longer):
 
-```
+```sh
 brew install hdf5
 export HDF5_DIR="$(brew --prefix hdf5)"
 pip3 install --no-binary=h5py h5py
 ```
 
 You can also download all network checkpoint files (this should be done if you are installing for multiple users):
-```
+```sh
 python3 FastSurferCNN/download_checkpoints.py --all
 ```
 
@@ -226,7 +226,7 @@ To run the full pipeline, install and source also the supported FreeSurfer versi
 #### 4. Apple AI Accelerator support
 You can also try the experimental support for the Apple Silicon AI Accelerator by setting `PYTORCH_ENABLE_MPS_FALLBACK` and passing `--device mps`:
 
-```
+```sh
 export PYTORCH_ENABLE_MPS_FALLBACK=1
 ./run_fastsurfer.sh --seg_only --device mps ....
 ```