Typical Usage Scenarios And Example Applications

Interesting Topics To Start Integrating Impact Acquire

Since Impact Acquire SDK and the Balluff devices provide a huge variety of functionality, it will be helpful to use this page as a starting point which leads through a number of common image acquisition and configuration tasks.

The summarized code samples will show the most common cases and can be used as a base for an own image acquisition using the Impact Acquire SDK.

Note

Apart from those usage scenarios a large number of use cases can be found in the corresponding device manuals. Usually they are located at the 'Use Case'-chapter of each device's manual which is

• either part of the installed package or
• online from Balluff GmbH
  • for BVS CA-GT (mvBlueCOUGAR-XT)
  • for BVS CA-BN (mvBlueNAOS)
  • for mvBlueCOUGAR-X/XD
  • for mvBlueFOX3
  • for mvBlueFOX
  • for BVS CA-UB
  • for mvVirtualDevice

Image Acquisition

Single Frame Acquisition

The most simple image acquisition task is acquiring just a single frame. Depending on the following task the complexity might increase.

The following samples will explain how single frame acquisitions will be realized in the most efficient way.

• SingleCapture.cpp
• SingleCaptureStorage.cpp

Using Multiple Devices At The Same Time

Single frame acquisitions will be possible by using not just only on device, it is possible by using multiple device which acquire a single frame each.

Such purpose is explained by the next samples.

• SingleCaptureMasterSlave.cpp
• ContinuousCaptureAllDevices.cpp
  • ContinuousCaptureAllDevices.linux.cpp (only recommended when working with a non C++11 compliant compiler on Linux!)
  • ContinuousCaptureAllDevices.win32.cpp (only recommended when working with a non C++11 compliant compiler on Windows!)

Continuous Image Acquisition

A very common task is to acquire various images continuously to use them e.g. for video streams, continuous analysis or displaying purpose. This purpose is a bit more complex than acquiring just a single frame, but usually not that complex.

Note

It will be very useful to get familiar with the image capturing process of Impact Acquire to work create continuous image acquisitions. All important details are explained at the chapter The Capture Process.

The following samples will illustrate how simple continuous acquisitions can be realized.

• ContinuousCapture.cpp (shows the usage of the RequestProvider helper class which is meant to allow very easy, continuous image acquisition for standard applications. Needs a C++11 compliant compiler!)
  • ContinuousCapture.linux.cpp (only recommended when working with a non C++11 compliant compiler on Linux!)
  • ContinuousCapture.win32.cpp (only recommended when working with a non C++11 compliant compiler on Windows!)
• ContinuousCaptureAllFormats.cpp (Needs a C++11 compliant compiler!)
  • ContinuousCaptureAllFormats.win32.cpp (only recommended when working with a non C++11 compliant compiler on Windows!)
• ContinuousCaptureAllDevices.cpp
• ContinuousCaptureFFmpeg.cpp (shows how to combine Impact Acquire with the FFmpeg project(https://ffmpeg.org/) to store compressed video streams)

Displaying Acquired Images And Capturing Data Into User Controlled Memory

In some cases simple continuous acquisitions are not sufficient since the image data should be processed or stored within the application. The complexity of such an application depends on the task.

• ContinuousCaptureToAVIFile.cpp
• ContinuousCaptureDirectX.cpp
• ContinuousCaptureMultiPart.cpp
• ContinuousCaptureOnlyProcessLatest.cpp
• CaptureToUserMemory.cpp
• SequenceCapture.cpp – SequenceCapture.win32.cpp (only recommended when working with a non C++11 compliant compiler on Windows!)

Continuously captured images to video file

To capture images and write each image to an AVI stream the following examples will be useful.

• ContinuousCaptureToAVIFile.cpp
• SequenceCapture.cpp

Changing Device Settings

To modify device settings e.g. exposure time or gain, there are different approaches depending on interface layout supported by the used device. The two different interface layouts are 'GenICam' and 'Device Specific'. To get an idea which interface is supported by which device, please refer to the chapter Which Interface Is Supported By Which Device?.

Note

The differences between both interface layouts are explained at the page 'GenICam' vs. 'DeviceSpecific' Interface Layout.

Changing Device Settings For GenICam-Devices

Since most Balluff/MATRIX VISION devices support the GenICam™ interface layout, the following examples will be helpful. They will explain how device properties are changed in a convenient and safe way.

• Properties.cpp
• GenICamCommonSettingsUsage.cpp
• GenICamInterfaceLayout.cpp

Changing Specific Device Settings For GenICam-Devices

Some specific settings offered by the GenICam™ interface might be necessary to be explained regarding their usage. The following samples will help to understand how the more special settings are used.

• GenICamI2cUsage.cpp
• GenICamSequencerParameterChangeAtRuntime.cpp
• GenICamSequencerUsage.cpp
• GenICamSequencerUsageWithPaths.cpp
• GenICamSmartFrameRecallUsage.cpp

Changing Device Settings

For devices supporting the Device Specific interface layout (e.g. BVS CA-UB, mvBlueFOX and Framegrabbers), the following samples will show possible approaches.

• DigitalIOs.cpp
• Properties.cpp

Changing Device Settings In A Generic Way

Note

More details on configuring devices in a generic way can be found at Runtime Feature Extraction

• GenericInterfaceLayout.cpp

Special Device Functionalities

Beginning with the release of 2.49.0 of Impact Acquire firmware updates for all devices still active can be applied in a rather convenient way by using a high level firmware update API. This API is available for every supported programming language. For object orientated languages a FirmwareUpdater class will be part of the SDK and code snippets can be found in the corresponding documentation of the class.

• FirmwareUpdate.cpp

BVS CA-BN, mvBlueCOUGAR-X, mvBlueFOX3

mvBlockscan Mode

Beginning with release 2.35 of the GenICam™ device firmware a growing number of device models now support the mvBlockscan mode allowing to transmit multiple images as one thus using a single transfer block for transporting several consecutive frames from the same AOI reducing the overall overhead needed for transporting and reporting a frame thus in total reducing the CPU load on the host for certain scenarios.

The properties to control this feature are

• mvIMPACT::acquire::GenICam::DeviceControl::deviceScanType
• mvIMPACT::acquire::GenICam::ImageFormatControl::mvBlockscanLinesPerBlock
• mvIMPACT::acquire::GenICam::ImageFormatControl::mvBlockscanBlockCount

The maximum number of frames that can be combined that way by the device might be limited for various reasons but depending on the use-case the performance benefit can be significant.

When the device is not capable of handling the full transfer on its own the following example application shows one way of efficiently dealing with this use-case in an application depending on the capabilities of the device:

• CaptureToMegaBuffer.cpp

BVS CA-UB and mvBlueFOX

PowerMode

BVS CA-UB and mvBlueFOX2 USB devices allow to put themselves into a mode where less power is consumed. This can be used when no image acquisition is currently active and helps to reduce the overall power consumption of the system in idle mode.

The property mvIMPACT::acquire::SystemBlueFOX::powerMode can be used to configure this behaviour.

mvVirtualDevice

Apart from allowing to generate arbitrary test images in every pixel format supported by Impact Acquire the mvVirtualDevice package can also be used to capture images from a defined folder on the hard disk drive. This can be extremely useful when prototyping without real hardware or to feed defined test images into an algorithm in way the capture engine seems to provide these images. To do that just a couple of properties must be set appropriately:

• mvIMPACT::acquire::CameraSettingsVirtualDevice::testMode must be set to mvIMPACT::acquire::TVirtualDeviceTestMode::vdtmImageDirectory
• mvIMPACT::acquire::CameraSettingsVirtualDevice::imageDirectory must be set to the directory to capture from
• mvIMPACT::acquire::CameraSettingsVirtualDevice::imageType must be configured for the correct image formats (e.g. *.bmp and *.png). For the file import Impact Acquire makes use of the FreeImage library!
• mvIMPACT::acquire::CameraSettingsVirtualDevice::aoiMode can be used to get equal sized images independent of the source image sizes OR to capture each image with the size it is stored on disc

The images are captured from the directory specified by the application in a Round-Robin fashion so once the last image from the folder has been captured the next image will be the first again. Whenever for some reason an image cannot be imported from the hard disk an artificial test image will be generated instead.

Time Stamp Device Functionalities

mvBlueCOUGAR-X, mvBlueFOX3

In modern computer networks and application solutions, time synchronization is critical because every aspect of managing, scheduling, and debugging a network or system involves determining when events happen. Time also provides the only frame of reference between all devices on the network or in a closed system. For this reason, Balluff/MATRIX VISION devices offer various solutions for synchronizing clocks using closed loop and open loop controllers

The following sample will show the given synchronization modes and how they can be realized:

• TimestampFeatures.cpp

BVS 3D-RV0 and BVS 3D-RV1

BVS 3D-RV0 and BVS 3D-RV1 devices offer various functionalities which can be used to generate 3D information.

The following examples might help to get an understanding of the possibilities offered by these devices:

• ContinuousCapture_BVS-3D-RV0.cpp
• ContinuousCapture_BVS-3D-RV1.cpp

General SDK Functionalities

Callbacks

To get an idea how callbacks are implemented, the following sample will be helpful:

• Callback.cpp
• GenICamCallbackOnEvent.cpp

Parsing Data From A GenDC Capable Source

Beginning with the release of 2.50 of Impact Acquire the GenICam™ GenDC format developed by the GenICam working group is supported. This format was triggered by the need to allow various vendors to transfer specific payload without the need to standardize a new payload format all the time.

Note

More details GenDC can be found at GenICam™ GenDC Format

• ContinuousCaptureGenDC.cpp

Setting Up The Framework For Third Party GenTL Producer Usage

How to set up the way Impact Acquire connects to and enumerates third party GenTL producers is described here: Setting Up The Framework For Third Party GenTL Producer Usage

GUI Applications

All GUI-samples are delivered as part of the installation package and are installed during the installation process except for wxWidgets based applications (e.g. ImpactControlCenter and DeviceConfigure (both C++)) which have to be selected explicitly to be installed during the installation process on Windows.

DirectX

• ContinuousCaptureDirectX.cpp

Qt

• ContinuousCaptureQt.cpp

wxWidgets

• ImpactControlCenter