Formats API Reference — imagedata 1.3.0 documentation

# 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`(hdr)

    Extract DICOM attributes

    Parameters

      - self – DICOMPlugin instance

      - hdr – header dict

    Returns

      header dict

        - seriesNumber

        - seriesDescription

        - imageType

        - spacing

        - orientation

        - imagePositions

        - axes

    Return type

      hdr

  `getDicomAttribute`(tag, slice=0)

    Get DICOM attribute from first image for given slice.

    Parameters

      - tag – DICOM tag of requested attribute.

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

  `getOriginForSlice`(slice)

    Get origin of given slice.

    Parameters

      - self – DICOMPlugin instance

      - slice – slice number (int)

    Returns

      coordinate for origin of given slice (np.array)

    Return type

      z,y,x

  `get_dicom_headers`(sources, input_order, opts=None, skip_pixels=True)

    Get DICOM headers.

    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: True)

    Returns

      Tuple of

        - hdr: dict

        - 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 dict

            - input_format

            - input_order

            - slices

            - sliceLocations

            - DicomHeaderDict

            - tags

            - seriesNumber

            - seriesDescription

            - imageType

            - spacing

            - orientation

            - imagePositions

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

  `read_headers`(sources, input_order, opts, skip_pixels=True)

    Read DICOM headers only

    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: True)

    Returns

      Tuple of

        - hdr: header dict

        - shape: required shape of image data

  `removePrivateTags`()

    Remove private DICOM attributes.

    Ignore if no real dicom header exists.

  `setDicomAttribute`(tag, value)

    Set a given DICOM attribute to the provided value.

    Ignore if no real dicom header exists.

    Parameters

      - 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 dict

            - input_format

            - input_order

            - slices

            - sliceLocations

            - DicomHeaderDict

            - 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)

    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

    Raises:

  `write_slice`(tag, slice, si, archive, filename, ifile)

    Write single slice to DICOM file

    Parameters

      - self – DICOMPlugin instance

      - tag – tag index

      - slice – slice index

      - si – Series instance, including these attributes:

      - slices (-) –

      - sliceLocations (-) –

      - DicomHeaderDict (-) –

      - tags (-) –

      - seriesNumber (-) –

      - seriesDescription (-) –

      - imageType (-) –

      - frame (-) –

      - spacing (-) –

      - orientation (-) –

      - imagePositions (-) –

      - photometricInterpretation (-) –

      - archive – archive object

      - filename – file name, possible without ‘.dcm’ extension

      - 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

      - an array (image) –

      - image np.ndarray (type) –

    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 – Series array, including these attributes:

      - slice – Series array, including these attributes:

      - rows – Series array, including these attributes:

      - 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, possibly without extentsion

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 (-) –

    :param : :param - spacing: :param : :param - tags: :param destination: dict of archive and filenames :param 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:

      - slice – Series array, including these attributes:

      - rows – Series array, including these attributes:

      - columns] – Series array, including these attributes:

      - slices (-) –

    :param : :param - spacing: :param : :param - tags: :param destination: dict of archive and filenames :param 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

exception `imagedata.formats.niftiplugin.` `FilesGivenForMultipleURLs`

class `imagedata.formats.niftiplugin.` `NiftiPlugin`

  Read/write Nifti-1 files.

  `create_affine_xyz`()

    Create affine in xyz.

  `url` = 'www.helse-bergen.no'

    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 (-) –

    :param : :param - spacing: :param : :param - imagePositions: :param : :param - transformationMatrix: :param : :param - orientation: :param : :param - tags: :param destination: dict of archive and filenames :param opts: Output options (dict)

  `write_4d_numpy`(si, destination, opts)

    Write 4D numpy image as Nifti file

    Parameters

      - self – NiftiPlugin instance

      - si[tag – Series array, including these attributes:

      - slice – Series array, including these attributes:

      - rows – Series array, including these attributes:

      - columns] – Series array, including these attributes:

      - slices (-) –

    :param : :param - spacing: :param : :param - imagePositions: :param : :param - transformationMatrix: :param : :param - orientation: :param : :param - tags: :param destination: dict of archive and filenames :param opts: Output options (dict)

  static `write_numpy_nifti`(img, archive, filename)

    Write nifti data to file

    Parameters

      - self – ITKPlugin instance, including these attributes:

      - slices (-) –

      - spacing (-) –

      - imagePositions (-) –

      - transformationMatrix (-) –

      - orientation (-) –

      - tags (-) –

      - img – Nifti1Image

      - archive – archive object

      - filename – file name, possibly without extentsion

exception `imagedata.formats.niftiplugin.` `NoInputFile`

## Module imagedata.formats.psplugin

Read/Write PostScript files

exception `imagedata.formats.psplugin.` `DependencyError`

  Thrown when a required module could not be loaded.

exception `imagedata.formats.psplugin.` `ImageTypeError`

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

class `imagedata.formats.psplugin.` `PSPlugin`

  Read PostScript files. Writing PostScript files is not implemented.

  `write_3d_numpy`(si, destination, opts)

    Write 3D numpy image as PostScript file

    Parameters

      - self – ITKPlugin instance

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

      - slices (-) –

    :param : :param - spacing: :param : :param - imagePositions: :param : :param - transformationMatrix: :param : :param - orientation: :param : :param - tags: :param destination: dict of archive and filenames :param opts: Output options (dict)

    Raises

      imagedata.formats.WriteNotImplemented – Always, writing is not implemented.

  `write_4d_numpy`(si, destination, opts)

    Write 4D numpy image as PostScript files

    Parameters

      - self – ITKPlugin instance

      - si[tag – Series array, including these attributes:

      - slice – Series array, including these attributes:

      - rows – Series array, including these attributes:

      - columns] – Series array, including these attributes:

      - slices (-) –

    :param : :param - spacing: :param : :param - imagePositions: :param : :param - transformationMatrix: :param : :param - orientation: :param : :param - tags: :param destination: dict of archive and filenames :param opts: Output options (dict)

    Raises

      imagedata.formats.WriteNotImplemented – Always, writing is not implemented.