Operator Reference

expand_gray_refexpand_gray_refExpandGrayRefExpandGrayRefexpand_gray_ref (Operator)

expand_gray_refexpand_gray_refExpandGrayRefExpandGrayRefexpand_gray_ref — Fill gaps between regions (depending on gray value or color) or split overlapping regions.

Signature

expand_gray_ref(Regions, Image, ForbiddenArea : RegionExpand : Iterations, Mode, RefGray, Threshold : )

Description

expand_gray_refexpand_gray_refExpandGrayRefExpandGrayRefexpand_gray_ref closes gaps between the input regions, which resulted from the suppression of small regions in a segmentation operator, (mode 'image'"image""image""image""image"), for example, or separates overlapping regions 'region'"region""region""region""region"). Both uses result from the expansion of regions. The operator works by adding a one pixel wide “strip” to a region, in which the gray values or color are different from a reference gray value or color by at most ThresholdThresholdThresholdthresholdthreshold (in each channel). For images of type 'cyclic'"cyclic""cyclic""cyclic""cyclic" (e.g., direction images), also points with a gray value difference of at least 255 - ThresholdThresholdThresholdthresholdthreshold are added to the output region.

The expansion takes place only in regions, which are designated as not “forbidden” (parameter ForbiddenAreaForbiddenAreaForbiddenAreaforbiddenAreaforbidden_area). The number of iterations is determined by the parameter IterationsIterationsIterationsiterationsiterations. By passing 'maximal'"maximal""maximal""maximal""maximal", expand_gray_refexpand_gray_refExpandGrayRefExpandGrayRefexpand_gray_ref iterates until convergence, i.e., until no more changes occur. By passing 0 for this parameter, all non-overlapping regions are returned. The two modes of operation ('image'"image""image""image""image" and 'region'"region""region""region""region") are different in the following ways:

'image'"image""image""image""image": The input regions are expanded iteratively until they touch another region or the image border, or the expansion stops because of too high gray value differences. Because expand_gray_refexpand_gray_refExpandGrayRefExpandGrayRefexpand_gray_ref processes all regions simultaneously, gaps between regions are distributed evenly to all regions with a similar gray value. Overlapping regions are split by distributing the area of overlap evenly to both regions.
'region'"region""region""region""region": No expansion of the input regions is performed. Instead, only overlapping regions are split by distributing the area of overlap evenly to regions having a matching gray value or color.

Attention

Because regions are only expanded into areas having a matching gray value or color, usually gaps will remain between the output regions, i.e., the segmentation is not complete.

Execution Information

Multithreading type: reentrant (runs in parallel with non-exclusive operators).
Multithreading scope: global (may be called from any thread).
Processed without parallelization.

Parameters

RegionsRegionsRegionsregionsregions (input_object) region(-array) → object

Regions for which the gaps are to be closed, or which are to be separated.

ImageImageImageimageimage (input_object) (multichannel-)image → object (byte / cyclic)

Image (possibly multi-channel) for gray value or color comparison.

ForbiddenAreaForbiddenAreaForbiddenAreaforbiddenAreaforbidden_area (input_object) region → object

Regions in which no expansion takes place.

RegionExpandRegionExpandRegionExpandregionExpandregion_expand (output_object) region(-array) → object

Expanded or separated regions.

IterationsIterationsIterationsiterationsiterations (input_control) string → (string / integer)

Number of iterations.

Default: 'maximal' "maximal" "maximal" "maximal" "maximal"

Suggested values: 'maximal'"maximal""maximal""maximal""maximal", 1, 2, 3, 4, 5, 7, 10, 15, 20, 30, 50, 70, 100, 150, 200, 300, 500

Value range: 1 ≤ Iterations Iterations Iterations iterations iterations ≤ 500 (lin)

Minimum increment: 1

Recommended increment: 1

ModeModeModemodemode (input_control) string → (string)

Expansion mode.

Default: 'image' "image" "image" "image" "image"

List of values: 'image'"image""image""image""image", 'region'"region""region""region""region"

RefGrayRefGrayRefGrayrefGrayref_gray (input_control) integer(-array) → (integer)

Reference gray value or color for comparison.

Default: 128

Suggested values: 1, 10, 20, 50, 100, 128, 200, 255

Value range: 1 ≤ RefGray RefGray RefGray refGray ref_gray ≤ 255 (lin)

Minimum increment: 1

Recommended increment: 10

ThresholdThresholdThresholdthresholdthreshold (input_control) integer(-array) → (integer)

Maximum difference between the reference gray value or color and a candidate for expansion.

Default: 32

Suggested values: 4, 10, 15, 20, 25, 30, 40

Value range: 1 ≤ Threshold Threshold Threshold threshold threshold ≤ 255 (lin)

Minimum increment: 1

Recommended increment: 5

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   image (argv[1]);
  HRegion  empty_region;
  HWindow  win;

  win.SetDraw ("margin");
  win.SetColored (12);

  image.Display (win);

  HRegionArray seg = (image >= 100).Connection ();
  seg.Display (win);

  Tuple iter = "maximal";
  Tuple mode = "image";
  Tuple refg = 128;
  Tuple thrs = 32;

  HRegionArray exp = seg.ExpandGrayRef (image, empty_region,
                                        iter, mode, refg, thrs);
  exp.Display (win);
  win.Click ();

  return (0);
}

Example (C)

read_image(&Image,"fabrik");
disp_image(Image,WindowHandle);
regiongrowing(Image,&RawSegments,3,3,6.0,100);
set_colored(WindowHandle,12);
disp_region(RawSegments,WindowHandle);
T_intensity(RawSegments,Image,&Mean,NULL);
set_i(Thresh,24,0);
set_s(Iter,"maximal",0);
set_s(Mode,"image",0);
T_expand_gray_ref(RawSegments,Image,EMPTY_REGION,&Segments,Iter,Mode,
               Mean,Thresh);
disp_region(Segments,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   image (argv[1]);
  HRegion  empty_region;
  HWindow  win;

  win.SetDraw ("margin");
  win.SetColored (12);

  image.Display (win);

  HRegionArray seg = (image >= 100).Connection ();
  seg.Display (win);

  Tuple iter = "maximal";
  Tuple mode = "image";
  Tuple refg = 128;
  Tuple thrs = 32;

  HRegionArray exp = seg.ExpandGrayRef (image, empty_region,
                                        iter, mode, refg, thrs);
  exp.Display (win);
  win.Click ();

  return (0);
}

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   image (argv[1]);
  HRegion  empty_region;
  HWindow  win;

  win.SetDraw ("margin");
  win.SetColored (12);

  image.Display (win);

  HRegionArray seg = (image >= 100).Connection ();
  seg.Display (win);

  Tuple iter = "maximal";
  Tuple mode = "image";
  Tuple refg = 128;
  Tuple thrs = 32;

  HRegionArray exp = seg.ExpandGrayRef (image, empty_region,
                                        iter, mode, refg, thrs);
  exp.Display (win);
  win.Click ();

  return (0);
}

Result

expand_gray_refexpand_gray_refExpandGrayRefExpandGrayRefexpand_gray_ref always returns the value 2 ( H_MSG_TRUE) . The behavior in case of empty input (no regions given) can be set via set_system('no_object_result',<Result>)set_system("no_object_result",<Result>)SetSystem("no_object_result",<Result>)SetSystem("no_object_result",<Result>)set_system("no_object_result",<Result>), the behavior in case of an empty input region via set_system('empty_region_result',<Result>)set_system("empty_region_result",<Result>)SetSystem("empty_region_result",<Result>)SetSystem("empty_region_result",<Result>)set_system("empty_region_result",<Result>), and the behavior in case of an empty result region via set_system('store_empty_region',<'true'/'false'>)set_system("store_empty_region",<"true"/"false">)SetSystem("store_empty_region",<"true"/"false">)SetSystem("store_empty_region",<"true"/"false">)set_system("store_empty_region",<"true"/"false">). If necessary, an exception is raised.

Possible Predecessors

connectionconnectionConnectionConnectionconnection, regiongrowingregiongrowingRegiongrowingRegiongrowingregiongrowing, pouringpouringPouringPouringpouring, class_ndim_normclass_ndim_normClassNdimNormClassNdimNormclass_ndim_norm

Possible Successors

select_shapeselect_shapeSelectShapeSelectShapeselect_shape

Module

Foundation

Operators

Operator Reference

expand_gray_refexpand_gray_refExpandGrayRefExpandGrayRefexpand_gray_ref (Operator)

Signature

Description

Attention

Execution Information

Parameters

Example (C++)

Example (C)

Example (C++)

Example (C++)

Result

Possible Predecessors

Possible Successors

See also

Module