Dolphin dimage

class dolphin.dimage(shape: Optional[Tuple[int, ...]] = None, dtype: dtype = dtype.uint8, stream: Optional[pycuda.driver.Stream] = None, array: Optional[ndarray] = None, channel_format: Optional[dimage_channel_format] = None, strides: Optional[Tuple[int, ...]] = None, allocation: Optional[pycuda.driver.DeviceAllocation] = None, allocation_size: Optional[int] = None)[source]

Bases: darray

This class inherits from darray in order to provide image processing functionalities.

dimage is made with the same philosophy as darray but with additionnal functionalities for image processing gpu-accelerated. It supports all the methods defined in darray but has some specific attributes in order to better handle images.

We tried to partly follow the same philosophy as OpenCV in order to make the transition easier.

Important : dimage is assuming to follow (height, width) order as per defined in OpenCV.

Parameters:

shape (Tuple[int, ...][int, ...], optional) – Shape of the darray, defaults to None
dtype (dolphin.dtype, optional) – dtype of the darray, defaults to None
stream (cuda.Stream, optional) – CUDA stream to use, defaults to None
array (numpy.ndarray, optional) – numpy array to copy, defaults to None
channel_format (dimage_channel_format, optional) – Channel format of the image, defaults to None
strides (Tuple[int, ...][int, ...], optional) – strides of the darray, defaults to None
allocation (cuda.DeviceAllocation, optional) – CUDA allocation to use, defaults to None
allocation_size (int, optional) – Size of the allocation, defaults to None

__init__(shape: Optional[Tuple[int, ...]] = None, dtype: dtype = dtype.uint8, stream: Optional[pycuda.driver.Stream] = None, array: Optional[ndarray] = None, channel_format: Optional[dimage_channel_format] = None, strides: Optional[Tuple[int, ...]] = None, allocation: Optional[pycuda.driver.DeviceAllocation] = None, allocation_size: Optional[int] = None) → None[source]

copy() → dimage[source]

Returns a copy of the image.

Returns:: The copy of the image
Return type:: dimage

property image_channel_format: dimage_channel_format

Returns the image channel format.

Returns:: The image channel format
Return type:: dimage_channel_format

property image_dim_format: dimage_dim_format

Returns the image dimension format.

Returns:: The image dimension format
Return type:: dimage_dim_format

property height: uint16

Returns the height of the image.

Returns:: The height of the image
Return type:: numpy.uint16

property width: uint16

Returns the width of the image.

Returns:: The width of the image
Return type:: numpy.uint16

property channel: uint8

Returns the number of channels of the image.

Returns:: The number of channels of the image
Return type:: numpy.uint8

astype(dtype: dtype, dst: Optional[dimage] = None) → dimage[source]

Convert the image to a different type

This function converts the image to a different type. To use it efficiently, the destination image must be preallocated and passed as an argument to the function:

src = dimage(shape=(100, 100, 3), dtype=dolphin.dtype.uint8)
dst = dimage(shape=(100, 100, 3), dtype=dolphin.dtype.float32)
src.astype(dolphin.dtype.float32, dst)

Parameters:

dtype (dolphin.dtype) – Dtype to convert the darray to
dst (dimage) – Destination image

resize_padding(shape: Tuple[int, ...], dst: Optional[dimage] = None, padding_value: Union[int, float] = 127) → Tuple[dimage, float, Tuple[int, int]][source]

Padded resize the image

This function resizes the image to a new shape with padding. It means that the image is resized to the new shape and the remaining pixels are filled with the padding value (127 by default).

If for instance the image is resized from (50, 100) to (200, 200), the aspect ratio of the image is preserved and the image is resized to (100, 200). The remaining pixels are filled with the padding value. In this scenario, the padding would appear on the left and right side of the image, with a width of 50 pixels.

In order to use this function in an efficient way, the destination image must be preallocated and passed as an argument to the function:

src = dimage(shape=(100, 100, 3), dtype=dolphin.dtype.uint8)
dst = dimage(shape=(200, 200, 3), dtype=dolphin.dtype.uint8)
src.resize_padding((200, 200), dst)

If aspect ratio does not matter, the function resize() can be used.

Parameters:

shape (Tuple[int, ...]) – The new shape of the image
dst (dimage) – The destination image
padding_value (int or float) – The padding value

Returns:

The resized image and the offset parameters of the image

Return type:

Tuple[dimage, float, Tuple[int, int]]

resize(shape: Tuple[int, ...], dst: Optional[dimage] = None) → dimage[source]

Resize the image

This function performs a naive resize of the image. The resize type is for now only dolphin.dimage_resize_type.DOLPHIN_NEAREST. In order to use this function in an efficient way, the destination image must be preallocated and passed as an argument to the function:

src = dimage(shape=(100, 100, 3), dtype=dolphin.dtype.uint8)
dst = dimage(shape=(200, 200, 3), dtype=dolphin.dtype.float32)
src.resize((200, 200), dst)

The returned resized image aspect ratio might change as the new shape is not necessarily a multiple of the original shape.

If aspect ratio of the orginal image matters to you, use resize_padding() instead:

src = dimage(shape=(100, 100, 3), dtype=dolphin.dtype.uint8)
dst = dimage(shape=(200, 200, 3), dtype=dolphin.dtype.float32)
src.resize_padding((200, 200), dst)

Parameters:

shape (Tuple[int, ...]) – The new shape of the image
dst (dimage) – The destination image

__module__ = 'dolphin.core.dimage'

crop_and_resize(coordinates: darray, size: Tuple[int, int], dst: Optional[darray] = None) → darray[source]

This method is well performing for cropping and resizing images. The use case would be to process a batch of images which would be the crops of a bigger image. The coordinates of the crops would, for instance, be the output of a detection model.

In terms of usability, the coordinates are expected to be in the following format: [[x1, y1, x2, y2], …] where x1, y1, x2, y2 are the absolute coordinates of the top left and bottom right corners of the crop in the original image.

Coordinates would thus be a dolphin.darray of shape (n, 4) where n is the number of crops, n >= 1.

Also, for faster execution, the destination darray is expected to be preallocated and passed as an argument to the function.

Parameters:

coordinates (dolphin.darray) – darray of coordinates
size (Tuple[int, int]) – Tuple of the desired shape (width, height)
dst (dolphin.darray, optional) – Destination darray for faster execution, defaults to None

Returns:

darray of cropped and resized images

Return type:

dolphin.darray

crop_and_resize_padding(coordinates: darray, size: Tuple[int, int], padding: Union[int, float] = 127, dst: Optional[darray] = None) → darray[source]

This method is well performing for cropping and resizing images using padded resize. The use case would be to process a batch of images which would be the crops of a bigger image. The coordinates of the crops would, for instance, be the output of a detection model.

In terms of usability, the coordinates are expected to be in the following format: [[x1, y1, x2, y2], …] where x1, y1, x2, y2 are the absolute coordinates of the top left and bottom right corners of the crop in the original image.

Coordinates would thus be a dolphin.darray of shape (n, 4) where n is the number of crops, n >= 1.

Also, for faster execution, the destination darray is expected to be preallocated and passed as an argument to the function.

Parameters:

coordinates (dolphin.darray) – darray of coordinates
size (Tuple[int, int]) – Tuple of the desired shape (width, height)
dst (dolphin.darray, optional) – Destination darray for faster execution, defaults to None

Returns:

darray of cropped and resized images

Return type:

dolphin.darray

normalize(normalize_type: dimage_normalize_type = dimage_normalize_type.DOLPHIN_255, mean: Optional[List[Union[int, float]]] = None, std: Optional[List[Union[int, float]]] = None, dtype: dtype = dtype.float32, dst: Optional[dimage] = None) → dimage[source]

Normalize the image

This function is a function to efficiently normalize an image in different manners.

The mean and std values must be passed as a list of values if you want to normalize the image using the dolphin.dimage_normalize_type.DOLPHIN_MEAN_STD normalization type. To use this function efficiently, the destination image must be preallocated and passed as an argument to the function:

src = dimage(shape=(100, 100, 3), dtype=dolphin.dtype.uint8)
dst = dimage(shape=(100, 100, 3), dtype=dolphin.dtype.float32)
src.normalize(dimage_normalize_type.DOLPHIN_MEAN_STD,
              mean=[0.5, 0.5, 0.5],
              std=[0.5, 0.5, 0.5], dst=dst)

or:

src = dimage(shape=(100, 100, 3), dtype=dolphin.dtype.uint8)
dst = dimage(shape=(100, 100, 3), dtype=dolphin.dtype.float32)
src.normalize(dimage_normalize_type.DOLPHIN_255, dst=dst)

Parameters:

normalize_type (dimage_normalize_type) – The type of normalization
mean (List[Union[int, float]]) – The mean values
std (List[Union[int, float]]) – The std values
dst (dimage) – The destination image

cvtColor(color_format: dimage_channel_format, dst: Optional[dimage] = None) → dimage[source]

Transforms the image to the specified color format.

This function transforms the image to the specified color format. The supported color formats are:

- dolphin.dimage_channel_format.DOLPHIN_RGB
- dolphin.dimage_channel_format.DOLPHIN_BGR
- dolphin.dimage_channel_format.DOLPHIN_GRAY_SCALE

Parameters:

color_format (dimage_channel_format) – The color format of the output image
dst (dimage) – The destination image

transpose(*axes: int) → dimage[source]

Transpose the image.

This function transposes the image. The axes are specified as a sequence of axis numbers.

To be used efficiently, the destination image must be provided and must have the same shape as the source image:

src = dimage(shape=(2, 3, 4), dtype=np.float32)
dst = dimage(shape=(4, 3, 2), dtype=np.float32)
src.transpose(2, 1, 0)

Parameters:: axes (*int) – The permutation of the axes
Returns:: The transposed image
Return type:: dimage

dimage Enumerations

class dolphin.dimage_dim_format(value)[source]

Bases: Enum

Image dimension format.

DOLPHIN_CHW: int = 0

DOLPHIN_HWC: int = 1

DOLPHIN_HW: int = 2

class dolphin.dimage_channel_format(value)[source]

Bases: Enum

Image channel format.

DOLPHIN_RGB: int = 0

DOLPHIN_BGR: int = 1

DOLPHIN_GRAY_SCALE: int = 2

class dolphin.dimage_resize_type(value)[source]

Bases: Enum

Image resize type.

DOLPHIN_NEAREST stands for nearest neighbor interpolation resize. Its equivalent in opencv is INTER_NEAREST:

cv2.resize(src, (width, height), interpolation=cv2.INTER_NEAREST)

DOLPHIN_PADDED stands for padded nearest neighbor interpolation resize. Its equivalent can be found here. # noqa

DOLPHIN_NEAREST: int = 0

DOLPHIN_PADDED: int = 1

class dolphin.dimage_normalize_type(value)[source]

Bases: Enum

Image normalize type.

DOLPHIN_MEAN_STD stands for normalization by mean and std. Which is:

image = (image - mean) / std

DOLPHIN_255 stands for normalization by 255. Which is:

image = image / 255.0

DOLPHIN_TF stands for tensorflow normalization. Which is:

image = image / 127.5 - 1.0

DOLPHIN_MEAN_STD: int = 0

DOLPHIN_255: int = 1

DOLPHIN_TF: int = 2

Built-in functions

dolphin.resize_padding(src: dimage, shape: Tuple[int, ...], padding_value: Union[int, float] = 127, dst: Optional[dimage] = None) → Tuple[dimage, float, Tuple[float, float]][source]

Padded resize the image

This function resizes the image to a new shape with padding. It means that the image is resized to the new shape and the remaining pixels are filled with the padding value (127 by default).

If for instance the image is resized from (50, 100) to (200, 200), the aspect ratio of the image is preserved and the image is resized to (100, 200). The remaining pixels are filled with the padding value. In this scenario, the padding would appear on the left and right side of the image, with a width of 50 pixels.

In order to use this function in an efficient way, the destination image must be preallocated and passed as an argument to the function:

src = dimage(shape=(100, 100, 3), dtype=dolphin.dtype.uint8)
dst = dimage(shape=(200, 200, 3), dtype=dolphin.dtype.uint8)
src.resize_padding((200, 200), dst)

If aspect ratio does not matter, the function resize() can be used.

Parameters:

shape (Tuple[int, ...]) – The new shape of the image
dst (dimage) – The destination image
padding_value (int or float) – The padding value

dolphin.resize(src: dimage, shape: Tuple[int, ...], dst: Optional[dimage] = None) → dimage[source]

Resize the image

This function performs a naive resize of the image. The resize type is for now only dolphin.dimage_resize_type.DOLPHIN_NEAREST. In order to use this function in an efficient way, the destination image must be preallocated and passed as an argument to the function:

src = dimage(shape=(100, 100, 3), dtype=dolphin.dtype.uint8)
dst = dimage(shape=(200, 200, 3), dtype=dolphin.dtype.float32)
dolphin.resize(src, (200, 200), dst)

The returned resized image aspect ratio might change as the new shape is not necessarily a multiple of the original shape.

If aspect ratio of the orginal image matters to you, use resize_padding() instead:

src = dimage(shape=(100, 100, 3), dtype=dolphin.dtype.uint8)
dst = dimage(shape=(200, 200, 3), dtype=dolphin.dtype.float32)
dolphin.resize_padding(src, (200, 200), dst)

Parameters:

shape (Tuple[int, ...]) – The new shape of the image
dst (dimage) – The destination image

dolphin.normalize(src: dimage, normalize_type: dimage_normalize_type, mean: Optional[List[Union[int, float]]] = None, std: Optional[List[Union[int, float]]] = None, dtype: Optional[dtype] = None, dst: Optional[dimage] = None) → None[source]

Normalize the image

This function is a wrapper for the normalize function of the dimage class. The mean and std values must be passed as a list of values if you want to normalize the image using the dolphin.dimage_normalize_type.DOLPHIN_MEAN_STD normalization type. To use this function efficiently, the destination image must be preallocated and passed as an argument to the function:

src = dimage(shape=(100, 100, 3), dtype=dolphin.dtype.uint8)
dst = dimage(shape=(100, 100, 3), dtype=dolphin.dtype.float32)
normalize(src,
          dimage_normalize_type.DOLPHIN_MEAN_STD,
          mean=[0.5, 0.5, 0.5],
          std=[0.5, 0.5, 0.5], dst=dst)

or:

src = dimage(shape=(100, 100, 3), dtype=dolphin.dtype.uint8)
dst = dimage(shape=(100, 100, 3), dtype=dolphin.dtype.float32)
normalize(src, dimage_normalize_type.DOLPHIN_255, dst=dst)

Parameters:

src (dimage) – Source image
normalize_type (dimage_normalize_type) – The type of normalization
mean (List[Union[int, float]]) – The mean values
std (List[Union[int, float]]) – The std values
dst (dimage) – The destination image

dolphin.cvtColor(src: dimage, color_format: dimage_channel_format, dst: Optional[dimage] = None) → None[source]

Transforms the image to the specified color format.

This function is a wrapper for the cvtColor function of the dimage class.

This function transforms the image to the specified color format. The supported color formats are:

- dolphin.dimage_channel_format.DOLPHIN_RGB
- dolphin.dimage_channel_format.DOLPHIN_BGR
- dolphin.dimage_channel_format.DOLPHIN_GRAY_SCALE

Parameters:

color_format (dimage_channel_format) – The color format of the output image
dst (dimage) – The destination image