FreeSurfer Helper is a small Tkinter-based desktop application for Ubuntu Linux that helps non-technical users run DICOM-to-NIfTI conversion and FreeSurfer recon-all commands without using the terminal.

• Name: Mackay Chirwa
• Email: [email protected]

Running FreeSurfer from the terminal can be intimidating, especially for clinicians, students, and researchers who are not comfortable with long command lines and environment variables. This helper application was created to:

• Provide a simple, guided 3-step workflow: DICOM → NIfTI → FreeSurfer.
• Reduce mistakes related to SUBJECTS_DIR, missing flags, and wrong paths.
• Make it easier to resume long-running recon-all jobs after interruptions.
• Let experienced users still control options like parallel processing without having to remember the exact command syntax.

The goal is to make FreeSurfer more accessible while still being safe and transparent about what is happening under the hood.

• Simple, beginner-friendly graphical interface.
• Select a subject folder containing DICOM data.
• Enter a subject ID.
• Select an output directory for FreeSurfer (SUBJECTS_DIR).
• Convert DICOM to NIfTI using dcm2niix.
• Run recon-all for a new subject or resume processing.
• Detect if a subject folder already exists and optionally skip reprocessing.
• Scrollable log window showing commands, progress messages, and errors.
• Progress bar and disabled buttons while commands are running.

• Ubuntu with a working graphical desktop.
• Python 3 (for development and building).
• FreeSurfer installed and configured:
  • recon-all must be available on the PATH.
  • Your usual FreeSurfer environment should be sourced (e.g. FREESURFER_HOME).
• DICOM conversion tool:
  • dcm2niix installed and available on the PATH.

The generated executable does not bundle FreeSurfer or dcm2niix; they must be installed separately on the system.

python3 app.py

1. Install PyInstaller in your environment:

python3 -m pip install pyinstaller

2. From the project directory, build the application:

pyinstaller --onefile --windowed app.py

3. After the build completes, the executable will be created in the dist/ directory, for example:

dist/app

You can copy this single file to other Ubuntu machines. Users can then launch it by double-clicking it in their file manager or running it from a terminal:

./app

Remember: FreeSurfer (recon-all) and dcm2niix still need to be installed and configured on the target machine. If they are missing, the application will show clear error messages in the log window.

Contributions are welcome. Ideas that are especially helpful:

• Improving the beginner-friendly workflow or wording in the interface.
• Adding safe, easy-to-understand options for more advanced FreeSurfer flags.
• Better progress reporting (for example, parsing recon-all output).
• Additional safety checks that prevent common mistakes.

To contribute:

1. Fork this repository.
2. Create a feature branch (git checkout -b feature/my-improvement).
3. Make your changes and add clear logs/messages for non-technical users.
4. Open a pull request describing what you changed and why.

If you find a bug or have a feature request but cannot code it yourself, you can also open an issue explaining your use case.

If this tool is useful in your work and you would like to support further development, you can reach out or send support via PayPal to:

• Email / PayPal: [email protected]