added manifest. Updated user-guide and code documentation

MANIFEST.in

+include README.rst bootstrap-buildout.py buildout.cfg develop.cfg requirements.txt version.txt
+recursive-include doc *.py *.rst *.png *.ico
+recursive-include bob/ip/qualitymeasure/data *.mp4 *.jpg *.h5 *.hdf5

README.rst

@@ -22,7 +22,7 @@
 This package is part of the signal-processing and machine learning toolbox
 Bob_. It provides functions for extracting image-quality features proposed
 for PAD experiments by different research groups. Image quality measures
-proposed by Galbally et al (TIFS 2014) and by Wen et al. (TIFS 2015)
+proposed by Galbally et al (IEEE TIP 2014) and by Wen et al. (IEEE TIFS 2015)
 are implemented in this package.
 
 Installation

bob/ip/qualitymeasure/__init__.py

 #!/usr/bin/env python
 # vim: set fileencoding=utf-8 :
 
-
+from .galbally_iqm_features import compute_quality_features
+from .msu_iqa_features import compute_msu_iqa_features
 
 def get_config():
     """

bob/ip/qualitymeasure/galbally_iqm_features.py

@@ -28,15 +28,21 @@ Main function to be called, to extract a set of image quality-features computed
 """
 def compute_quality_features(image):
     """Extract a set of image quality-features computed for the input image.
-    :param image: 2d or 3d numpy array. Should represent input image of shape [M,N] (M rows x N cols).
+
+    Parameters:
+
+    image (:py:class:`numpy.ndarray`): A ``uint8`` array with 2 or 3 dimensions, representing the input image of shape [M,N] (M rows x N cols).
     If 2D, image should contain a gray-image of shape [M,N].
-    If 3d, image should have a shape [3,M,N], and should contain an RGB-image.
+    If 3D, image should have a shape [3,M,N], and should contain an RGB-image.
+
 
-    :return featSet: a tuple of float-scalars, each representing one image-quality measure.
+    Returns:
+
+    featSet (:py:class:`numpy.ndarray`): a 1D numpy array of 18 float32 scalars, each representing one image-quality measure.
     This function returns a subset of the image-quality features (for face anti-spoofing) that have been 
     described by Galbally et al. in their paper:
     "Image Quality Assessment for Fake Biometric Detection: Application to Iris, Fingerprint, and Face Recognition",
-     IEEE Trans. on Image Processing Vol 23(2), 2014.
+    IEEE Trans. on Image Processing Vol 23(2), 2014.
     """
     gray_image = None
     #print("shape of input image:")
@@ -226,11 +232,17 @@ Ref:Z. Wang, A.C. Bovik, H.R. Sheikh and E.P. Simoncelli:
 """
 def ssim(refImage, testImage):
     """Compute and return SSIM between two images.
-    @param refImage: 2D numpy array (reference image)
-    @param testImage: 2D numpy array (test image)
+
+    Parameters:
+
+    refImage: 2D numpy array (reference image)
+    testImage: 2D numpy array (test image)
+
+    Returns:
+
     Returns ssim and ssim_map
-     @return ssim: float-scalar. The mean structural similarity between the 2 input images.
-    @return ssim_map: the SSIM index map of the test image (this map is smaller than the test image).
+    ssim: float-scalar. The mean structural similarity between the 2 input images.
+    ssim_map: the SSIM index map of the test image (this map is smaller than the test image).
     """
     M=refImage.shape[0]
     N=refImage.shape[1]

bob/ip/qualitymeasure/msu_iqa_features.py

@@ -103,48 +103,51 @@ def sobelEdgeMap(image, orientation='both'):
 
 
 '''
+main function to call
 '''
 def compute_msu_iqa_features(rgbImage):
-#     print("computing msu iqa features")
+    """Computes image-quality features for the given input color (RGB) image.
+
+    Parameters:
+
+    rgbImage (:py:class:`numpy.ndarray`): A ``uint8`` array with 3 dimensions, representing the RGB input image of shape [3,M,N] (M rows x N cols).
+    
+    Returns:
+
+    featSet (:py:class:`numpy.ndarray`): a 1D numpy array of 121 float32 scalars.
+    This function returns the image-quality features (for face anti-spoofing) that have been 
+    described by Wen et al. in their paper:
+    "Face  spoof  detection  with  image distortion analysis", 
+    IEEE Trans. on Information Forensics and Security, vol. 10(4), pp. 746-761, April 2015.
+    """
+                                    
     assert len(rgbImage.shape)==3, 'compute_msu_iqa_features():: image should be a 3D array (containing a rgb image)'
-#     hsv = np.zeros_like(rgbImage)
-#     bob.ip.color.rgb_to_hsv(rgbImage, hsv)
-#     h = hsv[0,:,:]
-#     s = hsv[1,:,:]
-#     v = hsv[2,:,:]
     h,s,v = matlab_rgb2hsv(rgbImage) #defined above. Calls Bob's rgb_to_hsv() after rescaling the input image.
     
-    #print "compute_msu_iqa_features():: check bob.ip.color.rgb_to_hsv conversion"
     grayImage = np.zeros_like(h, dtype='uint8')
     bob.ip.color.rgb_to_gray(rgbImage, grayImage)
     
+    # compute blur-features
     blurFeat = blurriness(grayImage)
-#     print 'blurriness:', blurFeat
     
     pinaBlur = marzilianoBlur(grayImage)
     pinaBlur /= 30.0
-#     print 'pinaBlur:',pinaBlur
     
+    # compute color-diversity features
     colorHist, totNumColors = calColorHist(rgbImage)
     totNumColors /= 2000.0 #as done in Matlab code provided by MSU.
-#     print "color hist shape:", colorHist.shape
-#     print colorHist[0:11]
-#     print 'totNumColors', totNumColors
     
     # calculate mean, deviation and skewness of each channel
     # use histogram shifting for the hue channel
-#     print h.shape
     momentFeatsH = calmoment_shift(h)
-#     print 'H-moments:', momentFeatsH
         
     momentFeats = momentFeatsH.copy()
     momentFeatsS = calmoment(s)
-#     print 'S-moments:', momentFeatsS
     momentFeats = np.hstack((momentFeats, momentFeatsS))
     momentFeatsV = calmoment(v)
-#     print 'V-moments:', momentFeatsV
     momentFeats = np.hstack((momentFeats, momentFeatsV))
 
+    # compute the image-specularity features
     speckleFeats = compute_iqa_specularity_features(rgbImage, startEps=0.06)
     
     #stack the various feature-values in the same order as in MSU's matlab code.
@@ -156,8 +159,6 @@ def compute_msu_iqa_features(rgbImage):
     fv = np.hstack((fv, blurFeat))
     fv = np.hstack((fv, pinaBlur))
 
-#     print('computed msu features')
-
     return fv
 
 
@@ -177,7 +178,6 @@ def compute_iqa_specularity_features(rgbImage, startEps=0.05):
     speckleMean = np.mean(speckleImg)
     lowSpeckleThresh = speckleMean*1.5      #factors 1.5 and 4.0 are proposed by Wen et al. in their paper and matlab code.
     hiSpeckleThresh = speckleMean*4.0
-    #     print speckleMean, lowSpeckleThresh, hiSpeckleThresh
     specklePixels = speckleImg[np.where(np.logical_and(speckleImg >= lowSpeckleThresh, speckleImg<hiSpeckleThresh))]
 
     r = float(specklePixels.flatten().shape[0])/(speckleImg.shape[0]*speckleImg.shape[1]) #percentage of specular pixels in image

develop.cfg

@@ -9,8 +9,6 @@ extensions = bob.buildout
              mr.developer
 auto-checkout = *
 develop = src/bob.extension
-          src/bob.blitz
-          src/bob.core
           src/bob.io.base
           src/bob.io.image
           src/bob.io.video
@@ -27,8 +25,6 @@ newest = false
 
 [sources]
 bob.extension = git https://gitlab.idiap.ch/bob/bob.extension
-bob.blitz = git https://gitlab.idiap.ch/bob/bob.blitz
-bob.core = git https://gitlab.idiap.ch/bob/bob.core
 bob.io.base = git https://gitlab.idiap.ch/bob/bob.io.base
 bob.io.image = git https://gitlab.idiap.ch/bob/bob.io.image
 bob.io.video = git https://gitlab.idiap.ch/bob/bob.io.video

doc/guide.rst

@@ -28,9 +28,9 @@
 You can used this Bob package to extract image-quality features for face-PAD applications.
 Two sets of quality-features are implemented in this package:
 
-1. The image-quality measures proposed by Galbally et al. (TIFS 2014), and
+1. The image-quality measures proposed by Galbally et al. (IEEE TIP 2014), and
 
-2. The image-quality features proposed by Wen et al. (TIFS 2015).
+2. The image-quality features proposed by Wen et al. (IEEE TIFS 2015).
 
 The package includes separate modules for implementing the two feature-sets.
 The module ``galbally_iqm_features`` implements the features proposed by Gabally et al., and the module ``msu_iqa_features`` implements the features proposed by Wen et al. 
@@ -49,7 +49,7 @@ The function ``compute_quality_features()`` (in the module galbally_iqm_features
 proposed by Galbally et al. Note that Galbally et al. proposed 25 features in their paper. This package implements the following
 18 features from their paper, namely: 
 [mse, psnr, ad, sc, nk, md, lmse, nae, snrv, ramdv, mas, mams, sme, gme, gpe, ssim, vif, hlfi].
-The function ``galbally_iqm_features::compute_quality_features()`` returns a 18-D numpy array, containing the feature-values in the order listed above.
+The function ``galbally_iqm_features::compute_quality_features()`` returns a 1D numpy array of length 18, containing the feature-values in the order listed above.
 
 .. doctest::
 
@@ -69,8 +69,8 @@ Therefore, the function ``galbally_iqm_features::compute_quality_features()`` ta
 or a gray-level image.
 (The input image should be a numpy-array. RGB color-images should be in the format expected by Bob_.)
 When the input image is 3-dimensional, the first dimension being '3' (as is the case in the example above), the input
-is considered to represent a color RGB image, and is first converted to a gray-level image.
-If the input is 2-dimensional (say, a numpy array of shape [480, 720]), then it is considered to represent a gray-level
+is assumed to represent a color RGB image, and is first converted to a gray-level image.
+If the input is 2-dimensional (say, a numpy array of shape [480, 720]), then it is assumed to represent a gray-level
 image, and the RGB-to-gray conversion step is skipped. 
 
 

requirements.txt

@@ -6,3 +6,5 @@ bob.io.image
 bob.io.video
 bob.ip.draw
 bob.ip.color
+numpy
+scipy