dynamsoft-label-recognizer
Advanced tools
Dynamsoft Label Recognizer (DLR) is an SDK designed to recognize meaningful zonal text or symbols in an image (Label). Common scenarios include price tags in supermarkets, inventory labels in warehouses, VIN codes on car windshields, driver licenses, pass
Add the capability of reading passport MRZs, ID cards, VIN numbers, and various other fixed text fields in your web application with just a few lines of code.
Once integrated, your users can open your website in a browser, access their cameras, and read the intended text directly from the video input.
In this guide, you will learn step by step on how to integrate this SDK into your website.
Table of Contents
Let's start by testing the "MRZ Reading" example of the SDK which demonstrates how to enable a web page to read the machine-readable zones (MRZ) found on passports, ID cards, VISAs, etc. from a live video stream.
The complete code of the "MRZ Reading" example is shown below
<!DOCTYPE html>
<html>
<head>
<title>MRZ Reading</title>
<script src="https://cdn.jsdelivr.net/npm/dynamsoft-label-recognizer@2.2.11/dist/dlr.js"></script>
<script src="https://cdn.jsdelivr.net/npm/dynamsoft-camera-enhancer@3.0.1/dist/dce.js"></script>
</head>
<body>
<script>
// The following line specifies a license good for 24 hours, you can visit https://www.dynamsoft.com/customer/license/trialLicense?utm_source=npm&product=dlr&package=js to get your own trial license good for 30 days.
Dynamsoft.DLR.LabelRecognizer.license = 'DLS2eyJvcmdhbml6YXRpb25JRCI6IjIwMDAwMSJ9';
// The following code initializes and uses the SDK.
(async () => {
Dynamsoft.DLR.LabelRecognizer.onResourcesLoadStarted = (resourcePath) => {
// In this event handler, you can display a visual cue to show that the model file is being downloaded.
console.log("Loading " + resourcePath);
};
Dynamsoft.DLR.LabelRecognizer.onResourcesLoaded = (resourcePath) => {
// In this event handler, you can close the visual cue if it was displayed.
console.log("Finished loading " + resourcePath);
};
let recognizer = await Dynamsoft.DLR.LabelRecognizer.createInstance();
let cameraEnhancer = await Dynamsoft.DCE.CameraEnhancer.createInstance();
let options = {
resultsHighlightBaseShapes: Dynamsoft.DCE.DrawingItem
};
await recognizer.setImageSource(cameraEnhancer, options);
// The following line sets up the recognizer to read MRZ, which means the SDK will load a model file specifically designed for MRZ.
await recognizer.updateRuntimeSettingsFromString("video-mrz");
// onMRZRead is a callback specifically designed for MRZ.
recognizer.onMRZRead = (txt, results) => {
// Here we simply show the text in the browser console.
console.log("Found and read a MRZ:")
console.log(txt);
};
// Beginning of redundant code: just to demonstrate the use of onImageRead and onUniqueRead events
recognizer.onImageRead = results => {
console.log("Finished reading an image:")
for (let result of results) {
for (let lineResult of result.lineResults) {
console.log(lineResult.text);
}
}
};
recognizer.onUniqueRead = (txt, results) => {
console.log("Found a new unique text:")
console.log(txt);
};
// End of redundant code.
await recognizer.startScanning(true);
})();
</script>
</body>
</html>
LabelRecognizer.createInstance(): This method creates a LabelRecognizer object called recognizer.
CameraEnhancer.createInstance(): this method creates a CameraEnhancer object called cameraEnhancer, which is used to control the camera as well as the default user interface. Once cameraEnhancer is bound to recognizer via setImageSource(), it can send video frames from the camera to recognizer for recognition as well as highlight the recognized text areas directly in the video feed.
updateRuntimeSettingsFromString("video-mrz"): this sets up recognizer with a built-in template optimized for reading MRZ from continous video frames. Note that all built-in templates starting with "video-" are only valid after cameraEnhancer has been bound to recognizer.
Built-in templates include
Name Description numberFor pure number recognition. numberLetterFor number and English letter recognition. numberUpperCaseFor number and uppercase English letter recognition. letterFor pure English letter recognition. MRZFor MRZ (machine-readable zone) recognition. passportMRZFor passport MRZ recognition. visaMRZFor Visa (Country not Credit Card) MRZ recognition. VINFor VIN (vehicle identification number) recognition. VIN_NAFor North American VIN (vehicle identification number) recognition. When recognizing from video input, add the prefix "video-" for a slightly different template optimized for continuous frame recognition. For example, use
video-passportMRZto read the MRZ on passports with a camera.
onMRZRead: This event is triggered each time the SDK has identified a MRZ zone and finished recognizing it. The results object contains 2 or 3 lines of text results corresponding to the 2 or 3 lines in the MRZ. In this example, we simply print the results to the browser console.
The events
onImageReadandonUniqueReadare used in the code but they are not required. You can compare the results returned in the 3 events and see what the differences are.
onImageRead: This event is triggered every time the SDK finishes scanning a video frame image. The results object contains all the text results that the SDK has found on this frame. In this example, we print the results to the browser console.
onUniqueRead: This event is triggered when the SDK finds a new text, which is not a duplicate among multiple frames. txt holds the text value while results is an array of objects that hold details of the text. In this example, an alert will be displayed for this new text.
startScanning(true): Starts continuous video frame scanning. The return value is a Promise which resovles when the camera is opened, the video shows up on the page and the scanning begins (which means cameraEnhancer has started feeding recognizer with frames to recognize).
Create a text file with the name "readMRZ.html", fill it with the code above and save. After that, open the example page in a browser, allow the page to access your camera and the video will show up on the page. After that, you can point the camera at something with a simple line of text to read it.
You can also just test it at https://jsfiddle.net/DynamsoftTeam/kc35htxd/
Remember to open the browser console to check the resulting text. Also note that the found text will be highlighted on the UI.
Note:
If the test doesn't go as expected, you can contact us.
You can also try the official sample for MRZ reading (test in Github or check the code). This sample also demonstrates how to parse the MRZ text into meaningful fields.
In this section, we'll break down and show all the steps required to build a web page that reads the machine readable zone (MRZ) on a passport.
The simplest way to include the SDK is to use either the jsDelivr or UNPKG CDN. The "hello world" example above uses jsDelivr. Since the recognition is mostly on a video input, we should also include the supporting SDK Dynamsoft Camera Enhancer.
jsDelivr
<script src="https://cdn.jsdelivr.net/npm/dynamsoft-label-recognizer@2.2.11/dist/dlr.js"></script>
<script src="https://cdn.jsdelivr.net/npm/dynamsoft-camera-enhancer@3.0.1/dist/dce.js"></script>
UNPKG
<script src="https://unpkg.com/dynamsoft-label-recognizer@2.2.11/dist/dlr.js"></script>
<script src="https://unpkg.com/dynamsoft-camera-enhancer@3.0.1/dist/dce.js"></script>
Besides using the CDN, you can also download the SDK and host its files on your own website / server before including it in your application.
To download the SDK:
yarn
yarn add dynamsoft-label-recognizer@2.2.11
yarn add dynamsoft-camera-enhancer@3.0.1
npm
npm install dynamsoft-label-recognizer@2.2.11
npm install dynamsoft-camera-enhancer@3.0.1
Depending on how you downloaded the SDK and where you put it, you can typically include it like this:
<script src="/dlr-js-2.2.11/dist/dlr.js"></script>
<script src="/dlr-js-2.2.11/dce/dist/dce.js"></script>
or
<script src="/node_modules/dynamsoft-label-recognizer/dist/dlr.js"></script>
<script src="/node_modules/dynamsoft-camera-enhancer/dist/dce.js"></script>
or
import { LabelRecognizer } from 'dynamsoft-label-recognizer';
import { CameraEnhancer, DrawingItem } from 'dynamsoft-camera-enhancer';
Before using the SDK, you need to configure a few things.
The SDK requires a license to work, use the API license to specify a license key.
Dynamsoft.DLR.LabelRecognizer.license = "YOUR-LICENSE-KEY";
To test the SDK, you can request a 30-day trial license via the customer portal.
If the engine files (*.worker.js, *.wasm.js and *.wasm, etc.) are not in the same location with the main SDK file (dlr.js), you can use the API engineResourcePath to specify the engine path, for example:
// The following code uses the jsDelivr CDN, feel free to change it to your own location of these files.
Dynamsoft.DLR.LabelRecognizer.engineResourcePath = "https://cdn.jsdelivr.net/npm/dynamsoft-label-recognizer@2.2.11/dist/";
Dynamsoft.DCE.CameraEnhancer.engineResourcePath = "https://cdn.jsdelivr.net/npm/dynamsoft-camera-enhancer@3.0.1/dist/";
This configuration is usually required with frameworks like Angular or React where dlr.js is compiled into another file.
The .data files are crucial for the recognition of certain types of text. For example, to read the MRZ zone on passports, the file MRZ.data must be loaded first. These .data files are loaded from the server on demand at runtime which could be time-consuming. To make the process user-friendly, it's recommended to show a visual cue about the loading process to the user with the help of the APIs onResourcesLoadStarted , onResourcesLoadProgress and onResourcesLoaded :
These files are cached locally as soon as they are downloaded, so they load very quickly from the second time on.
Dynamsoft.DLR.LabelRecognizer.onResourcesLoadStarted = (resourcePath) => {
// In this event handler, you can display a visual cue to show that the model file is being downloaded.
console.log("Loading " + resourcePath);
};
Dynamsoft.DLR.LabelRecognizer.onResourcesLoadProgress = (resourcePath, progress) => {
// In this event handler, you can display the loading progress of the model file.
console.log(resourcePath + "loading progress: " + progress.loaded + "/" + progress.total);
}
Dynamsoft.DLR.LabelRecognizer.onResourcesLoaded = (resourcePath) => {
// In this event handler, you can close the visual cue if it was displayed.
console.log("Finished loading " + resourcePath);
};
LabelRecognizer objectTo use the SDK, we first create a LabelRecognizer object.
let recognizer = null;
try {
recognizer = await Dynamsoft.DLR.LabelRecognizer.createInstance();
} catch (ex) {
console.error(ex);
}
CameraEnhancer object and bind it to the LabelRecognizer objectA CameraEnhancer object is required for video recognition.
let cameraEnhancer = await Dynamsoft.DCE.CameraEnhancer.createInstance();
let options = {
resultsHighlightBaseShapes: Dynamsoft.DCE.DrawingItem
};
await recognizer.setImageSource(cameraEnhancer, options);
In some cases, a different camera might be required instead of the default one. Also, a different resolution might work better. To change the camera or the resolution, we use the CameraEnhancer object. Learn more here.
// The following lines set which camera and what resolution to use.
let allCameras = await cameraEnhancer.getAllCameras();
await cameraEnhancer.selectCamera(allCameras[0]);
await cameraEnhancer.setResolution(1280, 720);
Check out the following code:
// Sets up the scanner behavior
let scanSettings = await recognizer.getScanSettings();
// Disregards duplicated results found in a specified time period (in milliseconds).
scanSettings.duplicateForgetTime = 5000; // The default is 3000
// Sets a scan interval in milliseconds so the SDK may release the CPU from time to time.
// (setting this value larger is a simple way to save battery power and reduce device heating).
scanSettings.intervalTime = 100; // The default is 0.
// Sets captureAndDecodeInParallel to false, which tells the SDK not to acquire the next frame while decoding the first.
// This is another way to save battery power and is recommended on low-end phones. However, it does slow down the decoding speed.
scanSettings.captureAndDecodeInParallel = false; // The default is true.
await recognizer.updateScanSettings(scanSettings);
// The following line configures the SDK to use the template "video-MRZ" which is one of the built-in RuntimeSetting templates:
// "number", "letter", "numberLetter", "numberUppercase", "VIN", "VIN_NA", "MRZ", "passportMRZ", "visaMRZ"
// "video-number", "video-letter", "video-numberLetter", "video-numberUppercase", "video-VIN", "video-VIN_NA", "video-MRZ", "video-passportMRZ", "video-visaMRZ"
// NOTE: For convenience, these names are not case-sensitive.
await recognizer.updateRuntimeSettingsFromString("video-passportMRZ");
As you can see from the above code snippets, there are two types of configurations:
get/updateScanSettings: Configures the behavior of the recognizer which includes duplicateForgetTime and intervalTime, etc.
updateRuntimeSettingsFromString: Configures the recognizer engine with a built-in template or a template represented by a JSON string. This will override the previous RuntimeSettings. In our case, we use the template "video-passportMRZ" which is meant for reading the machine readable zone (MRZ) on a passport.
Note that templates starting with "video-" are only valid after a
CameraEnhancerinstance has been bound to thisLabelRecognizerinstance.
The built-in UI of the LabelRecognizer object is defined in the file dist/dlr.ui.html . There are a few ways to customize it:
Modify the file dlr.ui.html directly.
This option is only possible when you host this file on your own web server instead of using a CDN. Note that this file is put in the dist directory of the dynamsoft-camera-enhancer package.
Copy the file dlr.ui.html to your application, modify it and pass its URL to the API setUIElement to set it as the default UI.
await cameraEnhancer.setUIElement("THE-URL-TO-THE-FILE");
Append the default UI element to your page, customize it before showing it.
<div id="recognizerUI"></div>
await cameraEnhancer.open();
document.getElementById('recognizerUI').appendChild(cameraEnhancer.getUIElement());
document.getElementsByClassName('dce-btn-close')[0].hidden = true; // Hide the close button
Build the UI element into your own web page and specify it with the API setUIElement(HTMLElement).
Embed the video
<div id="div-ui-container" style="width:100%;height:100%;">
<div class="dce-video-container" style="position:relative;width:100%;height:500px;"></div>
</div>
<script>
(async () => {
let cameraEnhancer = await Dynamsoft.DCE.CameraEnhancer.createInstance();
await cameraEnhancer.setUIElement(document.getElementById('div-ui-container'));
let recognizer = await Dynamsoft.DLR.LabelRecognizer.createInstance();
let options = {
resultsHighlightBaseShapes: Dynamsoft.DCE.DrawingItem
};
await recognizer.setImageSource(cameraEnhancer, options);
await recognizer.updateRuntimeSettingsFromString("video-passportMRZ");
await recognizer.startScanning(true);
})();
</script>
The video element will be created and appended to the DIV element with the class
dce-video-container, make sure the class name is the correct. Also note that the CSS propertypositionof the DIV element must be eitherrelative,absolute,fixed, orsticky.
Add the camera list and resolution list
If the class names for these lists match the default ones, dce-sel-camera and dce-sel-resolution , the SDK will automatically populate the lists and handle the camera/resolution switching.
<div id="div-ui-container" style="width:100%;height:100%;">
<select class="dce-sel-camera"></select><br>
<div class="dce-video-container" style="position:relative;width:100%;height:500px;"></div>
</div>
<div id="div-ui-container">
<select class="dce-sel-camera"></select>
<select class="dce-sel-resolution"></select>
<br>
<div class="dce-video-container" style="position:relative;width:100%;height:500px;"></div>
</div>
By default, only 3 hard-coded resolutions (3840 x 2160, 1920 x 1080, 1280 x 720), are populated as options. You can show a customized set of options by hardcoding them.
<select class="dce-sel-resolution">
<option class="dce-opt-gotResolution" value="got"></option>
<option data-width="1280" data-height="720">1280x720</option>
<option data-width="1920" data-height="1080">1920x1080</option>
</select>
Generally, you need to provide a resolution that the camera supports. However, in case a camera does not support the specified resolution, it usually uses the cloest supported resolution. As a result, the selected resolution may not be the actual resolution. In this case, add an option with the class name
dce-opt-gotResolution(as shown above) and the SDK will then use it to show the actual resolution.
The last step is to attach event handlers to the events onImageRead (optional) and onMRZRead before calling startScanning() to starts the recognition process.
recognizer.onImageRead = results => {
for (let result of results) {
for (let lineResult of result.lineResults) {
console.log(lineResult.text);
}
}
};
recognizer.onMRZRead = (txt, results) => {
// In this event handler, you get a two-line string recognized from the MRZ on passports from which you can further decode and display meaningful information such as name, nationality, etc.
// Note that if you use the template video-MRZ, you may also get a three-line string.
alert(txt);
};
await recognizer.startScanning(true);
You can check out the detailed documentation about the APIs of the SDK at https://www.dynamsoft.com/label-recognition/docs/programming/javascript/api-reference/?ver=2.2.11&utm_source=npm&product=dlr&package=js.
DLR requires the following features to work:
Secure context (HTTPS deployment)
When deploying your application / website for production, make sure to serve it via a secure HTTPS connection. This is required for two reasons
Some browsers like Chrome may grant the access for
http://127.0.0.1andhttp://localhostor even for pages opened directly from the local disk (file:///...). This can be helpful for temporary development and test.
WebAssembly, Blob, URL/createObjectURL, Web Workers
The above four features are required for the SDK to work.
MediaDevices/getUserMedia
This API is only required for in-browser video streaming. If a browser does not support this API, the Single Frame Mode will be used automatically. If the API exists but doesn't work correctly, the Single Frame Mode can be used as an alternative way to access the camera.
getSettings
This API inspects the video input which is a MediaStreamTrack object about its constrainable properties.
The following table is a list of supported browsers based on the above requirements:
| Browser Name | Version |
|---|---|
| Chrome | v61+1 |
| Firefox | v52+ (v55+ on Android/iOS1) |
| Edge2 | v16+ |
| Safari3 | v11+ |
1 iOS 14.3+ is required for camera video streaming in Chrome and Firefox or Apps using webviews.
2 On Edge, due to strict Same-origin policy, you must host the SDK files on the same domain as your web page.
3 Safari v11.x already has the required features, but it has many other issues, so we recommend v12+.
Apart from the browsers, the operating systems may impose some limitations of their own that could restrict the use of the SDK. Browser compatibility ultimately depends on whether the browser on that particular operating system supports the features listed above.
Learn about what are included in each release at https://www.dynamsoft.com/label-recognition/docs/programming/javascript/release-notes/?ver=latest.
Now that you have got the SDK integrated, you can choose to move forward in the following directions
FAQs
Dynamsoft Label Recognizer (DLR) is an SDK designed to recognize meaningful zonal text or symbols in an image (Label). Common scenarios include price tags in supermarkets, inventory labels in warehouses, VIN codes on car windshields, driver licenses, pass
We found that dynamsoft-label-recognizer demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 0 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
RubyGems.org has added a new "maintainer" role that allows for publishing new versions of gems. This new permission type is aimed at improving security for gem owners and the service overall.
Security News
Node.js will be enforcing stricter semver-major PR policies a month before major releases to enhance stability and ensure reliable release candidates.
Security News
Research
Socket's threat research team has detected five malicious npm packages targeting Roblox developers, deploying malware to steal credentials and personal data.