Skip to content

Release Notes

0.2.2_7.4.1 [2026-08-19]

Enhancements:

  • Added merge_hemi_volumes_txt_to_csv() and pivot_volumes_txt_to_csv() utility functions to produce wide-format CSVs compatible with Flywheel DataViews for cross-subject aggregation.
  • Added output_configuration.enforce_file_version_match to manifest.json to enforce output file version consistency.

Fixes:

  • Fixed incorrect os.path.unlink() call (should be os.unlink()) that would raise AttributeError when removing the fsaverage symlink.
  • Replaced fragile shell symlink commands for hippocampal, thalamic, and brainstem segmentation outputs with direct file references using stable FreeSurfer 8 filenames (lh.hippoAmygLabels.FSvoxelSpace.mgz, ThalamicNuclei.FSvoxelSpace.mgz, brainstemSsLabels.FSvoxelSpace.mgz).
  • Removed broken Left-Brain-Stem / Right-Brain-Stem split logic from separate_aparc2009_rois that depended on intermediate temp files and AFNI 3dcalc coordinate-space arithmetic.
  • Fixed LUT line filtering in segAparc2009, sep_brainstem, and sep_hippo to correctly skip blank lines using s.strip() instead of s != "\n".

Maintenance:

  • Migrated from poetry to uv for dependency management and build system.
  • Upgraded base image from python:3.9 (Debian) to flywheel/python:3.12-wolfi-build (Wolfi/Chainguard), upgrading python from 3.9.15 to 3.12.13.
  • Upgraded FreeSurfer from flywheel/freesurfer:0.1.0_7.4.1 to flywheel/freesurfer:0.3.0_8.1.0 and updated segmentation commands to use the FreeSurfer 8 segment_subregions interface instead of the legacy MATLAB MCR scripts (segmentHA_T1.sh, segmentThalamicNuclei.sh, segmentBS.sh).
  • Replaced aria2c and wget atlas downloads with curl to match the Wolfi base image tool availability.
  • Restructured Dockerfile into multi-stage build (base, build, dev, prod) to separate production and development dependency installation.
  • Added tcsh vendored from the FreeSurfer builder stage to satisfy FreeSurfer script shebangs on the Wolfi base (where tcsh is not available via apk).
  • Removed unused compiled MATLAB helper files (readme.txt, requiredMCRProducts.txt) and removed the fixAllSegmentations post-processing step from the thalamic segmentation pipeline.
  • Added uv.lock, requirements-dev.txt, and tests/ to .dockerignore allowlist to support the dev Docker stage.
  • Added pytest pre-commit hook and eolfix, linkcheck hooks; replaced poetry_export with pyproject_export.
  • Updated CI pipeline to extend sse ref, add large-runner and 8-hour timeout for the gear test job, and add publish:docker, release:mr, and release:tag jobs.
  • Added unit tests for segAparc2009 (tests/test_separateROIs.py) and merge_hemi_volumes_txt_to_csv / pivot_volumes_txt_to_csv (tests/test_utils.py).
  • Added CLAUDE.md with codebase guidance for AI-assisted development.

Documentation:

  • Updated CONTRIBUTING.md to replace all poetry references with uv equivalents and refreshed the pre-commit hook list.
  • Rewrote the manifest.json gear description for clarity.
  • Updated README.md to remove trailing whitespace and clarify reconall_options config description.

0.2.1_7.4.1 [2024-09-27]

Fixes:

  • Fixed Dockerfile entrypoint to use absolute path /flywheel/v0/run.py instead of environment variable expansion

0.2.0_7.4.1 [2024-08-16]

Enhancements:

  • Added support for control points file input to enable manual intensity correction and re-running recon-all with updated parameters
  • Added rois_in_output configuration option to optionally output ROIs directly instead of only in zip archives
  • Added mniroizip input validation to check file format, dimensions, and NIfTI compatibility before processing
  • Added zipinfo.csv generation for all output zip files to provide detailed archive metadata
  • Enhanced MNI ROI handling to support both gear-provided and user-provided ROIs with flexible combinations via mni_rois config option

Fixes:

  • Fixed thalamic nuclei segmentation to use consistent version (v13) instead of wildcard pattern
  • Fixed hippocampal segmentation to properly handle both T1 and T2 inputs
  • Fixed aparc2009 ROI separation to handle both brainmask.mgz and brain.mgz files for compatibility with different Freesurfer versions
  • Fixed MACOSX metadata file removal from user-provided zip files
  • Fixed MNI ROI template path handling and dimension validation

Maintenance:

  • Migrated from freesurfer 7.3.2 to 7.4.1
  • Migrated from ants v2.4.2 and freesurfer 7.3.2 embedded builds to multi-stage Docker build using flywheel/rtp2_ants:0.1.0_2.4.2 and flywheel/freesurfer:0.1.0_7.4.1 pre-built images
  • Migrated from flywheel-gear-toolkit to support work directory separation from output directory
  • Updated pandas to ^2.2.2 and urllib3 to 1.26.18 for security patches
  • Reorganized Dockerfile to use multi-stage builds and optimize layer caching
  • Consolidated environment variables and reduced image size through layer optimization
  • Updated .gitlab-ci.yml to reference flywheel-io/tools/etc/qa-ci instead of sse-qa-ci
  • Reorganized template files and moved ROI-related files to templates/ directory
  • Removed merge request template in .gitlab/merge_request_templates/

Documentation:

  • Updated README with detailed descriptions of all inputs, configuration options, and outputs
  • Added clarification for control_points input requirements and usage
  • Enhanced mniroizip input documentation with validation requirements and download links
  • Updated configuration descriptions to explain re-run behavior and control point integration

0.1.2_7.3.2 [2023-02-08]

Enhancements:

  • Added FreeSurfer recon-all execution with multi-T1w and T2w support
  • Added automated segmentation of hippocampal subfields
  • Added brainstem structures segmentation
  • Added thalamic nuclei parcellation with FRAC correction algorithm
  • Added cerebellum parcellation using Buckner 2011 atlas
  • Added Glasser HCP atlas integration for cortical parcellation
  • Added MORI JHU white matter tract ROIs
  • Added Neuropythy analysis for visual cortex mapping (Benson14, Wang15 atlases)
  • Added aparc.a2009s segmentation with individual ROI extraction
  • Added ANTs registration pipeline for MNI space transformations
  • Added support for custom surface annotations (annot files) with conversion to volumetric ROIs
  • Added gtmseg execution for PETsurfer compatibility
  • Added automatic conversion of segmentation outputs to NIfTI format
  • Added CSV export for all segmentation statistics
  • Added support for pre-run FreeSurfer input via zip file

Maintenance:

  • Initial project setup with Docker environment configuration
  • Added build system with poetry for dependency management
  • Configured CI/CD pipeline with GitLab CI for testing and Docker publishing
  • Added pre-commit hooks for code quality (black, isort, pytest, markdownlint, yamllint)
  • Installed python 3.9.15 runtime environment
  • Installed FreeSurfer 7.3.2 and ANTs v2.4.2 for neuroimaging analysis
  • Added MATLAB Runtime (MCRv97) for brainstem and hippocampal subfield modules
  • Configured required dependencies: flywheel-gear-toolkit>=0.6, flywheel-sdk>=16.8.0, numpy>=1.23.4, scipy>=1.9.3, nilearn>=0.9.2, nibabel>=4.0.2, neuropythy>=0.12.5, pybids>=0.15.4

Documentation:

  • Added comprehensive README with usage instructions and examples
  • Added FAQ document for troubleshooting
  • Added CONTRIBUTING guide with development workflow
  • Added LICENSE (MIT)
  • Added merge request template with checklist