Skip to content

Commit 59ab6e9

Browse files
Shen-wbShen-wb
committed
Update README.md
1 parent fa83873 commit 59ab6e9

File tree

2 files changed

+151
-46
lines changed

2 files changed

+151
-46
lines changed

‎3.settings/README.md‎

Lines changed: 115 additions & 34 deletions
Original file line numberDiff line numberDiff line change
@@ -1,67 +1,140 @@
1-
# Using the Runtime Settings
1+
# JavaScript Parameter Settings Samples
22

3-
In this sample set, we will mainly focus on how to utilize the various runtime settings of DBR to offer a better overall performance and experience for your users.
3+
Dynamsoft Barcode Reader JavaScript SDK (hereafter called "the library") is based on Dynamsoft's algorithm in ROI (region of interest) locating and decoding. The algorithm is very flexible and has many configurable parameters. In this article, we'll take a look at how the library makes use of these parameters.
44

5-
DBR comes with a variety of runtime settings that you can find organizaed and classified by their functionality on this page: [Dynamsoft Barcode Reader Parameter Reference - Main Page](https://www.dynamsoft.com/barcode-reader/parameters/reference/?ver=latest)
5+
Please note that most of the styling is common across the samples in this sample set. So in order to make the code clearer, we grouped the styling all in one file, settings-css.css. Furthermore, the samples also share the same scanner initialization code. For the sake of clarity, the initialization code was also grouped in the same JS file, initScanner.js, and referenced throughout the different samples in this set.
66

7-
The next few sections will dive into each of the samples, explaining which runtime settings are used and which scenarios they correspond to.
7+
## Specify the Barcode Types and Number of Barcodes Per Image
88

9-
All of the samples come with plenty of comments in the code as well to guide you through the process of translating the user inputs to the RuntimeSettings of the scanner (or reader) instance.
9+
In most cases, an application only needs to process one or several predetermined types of Barcodes. Also, the algorithm is more efficient when it knows how many barcodes are expected on an image. The following code shows how to read 2 QR codes on an image.
1010

11-
Please note that most of the styling is common across the samples in this sample set. So in order to make the code clearer, we grouped the styling all in one file, `settings-css.css`. Furthermore, the samples also share the same scanner initialization code. For the sake of clarity, the initialization code was also grouped in the same JS file, `initScanner.js`, and referenced throughout the different samples in this set.
11+
```javascript
12+
const settings = await scanner.getRuntimeSettings();
13+
settings.barcodeFormatIds = Dynamsoft.DBR.EnumBarcodeFormat.BF_QR_CODE;
14+
settings.expectedBarcodesCount = 2;
15+
await scanner.updateRuntimeSettings(settings);
16+
```
1217

13-
Now to explore each of the samples.
18+
The following official sample showcases the same features.
1419

15-
## Barcode Formats and Expected Number of Barcodes
20+
* <a target = "_blank" href="https://demo.dynamsoft.com/samples/dbr/js/3.settings/1.barcodeFormats-expectedBarcodes.html">Specify Barcode Types and Count - Demo</a>
21+
* <a target = "_blank" href="https://github.com/Dynamsoft/barcode-reader-javascript-samples/blob/main/3.settings/1.barcodeFormats-expectedBarcodes.html">Specify Barcode Types and Count - Source Code</a>
1622

17-
In this sample, we visit two of the most widely used runtime settings that DBR offers, `BarcodeFormatIds` and `ExpectedBarcodesCount`.
23+
## Set Localization and Binarization Modes
1824

19-
[BarcodeFormatIds](https://www.dynamsoft.com/barcode-reader/programming/javascript/api-reference/interface/RuntimeSettings.html?ver=latest#barcodeformatids) sets the barcode formats to be read. The SDK will automatically discard any barcode results that do not belong to the specified formats. To learn of DBR's supported formats, please visit this [page](https://www.dynamsoft.com/barcode-reader/features/#Supported-Barcode-Types).
25+
Localization and binarization are two essential steps in the barcode reading process.
2026

21-
[ExpectedBarcodesCount](https://www.dynamsoft.com/barcode-reader/programming/javascript/api-reference/interface/RuntimeSettings.html?ver=latest#expectedbarcodescount) is used to control the number of barcodes detected for each image or frame.
27+
* Localization Modes
2228

23-
To learn how these two parameters can help reduce time cost and improve performance in various scenarios, please refer to this [article](https://www.dynamsoft.com/barcode-reader/parameters/scenario-settings/barcode-format-and-expected-barcode-counts.html).
29+
Localization modes specify how the algorithm scan the image in order to find a barcode. At present, 8 modes are available: "Connected Blocks", "Statistics", "Lines", "Scan Directly", "Statistics Marks", "Statistics Postal Code", "Center" and "OneD Fast Scan". More information can be found [here](https://www.dynamsoft.com/barcode-reader/parameters/reference/localization-modes.html?ver=latest). A barcode reading session will exhaust all set modes until the intended number of barcodes are found. In other words, the more modes you set, the harder the algorithm tries to find barcodes. The following code shows how to set multiple modes.
2430

25-
## Localization and Binarization
31+
```javascript
32+
const settings = await scanner.getRuntimeSettings();
33+
settings.localizationModes = [2, 16, 4, 8, 32, 64, 0, 0];
34+
await scanner.updateRuntimeSettings(settings);
35+
```
2636

27-
Localization and binarization are two essential steps in barcode reading. DBR comes with a variety of modes for each process, and depending on the scenario, using the right localization mode or binarization mode can provide a boost to the performance.
37+
Note that each mode is represented by a number.
2838

29-
[LocalizationModes](https://www.dynamsoft.com/barcode-reader/programming/javascript/api-reference/interface/RuntimeSettings.html?ver=latest#localizationmodes) sets the modes and priority of those modes. Different localization modes correspond to different scenarios and barcode formats. For instance, in an interactive video scenario, it is recommended to prioritize the `Connected Blocks` and `Scan Directly` modes. If you are dealing only with 1D barcodes, then it is a good idea to have the `Lines` mode higher on the priority list. Please read through this [article](https://www.dynamsoft.com/barcode-reader/parameters/scenario-settings/how-to-set-localization-modes.html) to learn more.
39+
Read more on [How to use different localization modes](https://www.dynamsoft.com/barcode-reader/parameters/scenario-settings/how-to-set-localization-modes.html).
3040

31-
[BinarizationModes](https://www.dynamsoft.com/barcode-reader/programming/javascript/api-reference/interface/RuntimeSettings.html?ver=latest#binarizationModes) sets the mode and priority for binarization. Like localization, the different binarization modes correspond to different situations and scenarios. To learn more about the aforementioned scenarios, please go through this [article](https://www.dynamsoft.com/barcode-reader/parameters/scenario-settings/how-to-set-binarization-modes.html).
41+
* Binarization Modes
3242

33-
## Dealing with Blurry or Small Barcodes
43+
Binarization modes specify how the algorithm binarizes a colored or gray image. Right now, there are only two modes available: "Local Block" and "Threshold". More information can be found [here](https://www.dynamsoft.com/barcode-reader/parameters/reference/binarization-modes.html?ver=latest).
3444

35-
Every now and then the library might encounter a barcode that is too blurry, causing the decoding process to fail. In other scenarios, it could encounter a barcode that is relatively very small to the entire image or frame, which we found to be a common scenario when dealing with barcodes on machinery, for instance.
45+
For each mode, there are a few arguments to fine-tune it for best performance. Read more on [How to configure the binarization parameters](https://www.dynamsoft.com/barcode-reader/parameters/scenario-settings/how-to-set-binarization-modes.html?ver=latest).
3646

37-
Luckily, DBR comes equipped with the appropriate parameters to combat those scenarios. Namely, we will be focussing on the `DeblurModes` and `ScaleUpModes`.
47+
The following official sample demonstrates how to set Localization and Binarization modes.
3848

39-
The SDK comes with seven distinct deblur modes that can be used to help improve the clarity of an image, all of which are listed [here](https://www.dynamsoft.com/barcode-reader/programming/javascript/api-reference/interface/RuntimeSettings.html?ver=latest#deblurmodes). It is recommended that the more blurry an image is, the more modes should be included in the `DeblurModes` array. To learn more about each mode, please refer to this [page](https://www.dynamsoft.com/barcode-reader/parameters/enum/parameter-mode-enums.html?ver=latest#deblurmode).
49+
* <a target = "_blank" href="https://demo.dynamsoft.com/samples/dbr/js/3.settings/2.localizationModes-binarizationModes.html">Localization and Binarization - Demo</a>
50+
* <a target = "_blank" href="https://github.com/Dynamsoft/barcode-reader-javascript-samples/blob/main/3.settings/2.localizationModes-binarizationModes.html">Localization and Binarization - Source Code</a>
4051

41-
[ScaleUpModes](https://www.dynamsoft.com/barcode-reader/programming/javascript/api-reference/interface/RuntimeSettings.html?ver=latest#scaleupmodes) are used to enlarge a barcode that is very small compared to the entire image or frame. By default, the SDK goes with the automatic mode, which allows the SDK to choose whether the barcode area needs to be enlarged, and which method to employ. The two methods are linear interpolation and nearest neighbour interpolation, each coming with a set of mode arguments that offer even more control over the enlargement process.
52+
## Set Deblur Modes and Scale-up Modes
4253

43-
To learn more about the ScaleUpModes and its methods, please refer to this [article](https://www.dynamsoft.com/barcode-reader/parameters/scenario-settings/how-to-set-scaleup-modes.html?ver=latest).
54+
* Deblur Modes
4455

45-
## Dealing with Deformed and Incomplete Barcodes
56+
The barcode reader often needs to handle blurry images, setting the deblur modes will help the algorithm better process them. In the library, there are 7 available modes: "Direct Binarization", "Threshold_Binarization", "Gray_Equalization", "Smoothing", "Morphing", "Deep_Analysis" and "Sharpening". More information can be found [here](https://www.dynamsoft.com/barcode-reader/parameters/reference/deblur-modes.html?ver=latest). A barcode reading session will exhaust all set modes until the intended number of barcodes are found. In other words, the more modes you set, the harder the algorithm tries to find barcodes. The following code shows how to set multiple deblur modes.
4657

47-
In the same vein as the previous sample, users might face a situation where they are scanning a deformed or incomplete barcode. Deformed barcodes usually form when the barcode is printed on an irregular surface, such as a cylindrical one, or perhaps if the barcode is on a wrinkled piece of paper. Incomplete barcodes, on the other hand, can occur due to misprinting.
58+
```javascript
59+
const settings = await scanner.getRuntimeSettings();
60+
settings.deblurModes = [1, 2, 4, 8, 0, 0, 0, 0, 0, 0];
61+
await scanner.updateRuntimeSettings(settings);
62+
```
4863

49-
To deal with both situations, DBR offers [DeformationResistingModes](https://www.dynamsoft.com/barcode-reader/programming/javascript/api-reference/interface/FurtherModes.html?ver=latest#deformationresistingmodes) for deformed barcodes, and [BarcodeComplementModes](https://www.dynamsoft.com/barcode-reader/programming/javascript/api-reference/interface/FurtherModes.html?ver=latest#barcodecomplementmodes) for incomplete barcodes.
64+
* Scale-up Modes
5065

51-
Please note that `DeformationResistingModes` is currently only compatible with QR and Datamatrix codes. To learn more about how this parameter helps fix the deformity in the aformentioned scenarios, please refer to this [article](https://www.dynamsoft.com/barcode-reader/parameters/scenario-settings/resist-deformation.html?ver=latest).
66+
In many cases, the barcodes appear very small on the image and makes it difficult to read. The scale-up modes can be used to enlarge such barcodes before reading them. In the library, there are 2 available modes: "Linear_Interpolation" and "Nearest_Neighbour_Interpolation". More information can be found [here](https://www.dynamsoft.com/barcode-reader/parameters/reference/scale-up-modes.html?ver=latest).
5267

53-
Similar to `DeformationResistingModes`, `BarcodeComplementModes` is currently only compatible with QR and Datamatrix codes. To learn more about how `BarcodeComplementModes` please check out the following [article](https://www.dynamsoft.com/barcode-reader/parameters/scenario-settings/how-to-set-barcode-complememt-modes.html?ver=latest).
68+
For each mode, there are a few arguments to fine-tune it for best performance. Read more on [How to read barcodes with small module sizes](https://www.dynamsoft.com/barcode-reader/parameters/scenario-settings/how-to-set-scaleup-modes.html?ver=latest).
5469

55-
## Region of Interest and Region Pre-detection
70+
The following official sample demonstrates how to set Deblur modes and Scale-up modes.
5671

57-
Usually, DBR will traverse the entire area of an image or frame to locate and decode any barcodes that are there. However, there are some situations where the user is only concerned about a specific area of an image or want to restrict the video view to a specific region. This sample demonstrates how to manually define a [Region](https://www.dynamsoft.com/barcode-reader/programming/javascript/api-reference/interface/Region.html?ver=latest). Once the region is defined, DBR will only decode barcodes that are within that region.
72+
* <a target = "_blank" href="https://demo.dynamsoft.com/samples/dbr/js/3.settings/3.blurred-small-barcodes.html">Deblur Modes and Scale-Up Modes - Demo</a>
73+
* <a target = "_blank" href="https://github.com/Dynamsoft/barcode-reader-javascript-samples/blob/main/3.settings/2.localizationModes-binarizationModes.html">Deblur Modes and Scale-Up Modes - Source Code</a>
5874

59-
To define the region, the top-most, left-most, right-most, and bottom-most coordinate or percentage of the region must be defined. Whether coordinate or percentage is used is defined by `regionMeasuredByPercentage`. In most cases, percentage is easier to use. Please refer to the following image to get an idea of how the percentages are taken into account:
60-
![RegionOfInterest Percentages](https://tst.dynamsoft.com/public/samples/dbr/JS/assets/regionOfInterest.png)
75+
## Deformation-Resisting Modes and Barcode-Complement Modes
6176

62-
To learn more about `Region` and how to use them, please refer to this [article](https://www.dynamsoft.com/barcode-reader/parameters/scenario-settings/manually-define-region-of-interest.html?ver=latest).
77+
* Deformation-Resisting Modes
6378

64-
Region detection can also be used to pre-detect the region of interest of a large image to get several areas where the barcodes may exist to reduce processing time. The different modes of [RegionPredetectionModes](https://www.dynamsoft.com/barcode-reader/programming/javascript/api-reference/interface/FurtherModes.html?ver=latest#regionpredetectionmodes) correspond to different scenarios, some of which are clarified [here](https://www.dynamsoft.com/barcode-reader/parameters/scenario-settings/how-to-use-region-predetection.html).
79+
As the name suggests, deformation-resisting modes deal with deformed barcocdes. Read more on [How to deal with deformed barcodes](https://www.dynamsoft.com/barcode-reader/parameters/scenario-settings/resist-deformation.html?ver=latest).
80+
81+
For now, there is only one available mode: "General".
82+
83+
The following code enables deformation resisting.
84+
85+
```javascript
86+
const settings = await scanner.getRuntimeSettings();
87+
settings.furtherModes.deformationResistingModes = [2, 0, 0, 0, 0, 0, 0, 0];
88+
await scanner.updateRuntimeSettings(settings);
89+
```
90+
91+
* Barcode-Complement Modes
92+
93+
QR codes and Data Matrix codes can be read even if they are incomplete due to reasons like misprinting. Read more on [How to decode incomplete barcodes](https://www.dynamsoft.com/barcode-reader/parameters/scenario-settings/how-to-set-barcode-complememt-modes.html?ver=latest).
94+
95+
The parameter for this case is called [ `BarcodeComplementMode` ](https://www.dynamsoft.com/barcode-reader/parameters/reference/barcode-complement-modes.html?ver=latest) which has only one available mode at present: "General".
96+
97+
The following code enables incomplete barcode reading.
98+
99+
```javascript
100+
const settings = await scanner.getRuntimeSettings();
101+
settings.furtherModes.deformationResistingModes = [2, 0, 0, 0, 0, 0, 0, 0];
102+
await scanner.updateRuntimeSettings(settings);
103+
```
104+
105+
The following official sample showcases deformation resisting and barcode complementing.
106+
107+
* <a target = "_blank" href="https://demo.dynamsoft.com/samples/dbr/js/3.settings/4.deformed-incomplete-barcodes.html">Deformation-Resisting Modes and Barcode-Complement Modes - Demo</a>
108+
* <a target = "_blank" href="https://github.com/Dynamsoft/barcode-reader-javascript-samples/blob/main/3.settings/4.deformed-incomplete-barcodes.html">Deformation-Resisting Modes and Barcode-Complement Modes - Source Code</a>
109+
110+
## Define or Detect the Region of Interest
111+
112+
When reading barcodes from a video input, the barcode normally takes up only a small portion of the video frame. If the barcode always appear around the same spot, we can set a limited region around it as the ROI (Region of Interest) to speed up the barcode reading process. With the library, there are two ways to do this.
113+
114+
* Manually define the ROI
115+
116+
If the ROI is predetermined in the use case, we can manually set the limit. For example, the following only reads 25% of the central area.
117+
118+
```javascript
119+
const settings = await scanner.getRuntimeSettings();
120+
settings.region.regionMeasuredByPercentage = 1;
121+
settings.region.regionLeft = 25;
122+
settings.region.regionTop = 25;
123+
settings.region.regionRight = 75;
124+
settings.region.regionBottom = 75;
125+
await scanner.updateRuntimeSettings(settings);
126+
```
127+
128+
* Automatically detect the ROI
129+
130+
To let the algorithm detect the ROI automatically, we can set the parameter [ `RegionPredetectionModes` ](https://www.dynamsoft.com/barcode-reader/parameters/reference/region-predetection-modes.html?ver=latest) which has four available modes: "General", "General_RGB_Contrast", "General_Gray_Contrast" and "General_HSV_Contrast".
131+
132+
For each mode, there are a few arguments to fine-tune it for best performance. Read more on [How To Use Region Predetection](https://www.dynamsoft.com/barcode-reader/parameters/scenario-settings/how-to-use-region-predetection.html?ver=latest).
133+
134+
The following official sample showcases both ways to specify ROI.
135+
136+
* <a target = "_blank" href="https://demo.dynamsoft.com/samples/dbr/js/3.settings/5.regionOfInterest-regionPredetection.html">Define or Detect the Region of Interest - Demo</a>
137+
* <a target = "_blank" href="https://github.com/Dynamsoft/barcode-reader-javascript-samples/blob/main/3.settings/5.regionOfInterest-regionPredetection.html">Define or Detect the Region of Interest - Source Code</a>
65138

66139
## Dealing with Dense Barcodes
67140

@@ -70,7 +143,15 @@ Some barcodes are designed to hold a lot of information which makes them very de
70143
1. Use a high resolution
71144
2. Use the built-in "dense" template
72145

73-
Check out the code for more information.
146+
```javascript
147+
await scanner.setResolution(3840, 2160);
148+
await scanner.updateRuntimeSettings("dense");
149+
```
150+
151+
The following official sample showcases the decode performance of dense barcode after modifying specific settings.
152+
153+
* <a target = "_blank" href="https://demo.dynamsoft.com/samples/dbr/js/3.settings/6.dense-barcodes.html">Dealing with Dense Barcodes - Demo</a>
154+
* <a target = "_blank" href="https://github.com/Dynamsoft/barcode-reader-javascript-samples/blob/main/3.settings/6.dense-barcodes.html">Dealing with Dense Barcodes - Source Code</a>
74155

75156
## Support
76157

0 commit comments

Comments
 (0)