DOC Better documentation of code

Author: luispedro

ch10/edginess.py

@@ -10,10 +10,12 @@
 
 
 def edginess_sobel(image):
-    '''
-    edgi = edginess_sobel(image)
+    '''Measure the "edginess" of an image
+
+    image should be a 2d numpy array (an image)
+
+    Returns a floating point value which is higher the "edgier" the image is.
 
-    Measure the "edginess" of an image
     '''
     edges = mh.sobel(image, just_filter=True)
     edges = edges.ravel()

ch10/figure10.py

@@ -8,6 +8,8 @@
 import numpy as np
 import mahotas as mh
 
+# This little script just builds an image with two examples, side-by-side:
+
 text = mh.imread("simple-dataset/text21.jpg")
 scene = mh.imread("simple-dataset/scene00.jpg")
 h, w, _ = text.shape

ch10/figure13.py

@@ -9,12 +9,19 @@
 from mahotas.colors import rgb2grey
 import numpy as np
 
+# Adds a little salt-n-pepper noise to an image
+
 im = mh.imread('lenna.jpg')
 im = rgb2grey(im)
 
+# Salt & pepper arrays
 salt = np.random.random(im.shape) > .975
 pepper = np.random.random(im.shape) > .975
 
+# salt is 170 & pepper is 30
+# Some playing around showed that setting these to more extreme values looks
+# very artificial. These look nicer
+
 im = np.maximum(salt * 170, mh.stretch(im))
 im = np.minimum(pepper * 30 + im * (~pepper), im)
 

ch10/lenna-ring.py

@@ -7,23 +7,35 @@
 
 import mahotas as mh
 import numpy as np
+
+# Read in the image
 im = mh.imread('lenna.jpg')
+
+# This breaks up the image into RGB channels
 r, g, b = im.transpose(2, 0, 1)
 h, w = r.shape
+
+# smooth the image per channel:
 r12 = mh.gaussian_filter(r, 12.)
 g12 = mh.gaussian_filter(g, 12.)
 b12 = mh.gaussian_filter(b, 12.)
+
+# build back the RGB image
 im12 = mh.as_rgb(r12, g12, b12)
 
 X, Y = np.mgrid[:h, :w]
 X = X - h / 2.
 Y = Y - w / 2.
 X /= X.max()
 Y /= Y.max()
+
+# Array C will have the highest values in the center, fading out to the edges:
+
 C = np.exp(-2. * (X ** 2 + Y ** 2))
 C -= C.min()
 C /= C.ptp()
 C = C[:, :, None]
 
+# The final result is sharp in the centre and smooths out to the borders:
 ring = mh.stretch(im * C + (1 - C) * im12)
 mh.imsave('lenna-ring.jpg', ring)