Skip to content

Release Notes

2.1.2 [2025-08-19]

Enhancements:

  • Added delete-reason configuration option to support audit-trail requirements for validated instances, with default value data_structured_incorrectly

Maintenance:

  • Migrated from poetry to uv for dependency management
  • Updated python from 3.12.10 to 3.12.11
  • Replaced deprecated ruff ignore argument with config-based approach in pre-commit hooks
  • Added eolfix pre-commit hook and reordered hook execution
  • Replaced poetry_export with pyproject_export hook
  • Migrated build system from poetry.core.masonry.api to hatchling.build
  • Updated pyproject.toml to PEP 621 format

Documentation:

  • Removed trailing whitespace from multiple documentation files

2.1.1 [2025-05-27]

Maintenance:

  • Upgraded python from 3.11.11 to 3.12.10 in Dockerfile
  • Added USER flywheel directive to Dockerfile for improved security (UID/GID 31337)

Documentation:

  • Fixed markdown formatting in CONTRIBUTING.md for poetry configuration link

2.1.0 [2025-03-19]

Enhancements:

  • Added filter to detect and exclude invalid DICOM files from input archives, enabled by default via new filter_archive configuration option
  • Changed operation order to attempt group_by split before geometric split when both are configured, preventing geometric split if group_by succeeds
  • Added automatic file type metadata update to dicom for all output files to ensure correct Flywheel classification

Fixes:

  • Fixed issue where archives with invalid DICOM files would fail to process instead of filtering out the problematic files

Maintenance:

  • Updated fw-file from ^3 to ^4.0.0, which includes pydicom update to 3.0.1
  • Refactored gear arguments to use GearArgs dataclass instead of tuple parameter expansion for improved code maintainability
  • Updated xh tool installation in Dockerfile build dependencies
  • Changed Dockerfile stage declarations from lowercase to uppercase (AS instead of as)
  • Updated test suite to use fw_file.dicom.testing utilities for improved test maintainability
  • Updated base image python version from 3.11.10 to 3.11.11

Documentation:

  • Expanded README with comprehensive sections including Overview, Configuration details, Usage workflow, and Contributing guidelines
  • Added detailed descriptions for all configuration options including new filter_archive parameter
  • Added workflow diagram using Mermaid to visualize gear operation
  • Clarified behavior changes in version 2.1.0 regarding split operation order and max_geometric_splits default value change

Breaking Changes:

  • Changed max_geometric_splits default from 4 to -1, disabling geometric split by default (users must explicitly enable)
  • Changed default tag value from "splitter" to "dicom-splitter" to match gear rename in version 2.0.0

2.0.3 [2024-11-22]

Enhancements:

  • Multiple SeriesNumber values within a split now logs a warning and continues instead of erroring and telling the user to split on SeriesNumber
  • Added logging for geometric split phase counts and detection of orientation changes
  • Improved handling of DICOM archives with non-uniform or degenerate slice geometry

Fixes:

  • Fixed error when DICOM archives contain multiple SeriesNumber values (now warns and continues processing)

Maintenance:

  • Added debug logging for geometric computation edge cases (end of list, no axis identified, non-uniform slice spacing)
  • Updated test suite to verify new logging behavior in geometry splitting

Documentation:

  • Updated README configuration options to match current implementation
  • Improved docstrings for run_individual_split(), gen_split_score(), run_split_localizer(), add_phases_to_output(), split_dicom(), run(), populate_qc(), populate_tags(), update_localizer_frames(), parse_config(), and split_by_geometry()
  • Fixed capitalization of "DICOM" throughout documentation and code comments

2.0.2 [2024-09-26]

Enhancements:

  • Built gdcm from source (version 3.0.24) instead of using pre-built image
  • Implemented multi-stage Docker build for optimized image size and build caching

Maintenance:

  • Upgraded python from 3.9 to 3.11
  • Updated scipy to ^1, pandas to ^2, pylibjpeg to ^2, pylibjpeg-libjpeg to ^2, pylibjpeg-openjpeg to ^2, and flywheel-sdk to ^18
  • Migrated CI configuration from sse-qa-ci to qa-ci project with updated reference
  • Enabled Docker build cache in CI pipeline
  • Updated .pre-commit-config.yaml hooks reference from specific SHA to main branch
  • Simplified regex split to string split in version parsing (fw_gear_dicom_splitter/metadata.py:20)
  • Updated .dockerignore to include all requirements files
  • Added test package initialization file (tests/__init__.py)
  • Fixed relative import in tests/test_splitters.py to use package-relative import
  • Updated development dependencies: pytest to ^8, pytest-cov to ^5, ipython to ^8
  • Removed obsolete development dependencies: black, isort, pylint, pycodestyle, pydocstyle, mypy, coverage, pre-commit
  • Added coverage configuration to exclude tests directory
  • Added pytest configuration for test paths and coverage reporting

2.0.1 [2024-06-26]

Fixes:

  • Fixed handling of Secondary Capture Image Storage (SOPClassUID 1.2.840.10008.5.1.4.1.1.7) files to perform split checks even when this SOPClassUID is present, as downstream workflows require single SeriesInstanceUID per file
  • Fixed geometry-based splitting to properly handle DICOM collections where one or more slices are missing ImagePositionPatient or ImageOrientationPatient metadata by returning None instead of attempting invalid split operations
  • Added warning log when geometry split cannot be performed due to missing ImagePositionPatient or ImageOrientationPatient data

Maintenance:

  • Removed check_secondary_capture_sopclassuid() function that prevented splitting of Secondary Capture Image Storage files
  • Added output_configuration.enforce_file_version_match set to true in manifest.json
  • Improved type hints in split_by_geometry() function signature to explicitly return Tuple[Optional[int], Optional[list]]

2.0.0 [2024-06-12]

Breaking Changes:

  • Renamed gear from splitter to dicom-splitter, including package name change from fw_gear_splitter to fw_gear_dicom_splitter, affecting all import statements and package references

Documentation:

  • Added breaking change notice to README explaining the gear rename and its impact on dependent software

1.7.2 [2024-04-18]

Maintenance:

  • Removed unneeded importlib-metadata dependency
  • Added gear categories to manifest
  • Replaced linting tools black and isort with ruff and ruff_format
  • Fixed comparison with None using identity check instead of equality
  • Fixed boolean comparisons to use truthiness checks
  • Removed unused variables and improved code quality
  • Added noqa comments for intentional violations
  • Fixed tuple assertion syntax in geometry tests
  • Changed api-key input from read-only to writable

1.7.1 [2024-02-22]

Maintenance:

  • Updated flywheel-gear-toolkit dependency to ^0.6.18

1.7.0 [2024-01-26]

Enhancements:

  • Added geometric splitting capability to separate DICOM archives by image orientation and slice location changes (multiphasic acquisitions)
  • Added max_geometric_splits configuration option to control maximum number of geometry-based splits (default: 4)
  • Enhanced output filename format to include group-by tag values for better identification
  • Added support for preserving SeriesInstanceUID when explicitly included in group_by configuration

Fixes:

  • Fixed handling of DICOM files with NumberOfFrames tag set to zero or missing
  • Fixed crash when PixelData attribute is missing during Jensen-Shannon splitting
  • Improved error handling for input deletion failures due to insufficient permissions
  • Corrected error messages to reference SeriesNumber instead of SeriesInstanceUID for clarity

Maintenance:

  • Updated fw-file dependency from ^2 to ^3
  • Removed unused .env file
  • Removed unused zoneinfo and tzlocal imports
  • Refactored localizer frame updates to support conditional SeriesInstanceUID preservation

Documentation:

  • Updated README to clarify multiphasic and geometry-based splitting use cases
  • Enhanced configuration section to document max_geometric_splits parameter
  • Improved output naming pattern documentation to include GroupByTags component
  • Fixed typo: "archvie" to "archive"

1.5.2 [2023-09-08]

Fixes:

  • Fixed handling of multiple SOPClassUID values in secondary capture image storage to prevent incorrect splitting of DICOM archives with mixed frame types

Maintenance:

  • Replaced deprecated get_localzone() with datetime.now().astimezone() for timezone handling
  • Updated .gitlab-ci.yml configuration with new CI variables and settings
  • Added gearcheck hook to .pre-commit-config.yaml
  • Removed .gitignore file
  • Updated manifest.json repository URLs and metadata structure
  • Refactored test case naming from test_check_no_split_sopclassuid to test_check_check_secondary_capture_sopclassuid

1.5.1 [2023-07-31]

Fixes:

  • Fixed splitting behavior for DICOM files with Secondary Capture Image Storage SOPClassUID values to prevent unnecessary splitting operations

Maintenance:

  • Added check_no_split_sopclassuid() function to validate SOPClassUID values against approved non-split cases
  • Updated log message for improved clarity when archive splitting is not performed
  • Added test coverage for SOPClassUID validation logic

1.5.0 [2023-05-22]

Enhancements:

  • Added delete_input configuration option to delete the input file after a successful DICOM split (default: true)

Fixes:

  • Fixed localizer splitting to only process MR and CT modality DICOMs, skipping other modalities (e.g., OCT)
  • Fixed handling of NaN values when splitting by unique DICOM tags
  • Fixed QC metadata state to reflect actual success/failure of splitting operation
  • Fixed return type of split_dicom() to properly indicate split failures
  • Fixed tagging logic to correctly handle deleted, retained, and non-split input files

Maintenance:

  • Updated fw-file dependency constraint from ^2.1 to ^2
  • Refactored UniqueTagMultiSplitter.decision() to use dropna=False in groupby() operation
  • Set fw_file.dicom.validation logging level to INFO to reduce log noise
  • Added logging statements when saving output files

1.4.3 [2023-02-17]

Maintenance:

  • Relaxed python version constraint from <3.11 to <4

1.4.2 [2023-02-17]

Enhancements:

  • Improved handling of invalid Code String (CS) values in DICOM files via fw-file update
  • Improved handling of invalid Decimal String (DS) and Integer String (IS) values in DICOM files via fw-file update

Maintenance:

  • Updated fw-file from ^1 to ^2.1
  • Added poetry publishing configuration to CI pipeline

1.4.1 [2022-11-30]

Enhancements:

  • Added tag-single-output configuration option to apply an additional tag to a single output file for gear-rule triggering

1.4.0 [2022-11-23]

Enhancements:

  • Output split DICOMs will have unique SeriesInstanceUID values

Fixes:

  • Updated description for tag configuration option for clarity

Maintenance:

  • Migrated from poetry to pip for dependency installation in Dockerfile
  • Updated .pre-commit-config.yaml hooks to use newer SSE QA CI configuration
  • Updated .dockerignore to reference requirements.txt instead of poetry.lock
  • Updated test coverage requirement to 80% in .gitlab-ci.yml

1.3.4 [2022-08-24]

Maintenance:

  • Updated gear suite classification from AEQC to Curation

1.3.3 [2022-08-24]

Maintenance:

  • Updated Flywheel suite classification from Conversion to AEQC

1.3.2 [2022-08-23]

Enhancements:

  • Added support for detecting and handling single DICOM files as input to prevent unnecessary processing

Fixes:

  • Fixed exit behavior when input is not a zip file to return an empty tuple instead of calling sys.exit(0), improving error handling consistency

Maintenance:

  • Added sniff_dcm utility import from fw_file.dicom.utils for DICOM file detection
  • Removed unused sys module import

1.3.1 [2022-06-30]

Maintenance:

  • Renamed config option zip_single to zip-single-dicom for consistency with dicom-fixer
  • Changed zip-single-dicom values from boolean to string enum (match or no)

1.3.0 [2022-06-29]

Enhancements:

  • Added zip_single config option to control whether single DICOM files are zipped or saved uncompressed
  • Updated metadata handling to use new flywheel-gear-toolkit 0.6 methods with improved logging and QC result tracking

Fixes:

  • Fixed QC metadata population to mark failed splits on input files when no outputs are generated

Maintenance:

  • Updated flywheel-gear-toolkit from 0.6 to 0.6
  • Updated mypy constraint from ^0.790 to ^0
  • Enabled mypy and pylint pre-commit hooks
  • Added .dockerignore file to optimize Docker build context
  • Simplified Dockerfile entrypoint from poetry run python to python
  • Replaced verbose COPY commands in Dockerfile with COPY . .
  • Added show-job: true to manifest custom metadata
  • Improved error messages for multiple SeriesNumber detection
  • Refactored tag population to use new metadata API methods
  • Enhanced type hints and fixed multiple pylint violations
  • Improved code quality with loop optimizations and unused variable removal

Documentation:

  • Updated release notes with enhancement and fix descriptions

1.2.5 [2022-05-26]

Fixes:

  • Improved euclidean distance splitter reliability by adding rounding to reduce sensitivity to very small distance changes
  • Changed euclidean splitter probability calculation to use halfnorm distribution with absolute distance from mean, improving split decision accuracy

1.2.4 [2022-05-04]

Enhancements:

  • Added error handling for failures within the JensenShannonDICOMSplitter when DICOM pixel data cannot be processed

Fixes:

  • Fixed Dockerfile to optimize layer caching by installing dependencies before copying source files

Maintenance:

  • Added SplitterError exception class for better error handling in splitters
  • Added test coverage for splitter error handling scenarios
  • Added pragma: no cover directive to version fallback exception handler

1.2.3 [2022-02-14]

Maintenance:

  • Suppressed warnings for RuntimeError exceptions already handled in beta distribution fitting
  • Updated python version constraint to >=3.8,<3.11
  • Updated scipy from ^1.6.0 to ^1.8.0
  • Added SAFETY_EXTRA="--ignore 44715" to environment configuration

1.2.2 [2021-12-22]

Fixes:

  • Fixed duplicate tag handling to prevent adding the same tag multiple times

Maintenance:

  • Moved flywheel-sdk from dev dependencies to production dependencies
  • Added environment variables to manifest including PATH, PYTHON_VERSION, POETRY_VERSION, and GDCM_VERSION
  • Removed @report_usage_stats() decorator from main function

1.2.1 [2021-12-06]

Documentation:

  • Added comprehensive usage documentation to README.md explaining main use cases for splitting DICOM archives
  • Documented output naming pattern series-<SeriesNumber>_<Modality>_<SeriesDescription>[_localizer]
  • Added description of localizer extraction and series splitting behavior
  • Configured pyproject.toml to publish README.md to PyPI

1.2.0 [2021-12-06]

Enhancements:

  • Added usage statistics reporting via report_usage_stats decorator

Fixes:

  • Added helpful error message and graceful exit when input is not a zip file
  • Improved group-by logic to be simpler and more robust

Maintenance:

  • Migrated from in-repo GDCM compilation to flywheel/python-gdcm base image
  • Upgraded python from 3.8 base with compiled GDCM to shared base image
  • Updated flywheel-gear-toolkit from ^0.2 to ^0.5
  • Updated fw-file from ^0.6 to ^1
  • Added flywheel-sdk ^16.0.0 as dev dependency
  • Migrated from poetry.yml CI template to gears.yml from flywheel-io/tools/etc/qa-ci
  • Migrated pre-commit hooks to centralized flywheel-io/tools/etc/qa-ci hooks
  • Updated import from fw_file.file to fw_file.base for File class
  • Updated import from fw_meta.fields to fw_meta.imports for file name validation
  • Added .env file with test coverage and pre-commit configuration
  • Updated .gitignore to include coverage.xml and junit.xml
  • Removed add_gdcm.sh installation script
  • Removed test-specific Dockerfile and shell script
  • Removed pytest, isort, and black configuration from pyproject.toml

Documentation:

  • Updated CONTRIBUTING.md with improved formatting and clarity
  • Updated README.md with improved line wrapping

1.1.2 [2021-07-13]

Enhancements:

  • Added new tag configuration option to specify the tag applied to input files upon gear completion (default: splitter)

Documentation:

  • Updated gear description to clarify functionality: extracts embedded localizer DICOM frames and re-groups DICOM frames by specified tags
  • Updated source and url fields in manifest to point to specific gear repository

1.1.1 [2021-06-03]

Fixes:

  • Fixed input file tagging logic to only mark for deletion when outputs are created

Maintenance:

  • Updated .gitlab-ci.yml reference from master to main
  • Changed gear suite classification from AEQC to Conversion

1.1.0 [2021-05-26]

Fixes:

  • Fixed output naming when splitting with group_by AND localizer
  • Fixed setting "deleted" tag on input after split
  • Caught AttributeError for PixelData on Jensen-Shannon splitter and moved on
  • Updated fw-file with version that handles deid dates of 0001-01-01

1.0.0 [2021-05-23]

Enhancements:

  • Added QC information to output files via populate_qc() function
  • Updated output filenames for split-by operations to follow consistent pattern: {SeriesNumber}_{Modality}_{SeriesDescription}_{count}
  • Improved SeriesNumber naming to use existing values and validate against multiple values in each unique collection
  • Enhanced localizer output naming and SeriesNumber generation (increments original by 1000)
  • Added tag config option to apply custom tags to output files

Fixes:

  • Fixed file extension handling to work with extensions other than .dicom.zip
  • Prevented localizer extraction from collections with less than 2 frames
  • Added error handling for Jensen-Shannon fit solver failures on dark images
  • Fixed variable name typo in run.py (tags instead of dicom_tags)

Maintenance:

  • Updated flywheel-gear-toolkit from ^0.1 to ^0.2
  • Updated fw-file from ^0.3 to ^0.6
  • Refactored gen_suffix() to gen_name() for improved naming generation
  • Updated gen_series_uid() to use set() instead of bulk_set() and return UID
  • Enhanced update_modified_attributes_sequence() to track both SeriesInstanceUID and SeriesNumber
  • Added update_series_number() and update_localizer_frames() helper functions
  • Improved pre-commit configuration to prevent commits to both master and main branches
  • Updated Dockerfile to copy manifest.json in single layer

0.2.4 [2021-04-16]

Fixes:

  • Fixed filename generation to sanitize invalid characters using fw_meta.fields.validate_filename()

0.2.3 [2021-04-05]

Fixes:

  • Fixed bug in collection_to_df() where file.get("key") was using a string literal instead of the key variable, preventing proper metadata extraction from DICOM files

0.2.2 [2021-04-05]

Fixes:

  • Fixed handling of single-slice DICOM archives to avoid unnecessary split attempts
  • Added informative logging when archives contain only one slice or cannot be split

0.2.1 [2021-03-26]

Fixes:

  • Fixed bug in collection_to_df() where file metadata was incorrectly accessed using hardcoded string "key" instead of the variable key

Maintenance:

  • Standardized string quotes from single to double quotes in logging statement

0.2.0 [2021-03-12]

Fixes:

  • Fixed behavior when DICOM files cannot be split: gear now returns an empty tuple instead of attempting to write output, preventing unnecessary file operations
  • Added informative logging when no split outputs are generated, clarifying that the DICOM was not split and no files will be uploaded

0.1.2 [2021-03-12]

Maintenance:

  • Updated pre-commit hooks to remove -poetry suffix from hook IDs
  • Migrated flywheel-gear-toolkit dependency from git branch to versioned release ^0.1
  • Migrated fw-file dependency from git revision to versioned release ^0.3
  • Added fw-gear-testing ^0.1 as development dependency

0.1.1 [2021-02-26]

Enhancements:

  • Changed default value for group_by configuration from empty string to SeriesInstanceUID

Documentation:

  • Updated README title from "Example Gear" to "DICOM Splitter"
  • Removed json_template input from documentation (no longer used)
  • Updated configuration documentation to reflect current options: extract_localizer and group_by instead of split_on_series_uid and force_dicom_read

Maintenance:

  • Applied code formatting to fw_gear_splitter/__init__.py

0.1.0 [2021-02-26]

Enhancements:

  • Added DICOM splitter functionality to separate localizer frames from main imaging data
  • Added multi-algorithm voting system for localizer detection using image orientation, position, and pixel intensity analysis
  • Added ability to split DICOM archives by unique tag combinations (e.g., SeriesInstanceUID, Rows, Columns)
  • Added automatic metadata tracking via ContributingEquipmentSequence and OriginalAttributesSequence
  • Added support for GDCM library integration to handle additional DICOM transfer syntaxes
  • Added extract_localizer configuration option to enable/disable localizer extraction
  • Added group_by configuration option to split archives by custom DICOM tags

Maintenance:

  • Initial project setup with poetry for dependency management
  • Added CI/CD pipeline configuration with .gitlab-ci.yml
  • Added pre-commit hooks for code quality (isort, black, pylint, pytest)
  • Added development dependencies: pytest, pytest-cov, pytest-mock, black, isort, pylint
  • Added runtime dependencies: flywheel-gear-toolkit, fw-file, scipy, pandas, pydicom, pylibjpeg
  • Built Docker image based on python:3.8 with GDCM compilation from source

Documentation:

  • Added README with gear description and configuration options
  • Added CONTRIBUTING guide with setup instructions and dependency management workflow
  • Added MIT license