Operator Reference

HALCON Operator Reference / OCR / Segmentation
ClassesClasses | | Operators

segment_charactersT_segment_charactersSegmentCharactersSegmentCharacterssegment_characters (Operator)

segment_charactersT_segment_charactersSegmentCharactersSegmentCharacterssegment_characters — Segments characters in a given region of an image.

Signature

Herror T_segment_characters(const Hobject Region, const Hobject Image, Hobject* ImageForeground, Hobject* RegionForeground, const Htuple Method, const Htuple EliminateLines, const Htuple DotPrint, const Htuple StrokeWidth, const Htuple CharWidth, const Htuple CharHeight, const Htuple ThresholdOffset, const Htuple Contrast, Htuple* UsedThreshold)

void SegmentCharacters(const HObject& Region, const HObject& Image, HObject* ImageForeground, HObject* RegionForeground, const HTuple& Method, const HTuple& EliminateLines, const HTuple& DotPrint, const HTuple& StrokeWidth, const HTuple& CharWidth, const HTuple& CharHeight, const HTuple& ThresholdOffset, const HTuple& Contrast, HTuple* UsedThreshold)

HImage HRegion::SegmentCharacters(const HImage& Image, HRegion* RegionForeground, const HString& Method, const HString& EliminateLines, const HString& DotPrint, const HString& StrokeWidth, const HTuple& CharWidth, const HTuple& CharHeight, Hlong ThresholdOffset, Hlong Contrast, HTuple* UsedThreshold) const

HImage HRegion::SegmentCharacters(const HImage& Image, HRegion* RegionForeground, const HString& Method, const HString& EliminateLines, const HString& DotPrint, const HString& StrokeWidth, const HTuple& CharWidth, const HTuple& CharHeight, Hlong ThresholdOffset, Hlong Contrast, Hlong* UsedThreshold) const

HImage HRegion::SegmentCharacters(const HImage& Image, HRegion* RegionForeground, const char* Method, const char* EliminateLines, const char* DotPrint, const char* StrokeWidth, const HTuple& CharWidth, const HTuple& CharHeight, Hlong ThresholdOffset, Hlong Contrast, Hlong* UsedThreshold) const

HImage HRegion::SegmentCharacters(const HImage& Image, HRegion* RegionForeground, const wchar_t* Method, const wchar_t* EliminateLines, const wchar_t* DotPrint, const wchar_t* StrokeWidth, const HTuple& CharWidth, const HTuple& CharHeight, Hlong ThresholdOffset, Hlong Contrast, Hlong* UsedThreshold) const   ( Windows only)

static void HOperatorSet.SegmentCharacters(HObject region, HObject image, out HObject imageForeground, out HObject regionForeground, HTuple method, HTuple eliminateLines, HTuple dotPrint, HTuple strokeWidth, HTuple charWidth, HTuple charHeight, HTuple thresholdOffset, HTuple contrast, out HTuple usedThreshold)

HImage HRegion.SegmentCharacters(HImage image, out HRegion regionForeground, string method, string eliminateLines, string dotPrint, string strokeWidth, HTuple charWidth, HTuple charHeight, int thresholdOffset, int contrast, out HTuple usedThreshold)

HImage HRegion.SegmentCharacters(HImage image, out HRegion regionForeground, string method, string eliminateLines, string dotPrint, string strokeWidth, HTuple charWidth, HTuple charHeight, int thresholdOffset, int contrast, out int usedThreshold)

def segment_characters(region: HObject, image: HObject, method: str, eliminate_lines: str, dot_print: str, stroke_width: str, char_width: Sequence[int], char_height: Sequence[int], threshold_offset: int, contrast: int) -> Tuple[HObject, HObject, Sequence[int]]

def segment_characters_s(region: HObject, image: HObject, method: str, eliminate_lines: str, dot_print: str, stroke_width: str, char_width: Sequence[int], char_height: Sequence[int], threshold_offset: int, contrast: int) -> Tuple[HObject, HObject, int]

Description

This operator is used to segment characters in a given RegionRegionRegionregionregion of an ImageImageImageimageimage. The RegionRegionRegionregionregion is only used to reduce the working area. The segmented characters are returned in RegionForegroundRegionForegroundRegionForegroundregionForegroundregion_foreground.

Two different methods to detect the characters are supplied. All segmentation methods assume that the text is darker than the background. If this is not the case, please invert the image with invert_imageinvert_imageInvertImageInvertImageinvert_image.

The parameter MethodMethodMethodmethodmethod determines the algorithm for text segmentation. The possible values are

'local_contrast_best'"local_contrast_best""local_contrast_best""local_contrast_best""local_contrast_best"

This method extracts text that differ locally from the background. Therefore, it is suited for images with inhomogeneous illumination. The enhancement of the text borders, leads to a more accurate determination of the outline of the text. Which is especially useful if the background is highly textured. The parameter ContrastContrastContrastcontrastcontrast defines the minimum contrast,i.e., the minimum gray value difference between symbols and background.

'local_auto_shape'"local_auto_shape""local_auto_shape""local_auto_shape""local_auto_shape"

The minimum contrast is estimated automatically such that the number of very small regions is reduced. This method is especially suitable for noisy images. The parameter ThresholdOffsetThresholdOffsetThresholdOffsetthresholdOffsetthreshold_offset can be used to adjust the threshold. Let g(x,y) be the gray value at position (x,y) in the input ImageImageImageimageimage. The threshold condition is determined by:

.

Select EliminateLinesEliminateLinesEliminateLineseliminateLineseliminate_lines if the extraction of characters is disturbed by lines that are horizontal or vertical with respect to the lines of text and set its value to 'true'"true""true""true""true". The elimination is influenced by the maximum of CharWidthCharWidthCharWidthcharWidthchar_width and the maximum of CharHeightCharHeightCharHeightcharHeightchar_height. For further information see the description of these parameters.

DotPrintDotPrintDotPrintdotPrintdot_print: Should be set to 'true'"true""true""true""true" if dot prints should be read, else to 'false'"false""false""false""false".

StrokeWidthStrokeWidthStrokeWidthstrokeWidthstroke_width: Specifies the stroke width of the text. It is used to calculate internally used mask sizes to determine the characters. This mask sizes are also influenced through the parameters DotPrintDotPrintDotPrintdotPrintdot_print, the average CharWidthCharWidthCharWidthcharWidthchar_width, and the average CharHeightCharHeightCharHeightcharHeightchar_height.

CharWidthCharWidthCharWidthcharWidthchar_width: This can be a tuple with up to three values. The first value is the average width of a character. The second is the minimum width of a character and the third is the maximum width of a character. If the minimum is not set or equal -1, the operator automatically sets these value depending on the average CharWidthCharWidthCharWidthcharWidthchar_width. The same is the case if the maximum is not set. Some examples:

[10] sets the average character width to 10, the minimum and maximum are calculated by the operator.

[10,-1,20] sets the average character width to 10, the minimum value is calculated by the system, and the maximum is set to 20.

[10,5,20] sets the average character width to 10, the minimum to 5, and the maximum to 20.

CharHeightCharHeightCharHeightcharHeightchar_height: This can be a tuple with up to three values. The first value is the average height of a character. The second is the minimum height of a character and the third is the maximum height of a character. If the minimum is not set or equal -1, the operator automatically sets these value depending on the average CharHeightCharHeightCharHeightcharHeightchar_height. The same is the case if the maximum is not set. Some examples:

[10] sets the average character height to 10, the minimum and maximum are calculated by the operator.

[10,-1,20] sets the average character height to 10, the minimum value is calculated by the system, and the maximum is set to 20.

[10,5,20] this sets the average character height to 10, the minimum to 5, and the maximum to 20.

ThresholdOffsetThresholdOffsetThresholdOffsetthresholdOffsetthreshold_offset: This parameter can be used to adjust the threshold, which is used when the segmentation method 'local_auto_shape'"local_auto_shape""local_auto_shape""local_auto_shape""local_auto_shape" is chosen.

ContrastContrastContrastcontrastcontrast: Defines the minimum contrast between the text and the background. This parameter is used if the segmentation method 'local_contrast_best'"local_contrast_best""local_contrast_best""local_contrast_best""local_contrast_best" is selected.

UsedThresholdUsedThresholdUsedThresholdusedThresholdused_threshold: After the execution, this parameter returns the threshold used to segment the characters.

ImageForegroundImageForegroundImageForegroundimageForegroundimage_foreground returns the image that was internally used for the segmentation.

Execution Information

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

Parameters

RegionRegionRegionregionregion (input_object)  region(-array) → objectHRegionHObjectHObjectHobject

Area in the image where the text lines are located.

ImageImageImageimageimage (input_object)  singlechannelimage → objectHImageHObjectHObjectHobject (byte / uint2)

Input image.

ImageForegroundImageForegroundImageForegroundimageForegroundimage_foreground (output_object)  image(-array) → objectHImageHObjectHObjectHobject * (byte / uint2)

Image used for the segmentation.

RegionForegroundRegionForegroundRegionForegroundregionForegroundregion_foreground (output_object)  singlechannelregion(-array) → objectHRegionHObjectHObjectHobject *

Region of characters.

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

Method to segment the characters.

Default: 'local_auto_shape' "local_auto_shape" "local_auto_shape" "local_auto_shape" "local_auto_shape"

List of values: 'local_auto_shape'"local_auto_shape""local_auto_shape""local_auto_shape""local_auto_shape", 'local_contrast_best'"local_contrast_best""local_contrast_best""local_contrast_best""local_contrast_best"

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

Eliminate horizontal and vertical lines?

Default: 'false' "false" "false" "false" "false"

List of values: 'false'"false""false""false""false", 'true'"true""true""true""true"

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

Should dot print characters be detected?

Default: 'false' "false" "false" "false" "false"

List of values: 'false'"false""false""false""false", 'true'"true""true""true""true"

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

Stroke width of a character.

Default: 'medium' "medium" "medium" "medium" "medium"

List of values: 'bold'"bold""bold""bold""bold", 'light'"light""light""light""light", 'medium'"medium""medium""medium""medium", 'ultra_light'"ultra_light""ultra_light""ultra_light""ultra_light"

CharWidthCharWidthCharWidthcharWidthchar_width (input_control)  integer-array → HTupleSequence[int]HTupleHtuple (integer) (int / long) (Hlong) (Hlong)

Width of a character.

Default: 25

Value range: 1 ≤ CharWidth CharWidth CharWidth charWidth char_width

CharHeightCharHeightCharHeightcharHeightchar_height (input_control)  integer-array → HTupleSequence[int]HTupleHtuple (integer) (int / long) (Hlong) (Hlong)

Height of a character.

Default: 25

Value range: 1 ≤ CharHeight CharHeight CharHeight charHeight char_height

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

Value to adjust the segmentation.

Default: 0

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

Minimum gray value difference between text and background.

Default: 10

UsedThresholdUsedThresholdUsedThresholdusedThresholdused_threshold (output_control)  integer(-array) → HTupleSequence[int]HTupleHtuple (integer) (int / long) (Hlong) (Hlong)

Threshold used to segment the characters.

Example (HDevelop)

for Index := 1 to 5 by 1
  read_image (Image, 'dot_print_rotated/dot_print_rotated_'+Index$'02d')
  text_line_orientation (Image, Image, 50, rad(-30), rad(30), \
                         OrientationAngle)
  rotate_image (Image, ImageRotate, deg(-OrientationAngle), 'constant')
  segment_characters (ImageRotate, ImageRotate, ImageForeground, \
                      RegionForeground, 'local_auto_shape', 'false', \
                      'false', 'medium', 25, 25, 0, 10, UsedThreshold)
endfor

Result

If the input parameters are set correctly, the operator segment_characterssegment_charactersSegmentCharactersSegmentCharacterssegment_characters returns the value 2 ( H_MSG_TRUE) . Otherwise an exception will be raised.

Possible Predecessors

text_line_orientationtext_line_orientationTextLineOrientationTextLineOrientationtext_line_orientation

Possible Successors

select_charactersselect_charactersSelectCharactersSelectCharactersselect_characters, connectionconnectionConnectionConnectionconnection

Alternatives

thresholdthresholdThresholdThresholdthreshold

Module

Foundation

ClassesClasses | | Operators