From 455349a0ebe6b275867e20111762ba4da21a9378 Mon Sep 17 00:00:00 2001
From: Alexander Mordvintsev <no@email>
Date: Wed, 6 Jun 2012 05:52:28 +0000
Subject: [PATCH] comments for digits.py sample

---
 samples/python2/common.py | 20 +++++++++
 samples/python2/digits.py | 91 +++++++++++++++++----------------------
 2 files changed, 60 insertions(+), 51 deletions(-)

diff --git a/samples/python2/common.py b/samples/python2/common.py
index 54e23d60d8..0eb49b8ea6 100644
--- a/samples/python2/common.py
+++ b/samples/python2/common.py
@@ -2,6 +2,7 @@ import numpy as np
 import cv2
 import os
 from contextlib import contextmanager
+import itertools as it
 
 image_extensions = ['.bmp', '.jpg', '.jpeg', '.png', '.tif', '.tiff', '.pbm', '.pgm', '.ppm']
 
@@ -170,3 +171,22 @@ class RectSelector:
             return
         x0, y0, x1, y1 = self.drag_rect
         cv2.rectangle(vis, (x0, y0), (x1, y1), (0, 255, 0), 2)
+
+
+def grouper(n, iterable, fillvalue=None):
+    '''grouper(3, 'ABCDEFG', 'x') --> ABC DEF Gxx'''
+    args = [iter(iterable)] * n
+    return it.izip_longest(fillvalue=fillvalue, *args)
+
+def mosaic(w, imgs):
+    '''Make a grid from images. 
+
+    w    -- number of grid columns
+    imgs -- images (must have same size and format)
+    '''
+    imgs = iter(imgs)
+    img0 = imgs.next()
+    pad = np.zeros_like(img0)
+    imgs = it.chain([img0], imgs)
+    rows = grouper(w, imgs, pad)
+    return np.vstack(map(np.hstack, rows))
diff --git a/samples/python2/digits.py b/samples/python2/digits.py
index c3494c0bb4..f4bb0a5cd0 100644
--- a/samples/python2/digits.py
+++ b/samples/python2/digits.py
@@ -1,89 +1,78 @@
+'''
+Neural network digit recognition sample.
+Usage:
+   digits.py
+
+   Sample loads a dataset of handwritten digits from 'digits.png'.
+   Then it trains a neural network classifier on it and evaluates
+   its classification accuracy.
+'''
+
 import numpy as np
 import cv2
-import itertools as it
-
-'''
-from scipy.io import loadmat
-
-m = loadmat('ex4data1.mat')
-X = m['X'].reshape(-1, 20, 20)
-X = np.transpose(X, (0, 2, 1))
-img = np.vstack(map(np.hstack, X.reshape(-1, 100, 20, 20)))
-img = np.uint8(np.clip(img, 0, 1)*255)
-cv2.imwrite('digits.png', img)
-'''
+from common import mosaic
 
 def unroll_responses(responses, class_n):
+    '''[1, 0, 2, ...] -> [[0, 1, 0], [1, 0, 0], [0, 0, 1], ...]'''
     sample_n = len(responses)
     new_responses = np.zeros((sample_n, class_n), np.float32)
     new_responses[np.arange(sample_n), responses] = 1
     return new_responses
     
 
-SZ = 20
+SZ = 20 # size of each digit is SZ x SZ
+CLASS_N = 10
 digits_img = cv2.imread('digits.png', 0)
 
+# prepare dataset
 h, w = digits_img.shape
 digits = [np.hsplit(row, w/SZ) for row in np.vsplit(digits_img, h/SZ)]
 digits = np.float32(digits).reshape(-1, SZ*SZ)
 N = len(digits)
-labels = np.repeat(np.arange(10), N/10)
+labels = np.repeat(np.arange(CLASS_N), N/CLASS_N)
 
+# split it onto train and test subsets
 shuffle = np.random.permutation(N)
 train_n = int(0.9*N)
-
 digits_train, digits_test = np.split(digits[shuffle], [train_n])
 labels_train, labels_test = np.split(labels[shuffle], [train_n])
 
-labels_train_unrolled = unroll_responses(labels_train, 10)
-
+# train model
 model = cv2.ANN_MLP()
-layer_sizes = np.int32([SZ*SZ, 25, 10])
+layer_sizes = np.int32([SZ*SZ, 25, CLASS_N])
 model.create(layer_sizes)
-        
-# CvANN_MLP_TrainParams::BACKPROP,0.001
-params = dict( term_crit = (cv2.TERM_CRITERIA_COUNT, 300, 0.01),
+params = dict( term_crit = (cv2.TERM_CRITERIA_COUNT, 100, 0.01),
                train_method = cv2.ANN_MLP_TRAIN_PARAMS_BACKPROP,
                bp_dw_scale = 0.001,
                bp_moment_scale = 0.0 )
 print 'training...'
+labels_train_unrolled = unroll_responses(labels_train, CLASS_N)
 model.train(digits_train, labels_train_unrolled, None, params=params)
 model.save('dig_nn.dat')
 model.load('dig_nn.dat')
 
-ret, resp = model.predict(digits_test)
-resp = resp.argmax(-1)
-error_mask = (resp == labels_test)
-print error_mask.mean()
+def evaluate(model, samples, labels):
+    '''Evaluates classifier preformance on a given labeled samples set.'''
+    ret, resp = model.predict(samples)
+    resp = resp.argmax(-1)
+    error_mask = (resp == labels)
+    accuracy = error_mask.mean()
+    return accuracy, error_mask
 
-def grouper(n, iterable, fillvalue=None):
-    "grouper(3, 'ABCDEFG', 'x') --> ABC DEF Gxx"
-    args = [iter(iterable)] * n
-    return it.izip_longest(fillvalue=fillvalue, *args)
+# evaluate model
+train_accuracy, _ = evaluate(model, digits_train, labels_train)
+print 'train accuracy: ', train_accuracy
+test_accuracy, test_error_mask = evaluate(model, digits_test, labels_test)
+print 'test accuracy: ', test_accuracy
 
-def mosaic(w, imgs):
-    imgs = iter(imgs)
-    img0 = imgs.next()
-    pad = np.zeros_like(img0)
-    imgs = it.chain([img0], imgs)
-    rows = grouper(w, imgs, pad)
-    return np.vstack(map(np.hstack, rows))
-
-test_img = np.uint8(digits_test).reshape(-1, SZ, SZ)
-
-def vis_resp(img, flag):
+# visualize test results
+vis = []
+for img, flag in zip(digits_test, test_error_mask):
+    img = np.uint8(img).reshape(SZ, SZ)
     img = cv2.cvtColor(img, cv2.COLOR_GRAY2BGR)
     if not flag:
         img[...,:2] = 0
-    return img
-
-test_img = mosaic(25, it.starmap(vis_resp, it.izip(test_img, error_mask)))
-cv2.imshow('test', test_img)
+    vis.append(img)
+vis = mosaic(25, vis)
+cv2.imshow('test', vis)
 cv2.waitKey()
-
-
-
-
-
-
-