BinarizationModes

Parameter BinarizationModes helps control the process of binarization, i.e., converting a grayscale image to a binary image. A better binary image greatly helps the following processes. During binarization, the threshold is the key criteria. If the pixel value is smaller than the threshold, it is set to 0, otherwise, it is set to a maximum value (255 in the library). By default, the library automatically calculates the adaptive size of the neighbourhood area and then binarizes the grayscale image with the adaptive threshold based on a small neighbourhood area with an adaptive size around it. BinarizationModes consists of one or more modes, each mode representing a different binarization process.

Example

{
    "BinarizationModes": [
        {
            "Mode": "BM_LOCAL_BLOCK", 
            "BlockSizeX": 5,
            "BlockSizeY": 5,
            "EnableFillBinaryVacancy" : 1,
            "ThresholdCompensation" : 5,
            "LibraryFileName" : "",
            "LibraryParameters" : ""
        },
        {
            "Mode": "BM_THRESHOLD", 
            "BinarizationThreshold": 125
        }
    ]
}

Parameter Summary

Parameter BinarizationModes consist of a group of binarization mode objects. Each binarization mode object includes a candidate mode and a series of mode arguments. The available mode arguments of the binarization mode object is shown as follow.

Mode Arguments

Mode Argument Name	Mode Argument Summary
Mode (Required)	Description Any one in Candidate Mode List as string
	Type String
	Candidate Mode List BM_THRESHOLD BM_LOCAL_BLOCK BM_SKIP
BlockSizeX (Optional)	Description Sets the horizontal block size for the binarization process.
	Type int
	Range [0,1000]
	Valid For BM_LOCAL_BLOCK
BlockSizeY (Optional)	Description Sets the vertical block size for the binarization process.
	Type int
	Range [0,1000]
	Valid For BM_LOCAL_BLOCK
EnableFillBinaryVacancy (Optional)	Description Sets whether to enable binary vacancy filling.
	Type int
	Range [0,1]
	Valid For BM_LOCAL_BLOCK
ThresholdCompensation (Optional)	Description Constant subtracted from the mean or weighted mean used for calculating the threshold. Normally, it is positive but may be zero or negative as well.
	Type int
	Range [-255, 255]
	Valid For BM_LOCAL_BLOCK
BinarizationThreshold (Optional)	Description Sets the binarization threshold.
	Type int
	Range [-1, 255]
	Valid For BM_THRESHOLD
MorphOperation(Optional)	Description
	Type String
	Range "Erode", "Dilate", "Open" or "Close"
	Valid For All modes
MorphOperationKernelSizeX (Optional)	Description Sets the binarization threshold.
	Type int
	Range [-1, 1000]
	Valid For All modes
MorphOperationKernelSizeY (Optional)	Description Sets the binarization threshold.
	Type int
	Range [-1, 1000]
	Valid For All modes
MorphShape (Optional)	Description Sets the binarization threshold.
	Type String
	Range "Rectangle", "Cross" or "Ellipse"
	Valid For All modes
GrayscaleEnhancementModesIndex (Optional)	Description The index of a specific image preprocessing mode in the GrayscaleEnhancementModes parameter which the current binarization mode is applied to.
	Type int
	Range [-1, 0x7fffffff]
	Valid For All modes
LibraryFileName (Optional)	Description Sets the file name of the library to load dynamically.
	Type String
	Range A string value representing file name.
	Default Value ""
	Valid For All modes
LibraryParameters (Optional)	Description The library must be in the same place with Dynamsoft Barcode Reader Library.
	Type String
	Range A string value representing parameters.
	Default Value ""
	Valid For All modes.

Default Setting

If the BinarizationModes is not configured in your template file, the following settings will be used as the default settings.

For Barcode Decoding

{
    "BinarizationModes" : 
    [
        {
            "BlockSizeX" : 0,
            "BlockSizeY" : 0,
            "EnableFillBinaryVacancy" : 0,
            "GrayscaleEnhancementModesIndex" : -1,
            "Mode" : "BM_LOCAL_BLOCK",
            "MorphOperation" : "Close",
            "MorphOperationKernelSizeX" : -1,
            "MorphOperationKernelSizeY" : -1,
            "MorphShape" : "Rectangle",
            "ThresholdCompensation" : 10
        }
    ]
}

For Label Recognizing

{
    "BinarizationModes" : 
    [
        {
            "BlockSizeX" : 0,
            "BlockSizeY" : 0,
            "EnableFillBinaryVacancy" : 1,
            "GrayscaleEnhancementModesIndex" : -1,
            "Mode" : "BM_LOCAL_BLOCK",
            "MorphOperation" : "Close",
            "MorphOperationKernelSizeX" : -1,
            "MorphOperationKernelSizeY" : -1,
            "MorphShape" : "Rectangle",
            "ThresholdCompensation" : 10
        }
    ]
}

For Document Normalizing

{
    "BinarizationModes" : 
    [
        {
            "BlockSizeX" : 0,
            "BlockSizeY" : 0,
            "EnableFillBinaryVacancy" : 0,
            "GrayscaleEnhancementModesIndex" : -1,
            "Mode" : "BM_LOCAL_BLOCK",
            "MorphOperation" : "Close",
            "MorphOperationKernelSizeX" : -1,
            "MorphOperationKernelSizeY" : -1,
            "MorphShape" : "Rectangle",
            "ThresholdCompensation" : 10
        }
    ]
}

For Text Line Specification

Re-binarize the text line area to support the character segmentation.

{
    "BinarizationModes" : 
    [
        {
            "BlockSizeX": 11,
            "BlockSizeY": 11,
            "EnableFillBinaryVacancy": 1,
            "GrayscaleEnhancementModesIndex": -1,
            "Mode": "BM_LOCAL_BLOCK",
            "MorphOperation": "Erode",
            "MorphOperationKernelSizeX": -1,
            "MorphOperationKernelSizeY": -1,
            "MorphShape": "Rectangle",
            "ThresholdCompensation": 10
        }
    ]
}

Candidate Modes Introduction

BM_LOCAL_BLOCK

If an image has different lighting conditions in different areas, BM_LOCAL_BLOCK can help. In this case, our algorithm determines the threshold for a pixel based on a small region around it, which makes it more adaptive and gives better results.

Available Mode Arguments:

BlockSizeX
BlockSizeY
EnableFillBinaryVacancy
ThresholdCompensation
BinarizationThreshold
GrayscaleEnhancementModesIndex
MorphOperation
MorphShape
MorphOperationKernelSizeX
MorphOperationKernelSizeY
LibraryFileName
LibraryParameters

BM_THRESHOLD

Binarizes the image for each pixel based on a unified threshold. If the gray value of the pixel is less than the threshold, it will be black in the binary image, otherwise it will be white.

Available Mode Arguments:

BinarizationThreshold
GrayscaleEnhancementModesIndex
MorphOperation
MorphShape
MorphOperationKernelSizeX
MorphOperationKernelSizeY
LibraryFileName
LibraryParameters