Barcode Detection

Experimental API for detecting and decoding 1D (linear) and 2D (matrix) barcodes in a 2D image. Resides in Zivid::Experimental::Toolbox and may change without prior notice.

        %%{init: {'themeVariables': {'fontSize': '18px'}, 'flowchart': {'nodeSpacing': 30, 'rankSpacing': 35}}}%%
flowchart LR
  ImageBGRA["Image<ColorBGRA>"]

  detectOp(["detect()"])
  decodeOp(["decode()"])

  LinearBarcodeDetectionResult
  LinearBarcodeDecodingResult["[LinearBarcodeDecodingResult]"]

  ImageBGRA -.-> detectOp --> LinearBarcodeDetectionResult
  LinearBarcodeDetectionResult --> decodeOp --> LinearBarcodeDecodingResult

  classDef zividClass fill:#4A8FA4,stroke:#34323D,color:#FFFFFF
  classDef api fill:#91D2C8,stroke:#4A8FA4,color:#000000
  class ImageBGRA,LinearBarcodeDetectionResult,LinearBarcodeDecodingResult zividClass
  class detectOp,decodeOp api
    

BarcodeDetector

Detects barcodes in a Image<ColorBGRA>. Call detect() to obtain a LinearBarcodeDetectionResult, then decode() on the result to get the decoded barcode strings.

C++

class BarcodeDetector

Class for enabling the detection of barcodes.

Constructing an instance of this class initializes the resources needed for efficient barcode detection. For repeated detection it is recommended to keep and re-use an instance of this class and not create a new one every time.

The recommended workflow for detecting barcodes with an instance of this class is:

1. Call BarcodeDetector::suggestSettings once to get a suitable Settings2D for your camera. Alternatively, create or load your own Settings2D optimized for your use-case.

2. Whenever you want to capture an image for barcode detection, call Camera::capture2D using the Settings2D. This will yield a Frame2D instance.

3. Running the algorithm to detect and decode barcodes in the image can then be done immediately or later by passing the Frame2D to BarcodeDetector::readLinearCodes or BarcodeDetector::readMatrixCodes.

Public Functions

BarcodeDetector()

Constructor.

Settings2D suggestSettings(Camera &camera) const

Get 2D capture settings that are ideal for barcode reading with the given camera.

Parameters:

camera – The camera to find barcode settings for.

Returns:

A Settings2D instance

std::vector<LinearBarcodeDetectionResult> detectLinearCodes(const Frame2D &frame2d) const

Detect linear (1D) barcode candidate regions based on the result of a 2D capture.

This function detects potential barcode regions in the image but does not attempt to decode them. Since decoding has not yet been attempted, the list of regions returned are likely to contain some false positives (regions that look like barcodes but are not actually barcodes). Use BarcodeDetector::decodeLinearCodes to attempt to decode some or all candidate image regions.

Parameters:

frame2d – A Frame2D instance from a 2D or 2D+3D capture

Returns:

A sequence of LinearBarcodeDetectionResult (one per detected barcode candidate)

std::vector<LinearBarcodeDetectionResult> detectLinearCodes(const Sensor::Frame2D &frame2d) const

Detect linear (1D) barcode candidate regions based on the result of a 2D capture.

This function detects potential barcode regions in the image but does not attempt to decode them. Since decoding has not yet been attempted, the list of regions returned are likely to contain some false positives (regions that look like barcodes but are not actually barcodes). Use BarcodeDetector::decodeLinearCodes to attempt to decode some or all candidate image regions.

Parameters:

frame2d – A Sensor::Frame2D instance from a sensor 2D capture

Returns:

A sequence of LinearBarcodeDetectionResult (one per detected barcode candidate)

std::vector<LinearBarcodeDetectionResult> detectLinearCodes(const DeviceArrayView<ColorRGBAf> &imageDeviceArray, const Sensor::FrameMetadata &metadata) const

Detect linear (1D) barcode candidate regions based on the result of a 2D capture.

This function detects potential barcode regions in the image but does not attempt to decode them. Since decoding has not yet been attempted, the list of regions returned are likely to contain some false positives (regions that look like barcodes but are not actually barcodes). Use BarcodeDetector::decodeLinearCodes to attempt to decode some or all candidate image regions.

Parameters:

• imageDeviceArray – A DeviceArray coming from a 2D sensor frame

• metadata – Metadata about the DeviceArray

Returns:

A sequence of LinearBarcodeDetectionResult (one per detected barcode candidate)

std::vector<std::optional<LinearBarcodeDecodingResult>> decodeLinearCodes(const std::vector<LinearBarcodeDetectionResult> &detectionResults, const LinearBarcodeFormatFilter &formatFilter = LinearBarcodeFormatFilter::all()) const

Decode linear (1D) barcode candidate regions.

This function attempts to decode barcode candidates that were previously detected using BarcodeDetector::detectLinearCodes. The ordering of the returned decoding results matches the ordering of the input detection results. If a specific candidate failed to decode, the corresponding element in the returned sequence will be nullopt.

By default this function will attempt to detect and decode all supported barcode formats. Users can achieve increased detection speed and reliability by using the formatFilter argument to specify a subset of formats, for example LinearBarcodeFormat::ean13 | LinearBarcodeFormat::ean8.

Parameters:

• detectionResults – Results from a previous call to detectLinearCodes

• formatFilter – A filter defining which barcode formats to look for.

Returns:

A sequence of optional LinearBarcodeDecodingResult (nullopt if decoding failed)

std::vector<LinearBarcodeDecodingResult> readLinearCodes(const Frame2D &frame2d, const LinearBarcodeFormatFilter &formatFilter = LinearBarcodeFormatFilter::all()) const

Detect and decode linear (1D) barcodes based on the result of a 2D capture.

By default this function will attempt to detect and decode all supported barcode formats. Users can achieve increased detection speed and reliability by using the formatFilter argument to specify a subset of formats, for example LinearBarcodeFormat::ean13 | LinearBarcodeFormat::ean8.

Parameters:

• frame2d – A Frame2D instance from a 2D or 2D+3D capture

• formatFilter – A filter defining which barcode formats to look for.

Returns:

A sequence of LinearBarcodeDecodingResult (one per successfully decoded barcode)

std::vector<LinearBarcodeDecodingResult> readLinearCodes(const Sensor::Frame2D &frame2d, const LinearBarcodeFormatFilter &formatFilter = LinearBarcodeFormatFilter::all()) const

Detect and decode linear (1D) barcodes based on the result of a 2D capture.

By default this function will attempt to detect and decode all supported barcode formats. Users can achieve increased detection speed and reliability by using the formatFilter argument to specify a subset of formats, for example LinearBarcodeFormat::ean13 | LinearBarcodeFormat::ean8.

Parameters:

• frame2d – A Sensor::Frame2D instance from a sensor 2D capture

• formatFilter – A filter defining which barcode formats to look for.

Returns:

A sequence of LinearBarcodeDecodingResult (one per successfully decoded barcode)

std::vector<LinearBarcodeDecodingResult> readLinearCodes(const DeviceArrayView<ColorRGBAf> &imageDeviceArray, const Sensor::FrameMetadata &metadata, const LinearBarcodeFormatFilter &formatFilter = LinearBarcodeFormatFilter::all()) const

Detect and decode linear (1D) barcodes based on the result of a 2D capture.

By default this function will attempt to detect and decode all supported barcode formats. Users can achieve increased detection speed and reliability by using the formatFilter argument to specify a subset of formats, for example LinearBarcodeFormat::ean13 | LinearBarcodeFormat::ean8.

Parameters:

• imageDeviceArray – A DeviceArray coming from a 2D frame

• metadata – Metadata about the DeviceArray

• formatFilter – A filter defining which barcode formats to look for.

Returns:

A sequence of LinearBarcodeDecodingResult (one per successfully decoded barcode)

std::vector<MatrixBarcodeDecodingResult> readMatrixCodes(const Frame2D &frame2d, const MatrixBarcodeFormatFilter &formatFilter = MatrixBarcodeFormatFilter::all()) const

Detect and decode matrix (2D) barcodes based on the result of a 2D capture.

By default this function will attempt to detect and decode all supported barcode formats. Users can achieve increased detection speed and reliability by using the formatFilter argument to specify a subset of formats, for example MatrixBarcodeFormat::qrcode | MatrixBarcodeFormat::dataMatrix.

Parameters:

• frame2d – A Frame2D instance from a 2D or 2D+3D capture

• formatFilter – A filter defining which barcode formats to look for.

Returns:

A sequence of MatrixBarcodeDecodingResult (one per successfully decoded barcode)

std::vector<MatrixBarcodeDecodingResult> readMatrixCodes(const Sensor::Frame2D &frame2d, const MatrixBarcodeFormatFilter &formatFilter = MatrixBarcodeFormatFilter::all()) const

Detect and decode matrix (2D) barcodes based on the result of a 2D capture.

By default this function will attempt to detect and decode all supported barcode formats. Users can achieve increased detection speed and reliability by using the formatFilter argument to specify a subset of formats, for example MatrixBarcodeFormat::qrcode | MatrixBarcodeFormat::dataMatrix.

Parameters:

• frame2d – A Sensor::Frame2D instance from a sensor 2D capture

• formatFilter – A filter defining which barcode formats to look for.

Returns:

A sequence of MatrixBarcodeDecodingResult (one per successfully decoded barcode)

std::vector<MatrixBarcodeDecodingResult> readMatrixCodes(const DeviceArrayView<ColorRGBAf> &imageDeviceArray, const Sensor::FrameMetadata &metadata, const MatrixBarcodeFormatFilter &formatFilter = MatrixBarcodeFormatFilter::all()) const

Detect and decode matrix (2D) barcodes based on the result of a 2D capture.

By default this function will attempt to detect and decode all supported barcode formats. Users can achieve increased detection speed and reliability by using the formatFilter argument to specify a subset of formats, for example MatrixBarcodeFormat::qrcode | MatrixBarcodeFormat::dataMatrix.

Parameters:

• imageDeviceArray – A DeviceArray coming from a 2D frame

• metadata – Metadata about the DeviceArray

• formatFilter – A filter defining which barcode formats to look for.

Returns:

A sequence of MatrixBarcodeDecodingResult (one per successfully decoded barcode)

std::string toString() const

Get string representation of the object.

Returns:

BarcodeDetector as a string

C#

See Zivid::NET::Experimental::Toolbox::BarcodeDetector in the C# API reference.

Python

See zivid-python.

LinearBarcodeDetectionResult

Result of a linear barcode detection. Contains located barcode regions that can be passed to decode() to retrieve the decoded data.

C++

class LinearBarcodeDetectionResult

Information about an image region that is likely (but not guaranteed) to be a linear (1D) barcode.

Public Functions

PointXY centerPosition() const

Get the location of the region in the 2D image.

Returns:

2D coordinates as a PointXY

BoundingBox boundingBox() const

Get the bounding box of the region in the 2D image.

Returns:

Bounding box as a BoundingBox

std::vector<PointXY> contour() const

Get the contour outlining the detected region in the 2D image.

Returns:

The contour as a sequence of 2D coordinates (PointXY)

std::string toString() const

Get string representation of the object.

Returns:

LinearBarcodeDetectionResult as a string

C#

See the C# API reference.

Python

See zivid-python.

LinearBarcodeDecodingResult

Decoded linear barcode — symbology, value, and position.

C++

class LinearBarcodeDecodingResult

Information about a decoded linear (1D) barcode.

Public Functions

std::string code() const

Get the code encoded in the barcode.

Returns:

Code as a string

LinearBarcodeFormat codeFormat() const

Get the format of the code.

Returns:

Format as a LinearBarcodeFormat enum value

PointXY centerPosition() const

Get the location of the barcode in the 2D image.

Returns:

2D coordinates as a PointXY

BoundingBox boundingBox() const

Get the bounding box of the barcode in the 2D image.

Returns:

Bounding box as a BoundingBox

std::string toString() const

Get string representation of the object.

Returns:

LinearBarcodeDecodingResult as a string

C#

See the C# API reference.

Python

See zivid-python.

MatrixBarcodeDecodingResult

Decoded 2D (matrix) barcode — symbology, value, and corner points.

C++

class MatrixBarcodeDecodingResult

Information about a detected matrix (2D) barcode.

Public Functions

std::string code() const

Get the code encoded in the barcode.

Returns:

Code as a string

MatrixBarcodeFormat codeFormat() const

Get the format of the code.

Returns:

Format as a MatrixBarcodeFormat enum value

PointXY centerPosition() const

Get the location of the barcode in the 2D image.

Returns:

2D coordinates as a PointXY

BoundingBox boundingBox() const

Get the bounding box of the barcode in the 2D image.

Returns:

Bounding box as a BoundingBox

std::string toString() const

Get string representation of the object.

Returns:

MatrixBarcodeDecodingResult as a string

C#

See the C# API reference.

Python

See zivid-python.

See also

• Barcode Detection

• Applications Basic

• SDK Changelog