Skip to content

Release Notes

2.1.1_8.1.0 [2026-01-13]

Maintenance:

  • Updated flywheel/freesurfer-recon-all image tag from 2.1.0_8.1.0 to 2.1.1_8.1.0

2.1.0_8.1.0 [2025-12-16]

Enhancements:

  • Added HPC support by relocating SUBJECTS_DIR and FS_LICENSE to /flywheel/v0/work, ensuring read-write access for both Flywheel analysis engines and HPC systems.
  • Refactored postprocessing retry logic so each step is retried independently, allowing subsequent steps to run even if an earlier step fails.
  • Added retry_step() helper function to encapsulate per-step retry behavior with up to MAX_RETRIES attempts on RuntimeError.
  • Updated srf2obj utility to accept an output file argument directly instead of requiring shell redirection, removing the need for shell=True in do_gear_convert_surfaces.

Fixes:

  • Fixed do_gear_convert_surfaces to invoke srf2obj with shell=False and pass the output file path as an argument, resolving a potential shell injection risk.
  • Fixed gear_environ.json to be written to and read from /flywheel/v0/gear_environ.json instead of /tmp/gear_environ.json.
  • Fixed SUBJECTS_DIR and FS_LICENSE constants to respect environment variables set at runtime, falling back to /flywheel/v0/work paths.
  • Fixed default CPU count to use half of available CPUs (os.cpu_count() // 2) to prevent out-of-memory errors during parallel recon-all execution.

Maintenance:

  • Updated urllib3 minimum version from >=2.5.0 to >=2.6.0.
  • Updated PYTHONPATH in manifest environment to include the full Python version path (/venv/lib/python3.12/site-packages).
  • Added UV_PYTHON_DOWNLOADS, UV_PYTHON, PYTHONDONTWRITEBYTECODE, UV_LINK_MODE, and UV_COMPILE_BYTECODE environment variables to manifest.json.
  • Updated FREESURFER_VERSION environment variable in manifest from 7.4.1 to 8.1.0.
  • Also remove yq from /opt/bin in Dockerfile cleanup step.
  • Updated test suite to reflect per-step retry refactor and new CPU count behavior.

Documentation:

  • Updated Flywheel license guide URLs across docs/details.md, docs/faqs.md, docs/overview.md, and docs/usages.md.
  • Updated docs/usages.md SDK installation link to point to the current api-docs.flywheel.io reference.
  • Added FAQ entry explaining SUBJECTS_DIR and FS_LICENSE are hard-coded to /flywheel/v0/work for permissions compatibility.
  • Added FAQ entry with workarounds for OOM / bad alloc errors caused by synthseg memory usage.
  • Updated runtime estimate in docs/faqs.md from 4–6 hours to 3–4 hours with clarifying notes on standard analysis engine specs.
  • Added HPC Support section to docs/overview.md explaining the rationale for fixed SUBJECTS_DIR and FS_LICENSE locations.

2.0.3_8.1.0 [2025-10-23]

Enhancements:

  • Upgraded FreeSurfer from 7.2.0 to 8.1.0
  • Added recon_all.txt and post_processing.txt log files to capture command output
  • Added stdbuf line-buffering to all FreeSurfer commands for real-time log streaming via prepare_command_with_stdbuf()
  • Added global-expert-options file to force mris_fix_topology -threads 1 for improved stability
  • Added --no-annot flag to surfreg calls to avoid medial wall artifacts
  • Added cleanup of existing surfreg output files before re-running surface registration to support idempotent re-runs
  • Added EXEC_ALWAYS_PRINT_RE environment variable to filter and display relevant FreeSurfer log lines in real time
  • Added fw_gear_freesurfer_recon_all/constants.py module with shared constants (THROTTLE_SECONDS, MAX_RETRIES) and utilities
  • Added fw_gear_freesurfer_recon_all/utils.py module with write_log_section_header() and text_file_to_csv_file() utilities
  • Replaced segmentHA_T1.sh, segmentBS.sh, segmentThalamicNuclei.sh with segment_subregions subcommand for FreeSurfer 8.1.0 compatibility
  • Updated output filenames for hippocampal, brainstem, and thalamic segmentations to match FreeSurfer 8.1.0 naming conventions
  • Added patch/surfreg script patched for FreeSurfer 8.1.0

Fixes:

  • Fixed execute_recon_all_command retry logic to correctly attempt MAX_RETRIES times instead of hardcoded 2
  • Fixed bare except clause in check_for_previous_run to catch specific exceptions (zipfile.BadZipFile, KeyError, IndexError)
  • Fixed get_input_file to use exist_ok=True when creating dicoms directory
  • Fixed mock_unzip_archive test helper signature to match the actual unzip_archive call signature

Maintenance:

  • Migrated from flywheel-gear-toolkit to fw-gear==0.3.2 library
  • Migrated from poetry to uv / hatchling for dependency management
  • Migrated Dockerfile base from freesurfer/freesurfer:7.2.0 (CentOS) to flywheel/python:3.12-debian with FreeSurfer installed from flywheel/freesurfer:0.3.0_8.1.0
  • Upgraded python from 3.8 to 3.12
  • Replaced miniconda / conda Python environment with uv virtual environment (/venv)
  • Added multi-stage Dockerfile build (base, build, dev, final)
  • Refactored main.py into preprocessing.py, postprocessing.py, and utils.py modules
  • Moved set_core_count() and parse_config() logic to parser.py
  • Removed gear-log-level config option; logging level now managed by fw-gear
  • Updated manifest.json command from /root/miniconda3/bin/python3 run.py to python run.py
  • Added requirements-dev.txt and updated .dockerignore to include it
  • Added flywheel-sdk==20.3.0, numpy>=1.23.0,<2, jinja2==3.1.6, requests>=2.32.4, urllib3>=2.5.0 as explicit dependencies
  • Updated CI to use PYVER: "3.12", larger runner, and 6h timeout
  • Refactored and expanded test suite to cover new module structure, parse_config, get_and_sanitize_subject_id, zip_and_cleanup_outputs, format_execution_results, write_log_section_header, and prepare_command_with_stdbuf
  • Removed test_make_file_name_safe.py and test_parser.py (replaced by test_parse_config.py)

Documentation:

  • Fixed trailing whitespace throughout CONTRIBUTING.md, docs/details.md, docs/faqs.md, docs/overview.md, and docs/usages.md
  • Improved hyperlink text phrasing across documentation pages

Breaking Changes:

  • Removed gear-log-level configuration option
  • Post-processing segmentation output filenames changed to match FreeSurfer 8.1.0 conventions (e.g., brainstemSsLabels.volumes.csv replaces brainstemSsVolumes.v2.csv, ThalamicNuclei.volumes.csv replaces ThalamicNuclei.v12.T1.volumes.csv)

2.0.2_7.2.0 [2024-11-15]

Fixes:

  • Changed default value of parallel config option from true to false

Documentation:

  • Updated Flywheel FreeSurfer license guide URLs across details.md, faqs.md, overview.md, and usages.md
  • Clarified parallel option description to reflect updated default of false

2.0.1_7.2.0 [2024-09-13]

Fixes:

  • Fixed command config construction in main.py to explicitly include debug, parallel, reconall_options, and openmp parameters, avoiding a podman issue caused by passing -c as an option.

Maintenance:

  • Updated Dockerfile to refresh CentOS-Base.repo from an Aliyun mirror and run yum cache update to fix broken package repository.
  • Added hadolint linter ignore directives and fixed ENV syntax to use key=value format in Dockerfile.
  • Used --no-cache-dir flag with pip install in Dockerfile.
  • Updated CI configuration to use flywheel-io/tools/etc/qa-ci pipeline and added medium runner override for test:gear.
  • Updated pre-commit hooks to add hadolint, jsonlint, linkcheck, markdownlint, ruff_format, and pytest; removed docker_build and generate_docs hooks.
  • Fixed variable shadowing in test mocks by using unique names (mock_zipfile1, mock_zipfile2, mock_zipfile3).
  • Updated exc.type == SystemExit to exc.type is SystemExit in tests.

Documentation:

  • Reformatted docs/details.md, docs/faqs.md, docs/index.md, docs/overview.md, and docs/usages.md to fix trailing whitespace, line lengths, and markdown linting issues.
  • Updated usage example code blocks to use python syntax highlighting.
  • Converted section headings in docs/usages.md from ### to ##.
  • Removed custom docs/overrides/partials/footer.html template.
  • Added empty docs/changelog.md file.

2.0.0_7.2.0 [2024-04-11]

Enhancements:

  • Added text_file_to_csv_file() helper to convert space-separated text files to CSV using the standard csv module, replacing shell-based tr commands.
  • Added output of hypothalamic subunits CSV file to the gear output directory via shutil.copy.

Fixes:

  • Removed metadata writing from postprocessing functions (do_gear_hippocampal_subfields, do_gear_brainstem_structures, do_gear_thalamic_nuclei, do_gear_convert_stats), eliminating a dependency on pandas for metadata population.
  • Fixed do_gear_hypothalamic_subunits to accept and pass mri_dir parameter required for locating output files.

Maintenance:

  • Replaced pandas import in main.py with standard library csv and shutil modules.
  • Pinned flywheel-gear-toolkit to 0.6.18.
  • Added mkdocs and related documentation dependencies to the dev dependency group in pyproject.toml.
  • Updated CI configuration to use ci/large-default.yml and enabled PUBLISH_PAGES.
  • Updated pre-commit hook to use generate_docs instead of pytest.
  • Added .gitignore with standard Python, macOS, and editor exclusions.
  • Updated test suite for postprocessing functions to use pytest-mock and improved assertion coverage.
  • Added tests for the new text_file_to_csv_file() function with pivot, no-pivot, and dry-run scenarios.
  • Added test asset files for text_file_to_csv_file tests.

Documentation:

  • Replaced the detailed inline README.md with a concise overview linking to the hosted mkdocs documentation site.
  • Added full mkdocs documentation site including index.md, overview.md, details.md, usages.md, faqs.md, and supporting assets.
  • Added mkdocs.yml configuration with Material theme and standard plugins.
  • Updated manifest.json source URL to point to the new GitLab repository location.

1.2.3_7.2.0 [2024-03-27]

Enhancements:

  • Added FreeSurfer 7.2.0 gear implementing full recon-all cortical reconstruction pipeline
  • Added support for multiple T1w anatomical inputs (t1w_anatomical_2 through t1w_anatomical_5) averaged together for motion correction
  • Added T2w/FLAIR anatomical input support to improve pial surface reconstruction
  • Added optional hippocampal subfield segmentation with CSV output
  • Added optional brainstem structure segmentation with CSV output
  • Added optional thalamic nuclei parcellation with CSV output
  • Added optional hypothalamic subunit segmentation
  • Added optional high-resolution segmentation via gtmseg
  • Added surface registration to fsaverage_sym template via xhemireg and surfreg
  • Added conversion of FreeSurfer surface files to OBJ format for Flywheel platform visualization
  • Added conversion of FreeSurfer volume files from MGZ to NIfTI format
  • Added conversion of FreeSurfer stats files to CSV format
  • Added post-processing-only mode for re-running post-processing on existing recon-all output archives
  • Added gear-dry-run mode for testing without executing recon-all
  • Added FreeSurfer license support via file input, config key, or project metadata
  • Added analysis metadata export for subcortical volumes, cortical parcellations, and optional segmentation outputs

Maintenance:

  • Added Dockerfile based on freesurfer/freesurfer:7.2.0 with miniconda3 python 3.8.5 environment
  • Added patched recon-all script fixing known race condition and parallel processing bugs introduced in FreeSurfer 7.1.1
  • Added flywheel-gear-toolkit ^0.6 and flywheel-sdk ^16.8.0 dependencies
  • Added pandas 1.5.1 dependency for stats file processing
  • Added CI/CD configuration via .gitlab-ci.yml
  • Added pre-commit hooks including gearcheck, ruff, and pytest
  • Added merge request template with release notes and testing checklist

Documentation:

  • Added README.md with full gear documentation including inputs, configuration options, outputs, and usage examples
  • Added CONTRIBUTING.md with development setup and release workflow instructions
  • Added FAQ.md for common questions and errors