sharpedge.modulate_image

Functions

_mode_conversion(img, mode)

Private function to be invoked by modulate_image().

_channel_swap(img, ch_swap)

Private function to be invoked by modulate_image().

_channel_extract(img, ch_extract)

Private function to be invoked by modulate_image().

modulate_image(img[, mode, ch_swap, ch_extract])

Convert or manipulate image color channels with flexibility for grayscale and RGB.

Module Contents

sharpedge.modulate_image._mode_conversion(img, mode)[source]

Private function to be invoked by modulate_image().

Validate the mode and perform mode conversion (grayscale ↔ RGB or ‘as-is’).

This function checks whether the requested mode is valid, and if so, converts the image to either grayscale or RGB. If ‘as-is’ is specified, the image is returned without changes.

Parameters:

  • img (numpy.ndarray) – Input image array. This can be either a 2D numpy array (grayscale) or a 3D numpy array (RGB).

  • mode (str) – The desired target color scale. It can be one of the following: - ‘as-is’: No conversion needed - ‘gray’: Convert the image to grayscale. - ‘rgb’: Convert the image to RGB.

Returns:

The processed image, which could be either in grayscale (2D) or RGB (3D).

Return type:

numpy.ndarray

Raises:

ValueError – If an invalid mode is provided.

sharpedge.modulate_image._channel_swap(img, ch_swap)[source]

Private function to be invoked by modulate_image().

Perform channel swapping on the RGB image.

This function swaps the RGB channels according to the specified order in ch_swap.

Parameters:

  • img (numpy.ndarray) – Input image array in RGB format (3D array).

  • ch_swap (list/tuple of int) – A list or tuple of three integers representing the new order of the RGB channels. For example: - [0, 1, 2] or (0, 1, 2) keeps the channels in their original order (Red, Green, Blue). - [2, 1, 0] or (2, 1, 0) swaps the Red and Blue channels.

Returns:

The image with channels swapped as per the ch_swap order.

Return type:

numpy.ndarray

Raises:

  • TypeError – If ch_swap is not a list or tuple, or if the elements are not integers.

  • ValueError – If ch_swap does not contain exactly three valid channel indices (0, 1, 2), or if the indices are duplicates.

sharpedge.modulate_image._channel_extract(img, ch_extract)[source]

Private function to be invoked by modulate_image().

Perform channel extraction on the RGB image.

This function extracts the specified RGB channels and sets the unselected channels to 0.

Parameters:

  • img (numpy.ndarray) – Input image array in RGB format (3D array).

  • ch_extract (list/tuple of int) – A list or tuple of integers representing the indices of the RGB channels to extract. For example: - [0] or (0) extracts only the Red channel. - [1, 2] or (1, 2) extracts the Green and Blue channels.

Returns:

The image with only the extracted channels present, and the other channels set to 0.

Return type:

numpy.ndarray

Raises:

  • TypeError – If ch_extract is not a list or tuple, or if the elements are not integers.

  • ValueError – If ch_extract contains invalid channel indices or exceeds the maximum length of 2.

sharpedge.modulate_image.modulate_image(img, mode='as-is', ch_swap=None, ch_extract=None)[source]

Convert or manipulate image color channels with flexibility for grayscale and RGB.

This function allows you to perform various color transformations on an image, including: - Converting between grayscale and RGB formats. - Swapping RGB channels to rearrange the color channels. - Extracting specific RGB channels (e.g., Red, Green, or Blue).

It supports both grayscale (2D) and RGB (3D) images. If a grayscale image is provided, channel swapping or extraction will not be applicable, and a notification will be given.

If the input image is already in the target mode (e.g., ‘gray’ or ‘rgb’), the function will notify that no conversion is necessary and return the original image.

Parameters:

  • img (numpy.ndarray) – Input image array. This can be either a 2D numpy array (grayscale image) or a 3D numpy array (RGB image). The dimensions of the image should be (height, width) for grayscale or (height, width, 3) for RGB images.

  • mode (str, optional) –

    The desired target color scale. This can one of the three: - ‘as-is’: No conversion needed - ‘gray’: Convert the image to grayscale. - ‘rgb’: Convert the image to RGB. Default is ‘as-is’.

    If the input image is already in the target mode, a notification will be printed, and the function will return the input image as-is without any conversion.

  • ch_swap (list/tuple of int, optional) –

    A list or tuple of integers representing the new order of the RGB channels. The list should contain exactly three elements, each of which is an index corresponding to the RGB channels: - [0, 1, 2] or (0, 1, 2) will keep the channels in their original order (Red, Green, Blue). - [2, 1, 0] or (2, 1, 0) will swap Red and Blue channels.

    If None, no channel swapping occurs. Default is None.

  • ch_extract (list/tuple of int, optional) –

    A list or tuple of integers representing the indices of the RGB channels to extract. For example: - [0] or (0): Extract only the Red channel. - [1, 2] or (1, 2): Extract the Green and Blue channels. - [2, 0] or (2, 0): Extract the Blue and Red channels.

    If None, no channel extraction occurs. Default is None.

Returns:

A numpy array representing the manipulated image. The output could be: - A grayscale image (2D array). - An RGB image (3D array). - A subset of RGB channels as a 3D image, where unextracted channels are set to 0. - A rearranged RGB image with swapped channels.

Return type:

numpy.ndarray

Raises:

ValueError – If the input image is not in grayscale or RGB format, or if any invalid channel indices are provided for extraction or swapping.

Notes

  • Grayscale images (2D arrays) do not have multiple color channels, so channel extraction or swapping will not be possible. These operations will be skipped with a corresponding notification.

  • If no operations are specified (i.e., no conversion or channel manipulation), the function will return the original image.

  • If the input image is already in the target mode (e.g., ‘gray’ or ‘rgb’), the function will notify that no conversion is necessary and return the image as-is.

Examples

>>> grayscale_image = modulate_image(rgb_image, mode='gray')  # Convert an RGB image to grayscale
>>> rgb_image_again = modulate_image(grayscale_image, mode='rgb')  # Convert a grayscale image back to RGB
>>> red_channel = modulate_image(rgb_image, ch_extract=[0])  # Extract the Red channel from an RGB image
>>> red_green_channels = modulate_image(rgb_image, ch_extract=[0, 1])  # Extract the Red and Green channels from an RGB image
>>> swapped_image = modulate_image(rgb_image, ch_swap=(2, 0, 1))  # Swap the Red and Blue channels in an RGB image