Skip to content

Barcode Scanner API Overview

The Barcode Scanner API lets you detect and read barcodes, its type, and retrieve its instance information.

See Best Practices for Barcode Scanning for information on the recommendations on barcode detection, the difference between 1-dimensional and 2-dimensional barcodes and choosing suitable barcodes.

General Setup

Please see the Engine Lifecycle for a general introduction to the Vuforia Engine lifecycle. The Engine is required for creating and using Observers.

Create Barcode Observer

Barcode detection is activated by creating a Barcode Observer. A Barcode Observer's default configuration initializes with all supported barcode types. The Barcode Observer is activated by default upon creation.

1
2
3
4
5
6
// Create an Observer config
VuBarcodeConfig barcodeConfig = vuBarcodeConfigDefault(); 
VuObserver* observer = nullptr; 

// Create a Barcode Observer
vuEngineCreateBarcodeObserver(engine, &observer, &barcodeConfig, nullptr);

Only one Barcode Observer can be active at a time.

Configuring Barcode types

Specifying the types of barcodes to detect is optional. In cases where the barcode type is known ahead of time, we recommend restricting the detection to those types being used. For example, if only detection of QR-codes is required, the Observer can be configured accordingly before creation.

1
2
3
4
5
6
7
8
// Specify the barcode types
VuBarcodeTypeSet* types = nullptr; 
vuBarcodeTypeSetCreate(&types); 
vuBarcodeTypeSetAddElement(types, VU_BARCODE_TYPE_QRCODE); 
barcodeConfig.observedTypes = types; 

// Create the Observer
vuEngineCreateBarcodeObserver(engine, &observer, &barcodeConfig, nullptr);

See the API reference documentation for supported VuBarcodeType. The default value is null which sets the types to all supported types.

After setting the barcode type for the Barcode Observer, you can destroy the types:

1
vuBarcodeTypeSetDestroy(types);

Configuring Barcode detection mode

You can set the detection mode to observe a single barcode at a time or multiple simultaneously with VuBarcodeDetectionMode. A single barcode detection improves device performance. Multiple barcode detections in parallel has higher performance requirements and will produce an observation for each barcode. Use the following Enums to define the detection mode:

  • VU_BARCODE_DETECTION_MODE_SINGLE
  • VU_BARCODE_DETECTION_MODE_MULTIPLE

Observations

The Barcode Observer produces a Barcode Observation on the State for each detected barcode instance. See the Observer and Observations article for more details on how to work with Observations.

Creation of Observation List

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
// Create observation list
VuObservationList* observationList = nullptr; 
vuObservationListCreate(&observationList); 
vuStateGetBarcodeObservations(&state, observationList); 

// Then, parse the observations to access the currently detected barcodes 
int numObservations = 0; 
vuObservationListGetSize(observationList, &numObservations); 
for (int i = 0; i < numObservations; i++) 
{ 
   VuObservation* observation = nullptr; 
   vuObservationListGetElement(observationList, i, &observation); 
   VuBarcodeObservationInstanceInfo instanceInfo; 
   vuBarcodeObservationGetInstanceInfo(observation, &instanceInfo); 
}

Destroy ObservationList

1
vuObservationListDestroy(observationList); 

Destroy the Observer

1
vuObserverDestroy(barcodeObserver);

Instance info

A barcode's payload is stored in VuBarcodeObservationInstanceInfo. Each instance info contains the following information about a detected barcode:

  • The actual payload of the barcode, encoded as a UTF-8 string. Accessible with buffer.
  • The type of barcode (e.g., EAN-13, CODE 39, QR-CODE). Accessible with type.
  • The 2D coordinates of the four corners of the barcode. Note that these are normalized coordinates in the [0.0-1.0] range. Accessible with vertices.
1
2
3
4
5
6
// Access barcode payload 
instanceInfo.buffer;
instanceInfo.type;

// Access barcode boundary coordinates 
instanceInfo.vertices;

Tracking Barcodes Across Frames

In some cases (e.g., when visualizing the detection results), it is useful to know which observation in a previous frame corresponds to the current observation. For this purpose, the Vuforia Engine assigns a unique id to each barcode which is kept consistent as long as the barcode is visible.

1
2
3
4
5
VuBarcodeObservationInfo barcodeInfo; 
vuBarcodeObservationGetInfo(observation, &barcodeInfo); 

// Access the unique id 
barcodeInfo.id;

Target Information

Get the set of supported barcode types of an activated Barcode Observer:

1
2
3
4
VuObserver* observer;
VuBarcodeTypeSet* types = nullptr;
vuBarcodeTypeSetCreate(&types);
vuBarcodeObserverGetObservedTypes(observer, types);

Get the number of elements in a barcode type set:

1
2
3
VuBarcodeTypeSet* types;
int setSize;
vuBarcodeTypeSetGetSize(types, &setSize);

Learn More

Vuforia Engine Lifecycle

Observer and Observations

Best Practices for Barcode Scanning

Barcode Scanner

Barcodes in Unity