sharpedge.seam_carving
======================

.. py:module:: sharpedge.seam_carving


Functions
---------

.. autoapisummary::

   sharpedge.seam_carving._energy
   sharpedge.seam_carving._find_vertical_seam
   sharpedge.seam_carving._find_horizontal_seam
   sharpedge.seam_carving._remove_vertical_seam
   sharpedge.seam_carving._remove_horizontal_seam
   sharpedge.seam_carving.seam_carve


Module Contents
---------------

.. py:function:: _energy(img)

   Computes the energy map of an image.

   This function calculates the energy of each pixel. The
   energy map highlights areas with high contrast, which
   are less likely to be removed during seam carving.
   Private function to be invoked by seam_carve().

   :param img: A color image represented as a 3D numpy array of shape (height, width, 3).
   :type img: numpy.ndarray

   :returns: A 2D array of shape (height, width) containing the energy values
             for each pixel in the original image.
   :rtype: numpy.ndarray

   :raises ValueError: If the input image is not a 3D numpy array with 3 channels.

   .. rubric:: Examples

   >>> img = np.random.rand(8, 5, 3)
   >>> e = _energy(img)
   >>> print(e.shape)
   (8, 5)


.. py:function:: _find_vertical_seam(energy)

   Find the vertical seam of lowest total energy in the image.
   Private function to be invoked by seam_carve().

   :param energy: A 2D array representing the energy of each pixel.
   :type energy: numpy.ndarray

   :returns: A list indicating the seam of column indices.
   :rtype: list

   :raises ValueError: If the energy map is not a 2D numpy array.

   .. rubric:: Examples

   >>> e = np.array([[0.6625, 0.3939], [1.0069, 0.7383]])
   >>> seam = _find_vertical_seam(e)
   >>> print(seam)
   [1, 1]


.. py:function:: _find_horizontal_seam(energy)

   Find the horizontal seam of lowest total energy
   in the image by transposing the energy map.
   Private function to be invoked by seam_carve().

   :param energy: A 2D array representing the energy of each pixel.
   :type energy: numpy.ndarray

   :returns: A list indicating the seam of row indices.
   :rtype: list

   :raises ValueError: If the energy map is not a 2D numpy array.

   .. rubric:: Examples

   >>> e = np.array([[0.6625, 0.3939], [1.0069, 0.7383]])
   >>> seam = _find_horizontal_seam(e)
   >>> print(seam)
   [0, 0]


.. py:function:: _remove_vertical_seam(img, seam)

   Remove a vertical seam from an image.
   Private function to be invoked by seam_carve().

   :param img: A 3D array representing the original image (height, width, 3).
   :type img: numpy.ndarray
   :param seam: A 1D array (or list) of column indices indicating
                which pixel to remove in each row.
   :type seam: numpy.ndarray

   :returns: A new image with one less column, of shape (height, width - 1, 3).
   :rtype: numpy.ndarray

   :raises ValueError: - If the input img is not a 3D numpy array with 3 channels.
       - If the input seam is not a 1D array or a list.
       - If the length of the seam does not match the height of the image.

   .. rubric:: Examples

   >>> img = np.random.rand(8, 5, 3)
   >>> seam = [2, 1, 3, 2, 0, 1, 4, 3]
   >>> new_img = _remove_vertical_seam(img, seam)
   >>> print(new_img.shape)
   (8, 4, 3)


.. py:function:: _remove_horizontal_seam(img, seam)

   Remove a horizontal seam from an image.
   Private function to be invoked by seam_carve().

   :param img: A 3D array representing the original image (height, width, 3).
   :type img: numpy.ndarray
   :param seam: A 1D array (or list) of row indices indicating
                which pixel to remove in each column.
   :type seam: numpy.ndarray

   :returns: A new image with one less row, of shape (height - 1, width, 3).
   :rtype: numpy.ndarray

   :raises ValueError: - If the input img is not a 3D numpy array with 3 channels.
       - If the input seam is not a 1D array or a list.
       - If the length of the seam does not match the width of the image.

   .. rubric:: Examples

   >>> img = np.random.rand(5, 8, 3)
   >>> seam = [2, 1, 3, 2, 0, 1, 4, 3]
   >>> new_img = _remove_horizontal_seam(img, seam)
   >>> print(new_img.shape)
   (4, 8, 3)


.. 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)