Formats API Reference

Module imagedata.formats.abstractplugin

Abstract class for image formats.

Defines generic functions.

class imagedata.formats.abstractplugin.AbstractPlugin(name, description, authors, version, url)

Abstract base class definition for imagedata format plugins. Plugins must be a subclass of AbstractPlugin and must define the atttributes set in __init__() and the following methods:

read() method write_3d_numpy() method write_4d_numpy() method

Variables:

• input_order –

• tags –

• transformationMatrix –

property authors

Plugin authors

Multi-line string naming the author(s) of the plugin.

property description

Plugin description

Single line string describing the image format.

getPositionForVoxel(r, transformation=None)

Get patient position for center of given voxel r

Use Patient Position and Image Orientation to calculate world coordinates for given voxel

Parameters:

• r – (z,y,x) of voxel in voxel coordinates as numpy.array

• transformation – transformation matrix when different from self.transformationMatrix

Returns:

(z,y,x) of voxel in world coordinates (mm) as numpy.array

getTimeline()

Get timeline

Returns:

Timeline in seconds, as numpy array of floats

Delta time is given as seconds. First image is t=0. Length of array is number of tags.

Raises:

ValueError – tags for dataset is not time tags

getVoxelForPosition(p, transformation=None)

Get voxel for given patient position p

Use Patient Position and Image Orientation to calculate world coordinates for given voxel

Parameters:

• p – (z,y,x) of voxel in world coordinates (mm) as numpy.array

• transformation – transformation matrix when different from self.transformationMatrix

Returns:

(z,y,x) of voxel in voxel coordinates as numpy.array

property name

Plugin name

Single word string describing the image format. Typical names: dicom, nifti, itk.

read(sources, pre_hdr, input_order, opts)

Read image data

Generic version for images which will be sorted on their filenames.

Parameters:

• sources – list of sources to image data

• pre_hdr – DICOM template

• input_order – sort order

• opts – Input options (dict)

Returns:

Tuple of

• hdr: Header dict

• si[tag,slice,rows,columns]: numpy array

static replace_geometry_attributes(im, gim)

Replace geometry attributes in image with values from gim

property url

Plugin URL

URL string to the site of the plugin or the author(s).

property version

Plugin version

String giving the plugin version. Version scheme: 1.0.0

abstract write_3d_numpy(si, destination, opts)

Write 3D Series image

Parameters:

• self – format plugin instance

• si[slice – Series array

• rows – Series array

• columns] – Series array

• destination – dict of archive and filenames

• opts – Output options (dict)

abstract write_4d_numpy(si, destination, opts)

Write 4D Series image

Parameters:

• self – format plugin instance

• si[tag – Series array

• slice – Series array

• rows – Series array

• columns] – Series array

• destination – dict of archive and filenames

• opts – Output options (dict)

exception imagedata.formats.abstractplugin.NoOtherInstance

Module imagedata.formats.dicomplugin

Read/Write DICOM files

class imagedata.formats.dicomplugin.DICOMPlugin

Read/write DICOM files.

Variables:

• input_order –

• DicomHeaderDict (#) –

• instanceNumber –

• today –

• now –

• serInsUid –

• input_options –

• output_sort –

• output_dir –

• seriesTime –

create_affine(hdr)

Function to generate the affine matrix for a dicom series This method was based on (http://nipy.org/nibabel/dicom/dicom_orientation.html) :param hdr: list with sorted dicom files

extractDicomAttributes(dictionary, hdr)

Extract DICOM attributes

Parameters:

• self – DICOMPlugin instance

• dictionary – image dictionary

• hdr – header

Returns:

header

• seriesNumber

• seriesDescription

• imageType

• spacing

• orientation

• imagePositions

• axes

• modality, laterality, protocolName, bodyPartExamined

• seriesDate, seriesTime, patientPosition

Return type:

hdr

getDicomAttribute(dictionary, tag, slice=0)

Get DICOM attribute from first image for given slice.

Parameters:

• self – DICOMPlugin instance

• dictionary – image dictionary

• tag – DICOM tag of requested attribute.

• slice – which slice to access. Default: slice=0

getOriginForSlice(dictionary, slice)

Get origin of given slice.

Parameters:

• self – DICOMPlugin instance

• dictionary – image dictionary

• slice – slice number (int)

Returns:

coordinate for origin of given slice (np.array)

Return type:

z,y,x

get_dicom_files(sources, input_order, opts=None, skip_pixels=False)

Get DICOM objects.

Parameters:

• self – DICOMPlugin instance

• sources – list of sources to image data

• input_order – Determine how to sort the input images

• opts – options (dict)

• skip_pixels – Do not read pixel data (default: False)

Returns:

Tuple of

• sorted_headers: dict where sliceLocations are keys

• hdr: Header

• shape: tuple

read(sources, pre_hdr, input_order, opts)

Read image data

Parameters:

• self – DICOMPlugin instance

• sources – list of sources to image data

• pre_hdr – Pre-filled header dict. Can be None

• input_order – sort order

• opts – input options (dict)

Returns:

Tuple of

• hdr: Header

  • input_format

  • input_order

  • slices

  • sliceLocations

  • dicomTemplate

  • keep_uid

  • tags

  • seriesNumber

  • seriesDescription

  • imageType

  • spacing

  • orientation

  • imagePositions

• si[tag,slice,rows,columns]: multi-dimensional numpy array

read_files(sources, input_order, opts, skip_pixels=False)

Read DICOM objects

Parameters:

• self – DICOMPlugin instance

• sources – list of sources to image data

• input_order – sort order

• opts – input options (dict)

• skip_pixels – Do not read pixel data (default: False)

Returns:

Tuple of

• hdr: header

• si: numpy pixel matrix

removePrivateTags(dictionary)

Remove private DICOM attributes.

Ignore if no real dicom header exists.

Parameters:

• self – DICOMPlugin instance

• dictionary – image dictionary

setDicomAttribute(dictionary, tag, value)

Set a given DICOM attribute to the provided value.

Ignore if no real dicom header exists.

Parameters:

• self – DICOMPlugin instance

• dictionary – image dictionary

• tag – DICOM tag of addressed attribute.

• value – Set attribute to this value.

sort_images(header_dict, input_order, opts)

Sort DICOM images.

Parameters:

• self – DICOMPlugin instance

• header_dict – dict where sliceLocations are keys

• input_order – determine how to sort the input images

• opts – options (dict)

Returns:

Tuple of

• hdr

  • input_format

  • input_order

  • slices

  • sliceLocations

  • dicomTemplate

  • SOPInstanceUIDs

  • tags

• shape

write_3d_numpy(si, destination, opts)

Write 3D Series image as DICOM files

Parameters:

• self – DICOMPlugin instance

• si – Series array (3D or 4D)

• destination – dict of archive and filenames

• opts – Output options (dict)

write_4d_numpy(si, destination, opts)

Write 4D Series image as DICOM files

si.series_number is inserted into each dicom object

si.series_description is inserted into each dicom object

si.image_type: Dicom image type attribute

opts[‘output_sort’]: Which tag will sort the output images (slice or tag)

opts[‘output_dir’]: Store all images in a single or multiple directories

Parameters:

• self – DICOMPlugin instance

• si – Series array si[tag,slice,rows,columns]

• destination – dict of archive and filenames

• opts – Output options (dict)

write_enhanced(si, archive, filename_template, opts)

Write enhanced CT/MR object to DICOM file

Parameters:

• self – DICOMPlugin instance

• si – Series instance, including these attributes:

• archive – archive object

• filename_template – file name template, possible without ‘.dcm’ extension

• opts – Output options (dict)

Raises:

write_slice(input_order, tag, si, destination, ifile, sop_ins_uid=None)

Write single slice to DICOM file

Parameters:

• self – DICOMPlugin instance

• input_order – input order

• tag – tag index

• si – Series instance, including these attributes:

• slices (-) –

• sliceLocations (-) –

• dicomTemplate (-) –

• dicomToDo (-) –

• tags (-) –

• seriesNumber (-) –

• seriesDescription (-) –

• imageType (-) –

• frame (-) –

• spacing (-) –

• orientation (-) –

• imagePositions (-) –

• photometricInterpretation (-) –

• destination – destination object

• ifile – instance number in series

exception imagedata.formats.dicomplugin.FilesGivenForMultipleURLs

exception imagedata.formats.dicomplugin.NoDICOMAttributes

exception imagedata.formats.dicomplugin.UnevenSlicesError

exception imagedata.formats.dicomplugin.UnknownTag

exception imagedata.formats.dicomplugin.ValueErrorWrapperPrecisionError

Module imagedata.formats.itkplugin

Read/Write image files using ITK

exception imagedata.formats.itkplugin.DependencyError

Thrown when a required module could not be loaded.

class imagedata.formats.itkplugin.ITKPlugin(name=None, description=None, authors=None, version=None, url=None)

Read/write ITK files.

get_image_from_numpy(image)

Returns an itk Image created from the supplied scipy ndarray.

If the image_type is supported, will be automatically transformed to that type, otherwise the most suitable is selected.

Note: always use this instead of directly the itk.PyBuffer, as that

object transposes the image axes.

Parameters:

• array (image an) –

• np.ndarray (type image) –

Returns:

an instance of itk.Image holding the array’s data, type itk.Image (instance)

write_3d_numpy(si, destination, opts)

Write 3D numpy image as ITK file

Parameters:

• self – ITKPlugin instance

• si – Series array (3D or 4D), including these attributes:

• slices (-) –

• spacing (-) –

• imagePositions (-) –

• transformationMatrix (-) –

• orientation (-) –

• tags (-) –

• destination – dict of archive and filenames

• opts – Output options (dict)

write_4d_numpy(si, destination, opts)

Write 4D numpy image as ITK files

Parameters:

• self – ITKPlugin instance

• si – [tag,slice,rows,columns]: Series array, including these attributes:

• slices (-) –

• spacing (-) –

• imagePositions (-) –

• transformationMatrix (-) –

• orientation (-) –

• tags (-) –

• destination – dict of archive and filenames

• opts – Output options (dict)

write_numpy_itk(si, archive, filename)

Write single volume to file

Parameters:

• self – ITKPlugin instance, including these attributes: - slices (not used) - spacing - imagePositions - transformationMatrix - orientation (not used) - tags (not used)

• si – numpy 3D array [slice,row,column]

• archive – archive object

• filename – file name

exception imagedata.formats.itkplugin.ImageTypeError

Thrown when trying to load or save an image of unknown type.

Module imagedata.formats.matplugin

Read/Write Matlab-compatible MAT files

exception imagedata.formats.matplugin.DependencyError

Thrown when a required module could not be loaded.

exception imagedata.formats.matplugin.ImageTypeError

Thrown when trying to load or save an image of unknown type.

class imagedata.formats.matplugin.MatPlugin

Read/write MAT files.

write_3d_numpy(si, destination, opts)

Write 3D numpy image as MAT file

Parameters:

• self – MATPlugin instance

• si – Series array (3D or 4D), including these attributes: slices, spacing, tags

• destination – dict of archive and filenames

• opts – Output options (dict)

write_4d_numpy(si, destination, opts)

Write 4D numpy image as MAT files

Parameters:

• self – MATPlugin instance

• si[tag – Series array, including these attributes: slices, spacing, tags

• slice – Series array, including these attributes: slices, spacing, tags

• rows – Series array, including these attributes: slices, spacing, tags

• columns] – Series array, including these attributes: slices, spacing, tags

• destination – dict of archive and filenames

• opts – Output options (dict)

exception imagedata.formats.matplugin.MatrixDimensionNotImplemented

Matrix dimension is not implemented.

exception imagedata.formats.matplugin.MultipleVariablesInMatlabFile

Reading multiple variables from a MAT file is not implemented.

Module imagedata.formats.niftiplugin

Read/Write Nifti-1 files

class imagedata.formats.niftiplugin.NiftiPlugin

Read/write Nifti-1 files.

extensions = ['.nii', '.nii.gz']

data - getter and setter - NumPy array read() method write() method

write_3d_numpy(si, destination, opts)

Write 3D numpy image as Nifti file

Parameters:

• self – NiftiPlugin instance

• si – Series array (3D or 4D), including these attributes: slices, spacing, imagePositions, transformationMatrix, orientation, tags

• destination – dict of archive and filenames

• opts – Output options (dict)

write_4d_numpy(si, destination, opts)

Write 4D numpy image as Nifti file

si[tag,slice,rows,columns]: Series array, including these attributes:

slices, spacing, imagePositions, transformationMatrix, orientation, tags

Parameters:

• si (imagedata.Series) – Series array

• destination – dict of archive and filenames

• opts – Output options (dict)

write_numpy_nifti(si, destination, opts)

Write nifti data to file

Parameters:

• si (imagedata.Series) – Series array

• destination – dict of archive and filenames

• opts – Output options (dict)