# 46. `plugins.imagearray` — Convert bitmap images into numpy arrays.

This module contains functions to convert bitmap images into numpy arrays and vice versa.

This code was based on ideas found on the PyQwt mailing list.

class `plugins.imagearray.``DicomStack`(files, zsort=True, reverse=False)

  A stack of DICOM images.

  The DicomStack class stores a collection of DICOM images and provides conversion to ndarray.

  The DicomStack is initialized by a list of file names. All input files are scanned for DICOM image data and non-DICOM files are skipped. From the DICOM files, the pixel and slice spacing are read, as well as the origin. The DICOM files are sorted in order of ascending origin_z value.

  While reading the DICOM files, the following attributes are set:

  - files: a list of the valid DICOM files, in order of ascending z-value.
  - pixel_spacing: a dict with an (x,y) pixel spacing tuple as key and a list of indices of the matching images as value.
  - slice_thickness: a list of the slice thicknesses of the images, in the same order as files.
  - xy_origin: a dict with an (x,y) position the pixel (0,0) as key and a list of indices of the matching images as value.
  - z_origin: a list of the z positions of the images, in the same order as files.
  - rejected: list of rejected files.
  class `Object`

    _A dummy object to allow attributes

  `nfiles`()

    Return the number of accepted files.

  `files`()

    Return the list of accepted filenames

  `rejected`()

    Return the list of rejected filenames

  `spacing`()

    Return the pixel spacing and slice thickness.

    Return the pixel spacing (x,y) and the slice thickness (z) in the accepted images.

    Returns: a float array of shape (nfiles,3).

  `origin`()

    Return the origin of all accepted images.

    Return the world position of the pixel (0,0) in all accepted images.

    Returns: a float array of shape (nfiles,3).

  `zvalue`()

    Return the zvalue of all accepted images.

    The zvalue is the z value of the origin of the image.

    Returns: a float array of shape (nfiles).

  `image`(i)

    Return the image at index i

  `pixar`(raw=False)

    Return the DicomStack as an array

    Returns all images in a single array. This is only succesful if all accepted images have the same size.

## 46.1. Functions defined in module plugins.imagearray

`plugins.imagearray.``resizeImage`(image, w=0, h=0)

  Load and optionally resize an image.

  Parameters:

  - image: a QImage, or any data that can be converted to a QImage, e.g. the name of a raster image file.
  - w, h: requested size in pixels of the image. A value <= 0 will be replaced with the corresponding actual size of the image.

  Returns a QImage with the requested size.

`plugins.imagearray.``qimage2numpy`(image, resize=(0, 0), order='RGBA', flip=True, indexed=None, expand=None)

  Transform an image to a Numpy array.

  Parameters:

  - image: a QImage or any data that can be converted to a QImage, e.g. the name of an image file, in any of the formats supported by Qt. The image can be a full color image or an indexed type. Only 32bit and 8bit images are currently supported.
  - resize: a tuple of two integers (width,height). Positive value will force the image to be resized to this value.
  - order: string with a permutation of the characters ‘RGBA’, defining the order in which the colors are returned. Default is RGBA, so that result[…,0] gives the red component. Note however that QImage stores in ARGB order. You may also specify a subset of the ‘RGBA’ characters, in which case you will only get some of the color components. An often used value is ‘RGB’ to get the colors without the alpha value.
  - flip: boolean: if True, the image scanlines are flipped upside down. This is practical because image files are usually stored in top down order, while OpenGL uses an upwards positive direction, requiring a flip to show the image upright.
  - indexed: True, False or None.
    - If True, the result will be an indexed image where each pixel color is an index into a color table. Non-indexed image data will be converted.
    - If False, the result will be a full color array specifying the color of each pixel. Indexed images will be converted.
    - If None (default), no conversion is done and the resulting data are dependent on the image format. In all cases both a color and a colortable will be returned, but the latter will be None for non-indexed images.
  - expand: deprecated, retained for compatibility

  Returns:

  - if indexed is False: an int8 array with shape (height,width,4), holding the 4 components of the color of each pixel. Order of the components is as specified by the order argument. Indexed image formats will be expanded to a full color array.
  - if indexed is True: a tuple (colors,colortable) where colors is an (height,width) shaped int array of indices into the colortable, which is an int8 array with shape (ncolors,4).
  - if indexed is None (default), a tuple (colors,colortable) is returned, the type of which depend on the original image format:
    - for indexed formats, colors is an int (height,width) array of indices into the colortable, which is an int8 array with shape (ncolors,4).
    - for non-indexed formats, colors is a full (height,width,4) array and colortable is None.

`plugins.imagearray.``numpy2qimage`(array)

  Convert a 2D or 3D integer numpy array into a QImage

  Parameters:

  - array: 2D or 3D int array. If the input array is 2D, the array is converted into a gray image. If the input array is 3D, the last axis should have length 3 or 4 and represents the color channels in order RGB or RGBA.

  This is equivalent with calling `gray2qimage()` for a 2D array and rgb2qimage for a 3D array.

`plugins.imagearray.``gray2qimage`(gray)

  Convert the 2D numpy array gray into a 8-bit QImage with a gray colormap. The first dimension represents the vertical image axis.

`plugins.imagearray.``rgb2qimage`(rgb)

  Convert the 3D numpy array into a 32-bit QImage.

  Parameters:

  - rgb : (height,width,nchannels) integer array specifying the pixels of an image. There can be 3 (RGB) or 4 (RGBA) channels.

  Returns a QImage with size (height,width) in the format RGB32 (3channel) or ARGB32 (4channel).

`plugins.imagearray.``qimage2glcolor`(image, resize=(0, 0))

  Convert a bitmap image to corresponding OpenGL colors.

  Parameters:

  - image: a QImage or any data that can be converted to a QImage, e.g. the name of an image file, in any of the formats supported by Qt. The image can be a full color image or an indexed type. Only 32bit and 8bit images are currently supported.
  - resize: a tuple of two integers (width,height). Positive value will force the image to be resized to this value.

  Returns a (w,h,3) shaped array of float values in the range 0.0 to 1.0, containing the OpenGL colors corresponding to the image RGB colors. By default the image is flipped upside-down because the vertical OpenGL axis points upwards, while bitmap images are stored downwards.

`plugins.imagearray.``removeAlpha`(qim)

  Remove the alpha channel from a QImage.

  Directly saving a QImage grabbed from the OpenGL buffers always results in an image with transparency. See https://savannah.nongnu.org/bugs/?36995 .

  This function will remove the alpha channel from the QImage, so that it can be saved with opaque objects.

  Note: we did not find a way to do this directly on the QImage, so we go through a conversion to a numpy array and back.

`plugins.imagearray.``loadImage_gdcm`(filename)

  Load a DICOM image into a numpy array.

  This function uses the python-gdcm module to load a DICOM image into a numpy array. See also `loadImage_dicom()` for an equivalent using python-dicom.

  Parameters:

  - file: the name of a DICOM image file
  Returns a 2D array with the pixel data of the image. The first
    axis is the y value, the last the x.

  As a side effect, this function sets the global variables _dicom_spacing and _dicom_origin to a to a (3,) array with the pixel/slice spacing factors, resp. the origin, in order (x,y,z). It also sets the _dicom_slope, _dicom_intercept global variables.

`plugins.imagearray.``readDicom`(filename)

  Load a DICOM image into a numpy array.

  This function uses the python-gdcm module to load a DICOM image into a numpy array. See also `loadImage_dicom()` for an equivalent using python-dicom.

  Parameters:

  - file: the name of a DICOM image file
  Returns a 2D array with the pixel data of the image. The first
    axis is the y value, the last the x.

  As a side effect, this function sets the global variables _dicom_spacing and _dicom_origin to a to a (3,) array with the pixel/slice spacing factors, resp. the origin, in order (x,y,z). It also sets the _dicom_slope, _dicom_intercept global variables.

`plugins.imagearray.``dicom2numpy`(files)

  Read a set of DICOM image files.

  Parameters:

  - files: a list of file names of dicom images of the same size, or a directory containing such images. In the latter case, all the DICOM images in the directory will be read.

  Returns a tuple of:

  - pixar: a 3D array with the pixel data of all the images. The first axis is the z value, the last the x.
  - scale: a (3,) array with the scaling factors, in order (x,y,z).

`plugins.imagearray.``saveGreyImage`(a, f, flip=True)

  Save a 2D int array as a grey image.

  Parameters:

  - a: int array (nx,ny) with values in the range 0..255. These are the grey values of the pixels.
  - f: filename
  - flip: by default, the vertical axis is flipped, so that images are stored starting at the top. If your data already have the vertical axis downwards, use flip=False.