xml_image_information.py

Go to the documentation of this file.

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

import xml.dom.minidom
import datetime

## @package face_contour_detector.image_information.xml_image_information
#  The only classed defined here is XMLImageInformationDatabase - used to save and read image information databases from xml files.
#  @author Fabian Wenzelmann

## @brief Exception that is thrown if an error occured parsing the xml file.
#  @author Fabian Wenzelmann
#  @date 2011-02-20
class XMLValueException(Exception):
    def __init__(self, error_msg):
        super(XMLValueException, self).__init__(error_msg)

## @brief Class to read a database from a xml file and to write a database to a xml file.
#  @author Fabian Wenzelmann
#  @date 2011-02-20
#
#  A image database ist a list of dictionaries. Such a dictionary maps property names to tuples where the first component of the tuple is the value of this property and the second component is the type as string. Allowed types are "int", "float" and "string". For example if the only information for one image is the MaxPixelValue the dictionary has the form \verbatim { "MaxPixelValue" : (200, "int") } \endverbatim which means that the max pixel value in the image is 200 and the result is of type int. A list of such dictionaries is saved in a field called images.<br>
#  There is also a max_size parameter to restrict the size of images that can be stored in a database.
class XMLImageInformationDatabase:
    ## The constructor
    #  @param self the object pointer
    #  @param max_size If max_size is not None it is an integer >= 1. The append() method takes care that there are not more than max_size elements in the list. Also the load() method loads only max_size elements, even if there are more in the xml file. If it's None the database has no limit.
    def __init__(self, max_size=None):
        self.images = []
        self.max_size = max_size
    
    # field documentation
    ## @var images
    #  the list containing the images: images is a list of dictionaries.
    #  Such a dictionary maps property names to tuples where the first component of the tuple is the value of this property and the second component is the type as string. Allowed types are "int", "float" and "string". For example if the only information for one image is the MaxPixelValue the dictionary has the form \verbatim { "MaxPixelValue" : (200, "int") } \endverbatim which means that the max pixel value in the image is 200 and the result is of type int. A list of such dictionaries is saved in a field called images.
    
    ## @var max_size
    #  the maximum amount of images stores in the images list
    
    ## Load a xml file and add all entries to the images list.
    #  @param self the object pointer
    #  @param doc a xml object as received by xml.dom.minidom.parse
    #
    #  Parses a xml file and adds all images images list. The xml file must follow the XML Schema of imageInformationDatabase as defined in image_information.xsd. This means that the root note is "imageInformationDatabase". This node has subnodes with name "image". A image node has "entry" subnodes where each entry node has two child nodes: "name" (with the name of the property) and "content" (the value of this property). An entry also has an attribute "type" which is "int", "float" or "string".<br>
    #  Also max_size value is checked so if there are more than max_size elements in the file you only have max_size elements in the list (following the order of the document).
    #  @exception XMLValueError if the root node is not "imageInformationDatabase"
    #  @exception XMLValueError if the type attribute of entry is not "int", "float" or "string"
    #  @exception Exception An exception may be thrown if there is no attribute "type" in entry or if an entry has no name or no content subnode. We also assume that if entry is if type int the int function of python can translate the content of this entry to an integer (also for float).
    def load(self, doc):
        text_node_type = xml.dom.minidom.Node.TEXT_NODE
        root = doc.documentElement
        if root.tagName != "imageInformationDatabase":
            raise XMLValueException("Expected imageInformationDatabase as root of document not " + root.tagName)
        images = root.getElementsByTagName("image")
        for image in images:
            if self.max_reached():
                break
            image_information = {}
            information_entries = image.getElementsByTagName("entry")
            for entry in information_entries:
                entry_type = entry.getAttribute("type")
                translate_function = None
                if entry_type == "int":
                    translate_function = int
                elif entry_type == "float":
                    translate_function = float
                elif entry_type == "string":
                    translate_function = lambda x: x
                else:
                    raise XMLValueException("Only 'int', 'float' and 'string' are allowed values for entries in image information. Got " + entry_type)
                name_node = entry.getElementsByTagName("name")[0]
                value_node = entry.getElementsByTagName("content")[0]
                name = ""
                value = ""
                for n in name_node.childNodes:
                    if n.nodeType == text_node_type:
                        name += n.data
                for n in value_node.childNodes:
                    if n.nodeType == text_node_type:
                        value += n.data
                image_information[name] = translate_function(value.strip()), entry_type
            self.images.append(image_information)
            
    @staticmethod
    ## internal method to create an "entry" node
    def __information_entry_to_node(doc, type_name, name, content):
        root = doc.createElement("entry")
        attr = doc.createAttribute("type")
        attr.value = type_name
        root.setAttributeNode(attr)
        
        name_node = doc.createElement("name")
        name_text_node = doc.createTextNode(name)
        name_node.appendChild(name_text_node)
        root.appendChild(name_node)
        
        content_node = doc.createElement("content")
        content_text_node = doc.createTextNode(str(content))
        content_node.appendChild(content_text_node)
        root.appendChild(content_node)
        
        return root

    @staticmethod
    ## internal method to create an "image" node
    def __create_image_node(doc, entries):
        root = doc.createElement("image")
        for entry_name, (value, type_name) in entries.items():
            root.appendChild( XMLImageInformationDatabase.__information_entry_to_node(doc, type_name, entry_name, value) )
        return root
        
    @staticmethod
    ## internalt method: writes an "entry" node to the writer object (should have a write method)
    def __pretty_write_entry(typename, name, content, writer, indent, addindent, newl):
        writer.write(indent)
        writer.write('<entry type="')
        xml.dom.minidom._write_data(writer, typename)
        writer.write('">')
        writer.write(newl)
        
        next_indent = indent + addindent
        
        writer.write(next_indent)
        writer.write("<name>")
        xml.dom.minidom._write_data(writer, name)
        writer.write("</name>")
        writer.write(newl)
        
        writer.write(next_indent)
        writer.write("<content>")
        xml.dom.minidom._write_data(writer, str(content))
        writer.write("</content>")
        writer.write(newl)
        
        writer.write(indent)
        writer.write("</entry>")
        writer.write(newl)
    
    @staticmethod
    ## internal method to write an "image" node to writer (should have a write method)
    def __pretty_write_image(entries, writer, indent, addindent, newl):
        writer.write(indent)
        writer.write("<image>")
        writer.write(newl)
        for entry_name, (value, type_name) in entries.items():
            XMLImageInformationDatabase.__pretty_write_entry(type_name, entry_name, value, writer, indent + addindent, addindent, newl)
        writer.write(indent)
        writer.write("</image>")
        writer.write(newl)
    
    ## Write the database to the writer object.
    #  @param self the object pointer
    #  @param writer a object that has e "write" functions (file object interface)
    #  @param addindent a string that is the incremental idention for subnodes
    #  @param newl a string that is used as newline (after most nodes)
    #
    #  Writes a xml file that satisfies the imageInformationDatabase type as defined in image_information.xsd
    def write_pretty_xml(self, writer, addindent="\t", newl="\n"):
        writer.write('<?xml version="1.0" encoding="UTF-8"?>')
        writer.write(newl)
        writer.write(newl)
        writer.write("<!-- automatically generated on ")
        writer.write(str(datetime.date.today()))
        writer.write(" -->")
        writer.write(newl)
        writer.write("<!-- This file contains information about images used for the PR2 Drawing Faces module. Just technically stuff - no personal data! -->")
        writer.write(newl)
        writer.write(newl)
        
        writer.write("<imageInformationDatabase>")
        writer.write(newl)
        for image in self.images:
            XMLImageInformationDatabase.__pretty_write_image(image, writer, addindent, addindent, newl)
            writer.write(newl)
        writer.write("</imageInformationDatabase>")
    
    ## Write a xml file to path
    #  @param self the object pointer
    #  @param path file path to the xml file
    #
    #  @see write_pretty_xml()
    def write_file(self, path):
        with open(path, "w") as f:
            self.write_pretty_xml(f)
    
    ## Load the database from an xml file.
    #  @param path path of the xml file
    #  @exception Exception if file does not exists
    #
    #  Just calls load() method with xml.dom.minidom.parse(path)
    def load_file(self, path):
        self.load( xml.dom.minidom.parse(path) )
    
    ## Return true if max_size is reached for this database
    #  @param self the object pointer
    def max_reached(self):
        if self.max_size is None:
            return False
        return len(self.images) >= self.max_size
    
    ## Append a new entry to the database
    #  @param self the object pointer
    #  @param entry The new entry to add (a dictionary as defined in preface)
    #
    #  Adds a new element to the list. If max_size is reached the new entry will displace the oldest entry in the list. Which is assumed to be the first entry in the list.
    def append(self, entry):
        if self.max_reached():
            self.images[0] = entry
        else:
            self.images.append(entry)