Initial commit of binary morphology addon

PIL/ImageMorph.py

@@ -0,0 +1,234 @@
+# A binary morphology add-on for the Python Imaging Library
+#
+# History:
+#   2014-06-04 Initial version.
+#
+# Copyright (c) 2014 Dov Grobgeld <dov.grobgeld@gmail.com>
+
+from PIL import Image
+from PIL import _imagingmorph
+import re
+
+LUT_SIZE = 1<<9
+class LutBuilder:
+    """A class for building MorphLut's from a descriptive language
+
+      The input patterns is a list of a strings sequences like these:
+
+      4:(...
+         .1.
+         111)->1
+
+      (whitespaces including linebreaks are ignored). The option 4
+      descibes a series of symmetry operations (in this case a
+      4-rotation), the pattern is decribed by:
+
+         . or X - Ignore
+         1 - Pixel is on
+         0 - Pixel is off
+
+      The result of the operation is described after "->" string.
+
+      The default is to return the current pixel value, which is
+      returned if no other match is found.
+
+      Operations:
+         4 - 4 way rotation
+         N - Negate
+         1 - Dummy op for no other operation (an op must always be given)
+         M - Mirroring
+
+      Example:
+
+      lb = LutBuilder(patterns = ["4:(... .1. 111)->1"])
+      lut = lb.build_lut()
+
+    """
+    def __init__(self,patterns = None,op_name=None):
+        if patterns is not None:
+            self.patterns = patterns
+        else:
+            self.patterns = []
+        self.lut = None
+        if op_name is not None:
+            known_patterns = {
+                'corner' : ['1:(... ... ...)->0',
+                            '4:(00. 01. ...)->1'],
+                'dilation4' : ['4:(... .0. .1.)->1'],
+                'dilation8' : ['4:(... .0. .1.)->1',
+                               '4:(... .0. ..1)->1'],
+                'erosion4' : ['4:(... .1. .0.)->0'],
+                'erosion8' : ['4:(... .1. .0.)->0',
+                              '4:(... .1. ..0)->0'],
+                'edge' : ['1:(... ... ...)->0',
+                          '4:(.0. .1. ...)->1',
+                          '4:(01. .1. ...)->1']
+            }
+            if not op_name in known_patterns:
+                raise Exception('Unknown pattern '+op_name+'!')
+
+            self.patterns = known_patterns[op_name]
+
+    def add_patterns(self, patterns):
+        self.patterns += patterns
+
+    def build_default_lut(self):
+        symbols = ['\0','\1']
+        m = 1 << 4  # pos of current pixel
+        self.lut = bytearray(''.join([symbols[(i & m)>0] for i in range(LUT_SIZE)]))
+
+    def get_lut(self):
+        return self.lut
+
+    def _string_permute(self, pattern, permutation):
+        """string_permute takes a pattern and a permutation and returns the
+        string permuted accordinging to the permutation list.
+        """
+        assert(len(permutation)==9)
+        return ''.join([pattern[p] for p in permutation])
+
+    def _pattern_permute(self, basic_pattern, options, basic_result):
+        """pattern_permute takes a basic pattern and its result and clones
+        the mattern according to the modifications described in the $options
+        parameter. It returns a list of all cloned patterns."""
+        patterns = [(basic_pattern, basic_result)]
+
+        # rotations
+        if '4' in options:
+            res = patterns[-1][1]
+            for i in range(4):
+                patterns.append(
+                    (self._string_permute(patterns[-1][0],
+                                    [6,3,0,
+                                     7,4,1,
+                                     8,5,2]), res))
+        # mirror
+        if 'M' in options:
+            n = len(patterns)
+            for pattern,res in patterns[0:n]:
+                patterns.append(
+                    (self._string_permute(pattern, [2,1,0,
+					      5,4,3,
+					      8,7,6]), res))
+
+        # negate
+        if 'N' in options:
+            n = len(patterns)
+            for pattern,res in patterns[0:n]:
+                # Swap 0 and 1
+                pattern = (pattern
+                           .replace('0','Z')
+                           .replace('1','0')
+                           .replace('Z','1'))
+                res = '%d'%(1-int(res))
+                patterns.append((pattern, res))
+
+        return patterns
+
+    def build_lut(self):
+        """Compile all patterns into a morphology lut.
+
+        TBD :Build based on (file) morphlut:modify_lut
+        """
+        self.build_default_lut()
+        patterns = []
+
+        # Parse and create symmetries of the patterns strings
+        for p in self.patterns:
+            m = re.search(r'(\w*):?\s*\((.+?)\)\s*->\s*(\d)', p.replace('\n',''))
+            if not m:
+                raise Exception('Syntax error in pattern "'+p+'"')
+            options = m.group(1)
+            pattern = m.group(2)
+            result = int(m.group(3))
+
+            # Get rid of spaces
+            pattern= pattern.replace(' ','').replace('\n','')
+
+            patterns += self._pattern_permute(pattern, options, result)
+
+#        # Debugging
+#        for p,r in patterns:
+#            print p,r
+#        print '--'
+
+        # compile the patterns into regular expressions for speed
+        for i in range(len(patterns)):
+            p = patterns[i][0].replace('.','X').replace('X','[01]')
+            p = re.compile(p)
+            patterns[i] = (p, patterns[i][1])
+
+        # Step through table and find patterns that match.
+        # Note that all the patterns are searched. The last one
+        # caught overrides
+        for i in range(LUT_SIZE):
+            # Build the bit pattern
+            bitpattern = bin(i)[2:]
+            bitpattern = ('0'*(9-len(bitpattern)) + bitpattern)[::-1]
+
+            for p,r in patterns:
+                if p.match(bitpattern):
+                    self.lut[i] = ['\0','\1'][r]
+
+        return self.lut
+
+class MorphOp:
+    """A class for binary morphological operators"""
+
+    def __init__(self,
+                 lut=None,
+                 op_name = None,
+                 patterns = None):
+        """Create a binary morphological operator"""
+        self.lut = lut
+        if op_name is not None:
+            self.lut = LutBuilder(op_name = op_name).build_lut()
+        elif patterns is not None:
+            self.lut = LutBuilder(patterns = patterns).build_lut()
+
+    def apply(self, image):
+        """Run a single morphological operation on an image
+
+        Returns a tuple of the number of changed pixels and the
+        morphed image"""
+        if self.lut is None:
+            raise Exception('No operator loaded')
+
+        outimage = Image.new(image.mode, image.size, None)
+        count = _imagingmorph.apply(str(self.lut), image.im.id, outimage.im.id)
+        return count, outimage
+
+    def match(self, image):
+        """Get a list of coordinates matching the morphological operation on an image
+
+        Returns a list of tuples of (x,y) coordinates of all matching pixels."""
+        if self.lut is None:
+            raise Exception('No operator loaded')
+
+        return  _imagingmorph.match(str(self.lut), image.im.id)
+
+    def get_on_pixels(self, image):
+        """Get a list of all turned on pixels in a binary image
+
+        Returns a list of tuples of (x,y) coordinates of all matching pixels."""
+
+        return  _imagingmorph.get_on_pixels(image.im.id)
+
+    def load_lut(self, filename):
+        """Load an operator from an mrl file"""
+        self.lut = bytearray(open(filename,'rb').read())
+        if len(self.lut)!= 8192:
+            self.lut = None
+            raise Exception('Wrong size operator file!')
+
+    def save_lut(self, filename):
+        """Load an operator save mrl file"""
+        if self.lut is None:
+            raise Exception('No operator loaded')
+        open(filename,'wb').write(self.lut)
+
+    def set_lut(self, lut):
+        """Set the lut from an external source"""
+        self.lut = lut
+
+

Tests/test_imagemorph.py

@@ -0,0 +1,138 @@
+# Test the ImageMorphology functionality
+from tester import *
+
+from PIL import Image
+from PIL import ImageMorph
+
+def img_to_string(im):
+    """Turn a (small) binary image into a string representation"""
+    chars = '.1'
+    width, height = im.size
+    return '\n'.join(
+        [''.join([chars[im.getpixel((c,r))>0] for c in range(width)])
+         for r in range(height)])
+
+def string_to_img(image_string):
+    """Turn a string image representation into a binary image"""
+    rows = [s for s in image_string.replace(' ','').split('\n')
+            if len(s)]
+    height = len(rows)
+    width = len(rows[0])
+    im = Image.new('L',(width,height))
+    for i in range(width):
+        for j in range(height):
+            c = rows[j][i]
+            v = c in 'X1'
+            im.putpixel((i,j),v)
+
+    return im
+
+def img_string_normalize(im):
+  return img_to_string(string_to_img(im))
+
+def assert_img_equal(A,B):
+  assert_equal(img_to_string(A), img_to_string(B))
+
+def assert_img_equal_img_string(A,Bstring):
+  assert_equal(img_to_string(A), img_string_normalize(Bstring))
+
+A = string_to_img(
+"""    
+.......
+.......
+..111..
+..111..
+..111..
+.......
+.......
+"""
+)    
+
+# Test the named patterns
+
+# erosion8
+mop = ImageMorph.MorphOp(op_name='erosion8')
+count,Aout = mop.apply(A)
+assert_equal(count,8)
+assert_img_equal_img_string(Aout,
+"""
+.......
+.......
+.......
+...1...
+.......
+.......
+.......
+""")
+
+# erosion8
+mop = ImageMorph.MorphOp(op_name='dilation8')
+count,Aout = mop.apply(A)
+assert_equal(count,16)
+assert_img_equal_img_string(Aout,
+"""
+.......
+.11111.
+.11111.
+.11111.
+.11111.
+.11111.
+.......
+""")
+
+# erosion4
+mop = ImageMorph.MorphOp(op_name='dilation4')
+count,Aout = mop.apply(A)
+assert_equal(count,12)
+assert_img_equal_img_string(Aout,
+"""
+.......
+..111..
+.11111.
+.11111.
+.11111.
+..111..
+.......
+""")
+
+# edge 
+mop = ImageMorph.MorphOp(op_name='edge')
+count,Aout = mop.apply(A)
+assert_equal(count,1)
+assert_img_equal_img_string(Aout,
+"""
+.......
+.......
+..111..
+..1.1..
+..111..
+.......
+.......
+""")
+
+# Create a corner detector pattern
+mop = ImageMorph.MorphOp(patterns = ['1:(... ... ...)->0',
+                                     '4:(00. 01. ...)->1'])
+count,Aout = mop.apply(A)
+assert_equal(count,5)
+assert_img_equal_img_string(Aout,
+"""
+.......
+.......
+..1.1..
+.......
+..1.1..
+.......
+.......
+""")
+
+# Test the coordinate counting with the same operator
+coords = mop.match(A)
+assert_equal(len(coords), 4)
+assert_equal(tuple(coords),
+             ((2,2),(4,2),(2,4),(4,4)))
+
+coords = mop.get_on_pixels(Aout)
+assert_equal(len(coords), 4)
+assert_equal(tuple(coords),
+             ((2,2),(4,2),(2,4),(4,4)))