- fix the relative paths

Author: dkuegler

CerebNet/README.md

@@ -0,0 +1,5 @@
+# CerebNet
+Deep learning based tool for segmentation of cerebellar sub-regions.
+
+The training and evaluation scripts of CerebNet are currently not part of the FastSurfer repository and are only available as incompatible stubs from the authors on request via email.
+The interface to realistic deformations can be found in :py:`CerebNet.apply_warp`.

CerebNet/apply_warp.py

@@ -1,3 +1,4 @@
+import argparse
 
 # Copyright 2022 Image Analysis Lab, German Center for Neurodegenerative Diseases (DZNE), Bonn
 #
@@ -90,8 +91,7 @@ def main(img_path, lbl_path, warp_path, result_path, patch_size):
                    affine=lbl_file.affine)
 
 
-if __name__ == '__main__':
-    import argparse
+def make_parser() -> argparse.ArgumentParser:
     parser = argparse.ArgumentParser()
     parser.add_argument("--img_path",
                         help="path to T1 image",
@@ -107,11 +107,17 @@ def main(img_path, lbl_path, warp_path, result_path, patch_size):
                         help="Warp field file",
                         default='1Warp.nii.gz',
                         type=str)
+    return parser
+
 
+if __name__ == '__main__':
+    parser = make_parser()
     args = parser.parse_args()
-    warp_path = join(args.result_path, args.warp_filename)
-    main(args.img_path,
-                      args.lbl_path,
-                      warp_path=warp_path,
-                      result_path=args.result_path,
-                      patch_size=(128, 128, 128))
+    warp_path = str(join(args.result_path, args.warp_filename))
+    main(
+        args.img_path,
+        args.lbl_path,
+        warp_path=warp_path,
+        result_path=args.result_path,
+        patch_size=(128, 128, 128),
+    )

FastSurferCNN/README.md

@@ -1,7 +1,7 @@
 # Overview
 
 This directory contains all information needed to run inference with the readily trained FastSurferVINN or train it from scratch. FastSurferCNN is capable of whole brain segmentation into 95 classes in under 1 minute, mimicking FreeSurfer's anatomical segmentation and cortical parcellation (DKTatlas). The network architecture incorporates local and global competition via competitive dense blocks and competitive skip pathways, as well as multi-slice information aggregation that specifically tailor network performance towards accurate segmentation of both cortical and sub-cortical structures. 
-![](/doc/images/detailed_network.png)
+![](../doc/images/detailed_network.png)
 
 The network was trained with conformed images (UCHAR, 1-0.7 mm voxels and standard slice orientation). These specifications are checked in the run_prediction.py script and the image is automatically conformed if it does not comply.
 

README.md

@@ -20,17 +20,17 @@ The FastSurfer pipeline consists of two main parts for segmentation and surface
 - approximately 5 minutes (GPU), `--seg_only` only runs this part. 
 
 Modules (all run by default):
-1. `asegdkt:` FastSurferVINN for whole brain segmentation (deactivate with `--no_asegdkt`)
+1. `asegdkt:` [FastSurferVINN](FastSurferCNN/README.md) for whole brain segmentation (deactivate with `--no_asegdkt`)
    - the core, outputs anatomical segmentation and cortical parcellation and statistics of 95 classes, mimics FreeSurfer’s DKTatlas.
    - requires a T1w image ([notes on input images](#requirements-to-input-images)), supports high-res (up to 0.7mm, experimental beyond that).
    - performs bias-field correction and calculates volume statistics corrected for partial volume effects (skipped if `--no_biasfield` is passed).
-2. `cereb:` CerebNet for cerebellum sub-segmentation (deactivate with `--no_cereb`)
+2. `cereb:` [CerebNet](CerebNet/README.md) for cerebellum sub-segmentation (deactivate with `--no_cereb`)
    - requires `asegdkt_segfile`, outputs cerebellar sub-segmentation with detailed WM/GM delineation.
    - requires a T1w image ([notes on input images](#requirements-to-input-images)), which will be resampled to 1mm isotropic images (no native high-res support).
    - calculates volume statistics corrected for partial volume effects (skipped if `--no_biasfield` is passed).
 
 ### Surface reconstruction
-- approximately 60-90 minutes, `--surf_only` runs only the surface part.
+- approximately 60-90 minutes, `--surf_only` runs only [the surface part](recon_surf/README.md).
 - supports high-resolution images (up to 0.7mm, experimental beyond that).
 
 <!-- start of image requirements -->
@@ -75,7 +75,7 @@ All installation methods use the `run_fastsurfer.sh` call interface (replace `*f
 
    The `-B` flag is used to tell singularity, which folders FastSurfer can read and write to.
 
-   See also __[Example 2](doc/overview/EXAMPLES.md#example-2-fastSurfer-singularity)__ for a full singularity FastSurfer run command and [the Singularity documentation](Singularity/README.md#fastsurfer-singularity-image-usage) for details on more singularity flags.  
+   See also __[Example 2](doc/overview/EXAMPLES.md#example-2-fastsurfer-singularity)__ for a full singularity FastSurfer run command and [the Singularity documentation](Singularity/README.md#fastsurfer-singularity-image-usage) for details on more singularity flags.  
 
    (b) For __docker__, the syntax is
     ```
@@ -144,7 +144,7 @@ Minimum CPU-only: 8 GB system memory (much slower, not recommended) ``--device c
 
 ## Expert usage
 Individual modules and the surface pipeline can be run independently of the full pipeline script documented in this documentation. 
-This is documented in READMEs in subfolders, for example: [whole brain segmentation only with FastSurferVINN](FastSurferCNN/README.md), [cerebellum sub-segmentation (in progress)](CerebNet/README.md) and [surface pipeline only (recon-surf)](recon_surf/README.md).
+This is documented in READMEs in subfolders, for example: [whole brain segmentation only with FastSurferVINN](FastSurferCNN/README.md), [cerebellum sub-segmentation](CerebNet/README.md) and [surface pipeline only (recon-surf)](recon_surf/README.md).
 
 Specifically, the segmentation modules feature options for optimized parallelization of batch processing.
 

doc/conf.py

@@ -11,6 +11,7 @@
 from importlib import import_module
 import sys
 import os
+from pathlib import Path
 
 # here i added the relative path because sphinx was not able
 # to locate FastSurferCNN module directly for autosummary
@@ -65,7 +66,8 @@
     "myst.duplicate_def",
 ]
 
-myst_heading_anchors = 1
+# create anchors for which headings?
+myst_heading_anchors = 7
 
 templates_path = ["_templates"]
 exclude_patterns = [
@@ -253,23 +255,24 @@ def linkcode_resolve(domain, info):
 # myst_ref_domains = ["myst", "std", "py"]
 
 
-_script_dirs = "fastsurfercnn", "cerebnet", "recon_surf"
+_re_script_dirs = "fastsurfercnn|cerebnet|recon_surf"
+_up = "^/\\.\\./"
+_end = "(\\.md)?(#.*)?$"
 
 # re_reference_target=(regex) => used in missing-reference
 fix_links_target = {
     # all regexpr are ignorecase, individual replacements are applied until no further
     # change occurs, but different (different repl str) replacements are not combined
     # "^\\/overview\\/intro\\.md#": "/overview/index.rst#",
     "^/?(.*)#(.*)ubuntu-(\\d{2})(\\d{2})": ("/\\1#\\2ubuntu-\\3-\\4",),
-    "^/readme\\.md(#.*)?$": ("/index.rst\\1", "/overview/intro.rst\\1"),
-    "^/?(overview/)?intro(\\.rst)?(#.*)?$": ("/overview/index.rst\\3",),
-    "^/?(singularity|docker)/readme\\.md(#.*)?$": ("/overview/\\1.md\\2",),
-    f"^/?({'|'.join(_script_dirs)})/readme\\.md(#.*)?$": ("/scripts/\\1.rst\\2",),
-    "^/?doc/": ("/",),
-    "^/?license": ("/overview/license.rst",),
+    f"{_up}readme{_end}": ("/index.rst\\1", "/overview/intro.rst\\1"),
+    "^/overview/intro(#.*)?$": ("/overview/index.rst\\2",),
+    f"{_up}(singularity|docker)/readme{_end}": ("/overview/\\1.rst\\2",),
+    f"{_up}({_re_script_dirs})/readme{_end}": ("/scripts/\\1.rst\\2",),
+    f"{_up}license": ("/overview/license.rst",),
 }
 fix_links_alternative_targets = {
-    "overview/intro": ("/index.rst", "/overview/index.rst"),
+    "/overview/intro": ("/index.rst", "/overview/index.rst"),
 }
-
+fix_links_project_root = Path("..")
 

doc/index.rst

@@ -9,11 +9,13 @@
 
 .. include:: ../README.md
    :parser: fix_links.parser
+   :relative-docs: .
    :start-after: <!-- start of content -->
    :end-before: <!-- start of image requirements -->
 
 .. include:: ../README.md
    :parser: fix_links.parser
+   :relative-docs: .
    :start-after: <!-- start of references -->
 
 .. toctree::

doc/overview/DOCKER.md

@@ -38,10 +38,10 @@ Note, that the paths following `--fs_license`, `--t1`, and `--sd` are __inside__
 
 A directory with the name as specified in `--sid` (here subjectX) will be created in the output directory if it does not exist. So in this example output will be written to /home/user/my_fastsurfer_analysis/subjectX/ . Make sure the output directory is empty, to avoid overwriting existing files. 
 
-If you do not have a GPU, you can also run our CPU-Docker by dropping the `--gpus all` flag and specifying `--device cpu` at the end as a FastSurfer flag. See [Docker/README.md](Docker/README.md) for more details.
+If you do not have a GPU, you can also run our CPU-Docker by dropping the `--gpus all` flag and specifying `--device cpu` at the end as a FastSurfer flag, see also [FastSurfer's docker documentation](../../Docker/README.md) for more details.
 
 ## Example 2: FastSurfer Singularity
-After building the Singularity image (see below or 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) - same as when using Docker. This license needs to be passed to the script via the `--fs_license` flag. This is not necessary if you want to run the segmentation only.
+After building the Singularity image (see below or [these instructions](../../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) - same as when using Docker. This license needs to be passed to the script via the `--fs_license` flag. This is not necessary if you want to run the segmentation only.
 
 To run FastSurfer on a given subject using the Singularity image with GPU access, execute the following commands from a directory where you want to store singularity images. This will create a singularity image from our Dockerhub image and execute it:
 
@@ -91,7 +91,7 @@ For a native install you may want to make sure that you are on our stable branch
 git clone --branch stable https://github.com/Deep-MI/FastSurfer.git
 ```
 
-More details (e.g. you need all dependencies in the right versions and also FreeSurfer locally) can be found in our [INSTALL.md file](INSTALL.md).
+More details (e.g. you need all dependencies in the right versions and also FreeSurfer locally) can be found in our [Installation guide](INSTALL.md).
 Given you want to analyze data for subject which is stored on your computer under /home/user/my_mri_data/subjectX/t1-weighted.nii.gz, run the following command from the console (do not forget to source FreeSurfer!):
 
 ```bash

doc/overview/EXAMPLES.md

@@ -22,9 +22,9 @@ Assuming you have singularity installed already (by a system admin), you can bui
 ```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.
+Additionally, [the Singularity README](../../Singularity/README.md) contains detailed directions for building your own Singularity images from Docker.
 
-Our [README](doc/overview/EXAMPLES.md#example-2-fastsurfer-singularity) 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). 
+[Example 2](EXAMPLES.md#example-2-fastsurfer-singularity) 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). 
 
 
 ### Docker
@@ -35,7 +35,7 @@ This is very similar to Singularity. Assuming you have Docker installed (by a sy
 docker pull deepmi/fastsurfer:latest
 ```
 
-Our [README](doc/overview/EXAMPLES.md#example-1-fastsurfer-docker) 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 image](https://github.com/Deep-MI/FastSurfer/blob/dev/Docker/README.md). 
+[Example 1](EXAMPLES.md#example-1-fastsurfer-docker) 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 image](https://github.com/Deep-MI/FastSurfer/blob/dev/Docker/README.md). 
 
 
 ### Native (Ubuntu 20.04 or Ubuntu 22.04)
@@ -113,7 +113,7 @@ You can also download all network checkpoint files (this should be done if you a
 python3 FastSurferCNN/download_checkpoints.py --all
 ```
 
-Once all dependencies are installed, you are ready to run the FastSurfer segmentation-only (!!) pipeline by calling ```./run_fastsurfer.sh --seg_only ....``` , see the [README](doc/overview/EXAMPLES.md#example-3-native-fastsurfer-on-subjectx-with-parallel-processing-of-hemis) for command line flags.
+Once all dependencies are installed, you are ready to run the FastSurfer segmentation-only (!!) pipeline by calling ```./run_fastsurfer.sh --seg_only ....``` , see [Example 3](EXAMPLES.md#example-3-native-fastsurfer-on-subjectx-with-parallel-processing-of-hemis) for command line flags.
 
 #### 5. FreeSurfer
 To run the full pipeline, you will need to install FreeSurfer (we recommend and support version 7.3.2) according to their [Instructions](https://surfer.nmr.mgh.harvard.edu/fswiki/rel7downloads). There is a freesurfer email list, if you run into problems during this step. 
@@ -130,7 +130,7 @@ Build the Docker container with ROCm support.
 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](doc/overview/EXAMPLES.md#example-1-fastsurfer-docker) for `**other-docker-flags**` or `**fastsurfer-flags**`:
+You will need to add a couple of flags to your docker run command for AMD, see [Example 1](EXAMPLES.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 \
@@ -160,7 +160,7 @@ Second, pull one of our Docker containers. Open a terminal window and run:
 docker pull deepmi/fastsurfer:latest
 ```
 
-Continue with the example in our [README](doc/overview/EXAMPLES.md#example-1-fastsurfer-docker). 
+Continue with the example in [Example 1](EXAMPLES.md#example-1-fastsurfer-docker). 
 
 
 ### Native
@@ -215,7 +215,7 @@ You can also download all network checkpoint files (this should be done if you a
 python3 FastSurferCNN/download_checkpoints.py --all
 ```
 
-Once all dependencies are installed, run the FastSurfer segmentation only (!!) by calling ```bash ./run_fastsurfer.sh --seg_only ....``` with the appropriate command line flags, see the [README](README.md#usage). 
+Once all dependencies are installed, run the FastSurfer segmentation only (!!) by calling ```bash ./run_fastsurfer.sh --seg_only ....``` with the appropriate command line flags, see the [commandline documentation](../../README.md#usage). 
 
 Note: You may always need to prepend the command with `bash` (i.e. `bash run_fastsurfer.sh <...>`) to ensure that bash 4.0 is used instead of the system default.
 
@@ -247,7 +247,7 @@ After everything is installed, start Windows PowerShell and run the following co
 docker pull deepmi/fastsurfer:cpu-latest
 ```
 
-Now you can run Fastsurfer the same way as described in our [README](doc/overview/EXAMPLES.md#example-1-fastsurfer-docker) for the CPU build, for example:
+Now you can run Fastsurfer the same way as described in [Example 1](EXAMPLES.md#example-1-fastsurfer-docker) for the CPU build, for example:
 ```bash
 docker run -v C:/Users/user/my_mri_data:/data \
            -v C:/Users/user/my_fastsurfer_analysis:/output \
@@ -279,7 +279,7 @@ After everything is installed, start Windows PowerShell and run the following co
 docker pull deepmi/fastsurfer:latest
 ```
 
-Now you can run Fastsurfer the same way as described in our [README](doc/overview/EXAMPLES.md#example-1-fastsurfer-docker), for example:
+Now you can run Fastsurfer the same way as described in [Example 1](EXAMPLES.md#example-1-fastsurfer-docker), for example:
 ```bash
 docker run --gpus all
            -v C:/Users/user/my_mri_data:/data \

doc/overview/INSTALL.md

@@ -0,0 +1,8 @@
+Docker Support
+--------------
+
+.. include:: ../../Docker/README.md
+    :parser: fix_links.parser
+    :relative-docs: .
+    :relative-images:
+    :start-line: 1

doc/overview/SINGULARITY.md

@@ -9,8 +9,8 @@ User Guide
     EXAMPLES.md
     FLAGS.md
     OUTPUT_FILES.md
-    DOCKER.md
-    SINGULARITY.md
+    docker
+    singularity
     EDITING.md
     SECURITY.md
     CODE_OF_CONDUCT.md

doc/overview/docker.rst

@@ -4,20 +4,20 @@ Introduction to FastSurfer
 
 .. include:: ../../README.md
     :parser: fix_links.parser
-    :relative-docs: doc/
+    :relative-docs: .
     :relative-images:
     :start-after: <!-- start of getting started -->
     :end-before: <!-- start of flags -->
 
 .. include:: ../../README.md
     :parser: fix_links.parser
-    :relative-docs: doc/
+    :relative-docs: .
     :relative-images:
     :start-after: <!-- start of image requirements -->
     :end-before: <!-- end of image requirements -->
 
 .. include:: ../../README.md
     :parser: fix_links.parser
-    :relative-docs: doc/
+    :relative-docs: .
     :relative-images:
     :start-after: <!-- start of system requirements -->

doc/overview/index.rst

@@ -0,0 +1,8 @@
+Singularity Support
+-------------------
+
+.. include:: ../../Singularity/README.md
+    :parser: fix_links.parser
+    :relative-docs: .
+    :relative-images:
+    :start-line: 1

doc/overview/intro.rst

@@ -12,3 +12,8 @@ situations, it will be called from `run_fastsurfer.sh` a direct call to
     :module: CerebNet.run_prediction
     :func: setup_options
     :prog: CerebNet/run_prediction.py
+
+
+.. include:: ../../CerebNet/README.md
+    :parser: fix_links.parser
+    :start-line: 1

doc/overview/singularity.rst

@@ -3,7 +3,7 @@ FastSurferCNN: generate_hdf5.py
 
 .. include:: ../../FastSurferCNN/README.md
    :parser: fix_links.parser
-   :relative-docs: doc/
+   :relative-docs: .
    :relative-images:
    :start-after: <!-- after inference heading -->
    :end-before: <!-- before generate_hdf5 -->

doc/scripts/cerebnet.rst

@@ -6,7 +6,7 @@ FastSurferCNN: run_prediction.py
 
 .. include:: ../../FastSurferCNN/README.md
    :parser: fix_links.parser
-   :relative-docs: doc/
+   :relative-docs: .
    :relative-images:
    :start-after: <!-- after inference heading -->
    :end-before: <!-- before generate_hdf5 -->

doc/scripts/fastsurfercnn.generate_hdf5.rst

@@ -3,7 +3,7 @@ FastSurferCNN: run_model.py
 
 .. include:: ../../FastSurferCNN/README.md
    :parser: fix_links.parser
-   :relative-docs: doc/
+   :relative-docs: .
    :relative-images:
    :start-after: <!-- after training heading -->
 

doc/scripts/fastsurfercnn.rst

@@ -2,8 +2,8 @@ Surface pipeline: recon-surf.sh
 ===============================
 
 .. include:: ../../recon_surf/README.md
-   :parser: myst_parser.sphinx_
-   :relative-docs: doc/
+   :parser: fix_links.parser
+   :relative-docs: .
    :relative-images:
    :heading-offset: 1