dippykit.image_io module¶

Module of image I/O related functions

This module contains an assortment of functions that make the input and output of images much simpler. The syntax is similar to that of Matlab.

dippykit.image_io.im_read(filepath: str) → numpy.ndarray[source]¶

Reads an image from a file

Using Pillow, attempts to open the image at the given filepath argument and subsequently converts the image into a numpy array.

This function is essentially a wrapper for PIL.Image.open, so more detailed documentation may be found there.

Parameters:	filepath (`str`) – A filepath to the desired image.
Return type:	`numpy.ndarray`
Returns:	The image as a numpy array.
Raises:	IOError – “If the file cannot be found, or the image cannot be opened and identified.” -Pillow

Note

This function wraps around functions from other packages. Reading these functions’ documentations may be useful. See the See also section for more information.

See also

PIL.Image.open: Documentation of the open function from Pillow

Examples:

>>> im_read('black_image.tif')
array([[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.]])

dippykit.image_io.im_write(image: numpy.ndarray, filepath: str, quality: int = 75) → None[source]¶

Writes an image to a file

Using Pillow, attempts to write the image to a given filepath argument.

This function is essentially a wrapper for PIL.Image.save, so more detailed documentation may be found there.

Parameters:	image (`numpy.ndarray`) – The image to be written to a file. filepath (`str`) – A filepath for the output image. quality (`int`) – (default=75) The quality level at which you’d like to save the image. This value should range from 1 (worst) to 95 (best). This value is primarily used when saving JPEG files.
Raises:	KeyError – “If the output format could not be determined from the file name.” -Pillow IOError – “If the file could not be written. The file may have been created, and may contain partial data.” -Pillow

Note

This function wraps around functions from other packages. Reading these functions’ documentations may be useful. See the See also section for more information.

See also

PIL.Image.save: Documentation of the save function from Pillow

Examples:

>>> import numpy as np
>>> image = np.array([[0, 255], [255, 0]], dtype='uint8')
>>> im_write(image, 'image.tif')
>>> # There is now a file 'image.tif' in the current directory

dippykit.image_io.im_to_float(image: numpy.ndarray) → numpy.ndarray[source]¶

Converts an image from unsigned integer format to normalized floating point format

Given an image in an unsigned integer format (values between 0 and 2^N - 1), this function converts the image to a floating point format where each value is normalized between 0.0 and 1.0. Images in this format are more easily processed reliably.

The dtype of the input image must be one of the following: uint8, uint16, uint32, or uint64. The values in the image are assumed to have a range of 0~(2^N - 1) inclusive, where N is the number of bits used to represent each unsigned integer. This means that if one wants to convert an image with dtype uint8, every instance of the value 0 in the input image will become a 0.0 in the output image and every instance of the value 255 in the input image will become a 1.0 in the output image.

Parameters:	image (`numpy.ndarray` (dtype must be unsigned integer)) – The image in unsigned integer format.
Return type:	`numpy.ndarray`
Returns:	The image in normalized floating point format (values between 0.0 and 1.0).
Raises:	ValueError – If the dtype of the image argument is not unsigned integer.

Examples:

>>> import numpy as np
>>> image = np.array([[0, 64], [128, 255]], dtype='uint8')
>>> im_to_float(image)
array([[0.        , 0.25098039],
       [0.50196078, 1.        ]])

dippykit.image_io.float_to_im(image: numpy.ndarray, bit_depth: int = 8) → numpy.ndarray[source]¶

Converts an image from normalized floating point space to integer space

Given an image in normalized floating point format (values between 0.0 and 1.0), this function converts the image to an unsigned integer format normalized to the range of values of the format (e.g. for uint8 this range is 0~(2^N - 1) = 0~255 inclusive). Images in this format are more easily stored or written to files.

If any values in the image argument are less than 0.0 or greater than 1.0, they will be replaced with 0.0s and 1.0s, respectively. This allows for normalized floating point images to “saturate” in processing.

If the bit_depth argument is specified, the image will be converted with the specified bit depth. The number of levels in the image will be 2^bit_depth.

The dtype of the returned image is dependent on the bit depth specified. By default, the bit depth is set to 8, meaning that the returned image will have a dtype of uint8. For a given bit depth, the returned dtype will be the following:

1 <= bit_depth <= 8: uint8 (default)

9 <= bit_depth <= 16: uint16

17 <= bit_depth <= 32: uint32

33 <= bit_depth <= 64: uint64

Parameters:	image (`numpy.ndarray` (dtype must be float)) – The image in normalized floating point format (0.0 represents the minimum value and 1.0 represents the maximum value). bit_depth (`int`) – (default=8) Bit depth for the converted image (between 1 and 64 inclusive).
Return type:	`numpy.ndarray`
Returns:	The image in unsigned integer format.
Raises:	ValueError – If the bit_depth is not between 1 and 64.

Examples:

>>> import numpy as np
>>> image = np.array([[0, 64], [128, 255]], dtype='uint8')
>>> image_in_float = im_to_float(image)
>>> image_in_float
array([[0.        , 0.25098039],
       [0.50196078, 1.        ]])
>>> float_to_im(image_in_float)
array([[  0,  64],
       [128, 255]], dtype=uint8)
>>> float_to_im(image_in_float, 1)
array([[  0,   0],
       [128, 128]], dtype=uint8)