DOC: add mosaic_threshold

doc/examples/segmentation/plot_thresholding.py

@@ -3,15 +3,42 @@
 Thresholding
 ============
 
-Thresholding is used to create a binary image. This example uses Otsu's method
-to calculate the threshold value.
+Thresholding is used to create a binary image from a grayscale image [1]_.
+
+Thresholding algorithms can be separated in two categories:
+    * Global. They are based on the histogram of the pixel intensity of
+    the image.
+    * Local. To process a pixel, only the neighboring pixels are used.
+    These algorithms often require more computation time.
+
+Scikit-image includes a function to test thresholding algorithms provided
+in the library. Therefore, in a glance, you can select the best algorithm
+for you data, without a deep understanding of their mechanisms.
+
+.. [1] https://en.wikipedia.org/wiki/Thresholding_%28image_processing%29
+
+"""
+from skimage.data import page
+
+img = page()
+
+# Here, we specify a radius for local thresholding algorithm.
+# If it is not specified, only global algorithms are called.
+fig, ax = mosaic_threshold(img, radius=20, figsize=(10,8), verbose=False)
+fig
+
+"""
+
+.. image:: PLOT2RST.current_figure
+
+This example uses Otsu's method [2]_ to calculate the threshold value.
 
 Otsu's method calculates an "optimal" threshold (marked by a red line in the
 histogram below) by maximizing the variance between two classes of pixels,
 which are separated by the threshold. Equivalently, this threshold minimizes
 the intra-class variance.
 
-.. [1] http://en.wikipedia.org/wiki/Otsu's_method
+.. [2] http://en.wikipedia.org/wiki/Otsu's_method
 
 """
 import matplotlib