image_information.py

Go to the documentation of this file.

# -*- coding: utf-8 -*-

import math

## @package face_contour_detector.image_information.image_information
#  This module provides class to extract information from an image (class ImageInformation and InformationExtractor).
#  There are also basic information extractor implementations: SizeExtractor, MinMaxExtractor, AverageValueExtractor
#  @author Fabian Wenzelmann

## @brief This class is an abstract class that defines methods to extract informatioon from an image (CvMat).
#  @author Fabian Wenzelmann
#  @date 2011-02-20
#
#  For this we suppose the image to be in RGB format were the blue component is the first componenent, green the second and red the third (as in OpenCv, whyever).<br>
#  There is only one method required: extract_information(). See extract_information() for further explanation.<br>
#  Extracting information from an image is done by calling the extract_information() method for this image.
#  We assume the image to be "big enough". This means that there are more than two pixel in each image so that we can use values like \f$ \frac{1}{n-1} \f$ where n is the number of pixel.
#  Usually complete white pixels are ignored since we assume that they're white because this part of the image was not covered by the mask image.
class ImageInformation:    
    ## @brief For a given image (as CvMat in RGB format) extract whatever kind of information.
    #  @param self the object pointer
    #  @param img the image as CvMat in RGB format
    #
    #  Extract the information from the image. Return value is a <i>list</i>. This list contains <i>three tuples</i>. Such a tuple <i>t</i> has the form t = (name, value, type). Where <i>name</i> is the name of the property t represents for example MaxPixelValue. <i>value</i> is the value of this property for example 200 if 200 is the maximal pixel value in img. <i>type</i> is a string and is one of "int", "float", "string". These tuples can be added to xml_image_information.
    def extract_information(self, img):
        raise NotImplementedError("Subclasses of ImageInformation must implement the method extract_information(image)")

## @brief Subclass of ImageInformation that extracts height and width value (names "Height" and "Width"), both of type int
#  @author Fabian Wenzelmann
#  @date 2011-02-20
class SizeExtractor(ImageInformation):
    ## Constructor method
    #  @param self the object pointer
    def __init__(self):
        pass

    def extract_information(self, img):
        return [ ( "Height", img.height, "int" ), ("Width", img.width, "int") ]

## @brief Subclass of ImageInformation that extracts min / max pixel values from image.
#  @author Fabian Wenzelmann
#  @date 2011-02-20
#
#  For each color component there is a min / max component so it returns a list with 6 three tuples. The max value of the red component has the name MaxR and so on. All values are of tpye int.
class MinMaxExtractor(ImageInformation):
    ## Constructor method
    #  @param self the object pointer
    def __init__(self):
        pass
    
    def extract_information(self, img):
        first = img[0, 0]
        r_max = r_min = first[2]
        g_max = g_min = first[1]
        b_max = b_min = first[0]
        width_range = range(img.width)
        for row in range(img.height):
            for col in width_range:
                pixel = img[row, col]
                if pixel == (255, 255, 255):
                    continue
                r = pixel[2]
                g = pixel[1]
                b = pixel[0]
                r_max = max(r_max, r)
                r_min = min(r_min, r)
                g_max = max(g_max, g)
                g_min = min(g_min, g)
                b_max = max(b_max, b)
                b_min = min(b_min, b)
        return [ ("MaxR", r_max, "float"), ("MinR", r_min, "float"), ("MaxG", g_max, "float"), ("MinG", g_min, "float"), ("MaxB", b_max, "float"), ("MinB", b_min, "float") ]

## @brief Subclass of ImageInformation which extracts several average values.
#  @author Fabian Wenzelmann
#  @date 2011-02-20
#
#  For each pixel the brightness is defined as \f$ red * 0.299 + green * 0.587 + blue * 0.114\f$. The average of all those values is returned. Name is "AveragePixelBrightness".
#  Also calculates for each color channel the average value. For them the names are for example "AverageR" for the red color channel. Also calculates three standard deviation values (for each component one).
#  The names are "StandardDeviationR" and so on. Also (last also) returns "StandardBrightnessDeviation" All returned values are of type float.
class AverageValueExtractor(ImageInformation):
    ## Constructor method
    #  @param self the object pointer
    def __init__(self):
        pass

    def extract_information(self, img):
        value_sum = 0.0
        value_squared_sum = 0.0
        
        r_sum = 0.0
        g_sum = 0.0
        b_sum = 0.0
        
        r_square_sum = 0.0
        g_square_sum = 0.0
        b_square_sum = 0.0
        pixel_count = 0
        width_range = range(img.width)
        for row in range(img.height):
            for col in width_range:
                pixel = img[row, col]
                if pixel == (255, 255, 255):
                    continue
                pixel_count += 1
                blue = pixel[0]
                green = pixel[1]
                red = pixel[2]
                brightness = red * 0.299 + green * 0.587 + blue * 0.114
                value_sum += brightness
                value_squared_sum += brightness ** 2
                r_sum += red
                g_sum += green
                b_sum += blue
                
                r_square_sum += red ** 2
                g_square_sum += green ** 2
                b_square_sum += blue ** 2
        standard_derivation_r = math.sqrt( max( (1.0 / (pixel_count - 1)) * (r_square_sum - ((1.0 / pixel_count) * r_sum ** 2)), 0))
        standard_derivation_g = math.sqrt( max( (1.0 / (pixel_count - 1)) * (g_square_sum - ((1.0 / pixel_count) * g_sum ** 2)), 0))
        standard_derivation_b = math.sqrt( max( (1.0 / (pixel_count - 1)) * (b_square_sum - ((1.0 / pixel_count) * b_sum ** 2)), 0))
        standard_derivation_brightness = math.sqrt( max( (1.0 / (pixel_count - 1)) * (value_squared_sum - ((1.0 / pixel_count) * value_sum ** 2)), 0))
        return [ ("AveragePixelBrightness", value_sum / pixel_count, "float"), ("AverageR", r_sum / pixel_count, "float"), ("AverageG", g_sum / pixel_count, "float"), ("AverageB", b_sum / pixel_count, "float"), ("StandardDeviationR", standard_derivation_r, "float"), ("StandardDeviationG", standard_derivation_g, "float"), ("StandardDeviationB", standard_derivation_b, "float"), ("StandardBrightnessDeviation", standard_derivation_brightness, "float") ]

## @brief This class is used to extract information from an image using ImageInformation subclasses
#  @author Fabian Wenzelmann
class InformationExtractor:
        ## @brief Constructor method
        #  @param self the object pointer
    def __init__(self):
        self.information_extractors = []
    
    # field documentation
    ## @var information_extractors
    #  a list of objects of type ImageInformation. In this list all extractors are stored.
    
    ## @brief add ImageInformation objects for classes SizeExtractor, MinMaxExtractor, AverageValueExtractor
    #  @param self the object pointer
    def add_default_extractors(self):
        e1 = SizeExtractor()
        e2 = MinMaxExtractor()
        e3 = AverageValueExtractor()
        self.information_extractors += [e1, e2, e3]
    
    ## @brief Create a dictionary using the ImageInformation instances stored in self.information_extractors.
    #  @param self the object pointer
    #  @param img the image to collect the information from as cvMat with RGB colors.
    #
    #  All ImageInformation subclasses return in their extract_information() method tuples of names and values. The dictionary uses the names as keys and stores the information as tuples: (value, type)
    def to_dict(self, img):
        properties = {}
        for extractor in self.information_extractors:
            res = extractor.extract_information(img)
            for name, value, name_type in res:
                properties[name] = value, name_type
        return properties