BarcodeReader for Images

A low-level barcode reader that processes still images and return barcode results. The following code snippet shows its basic usage.

let reader = await Dynamsoft.DBR.BarcodeReader.createInstance();
let results = await reader.decode(imageSource);
for (let result of results) {
    console.log(result.barcodeText);
}

API Index

Create and Destroy Instances

Decode Barcodes

Decode Barcodes on multiple images from an Image Source

Change Settings

Auxiliary

createInstance

Creates a BarcodeReader instance.

static createInstance(): Promise<BarcodeReader>

Return Value

A promise resolving to the created BarcodeReader object.

Code Snippet

let reader = await Dynamsoft.DBR.BarcodeReader.createInstance();

See Also

• destroyContext

destroyContext

Destroies the BarcodeReader instance. If your page needs to create new instances from time to time, don’t forget to destroy unused old instances.

destroyContext(): void

Code Snippet

let reader = await Dynamsoft.DBR.BarcodeReader.createInstance();
// ... decode ...
reader.destroyContext();

See Also

• isContextDestroyed

isContextDestroyed

Returns whether the instance has been destroyed.

isContextDestroyed(): boolean

See Also

• destroyContext

decode

Decodes barcodes from an image.

decode(source: Blob | Buffer | ArrayBuffer | Uint8Array | Uint8ClampedArray | HTMLImageElement | HTMLCanvasElement | HTMLVideoElement | DCEFrame | DSImage | string): Promise<TextResult[]>

If the content in the binary data is raw img data, such as RGBA , use decodeBuffer() instead.

Parameters

source : specifies the image to decode. The supported image formats include png , jpeg , bmp , gif and a few others (some browsers support webp , tif ). Also note that the image can be specified in a lot of ways including binary data, base64 string (with MIME), URL, etc.

To speed up the reading, the image will be scaled down when it exceeds a size limit either horizontally or vertically.

• The limit is 2048 pixels on mobile devices and 4096 on other devices.
• If the template “dense” or “distance” is used, the limit is 4096 regardless of which device is used.

Therefore, setting a very high resolution will not help with the scanning.

Return Value

A promise resolving to an array of TextResult object that contains the barcode results found in this image.

Code Snippet

let results1 = await reader.decode(blob);
let results2 = await reader.decode(htmlImageElement);
let results3 = await reader.decode(url);
let results4 = await reader.decode(strBase64WithMime); // like `data:image/png;base64,iV************`

You can even use an HTMLVideoElement as the source. If the video is playing, the current frame will be decoded.

let results;
try {
    // The current frame will be decoded.
    results = await reader.decode(htmlVideoElement);
} catch (ex) {
    // If there is no frame in the video, throw an exception.
}

See Also

• Blob
• Buffer
• ArrayBuffer
• Uint8Array
• Uint8ClampedArray
• HTMLImageElement
• HTMLCanvasElement
• HTMLVideoElement
• TextResult
• DSImage
• DCEFrame

decodeBase64String

Decodes barcodes from a base64-encoded image (with or without MIME).

decodeBase64String(base64Str: string): Promise<TextResult[]>

Parameters

base64Str : specifies the image represented by a string.

Return Value

A promise resolving to an array of TextResult object that contains the barcode results found in this image.

Code Snippet

let results = await reader.decodeBase64String(strBase64); //e.g. `data:image/jpg;base64,Xfjshekk....` or `Xfjshekk...`.
for (let result of results) {
    console.log(result.barcodeText);
}

See Also

• TextResult

decodeUrl

Decodes barcodes from an image specified by its URL.

Note that the image should either be from the same domain or has the ‘Access-Control-Allow-Origin’ header set to allow access from your current domain.

decodeUrl(url: string): Promise<TextResult[]>

Parameters

url : specifies the image by its URL.

Return Value

A promise resolving to an array of TextResult object that contains the barcode results found in this image.

Code Snippet

let results = await reader.decodeUrl("https://www.yourdomain.com/imageWithBarcodes.png");
for (let result of results) {
    console.log(result.barcodeText);
}

See Also

• TextResult

decodeBuffer

Decodes barcodes from raw image data. It is an advanced API, if you don’t know what you are doing, use decode instead.

decodeBuffer(buffer: Blob | Buffer | ArrayBuffer | Uint8Array | Uint8ClampedArray, width: number, height: number, stride: number, format: EnumImagePixelFormat, orientation?: number): Promise<TextResult[]>

Parameters

buffer : specifies the raw image represented by a Uint8Array , Uint8ClampedArray , ArrayBuffer , Blob or Buffer object.

width : image width.

height : image height.

stride : image-width * pixel-byte-length .

format : pixel format.

orientation: specifies the oritation of the image data.

Return Value

A promise resolving to an array of TextResult object that contains the barcode results found in this image.

Code Snippet

let results = await reader.decodeBuffer(u8RawImage, 1280, 720, 1280 * 4, Dynamsoft.DBR.EnumImagePixelFormat.IPF_ABGR_8888);
for (let result of results) {
    console.log(result.barcodeText);
}

See Also

• Blob
• Buffer
• ArrayBuffer
• Uint8Array
• Uint8ClampedArray
• EnumImagePixelFormat
• TextResult

getRuntimeSettings

Returns the current runtime settings.

getRuntimeSettings(): Promise<RuntimeSettings>

Return Value

A promise resolving to a RuntimeSettings object that contains the settings for barcode reading.

Code Snippet

let settings = await reader.getRuntimeSettings();
settings.barcodeFormatIds = Dynamsoft.DBR.EnumBarcodeFormat.BF_QR_CODE; // Decodes only QR code.
await reader.updateRuntimeSettings(settings);

See Also

• RuntimeSettings
• updateRuntimeSettings
• resetRuntimeSettings

initRuntimeSettingsWithString

Initializes the RuntimeSettings with the settings in the given JSON string.

initRuntimeSettingsWithString(template: string): Promise<void>

Parameters

template : a string representing the template.

Return Value

A promise that resolves when the operation succeeds.

See Also

• RuntimeSettings
• updateRuntimeSettings

updateRuntimeSettings

Updates runtime settings with a given struct or a preset template represented by one of the following strings:

• speed: fast but may miss a few codes;
• coverage: slow but try to find all codes, this is the default setting for a BarcodeReader instance;
• balance: between speed and coverage;
• single: optimized for scanning one single barcode from a video input, this is supported only by the sub-class BarcodeScanner and is also the default setting for a BarcodeScanner instance;
• dense: optimized for scanning dense barcodes such as the PDF417 on driver’s license;
• distance: optimized for scanning a barcode that is placed far from the device and appear small in the video stream.

NOTE

If the settings barcodeFormatIds , barcodeFormatIds_2 and region have been changed by the customer, changing the template will preserve the previous settings.

updateRuntimeSettings(settings: RuntimeSettings | string): Promise<void>

Parameters

settings : a RuntimeSettings object that contains the new settings for barcode reading.

Return Value

A promise that resolves when the operation succeeds.

Code Snippet

await reader.updateRuntimeSettings('balance');
let settings = await reader.getRuntimeSettings();
settings.barcodeFormatIds = Dynamsoft.DBR.EnumBarcodeFormat.BF_ONED;
await reader.updateRuntimeSettings(settings);

See Also

• RuntimeSettings
• getRuntimeSettings
• resetRuntimeSettings

resetRuntimeSettings

Resets all parameters to default values.

For a BarcodeReader instance, it is equivalent to setting the coverage template.

For a BarcodeScanner instance, it is equivalent to setting the single template.

resetRuntimeSettings(): Promise<void>

Parameters

None.

Return Value

A promise that resolves when the operation succeeds.

Code Snippet

await reader.resetRuntimeSettings();

outputRuntimeSettingsToString

Return the current RuntimeSettings in the form of a string.

outputRuntimeSettingsToString(): Promise<string>

Return Value

A promise resolving to a string which represents the current RuntimeSettings.

See Also

• RuntimeSettings
• getRuntimeSettings

getModeArgument

Returns the argument value for the specified mode parameter.

getModeArgument(modeName: string, index: number, argumentName: string): Promise<string>

Parameters

modeName : specifies the mode which contains one or multiple elements.

index : specifies an element of the mode by its index.

argumentName : specifies the argument.

Return Value

A promise resolving to a string which represents the value of the argument.

Code Snippet

let argumentValue = await reader.getModeArgument("BinarizationModes", 0, "EnableFillBinaryVacancy");

See Also

• setModeArgument

setModeArgument

Sets the argument value for the specified mode parameter.

setModeArgument(modeName: string, index: number, argumentName: string, argumentValue: string): Promise<void>

Parameters

modeName : specifies the mode which contains one or multiple elements.

index : specifies an element of the mode by its index.

argumentName : specifies the argument.

argumentValue : specifies the value.

Return Value

A promise that resolves when the operation succeeds.

Code Snippet

await reader.setModeArgument("BinarizationModes", 0, "EnableFillBinaryVacancy", "1");

See Also

• getModeArgument

ifSaveOriginalImageInACanvas

Whether to save the original image into a <canvas> element. The original image refers to the actual image the library tried to read barcodes from. It can be returned by ‘getOriginalImageInACanvas()’.

ifSaveOriginalImageInACanvas: boolean;

Default value

false

Code Snippet

reader.ifSaveOriginalImageInACanvas = true;
let results = await reader.decode(source);
document.body.append(reader.getOriginalImageInACanvas());

See Also

• getOriginalImageInACanvas

getOriginalImageInACanvas

An HTMLCanvasElement that holds the original image. The original image refers to the actual image the library tried to read barcodes from.

getOriginalImageInACanvas(): HTMLCanvasElement

Code Snippet

reader.ifSaveOriginalImageInACanvas = true;
let results = await reader.decode(source);
document.body.append(reader.getOriginalImageInACanvas());

See Also

• ifSaveOriginalImageInACanvas
• HTMLCanvasElement

setImageSource

Sets an image source for continous scanning.

setImageSource: (imageSource: ImageSource, options?: object)=>Promise<void>;

Parameters

imageSource : Specifies the image source.

options : Options to help with the usage of the ImageSource object. At present, it only contains one property resultsHighlightBaseShapes that accepts Dynamsoft.DCE.DrawingItem as its value to help with the highlighting of barcode regions as shown in the code snippet below. More properties will be added as needed in the future.

Return Value

A promise that resolves when the operation succeeds.

Code Snippet

let reader = await Dynamsoft.DBR.BarcodeReader.createInstance();
let enhancer = await Dynamsoft.DCE.CameraEnhancer.createInstance();
let options = {
    resultsHighlightBaseShapes: Dynamsoft.DCE.DrawingItem
};
await reader.setImageSource(enhancer, options);
reader.onUniqueRead = (txt, result) => {
    console.log(txt);
};
await reader.startScanning(true);

See Also

• ImageSource

onUniqueRead

This event is triggered when a new, unduplicated label is found.

onUniqueRead: (txt: string, result: TextResult) => void

Arguments

txt : a string that holds the label text (one single line).

result : a TextResult object that contains more detailed info about the returned text.

Code Snippet

let reader = await Dynamsoft.DBR.BarcodeReader.createInstance();
let enhancer = await Dynamsoft.DCE.CameraEnhancer.createInstance();
let options = {
    resultsHighlightBaseShapes: Dynamsoft.DCE.DrawingItem
};
await reader.setImageSource(enhancer, options);
reader.onUniqueRead = (txt, result) => {
    console.log(txt);
}
await reader.startScanning(true);

See Also

• TextResult
• onImageRead

onImageRead

This event is triggered after the library finishes scanning a image.

onImageRead: (results: TextResult[]) => void

Arguments

results : an array of TextResult object that contains the barcode results in this image.

Code Snippet

let reader = await Dynamsoft.DBR.BarcodeReader.createInstance();
let enhancer = await Dynamsoft.DCE.CameraEnhancer.createInstance();
let options = {
    resultsHighlightBaseShapes: Dynamsoft.DCE.DrawingItem
};
await reader.setImageSource(enhancer, options);
reader.onImageRead = (results) => {
    if (results.length > 0) {
        results.forEach(result => {
            console.log(result.barcodeText);
        });
    }
};
await reader.startScanning(true);

See Also

• TextResult
• onUniqueRead

startScanning

Open the camera and starts continuous scanning of incoming images.

startScanning(appendOrShowUI?: boolean): Promise<ScannerPlayCallbackInfo>;

Parameters

appendOrShowUI : this parameter specifies how to handle the UI that comes with the bound CameraEnhancer instance. When set to true, if the UI doesn’t exist in the DOM tree, the CameraEnhancer instance will append it in the DOM and show it; if the UI already exists in the DOM tree but is hidden, it’ll be displayed. When not set or set to false, it means not to change the original state of that UI: if it doesn’t exist in the DOM tree, nothing shows up on the page; if it exists in the DOM tree, it may or may not show up depending on its original state.

Return Value

A promise resolving to a ScannerPlayCallbackInfo object which contains the resolution of the video.

Code Snippet

let reader = await Dynamsoft.DBR.BarcodeReader.createInstance();
let enhancer = await Dynamsoft.DCE.CameraEnhancer.createInstance();
let options = {
    resultsHighlightBaseShapes: Dynamsoft.DCE.DrawingItem
};
await reader.setImageSource(enhancer, options);
reader.onUniqueRead = (txt, result) => {
    console.log(txt);
}
await reader.startScanning(true);

See Also

• ScannerPlayCallbackInfo
• stopScanning
• pauseScanning
• resumeScannig

pauseScanning

Pause continuous scanning but keep the video stream.

pauseScanning(options?: object): void;

Parameters

options: options to configure how the pause works. At present, it only contains one property keepResultsHighlighted which, when set to true, will keep the barcodes found on the frame (at the time of the pause) highlighted.

See Also

• resumeScanning

resumeScanning

Resumes continuous scanning.

resumeScanning(): void;

See Also

• pauseScanning

stopScanning

Stops continuous scanning and closes the video stream.

stopScanning(hideUI?: boolean): void;

Parameters

hideUI : this parameter specifies how to handle the UI that comes with the bound CameraEnhancer instance. When set to true, if the UI doesn’t exist in the DOM tree or it exists but is hidden, nothing is done; if the UI already exists in the DOM tree and is shown, it’ll be hidden. When not set or set to false, it means not to change the original state of that UI: if it doesn’t exist in the DOM tree, nothing happens; if it exists in the DOM tree, it may or may not be hidden depending on its original state.

Code Snippet

let reader = await Dynamsoft.DBR.BarcodeReader.createInstance();
let enhancer = await Dynamsoft.DCE.CameraEnhancer.createInstance();
let options = {
    resultsHighlightBaseShapes: Dynamsoft.DCE.DrawingItem
};
await reader.setImageSource(enhancer, options);
reader.onUniqueRead = (txt, result) => {
    console.log(txt);
    reader.stopScanning(true);
}
await reader.startScanning(true);

See Also

• startScanning
• pauseScanning
• resumeScannig

getScanSettings

Returns the current scan settings.

getScanSettings(): Promise<ScanSettings>

Return Value

A promise resolving to a ScanSettings .

Code Snippet

let scanSettings = await reader.getScanSettings();
scanSettings.intervalTime = 50;
scanSettings.duplicateForgetTime = 1000;
await reader.updateScanSettings(scanSettings);

See Also

• ScanSettings
• updateScanSettings

updateScanSettings

Changes scan settings with the object passed in.

updateScanSettings(settings: ScanSettings): Promise<void>

Parameters

settings : specifies the new scan settings.

Return Value

A promise that resolves when the operation succeeds.

Code Snippet

let scanSettings = await reader.getScanSettings();
scanSettings.intervalTime = 50;
scanSettings.duplicateForgetTime = 1000;
await reader.updateScanSettings(scanSettings);

See Also

• ScanSettings
• getScanSettings