dyn_thresholdDynThresholdDynThresholddyn_thresholddyn_threshold🔗

Short description🔗

dyn_thresholdDynThresholdDynThresholddyn_thresholddyn_threshold — Segment an image using a local threshold.

Signature🔗

dyn_threshold( image OrigImage, image ThresholdImage, out region RegionDynThresh, number Offset, string LightDark )

Description🔗

dyn_thresholdDynThreshold selects from the input image those regions in which the pixels fulfill a threshold condition. Let \(g_{o} = g_{\textrm{OrigImage}}\), and \(g_{t} = g_{\textrm{ThresholdImage}}\). Then the condition for LightDarklightDarklight_dark = 'light'"light" is:

\[\begin{eqnarray*} g_{o} \ge g_{t} + \textrm{Offset} \end{eqnarray*}\]

For LightDarklightDarklight_dark = 'dark'"dark" the condition is:

\[\begin{eqnarray*} g_{o} \le g_{t} - \textrm{Offset} \end{eqnarray*}\]

For LightDarklightDarklight_dark = 'equal'"equal" it is:

\[\begin{eqnarray*} g_{t} - \textrm{Offset} \le g_{o} \le g_{t} + \textrm{Offset} \end{eqnarray*}\]

Finally, for LightDarklightDarklight_dark = 'not_equal'"not_equal" it is:

\[\begin{eqnarray*} g_{t} - \textrm{Offset} > g_{o} \vee g_{o} > g_{t} + \textrm{Offset} \end{eqnarray*}\]

Typically, the threshold images are smoothed versions of the original image (e.g., by applying mean_imageMeanImage, binomial_filterBinomialFilter, gauss_filterGaussFilter, etc.). Then the effect of dyn_thresholdDynThreshold is similar to applying thresholdThreshold to a highpass-filtered version of the original image (see highpass_imageHighpassImage).

With dyn_thresholdDynThreshold, contours of an object can be extracted, where the objects’ size (diameter) is determined by the mask size of the lowpass filter and the amplitude of the objects’ edges:

The larger the mask size is chosen, the larger the found regions become. As a rule of thumb, the mask size should be about twice the diameter of the objects to be extracted. It is important not to set the parameter Offsetoffsetoffset to zero because in this case too many small regions will be found (noise). Values between 5 and 40 are a useful choice. The larger Offsetoffsetoffset is chosen, the smaller the extracted regions become.

All points of the input image fulfilling the above condition are stored jointly in one region. If necessary, the connected components can be obtained by calling connectionConnection.

Attention🔗

If Offsetoffsetoffset is chosen from -1 to 1 usually a very noisy region is generated, requiring large storage. If Offsetoffsetoffset is chosen too large (\(>\) 60, say) it may happen that no points fulfill the threshold condition (i.e., an empty region is returned). If Offsetoffsetoffset is chosen too small (\(<\) -60, say) it may happen that all points fulfill the threshold condition (i.e., a full region is returned).

Execution information🔗

Execution information

Multithreading type: reentrant (runs in parallel with non-exclusive operators).
Multithreading scope: global (may be called from any thread).
Automatically parallelized on domain level.

Parameters🔗

OrigImageorigImageorig_image (input_object) singlechannelimage(-array) → object (byte / int2 / uint2 / int4 / real)

Input image.

ThresholdImagethresholdImagethreshold_image (input_object) singlechannelimage(-array) → object (byte / int2 / uint2 / int4 / real)

Image containing the local thresholds.

RegionDynThreshregionDynThreshregion_dyn_thresh (output_object) region(-array) → objectHObjectHRegionHObjectHobject *

Segmented regions.

Offsetoffsetoffset (input_control) number → (real / integer)HTuple (double / Hlong)HTuple (double / int / long)Union[int, float]Htuple (double / Hlong)

Offset applied to ThresholdImage.

Default: 5.05.0
Suggested values: 1.0, 3.0, 5.0, 7.0, 10.0, 20.0, 30.01.0, 3.0, 5.0, 7.0, 10.0, 20.0, 30.0
Value range: -255.0 ≤ Offset ≤ 255.0 (lin)
Minimum increment: 0.01
Recommended increment: 5

LightDarklightDarklight_dark (input_control) string → (string)HTuple (HString)HTuple (string)strHtuple (char*)

Extract light, dark or similar areas?

Default: 'light'"light"
List of values: 'dark', 'equal', 'light', 'not_equal'"dark", "equal", "light", "not_equal"

Example🔗

(HDevelop)

* Looking for regions with the diameter D
mean_image(Image,Mean,D*2+1,D*2+1)
dyn_threshold(Image,Mean,Seg,5,'light')
connection(Seg,Regions)

(C)

/* Looking for regions with the diameter D */
mean_image(Image,&Mean,D*2+1,D*2+1)\;
dyn_threshold(Image,Mean,&Seg,5.0,"light")\;
connection(Seg,&Region)\;

(C++)

#include "HIOStream.h"
#if !defined(USE_IOSTREAM_H)
using namespace std\;
#endif
#include "HalconCpp.h"
using namespace Halcon\;

int main (int argc, char *argv[])
{
  HImage   image ("monkey"),
           mean\;
  HWindow  win\;
 if (argc != 2)
  {
    cout << "Using: " << argv[0] << " <diameter>" << endl\;
    exit (1)\;
  }
 int d = atoi (argv[1]) * 2 + 1\;
 image.Display (win)\;
 mean = image.MeanImage (d, d)\;
 HRegionArray seg = image.DynThreshold (mean, 5.0, "light")\;
  HRegionArray reg = seg.Connection ()\;
 win.SetColored (12)\;
  reg.Display (win)\;
  win.Click ()\;
 return (0)\;
}

Complexity🔗

Let \(A\) be the area of the input region. Then the runtime complexity is \(O(A)\).

Result🔗

dyn_thresholdDynThreshold returns 2 (H_MSG_TRUE) if all parameters are correct. The behavior with respect to the input images and output regions can be determined by setting the values of the flags 'no_object_result'"no_object_result", 'empty_region_result'"empty_region_result", and 'store_empty_region'"store_empty_region" with set_systemSetSystem. If necessary, an exception is raised.

Combinations with other operators🔗

Combinations

Possible predecessors

mean_imageMeanImage, smooth_imageSmoothImage, binomial_filterBinomialFilter, gauss_filterGaussFilter

Possible successors

connectionConnection, select_shapeSelectShape, reduce_domainReduceDomain, select_graySelectGray, rank_regionRankRegion, dilation1Dilation1, openingOpening, erosion1Erosion1

Alternatives

check_differenceCheckDifference, thresholdThreshold

Module🔗

Foundation