gray_histoT_gray_histoGrayHistoGrayHistogray_histo (Operator)

Name

gray_histoT_gray_histoGrayHistoGrayHistogray_histo — Calculate the gray value distribution.

Signature

gray_histo(Regions, Image : : : AbsoluteHisto, RelativeHisto)

Herror T_gray_histo(const Hobject Regions, const Hobject Image, Htuple* AbsoluteHisto, Htuple* RelativeHisto)

void GrayHisto(const HObject& Regions, const HObject& Image, HTuple* AbsoluteHisto, HTuple* RelativeHisto)

HTuple HImage::GrayHisto(const HRegion& Regions, HTuple* RelativeHisto) const

HTuple HRegion::GrayHisto(const HImage& Image, HTuple* RelativeHisto) const

static void HOperatorSet.GrayHisto(HObject regions, HObject image, out HTuple absoluteHisto, out HTuple relativeHisto)

HTuple HImage.GrayHisto(HRegion regions, out HTuple relativeHisto)

HTuple HRegion.GrayHisto(HImage image, out HTuple relativeHisto)

def gray_histo(regions: HObject, image: HObject) -> Tuple[Sequence[int], Sequence[float]]

Description

The operator gray_histogray_histoGrayHistoGrayHistoGrayHistogray_histo calculates for the image (ImageImageImageImageimageimage) within RegionsRegionsRegionsRegionsregionsregions the absolute (AbsoluteHistoAbsoluteHistoAbsoluteHistoAbsoluteHistoabsoluteHistoabsolute_histo) and relative (RelativeHistoRelativeHistoRelativeHistoRelativeHistorelativeHistorelative_histo) histogram of the gray values.

Both histograms are tuples of 256 values, which --- beginning at 0 --- contain the frequencies of the individual gray values of the image.

AbsoluteHistoAbsoluteHistoAbsoluteHistoAbsoluteHistoabsoluteHistoabsolute_histo indicates the absolute frequencies of the gray values in integers, and RelativeHistoRelativeHistoRelativeHistoRelativeHistorelativeHistorelative_histo indicates the relative, i.e. the absolute frequencies divided by the area of the image as floating point numbers.

'real'"real""real""real""real""real"-, 'int2'"int2""int2""int2""int2""int2"-, 'uint2'"uint2""uint2""uint2""uint2""uint2"-, and 'int4'"int4""int4""int4""int4""int4"-images are transformed into 'byte'"byte""byte""byte""byte""byte"-images (first the largest and smallest gray value in the image are determined, and then the original gray values are mapped linearly into the area 0..255) and then processed as mentioned above.

Attention

Note that the operator gray_histogray_histoGrayHistoGrayHistoGrayHistogray_histo only considers the given RegionsRegionsRegionsRegionsregionsregions and ignores any previously set domain of the input image ImageImageImageImageimageimage.

Real, int2, uint2, and int4 images are reduced to 256 gray values.

gray_histogray_histoGrayHistoGrayHistoGrayHistogray_histo can be executed on OpenCL devices for byte, int1, directional and cyclic images if the OpenCL device supports the cl_khr_local_int32_base_atomics and cl_khr_global_int32_base_atomics extensions (which are optional in OpenCL 1.0). Unlike most other HALCON operators, gray_histogray_histoGrayHistoGrayHistoGrayHistogray_histo can be substantially slower on an OpenCL device if the ImageImageImageImageimageimage is not completely included in the RegionsRegionsRegionsRegionsregionsregions.

OpenCL support is not available in HALCON XL, as 64 bit atomic integer arithmetic would be required.

Execution Information

Parameters

RegionsRegionsRegionsRegionsregionsregions (input_object)  region(-array) objectHRegionHObjectHRegionHobject

Region in which the histogram is to be calculated.

ImageImageImageImageimageimage (input_object)  singlechannelimage objectHImageHObjectHImageHobject (byte* / cyclic* / direction* / int1* / int2 / uint2 / int4 / real) *allowed for compute devices

Image the gray value distribution of which is to be calculated.

AbsoluteHistoAbsoluteHistoAbsoluteHistoAbsoluteHistoabsoluteHistoabsolute_histo (output_control)  histogram-array HTupleSequence[int]HTupleHtuple (integer) (int / long) (Hlong) (Hlong)

Absolute frequencies of the gray values.

RelativeHistoRelativeHistoRelativeHistoRelativeHistorelativeHistorelative_histo (output_control)  histogram-array HTupleSequence[float]HTupleHtuple (real) (double) (double) (double)

Frequencies, normalized to the area of the region.

Complexity

If F is the area of the region the runtime complexity is O(F + 255).

Result

The operator gray_histogray_histoGrayHistoGrayHistoGrayHistogray_histo returns the value 2 (H_MSG_TRUE) if the image has defined gray values and the parameters are correct. The behavior in case of empty input (no input images available) is set via the operator set_system(::'no_object_result',<Result>:)set_system("no_object_result",<Result>)SetSystem("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 empty region is set via set_system(::'empty_region_result',<Result>:)set_system("empty_region_result",<Result>)SetSystem("empty_region_result",<Result>)SetSystem("empty_region_result",<Result>)SetSystem("empty_region_result",<Result>)set_system("empty_region_result",<Result>). If necessary an exception is raised.

Possible Successors

histo_to_threshhisto_to_threshHistoToThreshHistoToThreshHistoToThreshhisto_to_thresh, gen_region_histogen_region_histoGenRegionHistoGenRegionHistoGenRegionHistogen_region_histo

Alternatives

min_max_graymin_max_grayMinMaxGrayMinMaxGrayMinMaxGraymin_max_gray, intensityintensityIntensityIntensityIntensityintensity, gray_histo_absgray_histo_absGrayHistoAbsGrayHistoAbsGrayHistoAbsgray_histo_abs, gray_histo_rangegray_histo_rangeGrayHistoRangeGrayHistoRangeGrayHistoRangegray_histo_range

See also

set_paintset_paintSetPaintSetPaintSetPaintset_paint, histo_2dimhisto_2dimHisto2dimHisto2dimHisto2dimhisto_2dim, scale_image_maxscale_image_maxScaleImageMaxScaleImageMaxScaleImageMaxscale_image_max, entropy_grayentropy_grayEntropyGrayEntropyGrayEntropyGrayentropy_gray

Module

Foundation