# Documentation — IPFML v0.2.5 documentation

# Documentation

## ipfml.metrics

`ipfml.metrics.``get_LAB`(image)

  Transforms RGB Image into Lab

  Parameters: | image – image to convert
  Returns: | Lab information

  Usage:

      >>> from PIL import Image
      >>> from ipfml import metrics
      >>> img = Image.open('./images/test_img.png')
      >>> Lab = metrics.get_LAB(img)
      >>> Lab.shape
      (200, 200, 3)

`ipfml.metrics.``get_LAB_L`(image)

  Transforms RGB Image into Lab and returns L

  Parameters: | image – image to convert
  Returns: | The L chanel from Lab information

      >>> from PIL import Image
      >>> from ipfml import metrics
      >>> img = Image.open('./images/test_img.png')
      >>> L = metrics.get_LAB_L(img)
      >>> L.shape
      (200, 200)

`ipfml.metrics.``get_LAB_a`(image)

  Transforms RGB Image into LAB and returns a

  Parameters: | image – image to convert
  Returns: | The a chanel from Lab information

  Usage:

      >>> from PIL import Image
      >>> from ipfml import metrics
      >>> img = Image.open('./images/test_img.png')
      >>> a = metrics.get_LAB_a(img)
      >>> a.shape
      (200, 200)

`ipfml.metrics.``get_LAB_b`(image)

  Transforms RGB Image into LAB and returns b

  Parameters: | image – image to convert
  Returns: | The b chanel from Lab information

  Usage :

      >>> from PIL import Image
      >>> from ipfml import metrics
      >>> img = Image.open('./images/test_img.png')
      >>> b = metrics.get_LAB_b(img)
      >>> b.shape
      (200, 200)

`ipfml.metrics.``get_SVD`(image)

  Transforms Image using SVD compression

  Parameters: | image – image to convert into SVD compression
  Returns: | U, s, V obtained from SVD compression

  Usage:

      >>> from PIL import Image
      >>> from ipfml import metrics
      >>> img = Image.open('./images/test_img.png')
      >>> U, s, V = metrics.get_SVD(img)
      >>> U.shape
      (200, 200, 3)
      >>> len(s)
      200
      >>> V.shape
      (200, 3, 3)

`ipfml.metrics.``get_SVD_U`(image)

  Transforms Image into SVD and returns only ‘U’ part

  Parameters: | image – image to convert
  Returns: | U matrix from SVD compression

  Usage:

      >>> from PIL import Image
      >>> from ipfml import metrics
      >>> img = Image.open('./images/test_img.png')
      >>> U = metrics.get_SVD_U(img)
      >>> U.shape
      (200, 200, 3)

`ipfml.metrics.``get_SVD_V`(image)

  Transforms Image into SVD and returns only ‘V’ part

  Parameters: | image – image to convert
  Returns: | V matrix obtained from SVD compression

  Usage :

      >>> from PIL import Image
      >>> from ipfml import metrics
      >>> img = Image.open('./images/test_img.png')
      >>> V = metrics.get_SVD_V(img)
      >>> V.shape
      (200, 3, 3)

`ipfml.metrics.``get_SVD_s`(image)

  Transforms Image into SVD and returns only ‘s’ part

  Parameters: | image – image to convert
  Returns: | vector of singular values obtained from SVD compression

  Usage:

      >>> from PIL import Image
      >>> from ipfml import metrics
      >>> img = Image.open('./images/test_img.png')
      >>> s = metrics.get_SVD_s(img)
      >>> len(s)
      200

`ipfml.metrics.``get_XYZ`(image)

  Transforms RGB Image into XYZ

  Parameters: | image – image to convert
  Returns: | XYZ information obtained from transformation

  Usage:

      >>> from PIL import Image
      >>> from ipfml import metrics
      >>> img = Image.open('./images/test_img.png')
      >>> metrics.get_XYZ(img).shape
      (200, 200, 3)

`ipfml.metrics.``get_XYZ_X`(image)

  Transforms RGB Image into XYZ and returns X

  Parameters: | image – image to convert
  Returns: | The X chanel from XYZ information

  Usage:

      >>> from PIL import Image
      >>> from ipfml import metrics
      >>> img = Image.open('./images/test_img.png')
      >>> x = metrics.get_XYZ_X(img)
      >>> x.shape
      (200, 200)

`ipfml.metrics.``get_XYZ_Y`(image)

  Transforms RGB Image into XYZ and returns Y

  Parameters: | image – image to convert
  Returns: | The Y chanel from XYZ information

  Usage:

      >>> from PIL import Image
      >>> from ipfml import metrics
      >>> img = Image.open('./images/test_img.png')
      >>> y = metrics.get_XYZ_Y(img)
      >>> y.shape
      (200, 200)

`ipfml.metrics.``get_XYZ_Z`(image)

  Transforms RGB Image into XYZ and returns Z

  Parameters: | image – image to convert
  Returns: | The Z chanel from XYZ information
  Raises: | `ValueError` – If nb_bits has unexpected value. nb_bits needs to be in interval [1, 8].

  Usage:

      >>> from PIL import Image
      >>> from ipfml import metrics
      >>> img = Image.open('./images/test_img.png')
      >>> z = metrics.get_XYZ_Z(img)
      >>> z.shape
      (200, 200)

`ipfml.metrics.``get_bits_img`(image, interval)

  Returns only bits specified into the interval

  Parameters:

  - image – image to convert using this interval of bits value to keep
  - interval – (begin, end) of bits values

  Returns: | Numpy array with reduced values

  Raises:

  - `ValueError` – If min value from interval is not >= 1.
  - `ValueError` – If max value from interval is not <= 8.
  - `ValueError` – If min value from interval >= max value.

  Usage:

      >>> from PIL import Image
      >>> from ipfml import metrics
      >>> img = Image.open('./images/test_img.png')
      >>> bits_img = metrics.get_bits_img(img, (2, 5))
      >>> bits_img.shape
      (200, 200, 3)

`ipfml.metrics.``get_low_bits_img`(image, nb_bits=4)

  Returns Image or Numpy array with data information reduced using only low bits

  Parameters:

  - image – image to convert
  - nb_bits – optional parameter which indicates the number of bits to keep

  Returns: | Numpy array with reduced values

  Usage:

      >>> from PIL import Image
      >>> from ipfml import metrics
      >>> img = Image.open('./images/test_img.png')
      >>> low_bits_img = metrics.get_low_bits_img(img, 5)
      >>> low_bits_img.shape
      (200, 200, 3)

`ipfml.metrics.``gray_to_mscn`(image)

  Convert Grayscale Image into Mean Subtracted Contrast Normalized (MSCN)

  Parameters: | image – grayscale image
  Returns: | MSCN matrix obtained from transformation

  Usage:

      >>> from PIL import Image
      >>> from ipfml import processing
      >>> img = Image.open('./images/test_img.png')
      >>> img_mscn = processing.rgb_to_mscn(img)
      >>> img_mscn.shape
      (200, 200)

## ipfml.processing

`ipfml.processing.``divide_in_blocks`(image, block_size, pil=True)

  Divide image into equal size blocks

  Parameters:

  - image – PIL Image or Numpy array
  - block – tuple (width, height) representing the size of each dimension of the block
  - pil – block type returned (default True)

  Returns: | list containing all 2D Numpy blocks (in RGB or not)
  Raises: | `ValueError` – If image_width or image_heigt are not compatible to produce correct block sizes

  Example:

      >>> import numpy as np
      >>> from PIL import Image
      >>> from ipfml import processing
      >>> from ipfml import metrics
      >>> image_values = np.random.randint(255, size=(800, 800, 3))
      >>> blocks = divide_in_blocks(image_values, (20, 20))
      >>> len(blocks)
      1600
      >>> blocks[0].width
      20
      >>> blocks[0].height
      20
      >>> img_l = Image.open('./images/test_img.png')
      >>> L = metrics.get_LAB_L(img_l)
      >>> blocks_L = divide_in_blocks(L, (100, 100))
      >>> len(blocks_L)
      4
      >>> blocks_L[0].width
      100

`ipfml.processing.``get_LAB_L_SVD`(image)

  Returns Singular values from LAB L Image information

  Parameters: | image – PIL Image or Numpy array
  Returns: | U, s, V information obtained from SVD compression using Lab

  Example:

      >>> from PIL import Image
      >>> from ipfml import processing
      >>> img = Image.open('./images/test_img.png')
      >>> U, s, V = processing.get_LAB_L_SVD(img)
      >>> U.shape
      (200, 200)
      >>> len(s)
      200
      >>> V.shape
      (200, 200)

`ipfml.processing.``get_LAB_L_SVD_U`(image)

  Returns U SVD from L of LAB Image information

  Parameters: | image – PIL Image or Numpy array
  Returns: | U matrix of SVD compression

  Example:

      >>> from PIL import Image
      >>> from ipfml import processing
      >>> img = Image.open('./images/test_img.png')
      >>> U = processing.get_LAB_L_SVD_U(img)
      >>> U.shape
      (200, 200)

`ipfml.processing.``get_LAB_L_SVD_V`(image)

  Returns V SVD from L of LAB Image information

  Parameters: | image – PIL Image or Numpy array
  Returns: | V matrix of SVD compression

  Example:

      >>> from PIL import Image
      >>> from ipfml import processing
      >>> img = Image.open('./images/test_img.png')
      >>> V = processing.get_LAB_L_SVD_V(img)
      >>> V.shape
      (200, 200)

`ipfml.processing.``get_LAB_L_SVD_s`(image)

  Returns s (Singular values) SVD from L of LAB Image information

  Parameters: | image – PIL Image or Numpy array
  Returns: | vector of singular values

  Example:

      >>> from PIL import Image
      >>> from ipfml import processing
      >>> img = Image.open('./images/test_img.png')
      >>> s = processing.get_LAB_L_SVD_s(img)
      >>> len(s)
      200

`ipfml.processing.``normalize_2D_arr`(arr)

  Return array normalize from its min and max values

  Parameters: | arr – 2D Numpy array
  Returns: | Normalized 2D Numpy array

  Example:

      >>> from PIL import Image
      >>> from ipfml import processing
      >>> img = Image.open('./images/test_img.png')
      >>> img_mscn = processing.rgb_to_mscn(img)
      >>> img_normalized = processing.normalize_2D_arr(img_mscn)
      >>> img_normalized.shape
      (200, 200)

`ipfml.processing.``normalize_arr`(arr)

  Normalize data of 1D array shape

  Parameters: | arr – array data of 1D shape
  Returns: | Normalized 1D array

  Example:

      >>> from ipfml import processing
      >>> import numpy as np
      >>> arr = np.arange(11)
      >>> arr_normalized = processing.normalize_arr(arr)
      >>> arr_normalized[1]
      0.1

`ipfml.processing.``normalize_arr_with_range`(arr, min, max)

  Normalize data of 1D array shape

  Parameters: | arr – array data of 1D shape
  Returns: | Normalized 1D Numpy array

  Example:

      >>> from ipfml import processing
      >>> import numpy as np
      >>> arr = np.arange(11)
      >>> arr_normalized = processing.normalize_arr_with_range(arr, 0, 20)
      >>> arr_normalized[1]
      0.05

`ipfml.processing.``rgb_to_LAB_L_bits`(image, interval)

  Returns only bits from LAB L canal specified into the interval

  Parameters:

  - image – image to convert using this interval of bits value to keep
  - interval – (begin, end) of bits values

  Returns: | 2D Numpy array with reduced values

      >>> from PIL import Image
      >>> from ipfml import processing
      >>> img = Image.open('./images/test_img.png')
      >>> bits_Lab_l_img = processing.rgb_to_LAB_L_bits(img, (2, 6))
      >>> bits_Lab_l_img.shape
      (200, 200)

`ipfml.processing.``rgb_to_LAB_L_low_bits`(image, nb_bits=4)

  Convert RGB Image into Lab L channel image using only 4 low bits values

  Parameters:

  - image – 3D RGB image Numpy array or PIL RGB image
  - nb_bits – optional parameter which indicates the number of bits to keep (default 4)

  Returns: | 2D Numpy array with low bits information kept

  Example:

      >>> from PIL import Image
      >>> from ipfml import processing
      >>> img = Image.open('./images/test_img.png')
      >>> low_bits_Lab_l_img = processing.rgb_to_LAB_L_low_bits(img, 5)
      >>> low_bits_Lab_l_img.shape
      (200, 200)

`ipfml.processing.``rgb_to_grey_low_bits`(image, nb_bits=4)

  Convert RGB Image into grey image using only 4 low bits values

  Parameters:

  - image – 3D RGB image Numpy array or PIL RGB image
  - nb_bits – optional parameter which indicates the number of bits to keep (default 4)

  Returns: | 2D Numpy array with low bits information kept

  Example:

      >>> from PIL import Image
      >>> from ipfml import processing
      >>> img = Image.open('./images/test_img.png')
      >>> low_bits_grey_img = processing.rgb_to_grey_low_bits(img, 5)
      >>> low_bits_grey_img.shape
      (200, 200)

`ipfml.processing.``rgb_to_mscn`(image)

  Convert RGB Image into Mean Subtracted Contrast Normalized (MSCN)

  Parameters: | image – 3D RGB image Numpy array or PIL RGB image
  Returns: | 2D Numpy array with MSCN information

  Example:

      >>> from PIL import Image
      >>> from ipfml import processing
      >>> img = Image.open('./images/test_img.png')
      >>> img_mscn = processing.rgb_to_mscn(img)
      >>> img_mscn.shape
      (200, 200)

## ipfml.filters

### ipfml.filters.noise

`ipfml.filters.noise.``cauchy_noise`(image, n, identical=False, distribution_interval=(0, 1), k=0.0002)

  Cauchy noise filter to apply on image

  Parameters:

  - image – image used as input (2D or 3D image representation)
  - n – used to set importance of noise [1, 999]
  - identical – keep or not identical noise distribution for each canal if RGB Image (default False)
  - distribution_interval – set the distribution interval of normal law distribution (default (0, 1))
  - k – variable that specifies the amount of noise to be taken into account in the output image (default 0.0002)

  Returns: | 2D Numpy array with Cauchy noise applied

  Example:

      >>> from ipfml.filters.noise import cauchy_noise
      >>> import numpy as np
      >>> image = np.random.uniform(0, 255, 10000).reshape((100, 100))
      >>> noisy_image = cauchy_noise(image, 10)
      >>> noisy_image.shape
      (100, 100)

`ipfml.filters.noise.``gaussian_noise`(image, n, identical=False, distribution_interval=(0, 1), k=0.1)

  Gaussian noise filter to apply on image

  Parameters:

  - image – image used as input (2D or 3D image representation)
  - n – used to set importance of noise [1, 999]
  - identical – keep or not identical noise distribution for each canal if RGB Image (default False)
  - distribution_interval – set the distribution interval of normal law distribution (default (0, 1))
  - k – variable that specifies the amount of noise to be taken into account in the output image (default 0.1)

  Returns: | 2D Numpy array with gaussian noise applied

  Example:

      >>> from ipfml.filters.noise import gaussian_noise
      >>> import numpy as np
      >>> image = np.random.uniform(0, 255, 10000).reshape((100, 100))
      >>> noisy_image = gaussian_noise(image, 10)
      >>> noisy_image.shape
      (100, 100)

`ipfml.filters.noise.``laplace_noise`(image, n, identical=False, distribution_interval=(0, 1), k=0.1)

  Laplace noise filter to apply on image

  Parameters:

  - image – image used as input (2D or 3D image representation)
  - n – used to set importance of noise [1, 999]
  - identical – keep or not identical noise distribution for each canal if RGB Image (default False)
  - distribution_interval – set the distribution interval of normal law distribution (default (0, 1))
  - k – variable that specifies the amount of noise to be taken into account in the output image (default 0.1)

  Returns: | 2D Numpay array with Laplace noise applied

  Example:

      >>> from ipfml.filters.noise import laplace_noise
      >>> import numpy as np
      >>> image = np.random.uniform(0, 255, 10000).reshape((100, 100))
      >>> noisy_image = laplace_noise(image, 10)
      >>> noisy_image.shape
      (100, 100)

`ipfml.filters.noise.``log_normal_noise`(image, n, identical=False, distribution_interval=(0, 1), k=0.05)

  Log-normal noise filter to apply on image

  Parameters:

  - image – image used as input (2D or 3D image representation)
  - n – used to set importance of noise [1, 999]
  - identical – keep or not identical noise distribution for each canal if RGB Image (default False)
  - distribution_interval – set the distribution interval of normal law distribution (default (0, 1))
  - k – variable that specifies the amount of noise to be taken into account in the output image (default 0.05)

  Returns: | 2D Numpy array with Log-normal noise applied

  Example:

      >>> from ipfml.filters.noise import log_normal_noise
      >>> import numpy as np
      >>> image = np.random.uniform(0, 255, 10000).reshape((100, 100))
      >>> noisy_image = log_normal_noise(image, 10)
      >>> noisy_image.shape
      (100, 100)

`ipfml.filters.noise.``mut_white_noise`(image, n, identical=False, distribution_interval=(-0.5, 0.5), k=0.2)

  Multiplied White noise filter to apply on image

  Parameters:

  - image – image used as input (2D or 3D image representation)
  - n – used to set importance of noise [1, 999]
  - identical – keep or not identical noise distribution for each canal if RGB Image (default False)
  - distribution_interval – set the distribution interval of normal law distribution (default (-0.5, 0.5))
  - k – variable that specifies the amount of noise to be taken into account in the output image (default 0.2)

  Returns: | 2D Numpy array with multiplied white noise applied

  Example:

      >>> from ipfml.filters.noise import mut_white_noise
      >>> import numpy as np
      >>> image = np.random.uniform(0, 255, 10000).reshape((100, 100))
      >>> noisy_image = mut_white_noise(image, 10)
      >>> noisy_image.shape
      (100, 100)

`ipfml.filters.noise.``salt_pepper_noise`(image, n, identical=False, p=0.1, k=0.5)

  Pepper salt noise filter to apply on image

  Parameters:

  - image – image used as input (2D or 3D image representation)
  - n – used to set importance of noise [1, 999]
  - identical – keep or not identical noise distribution for each canal if RGB Image (default False)
  - p – probability to increase pixel value otherwise decrease it
  - k – variable that specifies the amount of noise to be taken into account in the output image (default 0.5)

  Returns: | 2D Numpy array with salt and pepper noise applied

  Example:

      >>> from ipfml.filters.noise import salt_pepper_noise
      >>> import numpy as np
      >>> image = np.random.uniform(0, 255, 10000).reshape((100, 100))
      >>> noisy_image = salt_pepper_noise(image, 10)
      >>> noisy_image.shape
      (100, 100)

`ipfml.filters.noise.``white_noise`(image, n, identical=False, distribution_interval=(-0.5, 0.5), k=0.2)

  White noise filter to apply on image

  Parameters:

  - image – image used as input (2D or 3D image representation)
  - n – used to set importance of noise [1, 999]
  - identical – keep or not identical noise distribution for each canal if RGB Image (default False)
  - distribution_interval – set the distribution interval of normal law distribution (default (-0.5, 0.5))
  - k – variable that specifies the amount of noise to be taken into account in the output image (default 0.2)

  Returns: | 2D Numpy array with white noise applied

  Example:

      >>> from ipfml.filters.noise import white_noise
      >>> import numpy as np
      >>> image = np.random.uniform(0, 255, 10000).reshape((100, 100))
      >>> noisy_image = white_noise(image, 10)
      >>> noisy_image.shape
      (100, 100)