sharpedge.pca_compression
=========================

.. py:module:: sharpedge.pca_compression


Functions
---------

.. autoapisummary::

   sharpedge.pca_compression.pca_compression


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

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