sharpedge ========= .. py:module:: sharpedge Submodules ---------- .. toctree:: :maxdepth: 1 /autoapi/sharpedge/frame_image/index /autoapi/sharpedge/modulate_image/index /autoapi/sharpedge/pca_compression/index /autoapi/sharpedge/pooling_image/index /autoapi/sharpedge/reposition_image/index /autoapi/sharpedge/seam_carving/index Attributes ---------- .. autoapisummary:: sharpedge.__version__ Functions --------- .. autoapisummary:: sharpedge.reposition_image sharpedge.frame_image sharpedge.modulate_image sharpedge.pooling_image sharpedge.pca_compression sharpedge.seam_carve Package Contents ---------------- .. py:data:: __version__ .. py:function:: reposition_image(img, flip='none', rotate='up', shift_x=0, shift_y=0) Flip, rotate, and shift an image based on the specified requested action. This function allows repositioning of an image by applying one or more transformations (flipping, rotating, and shifting). Each transformation can be controlled by the respective parameters. :param img: The input image as a 2D numpy array (grayscale) or 3D numpy array (RGB). :type img: numpy.ndarray :param flip: Argument used to flip the image. It can be - 'none': No flipping. - 'horizontal': Flip the image horizontally. - 'vertical': Flip the image vertically. - 'both': Flip the image both horizontally and vertically. Default is 'none'. :type flip: str, optional :param rotate: Argument used to rotate the image. It can be - 'up': No rotation. - 'left': Rotate the image 90 degrees counter-clockwise. - 'right': Rotate the image 90 degrees clockwise. - 'down': Rotate the image 180 degrees (flip upside down). Default is 'up'. :type rotate: str, optional :param shift_x: Argument used to shift the image along the x-axis. Default is 0. :type shift_x: int, optional :param shift_y: Argument used to shift the image along the y-axis. Default is 0. :type shift_y: int, optional :returns: The repositioned image that has been flipped, rotated, and/or shifted based on the parameter values. :rtype: numpy.ndarray :raises ValueError: - If the input image is not a 2D or 3D numpy array. - or if the `flip` or `rotate` arguments are invalid. :raises TypeError: If `shift_x` or `shift_y` is not an integer. .. warning:: UserWarning - If the shift values are larger than the image dimensions. - If resizing causes unexpected behavior due to large shifts. .. rubric:: Examples >>> img = np.random.rand(100, 100) >>> repositioned_img = reposition_image(img, flip='horizontal', rotate='left', shift_x=10, shift_y=20) For an RGB image: >>> img_rgb = np.random.rand(100, 100, 3) >>> repositioned_img = reposition_image(img_rgb, flip='both', rotate='down', shift_x=-5, shift_y=10) .. py:function:: frame_image(img, h_border=20, w_border=20, inside=False, color=0) Add a decorative frame around the image with a customizable color. This function adds a border around the input image, either inside the image (preserving its original size) or outside (increasing its size). The border color can be specified for both grayscale and RGB images. :param img: The input image as a 2D numpy array (grayscale) or 3D numpy array (RGB). :type img: ndarray :param h_border: The height of the border in pixels. Default is 20. :type h_border: int, optional :param w_border: The width of the border in pixels. Default is 20. :type w_border: int, optional :param inside: If True, the border is added **inside** the image (maintaining the image size). If False, the border is added **outside** the image (increasing the image size). Default is False. :type inside: bool, optional :param color: The color of the border. Can be: - A single value for grayscale frames (e.g., 0 for black, 255 for white). - A tuple of 3 values for RGB frames (e.g., (0, 0, 0) for black). Default is 0 (black) for grayscale frames. :type color: int or tuple of int, optional :returns: The framed image with the applied border. :rtype: ndarray .. rubric:: Examples >>> img = np.random.rand(100, 100) >>> framed_img = frame_image(img, h_border=30, w_border=30, inside=True, color=255) >>> framed_img_rgb = frame_image(img_rgb, h_border=20, w_border=20, inside=False, color=(255, 0, 0)) .. py:function:: modulate_image(img, mode='as-is', ch_swap=None, ch_extract=None) 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. :param img: 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. :type img: numpy.ndarray :param mode: 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. :type mode: str, optional :param ch_swap: 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`. :type ch_swap: list/tuple of int, optional :param ch_extract: 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`. :type ch_extract: list/tuple of int, optional :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. :rtype: 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. .. rubric:: 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. .. rubric:: 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 .. py:function:: pooling_image(img, window_size, pooling_method=np.mean) Perform pooling on an image using a specified window size and pooling function. :param img: The input image as a 2D numpy array (grayscale) or 3D numpy array (RGB). :type img: numpy.ndarray :param window_size: The size of the pooling window (e.g., 10 for 10x10 windows). :type window_size: int :param pooling_method: The pooling function to apply to each window. Common options include `numpy.mean`, `numpy.median`, `numpy.max`, and `numpy.min`. Default is `numpy.mean`. :type pooling_method: callable, optional :returns: The resized image, reduced by the pooling operation based on the specified window size and pooling function. For grayscale images, the result is a 2D array. For RGB images, the result is a 3D array normalized to the range [0.0, 1.0]. :rtype: numpy.ndarray :raises TypeError: If `window_size` is not an integer or `pooling_method` is not callable. :raises ValueError: If the image dimensions are not divisible by the window size. .. rubric:: Examples >>> img = np.random.rand(100, 100) >>> pooled_img = pooling_image(img, window_size=10, pooling_method=np.mean) For an RGB image: >>> img_rgb = np.random.rand(100, 100, 3) >>> pooled_img = pooling_image(img_rgb, window_size=20, pooling_method=np.max) .. py:function:: pca_compression(img, preservation_rate=0.9) Compress the input image using Principal Component Analysis (PCA) via the Singular Value Decomposition (SVD) method. This function first applies SVD to decompose the image array into its principal components, and then retains a specified portion of the eigenvectors based on the preservation rate. The output is the compressed image in 2D array. This function supports only grayscale (2D) images. :param img: Input image array. This needs to be a 2D numpy array (grayscale image). :type img: numpy.ndarray :param preservation_rate: The proportion of eigen values to preserve in the compressed image. Must be a value between 0 and 1. Higher values preserve more details from the original image, while lower values result in greater compression. Default is 0.9. :type preservation_rate: float, optional :returns: A numpy array representing the manipulated image. The output would be: - A grayscale image (2D array). :rtype: numpy.ndarray :raises TypeError: If `preservation_rate` is not a float. :raises ValueError: If the input image is not valid (not a 2D array). If `preservation_rate` is not between 0 and 1. :raises Warning: If `preservation_rate` is very low (< 0.1), as it may result in significant quality loss. .. rubric:: Examples Compress a grayscale image by retaining 80% of the variance: >>> compressed_img = pca_compression(img, preservation_rate=0.8) Compress an RGB image with the default preservation rate (90%): >>> compressed_img = pca_compression(img) .. py:function:: seam_carve(img, target_height, target_width) Seam carve an image to resize it to the target dimensions. :param img: A 3D array representing the original image (height, width, 3). :type img: numpy.ndarray :param target_height: The desired height of the resized image. :type target_height: int :param target_width: The desired width of the resized image. :type target_width: int :returns: The resized image with dimensions (target_height, target_width, 3). :rtype: numpy.ndarray :raises ValueError: - If the input img is not a 3D numpy array with 3 channels. - If target_height or target_width is not an integer. - If target_height is greater than the original height or less than 1. - If target_width is greater than the original width or less than 1. .. warning:: UserWarning - If the target size is the same as the original size (no resizing needed). - If only one dimension is resized (height or width remains the same). - If the original image or target size is reduced to a single pixel. - If the resizing is significant (difference of 200+ pixels), which may cause long processing times. .. rubric:: Examples >>> img = np.random.rand(5, 5, 3) >>> resized_img = seam_carve(img, 3, 3) >>> print(resized_img.shape) (3, 3, 3)