Impact Acquire SDK Python
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

Image Acquisition

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.

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.

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.

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

  • DeviceScanType of the GenICam/DeviceControl category
  • mvBlockscanLinesPerBlock of the GenICam/ImageFormatControl category
  • mvBlockscanBlockCount of the GenICam/ImageFormatControl category

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.

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.

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:

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.

General SDK Functionalities

Callbacks

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

This API will allow you to register a callback that gets executed whenever a certain feature of interest did change in any way (e.g. its visibility, value, etc.). To do that you first need to derive from the class mvIMPACT.acquire.ComponentCallback like shown in the following example:

from mvIMPACT import acquire
class MyCallback(acquire.ComponentCallback):
def __init__(self, pUserData=None):
acquire.ComponentCallback.__init__(self)
self.pUserData_ = pUserData
self.executeHitCount_ = 0
def execute(self, c, pUserData):
try:
# here you would actually do what is important for you! Please IGNORE the 'pUserData' parameter
# coming into this function! Use the one you did provide in you constructor call instead for
# whatever is necessary (e.g. cast it to an instance of a class you might want to call). Counting
# the number of times this function got called is a silly example only! Remove this in a real world
# application!
self.executeHitCount_ += 1
except Exception as e:
print("An exception has been raised by code that is not supposed to raise one: '" + str(e) + "'! If this is NOT handled here the application will crash as this Python exception instance will be returned back into the native code that fired the callback!")
mvIMPACT
Definition __init__.py:1

The next thing that needs to be done now is to create an instance of that callback object somewhere appropriate in the code:

cb = MyCallback(self) # Here we pass the instance of the class we are currently in to the callback. You may have different ideas!

Now the only thing left to do is to register a feature that you want to get callbacks on changes for:

cb.registerComponent(pDev.state)

Now for an open GEV/U3V device or a BVS CA-UB/mvBlueFOX2 device whenever you unplug the device or plug it back in afterwards you should get a callback!

Using Third Party GenICam™ GenTL Producers

How to set up the way Impact Acquire connects to and enumerates third party GenTL producers is described here: Using Third Party GenICam™ GenTL Producers

Reading/Writing Binary Data To A Property

Some string properties (mvIMPACT.acquire.PropertyS ) instances can store binary data. In order to e.g. allow serializing of all data to an XML file binary data internally is stored encoded in Base64. So when using the standard read/write functions expecting a string parameter it is the responsibility of the application to encode the binary data into a Base64 encoded string before writing the value and decoding the string into a byte array again when reading.

# ... more code
pseudoBinaryProp = getAccessToPropertyFromSomewhere()
# define some arbitrary binary data. In real life this of course will be something meaningful!
pBuf = b'\x00\xFF\x80\x33' # note the prefix
# write the data to the property
pseudoBinaryProp.writeBinary(pBuf)
# read back the data from the property again
pReadBack = pseudoBinaryProp.readBinary()
# in a unit test case we could now validate if the property actually stores the right amount of data
self.assertEqual(pReadBack, pBuf)
# You can also use string buffer instead of a binary one for binary data exchange, BUT be aware that Python uses UTF-8
# so this will result in UTF-8 encoded data reaching the actual \product_name libraries. This is fine, if
# the data is only used to read it back into the Python application later, but will lead to unwanted side effects
# when data passed like this is used by the lower layers (e.g. to perform a firmware update or to send data to
# an I2C bus) for obvious reasons!
pBuf = '\x00\xFF\x80\x33' # this will reach the Impact Acquire runtime as 0x00 0xC3 0xBF 0xC2 0x80 0x33!!!
# 0xFF becomes 0xC3 0xBF due to the rules UTF-8 is built:
# U+0080 bis U+07FF is encoded as 2 byte UTF-8! Codepoint therefore is:
# 110xxxxx 10xxxxxx
# 11111111 (0xFF)
# 11 111111 (fill bits into free spaces)
# 11000011 10111111 (0xC3 0xBF)
# read/write byte buffer from/to default index(0)
# write the data to the property
pseudoBinaryProp.writeBinary(pBuf)
# ... even more code

Deriving From mvIMPACT.acquire.RequestFactory And mvIMPACT.acquire.Request

Deriving from mvIMPACT.acquire.Request can be useful when a certain device driver or device offers a custom feature that is returned as part of the request object that can not be accessed using the mvIMPACT.acquire.Request class offered by this interface.

In C++ deriving from the class mvIMPACT.acquire.RequestFactory allows to customize the type of mvIMPACT.acquire.Request objects that will be created by the class mvIMPACT.acquire.FunctionInterface. The same feature is available in Python as well however compared to the C++ implementation there is one important difference. The following example code will explain how to work with the mvIMPACT.acquire.RequestFactory:

Deriving From mvIMPACT.acquire.Request

# Example for a derived request object. It doesn't introduce new functionality
# but rebinds an existing property. Custom properties could bound in a similar
# way.
class MyRequest(acquire.Request):
def __init__(self, *args):
acquire.Request.__init__(self, *args)
self.myRequestResult = acquire.PropertyIRequestResult()
locator = acquire.DeviceComponentLocator(self.getComponentLocator().hObj())
locator.bindComponent(self.myRequestResult, "Result" )

Deriving From mvIMPACT.acquire.RequestFactory

class MyRequestFactory(acquire.RequestFactory):
def __init__(self):
acquire.RequestFactory.__init__(self)
self.createRequestHitCount_ = 0
self.__instances = []
def createRequest(self, pDev, requestNr):
try:
self.createRequestHitCount_ += 1
instance = MyRequest(pDev, requestNr)
# We MUST keep a reference to this request object here as otherwise the instance gets cleaned up
# by the garbage collector when leaving this function. We therefore add an artificial reference
# by adding this MyRequest instance to the array which is kind of silly but in Java we have a
# very similar effect (see corresponding unit test).
#
# Maybe there is a better way to do this! Suggestions welcome!
self.__instances.append(instance)
return instance
except Exception as e:
print("An exception has been raised by code that is not supposed to raise one: '" + str(e) + "'! If this is NOT handled here the application will crash as this Python exception instance will be returned back into the native code that fired the callback!")
return None

Using The Derived Classes

Now the request factory must be passed to the function interface:

def fn(pDev):
# ... some code ...
mrf = MyRequestFactory()
fi = acquire.FunctionInterface(pDev, mrf)
#... more additional code
# assuming we got back a request from the framework at this point:
pRequest = getRequestFromDriver() # or simply: 'fi.getRequest(0)'...
if pRequest.isOK:
# in a unit test you now could assert:
# self.assertTrue( type(pRequest) is MyRequest, "Requests returned from the function interface should be of type 'MyRequest' as this is the whole point of this test! These are derived from 'Request'. We however got a '{0}' instance here.".format(type(pRequest)) );
print("{0}: {1}".format(pRequest.myRequestResult.name(), pRequest.myRequestResult.readS()))
# ... probably even more additional code
}