NIfTI → PNG / DICOM converter for task-fMRI statistical maps — PACS-ready
A desktop GUI application for converting task-fMRI NIfTI statistical maps (FSL Z-score overlays) into publication-quality PNG screenshots and fully compliant DICOM series, ready for archiving in clinical or research PACS (Agfa, Fuji, Horos, OsiriX, etc.).
Task-fMRI produces statistical maps (Z-score, t-stat, cluster masks) stored as NIfTI files — a format invisible to clinical PACS and picture archiving systems. Communicating fMRI results to clinical teams, embedding them in patient records, or archiving them alongside structural MRI requires converting those maps into a standard imaging format.
This tool bridges that gap:
NIfTI anatomical (T1/MNI152) ┐
├──▶ PNG screenshots (mosaic + individual slices)
NIfTI statistical map (Z-map) ─┘
└──▶ DICOM series (RGB, PACS-compatible)
Typical use cases:
- Presurgical fMRI reporting — embed activation maps in the PACS study of a patient undergoing neurosurgical planning (language, motor, memory paradigms)
- Clinical communication — share task-fMRI results with radiologists or neurosurgeons who work in PACS, not NIfTI viewers
- Research archiving — store group-level or individual activation maps as DICOM series alongside the original MRI data
- Figures and presentations — generate high-DPI anatomically labeled slice mosaics for papers, posters, or case reports
- Dark radiology workstation UI built with
customtkinter - Loads any NIfTI anatomical base (T1, MNI152) + FSL Z-map overlay (
.nii,.nii.gz) - Generates a global mosaic (3 × N grid: Sagittal / Coronal / Axial) as a single PNG
- Generates individual slice PNG files per view at configurable mm spacing
- Anatomical orientation labels (R/L/A/P/S/I) derived from the affine matrix — see orientation disclaimer
- Configurable Z-threshold, overlay alpha, colormap (hot, plasma, inferno, RdBu_r…), DPI, and file prefix
- Optional DICOM export (requires
pydicom+Pillow):- Full RGB color preserved — colormaps render correctly in any PACS viewer
- Optional subject reference DICOM for automatic tag inheritance (PatientName, PatientID, StudyInstanceUID, InstitutionName, etc.) — avoids manual tag entry per subject
- Unified
SeriesInstanceUIDper view — prevents series fragmentation in strict PACS viewers such as Agfa - Shared
FrameOfReferenceUIDand spatial tags (ImagePositionPatient,SliceLocation) for correct slice ordering - Falls back to generic tags when no reference DICOM is provided
| File | Description |
|---|---|
Any .nii / .nii.gz anatomical |
T1w, T2w, MNI152 standard space template, FLAIR, etc. |
FSL zstat*.nii.gz |
Z-statistic map from FEAT first- or higher-level analysis |
FSL tstat*.nii.gz |
T-statistic map |
FSL thresh_zstat*.nii.gz |
Thresholded Z-map (cluster or voxel-wise) |
SPM spmT_*.nii |
T-map from SPM contrast |
| Any continuous NIfTI overlay | Custom masks, beta maps, percent signal change maps, etc. |
The overlay is thresholded at runtime using the Z-threshold parameter — no pre-thresholding required.
Converters that generate one DICOM per PNG typically assign a new SeriesInstanceUID to each file. Lenient viewers (Horos, OsiriX) group by folder; strict PACS (Agfa, Fuji) apply the UID literally and display each image as a separate series. This tool generates all UIDs once per session and assigns them consistently across all slices of the same view, resulting in exactly 3 clean series per run (Sagittal / Coronal / Axial).
Anatomical orientation labels (R/L/A/P/S/I) are derived directly from the NIfTI affine matrix of the input image and rendered explicitly on every slice. This is intentional.
Neuroimaging software and clinical PACS viewers differ in their default lateral display convention:
- Radiological convention (standard in PACS/clinical): patient's left appears on the viewer's right
- Neurological convention (common in FSL, SPM, NiBabel): patient's left appears on the viewer's left
Because the DICOM files generated by this tool may be opened in either context, the corner labels are the ground truth. Do not infer lateralization from the screen position of an activation cluster — always read the R/L labels rendered on the image. This is especially relevant when reporting lateralized functions (language dominance, motor cortex) across radiological and neurological workflows.
Python >= 3.9
nibabel
numpy
matplotlib
customtkinter
# For DICOM export (optional):
pydicom
Pillow
Install all at once:
pip install nibabel numpy matplotlib customtkinter pydicom Pillowpython fmri_screenshot_generator.py- 01 Input files — select the anatomical NIfTI (T1 / MNI152) and the FSL Z-map (
zstat1.nii.gzor equivalent) - 02 Output folder — select or create the destination folder
- 03 Export parameters — set Z-threshold, slice spacing (mm), overlay alpha, DPI, and colormap
- 04 DICOM export (optional) — enable the checkbox, then optionally select any
.dcmfile from the same subject to inherit identity tags automatically - Click ▶ GENERATE SCREENSHOTS
| File | Description |
|---|---|
<prefix>_global.png |
Full 3-view mosaic (Sagittal / Coronal / Axial) |
<prefix>_sagittal_<N>mm.png |
Individual sagittal slices |
<prefix>_coronal_<N>mm.png |
Individual coronal slices |
<prefix>_axial_<N>mm.png |
Individual axial slices |
<prefix>_sagittal_<N>mm.dcm |
DICOM RGB — Sagittal series (if enabled) |
<prefix>_coronal_<N>mm.dcm |
DICOM RGB — Coronal series (if enabled) |
<prefix>_axial_<N>mm.dcm |
DICOM RGB — Axial series (if enabled) |
<prefix>_log_<timestamp>.txt |
Run parameters log |
| Tag | Value |
|---|---|
| SOPClassUID | 1.2.840.10008.5.1.4.1.1.7 (Secondary Capture Image Storage) |
| PhotometricInterpretation | RGB |
| SamplesPerPixel | 3 |
| PlanarConfiguration | 0 (interleaved RGBRGB…) |
| Modality | OT |
| BitsAllocated / BitsStored | 8 / 8 |
| SeriesInstanceUID | One per view (Sagittal / Coronal / Axial) |
| FrameOfReferenceUID | Shared across all series of the session |
| ImagePositionPatient | Derived from NIfTI voxel index × voxel size (mm) |
| SliceLocation | Slice coordinate in mm along the respective axis |
Note on Agfa / strict PACS windowing: if colors appear desaturated after import, add
ds.PresentationLUTShape = 'IDENTITY'inpng_to_dicom().
| Author | Role |
|---|---|
| Pablo Reyes — github.com/pabloreyesg | Concept, design, domain expertise, neuroimaging pipeline integration |
| Claude (Anthropic) | AI-assisted code development and iteration |
This tool was developed through iterative human–AI collaboration. The scientific rationale, clinical use case, and architectural decisions were driven by Pablo Reyes; the code was written collaboratively with Claude (claude.ai).
Copyright (C) 2025 Pablo Reyes
This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License v3 as published by the Free Software Foundation.
See LICENSE for the full text, or visit https://www.gnu.org/licenses/gpl-3.0.html.
Built on top of:
- NiBabel — NIfTI I/O and affine handling
- pydicom — DICOM read/write
- matplotlib — slice rendering and colormap application
- customtkinter — modern Tkinter UI
- Pillow — PNG → RGB array conversion for DICOM pixel data