MATRIX VISION - mvBlueLYNX-M7 Technical Documentation
Application Usage

Table of Contents

wxPropView

wxPropView is an interactive GUI tool to acquire images and to configure the device and to display and modify the device properties of MATRIX VISION GmbH hardware. After the installation you can find wxPropView

  • as an icon with the name "wxPropView" on the desktop (Windows) or
  • in "~/mvimpact-acquire/apps/mvPropView/x86" (Linux).
Note
"With Linux": If you want to run the GUI tools as root for achieving a better performance, you have to export following paths (this is done automatically for simple user): 
export GENICAM_ROOT=/home/x/tmp 
export GENICAM_ROOT_V3_0=/home/x/tmp
export GENICAM_LOG_CONFIG=/home/x/tmp/share/genicam/log/config/DefaultLogging.properties

or easier run shell script "genicam.sh" before: 
. /etc/profile.d/genicam.sh
Webcast
wxPropView - Introduction

How to work with wxPropView

Webcast
wxPropView - Working with wxPropView

Depending on the driver version, wxPropView starts with the Quick Setup Wizard (as soon as a camera with the right firmware version was selected used or a single camera with the right firmware was found) or without it.

Quick Setup Wizard

Since
mvIMPACT Acquire 2.11.3

The Quick Setup Wizard is a tiny and powerful single window configuration tool to optimize the image quality automatically and to set the most important parameters, which affect the image quality, in an easy way manually and to get a preview of this changes. Settings will be accepted by clicking ok, otherwise the changes are cancelled.

Figure 1:Quick Setup Wizard started

Depending on the camera spectrum (gray or color sensor), it will automatically pre-set the camera so that image quality is usually as best as possible.

"For all cameras:"
Image format is chosen as 10 bit (if possible) as a good compromise on image quality and speed.
It will further set

  • "Exposure" to Auto,
  • "Gain" to Auto,
  • "Frame rate" to Auto based on current settings of the camera, and
  • switches camera into continuous mode

"In case of gray:"
The above settings will be also applied whenever the "Gray Preset" button is pressed. For gray cameras it is herewith assumed that image processing prefers a linear camera response.

"In case of color:"
It will additionally set

  • "White balance" in the camera to Auto, and will apply
  • a host based moderate "Gamma correction" (1.8), and lastly it will apply
  • a host (PC) based sensor specific "Color Correction Matrix" and use the respective "sRGB display matrix".

These settings will also be applied whenever the "Color Preset" button is pressed. It is herewith assumed that color camera image is optimized for best human visual feedback.

Changing the Presets

There are 3 presets:

  • Gray
  • Color
  • Factory

Factory can be used as a fall back to quickly skip or remove all presets and load the factory default settings.

Modifying Settings

All auto modes can be switched off and all settings, such as Gain, Exposure etc. can be subsequently modified by using:

  • the sliders,
  • the arrow keys, or
  • entering real values with your keyboard.

Toggling Gamma button loads or unloads a host based 10 bit Gamma correction with a moderate value of 1.8 into the signal processing path. Switch Gamma on if you require a gray level camera image to appear natural for the human eye.

Toggling Color+ button switches both CCM and sRGB display matrix on and off. This optimizes the sensor color response for the human eye and goes in conjunction with a display color response. Because sRGB displays are mostly used and this is the default color space in Windows OS, these are preselected. If you require other display matrices (e.g. Adobe or WideGamut) feel free to use the tree mode of wxPropView and select ColorTwistOutputCorrection accordingly.

Setting Black Level
Black level can be used if you require dark portions in the image to appear even darker or brighter. Please note that this slider combines analog and digital settings meaningfully.

Setting Gain
Gain settings also combine analog and digital registers into one slider setting.

Setting Saturation
Saturation setting increases the color saturation to make the image appear more colored. It does not change uncolored parts in the image nor changes the color tone or hue.

How to disable Quick Setup Wizard

Uncheck the checkbox "Show This Display When A Device Is Opened" to disable the Quick Setup Wizard to be called automatically. Use the "Wizards" menu and select "Quick Setup" to open the Quick Setup Wizard once again.

How to Return to the Tree Mode

Use OK to use the values and settings of the Quick Setup Wizard and go back to the tree mode of wxPropView.

Use Cancel to discard the Quick Setup Wizard values and settings and go back to wxPropView and use the former (or default) settings.

Image Display Functions

Quick Setup Wizard allows zooming into the image by right clicking in the image area and unchecking "Fit To Screen" mode. Use the mouse wheel to zoom in or out. Check "Fit To Screen" mode, if you want the complete camera image to be sized in the window screen size.

Known Restrictions

In cases of Tungsten (artificial) light, camera brightness may tend to oscillations if Auto functions are used. This can be minimized or avoided by setting the frame frequency to an integer divisor of the mains frequency.

  • Example:
    • Europe: 50 Hz; Set frame rate to 100, 50, 25 12.5 fps or appropriate.
    • In countries with 60 Hz use 120, 60, 30 or 15… accordingly.

First View of wxPropView

wxPropView consists of several areas:

Figure 2:wxPropView started
  • "Menu Bar"
    (to work with wxPropView using the menu)
  • "Upper Tool Bar"
    (to select and initialize a device, acquire images, play a recorder sequence)
  • "Left Tool Bar"
    (to hide and show parts of the GUI)
  • "Status Tool Bar"
  • "Main Window" with
    • "Grid"
      (tree control with the device settings accessible by the user)
    • "Display"
      (for the acquired images)
  • "Analysis"
    (information about whole images or an AOI)

By clicking on F1 you will get the HELP dialog.

Now, you can initialize a device by

  • selecting it in the drop down list in the "Upper Tool Bar" and
  • clicking on "Use".

After having successfully initialized a device the tree control in the lower left part of the "Main Window" will display the properties (settings or parameters) (according to the "interface layout") accessible by the user.

You've also got the possibility to set your "User Experience". According to the chosen experience, the level of visibility is different:

  • Beginner (basic camera settings/properties are visible)
  • Expert (e.g. all advanced image processing are visible)
  • Guru (all settings/properties are visible)

Properties displayed in light grey cannot be modified by the user. Only the properties, which actually have an impact on the resulting image, will be visible. Therefore, certain properties might appear or disappear when modifying another properties.

To permanently commit a modification made with the keyboard the ENTER must be pressed. If leaving the editor before pressing ENTER will restore the old value.

How to see the first image

As described earlier, for each recognized device in the system the devices serial number will appear in the drop down menu in the upper left corner of the "Upper Tool Bar". When this is the first time you start the application after the system has been booted this might take some seconds when working with devices that are not connected to the host system via PCI or PCIe.

Once you have selected the device of your choice from the drop down menu click on the "Use" button to open it.

When the device has been opened successfully, the remaining buttons of the dialog will be enabled:

Note
Following screenshots are representative and where made using a mvBlueCOUGAR-X camera as the capturing device.

For color sensors, it is recommended to perform a white balance calibration before acquiring images. This will improve the quality of the resulting images significantly.

Figure 3:wxPropView - First start

 

Now, you can capture an image ("Acquisition Mode": "SingleFrame") or display live images ("Continuous"). Just

  • select an "Acquisition Mode" e.g. "SingleFrame" and
  • click the "Acquire" button.
Note
The techniques behind the image acquisition can be found in the developers sections.

The frame rate depends on

  • the camera,
  • the pixel clock of the sensor and
  • the "Acquisition Frame Rate".

If you want to have a fixed frame rate using the "Continuous" mode, GenICam offers the property "Setting -> Base -> Camera -> GenICam -> Acquisition Control -> Acquisition Frame Rate" (from 5 fps to maximum of the camera in 0.1 increments). Just adapt this property to your needs.

Alternatively, if you need frame rates below 5 fps, you can use Timers. Since the mvBlueLYNX-M7 has two sensors, you have to set the image source. In section "Camera" you can define all the parameters used for image acquisition. To change between sensors, go into subsection "Connector" and change property "VideoChannel" to either 0 or 1. wxPropView can only display images from one sensor simultaneously.

Set acquisition parameters suitable for your application and save settings with menu item "Action -> Capture Settings -> Save -> Active Device Settings".

Figure 4: wxPropView - Selecting camera source (screenshot: Linux system)
Note
There is one special example application, which demonstrates, how to capture from both sensors simultaneously. This example is called "SynchronousCaptureMultipleInputs" and can be found in the "mvIMPACT Acquire API" manuals.

Record Mode

It is also possible to record image sequences using wxPropView.

  1. For this, you have to set the size of the recorder in "System Settings -> RequestCount" e.g. to 100.
    This will save the last 100 requests in the request queue of the driver, i.e. the image data including the request info like frame number, time stamp, etc.
  2. Afterwards you can start the recording by clicking the Rec. button.
  3. With the Next and Prev. buttons you can display the single images.

If you switched on the request info overlay (righ-click on the display area and select the entry to activate this feature), these information will be displayed on the image, too. With the timestamp you can see the interval of the single frames in microseconds.

Figure 5: wxPropView - Using the record mode.

Hard Disk Recording

You can save acquired images to the hard disk the following way:

  1. In the "Menu Bar" click on "Capture -> Recording -> Setup Hard Disk Recording".
  2. Confirm with "Yes".
  3. Afterwards select the target folder for the images.
  4. Finally, choose the file format of the acquired images.
Figure 6: wxPropView - Hard Disk Recording.

Using the analysis plots

With the analysis plots you have the possiblity to get image details and to export them.

Spatial noise histogram

The spatial noise histogram calculates and evalutates statistically the difference between two neighbouring pixels in vertical and horizontal direction. I.e. it shows the sensor's spatial background pattern like the sensitivity shifts of each pixel. An ideal sensor or camera has a spatial noise of zero. However, you have to keep in mind the temporal noise as well.

Figure 7:wxPropView - Spatial noise histogram

Read: Channel::Direction (Mean difference, most frequent value count/ value, Standard deviation)

Example: For a single channel(Mono) image the output of 'C0Hor(3.43, 5086/ 0, 9.25), C0Ver(3.26, 4840/ 0, 7.30) will indicate that the mean difference between pixels in horizontal direction is 3.43, the most frequent difference is 0 and this difference is present 5086 times in the current AOI. The standard deviation in horizontal direction is 9.25. The C0Ver value list contains the same data but in vertical direction.

Temporal noise histogram

The temporal noise histogram shows the changes of a pixel from image to image. This method is more stable because it is relatively independent from the image content. By subtracting two images, the actual structure is eliminated, leaving the change of a pixel from image to image, that is, the noise. When capturing images, all parameters must be frozen, all automatic mechanisms have to be turned off and the image may not have underexposed or saturated areas. However, there are no picture signals without temporal noise. Light is a natural signal and the noise always increases with the signal strength. If the noise only follows the natural limits, then the camera is good. Only if additional noise is added the camera or the sensor has errors.

Figure 8:wxPropView - Temporal noise histogram

Read: Channel# (Mean difference, most frequent value count/ value, Standard deviation)

Example: For a single channel(Mono) image the output of 'C0(3.43, 5086/ 0, 9.25) will indicate that the mean difference between pixels in 2 consecutive images is 3.43, the most frequent difference is 0 and this difference is present 5086 times in the current AOI. The standard deviation between pixels in these 2 images is 9.25. Please note the impact of the 'Update Interval' in this plot: It can be used to define a gap between 2 images to compare. E.g. if the update interval is set to 2, the differences between image 1 and 3, 3 and 5, 5 and 7 etc. will be calculated. In order to get the difference between 2 consecutive images the update interval must be set to 1!

Storing and restoring settings

When wxPropView is started for the first time, the values of properties set to their default values will be displayed in green to indicate that these values have not been modified by the user so far. Modified properties (even if the value is the same as the default) will be displayed in black.

Figure 9:wxPropView - Storing settings

Settings can be stored in several ways (via the "Menu Bar": "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.
  • "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.
  • "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).

During the startup of a device, all these setting possibilities show different behaviors. The differences are described in chapter Settings behaviour during startup

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

However, at runtime the user has different load settings possibilities (via the "Menu Bar": "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")
Warning
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.


Warning
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 including sequencer set and user set (see SFNC 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.
With "Action -> Capture Settings -> Manage..." you can delete the settings which were saved on the system.
Figure 10:wxPropView - Restoring settings

Properties

All properties and functions can be displayed in the list control on the lower left side of the dialog. To modify the value of a property select the edit control right of the properties name. Property values, which refer to the default value of the device, are displayed in green. A property value once modified by the user will be displayed in black (even if the value itself has not changed). To restore its default value of a single property

  • right click on the name of the property and
  • select "Restore Default".

To restore the default value for a complete list (which might include sub-lists)

  • right click on the name of a list and
  • select "Restore Default".

In this case a popup window will be opened and you have to confirm again.

Figure 11:wxPropView - Restore the default value of a property

Most properties store one value only, thus they will appear as a single entry in the property grid. However, properties are capable of storing more than one value, if this is desired. A property storing more than one value will appear as a parent list item with a WHITE background color (lists will be displayed with a grey background) and as many child elements as values stored by the property. The PARENT grid control will display the number of values stored by the property, every child element will display its corresponding value index.

If supported by the property, the user might increase or decrease the number of values stored by right clicking on the PARENT grid element. If the property allows the modification the pop up menu will contain additional entries now:

Figure 12:wxPropView - A resizable property

When a new value has been created it will be displayed as a new child item of the parent grid item:

Figure 13:wxPropView - A resized property

Currently, only the last value can be removed via the GUI and a value can't be removed, when a property stores one value only.

Also the user might want to set all (or a certain range of) values for properties that store multiple values with a single operation. If supported by the property, this can also be achieved by right clicking on the PARENT grid element. If the property allows this modification the pop up menu will again contain additional entries:

Figure 14:wxPropView - Setting multiple property values

It's possible to either set all (or a range of) elements of the property to a certain value OR to define a value range, that then will be applied to the range of property elements selected by the user. The following example will explain how this works:

Figure 15:wxPropView - Setting multiple property values within a certain value range

In this sample the entries 0 to 255 of the property will be assigned the value range of 0 to 255. This will result in the following values AFTER applying the values:

Figure 16:wxPropView - After applying the value range to a property

Methods

Method appears as entries in the tree control as well. However, their name and behavior differs significantly from the behavior of properties. The names of method objects will appear in 'C' syntax like e.g. "int function( char*, int )". This will specific a function returning an integer value and expecting a string and an integer as input parameters. To execute a method object

  • right click on the name of a method and
  • select "Execute" from the popup menu:
Figure 17:wxPropView - Calling a method object

Parameters can be passed to methods by selecting the edit control left of a method object. Separate the parameters by blanks. So to call a function expecting a string and an integer value you e.g. might enter "testString 0" into the edit control left of the method.

The return value (in almost every case an error code as an integer) will be displayed in the lower right corner of the tree control. The values displayed here directly correspond the error codes defined in the interface reference and therefore will be of type TDMR_ERROR or TPROPHANDLING_ERROR.

Copy grid data to the clipboard

Since wxPropView version 1.11.0 it is possible to copy analysis data to the clipboard. The data will be copied in CSV style thus can be pasted directly into tools like Open Office™ or Microsoft® Office™.

Just

  • right-click on the specific analysis grid when in numerical display mode and
  • select "Copy grid to clipboard" from the pop up menu.
Figure 18:wxPropView - Copying grid data to the clipboard

Import and Export images

wxPropView offers a wide range of image formats that can be used for exporting captured image to a file. Some formats e.g. like packed YUV 4:2:2 with 10 bit per component are rather special thus they can't be stored into a file like e.g. offered by the BMP file header. When a file is stored in a format, that does not support this data type wxPropView will convert this image into something that matches the original image format as close as possible. This, however, can result in the loss of data. In order to allow the storage of the complete information contained in a captured image wxPropView allows to store the data in a raw format as well. This file format will just contain a binary dump of the image with no leader or header information. However, the file name will automatically be extended by information about the image to allow the restoring of the data at a later time.

All image formats, that can be exported can also be imported again. Importing a file can be done in 3 different ways:

  • via the menu (via the "Menu Bar": "Action -> Load image...")
  • by dragging an image file into an image display within wxPropView
  • by starting wxPropView from the command line passing the file to open as a command line parameter (under Windows® e.g. "wxPropView.exe MyImage.png" followed by [ENTER])

When importing a "*.raw" image file a small dialog will pop up allowing the user to define the dimensions and the pixel format of the image. When the file name has been generated using the image storage function offered by wxPropView, the file name will be passed and the extracted information will automatically be set in the dialog thus the user simply needs to confirm this information is correct.

Figure 19:wxPropView - Raw image file import

Setting up multiple display support and/or work with several capture settings in parallel

wxPropView is capable of

  • dealing with multiple capture settings or acquisition sequences for a single device and in addition to that
  • it can be configured to deal with multiple image displays.

The amount of parallel image displays can be configured via the command line parameter "dcx" and "dcy". In this step by step setup wxPropView has been started like this from the command line:

wxPropView dcx=1 dcy=2

This will result in 1 display in horizontal direction and 2 in vertical direction.

Since
mvIMPACT Acquire 2.18.1

Is is also possible to change the amount of display at runtime via "Settings -> Image Displays -> Configure Image Display Count":

Figure 20:wxPropView - Create capture setting



Additional capture settings can be created via "Menu Bar": "Capture -> Capture Settings -> Create Capture Settings". The property grid will display these capture settings either in "Developers" or in "Multiple Settings View".

Note
In GenICam interface layout multiple capture settings are NOT supported. However, you can define different acquisition sets using the Sequencer Control.

Now, in order to set up wxPropView to work with 2 instead of one capture setting,

  1. Various additional capture setting can be created. In order to understand what a capture setting actually is please refer to

    • "Working with settings" chapter of the "mvIMPACT Acquire API" manuals.

    Creating a capture setting is done via "Capture -> Capture Settings -> Create Capture Setting".

    Figure 21:wxPropView - Create capture setting



  2. Then, the user is asked for the name of the new setting.

    Figure 22:wxPropView - Create capture setting - Choosing name



  3. And finally for the base this new setting shall be derived from.

    Figure 23:wxPropView - Create capture setting - Choosing base

Afterwards, in this example we end up having 2 capture settings:

  • a "Base" setting, which is always available
  • a "NewSetting1", which has been derived from "Base".
Figure 24:wxPropView - two settings

As "NewSetting1" has been derived from "Base" changing a property in "Base" will automatically change this property in "NewSetting1" if this property has not already been modified in "NewSetting1". Again to get an understanding for this behaviour please refer to

  • "Working with settings" chapter of the "mvIMPACT Acquire API" manuals.

Now, to set up wxPropView to display all images taken using capture setting "Base" in one display and all image taken using capture setting "NewSetting1" in another display the capture settings need to be assigned to image displays via "Capture -> Capture Settings -> Assign To Display(s)".

Figure 25:wxPropView - Assigning displays
Figure 26:wxPropView - Assigning displays

By default a new setting when created will be assigned to one of the available displays in a round-robin scheme, thus when there are 3 displays, the first (Base) setting will be assigned to "Display 0", the next to "Display 1", the next to "Display 2" and a fourth setting will be assigned to "Display 0" again. The setting to display relationships can be customized via "Capture -> Capture Settings -> Assign to Display(s)".

As each image display keeps a reference to the request, this image belongs to the driver can't re-use the request buffer until a new request is blitted into this display. Thus, it might be necessary to increase the number of request objects the driver is working with if a larger number of displays are involved. The minimum number of requests needed is 2 times the amount of images displays. The number of requests used by the driver can be set up in the drivers property tree:

Figure 27:wxPropView - Setting up request count

Finally, wxPropView must be configured in order to use all available capture settings in a round-robin scheme. This can be done by setting the capture setting usage mode to "Automatic" via "Capture -> Capture Settings -> Usage Mode":

Figure 28:wxPropView - Capture setting usage mode

That's it. Now, starting a live acquisition will display live images in both displays and each display is using a different set of capture parameters. If a device supports parallel acquisition from multiple input channels, this will increase

  • the used bandwidth and also
  • the CPU load

as wxPropView now needs to display more images per second. Each display can be configured independently thus e.g. one display can be used scaled while the other displays 1:1 data. The analysis plots can be assigned to a specific display by left-clicking on the corresponding image display, the info plot will plot a graph for each capture setting in parallel.

Figure 29:wxPropView - Running example

When only one setting shall be used at a given time, this can be achieved by setting the capture setting usage mode back to "Manual" via "Capture -> Capture Settings -> Usage Mode". Then the setting that shall be used can be manually selected in the request control list:

Figure 30:Manual Setting Usage Mode

This can even be changed during a running acquisition.

Bit-shifting an image

wxPropView shows snapped or live images in the display area of the GUI. The area, however, shows the most significant bits (msb) of the image in the 8 bit display.

The following image shows how a mid-grey 12 bit pixel of an image is displayed with 8 bit. Additionally, two shifts are shown.

Figure 31:Mid-grey 12 bit pixel image and 8 bit display with 2 example shifts

In this particular case, the pixel will be brighter (as the most significant bits are 1’s). Perhaps you already recognized it. Each shift means that each pixel value is multiplied or divided by 2 according to the direction.

Anyway, there is one restriction in the 8 bit display:

If the pixel value is greater than 255, the pixel value will be clipped to 255. To describe this from a programmer’s view; a represents the pixel value:

 a = ( a > 255 ) ? 255 : a

With wxPropView you can shift the bits in the display using the left and right arrow keys. Furthermore you can turn on the monitor display to compare the images synchronously.

Webcast
wxPropView - Bit-shifting an Image

Changing the view of the property grid to assist writing code that shall locate driver features

With wxPropView it is possible to switch the views between "Standard View" (user-friendly) and "Developers View". While the first (default) view will display the device drivers feature tree in a way that might be suitable for most users of a GUI application it might present the features in a slightly different order as they actually are implemented in the device driver. The developers view switches the tree layout of the application to reflect the feature tree exactly like it is implemented an presented by the SDK. It can be helpful when writing code that shall locate a certain property in the feature tree of the driver using the C, C++, or .NET interface. The feature hierarchy displayed here can directly be used for searching for the features using the "ComponentLocator (C++/.NET)" objects or "DMR_FindList (C)" and "OBJ_GetHandleEx (C)" functions.

Figure 32:Developers View

Accessing log files

Since
mvIMPACT Acquire 2.11.9

Using Windows, it is possible to access the log files generated by MATRIX VISION via the Help menu. Sending us the log files will speed up support cases.

Figure 33:wxPropView - Help menu

The options are to

See also
Accessing log files using Linux

How to configure a device

As described above, after the device has been initialized successfully in the "Grid" area of the GUI the available properties according to the chosen "interface layout" (e.g. GenICam) are displayed in a hierarchy tree.

Webcast
wxPropView - Configuring a device

The next chapter will show how to set the interface layout and which interface you should use according to your needs.

 

Changing interface to GenICam or device specific

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

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 Bar":

Figure 34: 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":

Figure 35: Selection of the interface layout for this specific device
See also
GenICam
Standard Feature Naming Convention of GenICam properties

White balance of a camera device (color version)

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

Figure 36: 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.

Figure 37: wxPropView - Selecting WhiteBalance profile
Figure 38: wxPropView - WhiteBalanceCalibration
Figure 39: wxPropView - White balance summary

Configuring different trigger modes

To configure a device for a triggered acquisition, in wxPropView the property "Image Setting -> Camera -> TriggerMode" ("DeviceSpecific interface layout") or "Setting -> Base -> Camera -> GenICam -> Acquisition Control -> Trigger Selector" ("GenICam interface layout") is available.

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

All trigger modes are defined by an enumeration:

  • TCameraTriggerMode and TCameraTriggerSource
  • CameraSettingsBlueCOUGAR

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 laylout, 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.

Figure 40: wxPropView - Call refresh

Command-line options

It is possible to start wxPropView via command line and controlling the starting behavior using parameters. The supported parameter are as follows:

Parameter Description
width or w Defines the startup width of wxPropView. Example: width=640
height or h Defines the startup height of wxPropView. Example: height=460
xpos or x Defines the startup x position of wxPropView.
ypos or y Defines the startup x position of wxPropView.
splitterRatio Defines the startup ratio of the position of the property grids splitter. Values between > 0 and < 1 are valid. Example: splitterRatio=0.5
propgridwidth or pgw Defines the startup width of the property grid.
debuginfo or di Will display debug information in the property grid.
dic Will display invisible (currently shadowed) components in the property grid.
displayCountX or dcx Defines the number of images displayed in horizontal direction.
displayCountY or dcy Defines the number of images displayed in vertical direction.
fulltree or ft Will display the complete property tree (including the data not meant to be accessed by the user) in the property grid. Example (Tree will be shown): fulltree=1
device or d Will directly open a device with a particular serial number. * will take the first device. Example: d=GX000735
qsw Will forcefully hide or show the Quick Setup Wizard, regardless of the default settings. Example (Quick Setup Wizard will be shown): qsw=1
live Will directly start live acquisition from the device opened via device or d directly. Example (will start the live acquisition): live=1

Sample (Windows)

wxPropView.exe d=* fulltree=1 qsw=0

This will start the first available device, will hide the Quick Setup Wizard, and will display the complete property tree.



mvGigEConfigure

mvGigEConfigure is an interactive GUI tool to install the GigE capture filter which adds a service to your Gigabit Ethernet interface

Note
Windows 2000 does not support the "Resend" mechanism of GigE Vision.

Install GigE Vision capture filter

To install the GigE capture filter, please follow these instructions:

  1. Start the mvGigEConfigure by clicking the program in the start menu.
    The tool will start.
  2. Click on the "Install driver" button.
    mvGigEConfigure will install the driver and adds a service to your Gigabit Ethernet interface automatically.

After installation of the capture filter, you will see you network devices and the connected devices:

Figure 41: mvGigEConfigure displays connected devices

When a GigE compliant device will be initialised, wxPropView it will display the used driver technology:

Figure 42: wxPropView - Device Properties

Once a device has been initialized successfully the property "mvStreamDriverTechnology" will display either "FilterDriver" when the high performance Kernel mode driver is used or "SocketAPI" when the driver is not installed or available. The property is located under "System Settings -> GenTL" in interface layout "DeviceSpecific" or under "Image Settings -> Camera -> GenTL" in interface layout "GenICam".

Remove GigE Vision capture filter

To remove the GigE capture filter, please follow these instructions:

  1. Start the mvGigEConfigure by clicking the program in the start menu.
    The tool will start.
  2. Click on the "Remove driver" button.
    mvGigEConfigure will remove the driver automatically.

Command-line options

mvGigEConfigure offers a couple of command-line options to allow driver installation without the need of user interaction. The available command-line options are

Parameter Description
install Will install the driver if it can be located under
  • "%MVIMPACT_ACQUIRE_DIR%\KernelDrivers\mvGigECaptureDriver(x86)" for 32-bit versions of Windows Vista, 7, 8 and 8.1
  • "%MVIMPACT_ACQUIRE_DIR%\KernelDrivers\mvGigECaptureDriver(x86)(SHA256.EV)" for 32-bit versions of Windows 10
  • "%MVIMPACT_ACQUIRE_DIR%\KernelDrivers\mvGigECaptureDriver(x64)" for 64-bit versions of Windows Vista, 7, 8 and 8.1
  • "%MVIMPACT_ACQUIRE_DIR%\KernelDrivers\mvGigECaptureDriver(x64)(SHA256.EV)" for 64-bit versions of Windows 10
install_retry_count Defines the number of retry attempts for the driver installation. This can sometimes be useful when a network component is currently in use/shutting down. 45 seconds will be spent between 2 consecutive attempts. Currently this value will only have an effect, if specified BEFORE the 'install' parameter!
enable='index', all or allWithAtLeastOneDevice Will enable the driver for interface index, all interfaces or all interfaces that have at least on GigE Vision device connected to it.
disable='index' or all Will disable the driver for interface index or every interface.
remove Will remove the driver.
welcome Will display a welcome message to the user explaining what is about to happen.
postInstallMessage Will display a message to the user AFTER the filter driver has been installed on the system.
log_file='file_name' or lf='file_name' Will write the content of the output window of the application into a file. Passing 'STDLOGDIR' as the initial path (e.g. STDLOGDIR/file_name.log) will write the file into MVIMPACT_ACQUIRE_DATA_DIR/logs thus the file containing the regular mvIMPACT Acquire log-files as well.
quit Will automatically terminate the application once all the other command line parameters have been processed.

Sample (Windows)

So e.g. to automatically install the filter driver and terminate the application afterwards without any additional messages display to the user the following command line is needed:

mvGigEConfigure.exe install quit

This will install the filter driver, but will disable it on all the adapters and then will terminate automatically

mvGigEConfigure install disable=all quit

This will enable the filter driver on adapters 1 and 3

mvGigEConfigure enable=1 enable=3

This will be used during standard installation

mvGigEConfigure welcome install postinstallmessage



mvIPConfigure

mvIPConfigure is an interactive GUI tool to configure the network behaviour of GigE devices. With mvIPConfigure it is possible

  • to assign a user defined name to a GigE Vision™ compliant device,
  • to change its IP address behaviour, and
  • to find and fix incorrectly configured (e.g. wrong IP address) GigE Vision™ compliant devices.

The user can select, if the device should

  • use a persistent IP address (if supported by the device) or
  • use DHCP to obtain an IP address

LLA must always be enabled thus this control will never become modifiable in this GUI application.

Every GigE Vision™ compliant device must use the following IP protocol selection algorithm:

Figure 43: IP protocol selection sequence

Configure a GigE Vision device

To configure the GigE device, please follow these instructions:

Figure 44: mvIPConfigure - Start window
  1. Start the mvIPConfigure by clicking the program in the start menu.
    The tool will start.
  2. Select the device you want to configure from the list on left side of the tool.

  3. Click on the "Configure" button.
    Now every feature that is supported by the device and that can be modified will become enabled.

    Figure 45: mvIPConfigure - Device Properties

  4. When the device shall use a persistent IP address not only check the check box "Use Persistent IP" but also enter all the required information into the text control in the group box "Persistent IP address".
    Note
    In order that the camera is certainly detected in the network with the new IP address, please switch the camera off and on after you applied the changes in the next step.
  5. To write the changes to the device click on "Apply Changes" button. To discard the changes made in the GUI controls either close the application, select another device or click anywhere in the device list.
Note
If you use two GigE Vision cameras with two network adapters in one host device, please be sure that you use different subnets.

It is also possible to assign a temporary IP address to a certain device with a known MAC address via the "Action" menu item.

  1. Select the "Action" menu item and click on "Manually Assign Temporary IPv4 Address".

    Figure 46: mvIPConfigure - Action menu

    A dialog opens, where you can enter the network details.

    Figure 47: mvIPConfigure - Temporary IP dialog

  2. Click on "Execute" button.
    The device will now use this data until disconnected from its power supply or until it is assigned a new IP address.

Recover a incorrectly configured GigE Vision device

Because of the activated setting "Use Advanced Device Discovery", by default, incorrectly configured GigE Vision™ compliant devices will be listed within mvIPConfigure even if the IP address does not match the local network.

Figure 48: mvIPConfigure - Not properly configured device

Just select the device and configure it as described in the chapter above.



mvDeviceConfigure

mvDeviceConfigure is an interactive GUI tool to configure MATRIX VISION devices. It shows all connected devices. With mvDeviceConfigure it is possible e.g.

  • to check, if the camera is accessible on host PC,
  • to set the device ID,
  • to update firmware of the mvBlueLYNX-M7 or
  • to upload a GenICam XML file.

Using Linux, the tool is located in "~/mvimpact-acquire/apps/mvPropView/x86".

Note
If you want to run tools as root for achieving a better performance, you have to export following paths (this is done automatically for simple user): 
   export GENICAM_ROOT_V3_0=/home/x/tmp
   export GENICAM_LOG_CONFIG=/home/x/tmp/share/genicam/log/config/DefaultLogging.properties

or easier run shell script "genicam.sh" before: 
   . /etc/profile.d/genicam.sh

Various things can also be done without user interaction (e.g. updating the firmware of a device). To find out how to do this please start mvDeviceConfigure and have a look at the available command line options presented in the text window in the lower section (the text control) of the application.

How to set the device ID

Note
Currently you cannot set the device ID.

The device ID is used to identify the devices with a self defined ID. The default ID on the device's EEPROM is "0". If the user hasn't assigned unique device IDs to his devices, the serial number can be used to selected a certain device instead. However, certain third-party drivers and interface libraries might rely on these IDs to be set up in a certain way and in most of the cases this means, that each device needs to have a unique ID assigned and stored in the devices non-volatile memory. So after installing the device driver and connecting the devices setting up these IDs might be a good idea.

To set the ID please start the mvDeviceConfigure tool. You will see the following window:

Figure 48: mvDeviceConfigure - Overview devices

Whenever there is a device that shares its ID with at least one other device belonging to the same device family, mvDeviceConfigure will display a warning and the devices in red color.

Step 1: Device selection

Select the device you want to set up. Select the menu item Action and click on Set ID.

Note
It is also possible to select the action with a right click on the device.
Figure 49: mvDeviceConfigure - Select action

Step 2: Open dialog to set the ID

  • Enter the new ID and click OK.
  • Now the overview shows you the list with all devices as well as the new ID.

In case there has been an ID conflict before that has been resolved now mvDeviceConfigure will no longer highlight the conflict now.

How to update the firmware

With the mvDeviceConfigure tool it is also possible to update the firmware. In the device list, new firmware versions, if available, will be marked in blue.

Note
Since version 2.29.1 for GenICam compliant devices firmware updates will not be installed by the mvIMPACT Acquire driver installation package any more. Firmware archives can be downloaded from the MATRIX VISION website instead. The latest firmware (and previous versions) can always be found in the download area of the corresponding product. Downloaded archives should be copied into the /Firmware/<product name> folder as then mvDeviceConfigure will automatically check if your devices run with the latest firmware or not.

To update the firmware on a MATRIX VISION device, the following steps are necessary:

Step 1: Device selection

Select the device you want to set up. Select the menu item Action and click on Update firmware.

Note
It is also possible to select the action with a right click on the device.
Figure 50: mvDeviceConfigure - Select action

Step 2: Start firmware update

  • You have to close applications using the device and click Ok.
Figure 51: mvDeviceConfigure - Close all applications
  • You have to select the update file
    • mvBlueCOUGAR-S: mvBlueCOUGAR-S[MODELNAME]_Update.fpg
    • mvBlueCOUGAR-P: mvBlueCOUGAR-P_Update.tgz
    • mvBlueCOUGAR-X: mvBlueCOUGAR-X[MODELNAME]_Update.mvu
    • mvBlueLYNX-M7: mvBlueLYNX-M7_Update.tgz
  • Afterwards, you have to select the GenICam file that came with the firmware e.g. MATRIXVISION_mvBlueCOUGAR-[MODELNAME]_GigE_[VERSIONNUMBER].zip or MATRIXVISION_mvBlueFOX3_GigE_[VERSIONNUMBER].zip .
Figure 52: mvDeviceConfigure - Select firmware file
Warning
All current camera settings will be lost when updating the firmware. Network configuration settings (such as static IP settings etc.) on the other hand will not be affected. UserSet settings may or may not be lost, depending on whether the "Persistent UserSet Settings" parameter is set (this issue will be covered later in this chapter).
  • Confirm the firmware update.
Figure 53: mvDeviceConfigure - Confirm update
  • Afterwards, you will see a progress bar:
Figure 54: mvDeviceConfigure - Progress of firmware update

If the firmware update is successful, the dialog will disappear.

Note
The firmware update is only necessary in some special cases (e.g. to benefit from a new functionality added to the firmware, to fix a firmware related bug or to update the kernel driver). Before updating the firmware be sure what you are doing and have a look into the change log (versionInfo.txt and/or the manual to see if the update will fix your problem).
The firmware update takes several minutes and during this time the application will not respond!

Preserving UserSet settings when updating the Firmware

For devices that are capable of storing UserSet settings on the device itself (mvBlueCOUGAR-X/XD, mvBlueFOX3, etc.) these settings will by default be preserved during firmware updates since mvIMPACT Acquire 2.9.1. This may lead to slightly longer firmware update times. If UserSets are not used, and their persistence during firmware-updates is not desired, the "Persistent UserSet Settings" in the Settings Submenu can be unchecked:

Figure 58: mvDeviceConfigure - UserSet Persistence

This will also accellerate the firmware update process.

How to disable CPU sleep states a.k.a. C states (< Windows 8)

Modern PC's, notebook's, etc. try to save energy by using a smart power management. For this several hardware manufacturers specified the ACPI standard. The standard defines several power states. For example, if processor load is not needed the processor changes to a power saving (sleep) state automatically and vice versa. Every state change will stop the processor for microseconds. This time is enough to cause image error counts!

See also
More information about ACPI: http://en.wikipedia.org/wiki/Advanced_Configuration_and_Power_Interface

To disable the power management on the processor level (so-called "C states"), you can use mvDeviceConfigure:

Note
With Windows XP it is only possible to disable the C2 and C3 states. With Windows Vista / 7 all C states (1,2, and 3) will be disabled.
Warning
Please be sure you know what you do! To turn off the processor's sleep states will lead to a higher power consumption of your system.
Note
Modifying the sleep states using mvDeviceConfigure does only affects the current power scheme. For notebooks this will e.g. make a difference depending on whether the notebook is running on battery or not. E.g. if the sleep states have been disabled while running on battery and then the system is connected to an external power supply, the sleep states might be active again. Thus in order to permanently disable the sleep states, this needs to be done for all power schemes that will be used when operating devices.
  1. Start mvDeviceConfigure.
  2. Go to tab "Settings" and unselect "CPU Idle States Enabled".
Figure 56: mvDeviceConfigure - Settings

The sleep states can also be enabled or disabled from a script by calling mvDeviceConfigure like this:

mvDeviceConfigure.exe set_processor_idle_states=1 quit

or

mvDeviceConfigure.exe set_processor_idle_states=0 quit

The additional quit will result in the application to terminate after the new value has been applied.

Note
With Windows Vista or newer mvDeviceConfigure must be started from a command shell with administrator privileges in order to modify the processors sleep states.

Command-line options

It is possible to start mvDeviceConfigure via command line and controlling the starting behavior using parameters. The supported parameter are as follows:

Parameter Description
setid or id Updates the firmware of one or many devices(syntax: 'id=<serial>.<id>' or 'id=<product>.<id>').
set_processor_idle_states or spis Changes the C1, C2 and C3 states for ALL processors in the current system(syntax: 'spis=1' or 'spis=0').
set_userset_persistence or sup Sets the persistency of UserSet settings during firmware updates (syntax: 'sup=1' or 'sup=0').
update_fw or ufw Updates the firmware of one or many devices.
update_fw_file or ufwf Updates the firmware of one or many devices. Pass a full path to a text file that contains a serial number or a product type per line.
custom_genicam_file or cgf Specifies a custom GenICam file to be used to open devices for firmware updates. This can be useful when the actual XML on the device is damaged/invalid.
update_kd or ukd Updates the kernel driver of one or many devices.
ipv4_mask Specifies an IPv4 address mask to use as a filter for the selected update operations. Multiple masks can be passed here separated by semicolons.
fw_file Specifies a custom name for the firmware file to use.
fw_path Specifies a custom path for the firmware files.
log_file or lf Specifies a log file storing the content of this text control upon application shutdown.
quit or q Ends the application automatically after all updates have been applied.
force or f Forces a firmware update in unattended mode, even if it isn't a newer version.
* Can be used as a wildcard, devices will be searched by serial number AND by product. The application will first try to locate a device with a serial number matching the specified string and then (if no suitable device is found) a device with a matching product string.

The number of commands that can be passed to the application is not limited.

Sample (Windows)

mvDeviceConfigure ufw=BF000666

This will update the firmware of a mvBlueFOX with the serial number BF000666.

mvDeviceConfigure update_fw=BF*

This will update the firmware of ALL mvBlueFOX devices in the current system.

mvDeviceConfigure update_fw=mvBlueFOX-2* lf=output.txt quit

This will update the firmware of ALL mvBlueFOX-2 devices in the current system, then will store a log file of the executed operations and afterwards will terminate the application.

mvDeviceConfigure setid=BF000666.5

This will assign the device ID '5' to a mvBlueFOX with the serial number BF000666.

mvDeviceConfigure ufw=*

This will update the firmware of every device in the system.

mvDeviceConfigure ufw=BF000666 ufw=BF000667

This will update the firmware of 2 mvBlueFOX cameras.

mvDeviceConfigure ipv4_mask=169.254.*;192.168.100* update_fw=GX*

This will update the firmware of all mvBlueCOUGAR-X devices with a valid IPv4 address that starts with '169.254.' or '192.168.100.'.