Debian Codegraph @

dask_image/ndfilters/_threshold.py

raw
1 import numpy as np
2
3 from ..dispatch._dispatch_ndfilters import dispatch_threshold_local_mean
4 from . import _gaussian, _generic, _order
5
6 __all__ = [
7 "threshold_local",
8 ]
9
10
11 def threshold_local(image, block_size, method='gaussian', offset=0,
12 mode='reflect', param=None, cval=0):
13 """Compute a threshold mask image based on local pixel neighborhood.
14
15 Also known as adaptive or dynamic thresholding[1]_. The threshold value is
16 the weighted mean for the local neighborhood of a pixel subtracted by a
17 constant. Alternatively the threshold can be determined dynamically by a
18 given function, using the 'generic' method.
19
20 Parameters
21 ----------
22 image : (N, M) dask ndarray
23 Input image.
24 block_size : int or list/tuple/array
25 Size of pixel neighborhood which is used to calculate the
26 threshold value.
27 (1) A single value for use in all dimensions or
28 (2) A tuple, list, or array with length equal to image.ndim
29 method : {'generic', 'gaussian', 'mean', 'median'}, optional
30 Method used to determine adaptive threshold for local neighbourhood in
31 weighted mean image.
32
33 * 'generic': use custom function (see `param` parameter)
34 * 'gaussian': apply gaussian filter (see `param` parameter for custom\
35 sigma value)
36 * 'mean': apply arithmetic mean filter
37 * 'median': apply median rank filter
38
39 By default the 'gaussian' method is used.
40 offset : float, optional
41 Constant subtracted from weighted mean of neighborhood to calculate
42 the local threshold value. Default offset is 0.
43 mode : {'reflect', 'constant', 'nearest', 'mirror', 'wrap'}, optional
44 The mode parameter determines how the array borders are handled, where
45 cval is the value when mode is equal to 'constant'.
46 Default is 'reflect'.
47 param : {int, function}, optional
48 Either specify sigma for 'gaussian' method or function object for
49 'generic' method. This functions takes the flat array of local
50 neighbourhood as a single argument and returns the calculated
51 threshold for the centre pixel.
52 cval : float, optional
53 Value to fill past edges of input if mode is 'constant'.
54
55 Returns
56 -------
57 threshold : (N, M) dask ndarray
58 Threshold image. All pixels in the input image higher than the
59 corresponding pixel in the threshold image are considered foreground.
60
61 References
62 ----------
63 .. [1] https://docs.opencv.org/modules/imgproc/doc/miscellaneous_transformations.html?highlight=threshold
64
65 Examples
66 --------
67 >>> import dask.array as da
68 >>> image = da.random.random((1000, 1000), chunks=(100, 100))
69 >>> result = threshold_local(image, 15, 'gaussian')
70 """ # noqa
71
72 image = image.astype(np.float64)
73
74 if method == 'generic':
75 if not callable(param):
76 raise ValueError("Must include a valid function to use as the "
77 "'param' keyword argument.")
78 thresh_image = _generic.generic_filter(image, param, block_size,
79 mode=mode, cval=cval)
80 elif method == 'gaussian':
81 if param is None:
82 sigma = (np.array(block_size).astype(float) - 1) / 6.0
83 else:
84 sigma = param
85 thresh_image = _gaussian.gaussian_filter(image, sigma, mode=mode,
86 cval=cval)
87 elif method == 'mean':
88 thresh_image = _generic.generic_filter(
89 image, dispatch_threshold_local_mean(image), block_size, mode=mode,
90 cval=cval)
91 elif method == 'median':
92 thresh_image = _order.median_filter(image, block_size, mode=mode,
93 cval=cval)
94 else:
95 raise ValueError("Invalid method specified. Please use `generic`, "
96 "`gaussian`, `mean`, or `median`.")
97 return thresh_image - offset