Get Started With MatrixScan#

With MatrixScan, you can highlight and interact multiple barcodes within the same frame and build AR experiences. MatrixScan use cases are implemented through functionality provided by BarcodeTracking.

In this guide you will learn step by step how to add BarcodeTracking to your application. Roughly, the steps are:

Prerequisites#

Before starting with adding a capture mode, make sure that you have a valid Scandit Data Capture SDK license key and that you added the necessary dependencies. If you have not done that yet, check out this guide.

Note

You can retrieve your Scandit Data Capture SDK license key, by signing in to your account at ssl.scandit.com.

Create the Data Capture Context#

The first step to add barcode capture capabilities to your application is to create a new data capture context. The context expects a valid Scandit Data Capture SDK license key during construction.

DataCaptureContext dataCaptureContext = DataCaptureContext.forLicenseKey("-- ENTER YOUR SCANDIT LICENSE KEY HERE --");

Configure the Barcode Tracking Mode#

The main entry point for the Barcode Tracking Mode is the BarcodeTracking object. It is configured through BarcodeTrackingSettings and allows to register one or more listeners that will get informed whenever a new frame has been processed.

Most of the times, you will not need to implement a BarcodeTrackingListener, instead you will add a BarcodeTrackingBasicOverlay and implement a BarcodeTrackingBasicOverlayListener.

For this tutorial, we will setup Barcode Tracking for tracking QR codes.

BarcodeTrackingSettings settings = new BarcodeTrackingSettings();
settings.enableSymbology(Symbology.QR, true);

Note

If your scenario is similar to one described in Barcode Tracking Scenarios, then you should consider using BarcodeTrackingSettings.forScenario() for better results.

Next, create a BarcodeTracking instance with the data capture context and the settings initialized in the previous steps:

BarcodeTracking barcodeTracking = BarcodeTracking.forDataCaptureContext(dataCaptureContext, settings);

Use the Built-in Camera#

The data capture context supports using different frame sources to perform recognition on. Most applications will use the built-in camera of the device, e.g. the world-facing camera of a device. The remainder of this tutorial will assume that you use the built-in camera.

When using the built-in camera there are recommended settings for each capture mode. These should be used to achieve the best performance and user experience for the respective mode. The following couple of lines show how to get the recommended settings and create the camera from it:

CameraSettings cameraSettings = BarcodeTracking.createRecommendedCameraSettings();

// Depending on the use case further camera settings adjustments can be made here.

Camera camera = Camera.getDefaultCamera();
if (camera != null) {
  camera.applySettings(cameraSettings, null);
}

Because the frame source is configurable, the data capture context must be told which frame source to use. This is done with a call to DataCaptureContext.setFrameSource():

dataCaptureContext.setFrameSource(camera);

The camera is off by default and must be turned on. This is done by calling FrameSource.switchToDesiredState() with a value of FrameSourceState.ON:

if (camera != null) {
  camera.switchToDesiredState(FrameSourceState.ON);
}

Note

On Android the Scandit Data Capture SDK is not lifecycle aware which means it is not able to turn off the camera when the app goes in the background etc. which has to be done as otherwise the camera is locked for other apps. This responsibility to do this is left to the implementer. Make sure that you always turn the camera off in the activity’s onPause lifecycle method. Often this means that you want to (re)start it in onResume. You can see a way of doing this in all of the samples.

There is a separate guide for more advanced camera functionality.

Use a Capture View to Visualize the Scan Process#

When using the built-in camera as frame source, you will typically want to display the camera preview on the screen together with UI elements that guide the user through the capturing process. To do that, add a DataCaptureView to your view hierarchy:

DataCaptureView dataCaptureView = DataCaptureView.newInstance(this, dataCaptureContext);
setContentView(dataCaptureView);

To visualize the results of Barcode Tracking, first you need to add the following overlay:

BarcodeTrackingBasicOverlay overlay = BarcodeTrackingBasicOverlay.newInstance(barcodeTracking, dataCaptureView);

Once the overlay has been added, you should implement the BarcodeTrackingBasicOverlayListener interface. The method BarcodeTrackingBasicOverlayListener.brushForTrackedBarcode() is invoked every time a new tracked barcode appears and it can be used to set a brush that will be used to highlight that specific barcode in the overlay.

@Override
public void brushForTrackedBarcode(@NonNull BarcodeTrackingBasicOverlay overlay,
                                  @NonNull TrackedBarcode trackedBarcode) {
    // Return a custom Brush based on the tracked barcode.
}

If you would like to make the highlights tappable, you need to implement the BarcodeTrackingBasicOverlayListener.onTrackedBarcodeTapped() method.

@Override
public void onTap(@NonNull BarcodeTrackingBasicOverlay overlay,
                  @NonNull TrackedBarcode trackedBarcode) {
    // A tracked barcode was tapped.
}

Get Barcode Tracking Feedback#

Barcode Tracking, unlike Barcode Capture, doesn’t emit feedback (sound or vibration) when a new barcode is recognized. However, you may implement a BarcodeTrackingListener to provide a similar experience. Below, we use the default Feedback, but you may configure it with your own sound or vibration if you want.

First, let’s create a feedback. We release it after it is no longer used, to avoid resources being unnecessarily held.

@Override
protected void onResume() {
    super.onResume();

    feedback = Feedback.defaultFeedback()
}

@Override
protected void onPause() {
    super.onPause();

    feedback.release();
}

Next, use this feedback in a BarcodeTrackingListener:

public class FeedbackListener implements BarcodeTrackingListener {
    @Override
    public void onObservationStarted(@NotNull BarcodeTracking barcodeTracking) {
        // Called when Barcode Tracking is started.
        // We don't use this callback in this guide.
    }

    @Override
    public void onObservationStopped(@NotNull BarcodeTracking barcodeTracking) {
        // Called when Barcode Tracking is stopped.
        // We don't use this callback in this guide.
    }

    @Override
    public void onSessionUpdated(
            @NotNull BarcodeTracking mode,
            @NotNull BarcodeTrackingSession session,
            @NotNull FrameData data
    ) {
        if (!session.getAddedTrackedBarcodes().isEmpty()) {
            feedback.emit();
        }
    }
}

BarcodeTrackingListener.onSessionUpdated() is invoked for every processed frame. The session parameter contains information about the currently tracked barcodes, in particular, the newly recognized ones. We check if there are any and if so, we emit the feedback.

As the last step, register the listener responsible for emitting the feedback with the BarcodeTracking instance.

barcodeTracking.addListener(feedbackListener);

Limitations#

MatrixScan does not support the following symbologies:

  • DotCode

  • MaxiCode

  • All postal codes (KIX, RM4SCC)

What’s next?

To dive further into the Scandit Data Capture SDK we recommend the following articles: