Changing Device Settings

General

The Impact Acquire framework uses a property based concept to access parameters of internal structures or to configure the drivers behaviour. Features offered by the device will simply be added to other properties already present in the drivers feature tree. The following list displays the general layout of features in the GenICam interface layout (see 'GenICam' vs. 'DeviceSpecific' Interface Layout for details on different interface layouts):

|
|- ImagingSubsystem
|    |
|    |- Setting
|         |
|         |- Setting Base // In GenICam interface layout only one capture setting is supported to understand how to use several settings have a look at the example section or the 'Image acquisition -> Working with settings' chapter
|         |    |
|         |    |- Camera
|         |         |
|         |         |- GenICam // features extracted from the devices XML file
|         |         |     |
|         |         |     |- ImageFormatControl (see SFNC)
|         |         |     |- AcquisitionAndTriggerControl (see SFNC)
|         |         |     |- etc. // everything else, that is not part of the SFNC. This will be created 'as is', thus with the structure defined in the description file of the device
|         |         |
|         |         |- GenTL // features extracted from the GenICam GenTL producers XML files
|         |               |
|         |               |- Device
|         |               |- DataStream
|         |               |- etc.
|
|- System
|    |
|    |- CodeGeneration
|    |- etc. // various other features the influence the overall behaviour of the driver
|
|- Info // various features providing information about the device, driver versions etc.
|
|
other features

For most of the features offered by a device there will be ready to use wrapper objects that come with the SDK so there will be no need to look up the feature at runtime. Depending on the selected interface layout either objects belonging to the DeviceSpecific interface or to the GenICam interface can be used. To see which SDK objects belong to which interface layout all the objects have been put into groups in the Modules section of this documentation. To find out which device supports which interface layout please refer to Which Interface Is Supported By Which Device? .

For the GenICam interface layout there will be convenient access objects fro ALL the feature defined in the GenICam Standard Feature Naming Convention (SFNC) as well as ALL the custom features defined by Balluff. So to access e.g. SFNC compliant features belonging the AcquisitionControl category this object can be used:

mvIMPACT::acquire::GenICam::AcquisitionControl. In order to be able to use the GenICam specific wrapper classes in an application also needs to include an additional header file:

#include <mvIMPACT_CPP/mvIMPACT_acquire_GenICam.h>

The exposure time then can be modified like this:

// Set property exposureTime using GenICam
mvIMPACT::acquire::GenICam::AcquisitionControl ac( pDev /* this device pointer can be obtained from the mvIMPACT::acquire::DeviceManager class */);
cout << "exposureTime (current): " << ac.exposureTime.read() << endl;
ac.exposureTime.write( 10000 );
cout << "exposureTime (new): " << ac.exposureTime.read() << endl;

Further information about the usage of the GenICam to change settings can be found a the sample: GenICamCommonSettingsUsage.cpp

In addition to that the mvGenTL_Acquire driver package contains an embedded wrapper code generator that can be used to create a custom header file for a device or device family not known at compile time. The usage of this code generator is explained in the use case GenICam To Impact Acquire Code Generator. It can significantly simplify the development process if all devices that shall be used by an application are known at the time of compiling the application.

All objects which grant access to device driver interface properties will require the pointer to the mvIMPACT::acquire::Device acquired from a mvIMPACT::acquire::DeviceManager object again.

Note

It is not necessary to call mvIMPACT::acquire::Device::open before creating objects requiring a pointer to a device object, but each constructor accepting such a pointer will need the device to be opened, so the first object constructed from a pointer to a closed mvIMPACT::acquire::Device object will try to initialize the device, which is why the first constructor call might take some time.

If for some reason the device can't be initialized, an exception might be thrown by any of those constructors.

Objects the user can create to modify or read mvIMPACT::acquire::Property values include (among other):

Common Objects Available For Every Device In Every Interface Layout

Name of the class	Description
mvIMPACT::acquire::DeviceManager	The main and most important of all objects. There always has to be at least one!
mvIMPACT::acquire::Device	An object representing an actual device. This is needed for creating almost every other object.
mvIMPACT::acquire::BasicDeviceSettings	A collection of basic settings. Please note that device specific classes derived from this class might offer more features
mvIMPACT::acquire::ImageProcessing	Various properties and methods to process the image before transmitted to the user
mvIMPACT::acquire::ImageDestination	Properties to control the destination format of the image
mvIMPACT::acquire::Info	General information about the device and the driver
mvIMPACT::acquire::Statistics	Provides access to statistical information like the current frames per second
mvIMPACT::acquire::SystemSettings	Provides access to settings controlling the overall behaviour of the driver

Device Specific Interface Layout

mvBlueCOUGAR

Name of the class	Description
mvIMPACT::acquire::CameraSettingsBlueCOUGAR	A collection of mvBlueCOUGAR specific settings
mvIMPACT::acquire::Connector	Properties to control the video input channel selection for frame grabber devices

mvBlueFOX

Name of the class	Description
mvIMPACT::acquire::CameraSettingsBlueFOX	A collection of mvBlueFOX specific settings
mvIMPACT::acquire::SettingsBlueFOX	A combination of the three classes mvIMPACT::acquire::SettingsBlueFOX, mvIMPACT::acquire::ImageDestination and mvIMPACT::acquire::ImageProcessing
mvIMPACT::acquire::InfoBlueFOX	Specific information about the mvBlueFOX and the driver
mvIMPACT::acquire::IOSubSystemBlueFOX	Provides access to the digital I/Os of the device and to real time control machines if available
mvIMPACT::acquire::SystemBlueFOX	Provides access to settings controlling the overall behaviour of the driver

Frame Grabbers

Name of the class	Description
mvIMPACT::acquire::CameraSettingsFrameGrabber	A collection of device specific settings
mvIMPACT::acquire::Connector	Properties to control the video input channel selection
mvIMPACT::acquire::SettingsFrameGrabber	A combination of the four classes mvIMPACT::acquire::CameraSettingsFrameGrabber, mvIMPACT::acquire::Connector, mvIMPACT::acquire::ImageDestination and mvIMPACT::acquire::ImageProcessing
mvIMPACT::acquire::IOSubSystemFrameGrabber	Provides access to the digital I/Os of the device and to real time control machines if available
mvIMPACT::acquire::OutputSignalGeneratorFrameGrabber	Provides access to high level functions to control the creation of complex signals on digital outputs

mvVirtualDevice

Name of the class	Description
mvIMPACT::acquire::CameraSettingsVirtualDevice	A collection of mvVirtualDevice specific settings

GenICam Interface Layout

Attention

Third party vendors might define their own custom features and these features availability (or presence) will be known at runtime only so there will be no convenient access objects as part of the shipped SDK. These features however can be accessed as well and how to do this is described later in this chapter or custom wrapper code can be generated using the code generator mentioned above. This however affects the configuration of a device only! The overall capture process described in this documentation applies to any device that can be operated using this device driver collection.

Please refer to the mvIMPACT::acquire::GenICam namespace for additional details and the sample GenICamCommonSettingsUsage.cpp how to programmatically work with the GenICam settings.

Runtime Feature Extraction

If an application shall be capable of dealing with every feature of every device and not all these devices are known at compile time, a code generator can not be used as it can only create code for devices which are accessible when creating the code. In this case, features must be extracted dynamically from the drivers feature tree. To do this SDK offers a set of functions that can be used to search and use features or to iterate over a tree of features. These objects and functions will be explained in the following sections.

Note

The GUI tool ImpactControlCenter can be of great help when writing code that shall extract certain features from the driver for using them inside an application. To find out how please have a look at the chapter "Changing the view of the property grid to assist writing code that shall locate driver features" in the technical manual of the device.

Most of the code presented in this section is also part of the SDK even though it is not part of the actual Impact Acquire driver framework. It has been added as a set of helper functions in a separate source file to the example applications. The source code can be found in the installation folder under apps/Common/exampleHelper_C*. An application can either add the full source file to its Makefile or extract and re-use source code as needed from here. All the example applications written in C do this as well.

Locating Properties

To bind a C++ property object to a certain feature offered by the device at runtime the C++ interface can be used in several ways. One possibility is to use a mvIMPACT::acquire::DeviceComponentLocator object. Let's assume an application wants to access a 64 bit integer property that is called Width and is located somewhere in the devices feature tree. In this case, we want to bind the property of the base setting. The code to bind the device feature to a C++ object would look more or less like this:

Device* pDev = getTheDevicePointerFromSomewhere();
PropertyI64 width;
// create a locator object that can iterate and find a driver feature
DeviceComponentLocator locator(pDev, dltSetting, "Base");
// find the feature and bind it to the property object
locator.bindComponent( width, "Width" );
// now the property is ready to use when available:
if( width.isValid() )
{
  width.write( width.read( plMaxValue ) / 2 ); // set the width to half of its maximum value
}
else
{
  // oops... The feature is not offered by this device
}

Locating And Using Methods

Method objects (ICommand nodes in GenICam) can be bound in exactly the same way however special care must be taken as their names contain information about the argument list of the method:

Device* pDev = getTheDevicePointerFromSomewhere();
Method triggerSoftware;
// create a locator object that can iterate and find a driver feature
DeviceComponentLocator locator(pDev, dltSetting, "Base");
// find the feature and bind it to the method object. Here it is crucial to notice that the exact name
// of a method object in mvIMPACT_Acquire is constructed from the actual feature name, the return type
// of the method and the arguments expected by the method (optional). More information about this topic
// can be found in the documentation of the 'Method' object.
locator.bindComponent( triggerSoftware, "TriggerSoftware@i" );
// '@i' indicates, that calling this function will return an integer
// (the result of the function call, which is either 0 or a negative value in case of an error)
// and takes no parameters
 
// now the method is ready to use when available:
if( triggerSoftware.isValid() )
{
  int result = triggerSoftware.call(); // execute the command
  if( result != DMR_NO_ERROR )
  {
    cout << "ERROR: " << ImpactAcquireException::getErrorCodeAsString( result ) << endl;
  }
}
else
{
  // oops... The feature is not offered by this device
}

Bind Features Of An Unknown Type

If the type is unclear for a particular feature some more complex code is needed:

Device* pDev = getTheDevicePointerFromSomewhere();
DeviceComponentLocator locator(pDev, dltSetting, "Base");
Component feature;
locator.bindComponent( feature, "Feature" );
// now the feature is ready to use when available:
if( feature.isValid() )
{
  cout << "Feature " << feature.name() << " is a " << feature.typeAsString() << endl;
  switch( feature.type() )
  {
    case ctPropString:
      PropertyS stringProp( feature );
      doStringPropAction( stringProp );
      break;
    case ctPropInt:
      PropertyI intProp( feature );
      doIntPropAction( intProp );
      break;
    case ctPropInt64:
      PropertyI64 longProp( feature );
      doLongPropAction( longProp );
      break;
    case ctPropFloat:
      PropertyF floatProp( feature );
      doFloatPropAction( floatProp );
      break;
    default:
      // don't handle this feature. This might be a method or a list or a property
      // of a type not dealt with in the 'case' statements from above
      break;
  }
}
else
{
  // oops... The feature is not offered by this device
}

Iterate Over A Tree Of Features

It's also possible to iterate over all the features offered by a device or a subtree of this. To see how this is done please have a look at the description of the class mvIMPACT::acquire::Component.

To access e.g. the device information related features, the locator instance must be initialised in a different way:

Device* pDev = getTheDevicePointerFromSomewhere();
DeviceComponentLocator locator(pDev, dltInfo, "DeviceInformation");
PropertyS deviceVersion;
locator.bindComponent( deviceVersion, "DeviceVersion" );
// now the property is ready to use when available:
if( deviceVersion.isValid() )
{
  cout << deviceVersion.name() << ": " << deviceVersion.read() << endl;
}
else
{
  // oops... The feature is not offered by this device
}