Operator Reference

HALCON Operator Reference / Segmentation / Topography
ClassesClasses | | Operators

pouringpouringPouringPouringpouring (Operator)

pouringpouringPouringPouringpouring — Segment an image by “pouring water” over it.

Signature

pouring(Image : Regions : Mode, MinGray, MaxGray : )

Herror pouring(const Hobject Image, Hobject* Regions, const char* Mode, const Hlong MinGray, const Hlong MaxGray)

Herror T_pouring(const Hobject Image, Hobject* Regions, const Htuple Mode, const Htuple MinGray, const Htuple MaxGray)

void Pouring(const HObject& Image, HObject* Regions, const HTuple& Mode, const HTuple& MinGray, const HTuple& MaxGray)

HRegion HImage::Pouring(const HString& Mode, Hlong MinGray, Hlong MaxGray) const

HRegion HImage::Pouring(const char* Mode, Hlong MinGray, Hlong MaxGray) const

HRegion HImage::Pouring(const wchar_t* Mode, Hlong MinGray, Hlong MaxGray) const   ( Windows only)

static void HOperatorSet.Pouring(HObject image, out HObject regions, HTuple mode, HTuple minGray, HTuple maxGray)

HRegion HImage.Pouring(string mode, int minGray, int maxGray)

def pouring(image: HObject, mode: str, min_gray: int, max_gray: int) -> HObject

Description

pouringpouringPouringPouringpouring regards the input image as a “mountain range.” Larger gray values correspond to mountain peaks, while smaller gray values correspond to valley bottoms. pouringpouringPouringPouringpouring segments the input image in several steps. First, the local maxima are extracted, i.e., pixels which either alone or in the form of an extended plateau have larger gray values than their immediate neighbors (in 4-neighborhood). In the next step, the maxima thus found are the starting points for an expansion until “valley bottoms” are reached. The expansion is done as long as there are chains of pixels in which the gray value becomes smaller (like water running downhill from the maxima in all directions). Again, the 4-neighborhood is used, but with a weaker condition (smaller or equal). This means that points at valley bottoms may belong to more than one maximum. These areas are at first not assigned to a region, but rather are split among all competing segments in the last step. The split is done by a uniform expansion of all involved segments, until all ambiguous pixels were assigned. The parameter ModeModeModemodemode determines which steps are executed. The following values are possible:

'all'"all""all""all""all"

This is the normal mode of operation. All steps of the segmentation are performed. The regions are assigned to maxima, and overlapping regions are split.

'maxima'"maxima""maxima""maxima""maxima"

The segmentation only extracts the local maxima of the input image. No corresponding regions are extracted.

'regions'"regions""regions""regions""regions"

The segmentation extracts the local maxima of the input image and the corresponding regions, which are uniquely determined. Areas that were assigned to more than one maximum are not split.

In order to prevent the algorithm from splitting a uniform background that is different from the rest of the image, the parameters MinGrayMinGrayMinGrayminGraymin_gray and MaxGrayMaxGrayMaxGraymaxGraymax_gray determine gray value thresholds for regions in the image that should be regarded as background. All parts of the image having a gray value smaller than MinGrayMinGrayMinGrayminGraymin_gray or larger than MaxGrayMaxGrayMaxGraymaxGraymax_gray are disregarded for the extraction of the maxima as well as for the assignment of regions. For a complete segmentation of the image, MinGrayMinGrayMinGrayminGraymin_gray = 0 and MaxGrayMaxGrayMaxGraymaxGraymax_gray = 255 should be selected. MinGrayMinGrayMinGrayminGraymin_gray < MaxGrayMaxGrayMaxGraymaxGraymax_gray must be observed.

Execution Information

  • Multithreading type: mutually exclusive (runs in parallel with other non-exclusive operators, but not with itself).
  • Multithreading scope: global (may be called from any thread).
  • Processed without parallelization.

Parameters

ImageImageImageimageimage (input_object)  singlechannelimage → objectHImageHObjectHObjectHobject (byte)

Input image.

RegionsRegionsRegionsregionsregions (output_object)  region-array → objectHRegionHObjectHObjectHobject *

Segmented regions.

ModeModeModemodemode (input_control)  string → HTuplestrHTupleHtuple (string) (string) (HString) (char*)

Mode of operation.

Default: 'all' "all" "all" "all" "all"

List of values: 'all'"all""all""all""all", 'maxima'"maxima""maxima""maxima""maxima", 'regions'"regions""regions""regions""regions"

MinGrayMinGrayMinGrayminGraymin_gray (input_control)  integer → HTupleintHTupleHtuple (integer) (int / long) (Hlong) (Hlong)

All gray values smaller than this threshold are disregarded.

Default: 0

Suggested values: 0, 10, 20, 30, 40, 50, 60, 70, 80, 90, 100, 110

Value range: 0 ≤ MinGray MinGray MinGray minGray min_gray ≤ 254 (lin)

Minimum increment: 1

Recommended increment: 10

MaxGrayMaxGrayMaxGraymaxGraymax_gray (input_control)  integer → HTupleintHTupleHtuple (integer) (int / long) (Hlong) (Hlong)

All gray values larger than this threshold are disregarded.

Default: 255

Suggested values: 100, 110, 120, 130, 140, 150, 160, 170, 180, 190, 200, 210, 220, 230, 240, 250, 255

Value range: 1 ≤ MaxGray MaxGray MaxGray maxGray max_gray ≤ 255 (lin)

Minimum increment: 1

Recommended increment: 10

Restriction: MaxGray > MinGray

Example (HDevelop)

* Segment a filtered image
read_image(Image,'particle')
mean_image(Image,Mean,11,11)
pouring(Mean,Seg,'all',0,255)
dev_display(Mean)
dev_set_colored(12)
dev_display(Seg)

* Segment an image while masking the dark background
read_image(Image,'particle')
mean_image(Image,ImageMean,15,15)
pouring(Mean,Seg,'all',90,255)
dev_display(Mean)
dev_set_colored(12)
dev_display(Seg)

Example (C)

/* Segmentation of a filtered image */
read_image(&Image,"br2");
mean_image(Image,&Mean,11,11);
pouring(Mean,&Seg,"all",0,255);
disp_image(Mean,WindowHandle);
set_colored(WindowHandle,12);
disp_region(Seg,WindowHandle);

/* Segmentation of an image with masking of a dark backround */
read_image(&Image,"hand");
mean_image(Image,&Mean,15,15);
pouring(Mean,&Seg,"all",40,255);
disp_image(Mean,WindowHandle);
set_colored(WindowHandle,12);
disp_region(Seg,WindowHandle);

Example (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   img1 ("br2"),
           img2 ("hand"),
           img3 ("monkey"),
           texture,
           testreg;

  HWindow      w1, w2, w3;
  HRegion      region;
  HRegionArray seg;

  w1.SetColored (12);   img1.Display (w1);
  w2.SetColored (12);   img2.Display (w2);
  w3.SetColored (12);   img3.Display (w3);

  cout << "Smoothing of images 1 and 2 ..." << endl;

  HImage mean1 = img1.MeanImage (11, 11);
  HImage mean2 = img2.MeanImage (15, 15);

  cout << "Full segmentation of images ... " << endl;
  seg = mean1.Pouring ("all", 0, 255);
  seg.Display (w1);

  cout << "Segmentation with: a) masked background " << endl;
  cout << "                   b) intersection " << endl;
  seg = mean2.Pouring ("regions", 40, 255);
  seg.Display (w2);

  cout << "Segmentation in 2d-histogram" << endl;
  cout << "Draw region with the mouse: " << endl;

  region  = w3.DrawRegion ();
  texture = img3.TextureLaws ("el", 2, 5);

  testreg = texture.ReduceDomain (region);
  histo   = testreg.Histo2dim (texture, region);
  seg     = histo.Pouring ("all", 0, 255);

  seg.Display (w3);
  w3.Click ();
  return (0);
}

Example (HDevelop)

* Segment a filtered image
read_image(Image,'particle')
mean_image(Image,Mean,11,11)
pouring(Mean,Seg,'all',0,255)
dev_display(Mean)
dev_set_colored(12)
dev_display(Seg)

* Segment an image while masking the dark background
read_image(Image,'particle')
mean_image(Image,ImageMean,15,15)
pouring(Mean,Seg,'all',90,255)
dev_display(Mean)
dev_set_colored(12)
dev_display(Seg)

Complexity

Let be the number of pixels in the input image and be the number of found segments, where the enclosing rectangle of the segment contains pixels. Furthermore, let be the number of chords in segment . Then the runtime complexity is

Result

pouringpouringPouringPouringpouring usually returns the value 2 ( H_MSG_TRUE) . If necessary, an exception is raised.

Possible Predecessors

binomial_filterbinomial_filterBinomialFilterBinomialFilterbinomial_filter, gauss_filtergauss_filterGaussFilterGaussFiltergauss_filter, smooth_imagesmooth_imageSmoothImageSmoothImagesmooth_image, mean_imagemean_imageMeanImageMeanImagemean_image

Alternatives

watershedswatershedsWatershedsWatershedswatersheds, local_maxlocal_maxLocalMaxLocalMaxlocal_max, watersheds_thresholdwatersheds_thresholdWatershedsThresholdWatershedsThresholdwatersheds_threshold, watersheds_markerwatersheds_markerWatershedsMarkerWatershedsMarkerwatersheds_marker

See also

histo_2dimhisto_2dimHisto2dimHisto2dimhisto_2dim, expand_regionexpand_regionExpandRegionExpandRegionexpand_region, expand_grayexpand_grayExpandGrayExpandGrayexpand_gray, expand_gray_refexpand_gray_refExpandGrayRefExpandGrayRefexpand_gray_ref

Module

Foundation

ClassesClasses | | Operators