src.imagedata.formats package

Subpackages

• src.imagedata.formats.dicomlib package
  • Submodules
  • src.imagedata.formats.dicomlib.uid module
    • get_hostid()
    • get_uid()
    • get_uid_for_storage_class()
    • uid_append_instance()
  • Module contents

Submodules

src.imagedata.formats.abstractplugin module

Abstract class for image formats.

Defines generic functions.

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

Bases: object

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.

plugin_type = 'format'

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 src.imagedata.formats.abstractplugin.NoOtherInstance

Bases: Exception

src.imagedata.formats.dicomplugin module

Read/Write DICOM files

class src.imagedata.formats.dicomplugin.DICOMPlugin

Bases: AbstractPlugin

Read/write DICOM files.

Variables:

• input_order

• DicomHeaderDict (#)

• instanceNumber

• today

• now

• serInsUid

• input_options

• output_sort

• output_dir

• seriesTime

authors = 'Erling Andersen'

auto_sort(header_dict, opts)

construct_basic_dicom(template=None, filename='NA', sop_ins_uid=None)

construct_dicom(filename, template, si, sop_ins_uid=None)

construct_pixel_array(image_dict, hdr, shape, opts=None)

correct_acqtimes_for_dynamic_series(hdr, si)

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

description = 'Read and write DICOM files.'

extensions = ['.dcm', '.ima']

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

keep_uid = False

name = 'dicom'

process_member(image_dict, archive, member_name, member, opts, skip_pixels=False)

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

root = '2.16.578.1.37.1.1.4'

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.

simulateAffine()

smallint = ('bool8', 'byte', 'ubyte', 'ushort', 'uint16', 'int8', 'uint8', 'int16')

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

url = 'www.helse-bergen.no'

version = '1.3.0'

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 src.imagedata.formats.dicomplugin.FilesGivenForMultipleURLs

Bases: Exception

exception src.imagedata.formats.dicomplugin.NoDICOMAttributes

Bases: Exception

exception src.imagedata.formats.dicomplugin.UnevenSlicesError

Bases: Exception

exception src.imagedata.formats.dicomplugin.UnknownTag

Bases: Exception

exception src.imagedata.formats.dicomplugin.ValueErrorWrapperPrecisionError

Bases: Exception

src.imagedata.formats.itkplugin module

Read/Write image files using ITK

exception src.imagedata.formats.itkplugin.DependencyError

Bases: Exception

Thrown when a required module could not be loaded.

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

Bases: AbstractPlugin

Read/write ITK files.

authors = 'Erling Andersen'

description = 'Read and write ITK files.'

extensions = ['.mhd', '.mha', '.jpg', '.jpeg', '.tiff']

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)

name = 'itk'

set_direction_from_dicom_header(image)

set_direction_from_transformation_matrix(image)

url = 'www.helse-bergen.no'

version = '2.0.0'

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 src.imagedata.formats.itkplugin.ImageTypeError

Bases: Exception

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

src.imagedata.formats.matplugin module

Read/Write Matlab-compatible MAT files

exception src.imagedata.formats.matplugin.DependencyError

Bases: Exception

Thrown when a required module could not be loaded.

exception src.imagedata.formats.matplugin.ImageTypeError

Bases: Exception

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

class src.imagedata.formats.matplugin.MatPlugin

Bases: AbstractPlugin

Read/write MAT files.

authors = 'Erling Andersen'

description = 'Read and write MAT files.'

extensions = ['.mat']

name = 'mat'

url = 'www.helse-bergen.no'

version = '1.0.0'

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 src.imagedata.formats.matplugin.MatrixDimensionNotImplemented

Bases: Exception

Matrix dimension is not implemented.

exception src.imagedata.formats.matplugin.MultipleVariablesInMatlabFile

Bases: Exception

Reading multiple variables from a MAT file is not implemented.

src.imagedata.formats.niftiplugin module

Read/Write Nifti-1 files

class src.imagedata.formats.niftiplugin.NiftiPlugin

Bases: AbstractPlugin

Read/write Nifti-1 files.

authors = 'Erling Andersen'

description = 'Read and write Nifti-1 files.'

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

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

name = 'nifti'

url = 'www.helse-bergen.no'

version = '2.0.0'

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)

Module contents

This module provides plugins for various imaging formats.

Standard plugins provides support for DICOM and Nifti image file formats.

exception src.imagedata.formats.CannotSort

Bases: Exception

exception src.imagedata.formats.EmptyImageError

Bases: Exception

exception src.imagedata.formats.FormatPluginNotFound

Bases: Exception

exception src.imagedata.formats.NotImageError

Bases: Exception

exception src.imagedata.formats.NotTimeOrder

Bases: Exception

exception src.imagedata.formats.SOPInstanceUIDNotFound

Bases: Exception

exception src.imagedata.formats.UnknownInputError

Bases: Exception

exception src.imagedata.formats.UnknownTag

Bases: Exception

exception src.imagedata.formats.WriteNotImplemented

Bases: Exception

src.imagedata.formats.find_plugin(ftype)

Return plugin for given format type.

src.imagedata.formats.get_plugins_list()

src.imagedata.formats.get_size(obj, seen=None)

Recursively finds size of objects

src.imagedata.formats.input_order_to_dirname_str(input_order)

src.imagedata.formats.input_order_to_str(input_order)

src.imagedata.formats.shape_to_str(shape)

Convert numpy image shape to printable string

Parameters:

shape

Returns:

printable shape (str)

Raises:

ValueError – when shape cannot be converted to printable string

src.imagedata.formats.sort_on_to_str(sort_on)

src.imagedata.formats.str_to_dtype(s)

src.imagedata.formats.str_to_input_order(s)

src.imagedata.formats.str_to_sort_on(s)