Setting up the scanning area for code selection

This document explains how to configure the barcode scanner for code selection.

By default, barcodes and 2d codes are scanned in the whole image. While this is the desired behavior for most applications, depending on your requirements, you might want to modify the scanning areas to tweak the scanning performance for your use-case. For example, when scanning codes on a sheet with densely packed barcodes, or 2d codes, it is difficult to point the device at one code in particular. As a result the code that gets scanned is unpredictable. To provide a better scanning experience, you should restrict the area in which codes are scanned to a subset of the image.

This document outlines the options for tweaking the scan performance for these code selection use-cases.

The symbologies supported by the Scandit BarcodeScanner SDK have been classified into two groups. Symbologies with a large width/height ratio are classified as wide codes, symbologies with a width/height aspect ratio close to one are classified as square codes. Wide codes include all classic linear barcode symbologies such as Code 128, EAN-13, UPC-A, EAN-8 etc. as well as PDF417, MicroPDF417 and postal codes (KIX, RM4SCC etc.). It also includes the DataBar class of symbologies. Square symbologies include QR Code, Data Matrix, MaxiCode and Aztec. Data Matrix is classified as a square symbology, even though non-square versions exist. But since square Data Matrix symbols are much more common, it is classified as such.

The scanning process can be configured with three different areas:

  • The search area is the area in which codes are searched. In this area, codes can be scanned at any angle, e.g. at a rotation of 0, 90, or 32 degrees. By default, this area is set to the whole image. The search area affects the search of both wide and square codes.
  • The remaining two areas, the wide and square location areas affect wide, or square codes, respectively. There are 3 different constraint modes for these areas. restrict, hint, and ignore. If the constraint is set to restrict, square/wide codes will only be scanned in the provided area. If the mode is hint, codes continue to be searched in the search area, and the area is just used as a hint as to where codes are most likely to be found. Codes are searched with more effort in this area. If code is set to ignore, the wide/square areas are ignored.

All the areas are specified in relative coordinates, where the top-left corner has the coordinates (0,0), and the bottom-right corner has the coordinates (1,1). These areas are automatically rotated with the device. The coordinate (0,0) always indicates the top-left corner of the preview on the screen, even if the device is is portrait, portrait-upside-down or reversed landscape orientation. Before the rectangles are applied to the barcode scanner, they are rotated into image-space.

Coordinate System

For all platforms, except Android, rectangle coordinates are provided using the top-left corner and size, on Android rectangle coordinates are provided with top-left and bottom-right corners.


For code-selection, 3 different use-cases exist:

(a) Selecting stacked wide codes, e.g. a sheet of vertically-stacked Code 128. No square codes are enabled, or they should be scanned in the whole image.

Code Selection for Wide Codes

(b) Selecting a square code, e.g. Data Matrix, from a list of horizontally arranged codes. No wide codes are enabled, or they should be scanned in the whole image.

Code Selection for Square Codes

(c) A combination of (a) and (b): Selecting stacked wide codes as well as square codes.

The table below lists recommended configurations for the wide/square and search areas for the three scenarios mentioned above. The rectangles have been optimized for an image with a HD/Full-HD aspect ratio (1920/1080 =1280/720 = 1.777). The width and height of the square area have been chosen such that the resulting rectangle in pixels has equal height and width. For an image in portrait mode, or an image with different aspect ratio, you will have to adjust the width and height accordingly.

Scenario Search Area Wide Area Wide Constraint Square Area Square Constraint
(a) Wide Code Selection left=0,top=0,width=1,height=1 left=0,top=0.45,width=1,height=0.1 restrict left=0,top=0,width=1,height=1 hint
(b) Square Code Selection left=0,top=0,width=1,height=1 left=0,top=0.375,width=1,height=0.25 hint left=0.4,top=0.325,width=0.2,height=0.35 restrict
(c) Wide/Square Selection left=0,top=0,width=1,height=1 left=0,top=0.45,width=1,height=0.1 restrict left=0.4,top=0.325,width=0.2,height=0.35 restrict

For details on how to configure the scanning area on different platforms, take a look at the platform-specific documentation: iOS, Android