mvIMPACT Acquire SDK GUI Applications
General Device Configuration

After the device has been initialized successfully in the "Grid" area of the GUI the available GenICam "interface layout" properties are displayed in a hierarchy tree.

Webcast
wxPropView - Configuring a device

Changing The Interface Layout To GenICam Or DeviceSpecific

The mvIMPACT Acquire interface internally uses the GenICam runtime libraries, so that it can be considered as an user application written with the GenICam interface. This behavior has several advantages:

  • The current version of the mvGenTL-Acquire driver is meant to work with every GigE Vision™ and every U3V (USB3 Vision™) compliant device.
  • Developers either can use the generic GenICam properties or the "mvIMPACT Acquire" properties.

You can change the property interfaceLayout with wxPropView to select the preferred interface.

  • When "GigE Vision" and GenICam compliant devices from several vendors shall be used in the same application it's recommended to use the "GenICam" interface layout only in order to keep the application code simple.
  • When several different MATRIX VISION devices (e.g. a frame grabber, a USB camera and a GigE Vision camera) shall be operated by the same application, it's recommended to use the device specific interface for the same reasons.
  • When an application shall be able to work with every MATRIX VISION device and every "GigE Vision" and GenICam compliant device both approaches make sense however a mixture between the 2 worlds can't be avoided.

To specify the InterfaceLayout for all devices globally, you can do this via the "Action -> Default Device Interface Layout" in the menu:

Global selection of the interface layout for all devices

If you want to specify the InterfaceLayout for the used device, you can do this via "Device Properties" in the section "Device -> InterfaceLayout":

Selection of the interface layout for this specific device
Note
If a device is opened, but the selected interface layout has been declared deprecated, a message box will show up to make sure that the interface layout has not been changed by accident.
Warning message if an interface layout is selected which has been declared deprecated for the used device
See also

Changing The Interface Layout To GenICam Or DeviceSpecific

Devices belonging to this family only support the Device Specific interface layout which is the common interface layout supported by most MATRIX VISION devices.

GenICam compliant devices can be operated in different interface layouts. Have a look at a GenICam compliant device for additional information.

Interface Configuration And Driver Configuration

Some basic driver configuration is available through the Detailed Driver Information dialog. Much more is possible and how to do this is described in the API manuals in the corresponding chapter "Setting Up The Framework For Third Party GenTL Producer Usage"

See also

Storing, Restoring And Managing Settings

About Settings

A setting contains all parameters that are needed to configure the device to a state it was in when the setting was created. Every image can be captured with a completely different set of parameters. In almost every case, these parameters are accessible via a property offered by the device driver. A setting e.g. might contain

  • The gain to be applied to the analog to digital conversion process for analog video sources or
  • The AOI to be captured from the incoming image data.

So for the user a setting is the one and only place where all the necessary modifications can be applied to achieve the desired data acquisition mode. There is however an important difference in behaviour between different interface layouts. See here to find out how to modify the interface layout or check in the API documentation for the interfaceLayout property of the class Device.

  • When working with the DeviceSpecific interface layout, each frame will be captured with the settings as present when requesting the image. Every parameter can be modified at any time. When requesting another image the settings valid at that moment will be used to fill this buffer with data
  • For the GenICam interface layout all device properties modified during a continuous acquisition will be applied at once so might affect this or the next image transmitted by the device. Depending on various parameters (the number of buffer already captured but not collected by the application, the way the device internally operates(e.g. has already captured a couple of images that await transmission), etc.) this will have impact on that captured images somewhere in the near future thus when a precise moment to change settings is needed, continuous acquisition must be stopped and then restarted after modifying the features. Certain features (typically those affecting the buffer layout/size) cannot be changed while a continuous acquisition is running in GenICam interface layout anyway.

Now, whenever a device is opened, the driver will execute following procedure:

wxPropView - Device setting start procedure
  • Please note that each setting location step in the figure from above internally contains two search steps. First the framework will try to locate a setting with user scope and if this can't be located, the same setting will be searched with global (system-wide) scope. On Windows this e.g. will access either the HKEY_CURRENT_USER or (in the second step) the HKEY_LOCAL_MACHINE branch in the Registry.
  • Whenever storing a product specific setting, the device specific setting of the device used for storing will be deleted (if existing). E.g. you have a device "VD000001" which belongs to the product group "VirtualDevice" with a setting exclusively for "VD000001". As soon as you store a product specific setting using THIS device, the (device specific) setting for "VD000001" will be deleted. Otherwise a product specific setting would never be loaded as a device specific setting will always be found first. Storing a product specific setting with a different device belonging to the same family however will NOT delete device specific settings for other devices.
  • The very same thing will also happen when opening a device from any other application! mvPropView does not behave in a special way but only acts as an arbitrary user application.
  • Whenever storing a device family specific setting, the device specific or product specific setting of the device used for storing will be deleted (if existing). See above to find out why.
  • On Windows the driver will not look for a matching XML file during start-up automatically as the native storage location for settings is the Windows Registry. This must be loaded explicitly by the user by using the appropriate API function offered by the SDK. However, under Linux XML files are the only setting formats understood by the driver framework thus here the driver will also look for them at start-up. The device specific setting will be an XML file with the serial number of the device as the file name, the product specific setting will be an XML file with the product string as the filename, the device family specific setting will be an XML file with the device family name as the file name. All other XML files containing settings will be ignored!
  • Restoring of settings previously stored works in a similar way. After a device has been opened the settings will be loaded automatically as described above.
  • A detailed description of the individual properties offered by a device will not be provided here but can be found in the C++ API reference, where descriptions for all properties relevant for the user (grouped together in classes sorted by topic) can be found. As mvPropView doesn't introduce new functionality but simply evaluates the list of features offered by the device driver and lists them any modification made using the GUI controls just calls the underlying function needed to write to the selected component. mvPropView also doesn't know about the type of component or e.g. the list of allowed values for a property. This again is information delivered by the driver and therefore can be queried by the user as well without the need to have special inside information. One version of the tool will always be delivered in source so it can be used as a reference to find out how to get the desired information from the device driver.

Storing Settings

wxPropView - Storing settings

Settings can be stored in several ways via the menu: "Action -> Capture Settings -> Save Active Device Settings":

  • "As Default Settings For All Devices Belonging To The Same Family (Per User Only)": As the start-up parameters for every device belonging to the same family, e.g. for mvBlueCOUGAR-X, mvBlueCOUGAR-XD, mvBlueCOUGAR-XT.
  • "As Default Settings For All Devices Belonging To The Same Family And Product Type": As the start-up parameters for every device belonging to the same product, e.g. for any mvBlueCOUGAR-X but not for mvBlueCOUGAR-XD or mvBlueCOUGAR-XT.
  • "As Default Settings For This Device(Serial Number)": As the start-up parameters for the currently selected device.
  • "To A File": As an XML file that can be used e.g. to transport a setting from one machine to another or even to use the settings configured for one platform on another (Windows <-> Linux).

Restoring Settings

Restoring of settings previously stored works in a similar way as Storing Settings. After a device has been opened the settings will be loaded automatically as described above.

However a different setting can be restored at any time via the menu: "Action -> Capture Settings -> Load Active Device Settings":

  • explicitly load the device family specific settings stored on this machine (from "The Default Settings Location For This Devices Family (Per User Only)")
  • explicitly load the product specific settings stored on this machine (from "The Default Settings Location For This Devices Family And Product Type)")
  • explicitly load the device specific settings stored on this machine (from "The Default Settings Location For This Device(Serial Number)")
  • explicitly load device family specific settings from a XML file previously created ("From A File")
Note
Another way to load a setting from hard disk is by dragging it onto The Property Grid and dropping it there.
"GenICam devices": Since mvIMPACT Acquire 2.9.0 GenICam devices will be able to save their properties in a XML File, only if the properties have the streamable attribute set (for more information refer to the GenICam standard specification). Properties with no streamable attribute set, will be silently ignored when saving, which means they will not be saved in the XML file. For MATRIX VISION GenICam cameras, starting with firmware version 1.6.414 the streamable attribute is set for all the necessary properties.


Note
Since mvIMPACT Acquire 2.9.0 and again in version 2.11.0 storing and loading of camera settings in a XML file for the GenICam interface layout has been updated. As a result XML files created with newer versions of mvIMPACT Acquire might not be readable on systems with older version of mvIMPACT Acquire installed. XML files created on systems with earlier versions of mvIMPACT Acquire will always be readable this or newer versions. See the following table for details.
mvIMPACT Acquire VersionLoading a XML settings file created with mvIMPACT Acquire version < 2.9.0Loading a XML settings file created with mvIMPACT Acquire version 2.9.0 - 2.10.1Loading a XML settings file created with mvIMPACT Acquire version 2.11.0 or later
< 2.9.0 YES NO NO
2.9.0 - 2.10.1 YES YES NO
>= 2.11.0 YES YES YES
Attention
Since mvIMPACT Acquire 2.28.0 it is possible for devices operated in the GenICam interface layout to store settings including sequencer set and user set (see SFNC(https://www.emva.org/standards-technology/genicam/) for details) data by specifying appropriate flags during the storage operation. Settings stored like this cannot be loaded by previous mvIMPACT Acquire versions.
Note
For devices operated in the GenICam interface layout further restriction apply: Settings created with a certain product type can only be used with other devices belonging to the exact same type as defined by the property Product inside the device list (the one device specific property list that is accessible without initializing the device before). Even if a setting can be used with various firmware versions it is recommended to use one setting for multiple devices all updated to the very same firmware version to avoid compatibility problems.
wxPropView - Restoring settings

Deleting Settings

With "Action -> Capture Settings -> Manage..." you can delete the settings which were saved on the system:

wxPropView - Manage settings

This will open another dialog displaying ALL (not only the ones applicable for the currently selected device) settings that are currently stored on the system at the default location:

wxPropView - Manage settings

White Balancing A Color Camera

Start the wxPropView and initialize the device by clicking "Use" and start a "Continuous" acquisition.

wxPropView - Starting window

While using a color version of the camera, the PC will calculate a color image from the original gray Bayer mosaic data. For getting correct colors when working with a Bayer mosaic filter you have to calibrate the white balance (this must be performed every time the lighting conditions change).

The "White Balance Control" can be found in "Setting -> Base -> Camera -> GenICam -> Analog Control -> Balance White Auto". Just select "Continuous" and you will get a white balanced image.

For older devices, wxPropView offers predefined settings for e.g.

  • "Daylight",
  • "TungstenLamp",
  • "HalogenLamp",
  • "FluorescentLamp" and many more.

Simply select the necessary item in the menu "Image Settings -> Base -> ImageProcessing -> WhiteBalance" (DeviceSpecific interface layout) or "Setting -> Base -> ImageProcessing -> WhiteBalance" (GenICam interface layout).

If you need a user defined setting, you can also define own ones. For this, select a profile (e.g. User1) for this setting:

wxPropView - Selecting WhiteBalance profile
Note
You can use up to 4 profiles.

Point the camera on a white or light gray area (the pixels do not have to be saturated, so use gray values between 150 and 230).

Go to the menu item "WhiteBalanceCalibration" and select the parameter "Calibrate Next Frame":

wxPropView - WhiteBalanceCalibration

By committing the selected value, the application accepts the change. The next acquired image will be the reference for the white balance.

All further acquired images will be balanced with this setting:

wxPropView - White balance summary

For easier handling and easier working, all settings can be saved by clicking the menu Action -> Capture Settings -> Save ....

Optimizing White Balance In The Camera

The gain is increased before the digital white balancing, which uses green as reference. Based on the 14 bit image raw data, the digital white balance adjusts the gain of red and blue. Afterwards, the 8 bit reducing and the transfer takes place.

To optimize the digital white balance within the camera you can select "Red" or "Blue" in "Balance Ratio Selector" (in "Analog Control") to adjust the gain. Afterwards, turn "Balance White Auto" to "Off" and "Once" to execute it.

wxPropView - Optimizing white balance

Configuring Different Trigger Modes

To configure a device for a triggered acquisition, in wxPropView the property "Setting -> Base -> Camera -> GenICam -> Acquisition Control -> Trigger Selector" ("GenICam interface layout") is available. For older devices without GenICam you will find the property here: "Image Setting -> Camera -> TriggerMode".

Note
The supported trigger modes of each sensor are described in the "More specific data" of each sensor in the corresponding product manual.

All trigger modes are defined by an enumeration:

  • TCameraTriggerMode and TCameraTriggerSource

"For frame grabbers:"

  • DeviceTriggerMode. However, not every device will offer all these trigger modes but a subset of them. Valid trigger modes therefore can be found by reading the properties translation dictionary.

A sample on how to query a property's translation dictionary can be found here:

  • mvIMPACT::acquire::PropertyI::getTranslationDict (C++ developers)
  • OBJ_GetDictSize() (C or VB developers)

There is also a chapter "Getting a triggered image" chapter, which is available in the "mvIMPACT Acquire API" manuals.

Testing The Digital Inputs

Note
The following description will be significant if you are using the "DeviceSpecific interface layout". In GenICam layout, the "Digital I/O" section can be found in "Setting -> Base -> Camera -> GenICam -> Digital I/O Control".

For performance reasons, device drivers will not automatically update their digital input properties if nobody is interested in the current state. Therefore, in order to check the current state of a certain digital input, it is necessary to manually refresh the state of the properties. To do this please right-click on the property you are interested in and select "Force Refresh" from the pop-up menu.

GenICam interface layout only:

Some devices might also offer an event notification if a certain digital input changed its state. This event can then be enabled

  • via the "EventSelector" in "Setting -> Base -> Camera -> GenICam -> Event Control".
  • Afterwards, a callback can be registered by right-clicking on the property you are interested in again.
  • Now, select "Attach Callback" from the pop-up menu and switch to the "Output" tab in the lower right section of wxPropView (Analysis tabs).

Whenever an event is send by the device that updates one of the properties a callback has been attached to, the output window will print a message with some information about the detected change.

wxPropView - Call refresh

Compensating Defective Pixels

Since
Firmware version 1.01.20

The mvBlueCOUGAR-S cameras feature a built-in defective pixel compensation. For that purpose, you will need the current firmware.

See also

To compensate the defective pixels, please do following steps (you can use the tab "Pixel Histogram" to show the gray scale values):

  1. Select the value "PixelCompensationLevelRaw", which indicates the percentage level from which a pixel is considered as defective.
  2. Over "int PixelCompensationDetect()", click on the right mouse button and confirm with "Execute".

    wxPropView - Execute PixelCompensationDetect
    wxPropView - PixelCompensationDetect executed

  3. Now, activate the PixelCompensation by setting "PixelCompensationMode" to "On."

    wxPropView - PixelCompensationMode "On"

This setting can be saved in the camera via "int PixelCompensationSave()" so that the pixel compensation is system independent.

Saving User Settings In The Non-volatile Memory

Some cameras offer the possibility, to save up to 4 user sets in the camera's non-volatile memory directly. This means that all camera specific settings you've adjusted via wxPropView can be saved in a non-volatile memory.

Example: You have connected a flash via exposure out of the camera and you want to avoid an overload of the flash by maloperation, you can save a suitable shutter time, with which the camera will start.

To save your specific settings, set you properties in the "Setting -> Camera -> GenICam" section of wxPropView. Then, select in "User Set Control" your user set with the "User Set Selector", for example "UserSet1". Afterwards, save the user set with "int UserSetSave()". Finally, if you want that the camera starts with a specific user set (after power up), you have to select it with the "User Set Default Selector".

wxPropView - User set control
Attention
A firmware update will delete all saved register settings!