Skip to content

Release Notes

0.5.0 [2026-07-16]

Enhancements:

  • Added support for converting 4D NIfTI input (previously 3D-only), across three input combinations:
    • NIfTI + reference DICOM: volumes are matched back to the reference DICOM series either by a pixel-verified sort-key hypothesis (classic one-instance-per-slice series) or, for Siemens MOSAIC-format references, by de-mosaicing and matching tiles within each instance. Per-instance tags (e.g. AcquisitionTime, DiffusionBValue/DiffusionGradientOrientation, TemporalPositionIdentifier) are inherited from the matched reference instance for each output volume/slice.
    • NIfTI + JSON sidecar only (no reference DICOM): per-volume tags are synthesized directly from the BIDS JSON sidecar (plus auto-discovered .bval/.bvec files for diffusion, parsed via a new nibabel runtime dependency), for time-series (fMRI/perfusion), PET, and diffusion (DWI) acquisitions. New nifti_4d_dimension config option (auto/time/diffusion/pet) controls how the 4th dimension is interpreted when it can't be auto-detected.
    • NIfTI only (no reference DICOM and no JSON sidecar): explicitly rejected with a clear error rather than guessing or silently producing incomplete output.
  • Global pixel-value rescaling and reference-DICOM instance-count validation across all volumes of a 4D series.
  • ASL/perfusion sidecars are rejected outright for sidecar-only 4D conversion (not yet supported); multi-echo NIfTIs log a warning that each echo converts to its own separate DICOM series.
  • Added match_series_instance_uid config option: reuse a reference DICOM's own SeriesInstanceUID instead of generating a new one, or (default) generate a deterministic one from subject/session/acquisition labels and the NIfTI filename instead of a fully random one each run. Forced on when overwrite_source_dicom is enabled.

Fixes:

  • Fixed several sidecar/reference-DICOM tag values being written despite being invalid for their DICOM tag's VR, where a BIDS/sidecar field name coincidentally matches a DICOM keyword with a different meaning or value format (e.g. BIDS PartialFourier's fraction vs. DICOM's CS-VR boolean flag of the same name; a de-mosaiced ImageType still containing MOSAIC; PET frame-timing fields needing a seconds-to-milliseconds conversion). All sidecar/reference-derived tag values are now validated against their DICOM VR before being written, and skipped with a warning on a mismatch.

Documentation:

  • Updated README.md's Limitations section to reflect 4D support, including the reference-DICOM round-trip requirement and JSON-sidecar 4th-dimension requirements.
  • Updated manifest.json's description to reflect 4D support.

0.4.0 [2026-06-02]

Enhancements:

  • Added optional dicom input for providing a template DICOM to populate output DICOM tags, replacing the previous pixelmed-based sidecar-only conversion.
  • Added force_16_bit config option to force output pixel data to 16-bit.
  • Added copy_metadata_from_dicom config option to copy Flywheel file metadata (modality, classification, info, tags) from a template DICOM to the output DICOM.
  • Added find_dicom_in_container config option to automatically search the parent acquisition container for a template DICOM at runtime.
  • Added overwrite_source_dicom config option to name the output DICOM to match the input template DICOM filename.
  • Added allow_no_sidecar config option to allow conversion to continue without a DICOM or JSON sidecar, using NIfTI header orientation as a fallback.
  • Added tag config option to apply a tag to the output DICOM file upon completion.
  • Added support for OPT and PET modalities in the sidecar conversion method, in addition to the existing MR and CT support.
  • Added support for project-level JSON sidecar (nifti_to_dicom_config.json) as a fallback when no acquisition-level sidecar is found.
  • Added MediaStorageSOPClassUID to output DICOM metadata population.
  • Replaced pixelmed Java-based conversion backend with SimpleITK-based (simpleitk) Python conversion in fw_gear_nifti_to_dicom/convert.py.

Fixes:

  • Fixed SOPClassUID values for MR (1.2.840.10008.5.1.4.1.1.4) and CT (1.2.840.10008.5.1.4.1.1.2) to use correct non-enhanced DICOM standard UIDs.
  • Fixed PatientName, PatientID, and StudyID fields to respect DICOM VR character limits (PN 64 chars, LO 64 chars, SH 16 chars).
  • Fixed gear to use NIfTI file modality as fallback when sidecar lacks Modality, before defaulting to "MR".

Maintenance:

  • Migrated from flywheel-gear-toolkit and fw-core-client to fw-gear library.
  • Migrated from poetry to uv for dependency management.
  • Upgraded base Docker image from flywheel/python:master.9746b723 to flywheel/python:3.12-wolfi-build with multi-stage Dockerfile.
  • Upgraded python requirement from ^3.9 to >=3.12,<4.
  • Updated dependencies: replaced flywheel-gear-toolkit, backoff, fw-core-client, fw-file ^1.0.3 with fw-gear>=0.3.7, fw-file>=4.2.3, flywheel-sdk>=21.6.1, numpy>=2.4.4, simpleitk>=2.5.3.
  • Removed pixelmed Java library and all associated Java runtime dependencies.
  • Migrated build system from poetry.core.masonry.api to hatchling.
  • Updated CI configuration to use PYVER: "3.12" and new qa-ci spec.
  • Updated pre-commit hooks from legacy flywheel-lint/isort/black stack to ruff_format, ruff, pytest, and other qa-ci hooks.
  • Updated manifest.json gear classification schema and environment variables to reflect new Docker image and uv-based environment.
  • Rewrote test suite to use flywheel SDK mocks, replacing fw-http-testserver fixtures; added integration-style test_convert.py with real NIfTI and DICOM test assets.

Documentation:

  • Expanded README.md with full gear overview, inputs, config options, outputs, prerequisites, usage workflow, limitations, and a Mermaid workflow diagram.
  • Updated CONTRIBUTING.md to reflect uv-based dependency management and new pre-commit hook list.