MATRIX VISION - mvBlueFOX Technical Documentation
Application Usage

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).
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 mvBlueFOX 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

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 4: 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 5: 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 6: 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 7: 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 8: 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")
Note
With "Action -> Capture Settings -> Manage..." you can delete the settings which were saved on the system.
Figure 9: 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 10: 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 11: 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 12: 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 13: 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 14: 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 15: 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 16: 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 17: 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 18: 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 19: 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".

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 20: wxPropView - Create capture setting



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

    Figure 21: wxPropView - Create capture setting - Choosing name



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

    Figure 22: 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 23: 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 24: wxPropView - Assigning displays
Figure 25: 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 26: 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 27: 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 28: 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 29: 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 30: 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 31: 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 32: 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.

Different interface layouts

 

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.

White balance of a camera device (color version)

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

Figure 33: 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 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:

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

Figure 35: 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:

Figure 36: wxPropView - White balance summary

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

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
  • CameraSettingsBlueFOX

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 37: wxPropView - Call refresh

Setting up external trigger and flash control

To set up external trigger and flash control, following things are required:

  • mvBlueFOX with CCD sensor
  • Host PC with USB 2.0 interface
  • USB 2.0 cable with max. 5m
  • Cable for supplying external trigger signal to camera
  • Flash with needed cable and power supply
  • Current mvBlueFOX driver

The camera is only connected by USB 2.0 cable to PC. All other signals are connected directly to the camera. Trigger and flash signals are directly controlled by the FPGA, which does the timing in the camera. This makes the trigger and flash control independent from CPU load of host PC or temporary USB 2.0 interrupts.

Figure 38: mvBlueFOX with trigger and flash

Trigger control
External trigger signal resets the image acquisition asynchronously to any other timing so that reaction delay is such short that it can be ignored. If a delay between trigger signal and starting integration is needed, it can be defined. By default it is set to 0 us.

Flash control
Signal for flash control is immediately set as soon as image integration begins. If a delay is needed it can be defined. By default this delay is set to 0.

Connection

External trigger signal
Signal for triggering image acquisition must be connected to digital input on backside of mvBlueFOX on D-Sub 9-pin connector. You can choose either input IN0 (pin 6 and 1) or IN1 (pin 9 and 4) for triggering.

Figure 39: External trigger signal

Schematic shows how to fit application's switch to camera's digital input. External trigger signal must be in following conditions:

  • TTL (5 V): High min. 3 V, Low max. 1 V
  • PLC (24 V): High min. 12 V, Low max. 10 V

Application's switch can be a mechanical one any light barrier or some kind of encounter.

Note
Depending on used switch it might be necessary to use a pull-up or pull-down resistor so that camera input can recognize signal correctly.
See also
Characteristics of the digital inputs

To test the general trigger functionality, please follow these steps:

  1. Select the "Acquisition Mode" "Continuous".
  2. Click on "Acquire".
  3. Set the "TriggerMode" to "OnHighLevel".
  4. Set the "TriggerMode" to "DigitalInputThreshold" to e.g. 2V.
  5. Connect a standard power supply with e.g. 5 V (higher than the value of "DigitalInputThreshold") to pin 1 (-) and pin 6 (+)

As long as the power supply is connected, you can see a live preview. If you disconnect the power supply the live preview should stop. If this is working the trigger input works.

Figure 40: Settings to test the general trigger functionality

External flash signal
For supplying flash with control signal use any digital output Out0 (pin 7 and 2) or Out1 (pin 8 and 3) on 9 pin D-Sub connector.

Figure 41: External flash signal

If current needed for flash is below 100 mA you can connect flash directly to camera outputs. If it is higher, you have to use an additional driver for controlling the flash, which provides the higher current.

Note
Depending on used flash driver it could be necessary to use pull-up or pull-down resistors so that driver can recognize the signal correctly.
See also
Characteristics of the digital outputs

Setting up

In wxPropView you can open camera and display acquired images.

By default camera is running free. This means, it uses its own timing depending on set pixel clock, exposure time and shutter mode.

Trigger
To let the camera acquire images only with an external trigger signal you must change the "TriggerMode" to the mode suitable to your application:

Figure 42: TriggerMode
Mode Description
ContinuousFree running, no external trigger signal needed.
OnDemandImage acquisition triggered by command (software trigger).
OnLowLevelAs long as trigger signal is Low camera acquires images with own timing.
OnHighLevelAs long as trigger signal is High camera acquires images with own timing.
OnFallingEdgeEach falling edge of trigger signal acquires one image.
OnRisingEdgeEach rising edge of trigger signal acquires one image.
OnHighExposeEach rising edge of trigger signal acquires one image, exposure time corresponds to pulse width.
OnLowExposeEach falling edge of trigger signal acquires one image, exposure time corresponds to pulse width.
OnAnyEdgeStart the exposure of a frame when the trigger input level changes from high to low or from low to high.

Now, define on which pin the trigger signal is connected to.

Figure 43: TriggerSource

Choose either "DigIn0" if signal is connected to "IN0" or DigIn1 if signal is connected to IN1. In general entry "RTCtrl" is not useful in this case because triggering would be controlled by Hardware Real-Time Controller which is not described here and also not necessary.

Depending on voltage level you are using for trigger signal you must choose the "DigitalInputThreshold":

Figure 44: DigitalInputThreshold

In case of TTL choose 2V and in case of PLC choose 10V.

Now, the image acquisition runs corresponding to external trigger signal and trigger mode. You will see the acquired images on the left part of the window. Preview will be updated in frequency of external trigger.

The program knows a timeout period within at least one trigger signal must be provided to the camera. If no trigger signal comes within this time, no image is acquired and an error is set (error count increases). So be sure to set this timeout period to a value, which is long enough to receive at least one trigger signal. You can set this value in "ImageRequestTimeout" property:

Figure 45: ImageRequestTimeout

Trigger
To activate flash control signal set "FlashMode" to the output you connected flash or flash driver to:

Figure 46: External flash signal

Since this mode is activated each image acquisition will generate the flash signal. This generation is independent from used trigger mode. Flash signal is directly derived from integration timing.

This means that if no "FlashToExposedToLightDelay" is set flash signal will rise as soon as integration starts and fall when integration is finished. The pulse width cannot be changed. So you can be sure that integration takes place when trigger signal is high.

Working with the hardware Look-Up-Table (LUT)

There are two parameters which handles the pixel formats of the camera:

  • "Setting -> Camera -> PixelFormat" defines the pixel format used to transfer the image data into the target systems host memory.
  • "Setting -> ImageDestination -> PixelFormat" defines the pixel format of the resulting image (which is kept in the memory by the driver).

If both formats are set to "Auto", 8 bit will be used.

If you set "LUTImplementation" to "Software" in "Setting -> ImageProcessing -> LUTOperations", the hardware Look-Up-Table (LUT) will work with 8 bit data ("LUTMappingSoftware = 8To8"). Using Gamma functions you will see gaps in the histogram:

Figure 47: 8to8 software LUT leads to gaps in the histogram using gamma functions (screenshot: mvBlueFOX-MLC)

If you set "LUTImplementation" to "Hardware" in "Setting -> ImageProcessing -> LUTOperations", the hardware Look-Up-Table (LUT) will work with 10 bit data inside the camera and converts the data to 8 bit for output ("LUTMappingHardware = 10To8"). Now, there will be no gaps in the histogram:

Figure 48: 10to8 hardware LUT shows no in the histogram (screenshot: mvBlueFOX-MLC)

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.



mvDeviceConfigure

mvDeviceConfigure is an interactive GUI tool to configure MATRIX VISION devices. It shows all connected devices.

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

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 47: 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 like in the following image, showing in this example two mvBlueFOX cameras with an ID conflict:

Figure 48: mvDeviceConfigure - Conflicting device IDs

Step 1: Device Selection

Select the device you want to set up from the list box.

Step 2: Open dialog to set the ID

With the device selected, 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 3: Assign the new ID

Enter the new ID and click OK.

Figure 50: mvDeviceConfigure - New ID

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:

Figure 51: mvDeviceConfigure - Resolved ID conflict

How to update the firmware

With the mvDeviceConfigure tool it is also possible to update the firmware. These steps are necessary:

Step 1: Device selection

Select the device you want to update from the list box.

Step 2: Open dialog to update the firmware

With the device selected, 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 52: mvDeviceConfigure - Select action

Step 3: Confirm the firmware update

You have to confirm the update.

Figure 53: mvDeviceConfigure - Confirm update
Note
The firmware is compiled within the installed driver. The mvDeviceConfigure uses this version and updates the firmware. If you use an old driver, you will downgrade the firmware.

If the firmware update is successful, you will receive the following message:

Figure 54: mvDeviceConfigure - Update successful

Step 4: Disconnect and reconnect the device

Please disconnect and reconnect the device to activate the new firmware.

Note
The firmware update is only necessary in some special cases (e.g. to benefit from a new functionality added to the firmware or to fix a firmware related bug). 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 approx. 30 seconds!

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 informations 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 / 8 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. Some processor vendors might state that turning off the sleep states will result in the processors warranty will expire.
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 55: 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.'.