SimpleITK Image Basics

This document will give a brief orientation to the SimpleITK Image class.

First we import the SimpleITK Python module. By convention our module is imported into the shorter and more Pythonic "sitk" local name.

%matplotlib inline
import matplotlib.pyplot as plt
import SimpleITK as sitk

Image Construction

There are a variety of ways to create an image. All images' initial value is well defined as zero.

image = sitk.Image(256, 128, 64, sitk.sitkInt16)
image_2D = sitk.Image(64, 64, sitk.sitkFloat32)
image_2D = sitk.Image([32, 32], sitk.sitkUInt32)
image_RGB = sitk.Image([128, 128], sitk.sitkVectorUInt8, 3)

Pixel Types

The pixel type is represented as an enumerated type. The following is a table of the enumerated list.

sitkUInt8	Unsigned 8 bit integer
sitkInt8	Signed 8 bit integer
sitkUInt16	Unsigned 16 bit integer
sitkInt16	Signed 16 bit integer
sitkUInt32	Unsigned 32 bit integer
sitkInt32	Signed 32 bit integer
sitkUInt64	Unsigned 64 bit integer
sitkInt64	Signed 64 bit integer
sitkFloat32	32 bit float
sitkFloat64	64 bit float
sitkComplexFloat32	complex number of 32 bit float
sitkComplexFloat64	complex number of 64 bit float
sitkVectorUInt8	Multi-component of unsigned 8 bit integer
sitkVectorInt8	Multi-component of signed 8 bit integer
sitkVectorUInt16	Multi-component of unsigned 16 bit integer
sitkVectorInt16	Multi-component of signed 16 bit integer
sitkVectorUInt32	Multi-component of unsigned 32 bit integer
sitkVectorInt32	Multi-component of signed 32 bit integer
sitkVectorUInt64	Multi-component of unsigned 64 bit integer
sitkVectorInt64	Multi-component of signed 64 bit integer
sitkVectorFloat32	Multi-component of 32 bit float
sitkVectorFloat64	Multi-component of 64 bit float
sitkLabelUInt8	RLE label of unsigned 8 bit integers
sitkLabelUInt16	RLE label of unsigned 16 bit integers
sitkLabelUInt32	RLE label of unsigned 32 bit integers
sitkLabelUInt64	RLE label of unsigned 64 bit integers

There is also sitkUnknown, which is used for undefined or erroneous pixel ID's. It has a value of -1.

The 64-bit integer types are not available on all distributions. When not available the value is sitkUnknown.

More Information about the Image class be obtained in the Docstring

SimpleITK classes and functions have the Docstrings derived from the C++ definitions and the Doxygen documentation.

help(image)

Help on Image in module SimpleITK.SimpleITK object:

class Image(builtins.object)
 |  Image(*args)
 |  
 |  The Image class for SimpleITK.
 |  
 |  
 |  This Image class can represent 2D, 3D, and 4D images. The pixel types may be a
 |  scalar, a multi-component vector or a run-length-encoded (RLE)
 |  "label". The dimension, pixel type and size is specified at
 |  construction.
 |  
 |  A fundamental concept of ITK images is that they occupy physical space
 |  where the image is defined by an origin, spacing, and direction cosine
 |  matrix. The attributes are taken into consideration when doing most
 |  operations on an image. A meta-data dictionary is also associated with
 |  the image, which may contain additional fields from reading but these
 |  attributes are not propagated by image filters.
 |  
 |  The SimpleITK Image provides a single facade interface to several ITK image types.
 |  Internally, the SimpleITK Image maintains a pointer to the ITK image class, and performs reference
 |  counting and lazy copying. This means that deep copying of an image
 |  including it's buffer is delayed until the image is modified. This
 |  removes the need to use pointers to SimpleITK Image class, as copying and returning by value do not unnecessarily
 |  duplicate the data.
 |  
 |  
 |  See:
 |   itk::Image itk::VectorImage itk::LabelMap itk::ImageBase
 |  
 |  
 |  C++ includes: sitkImage.h
 |  
 |  Methods defined here:
 |  
 |  CopyInformation(self, srcImage)
 |      CopyInformation(Image self, Image srcImage)
 |      
 |      
 |      Copy common meta-data from an image to this one.
 |      
 |      
 |      Copies the Origin, Spacing, and Direction from the source image to
 |      this image. The meta-data dictionary is not copied.
 |      
 |      It is required for the source Image's dimension and size to match, this image's attributes, otherwise an
 |      exception will be generated.
 |  
 |  EraseMetaData(self, key)
 |      EraseMetaData(Image self, std::string const & key) -> bool
 |      
 |      
 |      Remove an entry from the meta-data dictionary.
 |      
 |      
 |      Returns true, when the value exists in the dictionary and is removed,
 |      false otherwise.
 |  
 |  EvaluateAtContinuousIndex(self, index, interp=2)
 |      Interpolate pixel value at a continuous index.
 |      
 |      This method is not supported for Label pixel types.
 |      
 |      The valid range of continuous index is [-0.5, size-0.5] for each dimension. An exception is thrown if index is out of bounds.
 |      
 |      Parameters
 |      ----------
 |      index
 |        The continuous index must be at least the length of the image dimension.
 |      interp
 |        The interpolation type to use, only sitkNearest and sitkLinear are supported for Vector and Complex pixel types.
 |      
 |      Returns
 |      -------
 |        The results will be of type float, complex, or an tuple of float of vectors.
 |  
 |  EvaluateAtPhysicalPoint(self, point, interp=2)
 |      Interpolate pixel value at a physical point.
 |      
 |      This method is not supported for Label pixel types.
 |      
 |      An exception is thrown if the point is out of the defined region for the image.
 |      
 |      Parameters
 |      ----------
 |      point
 |        The physical point at which the interpolation is computed.
 |      interp
 |        The interpolation type to use, only sitkNearest and sitkLinear are supported for Vector and Complex pixel types.
 |      
 |      Returns
 |      -------
 |        The results will be of type float, complex, or an tuple of float of vectors.
 |  
 |  GetDepth(self)
 |      GetDepth(Image self) -> unsigned int
 |      
 |      
 |      Get the number of pixels the Image is in the third dimension or 0 if the Image is only 2D
 |  
 |  GetDimension(self)
 |      GetDimension(Image self) -> unsigned int
 |      
 |      
 |      Get the number of physical dimensions.
 |      
 |      Only the spatial dimensions are considered here. These are the
 |      dimensions the origin, spacing and direction cosine matrix are
 |      applicable to. This does not include the pixels' vector index as a
 |      dimension.
 |  
 |  GetDirection(self)
 |      GetDirection(Image self) -> VectorDouble
 |  
 |  GetHeight(self)
 |      GetHeight(Image self) -> unsigned int
 |      
 |      
 |      Get the number of pixels the Image is in the second dimension
 |  
 |  GetITKBase(self, *args)
 |      GetITKBase(Image self) -> itk::DataObject
 |      GetITKBase(Image self) -> itk::DataObject const *
 |  
 |  GetMetaData(self, key)
 |      GetMetaData(Image self, std::string const & key) -> std::string
 |      
 |      
 |      Get the value of a meta-data dictionary entry as a string.
 |      
 |      
 |      If the key is not in the dictionary then an exception is thrown.
 |      
 |      string types in the dictionary are returned as their native strings.
 |      Other types are printed to string before returning.
 |  
 |  GetMetaDataKeys(self)
 |      GetMetaDataKeys(Image self) -> VectorString
 |      
 |      
 |      get a vector of keys in from the meta-data dictionary
 |      
 |      
 |      Returns a vector of keys to the key/value entries in the image's meta-
 |      data dictionary. Iterate through with these keys to get the values.
 |  
 |  GetNumberOfComponentsPerPixel(self)
 |      GetNumberOfComponentsPerPixel(Image self) -> unsigned int
 |      
 |      
 |      Get the number of components for each pixel.
 |      
 |      
 |      For images with scalar or complex pixel types this method returns one.
 |      For images with a vector pixel type the method returns the number of
 |      vector components per pixel.
 |  
 |  GetNumberOfPixels(self)
 |      GetNumberOfPixels(Image self) -> uint64_t
 |      
 |      
 |      Get the number of pixels in the image.
 |      
 |      
 |      To calculate the total number of values stored continuously for the
 |      image's buffer, the NumberOfPixels should be multiplied by
 |      NumberOfComponentsPerPixel in order to account for multiple component
 |      images.
 |  
 |  GetOrigin(self)
 |      GetOrigin(Image self) -> VectorDouble
 |  
 |  GetPixel(self, *idx)
 |      Returns the value of a pixel.
 |      
 |      This method takes 2 parameters in 2D: the x and y index,
 |      and 3 parameters in 3D: the x, y and z index.
 |  
 |  GetPixelID(self)
 |      GetPixelID(Image self) -> itk::simple::PixelIDValueEnum
 |      
 |      
 |      Get the pixel type
 |      
 |      The pixel type is set at construction type and can not be manually
 |      changed, unless by assignment. The value may be -1 or "Unknown".
 |  
 |  GetPixelIDTypeAsString(self)
 |      GetPixelIDTypeAsString(Image self) -> std::string
 |      
 |      
 |      Return the pixel type as a human readable string value.
 |  
 |  GetPixelIDValue(self)
 |      GetPixelIDValue(Image self) -> itk::simple::PixelIDValueType
 |  
 |  GetSize(self)
 |      GetSize(Image self) -> VectorUInt32
 |      
 |      
 |      Get the number of pixels the Image is in each dimension as a std::vector. The size of the vector is
 |      equal to the number of dimensions for the image.
 |  
 |  GetSizeOfPixelComponent(self)
 |      GetSizeOfPixelComponent(Image self) -> unsigned int
 |      
 |      
 |      Get the number of bytes per component of a pixel.
 |      
 |      
 |      Returns the sizeof the pixel component type.
 |  
 |  GetSpacing(self)
 |      GetSpacing(Image self) -> VectorDouble
 |  
 |  GetWidth(self)
 |      GetWidth(Image self) -> unsigned int
 |      
 |      
 |      Get the number of pixels the Image is in the first dimension
 |  
 |  HasMetaDataKey(self, key)
 |      HasMetaDataKey(Image self, std::string const & key) -> bool
 |      
 |      
 |      Query the meta-data dictionary for the existence of a key.
 |  
 |  IsCongruentImageGeometry(self, otherImage, coordinateTolerance, directionTolerance)
 |      IsCongruentImageGeometry(Image self, Image otherImage, double coordinateTolerance, double directionTolerance) -> bool
 |      
 |      
 |      Checks whether the images' pixels at the same index occupy the same
 |      physical space.
 |      
 |      Compares the origin, spacing, and direction for equality within
 |      provided tolerances. There is no check for matching regions in between
 |      the images.
 |      
 |      If The dimensions of the images do not match, false is returned.
 |  
 |  IsSameImageGeometryAs(self, *args, **kwargs)
 |      IsSameImageGeometryAs(Image self, Image otherImage, double arg3=DefaultImageCoordinateTolerance, double arg4=DefaultImageDirectionTolerance) -> bool
 |      
 |      
 |      Check whether the images have the same grid in physical space.
 |      
 |      Compares largest possible regions for equality, and the origin,
 |      spacing, and direction cosines for equality within provided
 |      tolerances.
 |      
 |      If the dimensions of the images do not match, false is returned.
 |  
 |  IsUnique(self)
 |      IsUnique(Image self) -> bool
 |      
 |      
 |      Returns true if no other SimpleITK Image object refers to the same internal data structure.
 |  
 |  MakeUnique(self)
 |      MakeUnique(Image self)
 |      
 |      
 |      Performs actually coping if needed to make object unique.
 |      
 |      
 |      The Image class by default performs lazy coping and assignment. This method
 |      make sure that coping actually happens to the itk::Image pointed to is only pointed to by this object.
 |  
 |  SetDirection(self, direction)
 |      SetDirection(Image self, VectorDouble direction)
 |  
 |  SetMetaData(self, key, value)
 |      SetMetaData(Image self, std::string const & key, std::string const & value)
 |      
 |      
 |      Set an entry in the meta-data dictionary.
 |      
 |      
 |      Replaces or creates an entry in the image's meta-data dictionary.
 |  
 |  SetOrigin(self, origin)
 |      SetOrigin(Image self, VectorDouble origin)
 |  
 |  SetPixel(self, *args)
 |      Sets the value of a pixel.
 |      
 |      This method takes 3 parameters in 2D: the x and y index then the value,
 |      and 4 parameters in 3D: the x, y and z index then the value.
 |  
 |  SetPixelAsComplexFloat64(self, idx, v)
 |      SetPixelAsComplexFloat64(Image self, VectorUInt32 idx, std::complex< double > const v)
 |  
 |  SetSpacing(self, spacing)
 |      SetSpacing(Image self, VectorDouble spacing)
 |  
 |  ToScalarImage(self, inPlace=True)
 |      ToScalarImage(Image self, bool inPlace=True) -> Image
 |      
 |      
 |      Convert a image of vector pixel type to a scalar image with N+1
 |      dimensions.
 |      
 |      
 |      This method will convert a vector image to a scalar image with the
 |      size of the first dimension equal to the number of components. If the
 |      image is already a scalar image then the image is returned.
 |      
 |      For the additional dimension the origin is set to zero, the spacing to
 |      one, and the new components of the direction cosine to the identity
 |      matrix.
 |      
 |      An exception is thrown if the image is has SITK_MAX_DIMENSION
 |      dimensions or if the pixel type is a label or complex pixel type.
 |      
 |      
 |      
 |      Parameters:
 |      
 |      inPlace:
 |      If true then the image is made unique and converted in place updating
 |      this image, otherwise a copy of the image is made and returned.
 |      
 |      
 |      See:
 |       ToVectorImage
 |  
 |  ToVectorImage(self, inPlace=True)
 |      ToVectorImage(Image self, bool inPlace=True) -> Image
 |      
 |      
 |      Convert the first dimension to the components for image with vector
 |      pixel type.
 |      
 |      
 |      This method will convert a scalar image to a vector image with the
 |      number of components equal to the size of the first dimension. If the
 |      image is already a vector image then the image is returned.
 |      
 |      The components of the direction cosine matrix for the first dimension
 |      must be the identity matrix, or else an exception is thrown.
 |      
 |      An exception is thrown if the image is 2D or if the pixel type is a
 |      label or complex pixel type.
 |      
 |      
 |      
 |      Parameters:
 |      
 |      inPlace:
 |      If true then the image is made unique and converted in place updating
 |      this image, otherwise a copy of the image is made and returned.
 |      
 |      
 |      See:
 |       ToScalarImage
 |  
 |  TransformContinuousIndexToPhysicalPoint(self, index)
 |      TransformContinuousIndexToPhysicalPoint(Image self, VectorDouble index) -> VectorDouble
 |      
 |      
 |      Transform continuous index to physical point
 |  
 |  TransformIndexToPhysicalPoint(self, index)
 |      TransformIndexToPhysicalPoint(Image self, VectorInt64 index) -> VectorDouble
 |      
 |      
 |      Transform index to physical point
 |  
 |  TransformPhysicalPointToContinuousIndex(self, point)
 |      TransformPhysicalPointToContinuousIndex(Image self, VectorDouble point) -> VectorDouble
 |      
 |      
 |      Transform physical point to continuous index
 |  
 |  TransformPhysicalPointToIndex(self, point)
 |      TransformPhysicalPointToIndex(Image self, VectorDouble point) -> VectorInt64
 |      
 |      
 |      Transform physical point to index
 |  
 |  __EvaluateAtContinuousIndex__(self, *args, **kwargs)
 |      __EvaluateAtContinuousIndex__(Image self, VectorDouble index, itk::simple::InterpolatorEnum interp=sitkLinear) -> VectorDouble
 |      
 |      
 |      Interpolate pixel value at a continuous index.
 |      
 |      
 |      This method is not supported for Label pixel types.
 |      
 |      The valid range of continuous index is [-0.5, size-0.5] for each
 |      dimension. An exception is thrown if index is out of bounds.
 |      
 |      
 |      
 |      Parameters:
 |      
 |      index:
 |      The continuous index must be at least the length of the image
 |      dimension.
 |      
 |      interp:
 |      The interpolation type to use, only sitkNearest and sitkLinear are
 |      supported for Vector and Complex pixel types.
 |      
 |      
 |      All supported pixel types are returned as an array, where complex
 |      numbers are returned with the real followed by the complex component.
 |  
 |  __EvaluateAtPhysicalPoint__(self, *args, **kwargs)
 |      __EvaluateAtPhysicalPoint__(Image self, VectorDouble point, itk::simple::InterpolatorEnum interp=sitkLinear) -> VectorDouble
 |      
 |      
 |      Interpolate pixel value at a physical point.
 |      
 |      This method is not supported for Label pixel types.
 |      
 |      An exception is thrown if the point is out of the defined region for
 |      the image.
 |      
 |      
 |      
 |      Parameters:
 |      
 |      point:
 |      The physical point at which the interpolation is computed.
 |      
 |      interp:
 |      The interpolation type to use, only sitkNearest and sitkLinear are
 |      supported for Vector and Complex pixel types.
 |      
 |      
 |      All supported pixel types are returned as an array, where complex
 |      numbers are returned with the real followed by the complex component.
 |  
 |  __GetPixelAsComplexFloat32__(self, idx)
 |      __GetPixelAsComplexFloat32__(Image self, VectorUInt32 idx) -> std::complex< float >
 |  
 |  __GetPixelAsComplexFloat64__(self, idx)
 |      __GetPixelAsComplexFloat64__(Image self, VectorUInt32 idx) -> std::complex< double >
 |  
 |  __GetPixelAsDouble__(self, idx)
 |      __GetPixelAsDouble__(Image self, VectorUInt32 idx) -> double
 |  
 |  __GetPixelAsFloat__(self, idx)
 |      __GetPixelAsFloat__(Image self, VectorUInt32 idx) -> float
 |  
 |  __GetPixelAsInt16__(self, idx)
 |      __GetPixelAsInt16__(Image self, VectorUInt32 idx) -> int16_t
 |  
 |  __GetPixelAsInt32__(self, idx)
 |      __GetPixelAsInt32__(Image self, VectorUInt32 idx) -> int32_t
 |  
 |  __GetPixelAsInt64__(self, idx)
 |      __GetPixelAsInt64__(Image self, VectorUInt32 idx) -> int64_t
 |  
 |  __GetPixelAsInt8__(self, idx)
 |      __GetPixelAsInt8__(Image self, VectorUInt32 idx) -> int8_t
 |  
 |  __GetPixelAsUInt16__(self, idx)
 |      __GetPixelAsUInt16__(Image self, VectorUInt32 idx) -> uint16_t
 |  
 |  __GetPixelAsUInt32__(self, idx)
 |      __GetPixelAsUInt32__(Image self, VectorUInt32 idx) -> uint32_t
 |  
 |  __GetPixelAsUInt64__(self, idx)
 |      __GetPixelAsUInt64__(Image self, VectorUInt32 idx) -> uint64_t
 |  
 |  __GetPixelAsUInt8__(self, idx)
 |      __GetPixelAsUInt8__(Image self, VectorUInt32 idx) -> uint8_t
 |  
 |  __GetPixelAsVectorFloat32__(self, idx)
 |      __GetPixelAsVectorFloat32__(Image self, VectorUInt32 idx) -> VectorFloat
 |  
 |  __GetPixelAsVectorFloat64__(self, idx)
 |      __GetPixelAsVectorFloat64__(Image self, VectorUInt32 idx) -> VectorDouble
 |  
 |  __GetPixelAsVectorInt16__(self, idx)
 |      __GetPixelAsVectorInt16__(Image self, VectorUInt32 idx) -> VectorInt16
 |  
 |  __GetPixelAsVectorInt32__(self, idx)
 |      __GetPixelAsVectorInt32__(Image self, VectorUInt32 idx) -> VectorInt32
 |  
 |  __GetPixelAsVectorInt64__(self, idx)
 |      __GetPixelAsVectorInt64__(Image self, VectorUInt32 idx) -> VectorInt64
 |  
 |  __GetPixelAsVectorInt8__(self, idx)
 |      __GetPixelAsVectorInt8__(Image self, VectorUInt32 idx) -> VectorInt8
 |  
 |  __GetPixelAsVectorUInt16__(self, idx)
 |      __GetPixelAsVectorUInt16__(Image self, VectorUInt32 idx) -> VectorUInt16
 |  
 |  __GetPixelAsVectorUInt32__(self, idx)
 |      __GetPixelAsVectorUInt32__(Image self, VectorUInt32 idx) -> VectorUInt32
 |  
 |  __GetPixelAsVectorUInt64__(self, idx)
 |      __GetPixelAsVectorUInt64__(Image self, VectorUInt32 idx) -> VectorUInt64
 |  
 |  __GetPixelAsVectorUInt8__(self, idx)
 |      __GetPixelAsVectorUInt8__(Image self, VectorUInt32 idx) -> VectorUInt8
 |  
 |  __SetPixelAsComplexFloat32__(self, idx, v)
 |      __SetPixelAsComplexFloat32__(Image self, VectorUInt32 idx, std::complex< float > const v)
 |  
 |  __SetPixelAsDouble__(self, idx, v)
 |      __SetPixelAsDouble__(Image self, VectorUInt32 idx, double v)
 |  
 |  __SetPixelAsFloat__(self, idx, v)
 |      __SetPixelAsFloat__(Image self, VectorUInt32 idx, float v)
 |  
 |  __SetPixelAsInt16__(self, idx, v)
 |      __SetPixelAsInt16__(Image self, VectorUInt32 idx, int16_t v)
 |  
 |  __SetPixelAsInt32__(self, idx, v)
 |      __SetPixelAsInt32__(Image self, VectorUInt32 idx, int32_t v)
 |  
 |  __SetPixelAsInt64__(self, idx, v)
 |      __SetPixelAsInt64__(Image self, VectorUInt32 idx, int64_t v)
 |  
 |  __SetPixelAsInt8__(self, idx, v)
 |      __SetPixelAsInt8__(Image self, VectorUInt32 idx, int8_t v)
 |  
 |  __SetPixelAsUInt16__(self, idx, v)
 |      __SetPixelAsUInt16__(Image self, VectorUInt32 idx, uint16_t v)
 |  
 |  __SetPixelAsUInt32__(self, idx, v)
 |      __SetPixelAsUInt32__(Image self, VectorUInt32 idx, uint32_t v)
 |  
 |  __SetPixelAsUInt64__(self, idx, v)
 |      __SetPixelAsUInt64__(Image self, VectorUInt32 idx, uint64_t v)
 |  
 |  __SetPixelAsUInt8__(self, idx, v)
 |      __SetPixelAsUInt8__(Image self, VectorUInt32 idx, uint8_t v)
 |  
 |  __SetPixelAsVectorFloat32__(self, idx, v)
 |      __SetPixelAsVectorFloat32__(Image self, VectorUInt32 idx, VectorFloat v)
 |  
 |  __SetPixelAsVectorFloat64__(self, idx, v)
 |      __SetPixelAsVectorFloat64__(Image self, VectorUInt32 idx, VectorDouble v)
 |  
 |  __SetPixelAsVectorInt16__(self, idx, v)
 |      __SetPixelAsVectorInt16__(Image self, VectorUInt32 idx, VectorInt16 v)
 |  
 |  __SetPixelAsVectorInt32__(self, idx, v)
 |      __SetPixelAsVectorInt32__(Image self, VectorUInt32 idx, VectorInt32 v)
 |  
 |  __SetPixelAsVectorInt64__(self, idx, v)
 |      __SetPixelAsVectorInt64__(Image self, VectorUInt32 idx, VectorInt64 v)
 |  
 |  __SetPixelAsVectorInt8__(self, idx, v)
 |      __SetPixelAsVectorInt8__(Image self, VectorUInt32 idx, VectorInt8 v)
 |  
 |  __SetPixelAsVectorUInt16__(self, idx, v)
 |      __SetPixelAsVectorUInt16__(Image self, VectorUInt32 idx, VectorUInt16 v)
 |  
 |  __SetPixelAsVectorUInt32__(self, idx, v)
 |      __SetPixelAsVectorUInt32__(Image self, VectorUInt32 idx, VectorUInt32 v)
 |  
 |  __SetPixelAsVectorUInt64__(self, idx, v)
 |      __SetPixelAsVectorUInt64__(Image self, VectorUInt32 idx, VectorUInt64 v)
 |  
 |  __SetPixelAsVectorUInt8__(self, idx, v)
 |      __SetPixelAsVectorUInt8__(Image self, VectorUInt32 idx, VectorUInt8 v)
 |  
 |  __abs__(self)
 |  
 |  __add__(self, other)
 |  
 |  __and__(self, other)
 |  
 |  __contains__(self, key)
 |      Test if key is contained in the meta-data dictionary.
 |  
 |  __copy__(self)
 |      Create a SimpleITK shallow copy, where the internal image share is shared with copy on write implementation.
 |  
 |  __deepcopy__(self, memo)
 |      Create a new copy of the data and image class.
 |  
 |  __delitem__(self, key)
 |      Remove an item from the meta-data dictionary.
 |      
 |      It is an exception to delete the "origin", "spacing" and "direction" reserved keys.
 |      
 |      If the key does not exist in the dictionary no action or exception occours.
 |  
 |  __div__(self, other)
 |  
 |  __eq__(self, other)
 |      Return self==value.
 |  
 |  __floordiv__(self, other)
 |  
 |  __ge__(self, other)
 |      Return self>=value.
 |  
 |  __getitem__(self, idx)
 |      Get an pixel value, a sliced image, or a metadata item
 |      
 |      This operator implements basic indexing where idx is
 |      arguments or a squence of integers the same dimension as
 |      the image. The result will be a pixel value from that
 |      index.
 |      
 |      Multi-dimension extended slice based indexing is also
 |      implemented. The return is a copy of a new image. The
 |      standard sliced based indices are supported including
 |      negative indices, to indicate location relative to the
 |      end, along with negative step sized to indicate reversing
 |      of direction.
 |      
 |      If the length of idx is less than the number of dimension
 |      of the image it will be padded with the defaults slice
 |      ":".
 |      
 |      When an index element is an integer, that dimension is
 |      collapsed extracting an image with reduced dimensionality.
 |      The minimum dimension of an image which can be extracted
 |      is 2D.
 |      
 |      If indexing with a string, then the metadata dictionary
 |      queried with the index as the key. If the metadata dictionary
 |      does not contain the key, a KeyError will occour.
 |  
 |  __gt__(self, other)
 |      Return self>value.
 |  
 |  __iadd__(self, *args)
 |      __iadd__(Image self, Image i) -> Image
 |      __iadd__(Image self, double c) -> Image
 |  
 |  __iand__(self, *args)
 |      __iand__(Image self, Image i) -> Image
 |      __iand__(Image self, int c) -> Image
 |  
 |  __ifloordiv__(self, *args)
 |      __ifloordiv__(Image self, Image i) -> Image
 |      __ifloordiv__(Image self, double c) -> Image
 |  
 |  __imod__(self, *args)
 |      __imod__(Image self, Image i) -> Image
 |      __imod__(Image self, int c) -> Image
 |  
 |  __imul__(self, *args)
 |      __imul__(Image self, Image i) -> Image
 |      __imul__(Image self, double c) -> Image
 |  
 |  __init__(self, *args)
 |      __init__(Image self) -> Image
 |      __init__(Image self, Image img) -> Image
 |      __init__(Image self, unsigned int width, unsigned int height, itk::simple::PixelIDValueEnum valueEnum) -> Image
 |      __init__(Image self, unsigned int width, unsigned int height, unsigned int depth, itk::simple::PixelIDValueEnum valueEnum) -> Image
 |      __init__(Image self, VectorUInt32 size, itk::simple::PixelIDValueEnum valueEnum, unsigned int numberOfComponents=0) -> Image
 |      
 |      
 |      Move constructor and assignment.
 |      
 |      
 |      
 |      
 |      Parameters:
 |      
 |      img:
 |      After the operation img is valid only for destructing and assignment;
 |      all other operations have undefined behavior.
 |  
 |  __invert__(self)
 |  
 |  __ior__(self, *args)
 |      __ior__(Image self, Image i) -> Image
 |      __ior__(Image self, int c) -> Image
 |  
 |  __ipow__(self, *args)
 |      __ipow__(Image self, Image i) -> Image
 |      __ipow__(Image self, double c) -> Image
 |  
 |  __isub__(self, *args)
 |      __isub__(Image self, Image i) -> Image
 |      __isub__(Image self, double c) -> Image
 |  
 |  __iter__(self)
 |  
 |  __itruediv__(self, *args)
 |      __itruediv__(Image self, Image i) -> Image
 |      __itruediv__(Image self, double c) -> Image
 |  
 |  __ixor__(self, *args)
 |      __ixor__(Image self, Image i) -> Image
 |      __ixor__(Image self, int c) -> Image
 |  
 |  __le__(self, other)
 |      Return self<=value.
 |  
 |  __len__(self)
 |  
 |  __lt__(self, other)
 |      Return self<value.
 |  
 |  __mod__(self, other)
 |  
 |  __mul__(self, other)
 |  
 |  __ne__(self, other)
 |      Return self!=value.
 |  
 |  __neg__(self)
 |  
 |  __or__(self, other)
 |      Return self|value.
 |  
 |  __pos__(self)
 |  
 |  __pow__(self, other)
 |  
 |  __radd__(self, other)
 |  
 |  __rand__(self, other)
 |  
 |  __rdiv__(self, other)
 |  
 |  __reduce_ex__(self, protocol)
 |      Helper for pickle.
 |  
 |  __repr__ = _swig_repr(self) from SimpleITK.SimpleITK
 |  
 |  __rfloordiv__(self, other)
 |  
 |  __rmul__(self, other)
 |  
 |  __ror__(self, other)
 |      Return value|self.
 |  
 |  __rpow__(self, other)
 |  
 |  __rsub__(self, other)
 |  
 |  __rtruediv__(self, other)
 |  
 |  __rxor__(self, other)
 |  
 |  __setitem__(self, idx, rvalue)
 |      Sets this image's pixel value(s) to rvalue.
 |      
 |      The dimension of idx must match that of the image.
 |      
 |      If all indices are integers then rvalue should be a pixel value
 |      ( scalar or sequence for vector pixels). The value is assigned to
 |      the pixel.
 |      
 |      If idx is an image, it is considered a binary mask of 0s and non-zeros.
 |      The pixels corresponding to the non-zeros of the mask are assigned
 |      values. If rvalue is a scalar constant the scalar value is assigned to
 |      the pixel. If rvalue is an image then the corresponding pixel is
 |      assigned. All images involved in the operation must have congruent
 |      geometry.
 |      
 |      If the indices are slices or integers then, the PasteImageFilter is
 |      used to assign values to this image. The rvalue can be an image
 |      or a scalar constant value. When rvalue is an image it must be of
 |      the same pixel type and equal or lesser dimension than self. The
 |      region defined by idx and rvalue's size must be compatible. The
 |      region defined by idx will collapse one sized idx dimensions when it
 |      does not match the rvalue image's size.
 |  
 |  __setstate__(self, args)
 |  
 |  __str__(self)
 |      __str__(Image self) -> std::string
 |  
 |  __sub__(self, other)
 |  
 |  __truediv__(self, other)
 |  
 |  __xor__(self, other)
 |  
 |  ----------------------------------------------------------------------
 |  Static methods defined here:
 |  
 |  __swig_destroy__ = delete_Image(...)
 |      delete_Image(Image self)
 |  
 |  ----------------------------------------------------------------------
 |  Data descriptors defined here:
 |  
 |  __dict__
 |      dictionary for instance variables
 |  
 |  __weakref__
 |      list of weak references to the object
 |  
 |  thisown
 |      The membership flag
 |  
 |  ----------------------------------------------------------------------
 |  Data and other attributes defined here:
 |  
 |  DefaultImageCoordinateTolerance = 1e-06
 |  
 |  DefaultImageDirectionTolerance = 1e-06
 |  
 |  __hash__ = None

Accessing Attributes

If you are familiar with ITK, then these methods will follow your expectations:

print(image.GetSize())
print(image.GetOrigin())
print(image.GetSpacing())
print(image.GetDirection())
print(image.GetNumberOfComponentsPerPixel())

(256, 128, 64)
(0.0, 0.0, 0.0)
(1.0, 1.0, 1.0)
(1.0, 0.0, 0.0, 0.0, 1.0, 0.0, 0.0, 0.0, 1.0)
1

Note: The starting index of a SimpleITK Image is always 0. If the output of an ITK filter has non-zero starting index, then the index will be set to 0, and the origin adjusted accordingly.

The size of the image's dimensions have explicit accessors:

print(image.GetWidth())
print(image.GetHeight())
print(image.GetDepth())

256
128
64

Since the dimension and pixel type of a SimpleITK image is determined at run-time accessors are needed.

print(image.GetDimension())
print(image.GetPixelIDValue())
print(image.GetPixelIDTypeAsString())

3
2
16-bit signed integer

What is the depth of a 2D image?

print(image_2D.GetSize())
print(image_2D.GetDepth())

(32, 32)
0

What is the dimension and size of a Vector image?

print(image_RGB.GetDimension())
print(image_RGB.GetSize())

2
(128, 128)

print(image_RGB.GetNumberOfComponentsPerPixel())

3

For certain file types such as DICOM, additional information about the image is contained in the meta-data dictionary.

for key in image.GetMetaDataKeys():
    print(f'"{key}":"{image.GetMetaData(key)}"')

Accessing Pixels

There are the member functions GetPixel and SetPixel which provides an ITK-like interface for pixel access.

help(image.GetPixel)

Help on method GetPixel in module SimpleITK.SimpleITK:

GetPixel(*idx) method of SimpleITK.SimpleITK.Image instance
    Returns the value of a pixel.
    
    This method takes 2 parameters in 2D: the x and y index,
    and 3 parameters in 3D: the x, y and z index.

print(image.GetPixel(0, 0, 0))
image.SetPixel(0, 0, 0, 1)
print(image.GetPixel(0, 0, 0))

0
1

print(image[0, 0, 0])
image[0, 0, 0] = 10
print(image[0, 0, 0])

1
10

Conversion between numpy and SimpleITK

nda = sitk.GetArrayFromImage(image)
print(nda)

[[[10  0  0 ...  0  0  0]
  [ 0  0  0 ...  0  0  0]
  [ 0  0  0 ...  0  0  0]
  ...
  [ 0  0  0 ...  0  0  0]
  [ 0  0  0 ...  0  0  0]
  [ 0  0  0 ...  0  0  0]]

 [[ 0  0  0 ...  0  0  0]
  [ 0  0  0 ...  0  0  0]
  [ 0  0  0 ...  0  0  0]
  ...
  [ 0  0  0 ...  0  0  0]
  [ 0  0  0 ...  0  0  0]
  [ 0  0  0 ...  0  0  0]]

 [[ 0  0  0 ...  0  0  0]
  [ 0  0  0 ...  0  0  0]
  [ 0  0  0 ...  0  0  0]
  ...
  [ 0  0  0 ...  0  0  0]
  [ 0  0  0 ...  0  0  0]
  [ 0  0  0 ...  0  0  0]]

 ...

 [[ 0  0  0 ...  0  0  0]
  [ 0  0  0 ...  0  0  0]
  [ 0  0  0 ...  0  0  0]
  ...
  [ 0  0  0 ...  0  0  0]
  [ 0  0  0 ...  0  0  0]
  [ 0  0  0 ...  0  0  0]]

 [[ 0  0  0 ...  0  0  0]
  [ 0  0  0 ...  0  0  0]
  [ 0  0  0 ...  0  0  0]
  ...
  [ 0  0  0 ...  0  0  0]
  [ 0  0  0 ...  0  0  0]
  [ 0  0  0 ...  0  0  0]]

 [[ 0  0  0 ...  0  0  0]
  [ 0  0  0 ...  0  0  0]
  [ 0  0  0 ...  0  0  0]
  ...
  [ 0  0  0 ...  0  0  0]
  [ 0  0  0 ...  0  0  0]
  [ 0  0  0 ...  0  0  0]]]

help(sitk.GetArrayFromImage)

Help on function GetArrayFromImage in module SimpleITK.extra:

GetArrayFromImage(image: SimpleITK.SimpleITK.Image) -> 'numpy.ndarray'
    Get a NumPy ndarray from a SimpleITK Image.
    
    This is a deep copy of the image buffer and is completely safe and without potential side effects.

# Get a view of the image data as a numpy array, useful for display
nda = sitk.GetArrayViewFromImage(image)

nda = sitk.GetArrayFromImage(image_RGB)
img = sitk.GetImageFromArray(nda)
img.GetSize()

(3, 128, 128)

help(sitk.GetImageFromArray)

Help on function GetImageFromArray in module SimpleITK.extra:

GetImageFromArray(arr: 'numpy.ndarray', isVector: Optional[bool] = None) -> SimpleITK.SimpleITK.Image
    Get a SimpleITK Image from a numpy array.
    
    If isVector is True, then the Image will have a Vector pixel type, and the last dimension of the array will be
    considered the component index. By default when isVector is None, 4D arrays
    are automatically considered 3D vector images, but 3D arrays are 3D images.

img = sitk.GetImageFromArray(nda, isVector=True)
print(img)

VectorImage (0x7fed06820780)
  RTTI typeinfo:   itk::VectorImage<unsigned char, 2u>
  Reference Count: 1
  Modified Time: 1647
  Debug: Off
  Object Name: 
  Observers: 
    none
  Source: (none)
  Source output name: (none)
  Release Data: Off
  Data Released: False
  Global Release Data: Off
  PipelineMTime: 0
  UpdateMTime: 0
  RealTimeStamp: 0 seconds 
  LargestPossibleRegion: 
    Dimension: 2
    Index: [0, 0]
    Size: [128, 128]
  BufferedRegion: 
    Dimension: 2
    Index: [0, 0]
    Size: [128, 128]
  RequestedRegion: 
    Dimension: 2
    Index: [0, 0]
    Size: [128, 128]
  Spacing: [1, 1]
  Origin: [0, 0]
  Direction: 
1 0
0 1

  IndexToPointMatrix: 
1 0
0 1

  PointToIndexMatrix: 
1 0
0 1

  Inverse Direction: 
1 0
0 1

  VectorLength: 3
  PixelContainer: 
    ImportImageContainer (0x6000002f0e40)
      RTTI typeinfo:   itk::ImportImageContainer<unsigned long, unsigned char>
      Reference Count: 1
      Modified Time: 1648
      Debug: Off
      Object Name: 
      Observers: 
        none
      Pointer: 0x7fed080e0000
      Container manages memory: true
      Size: 49152
      Capacity: 49152

The order of index and dimensions need careful attention during conversion

ITK's Image class does not have a bracket operator. It has a GetPixel which takes an ITK Index object as an argument, which is ordered as (x,y,z). This is the convention that SimpleITK's Image class uses for the GetPixel method and slicing operator as well. In numpy, an array is indexed in the opposite order (z,y,x). Also note that the access to channels is different. In SimpleITK you do not access the channel directly, rather the pixel value representing all channels for the specific pixel is returned and you then access the channel for that pixel. In the numpy array you are accessing the channel directly.

import numpy as np

multi_channel_3Dimage = sitk.Image([2, 4, 8], sitk.sitkVectorFloat32, 5)
x = multi_channel_3Dimage.GetWidth() - 1
y = multi_channel_3Dimage.GetHeight() - 1
z = multi_channel_3Dimage.GetDepth() - 1
multi_channel_3Dimage[x, y, z] = np.random.random(
    multi_channel_3Dimage.GetNumberOfComponentsPerPixel()
)

nda = sitk.GetArrayFromImage(multi_channel_3Dimage)

print("Image size: " + str(multi_channel_3Dimage.GetSize()))
print("Numpy array size: " + str(nda.shape))

# Notice the index order and channel access are different:
print("First channel value in image: " + str(multi_channel_3Dimage[x, y, z][0]))
print("First channel value in numpy array: " + str(nda[z, y, x, 0]))

Image size: (2, 4, 8)
Numpy array size: (8, 4, 2, 5)
First channel value in image: 0.47758376598358154
First channel value in numpy array: 0.47758377

Are we still dealing with Image, because I haven't seen one yet...

While SimpleITK does not do visualization, it does contain a built in Show method. This function writes the image out to disk and than launches a program for visualization. By default it is configured to use ImageJ, because it is readily supports all the image types which SimpleITK has and load very quickly. However, it's easily customizable by setting environment variables.

sitk.Show(image)

?sitk.Show

By converting into a numpy array, matplotlib can be used for visualization for integration into the scientific python environment.

%matplotlib inline
import matplotlib.pyplot as plt

z = 0
slice = sitk.GetArrayViewFromImage(image)[z, :, :]
plt.imshow(slice)

<matplotlib.image.AxesImage at 0x115dbe650>