image =	darkHysteresisThreshold2dImg (inImg,highSeedThreshold,highPropagationThreshold)
image =	lightHysteresisThreshold2dImg (inImg,lowSeedThreshold,lowPropagationThreshold)
image =	hysteresisThreshold2dImg (inImg,lowSeedThreshold,highSeedThreshold,lowPropagationThreshold,highPropagationThreshold)

Detailed Description

Apply hysteresis thresholding to an image.

Hysteresis threshold algorithm applies two thresholds $T_S$ and $T_P$ on the output image. $T_S$ is the most restrictive threshold and yields a seed image $I_S$ , used to propagate the marked features in $I_P$ , obtained by thresholding the input image by $T_P$ . This algorithm is commonly used in edge detection such as Canny edge detector.

The aim of this threshold is to preserve the features in $I_P$ containing a seed in $I_S$ .

The algorithm needs 4 thresholds: the minimum and maximum thresholds $T_S^{Min}$ and $T_S^{Max}$ to compute the seed image $I_S$ and the minimum and maximum thresholds $T_P^{Min}$ and $T_P^{Max}$ to compute the image $I_P$ , used for the propagation.

$\begin{eqnarray*} I_S[i] & = & \begin{cases} 1, & \text{if } T_S^{Min} \leq InImg[i] \leq T_S^{Max} \\ 0, & \text{otherwise} \end{cases} \\ I_P[i] & = & \begin{cases} 1, & \text{if } T_P^{Min} \leq InImg[i] \leq T_P^{Max} \\ 0, & \text{otherwise} \end{cases} \end{eqnarray*}$

To simplify the algorithm parametrization, several wrappers are defined to apply this threshold:

darkHysteresisThreshold2dImg: this wrapper only needs $T_S^{Max}$ and $T_P^{Max}$ , $T_S^{Min}$ and $T_S^{Min}$ being automatically set to the image buffer type minimum value. This allows to select dark features using darker seeds on light background.
lightHysteresisThreshold2dImg: this wrapper only needs $T_S^{Min}$ and $T_P^{Min}$ , $T_S^{Max}$ and $T_S^{Max}$ being automatically set to the image buffer type maximum value. This allows to select light features using lighter seeds on dark background.
hysteresisThreshold2dImg: this wrapper allows the user to determine the four thresholds. However, the following rules must be respected:
$\left\{ \begin{array}{ccc} T_S^{Min} & \leq & T_S^{Max} \\ T_P^{Min} & \leq & T_P^{Max} \\ T_S^{Max} & \leq & T_P^{Max} \end{array} \right.$

Here is an example of dark and light hysteresis threshold applied to a gray scale input image. The intensities of each area are indicated we used $T_S^{Max} = 4$ and $T_P^{Max} = 32$ for the dark threshold and $T_S^{Min} = 100$ and $T_P^{Min} = 64$ fot the light threshold:

The features and seeds intensities may be higher than the minimum image intensity and lower than the maximum image intensity. The hysteresisThreshold2dImg wrapper allows to handle this case, illustrated by the following figure. In this example, the background have an intensity of 50, the two little white circles have an intensity of 255, the intensity of the central main ellipse equals 96 and the two lighter ellipses inside have an intensity of 192 (left) and 128 (right). Finally, the intensity of the contour of the main ellipse varies from 12 to 44. The threshold used for the calculation are: $T_S^{Min} = 100$ , $T_P^{Min} = 60$ and $T_S^{Max} = T_P^{Max} = 200$ .

Example of Python code :

Example imports

import PyIPSDK

import PyIPSDK.IPSDKIPLBinarization as bin

Code Example

    # opening of input images
    inImg = PyIPSDK.loadTiffImageFile(inputImgPath)
    
    # threshold computation
    outImg = bin.hysteresisThreshold2dImg(inImg,  100,  127, 64, 127)

Example of C++ code :

Example informations

Header file

#include <IPSDKIPL/IPSDKIPLBinarization/Processor/HysteresisThreshold2dImg/HysteresisThreshold2dImg.h>

Code Example

            // Compute the dark hysteresis threshold
            // --------------------------------------
            ImagePtr pOutImg_dark = darkHysteresisThreshold2dImg(pInImg, threshSeedMax_dark, threshPropagationMax_dark);
            // Compute the light hysteresis threshold
            // --------------------------------------
            ImagePtr pOutImg_light = lightHysteresisThreshold2dImg(pInImg, threshSeedMin_light, threshPropagationMin_light);
            // Compute the hysteresis threshold with
            // custom params and provided ouput image
            // --------------------------------------
            const ipUInt64 sizeX = pInImg->getSizeX();
            const ipUInt64 sizeY = pInImg->getSizeY();
            // Create output image
            ImageGeometryPtr pOutputImageGeometry = geometry2d(eImageBufferType::eIBT_Binary, sizeX, sizeY);
            boost::shared_ptr<MemoryImage> pOutImg(boost::make_shared<MemoryImage>());
            pOutImg->init(*pOutputImageGeometry);
            // Compute the threshold
            hysteresisThreshold2dImg(pInImg, threshSeedMin, threshSeedMax, threshPropagationMin, threshPropagationMax, neighbourhood2d, pOutImg);