MATRIX VISION - mvBlueFOX3 Technical Documentation
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
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.
The Quick Setup Wizard is a tiny and powerful single window configuration tool to optimize the image quality automatically or to set the most important parameters, which affect the image quality, in an easy way manually:
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
"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
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.
There are 3 presets:
Factory can be used as a fall back to quickly skip or remove all presets and load the factory default settings.
All auto modes can be switched off and all settings, such as Gain, Exposure etc. can be subsequently modified by using:
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.
Gain settings also combine analog and digital registers into one slider setting.
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.
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.
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.
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.
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.
wxPropView consists of several areas:
By clicking on F1 you will get the HELP dialog.
Now, you can initialize a device by
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:
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.
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.
Settings can be stored in several ways (via the "Menu Bar": "Action -> Capture Settings -> Save"):
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 can decide to
|mvIMPACT Acquire Version||Loading a XML settings file created with mvIMPACT Acquire version < 2.9.0||Loading a XML settings file created with mvIMPACT Acquire version 2.9.0 - 2.10.1||Loading a XML settings file created with mvIMPACT Acquire version 2.11.0 or later|
|2.9.0 - 2.10.1||YES||YES||NO|
Productinside 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.
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
To restore the default value for a complete list (which might include sub-lists)
In this case a popup window will be opened and you have to confirm again.
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:
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:
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:
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
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.
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™.
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:
"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.
wxPropView is capable of
This will result in 1 display in horizontal direction and 2 in vertical direction.
Is is also possible to change the amount of display at runtime via "Settings -> Image Displays -> Configure Image Display Count":
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".
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.
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:
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.
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.
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.
The options are to
It is possible to start wxPropView via command line and controlling the starting behavior using parameters. The supported parameter are as follows:
|Defines the startup width of wxPropView. Example: |
|Defines the startup height of wxPropView. Example: |
|Defines the startup x position of wxPropView.|
|Defines the startup x position of wxPropView.|
|Defines the startup ratio of the position of the property grids splitter. Values between > 0 and < 1 are valid. Example: splitterRatio=0.5|
|Defines the startup width of the property grid.|
|Will display debug information in the property grid.|
|Will display invisible (currently shadowed) components in the property grid.|
|Defines the number of images displayed in horizontal direction.|
|Defines the number of images displayed in vertical direction.|
|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): |
|Will directly open a device with a particular serial number. * will take the first device. Example: |
|Will forcefully hide or show the Quick Setup Wizard, regardless of the default settings. Example (Quick Setup Wizard will be shown): |
|Will directly start live acquisition from the device opened via |
This will start the first available device, will hide the Quick Setup Wizard, and will display the complete property tree.
As described above, after the device has been initialized successfully in the "Grid" area of the GUI the available "interface layout" properties are displayed in a hierarchy tree. GenICam is the default interface layout of the mvBlueFOX3 and we recommend to use it!
The next chapter will show how to set the interface layout and which interface you should use according to your needs.
You can change the property interfaceLayout with wxPropView to select the preferred interface.
To specify the InterfaceLayout for all devices globally, you can do this via the "Action -> Default Device Interface Layout" in the "Menu Bar":
If you want to specify the InterfaceLayout for the used device, you can do this via "Device Properties" in the section
"Device -> InterfaceLayout":
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:
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.
Now, you can capture an image ("Acquisition Mode": "SingleFrame") or display live images ("Continuous"). Just
Three different acquisition modes are available:
The frame rate depends on
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. In the use case Creating synchronized acquisitions using timers, for example, a frame rate of 1 fps is generated.
It is also possible to record image sequences using wxPropView.
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.
Start the wxPropView and initialize the device by clicking "Use" and start a "Continuous" acquisition.
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.
To configure a device for a triggered acquisition, in wxPropView the property "Setting -> Base -> Camera -> GenICam -> Acquisition Control -> Trigger Selector" is available.
All trigger modes are defined by an enumeration:
There is also a chapter "Getting a triggered image" chapter, which is available in the "mvIMPACT Acquire API" manuals.
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.
Some devices might also offer an event notification if a certain digital input changed its state. This event can then be enabled
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.
The mvBlueFOX3 camera offers the possibility, to save up to 4 user sets in the camera's flash memory directly. This means that all camera specific settings you've adjusted via wxPropView can be saved in a non-volatile memory.
Example: You have connected a flash via exposure out of the camera and you want to avoid an overload of the flash by maloperation, you can save a suitable shutter time, with which the camera will start.
To save your specific settings, set you properties in the "Setting -> Camera -> GenICam" section of wxPropView. Then, select in "User Set Control" your user set with the "User Set Selector", for example "UserSet1". Afterwards, save the user set with "int UserSetSave()". Finally, if you want that the camera starts with a specific user set (after power up), you have to select it with the "User Set Default Selector".
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.
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.
To update the firmware on a MATRIX VISION device, the following steps are necessary:
Select the device you want to set up. Select the menu item Action and click on Update firmware.
If the firmware update is successful, you will receive the following message:
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:
This will also accellerate the firmware update process.
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!
To disable the power management on the processor level (so-called "C states"), you can use mvDeviceConfigure:
"CPU Idle States Enabled".
The sleep states can also be enabled or disabled from a script by calling mvDeviceConfigure like this:
quit will result in the application to terminate after the new value has been applied.