Docstring of graph_cut.py

skimage/graph/graph_cut.py

@@ -67,8 +67,44 @@ def cut_threshold(labels, rag, thresh):
     return map_array[labels]
 
 
-def cut_n(labels, rag, thresh):
+def cut_n(labels, rag, thresh=0.0001):
+    """Perform Normalized Graph cut on the Region Adjacency Graph.
 
+    Given an image's labels and its similarity RAG, recursively perform
+    a 2-wat Normalized cut on it. All nodes belonging to a subgraph
+    which cannot be cut further, are assigned a unique label in the
+    output.
+
+    Parameters
+    ----------
+    labels : ndarray
+        The array of labels.
+    rag : RAG
+        The region adjacency graph.
+    thresh : float
+        The threshold. A subgraph won't be further subdivided if the
+        value of the N-cut exceeds `thresh`.
+
+    Returns
+    -------
+    out : ndarray
+        The new labelled array.
+
+    Examples
+    --------
+    >>> from skimage import data, graph, segmentation, color, io
+    >>> img = data.lena()
+    >>> labels = segmentation.slic(img, compactness=30, n_segments=400)
+    >>> rag = graph.rag_mean_color(img, labels, mode='similarity')
+    >>> new_labels = graph.cut_n(labels, rag)
+
+    References
+    ----------
+    .. [1] Shi, J.; Malik, J., "Normalized cuts and image segmentation",
+           Pattern Analysis and Machine Intelligence,
+           IEEE Transactions on , vol.22, no.8, pp.888,905, Aug 2000
+
+    """
     _ncut_relabel(rag, thresh)
 
     from_ = range(labels.max() + 1)
@@ -78,7 +114,24 @@ def cut_n(labels, rag, thresh):
     return map_array[labels]
 
 
-def _ncut_relabel(rag, cut_thresh=0.0001):
+def _ncut_relabel(rag, thresh):
+    """Perform Normalized Graph cut on the Region Adjacency Graph.
+
+    Recursively partition the graph into 2, untill further subdividing
+    yields a cut greather than `thresh` or such a cut cannot be computed.
+    For such a subgraph, assign a 'ncut label` attribute to all its nodes,
+    which is a their new unique label.
+
+    Parameters
+    ----------
+    labels : ndarray
+        The array of labels.
+    rag : RAG
+        The region adjacency graph.
+    thresh : float
+        The threshold. A subgraph won't be further subdivided if the
+        value of the N-cut exceeds `thresh`.
+    """
     d, w = _ncut.DW_matrix(rag)
     error = False
 
@@ -112,7 +165,7 @@ def _ncut_relabel(rag, cut_thresh=0.0001):
                 mcut = cost
                 thresh = t
 
-        if (mcut < cut_thresh):
+        if (mcut < thresh):
             mask = ev > thresh
 
             nodes1 = [n for i, n in enumerate(rag.nodes()) if mask[i]]
@@ -121,8 +174,8 @@ def _ncut_relabel(rag, cut_thresh=0.0001):
             sub1 = rag.subgraph(nodes1)
             sub2 = rag.subgraph(nodes2)
 
-            _ncut_relabel(sub1, cut_thresh)
-            _ncut_relabel(sub2, cut_thresh)
+            _ncut_relabel(sub1, thresh)
+            _ncut_relabel(sub2, thresh)
             return
 
     node = rag.nodes()[0]

skimage/graph/rag.py

@@ -120,7 +120,7 @@ def _add_edge_filter(values, graph):
 
 
 def rag_mean_color(image, labels, connectivity=2, mode='dissimilarity',
-                   sigma=30.0):
+                   sigma=255.0):
     """Compute the Region Adjacency Graph using mean colors.
 
     Given an image and its initial segmentation, this method constructs the