Image.threshold#

Image.threshold(threshold: int | float | str | None = None, opt: str | None = None, *, method: str = 'binary', nbins: int = 256, p: float = 50.0, as_bool: bool = False, t: int | float | str | None = None) → Any[source]#

Image threshold

Parameters:

  • threshold (scalar or str) – threshold value, or automatic selector name ('otsu', 'triangle' or 'percentile')

  • method (str, optional) – thresholding method for scalar threshold values, defaults to 'binary'

  • nbins (int, optional) – number of bins for histogram-based automatic methods, defaults to 256

  • p (float, optional) – percentile used when threshold='percentile', defaults to 50

  • as_bool (bool, optional) – return binary outputs as bool if True, otherwise uint8 with values 0/255, defaults to False

Returns:

thresholded image

Return type:

Image

Apply a threshold threshold to the image. The threshold condition is for the value greater than threshold. Various thresholding options are supported where \(t\) is the threshold value:

method

Function

Return data type

'binary'

\(Y_{u,v} = \left\{ \begin{array}{l} T \mbox{,if } X_{u,v} > t \\ F \mbox{, otherwise} \end{array} \right.\)

uint8 or bool

'binary_inv'

\(Y_{u,v} = \left\{ \begin{array}{l} F \mbox{, if } X_{u,v} > t \\ T \mbox{, otherwise} \end{array}\right.\)

uint8 or bool

'truncate'

\(Y_{u,v} = \left\{ \begin{array}{l} t \mbox{,if } X_{u,v} > t \\ X_{u,v} \mbox{, otherwise} \end{array} \right.\)

same as \(X\)

'tozero'

\(Y_{u,v} = \left\{ \begin{array}{l} X_{u,v} \mbox{, if } X_{u,v} > t \\ 0 \mbox{, otherwise} \end{array}\right.\)

same as \(X\)

'tozero_inv'

\(Y_{u,v} = \left\{ \begin{array}{l} 0 \mbox{, if } X_{u,v} > t \\ X_{u,v} \mbox{, otherwise} \end{array}\right.\)

same as \(X\)

For the case where the return data type is uint8 the return pixel values are either \(F=0\) or \(T=255\). For the case where as_bool is True then the return data type is bool and the pixel values are either \(F=False\) or \(T=True\).

If threshold is a string then the threshold is determined automaticly prior to executing the logic above. The following automatic threshold selection methods are supported:

threshold

algorithm

'otsu'

Otsu’s method finds the threshold that minimizes the within-class variance. This technique is effective for a bimodal greyscale histogram.

'triangle'

The triangle method constructs a line between the histogram peak and the farthest end of the histogram. The threshold is the point of maximum distance between the line and the histogram. This technique is effective when the object pixels produce a weak peak in the histogram.

'percentile'

Select threshold from the image percentile given by p (0 to 100).

Example:

>>> from machinevisiontoolbox import Image
>>> img = Image([[1, 2, 3], [4, 5, 6], [7, 8, 9]])
>>> img.threshold(5).print()
     0   0   0
     0   0 255
   255 255 255
>>> img.threshold('otsu')
(Image(size=(3, 3), dtype=uint8), np.uint8(4))
>>> img.threshold('percentile', p=90)
(Image(size=(3, 3), dtype=uint8), np.uint8(8))
References:

  • A Threshold Selection Method from Gray-Level Histograms, N. Otsu. IEEE Trans. Systems, Man and Cybernetics Vol SMC-9(1), Jan 1979, pp 62-66.

  • Automatic measurement of sister chromatid exchange frequency” Zack (Zack GW, Rogers WE, Latt SA (1977), J. Histochem. Cytochem. 25 (7): 741–53.

  • P. Corke, Robotics, Vision & Control for Python, Springer, 2023, Section 12.1.1.

Note

Uses NumPy thresholding and toolbox-native Otsu and triangle threshold selection, not OpenCV functions, to support a wider range of datatypes and automatic threshold selection methods.

Seealso:

threshold_interactive threshold_adaptive_ otsu triangle