mvIMPACT Acquire SDK C++
GenICamCommonSettingsUsage.cpp

The GenICamCommonSettingsUsage example is intended as an example for people who do not have that much experience with the mvIMPACT Acquire SDK or did not use the classes which wrap the GenICam properties of a device yet. It shows the basic procedure of handling device settings, how a device is being configured with the most common settings and which steps are important to configure a device in an efficient way.

Program location
The source file GenICamCommonSettingsUsage.cpp can be found under:
%INSTALLDIR%\apps\GenICamCommonSettingsUsage\
Note
If you have installed the package without example applications, this file will not be available. On Windows the sample application can be installed or removed from the target system at any time by simply restarting the installation package.
Please be aware that this example utilizes the digital outputs of the device to show how they can be used in a real application. Please make sure not to run this application once there is some hardware connected to the digital outputs of the device.
GenICamCommonSettingsUsage example:
  1. Opens a MATRIX VISION device.
  2. Loads the default UserSet.
  3. Reads out some GenICam interface properties.
  4. Modifies some GenICam interface properties (Exposure Time, Analog Gain, Triggers, AOI, ...)
  5. Snaps some images using these properties and changing the analog gain every 100 frames (without display using Linux).
Console Output
--------------------------------------------!!! ATTENTION !!!--------------------------------------------
Please be aware that the digital outputs of the device might be enabled during the test. This might lead to unexpected behavior in case of devices which are connected to one of the digital outputs, so only proceed if you are sure that this will not cause any issue with connected hardware!!
---------------------------------------------------------------------------------------------------------

[0]: FF000026 (mvBlueFOX3-2024aC, Family: mvBlueFOX3, interface layout: GenICam, acquisition start/stop behaviour: User)

Please enter the number in front of the listed device followed by [ENTER] to open it: 0
Using device number 0.
Press [ENTER] to end the application
Initialising the device. This might take some time...

The device will be configured now!

Loading the device's default user set to avoid undefined settings!

Currently the exposure time is set to 20000 us. Changing to 10000 us

The sensor has a max resolution of about 1936x1216 pixels
The resolution will now be adjusted to the half of width and height. The resulting AOI will be: 968x608 pixels

To avoid some cabling work, we will use an internal timer for triggering in this sample!
The trigger frequency will be configured to half of the max frequency the sensor would be capable of in your setup.

Available Digital I/Os:
Line0 - Output - LineStatus: 0 - LineSource: mvExposureAndAcquisitionActive
Line1 - Output - LineStatus: 0 - LineSource: Off
Line2 - Output - LineStatus: 0 - LineSource: Off
Line3 - Output - LineStatus: 0 - LineSource: Off
Line4 - Input - LineStatus: 0 - LineSource: Off
Line5 - Input - LineStatus: 0 - LineSource: Off

Starting image acquisition

Info from FF000026: FramesPerSecond: 71.220532, ErrorCount: 0, CaptureTime_s: 0.123644, LineStatusAll: 0x0
Info from FF000026: FramesPerSecond: 71.210285, ErrorCount: 0, CaptureTime_s: 0.125834, LineStatusAll: 0x0
Info from FF000026: FramesPerSecond: 71.213282, ErrorCount: 0, CaptureTime_s: 0.123740, LineStatusAll: 0x0
Info from FF000026: FramesPerSecond: 71.219846, ErrorCount: 0, CaptureTime_s: 0.123399, LineStatusAll: 0x0
...
How it works
After getting the device from user input the sample tries to
  1. set the mvIMPACT::acquire::Device::interfaceLayout to mvIMPACT::acquire::dilGenICam
    pDev->interfaceLayout.write( dilGenICam );
    @ dilGenICam
    A GenICamâ„¢ like interface layout shall be used.
    Definition: mvDriverBaseEnums.h:2004
    and to
  2. open the device by calling
    pDev->open();
  3. The sample shows, how to work with SFNC (Standard Feature Naming Convention) compliant properties and their corresponding mvIMPACT Acquire classes without using the helper functions from exampleHelper.h.
Note
More details regarding the GenICam interface can be found here

At first the Default UserSet is loaded to make sure the device works on a specific set of settings before starting. This is a good idea once you want to bring the device to a defined state after using different settings e.g. once you used different software before.

The UserSet is selected using the UserSetSelector and using the writeS() function to assign the string value Default to the UserSetSelector property. Afterwards the UserSetLoad function is called by using it's call() function. More details regarding the usage of UserSets can be found here.

if( canRestoreFactoryDefault( pThreadParameter->pDev ) )
{
if( usc.userSetSelector.isValid() && usc.userSetSelector.isWriteable() && usc.userSetLoad.isValid() && usc.userSetLoad.isMeth() )
{
cout << "Loading the device's default user set to avoid undefined settings!\n" << endl;
// selecting the default user set which includes the factory settings of the device
usc.userSetSelector.writeS( "Default" );
// call the userSetLoad method to load the currently selected user set
usc.userSetLoad.call();
}
}
else
{
cout << "The device seems not to support the default user set!" << endl;
}

In the next step the exposure time is modified after it is verified that the property is supported by the device and it is currently writable.

Note
Usually it is a good idea to check if a property is available and if it is writable, since not every device supports every feature and not every feature is writable at every time.
const double dExposureTime = {10000.0};
// initialise the AcquisitionControl class to get access to the exposure time property
mvIMPACT::acquire::GenICam::AcquisitionControl acq( pThreadParameter->pDev );
// Make sure the exposure time property does exist and is currently not "read only"
if( acq.exposureTime.isValid() && acq.exposureTime.isWriteable() )
{
cout << "Currently the exposure time is set to " << acq.exposureTime.read() << " us. Changing to " << dExposureTime << " us" << endl;
cout << endl;
acq.exposureTime.write( dExposureTime );
}
Category for the acquisition and trigger control features.
Definition: mvIMPACT_acquire_GenICam.h:2075

Afterwards the AOI of the device is set to half of the sensor's size.

// initialising the ImageFormatControl class to get access to the sensor's AOI settings
mvIMPACT::acquire::GenICam::ImageFormatControl ifc( pThreadParameter->pDev );
// check if the sensors properties are available and modifying the AOI settings if width and height are valid properties
if( ifc.width.isValid() && ifc.height.isValid() )
{
cout << "The sensor has a max resolution of about " << ifc.width.getMaxValue() << "x" << ifc.height.getMaxValue() << " pixels" << endl;
cout << "The resolution will now be adjusted to the half of width and height. The resulting AOI will be: " << ifc.width.getMaxValue() / 2 << "x" << ifc.height.getMaxValue() / 2 << " pixels" << endl;
// the AOI settings are usually not writable once the senor is exposing images so make sure width and height are not read-only at the moment
if( !ifc.width.isWriteable() || !ifc.height.isWriteable() )
{
cout << "Width or Height are not writable at the moment." << endl;
}
else
{
ifc.width.write( ifc.width.getMaxValue() / 2 );
ifc.width.write( ifc.height.getMaxValue() / 2 );
}
}
Category for Image Format Control features.
Definition: mvIMPACT_acquire_GenICam.h:1104

To simulate an external trigger the timers of the device are used to generate trigger signals for the device. Since it is possible that not every device supports as much timers or TimerTriggerSource values, some more complex checks are necessary to make sure everything works as expected.

// Since the device's settings have a huge impact on the frame rate of the sensor, we need the device almost configured at this step. Otherwise the max frame rate would not be correct.
cout << endl;
cout << "To avoid some cabling work, we will use an internal timer for triggering in this sample!" << endl;
cout << "The trigger frequency will be configured to half of the max frequency the sensor would be capable of in your setup." << endl;
// Figuring out how many timers are available
vector<string> availableTimers;
if( ctc.timerSelector.isValid() )
{
ctc.timerSelector.getTranslationDictStrings( availableTimers );
}
if( ctc.timerSelector.isValid() && ctc.timerSelector.isWriteable() && ( availableTimers.size() >= 2 ) && acq.triggerSelector.isValid() && acq.mvResultingFrameRate.isValid() )
{
// Making sure that Timer2End as TimerTriggerSource does exist
ctc.timerSelector.writeS( "Timer1" );
vector<string> availableTriggerSources;
ctc.timerTriggerSource.getTranslationDictStrings( availableTriggerSources );
if( find( availableTriggerSources.begin(), availableTriggerSources.end(), "Timer2End" ) != availableTriggerSources.end() && acq.mvResultingFrameRate.isValid() )
{
const double dPeriod = 1000000. / ( acq.mvResultingFrameRate.read() / 2. );
if( dPeriod >= 300. )
{
// Defining the duration the trigger signal is "low". The timer selector has not to be changed since it has been set to Timer1 already
ctc.timerDuration.write( 1000. );
ctc.timerTriggerSource.writeS( "Timer2End" );
// Defining the duration the trigger signal is "high"
ctc.timerTriggerSource.writeS( "Timer1End" );
ctc.timerSelector.writeS( "Timer2" );
ctc.timerDuration.write( dPeriod - 1000. );
// Configuring the FrameStart trigger to use the start signal of Timer1 and enabling the trigger mode
acq.triggerSelector.writeS( "FrameStart" );
acq.triggerSource.writeS( "Timer1Start" );
acq.triggerMode.writeS( "On" );
}
}
else
{
cout << "This device does not support expected timer trigger sources! The device will work in free run mode instead!" << endl;
}
}
else
{
cout << "This device does not support timers! The device will work in free run mode instead!" << endl;
}
Category that contains the Counter and Timer control features.
Definition: mvIMPACT_acquire_GenICam.h:4199

The next step shows how the analog gain of the device's sensor can be modified. In this sample the value is set to its maximum.

mvIMPACT::acquire::GenICam::AnalogControl anc( pThreadParameter->pDev );
// Applying some gain to the signal provided by the device's sensor
if( anc.gain.isValid() && anc.gain.isWriteable() )
{
anc.gain.write( anc.gain.getMaxValue() );
}
Category that contains the Analog control features.
Definition: mvIMPACT_acquire_GenICam.h:2966

As the last configuration step the digital I/Os of the device are shown and summarized by iterating over all string elements within the property lineSelector which defines the input or output line of the digital I/Os. The first digital output is configured to use the mvExposureAndAcquisitionActive signal to make sure the digital output is set to 'high' once the device acquires images and exposes one.

Note
Since every line might be an input, output or bidirectional (depends on the hardware), the lineMode property for each line has to be read out.
mvIMPACT::acquire::GenICam::DigitalIOControl dio( pThreadParameter->pDev );
// Figuring out how many digital IOs are available
cout << "\nAvailable Digital IOs:" << endl;
vector<string> availableIOs;
dio.lineSelector.getTranslationDictStrings( availableIOs );
bool boConfiguredFirstOutput = false;
// iterating over the vector of digital IOs to read out the lineMode, lineStatus and lineSource properties
for( auto& line : availableIOs )
{
dio.lineSelector.writeS( line );
// using mvExposureAndAcquisitionActive as the lineSource for the first digital output found
if( !boConfiguredFirstOutput && dio.lineMode.readS() == "Output" )
{
dio.lineSource.writeS( "mvExposureAndAcquisitionActive" );
boConfiguredFirstOutput = true;
}
cout << line << " - " << ( dio.lineMode.isValid() ? dio.lineMode.readS() : string( "UNSUPPORTED" ) )
<< " - LineStatus: " << ( dio.lineStatus.isValid() ? dio.lineStatus.readS() : string( "UNSUPPORTED" ) )
<< " - LineSource: " << ( dio.lineSource.isValid() ? dio.lineSource.readS() : string( "UNSUPPORTED" ) )
<< endl;
}
Category that contains the digital input and output control features.
Definition: mvIMPACT_acquire_GenICam.h:3809

Finally, the sample shows a live display (mvIMPACT::acquire::display)(Windows only) and you can end the application with [ENTER].

Source code
#include <iostream>
#include <ios>
#include <memory>
#include <sstream>
#include <thread>
#include <apps/Common/exampleHelper.h>
#ifdef _WIN32
# define USE_DISPLAY
#else
# include <stdio.h>
# include <unistd.h>
#endif // #ifdef _WIN32
using namespace mvIMPACT::acquire;
using namespace std;
//=============================================================================
//================= Data type definitions =====================================
//=============================================================================
//-----------------------------------------------------------------------------
struct ThreadParameter
//-----------------------------------------------------------------------------
{
Device* pDev_;
unsigned int requestsCaptured_;
Statistics statistics_;
#ifdef USE_DISPLAY
ImageDisplayWindow displayWindow_;
#endif // #ifdef USE_DISPLAY
explicit ThreadParameter( Device* pDev, mvIMPACT::acquire::GenICam::DigitalIOControl& dio ) : pDev_( pDev ), requestsCaptured_( 0 ), statistics_( pDev ), dio_( dio )
#ifdef USE_DISPLAY
// initialise display window
// IMPORTANT: It's NOT safe to create multiple display windows in multiple threads!!!
, displayWindow_( "mvIMPACT_acquire sample, Device " + pDev_->serial.read() )
#endif // #ifdef USE_DISPLAY
{}
ThreadParameter( const ThreadParameter& src ) = delete;
ThreadParameter& operator=( const ThreadParameter& rhs ) = delete;
};
//=============================================================================
//================= implementation ============================================
//=============================================================================
//-----------------------------------------------------------------------------
static bool canRestoreFactoryDefault( Device* pDev )
//-----------------------------------------------------------------------------
{
GenICam::UserSetControl usc( pDev );
if( !usc.userSetSelector.isValid() || !usc.userSetLoad.isValid() )
{
return false;
}
vector<string> validUserSetSelectorStrings;
usc.userSetSelector.getTranslationDictStrings( validUserSetSelectorStrings );
return find( validUserSetSelectorStrings.begin(), validUserSetSelectorStrings.end(), "Default" ) != validUserSetSelectorStrings.end();
}
//-----------------------------------------------------------------------------
void myThreadCallback( shared_ptr<Request> pRequest, ThreadParameter& threadParameter )
//-----------------------------------------------------------------------------
{
++threadParameter.requestsCaptured_;
// display some statistical information every 100th image
if( threadParameter.requestsCaptured_ % 100 == 0 )
{
const Statistics& s = threadParameter.statistics_;
cout << "Info from " << threadParameter.pDev_->serial.read()
<< ": " << s.framesPerSecond.name() << ": " << s.framesPerSecond.readS()
<< ", " << s.errorCount.name() << ": " << s.errorCount.readS()
<< ", " << s.captureTime_s.name() << ": " << s.captureTime_s.readS()
<< ", LineStatusAll: " << threadParameter.dio_.lineStatusAll.read() << endl;
}
if( pRequest->isOK() )
{
#ifdef USE_DISPLAY
threadParameter.displayWindow_.GetImageDisplay().SetImage( pRequest );
threadParameter.displayWindow_.GetImageDisplay().Update();
#else
cout << "Image captured: " << pRequest->imageOffsetX.read() << "x" << pRequest->imageOffsetY.read() << "@" << pRequest->imageWidth.read() << "x" << pRequest->imageHeight.read() << endl;
#endif // #ifdef USE_DISPLAY
}
else
{
cout << "Error: " << pRequest->requestResult.readS() << endl;
}
}
//-----------------------------------------------------------------------------
// This function will allow to select devices that support the GenICam interface
// layout(these are devices, that claim to be compliant with the GenICam standard)
// and that are bound to drivers that support the user controlled start and stop
// of the internal acquisition engine. Other devices will not be listed for
// selection as the code of the example relies on these features in the code.
bool isDeviceSupportedBySample( const Device* const pDev )
//-----------------------------------------------------------------------------
{
if( !pDev->interfaceLayout.isValid() &&
!pDev->acquisitionStartStopBehaviour.isValid() )
{
return false;
}
vector<TDeviceInterfaceLayout> availableInterfaceLayouts;
pDev->interfaceLayout.getTranslationDictValues( availableInterfaceLayouts );
return find( availableInterfaceLayouts.begin(), availableInterfaceLayouts.end(), dilGenICam ) != availableInterfaceLayouts.end();
}
//-----------------------------------------------------------------------------
int main( void )
//-----------------------------------------------------------------------------
{
DeviceManager devMgr;
cout << "--------------------------------------------!!! ATTENTION !!!--------------------------------------------" << endl;
cout << "Please be aware that the digital outputs of the device might be enabled during the test." << endl
<< "This might lead to unexpected behavior in case of devices which are connected to one of the digital outputs," << endl
<< "so only proceed if you are sure that this will not cause any issue with connected hardware!!" << endl;
cout << "---------------------------------------------------------------------------------------------------------" << endl;
cout << "" << endl;
Device* pDev = getDeviceFromUserInput( devMgr, isDeviceSupportedBySample );
if( pDev == nullptr )
{
cout << "Unable to continue! Press [ENTER] to end the application" << endl;
cin.get();
return 1;
}
cout << "Initialising the device. This might take some time..." << endl;
cout << endl;
try
{
pDev->interfaceLayout.write( dilGenICam ); // This is also done 'silently' by the 'getDeviceFromUserInput' function but your application needs to do this as well so state this here clearly!
pDev->open();
}
catch( const ImpactAcquireException& e )
{
// this e.g. might happen if the same device is already opened in another process...
cout << "An error occurred while opening the device " << pDev->serial.read()
<< "(error code: " << e.getErrorCodeAsString() << ")." << endl
<< "Press [ENTER] to end the application..." << endl;
cin.get();
return 1;
}
// To make sure the device will be configured based on a defined state, the default user set will be loaded
cout << "The device will be configured now!\n" << endl;
// Make sure the default user set and the load method exist
// In general it is a good idea to verify if the GenICam class which should be used exists and is of the expected type
if( canRestoreFactoryDefault( pDev ) )
{
if( usc.userSetSelector.isValid() && usc.userSetSelector.isWriteable() && usc.userSetLoad.isValid() && usc.userSetLoad.isMeth() )
{
cout << "Loading the device's default user set to avoid undefined settings!\n" << endl;
// selecting the default user set which includes the factory settings of the device
usc.userSetSelector.writeS( "Default" );
// call the userSetLoad method to load the currently selected user set
usc.userSetLoad.call();
}
}
else
{
cout << "The device seems not to support the default user set!" << endl;
}
const double dExposureTime = {10000.};
// initialise the AcquisitionControl class to get access to the exposure time property
// Make sure the exposure time property does exist and is currently not "read only"
if( acq.exposureTime.isValid() && acq.exposureTime.isWriteable() )
{
cout << "Currently the exposure time is set to " << acq.exposureTime.read() << " us. Changing to " << dExposureTime << " us" << endl;
cout << endl;
acq.exposureTime.write( dExposureTime );
}
// initialising the ImageFormatControl class to get access to the sensor's AOI settings
// check if the sensors properties are available and modifying the AOI settings if width and height are valid properties
if( ifc.width.isValid() && ifc.height.isValid() )
{
cout << "The sensor has a max resolution of about " << ifc.width.getMaxValue() << "x" << ifc.height.getMaxValue() << " pixels" << endl;
cout << "The resolution will now be adjusted to the half of width and height. The resulting AOI will be: " << ifc.width.getMaxValue() / 2 << "x" << ifc.height.getMaxValue() / 2 << " pixels" << endl;
// the AOI settings are usually not writable once the senor is exposing images so make sure width and height are not read-only at the moment
if( !ifc.width.isWriteable() || !ifc.height.isWriteable() )
{
cout << "Width or Height are not writable at the moment." << endl;
}
else
{
ifc.width.write( ifc.width.getMaxValue() / 2 );
ifc.height.write( ifc.height.getMaxValue() / 2 );
}
}
// Since the device's settings have a huge impact on the frame rate of the sensor, we need the device almost configured at this step. Otherwise the max frame rate would not be correct.
cout << endl;
cout << "To avoid some cabling work, we will use an internal timer for triggering in this sample!" << endl;
cout << "The trigger frequency will be configured to half of the max frequency the sensor would be capable of in your setup." << endl;
// Figuring out how many timers are available
vector<string> availableTimers;
if( ctc.timerSelector.isValid() )
{
ctc.timerSelector.getTranslationDictStrings( availableTimers );
}
if( ctc.timerSelector.isValid() && ctc.timerSelector.isWriteable() && ( availableTimers.size() >= 2 ) && acq.triggerSelector.isValid() && acq.mvResultingFrameRate.isValid() )
{
// Making sure that Timer2End as TimerTriggerSource does exist
ctc.timerSelector.writeS( "Timer1" );
vector<string> availableTriggerSources;
ctc.timerTriggerSource.getTranslationDictStrings( availableTriggerSources );
if( find( availableTriggerSources.begin(), availableTriggerSources.end(), "Timer2End" ) != availableTriggerSources.end() && acq.mvResultingFrameRate.isValid() )
{
const double dPeriod = 1000000. / ( acq.mvResultingFrameRate.read() / 2. );
if( dPeriod >= 300. )
{
// Defining the duration the trigger signal is "low". The timer selector has not to be changed since it has been set to Timer1 already
ctc.timerDuration.write( 1000. );
ctc.timerTriggerSource.writeS( "Timer2End" );
// Defining the duration the trigger signal is "high"
ctc.timerTriggerSource.writeS( "Timer1End" );
ctc.timerSelector.writeS( "Timer2" );
ctc.timerDuration.write( dPeriod - 1000. );
// Configuring the FrameStart trigger to use the start signal of Timer1 and enabling the trigger mode
acq.triggerSelector.writeS( "FrameStart" );
acq.triggerSource.writeS( "Timer1Start" );
acq.triggerMode.writeS( "On" );
}
}
else
{
cout << "This device does not support expected timer trigger sources! The device will work in free run mode instead!" << endl;
}
}
else
{
cout << "This device does not support timers! The device will work in free run mode instead!" << endl;
}
// Applying some gain to the signal provided by the device's sensor
if( anc.gain.isValid() && anc.gain.isWriteable() )
{
anc.gain.write( anc.gain.getMaxValue() );
}
// Figuring out how many digital IOs are available
cout << "\nAvailable Digital IOs:" << endl;
vector<string> availableIOs;
dio.lineSelector.getTranslationDictStrings( availableIOs );
bool boConfiguredFirstOutput = false;
// iterating over the vector of digital IOs to read out the lineMode, lineStatus and lineSource properties
for( auto& line : availableIOs )
{
dio.lineSelector.writeS( line );
// using mvExposureAndAcquisitionActive as the lineSource for the first digital output found
if( !boConfiguredFirstOutput && dio.lineMode.readS() == "Output" )
{
dio.lineSource.writeS( "mvExposureAndAcquisitionActive" );
boConfiguredFirstOutput = true;
}
cout << line << " - " << ( dio.lineMode.isValid() ? dio.lineMode.readS() : string( "UNSUPPORTED" ) )
<< " - LineStatus: " << ( dio.lineStatus.isValid() ? dio.lineStatus.readS() : string( "UNSUPPORTED" ) )
<< " - LineSource: " << ( dio.lineSource.isValid() ? dio.lineSource.readS() : string( "UNSUPPORTED" ) )
<< endl;
}
// start the execution of the 'live' thread.
cout << "Press [ENTER] to end the application" << endl;
ThreadParameter threadParam( pDev, dio );
requestProvider.acquisitionStart( myThreadCallback, std::ref( threadParam ) );
cin.get();
requestProvider.acquisitionStop();
return 0;
}
Category that contains the User Set control features.
Definition: mvIMPACT_acquire_GenICam.h:9589
A helper class that can be used to implement a simple continuous acquisition from a device.
Definition: mvIMPACT_acquire_helper.h:428
This namespace contains classes and functions belonging to the GenICam specific part of the image acq...
Definition: mvIMPACT_acquire.h:22980
This namespace contains classes and functions that can be used to display images.
This namespace contains classes and functions belonging to the image acquisition module of this SDK.