Skip to content

gray_histoGrayHistoGrayHistogray_histoT_gray_histo🔗

Short description🔗

gray_histoGrayHistoGrayHistogray_histoT_gray_histo — Calculate the gray value distribution.

Signature🔗

gray_histo( region Region, image Image, out histogram AbsoluteHisto, out histogram RelativeHisto )void GrayHisto( const HObject& Region, const HObject& Image, HTuple* AbsoluteHisto, HTuple* RelativeHisto )static void HOperatorSet.GrayHisto( HObject region, HObject image, out HTuple absoluteHisto, out HTuple relativeHisto )def gray_histo( region: HObject, image: HObject ) -> Tuple[Sequence[int], Sequence[float]]

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

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

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

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

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

Description🔗

The operator gray_histoGrayHisto calculates for the image (Imageimageimage) within Regionregionregion the absolute (AbsoluteHistoabsoluteHistoabsolute_histo) and relative (RelativeHistorelativeHistorelative_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.

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

'real'"real"-, 'int2'"int2"-, 'uint2'"uint2"-, and 'int4'"int4"-images are transformed into '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_histoGrayHisto only considers the given Regionregionregion and ignores any previously set domain of the input image Imageimageimage.

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

gray_histoGrayHisto 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_histoGrayHisto can be substantially slower on an OpenCL device if the Imageimageimage is not completely included in the Regionregionregion.

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

Execution information🔗

Execution information

  • Supports OpenCL compute devices.

  • Multithreading type: reentrant (runs in parallel with non-exclusive operators).

  • Multithreading scope: global (may be called from any thread).

  • Automatically parallelized on internal data level.

Parameters🔗

Regionregionregion (input_object) region → objectHObjectHRegionHObjectHobject

Region in which the histogram is to be calculated.

Imageimageimage (input_object) singlechannelimage → object (byte* / cyclic* / direction* / int1* / int2 / uint2 / int4 / real)HObject (byte* / cyclic* / direction* / int1* / int2 / uint2 / int4 / real)HImage (byte* / cyclic* / direction* / int1* / int2 / uint2 / int4 / real)HObject (byte* / cyclic* / direction* / int1* / int2 / uint2 / int4 / real)Hobject (byte* / cyclic* / direction* / int1* / int2 / uint2 / int4 / real) *allowed for compute devices

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

AbsoluteHistoabsoluteHistoabsolute_histo (output_control) histogram-array → (integer)HTuple (Hlong)HTuple (int / long)Sequence[int]Htuple (Hlong)

Absolute frequencies of the gray values.

RelativeHistorelativeHistorelative_histo (output_control) histogram-array → (real)HTuple (double)HTuple (double)Sequence[float]Htuple (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_histoGrayHisto 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>:), the behavior in case of empty region is set via set_system(::'empty_region_result',<Result>:). If necessary an exception is raised.

Combinations with other operators🔗

Combinations

Possible successors

histo_to_threshHistoToThresh, gen_region_histoGenRegionHisto

Alternatives

min_max_grayMinMaxGray, intensityIntensity, gray_histo_absGrayHistoAbs, gray_histo_rangeGrayHistoRange

See also

set_paintSetPaint, histo_2dimHisto2dim, scale_image_maxScaleImageMax, entropy_grayEntropyGray

Module🔗

Foundation