mvIMPACT Acquire SDK GUI Applications
Basic Operation
Webcast
wxPropView - Working with wxPropView

Application Overview

wxPropView will start with the Quick Setup Wizard if a device with a suitable feature set has been selected and used:

wxPropView - Quick Setup Wizard Options

If supported the Quick Setup Wizard is the recommended way of capturing the first images. Later or when a third party device or a MATRIX VISION device without the feature required by this wizard is used when started the first time the application will look more or less like this:

wxPropView - Minimal Interface

On the left-hand side of the upper toolbar a drop down box will list all devices currently recognized by the mvIMPACT Acquire driver framework. If you find that a device is missing first make sure that you have it's driver package installed (e.g. by clicking on the "Info" button in the upper toolbar) and then make sure that the corresponding interface technology and the interface the device is connected to (e.g. a network card (NIC)) is enabled for enumeration. This can be seen by pressing the "Info" button in the upper toolbar. This would then open the Detailed Driver Information dialog.

To work with a device select it from the drop-down box and press the "Use" button.

Devices plugged into the system after the application has been started might not be listed until the "Update" button has been pressed. When this button is pressed every installed driver will rescan all interfaces for new devices so this will take some time.

In the middle of the upper toolbar various controls to either launch the Quick Setup Wizard or to start and stop the acquisition manually are located. In the right section of the upper toolbar recording of series of images into the RAM of the host computer can be configured. All these control will become available after a device has been initialised by pressing the "Use" button.

Enabling More Controls

Depending on your experience and/or needs you might want to see/do more than shown above. This can be achieved via the "Settings" menu:

wxPropView - Enhanced Interface
  • Selecting "Settings -> Property Grid -> Show Property Grid" will enable the The Property Grid displaying all device and driver features on the left side of the application
  • Enabling the "Show Left Tool Bar" option in the "Settings -> Options" dialog will add more tools to the far left side of the application

Enabling The Image Analysis Tools

Once the left toolbar is available there is more that can be activated. The most interesting feature is probably the Image Analysis tab control on the lower right of the application:

wxPropView - Enhanced Interface

The Big Picture

With all features enabled wxPropView then will look somewhat like this:

wxPropView - All Controls Enabled
  • "Menu Bar" for accessing various features not bound to any buttons or other controls
  • "Upper Tool Bar" for selecting and initializing devices, start/stop image acquisition, record/play back image sequences, launching the Quick Setup Wizard and the interface configuration dialog
  • "Left Tool Bar" to hide and show parts of the GUI and control various other settings
  • "Status Tool Bar" for displaying various statistical information
  • "Main Window" with
  • the Image Analysis area allowing to look at an image's histogram and various other things

Pressing F1 will open a HELP dialog also showing the Command-line Interface of the application.

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.

Note
USB3 Vision™ devices: Please have a look at the troubleshooting chapter of the mvBlueFOX 3 product manual if you neither see the mvBlueFOX3 nor cannot use it"

How To See The First Image

As described earlier, each device currently recognized will be listed 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 become enabled!

Note
"Frame grabber devices": Before you can capture data make sure that
  • a suitable camera has been connected to the grabber
  • the correct input channel has been selected
  • a suitable camera description (an XML file selected with the property "Image Settings -> Camera -> Type" in The Property Grid) has been selected. If you do not have an description, please have a look at Working With Camera Descriptions to see, how to generate one.

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
How to capture image data and configure a device from a custom application is described in great detail in the corresponding mvIMPACT Acquire API manuals for the programming language of your choice.
wxPropView - First image

Three different acquisition modes are available:

  • Continuous ("Live mode")
  • MultiFrame ("A sequence of defined length")
  • SingleFrame ("The acquisition of a single image")

The frame rate depends on

  • the camera or sensor in combination with the transmission technology,
  • the pixel clock of the sensor(defining the read-out speed of the device), and
  • the "Acquisition Frame Rate".

If you want to have a fixed frame rate using the "Continuous" mode, for some "GenICam" compliant devices the property "Setting -> Base -> Camera -> GenICam -> Acquisition Control -> Acquisition Frame Rate" will be supported

Alternatively, if you need frame rates below 5 fps, you can use Timers.

See also
Note
For color sensors, it is recommended to perform a white balance calibration now. This will improve the quality of the resulting images significantly.

Storing The Current Image

Since
mvIMPACT Acquire 2.37.0

To save an image directly from the live display directly, just

  1. Right-click on the display.
  2. Either select "Save Current Image" or "Copy Current Image To Clipboard".

With "Save Current Image" a dialog will appear, where you can specify the destination folder and the file format.

With "Copy Current Image To Clipboard" you can open you preferred image editing tool an paste the clipboard into it. For this functionality you can also use the shortcuts CTRL-C and CTRL-V.

wxPropView - Current image handling.

The Property Grid

The property grid on the left side of the application is the main way to modify driver and device behaviour. Properties displayed in light grey are read-only and cannot be modified by the user. Only the properties, which actually have an impact on the resulting image right now, will be visible. Therefore, certain properties might appear or disappear when modifying another properties.

The values of properties currently set to their default values will be displayed in a normal green font 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 a bold green font. It is possible that properties do already appear as being modified directly after opening a driver instance to it. In that case a previously stored setting has be found and loaded. See Storing, Restoring And Managing Settings for details.

User Experience

In the upper section of the property grid the "User Experience" can be selected. 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)

Find A Feature

Once a device has been opened and maybe after switching the User Experience to "Guru" there can easily be 500+ features into the feature tree of a single device instance. When not quite sure where to look the "Find Feature" option might come in handy:

wxPropView - Find Feature

This will open a flat list of all features currently available (even those currently invisible). While typing along the list is reduced to the features containing what has been typed so far.

wxPropView - Find Feature Dialog

Once the feature has been found a double-click on that feature will close the find dialog again an will expand the feature tree accordingly and will select the feature the user was looking for.

Detailed Feature Information

Right-clicking on a feature in the property grid will allow (among other things) to display the "Detailed Feature Information", displaying all sorts of information about a certain feature in a separate dialog:

wxPropView - Detailed feature information

For additional information about what all these data means please refer to the documentation of the objects derived from the Component class in the API manual of the programming language of your choice. Online versions of all these documents can be found here: https://www.matrix-vision.com/manuals/

Properties

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.

wxPropView - Restore 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:

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:

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:

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:

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:

wxPropView - After applying the value range to a property

Properties containing binary data will offer 2 additional options:

  • "Read File Into Property Value"
  • "Write Property Value To File"

Both might come in handy at some time. They allow to directly exchange the value of a property containing binary data with the hard disk.

Methods

Methods appear 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 specify a function returning an integer value and expecting a string and an integer as input parameters. To execute a method object either click on the little button with the 3 dots right of the methods parameter list or

  • right click on the name of a method and
  • select "Execute" from the popup menu:
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.

It is possible to execute methods either synchronously or asynchronously. This can be configured by using the Options dialog and is explained in the section Synchronous Method Execution.

Standard View and Developers View

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++, Java, .NET or Python 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.

wxPropView - Developers View

Callbacks

The property grid offers a way to get informed when properties change. This can be done by right-clicking on the desired feature and then select "Attach Callback" from the context menu. This can be done for as many features as desired.

wxPropView - Attach Callback

Now whenever one of these features change in any way (this includes not only a properties value but also e.g. it's visibility or access mode) a message will be written to the "Output" tab of the lower right analysis controls:

wxPropView - Callbacks have been fired

To detach/remove the callback again just right-click on the feature again and select "Detach Callback". This option will only be available if a callback is currently attached to the feature.

Importing And Exporting 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: "Action -> Load image...")
  • by dragging an image file onto an image display within wxPropView and the dropping it there
  • by starting wxPropView from the command line passing the file to open as a command line parameter (on 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.

wxPropView - Raw image file import

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.

wxPropView - Help menu

The options are to

  • directly open the logs folder, to
  • create a zip file with all the logs, and to
  • open the systems default email client to send an email to the MATRIX VISION Service Desk.

Linux

Since
mvIMPACT Acquire 2.24.0

You can access the log files in Linux via /opt/mvIMPACT_Acquire/data/logs .

You can also extract the directory using the following command

env | grep MVIMPACT_ACQUIRE_DATA_DIR

or change the directory directly via

cd $MVIMPACT_ACQUIRE_DATA_DIR/logs

For older versions:

Like on Windows, log files will be generated, if the activation flag for logging called mvDebugFlags.mvd is available in the same folder as the application (however, using Windows log files will be generated automatically, because the applications are started from the same folder). By default, on Linux the mvDebugFlags.mvd will be installed in the installation's destination folder in the sub-folder "apps". For example, if the destination folder was "/home/workspace", you can locate the mvDebugFlags.mvd like the following way:

user@linux-desktop:~$
// <- Starting the console window, you will be in the home directory: /home/
user@linux-desktop:~$ cd workspace/apps/
// <- Change the directory
user@linux-desktop:/home/workspace/apps$ ls -l
// <- List the directory
insgesamt 144
drwxr-xr-x  9 user user  4096 Mai 21 15:08 Callback
drwxr-xr-x  8 user user  4096 Mai 21 15:08 Callback_C
drwxr-xr-x  9 user user  4096 Mai 21 15:08 CaptureToUserMemory_C
drwxr-xr-x  3 user user  4096 Mai 21 15:03 Common
drwxr-xr-x 11 user user  4096 Mai 21 15:09 ContinuousCapture
drwxr-xr-x  9 user user  4096 Mai 21 15:09 ContinuousCaptureAllDevices
drwxr-xr-x  6 user user  4096 Mai 21 15:09 ContinuousCaptureFLTK
drwxr-xr-x  9 user user  4096 Mai 21 15:09 ContinuousCapture_C
drwxr-xr-x 11 user user  4096 Mai 21 15:09 DigitalIOs
drwxr-xr-x  9 user user  4096 Mai 21 15:09 FirmwareUpgrade
drwxr-xr-x 11 user user  4096 Mai 21 15:09 GenericInterfaceLayout
drwxr-xr-x 11 user user  4096 Mai 21 15:09 GenICamInterfaceLayout
-rw-r--r--  1 user user   854 Mai 21 15:03 Makefile
-rw-r--r--  1 user user  7365 Mai 21 15:03 Makefile.samp.inc
-rw-r--r--  1 user user 20713 Mai 21 15:03 mvDebugFlags.mvd
// <- Log activation flag
drwxr-xr-x  7 user user  4096 Mai 21 15:09 mvDeviceConfigure
drwxr-xr-x  6 user user  4096 Mai 21 15:10 mvIPConfigure
drwxr-xr-x  6 user user  4096 Mai 21 15:11 mvPropView
drwxr-xr-x  9 user user  4096 Mai 21 15:11 SingleCapture
drwxr-xr-x  9 user user  4096 Mai 21 15:11 SingleCaptureStorage

For log file generation you have to execute your app from the folder where mvDebugFlags.mvd is located. E.g. if you want to start wxPropView:

user@linux-desktop:/home/workspace/apps$ ./mvPropView/x86/wxPropView
// <- Start the executable from the folder, where \b mvDebugFlags.mvd is located.

Another possibility would be, to copy the mvDebugFlags.mvd file to the folder of the executable:

user@linux-desktop:/home/workspace/apps$ cp mvDebugFlags.mvd ./mvPropView/x86/wxPropView
// <- Copy the log activation flag
user@linux-desktop:/home/workspace/apps$ cd ./mvPropView/x86/
// <- Change the directory
user@linux-desktop:/home/workspace/apps/mvPropView/x86/$ ./wxPropView
// <- Start the executable

Afterwards, several log files are generated which are listed in files.mvloglist. The log files have the file extension .mvlog. Please send these files to our support team.