computer_vision.haralick_descriptors
====================================

.. py:module:: computer_vision.haralick_descriptors

.. autoapi-nested-parse::

   https://en.wikipedia.org/wiki/Image_texture
   https://en.wikipedia.org/wiki/Co-occurrence_matrix#Application_to_image_analysis



Attributes
----------

.. autoapisummary::

   computer_vision.haralick_descriptors.index


Functions
---------

.. autoapisummary::

   computer_vision.haralick_descriptors.binarize
   computer_vision.haralick_descriptors.binary_mask
   computer_vision.haralick_descriptors.closing_filter
   computer_vision.haralick_descriptors.euclidean
   computer_vision.haralick_descriptors.get_descriptors
   computer_vision.haralick_descriptors.get_distances
   computer_vision.haralick_descriptors.grayscale
   computer_vision.haralick_descriptors.haralick_descriptors
   computer_vision.haralick_descriptors.matrix_concurrency
   computer_vision.haralick_descriptors.normalize_array
   computer_vision.haralick_descriptors.normalize_image
   computer_vision.haralick_descriptors.opening_filter
   computer_vision.haralick_descriptors.root_mean_square_error
   computer_vision.haralick_descriptors.transform


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

.. py:function:: binarize(image: numpy.ndarray, threshold: float = 127.0) -> numpy.ndarray

   Binarizes a grayscale image based on a given threshold value,
   setting values to 1 or 0 accordingly.

   Examples:
       >>> binarize(np.array([[128, 255], [101, 156]]))
       array([[1, 1],
              [0, 1]])
       >>> binarize(np.array([[0.07, 1], [0.51, 0.3]]), threshold=0.5)
       array([[0, 1],
              [1, 0]])


.. py:function:: binary_mask(image_gray: numpy.ndarray, image_map: numpy.ndarray) -> tuple[numpy.ndarray, numpy.ndarray]

   Apply binary mask, or thresholding based
   on bit mask value (mapping mask is binary).

   Returns the mapped true value mask and its complementary false value mask.

   Example:
       >>> img = np.array([[[108, 201, 72], [255, 11,  127]],
       ...                 [[56,  56,  56], [128, 255, 107]]])
       >>> gray = grayscale(img)
       >>> binary = binarize(gray)
       >>> morphological = opening_filter(binary)
       >>> binary_mask(gray, morphological)
       (array([[1, 1],
              [1, 1]], dtype=uint8), array([[158,  97],
              [ 56, 200]], dtype=uint8))


.. py:function:: closing_filter(image: numpy.ndarray, kernel: numpy.ndarray | None = None) -> numpy.ndarray

   Opening filter, defined as the sequence of
   dilation and then erosion filter on the same image.

   Examples:
       >>> img = np.array([[1, 0.5], [0.2, 0.7]])
       >>> img = binarize(img, threshold=0.5)
       >>> closing_filter(img)
       array([[0, 0],
              [0, 0]], dtype=uint8)


.. py:function:: euclidean(point_1: numpy.ndarray, point_2: numpy.ndarray) -> float

   Simple method for calculating the euclidean distance between two points,
   with type np.ndarray.

   Example:
       >>> a = np.array([1, 0, -2])
       >>> b = np.array([2, -1, 1])
       >>> euclidean(a, b)
       3.3166247903554


.. py:function:: get_descriptors(masks: tuple[numpy.ndarray, numpy.ndarray], coordinate: tuple[int, int]) -> numpy.ndarray

   Calculate all Haralick descriptors for a sequence of
   different co-occurrence matrices, given input masks and coordinates.

   Example:
       >>> img = np.array([[[108, 201, 72], [255, 11,  127]],
       ...                 [[56,  56,  56], [128, 255, 107]]])
       >>> gray = grayscale(img)
       >>> binary = binarize(gray)
       >>> morphological = opening_filter(binary)
       >>> get_descriptors(binary_mask(gray, morphological), (0, 1))
       array([0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0.])


.. py:function:: get_distances(descriptors: numpy.ndarray, base: int) -> list[tuple[int, float]]

   Calculate all Euclidean distances between a selected base descriptor
   and all other Haralick descriptors
   The resulting comparison is return in decreasing order,
   showing which descriptor is the most similar to the selected base.

   Args:
       descriptors: Haralick descriptors to compare with base index
       base: Haralick descriptor index to use as base when calculating respective
       euclidean distance to other descriptors.

   Returns:
       Ordered distances between descriptors

   Example:
       >>> index = 1
       >>> img = np.array([[[108, 201, 72], [255, 11,  127]],
       ...                 [[56,  56,  56], [128, 255, 107]]])
       >>> gray = grayscale(img)
       >>> binary = binarize(gray)
       >>> morphological = opening_filter(binary)
       >>> get_distances(get_descriptors(
       ...                 binary_mask(gray, morphological), (0, 1)),
       ...               index)
       [(0, 0.0), (1, 0.0), (2, 0.0), (3, 0.0), (4, 0.0), (5, 0.0), (6, 0.0), (7, 0.0), (8, 0.0), (9, 0.0), (10, 0.0), (11, 0.0), (12, 0.0), (13, 0.0), (14, 0.0), (15, 0.0)]


.. py:function:: grayscale(image: numpy.ndarray) -> numpy.ndarray

   Uses luminance weights to transform RGB channel to greyscale, by
   taking the dot product between the channel and the weights.

   Example:
       >>> grayscale(np.array([[[108, 201, 72], [255, 11,  127]],
       ...                     [[56,  56,  56], [128, 255, 107]]]))
       array([[158,  97],
              [ 56, 200]], dtype=uint8)


.. py:function:: haralick_descriptors(matrix: numpy.ndarray) -> list[float]

   Calculates all 8 Haralick descriptors based on co-occurrence input matrix.
   All descriptors are as follows:
   Maximum probability, Inverse Difference, Homogeneity, Entropy,
   Energy, Dissimilarity, Contrast and Correlation

   Args:
       matrix: Co-occurrence matrix to use as base for calculating descriptors.

   Returns:
       Reverse ordered list of resulting descriptors

   Example:
       >>> img = np.array([[[108, 201, 72], [255, 11,  127]],
       ...                 [[56,  56,  56], [128, 255, 107]]])
       >>> gray = grayscale(img)
       >>> binary = binarize(gray)
       >>> morphological = opening_filter(binary)
       >>> mask_1 = binary_mask(gray, morphological)[0]
       >>> concurrency = matrix_concurrency(mask_1, (0, 1))
       >>> [float(f) for f in haralick_descriptors(concurrency)]
       [0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0]


.. py:function:: matrix_concurrency(image: numpy.ndarray, coordinate: tuple[int, int]) -> numpy.ndarray

   Calculate sample co-occurrence matrix based on input image
   as well as selected coordinates on image.

   Implementation is made using basic iteration,
   as function to be performed (np.max) is non-linear and therefore
   not callable on the frequency domain.

   Example:
       >>> img = np.array([[[108, 201, 72], [255, 11,  127]],
       ...                 [[56,  56,  56], [128, 255, 107]]])
       >>> gray = grayscale(img)
       >>> binary = binarize(gray)
       >>> morphological = opening_filter(binary)
       >>> mask_1 = binary_mask(gray, morphological)[0]
       >>> matrix_concurrency(mask_1, (0, 1))
       array([[0., 0.],
              [0., 0.]])


.. py:function:: normalize_array(array: numpy.ndarray, cap: float = 1) -> numpy.ndarray

   Normalizes a 1D array, between ranges 0-cap.

   Args:
       array: List containing values to be normalized between cap range.
       cap: Maximum cap amount for normalization.
   Returns:
       return 1D numpy array, corresponding to limited range array

   Examples:
       >>> normalize_array(np.array([2, 3, 5, 7]))
       array([0. , 0.2, 0.6, 1. ])
       >>> normalize_array(np.array([[5], [7], [11], [13]]))
       array([[0.  ],
              [0.25],
              [0.75],
              [1.  ]])


.. py:function:: normalize_image(image: numpy.ndarray, cap: float = 255.0, data_type: numpy.dtype = np.uint8) -> numpy.ndarray

   Normalizes image in Numpy 2D array format, between ranges 0-cap,
   as to fit uint8 type.

   Args:
       image: 2D numpy array representing image as matrix, with values in any range
       cap: Maximum cap amount for normalization
       data_type: numpy data type to set output variable to
   Returns:
       return 2D numpy array of type uint8, corresponding to limited range matrix

   Examples:
       >>> normalize_image(np.array([[1, 2, 3], [4, 5, 10]]),
       ...                 cap=1.0, data_type=np.float64)
       array([[0.        , 0.11111111, 0.22222222],
              [0.33333333, 0.44444444, 1.        ]])
       >>> normalize_image(np.array([[4, 4, 3], [1, 7, 2]]))
       array([[127, 127,  85],
              [  0, 255,  42]], dtype=uint8)


.. py:function:: opening_filter(image: numpy.ndarray, kernel: numpy.ndarray | None = None) -> numpy.ndarray

   Opening filter, defined as the sequence of
   erosion and then a dilation filter on the same image.

   Examples:
       >>> img = np.array([[1, 0.5], [0.2, 0.7]])
       >>> img = binarize(img, threshold=0.5)
       >>> opening_filter(img)
       array([[1, 1],
              [1, 1]], dtype=uint8)


.. py:function:: root_mean_square_error(original: numpy.ndarray, reference: numpy.ndarray) -> float

   Simple implementation of Root Mean Squared Error
   for two N dimensional numpy arrays.

   Examples:
       >>> root_mean_square_error(np.array([1, 2, 3]), np.array([1, 2, 3]))
       0.0
       >>> root_mean_square_error(np.array([1, 2, 3]), np.array([2, 2, 2]))
       0.816496580927726
       >>> root_mean_square_error(np.array([1, 2, 3]), np.array([6, 4, 2]))
       3.1622776601683795


.. py:function:: transform(image: numpy.ndarray, kind: str, kernel: numpy.ndarray | None = None) -> numpy.ndarray

   Simple image transformation using one of two available filter functions:
   Erosion and Dilation.

   Args:
       image: binarized input image, onto which to apply transformation
       kind: Can be either 'erosion', in which case the :func:np.max
             function is called, or 'dilation', when :func:np.min is used instead.
       kernel: n x n kernel with shape < :attr:image.shape,
             to be used when applying convolution to original image

   Returns:
       returns a numpy array with same shape as input image,
       corresponding to applied binary transformation.

   Examples:
       >>> img = np.array([[1, 0.5], [0.2, 0.7]])
       >>> img = binarize(img, threshold=0.5)
       >>> transform(img, 'erosion')
       array([[1, 1],
              [1, 1]], dtype=uint8)
       >>> transform(img, 'dilation')
       array([[0, 0],
              [0, 0]], dtype=uint8)


.. py:data:: index