From 64177b2000ea7a41a5a35d263ce00870f3693d79 Mon Sep 17 00:00:00 2001
From: Nicolas Pinto <pinto@alum.mit.edu>
Date: Tue, 14 Feb 2012 00:04:42 -0500
Subject: [PATCH] ENH: add a 'normalize' kwarg to util.montage2d()

---
 CONTRIBUTORS.txt        |  7 ++++---
 skimage/util/montage.py | 18 ++++++++++++++++--
 2 files changed, 20 insertions(+), 5 deletions(-)

diff --git a/CONTRIBUTORS.txt b/CONTRIBUTORS.txt
index bea4d230..5082c508 100644
--- a/CONTRIBUTORS.txt
+++ b/CONTRIBUTORS.txt
@@ -2,8 +2,9 @@
   Project coordination
 
 - Nicolas Pinto
-  Colour spaces and filters
-  Shape views: ``shape.view_as_windows`` and ``shape.view_as_blocks``
+  Colour spaces and filters.
+  Shape views: ``util.shape.view_as_windows`` and ``util.shape.view_as_blocks``
+  Montage helpers: ``util.montage``
 
 - Damian Eads
   Morphological operators
@@ -96,4 +97,4 @@
   Harris corner detector
 
 - Nicolas Poilvert
-  Shape views: ``shape.view_as_windows`` and ``shape.view_as_blocks``
+  Shape views: ``util.shape.view_as_windows`` and ``util.shape.view_as_blocks``
diff --git a/skimage/util/montage.py b/skimage/util/montage.py
index 15646440..0319fe84 100644
--- a/skimage/util/montage.py
+++ b/skimage/util/montage.py
@@ -2,8 +2,10 @@ __all__ = ['montage2d']
 
 import numpy as np
 
+EPSILON = 1e-6
 
-def montage2d(arr_in, fill='mean'):
+
+def montage2d(arr_in, fill='mean', normalize=True):
     """Create a 2-dimensional 'montage' from a 3-dimensional input array
     representing an ensemble of equally shaped 2-dimensional images.
 
@@ -29,10 +31,13 @@ def montage2d(arr_in, fill='mean'):
         3-dimensional input array representing an ensemble of n_images
         of equal shape (i.e. [height, width]).
 
-    fill: float or 'mean'
+    fill: float or 'mean', optional
         How to fill the 2-dimensional output array when sqrt(n_images)
         is not an integer. If 'mean' is chosen, then fill = arr_in.mean().
 
+    normalize: bool, optional
+        Whether to normalize each image with zero-mean, unit-variance.
+
     Returns
     -------
     arr_out: ndarray, shape=[alpha * height, alpha * width]
@@ -68,6 +73,15 @@ def montage2d(arr_in, fill='mean'):
 
     n_images, height, width = arr_in.shape
 
+    # -- normalize if necessary
+    if normalize:
+        arr_in = arr_in.T
+        arr_in -= arr_in.mean(0)
+        astd = arr_in.std(0)
+        astd[astd < EPSILON] = 1
+        arr_in /= astd
+        arr_in = arr_in.T
+
     # -- determine alpha
     alpha = int(np.ceil(np.sqrt(n_images)))