Skip to content

Release Notes

2.1.9_1.0.20250506 [2025-08-13]

Fixes:

  • Added explicit error handling for archive file type input with informative error message directing users to correct the file type before re-running

Maintenance:

  • Updated fw-gear-file-metadata-importer to >=1.5.9
  • Removed explicit dependency on flywheel-gear-toolkit (now handled by fw-gear-file-metadata-importer)
  • Removed explicit dependencies on numpy, pydicom, matplotlib, and jinja2 (now handled transitively)

2.1.8_1.0.20250506 [2025-08-12]

Enhancements:

  • Added filetype validation to fail earlier when invalid filetype is provided as gear input

Maintenance:

  • Enabled PyPI publishing in CI configuration by setting PUBLISH_POETRY to true

2.1.7_1.0.20250506 [2025-07-15]

Fixes:

  • Resolved HIGH and CRITICAL security vulnerabilities in container image dependencies

Maintenance:

  • Updated upstream dcm2niix from 1.0.20240202 to 1.0.20250506
  • Pinned jq to 1.8.0-r0 and git to 2.50.1-r0 for security patches
  • Migrated from poetry to uv for dependency management
  • Updated pyproject.toml to use PEP 621 format with hatchling build backend
  • Moved git from build-time to runtime dependencies for improved layer caching
  • Updated pre-commit hook from poetry_export to pyproject_export

2.1.6_1.0.20240202 [2025-06-13]

Maintenance:

  • Added eolfix hook to .pre-commit-config.yaml to ensure consistent line endings across the codebase
  • Removed trailing whitespace from documentation and configuration files
  • Fixed inconsistent line endings in Dockerfile, README.md, CONTRIBUTING.md, and shell scripts

2.1.5_1.0.20240202 [2025-06-09]

Fixes:

  • Improved support for PAR/REC files by adding proper DICOM file detection
  • Fixed file.info object handling for non-DICOM NIfTI files to prevent empty metadata headers
  • Improved DICOM metadata extraction to only process valid DICOM files

Maintenance:

  • Migrated base image to flywheel/python:3.12-alpine
  • Upgraded python runtime from 3.11 to 3.12
  • Updated pytest from ^6.1.2 to ^8
  • Updated ipython from ^7.22.0 to ^8.10.0
  • Updated jinja2 to ^3.1.5 to resolve security vulnerabilities
  • Restructured Dockerfile to use multi-stage builds with base, build, dev, and production stages
  • Migrated from apt to apk package manager for Alpine Linux
  • Updated CI configuration to increase coverage requirement to 80% and enable classification validation
  • Updated .pre-commit-config.yaml hooks reference from commit hash to sse branch
  • Updated .gitlab-ci.yml reference from commit hash to sse branch
  • Added show-job, uid, and gid fields to manifest configuration
  • Removed tests/Dockerfile in favor of unified build process

Documentation:

  • Clarified metadata extraction behavior in README for BIDS sidecar and file.info population
  • Updated description of DICOM metadata extraction to specify it applies to input DICOM headers
  • Fixed markdown link formatting in CONTRIBUTING.md

2.1.4_1.0.20240202 [2024-09-26]

Fixes:

  • Fixed metadata upload issue where gear attempted to upload nonexistent JSON sidecar files when bids_sidecar config option was set to n
  • Added warning log when both bids_sidecar and save_sidecar_as_metadata are set to n, alerting users that no BIDS sidecar information will be saved

Maintenance:

  • Updated CI/CD configuration to migrate from sse-qa-ci to qa-ci project
  • Disabled PYTEST_COV_FAIL_UNDER requirement (set to 0) in CI variables
  • Disabled PyPI package publishing in CI by default
  • Enhanced test coverage to verify metadata object is not returned for JSON sidecar files when bids_sidecar is n
  • Added test coverage to verify warning is logged when both bids_sidecar and save_sidecar_as_metadata are n
  • Updated pre-commit hooks configuration: added hadolint, jsonlint, linkcheck, and markdownlint hooks
  • Simplified ruff pre-commit arguments by removing inline E501 ignore

2.1.3_1.0.20240202 [2024-09-17]

Maintenance:

  • Updated fw-gear-file-metadata-importer from ^1.4.0 to ^1.5.2 to limit PerFrameFunctionalGroupsSequence metadata to first frame
  • Upgraded python version requirement from ^3.9 to ^3.10
  • Added matplotlib at version 3.9.0
  • Removed nibabel and fw-file explicit dependencies (now handled transitively)

2.1.2_1.0.20240202 [2024-08-06]

Fixes:

  • Fixed classification preservation when using the tag configuration option. Previously, providing a tag would cause any existing .metadata.json file to be lost. The tag is now added to .metadata.json alongside existing data.
  • Fixed metadata attachment for NIfTI files when using save_sidecar_as_metadata. Data from sidecar is now correctly attached as metadata instead of DICOM tags (which had different units since BIDS uses seconds while DICOM uses milliseconds).

Maintenance:

  • Pinned numpy to <2.0 to maintain compatibility
  • Refactored metadata generation to return dictionary instead of creating file directly
  • Removed unused pprint import from metadata module
  • Improved metadata handling by updating container metadata through gear context instead of file-based approach

2.1.1_1.0.20240202 [2024-06-28]

Fixes:

  • Fixed metadata structure to only include sidecar info in the info field, removing duplicate DICOM data when sidecar is present

2.1.0_1.0.20240202 [2024-04-30]

Enhancements:

  • Added save_sidecar_as_metadata config option to maintain backwards compatibility with previous BIDS workflow
  • Automatically detect BIDS workflow version from project.info when save_sidecar_as_metadata is not explicitly set
  • Improved logging for bids_sidecar config option handling

Fixes:

  • Fixed bids_sidecar config options n and o to work as expected by ensuring sidecar is always generated during conversion, then handling user preference during resolve stage

Maintenance:

  • Updated fw-file from 1.3.3 to 3.0.1
  • Updated fw-gear-file-metadata-importer from 1.2.5 to 1.4.0
  • Upgraded dcm2niix from 1.0.20230411 to 1.0.20240202
  • Updated python from 3.8 to 3.11
  • Replaced deprecated distutils.util with inline boolean conversion
  • Migrated linting from black and isort to ruff and ruff_format
  • Updated test suite to remove unused variables and improve assertion patterns
  • Improved code formatting and type hints throughout codebase
  • Refactored generate_gear_args into separate stage-specific functions: generate_prep_args, generate_dcm2niix_args, and generate_resolve_args

2.0.3_1.0.20230411 [2023-09-22]

Enhancements:

  • Changed default value of bids_sidecar configuration option from n to y

Fixes:

  • Fixed handling of bids_sidecar option when set to n to properly exclude JSON sidecar files from output

Documentation:

  • Updated bids_sidecar configuration description to reflect new default value of y (yes)

2.0.2_1.0.20230411 [2023-06-29]

Enhancements:

  • Added automatic tagging of input file with dcm2niix-failure tag when gear execution fails (controlled by tag_on_failure config option)
  • Added automatic removal of dcm2niix-failure tag from input file when gear completes successfully after previous failure

Fixes:

  • Fixed argument duplication in interface method call by correcting parent class reference in _format_arg method

Documentation:

  • Added documentation for tag and tag_on_failure config options explaining tagging behavior

2.0.1_1.0.20230411 [2023-05-18]

Enhancements:

  • Added tag_on_failure configuration option to automatically tag input files with dcm2niix-failure when conversion fails

Maintenance:

  • Updated dcm2niix from v1.0.20220720 to v1.0.20230411

2.0.0_1.0.20220720 [2023-04-10]

Enhancements:

  • Added support for .mvec file output when applicable, matching .bval and .bvec handling

Fixes:

  • Fixed metadata storage location to file.info.header.dicom for better organization

Maintenance:

  • Migrated from poetry to pip with requirements.txt for dependency management
  • Updated Docker base image from neurodebian to flywheel/python
  • Updated nipype from 1.5.0 to 1.8.4
  • Pinned flywheel-gear-toolkit to 0.6.10
  • Pinned fw-file to 1.3.3 and fw-gear-file-metadata-importer to 1.2.5
  • Added version pinning for system packages in Docker
  • Improved test coverage with additional unit tests

Documentation:

  • Updated README with reformatted gear documentation
  • Added FAQ and changelog files
  • Updated CONTRIBUTING guide with development workflow
  • Added merge request template

Breaking Changes:

  • Removed PyDeface functionality (now available as separate gear)
  • Removed PyDeface configuration options (pydeface, pydeface_cost, pydeface_nocleanup, pydeface_verbose)
  • Removed PyDeface input options (pydeface_template, pydeface_facemask)
  • Changed metadata storage location from duplicate sidecar to file.info.header.dicom
  • Sidecar information no longer duplicated in metadata; set bids_sidecar to y to maintain BIDS information

1.4.4_1.0.20220720 [2023-04-17]

Enhancements:

  • Added support for .mvec (motion vector) files in dcm2niix output by extending Dcm2niixOutputSpec with mvecs output field

Fixes:

  • Fixed dcm2niix interface to properly include .mvec files in conversion output alongside .bval and .bvec files

Maintenance:

  • Refactored Dcm2niixEnhanced._parse_stdout() method into _parse_files() and _list_outputs() methods for improved file type handling
  • Updated file type handling logic to recognize and process .mvec files throughout the codebase in fw_gear_dcm2niix/dcm2niix/interfaces.py:72-111
  • Updated docstrings in metadata.py and resolve.py to document .mvec file support

1.4.2_1.0.20220720 [2023-01-23]

Enhancements:

  • Updated dcm2niix from version 1.0.20211006 to 1.0.20220720
  • Added support for %dicom% filename template option to use input DICOM filename as output filename

Fixes:

  • Fixed handling of empty strings in DICOM SeriesDescription field
  • Fixed conditional logic in convert_directory() for compression_level validation
  • Fixed handling of bids_sidecar configuration for both n and o options
  • Fixed unused import and variable assignments throughout codebase
  • Corrected subprocess context managers to properly handle process cleanup

Maintenance:

  • Migrated CI configuration to use flywheel-io/scientific-solutions/etc/sse-qa-ci templates
  • Updated pre-commit hooks configuration with additional linters (hadolint, markdownlint, yamllint, jsonlint, pylint, pydocstyle, mypy, shellcheck, linkcheck)
  • Added .markdownlint.yaml configuration file
  • Updated base Docker image from neurodebian:bionic to neurodebian@sha256:d3d3a46841d5247a03f3368db37ad21c84f9d6ba8d1cce2716559970aa3 c1de3 (Focal)
  • Improved Dockerfile with hadolint compliance, including proper layer caching, --no-install-recommends flags, and cleanup commands
  • Added SHELL directive and LABEL instruction following best practices
  • Enhanced code quality with pylint compliance improvements across all modules
  • Improved logging with f-string to % formatting conversion for better performance
  • Refactored error handling and conditional logic for better readability
  • Added docstrings to __init__.py files for all sub-modules
  • Updated poetry dependencies in pyproject.toml

Documentation:

  • Reformatted README with improved line wrapping and readability
  • Updated CONTRIBUTING with proper shell code block syntax
  • Enhanced release notes formatting and organization
  • Updated code comments with proper grammar and formatting
  • Added clarifications for complex logic in inline comments

1.4.1_1.0.20211006 [2022-04-28]

Enhancements:

  • Added sanitize_filename configuration option to sanitize output filenames when using infile name
  • Added debug configuration option to enable debug logging mode

Fixes:

  • Fixed metadata extraction to be compatible with file-metadata-importer by using fw-gear-file-metadata-importer for DICOM header processing

Maintenance:

  • Enabled PyPI publishing in CI configuration
  • Updated flywheel-gear-toolkit from ^0.1.3 to ^0.5.0
  • Updated nibabel from ~3.1.0 to ~3.2.0
  • Updated pydicom from ~2.0.0 to ^2.1.0
  • Updated black from ^20.8b1 to ^22.1.0
  • Updated mypy from ^0.790 to ^0.910
  • Added fw-gear-file-metadata-importer dependency at ^1.2.1
  • Updated pre-commit hooks to pinned versions instead of master branch
  • Added yamllint disable directives for line length rules in CI configuration files
  • Changed system package from bsdtar to libarchive-tools in Dockerfile
  • Added -DUSE_GIT_PROTOCOL=OFF flag to cmake configuration for dcm2niix build
  • Protected main branch in addition to master in pre-commit hooks

Documentation:

  • Reformatted indentation in metadata list in README.md
  • Removed extra blank lines and trailing whitespace in multiple files
  • Fixed markdown formatting in tests/assets/README.md

1.4.0_1.0.20211006 [2022-02-22]

Enhancements:

  • Changed default filename template from %f to %f_%p_%t_%s to align with dcm2niix tool defaults
  • Changed default lossless scaling from n (no, but uint16->int16) to o (original) to align with dcm2niix tool defaults

Fixes:

  • Fixed issue where files were not correctly saved when rescaling was happening due to incorrect filepath extraction from dcm2niix stdout
  • Fixed parsing of dcm2niix output to handle malformed lines containing scale/slope in warning messages

Maintenance:

  • Optimized Dockerfile layer ordering to improve build time by moving frequently-changing code layers to the bottom

1.3.4_1.0.20211006 [2022-02-15]

Fixes:

  • Fixed merge2d option to use integer type instead of string, resolving argument handling issues
  • Corrected merge2d parameter processing to use proper NiPype interface instead of raw command-line arguments

Maintenance:

  • Extended NiPype Dcm2niixInputSpec to support merge_imgs parameter with proper trait definition
  • Updated merge2d configuration schema to use number type with enum values 0, 1, 2 instead of string values
  • Reformatted release notes structure for improved readability
  • Removed unused commented code from convert_directory() function

Documentation:

  • Clarified merge2d parameter description to use numeric options (0=no, 1=yes, 2=auto) instead of string values

1.3.3_1.0.20211006 [2022-01-25]

Enhancements:

  • Series Description is now optional for DICOM processing
  • merge2d option default now set to auto (merge2d="2")
  • JSON sidecar now included by default (bids_sidecar='y')

Fixes:

  • Escaped metacharacters in filename to prevent gear breakage when fields used for output name contain special characters ([]*)
  • Adjusted check for sidecar to output image matching and switched metadata generation to use naming fix

Maintenance:

  • Upgraded dcm2niix from 1.0.20201102 to 1.0.20211006
  • Upgraded python from 3.6 to 3.9.0
  • Added CI/CD pipeline configuration with GitLab CI
  • Added pre-commit hooks configuration for code quality checks
  • Light refactoring of wrapper code and package structure
  • Renamed package directory from dcm2niix_gear to fw_gear_dcm2niix

1.3.0_1.0.20201102 [2021-04-09]

Enhancements:

  • Added support for nested DICOM archives with multiple subdirectories, flattening hierarchical structures for processing
  • Added tally_files() function to profile directory contents and map file paths
  • Added flatten_directory() function to convert nested directory structures to flat layouts

Fixes:

  • Fixed handling of archives with multiple subdirectories by flattening contents before processing
  • Added collision detection to prevent overwriting files with identical names from different subdirectory levels

Maintenance:

  • Refactored archive extraction logic to handle multiple subdirectory levels (>=1 instead of ==1)
  • Enhanced test coverage with parametrized tests for nested DICOM archives
  • Added test assets for nested directory structures (one level, two levels, uneven nesting)
  • Added collision detection test cases for nested archives

Documentation:

  • Added CONTRIBUTING.md with Docker-based development environment setup instructions
  • Enhanced test docstrings with detailed descriptions of test purposes and parameters

1.2.2_1.0.20201102 [2021-02-05]

Maintenance:

  • Reorganized project structure into dcm2niix_gear package
  • Added setup.py for package distribution with fw-gear-dcm2niix name
  • Updated imports across all modules to reference new dcm2niix_gear package structure
  • Replaced deprecated nibabel get_data() method with get_fdata() in test files

1.2.1_1.0.20201102 [2021-01-15]

Fixes:

  • Fixed command execution by converting Path objects to strings in pydeface_run.py before passing to command-line arguments
  • Fixed handling of output.outputs.bids to properly support both string and list types in run.py
  • Fixed metadata generation to correctly pass output_sidecar_files to resolve.setup() instead of incorrect work_dir parameter in run.py
  • Fixed metadata capture to correctly handle .bvals and .bvecs outputs by adding them to output_image_files list in run.py
  • Fixed submit_instance_runs.py to properly quote find_one() argument
  • Added JSON serialization handler for bytes objects with UTF-8 and Latin-1 fallback decoding in metadata.py

Maintenance:

  • Refactored metadata.py by splitting generate() function into separate capture() and create_file() functions for improved modularity
  • Refactored metadata file association logic to use Path(sidecar).stem matching instead of regex-based string substitution in metadata.py and resolve.py
  • Refactored retain_gear_outputs() to iterate over sidecars first, then match files by stem name in resolve.py
  • Changed default value of retain_sidecar parameter from True to False in metadata.generate() and resolve.setup() functions
  • Updated test files to reference development version 1.2.1_1.0.20201102_dev1 and 1.2.1_1.0.20201102_dev2 in assess_instance_runs.py, submit_instance_runs.py, and build_gear.sh
  • Removed unused re import from metadata.py
  • Improved code organization by moving try-except block for nipype output handling in run.py
  • Replaced glob.glob() with os.listdir() for better clarity in resolve.setup() when moving files to output directory
  • Changed variable name from f to more descriptive names in parse_config.py for improved code clarity

1.2.0_1.0.20201102 [2020-12-10]

Enhancements:

  • Added support for case-insensitive PAR/REC file extensions (image.par and image.rec)
  • Added workflow diagram to documentation (gear_workflow.svg)
  • Renamed configuration option compress_nifti to compress_images for clarity
  • Updated documentation with improved formatting and structure throughout README

Fixes:

  • Fixed error handling when dcm2niix produces no outputs
  • Fixed filename parsing issues for files with path separators and non-ASCII characters
  • Fixed validation logic for mutually exclusive retain_nifti and output_nrrd parameters
  • Fixed NRRD file pattern matching in metadata generation to include .nrrd extension

Documentation:

  • Expanded README with detailed configuration descriptions and usage tips
  • Added notes about .nrrd output requiring compress_images set to 'n'
  • Clarified bids_sidecar metadata handling behavior
  • Added implementation notes for comment, filename, and ignore_errors options
  • Updated manifest descriptions for clearer input file specifications
  • Added tip about using %f filename template for downstream BIDS curation

1.1.0_1.0.20201102 [2020-11-13]

Enhancements:

  • Added comment configuration option to store comments (up to 24 characters) in NIfTI aux_file and JSON sidecars
  • Added dcm2niix_verbose configuration option to include verbose output from dcm2niix call
  • Added output_nrrd configuration option to export as NRRD format instead of NIfTI
  • Added internal compression option 'i' to compress_nifti configuration
  • Expanded filename template options to include %b (basename), %o (mediaObjectInstanceUID), %r (instance number), and %q (sequence name tag(0018,1020))
  • Changed lossless_scaling from boolean to string with options 'y' (scale), 'n' (no, but uint16->int16), 'o' (original) for finer control
  • Changed bids_sidecar default from 'y' to 'n'
  • Added comprehensive metadata documentation listing all DICOM tags extracted by dcm2niix and pydicom

Maintenance:

  • Updated dcm2niix from v1.0.20200331 to v1.0.20201102

Documentation:

  • Updated filename configuration description with complete list of template variables and their meanings
  • Updated compress_nifti configuration description to include 'i' (internal) option
  • Updated lossless_scaling configuration description to reflect string-based options
  • Updated merge2d configuration description to clarify it merges regardless of echo, exposure, etc.
  • Added metadata section documenting DICOM tags extracted via dcm2niix and pydicom
  • Updated convert_only_series example formatting to use inline code formatting

1.0.0_1.0.20200331 [2020-10-07]

Enhancements:

  • Added CircleCI configuration for automated build and test workflows
  • Added GitHub release drafter workflow for automated release note generation
  • Added support for DICOM decompression via gdcmconv before conversion with decompress_dicoms config option
  • Added support for removing incomplete trailing volumes with remove_incomplete_volumes config option
  • Added support for coil combined data extraction with coil_combine config option
  • Added support for PAR/REC file pairs as direct inputs without archive packaging
  • Added ignore_errors config option to preserve outputs when dcm2niix exits with errors
  • Added PyDeface integration for facial structure removal from NIfTI files
  • Added optional PyDeface template and facemask inputs for customized defacing
  • Added comprehensive metadata extraction from DICOM headers including acquisition parameters
  • Added BIDS sidecar generation with anonymization support via anonymize_bids config option
  • Added automatic retention of associated files (.bval, .bvec) when present

Maintenance:

  • Added dcm2niix version v1.0.20200331
  • Added python3, pip3, and scientific computing dependencies (nibabel, pydicom, pydeface)
  • Added FSL 5.0 for PyDeface support
  • Added gdcmconv for DICOM decompression capabilities
  • Added nipype for dcm2niix interface
  • Added flywheel-gear-toolkit for gear framework

Documentation:

  • Added comprehensive README with gear description, input specifications, and configuration options
  • Added test suite with pytest for validation of arrange, PyDeface, and utility functions