From 83616f0254bf33db6f886cdce2ebe1602c356d0a Mon Sep 17 00:00:00 2001
From: Andreas Mueller <amueller@ais.uni-bonn.de>
Date: Sun, 17 Jun 2012 23:01:24 +0200
Subject: [PATCH] DOC more docs....

---
 skimage/segmentation/felzenszwalb.py | 18 +++++++++++++++---
 skimage/segmentation/quickshift.pyx  | 23 ++++++++++++++++++-----
 2 files changed, 33 insertions(+), 8 deletions(-)

diff --git a/skimage/segmentation/felzenszwalb.py b/skimage/segmentation/felzenszwalb.py
index 6f2f89fc..b0467d57 100644
--- a/skimage/segmentation/felzenszwalb.py
+++ b/skimage/segmentation/felzenszwalb.py
@@ -3,13 +3,20 @@ import numpy as np
 
 from ._felzenszwalb import felzenszwalb_segmentation_grey
 
-from IPython.core.debugger import Tracer
-tracer = Tracer()
-
 
 def felzenszwalb_segmentation(image, scale=200, sigma=0.8):
     """Computes Felsenszwalb's segmentation for multi channel images.
 
+    Produces an oversegmentation of a multichannel (i.e. RGB) image
+    using a fast, minimum spanning tree based clustering on the image grid.
+    The parameter ``scale`` sets an observation level. Higher scale means
+    less and larger segments. ``sigma`` is the diameter of a Gaussian kernel,
+    used for smoothing the image prior to segmentation.
+
+    The number of produced segments as well as their size can only be
+    controlled indirectly through ``scale``. Segment size within an image can
+    vary greatly depending on local contrast.
+
     Calls the algorithm on each channel separately, then combines
     using "and", i.e. two pixels are in the same segment if they are
     in the same segment for each channel.
@@ -30,6 +37,11 @@ def felzenszwalb_segmentation(image, scale=200, sigma=0.8):
     -------
     segment_mask: ndarray, [width, height]
         Integer mask indicating segment labels.
+
+    References
+    ----------
+    .. [1] Efficient graph-based image segmentation, Felzenszwalb, P.F. and
+           Huttenlocher, D.P.  International Journal of Computer Vision, 2004
     """
 
     #image = img_as_float(image)
diff --git a/skimage/segmentation/quickshift.pyx b/skimage/segmentation/quickshift.pyx
index 7e27fc56..b47e5caa 100644
--- a/skimage/segmentation/quickshift.pyx
+++ b/skimage/segmentation/quickshift.pyx
@@ -10,7 +10,9 @@ cdef extern from "math.h":
 
 
 def quickshift(np.ndarray[dtype=np.float_t, ndim=3, mode="c"] image, sigma=5, tau=10, return_tree=False):
-    """Computes quickshift clustering in RGB-(x,y) space.
+    """Segments image using quickshift clustering in Color-(x,y) space.
+
+    Produces an oversegmentation of the image using the quickshift mode-seeking algorithm.
 
     Parameters
     ----------
@@ -29,26 +31,37 @@ def quickshift(np.ndarray[dtype=np.float_t, ndim=3, mode="c"] image, sigma=5, ta
     -------
     segment_mask: ndarray, [width, height]
         Integer mask indicating segment labels.
+
+    Notes
+    -----
+    The authors advocate to convert the image to Lab color space prior to segmentation.
+
+    References
+    ----------
+    .. [1] Quick shift and kernel methods for mode seeking, Vedaldi, A. and Soatto, S.
+           European Conference on Computer Vision, 2008
+
+
     """
 
     # We compute the distances twice since otherwise
-    # we might get crazy memory overhead (width * height * windowsize**2)
-    # if you want to speed up things: computing exp in C is the bottleneck ;)
+    # we get crazy memory overhead (width * height * windowsize**2)
 
     # TODO do smoothing beforehand?
     # TODO manage borders somehow?
+    # TODO join orphant roots?
 
     # window size for neighboring pixels to consider
     if sigma < 1:
         raise ValueError("Sigma should be >= 1")
     cdef int w = int(2 * sigma)
-    
+
     cdef int width = image.shape[0]
     cdef int height = image.shape[1]
     cdef int channels = image.shape[2]
     cdef float closest, dist
     cdef int x, y, xx, yy, x_, y_
-    
+
     cdef np.float_t* image_p = <np.float_t*> image.data
     cdef np.float_t* current_pixel_p = image_p
     cdef np.float_t* current_entry_p