Skip to content

Various updates and changes to the documentation #765

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
dkuegler wants to merge 12 commits into
base: dev
Choose a base branch
from
Open

Various updates and changes to the documentation #765

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
12 commits
Select commit Hold shift + click to select a range
2e4edfe
Fix the message that checked if cpu_only was run without more time bu…
dkuegler Nov 8, 2024
c058924
Clean up some formatting in several files
dkuegler Jan 24, 2025
6046be7
Help for when singularity builds fail
dkuegler Aug 27, 2024
f5dddb5
Unifying formatting in doc
dkuegler Feb 20, 2025
d7b560b
Fix trailing spaces
dkuegler Jan 21, 2026
198214f
Streamline the Contribution page
dkuegler Mar 5, 2025
b25be2e
Update the github issue templates
dkuegler Feb 20, 2025
fd2cc9f
Fix the link to FLAGS in cc doc
dkuegler Jan 6, 2026
27f3efe
Fix doc/conf.py
dkuegler Jan 19, 2026
e88fd63
Add better error text for heading level inconsistencies
dkuegler Jan 21, 2026
0b22293
Update version numbers in documentation
dkuegler Jan 21, 2026
ded6114
Ignore numpydoc GL09 warning, which is coming from the parent torch c…
dkuegler Jan 21, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
88 changes: 54 additions & 34 deletions .github/ISSUE_TEMPLATE/bug-report.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,52 +1,72 @@
---
name: Bug Report
about: Create a bug report to help us improve FastSurfer
about: You observed a behavior of FastSurfer that is clearly not intended, i.e. not working as intended.
title: ''
labels: bug
assignees: ''

---
Bug Report
==========
<!--
Please take a look at the contribution guide https://deep-mi.org/FastSurfer/dev/overview/CONTRIBUTING.html

## Description
<!-- A clear and concise description of the observed bug and/or error -->
....
This issue type is for:
You observed a behavior of FastSurfer that is clearly not intended, i.e. not working as intended.

## Steps to Reproduce
<!--
Steps to reproduce the observed behaviour, in as much detail as possible:
1. Go to '...'
2. Checkout version '...'
3. Run '....'
4. See error
Please provide clear and concise description of:
-->

<!-- If possible, provide error messages, stack traces, and any snippets useful in describing the bug here -->
...
Description
-----------
Which functionality, script, interface or interaction does this bug concern?

## Expected Behavior
<!-- A clear and concise description of what you expected to happen. -->
...
Expected Behavior
-----------------
Please provide a clear and concise description of what you expected to happen and/or how this is different to what you
expected. This also important to determine, if your expectation is also FastSurfer's intention.

## Log Files /Screenshots
<!-- Please attach the following log files: `$SUBJECTS_DIR/$SUBJECT_ID/scripts/deep-seg.log` and `$SUBJECTS_DIR/$SUBJECT_ID/scripts/recon-surf.log`. If applicable and desired, add screenshots to help illustrate your problem. -->
...
Steps to Reproduce
------------------
How can others reproduce this behavior? Please provide a step-by-step guide! If applicable provide error messages, stack
traces, and/or code snippets here. Make sure to **include the command causing the observed behavior** here!

## Environment
- Docker/Singularity Image (version?) or local install
- FastSurfer Version: ...
- FreeSurfer Version: ... <!-- if applicable -->
- OS: ... <!-- Linux Version, Windows, Mac -->
- GPU: ... <!-- e.g. RTX 2080 ... -->
<!-- Add any other relevant information on the environment here -->
1. Go to '...'
2. Checkout version '...'
3. Run '...'
4. The observed behavior/error is '...'

This is very important to understand and repair the behavior, bug, etc. Best, copy-paste your code or command line call,
but it is also completely fine to use screenshots.

Log Files / Screenshots
-----------------------
Please attach your log files here. They help understanding problems, FastSurfer version, your recognized hardware, etc.

<!-- If you ran FastSurfer locally, include a snapshot of the python software package versions you have (for e.g., using pip freeze or conda list) here -->
If you are interacting with the standard entrypoint scripts, the relevant log files are:
* `run_fastsurfer.sh`: Log files `$SUBJECTS_DIR/$SUBJECT_ID/scripts/deep-seg.log`,
`$SUBJECTS_DIR/$SUBJECT_ID/scripts/BUILD.log` and `$SUBJECTS_DIR/$SUBJECT_ID/scripts/recon-surf.log` (unless use are
running with `--seg_only`).
* `long_fastsurfer.sh`: Log files `$SUBJECTS_DIR/$TEMPLATE_ID/scripts/long_fastsurfer.log`.
* `brun_fastsurfer.sh`: Same as `run_fastsurfer.sh`.
* `srun_fastsurfer.sh`: All log files in the work log-directory (`<work>/slurm/logs` and `<work>/slum/scripts`), you may
choose select one example processing log from there, e.g. `seg_XXXX.log` and `surf_XXXX_Y.log`, try to select a case
affected by the bug.

### Execution
<!-- If you ran FastSurfer in a docker container, include the commands used to build and run the container here -->
If you can/want to share data privately with the FastSurfer team, you may use the following dropbox:
https://nextcloud.dzne.de/index.php/s/Z2qtHW8c7p3NSJ5

<!-- If you ran FastSurfer locally, include the command you used to run FastSurfer here -->
Run Command: <!-- For e.g. `\run_fastsurfer.sh ...` -->
Environment
-----------
Please describe how and which version of FastSurfer you are using. For this fill out the list below!

- **Installation type**: Docker / Singularity Image / native install
- FastSurfer Version: `run_fastsurfer.sh --version all` gives full version information, see also `scripts/BUILD.log`.
- FreeSurfer Version (if you are running a native install): FILL IN HERE
- OS: Linux Version / Windows / Mac
- GPU: e.g. RTX 2080 / ...
<!-- Add any other relevant information on the environment here -->

## Additional Context
<!-- Add any other context and comments about the problem here. -->
...
Additional Context
------------------
Add any other context and comments about the problem here.
32 changes: 28 additions & 4 deletions .github/ISSUE_TEMPLATE/documentation.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,12 +1,36 @@
---
name: Documentation
about: Report an issue or make a suggestion related to FastSurfer documentation
about: |
You are learning about FastSurfer, but part of the documentation is incomplete, outdated or wrong. Also, your use-case
is not covered in the documentation, but you think it is common (or you could not find a solution in other issues).
title: ''
labels: documentation
assignees: ''

---
Documentation Request
=====================
<!--
Please take a look at the contribution guide https://deep-mi.org/FastSurfer/dev/overview/CONTRIBUTING.html

## Documentation
<!-- A clear and concise description of an issue you observed in the documentation, or a suggestion you wish to make. -->
...
This issue type is for:
You are learning about FastSurfer, but part of the documentation is wrong, outdated or incomplete. Also, your use-case
is not covered in the documentation, but you think it is common (or you could not find a solution in other issues).

Please provide clear and concise description of:
-->

Description
-----------
What documentation is this request referencing?

Expected/Proposed Documentation
-------------------------------
What kind of documentation would you expect? What should this include?

If you can provide this documentation, please do! If you want to get credit create a pull request, see the contribution
guide https://deep-mi.org/FastSurfer/dev/overview/CONTRIBUTING.html

Existing Documentation
----------------------
If there is existent documentation, which should be updated or extended, link it. How is this different to what exists?
76 changes: 58 additions & 18 deletions .github/ISSUE_TEMPLATE/questions-help-support.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,30 +1,70 @@
---
name: Questions/Help/Support
about: Submit a request for support or a question
about: You need help in using FastSurfer, for example in interpreting an error message.
title: ''
labels: question
assignees: ''

---
General Support Request
=======================
<!--
Please take a look at the contribution guide https://deep-mi.org/FastSurfer/dev/overview/CONTRIBUTING.html

This issue type is for:
You need help in using FastSurfer, for example in interpreting an error message.

Please provide clear and concise description of:
-->

Description
-----------
What are you trying to achieve?

Steps that lead to your Issue
-----------------------------
Did you find an example/solution in the documentation/external guides that you are following? Please copy-paste a link
or the text of these instructions.

If your results did not match your expectations, please provide a step-by-step guide to reproduce these results and
state your expectations!
If applicable provide error messages, stack traces, and/or code snippets here. Make sure to **include the
commands causing the observed behavior** here, i.e. the commands that brought you to your question!

1. Go to '...'
2. Checkout version '...'
3. Run '....'

This is very important to understand where you are and how to help. Best, copy-paste your code or command line call,
but it is also completely fine to use screenshots.

**IMPORTANT**: Please make sure to fill out the information about your environment (see below). This is often critical information we need to help you.
Log Files / Screenshots
-----------------------
Please attach your log files here. They help understanding problems, FastSurfer version, your recognized hardware, etc.

## Question/Support Request
A clear and concise description of a question you may have or a problem for which you would like to request support.
If you are interacting with the standard entrypoint scripts, the relevant log files are:
* `run_fastsurfer.sh`: Log files `$SUBJECTS_DIR/$SUBJECT_ID/scripts/deep-seg.log`,
`$SUBJECTS_DIR/$SUBJECT_ID/scripts/BUILD.log` and `$SUBJECTS_DIR/$SUBJECT_ID/scripts/recon-surf.log` (unless use are
running with `--seg_only`).
* `long_fastsurfer.sh`: Log files `$SUBJECTS_DIR/$TEMPLATE_ID/scripts/long_fastsurfer.log`.
* `brun_fastsurfer.sh`: Same as `run_fastsurfer.sh`.
* `srun_fastsurfer.sh`: All log files in the work log-directory (`<work>/slurm/logs` and `<work>/slum/scripts`), you may
choose select one example processing log from there, e.g. `seg_XXXX.log` and `surf_XXXX_Y.log`, try to select a case
affected by the bug.

## Screenshots / Log files
Please provide error messages (can be a screenshot), stack traces, log files (specifically `$SUBJECTS_DIR/$SUBJECT_ID/scripts/deep-seg.log` and `$SUBJECTS_DIR/$SUBJECT_ID/scripts/recon-surf.log`) and any snippets useful in describing your problem here.
If you can/want to share data privately with the FastSurfer team, you may use the following dropbox:
https://nextcloud.dzne.de/index.php/s/Z2qtHW8c7p3NSJ5

## Environment
- FastSurfer Version: please run `run_fastsurfer.sh --version all` and copy/attach the resulting output
- Installation type: official docker/custom docker/singularity/native <!-- please remove not applicable; if you are running a custom docker please add how you built it. -->
- FreeSurfer Version: 7.4.1/7.3.2 <!-- if applicable -->
- OS: Windows/Linux/macOS <!-- please specify -->
- GPU: none/RTX 2080/... <!-- please specify -->
Environment
-----------
Please describe how and which version of FastSurfer you are using. For this fill out the list below!

<!-- more infos -->
...
- **Installation type**: official docker image / custom docker image / singularity / native
- **FastSurfer version**: `run_fastsurfer.sh --version all` gives full version information, see also `scripts/BUILD.log`.
- **FreeSurfer version** (if you are running a native install): 7.4.1 / 7.3.2 / ...
- **OS**: Linux (Ubuntu) / Windows / Mac / ...
- **GPU**: none / RTX 2080 / ...
<!-- Add any other relevant information on the environment here -->

### Execution
Include the command you used to run FastSurfer that cause the problem, e.g.
`./run_fastsurfer.sh --sid test --sd /path/to/dir --t1 /path/to/file.nii`.
Additional Context
------------------
Add any other context and comments about the problem here.
48 changes: 18 additions & 30 deletions .github/workflows/QUICKTEST.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,58 +1,46 @@
# FastSurfer Singularity GitHub Actions Workflow
FastSurfer Singularity GitHub Actions Workflow
==============================================

This GitHub Actions workflow is designed to automate the integration testing of new code into the FastSurfer repository using Singularity containers. The workflow is triggered whenever new code is pushed to the repository.

The workflow runs on a self-hosted runner labelled 'ci-gpu' to ensure security.

## Jobs
This GitHub Actions workflow is designed to automate the integration testing of new code into the FastSurfer repository
using Singularity containers. The workflow is triggered whenever new code is pushed to the repository.

Jobs
----
The workflow consists of several jobs that are executed in sequence:

### Checkout

This job checks out the repository using the `actions/checkout@v2` action.

### Prepare Job

This job sets up the necessary environments for the workflow. It depends on the successful completion of the `checkout` job. The environments set up in this job include:

- Python 3.10, using the `actions/setup-python@v3` action.
- Go, using the `actions/setup-go@v5` action with version `1.13.1`.
- Singularity, using the `eWaterCycle/setup-singularity@v7` action with version `3.8.3`.

### Build Singularity Image

This job builds a Docker image and converts it to a Singularity image. It depends on the successful completion of the `prepare-job`. The Docker image is built using a Python script `tools/Docker/build.py` with the `--device cuda --tag fastsurfer_gpu:cuda` flags. The Docker image is then converted to a Singularity image.
This job builds a Docker image and converts it to a Singularity image. It depends on the successful completion of the `prepare-job`. The Docker image is built using a Python script `tools/Docker/build.py` with the `--device cuda --tag fastsurfer_gpu:cuda` flags. The Docker image is then converted to a Singularity image.

### Run FastSurfer

This job runs FastSurfer on sample MRI data using the Singularity image built in the previous job. It depends on the successful completion of the `build-singularity-image` job. The Singularity container is executed with the `--nv`, `--no-home`, and `--bind` flags to enable GPU access, prevent home directory mounting, and bind the necessary directories respectively. The `FASTSURFER_HOME` environment variable is set to `/fastsurfer-dev` inside the container.

### Test File Existence

This job tests for the existence of certain files after running FastSurfer. It depends on the successful completion of the `run-fastsurfer` job. The test is performed using a Python script `test/test_file_existence.py`.

### Test Error Messages

This job tests for errors in log files after running FastSurfer. It runs on a self-hosted runner labeled `ci-gpu` and depends on the successful completion of both the `run-fastsurfer` and `test-file-existence` jobs. The test is performed using a Python script `test/test_error_messages.py`.

## Usage

Usage
-----
To use this workflow, you need to have a self-hosted runner labeled `ci-gpu` set up on your machine. You also need to update the environment variables of the runner, by going to `/home/your_runner/.env` file and adding the following environment variables with the actual paths you want to use.


### Environment variables
`RUNNER_FS_MRI_DATA`: Path to MRI Data

`RUNNER_FS_OUTPUT`: Path to Output directory

`RUNNER_FS_LICENSE`: Path to License directory

`RUNNER_SINGULARITY_IMGS`: Path to where Singularity images should be stored

`RUNNER_FS_OUTPUT_FILES`: Path to output files to be tested

`RUNNER_FS_OUTPUT_LOGS`: Path to output log files to check for errors


Once everything is set up, you can trigger the workflow manually from the GitHub Actions tab in your repository, as well as by pushing code to the repository.
- `RUNNER_FS_MRI_DATA`: Path to MRI Data
- `RUNNER_FS_OUTPUT`: Path to Output directory
- `RUNNER_FS_LICENSE`: Path to License directory
- `RUNNER_SINGULARITY_IMGS`: Path to where Singularity images should be stored
- `RUNNER_FS_OUTPUT_FILES`: Path to output files to be tested
- `RUNNER_FS_OUTPUT_LOGS`: Path to output log files to check for errors

Once everything is set up, you can trigger the workflow manually from the GitHub Actions tab in your repository, as well
as by pushing code to the repository.
Loading
Loading