Documentation
Table of contents

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

This page is compatible for:

Version 1.0

Is this page helpful?

YesYes NoNo

In this article:

latest version

    • Latest version
    • Version 2.x
      • Version 2.2.20
      • Version 2.2.10
      • Version 2.2.0
      • Version 2.0.30
      • Version 2.0.20
      • Version 2.0.10
      • Version 2.0.0
    Change +
    © 2003–2024 Dynamsoft. All rights reserved.
    Privacy Statement / Site Map / Home / Purchase / Support