Package: imagedata
Imagedata is a python library to read and write medical image data into numpy arrays.
Imagedata will handle multi-dimensional data.
In particular, imagedata will read and sort DICOM 3D and 4D series based on
defined tags.
Imagedata will handle geometry information between the formats.The following formats are included:DICOMNiftiITK (MetaIO)MatlabPostScript (input only)Other formats can be added through a plugin architecture.Installpip install imagedataDocumentationSee theDocumentationpage for info.Example codeA simple example reading two time series from dirA and dirB, and writing their mean to dirMean:fromimagedataimportSeriesa=Series('dirA','time')b=Series('dirB','time')asserta.shape==b.shape,"Shape of a and b differ"# Notice how a and b are treated as numpy arraysc=(a+b)/2c.write('dirMean')SortingSorting of DICOM slices is considered a major task. Imagedata will sort slices into volumes based on slice location.
Volumes may be sorted on a number of DICOM tags:‘time’: Dynamic time series, sorted on acquisition time‘b’: Diffusion weighted series, sorted on diffusion b value‘fa’: Flip angle series, sorted on flip angle‘te’: Sort on echo time TEIn addition, volumes can be sorted on user defined tags.Non-DICOM formats usually don’t specify the labelling of the 4D data.
In this case, you can specify the sorting manually.ViewingA simple viewer. Scroll through the image stack, step through the tags of a 4D dataset.
These operations are possible:Read-out voxel value: Move mouse over.Window/level adjustment: Move mouse with left key pressed.Scroll through slices of an image stack: Mouse scroll wheel, or up/down array keys.Step through tags (time, b-values, etc.): Left/right array keys.Move through series when many series are displayed: PageUp/PageDown keys.# View a Series instancea.show()# View both a and b Seriesa.show(b)# View several Seriesa.show([b,c,d])Converting data from DICOM and backIn many situations you need to process patient data using a tool that do not accept DICOM data.
In order to maintain the coupling to patient data, you may convert your data to e.g. Nifti and back.Example using the command line utility image_data:image_data--ofniftiniftiDirdicomDir# Now do your processing on Nifti data in niftiDir/, leaving the result in niftiResult/.# Convert the niftiResult back to DICOM, using dicomDir as a templateimage_data--ofdicom--templatedicomDirdicomResultniftiResult# The resulting dicomResult will be a new DICOM series that could be added to a PACS# Set series number and series description before transmitting to PACS using DICOM transportimage_data--sernum1004--serdes'Processed data'\dicom://server:104/AETITLEdicomResultThe same example using python code:fromimagedataimportSeriesa=Series('dicomDir')a.write('niftiDir',formats=['nifti'])# Explicitly select nifti as output format# Now do your processing on Nifti data in niftiDir/, leaving the result in niftiResult/.b=Series('niftiResult',template=a)# Or template='dicomDir'b.write('dicomResult')# Here, DICOM is default output format# Set series number and series description before transmitting to PACS using DICOM transportb.seriesNumber=1004b.seriesDescription='Processed data'b.write(' dicom://server:104/AETITLE')Series fieldsThe Series object is inherited from numpy.ndarray, adding a number of useful fields:Axesa.axes defines the unit and size of each dimension of the matrixAddressing4D: a[tags, slices, rows, columns]3D: a[slices, rows, columns]2D: a[rows, columns]RGB: a[…, rgb]patientID, patientName, patientBirthDateIdentifies patientaccessionNumberIdentifies studyseriesNumber, seriesDescription, imageTypeLabels DICOM dataslicesReturns number of slicesspacingReturns spacing for each dimension. Units depend on dimension, and could e.g. be mm or sec.tagsReturns tags for each slicetimelineReturns time steps for when a time seriestransformationMatrixThe transformation matrix to calculate physical coordinates from pixel coordinatesSeries instancingFrom image data file(s):a=Series('in_dir')From a list of directories:a=Series(['1','2','3'])From a numpy array:e=np.eye(128)a=Series(e)Series methodswrite()Write the image data as a Matlab file to out_dir:a.write('out_dir',formats=['mat'])slicingThe image data array can be sliced like numpy.ndarray. The axes will be adjusted accordingly.
This will give a 3Dbimage whenais 4D.b=a[0,...]ArchivesThe Series object can access image data in a number ofarchives. Some archives are:FilesystemAccess files in directories on the local file system.a=Series('in_dir')ZipAccess files inside zip files.# Read all files inside file.zip:a=Series('file.zip')# Read named directory inside file.zip:b=Series('file.zip?dir_a')# Write the image data to DICOM files inside newfile.zip:b.write('newfile.zip',formats=['dicom'])TransportsfileAccess local files (default):a=Series('file:in_dir')dicomAccess files using DICOM Storage protocols. Currently, writing (implies sending) DICOM images only:a.write('dicom://server:104/AETITLE')Command line usageThe command line programimage_datacan be used to convert between various image data formats:image_data--ordertimeout_dirin_dirs