Rename optimal_step and add comments

skimage/exposure/_adapthist.py

@@ -129,7 +129,7 @@ def _clahe(image, kernel_size, clip_limit, nbins=128):
     lut = np.arange(NR_OF_GREY)
     lut //= bin_size
 
-    img_view = view_as_windows(image, kernel_size, optimal_step=True)
+    img_view = view_as_windows(image, kernel_size, min_overlap=True)
     nr, nc = img_view.shape[:2]
     height = int(image.shape[0] / nr)
     width = int(image.shape[1] / nc)

skimage/util/shape.py

@@ -104,7 +104,7 @@ def view_as_blocks(arr_in, block_shape):
     return arr_out
 
 
-def view_as_windows(arr_in, window_shape, step=1, optimal_step=False):
+def view_as_windows(arr_in, window_shape, step=1, min_overlap=False):
     """Rolling window view of the input n-dimensional array.
 
     Windows are overlapping views of the input array, with adjacent windows
@@ -122,7 +122,7 @@ def view_as_windows(arr_in, window_shape, step=1, optimal_step=False):
     step : integer or tuple of length arr_in.ndim
         Indicates step size at which extraction shall be performed.
         If integer is given, then the step is uniform in all dimensions.
-    optimal_step: bool, optional
+    min_overlap: bool, optional
         When True, selects a ``step`` that will give full coverage of
         ``arr_in`` with minimal overlap.
 
@@ -229,13 +229,16 @@ def view_as_windows(arr_in, window_shape, step=1, optimal_step=False):
     if not (len(window_shape) == ndim):
         raise ValueError("`window_shape` is incompatible with `arr_in.shape`")
 
-    if optimal_step:
-        rem = np.array(arr_in.shape) - np.array(window_shape)
+    if min_overlap:
+        # start with no overlap
         step = list(window_shape)
-
+        # subtract the initial window shape from the overall shape
+        remainder = np.array(arr_in.shape) - np.array(window_shape)
+        # shrink the step size in each direction as needed
+        # to get full coverage
         for (ind, size) in enumerate(window_shape):
-            ns = int(np.ceil(arr_in.shape[ind] / size))
-            while step[ind] * (ns - 1) > rem[ind]:
+            num_steps = int(np.ceil(arr_in.shape[ind] / size))
+            while step[ind] * (num_steps - 1) > remainder[ind]:
                 step[ind] -= 1
 
     if isinstance(step, numbers.Number):