VCD Properties provide a generic, hardware independent and extendable way to control the settings of a video capture device.
DirectShow defines two sub sets of properties for video capture devices: VideoProcAmp and CameraControl. There is only one scalar data type ( long ) defined to represent a property value. Although this concept is an abstraction that allows you to write device independent code, there are two problems:
On one hand, the new VCD properties provide interfaces that allow property values to manipulated in terms of physical dimensions, such as seconds. On the other hand, these interfaces provide high precision. For all who are happy with the simple and somehow restricted way of accessing properties provided by earlier versions of IC Imaging Control, there is a helper class called VCDSimpleProperty. This class allow old code to be ported with minimum effort. If this class is used, the benefits of the new VCD properties are not available.
VCD properties are organized in a tree structure. In order to understand this, we have to consider the elements of which a property consists. First of all, a property has a name, such as "exposure". In addition, it contains elements, such as the value and an automation state. Therefore, we may say that a property is an object that contains a name and a set of elements. This object is called VCDPropertyItem. The elements are called VCDPropertyElement and contain a set of interfaces that allow to manipulate the element. The interfaces provide different access methods to the property. The interface VCDRangeProperty, for example, provides access to the property that is equivalent to the property access of DirectShow. The VCDAbsoluteValueProperty allows the property to be accessed in terms of a physical dimension with high accuracy. After this consideration, the structure of VCD property is clear: The property item contains property elements, which contain one or more interfaces. In order to be able to manipulate a property, you have to retrieve the appropriate item, element and interface. Please open the application "VCD Property Inspector" from the IC Imaging Control start menu entry, in order to get an idea on how the VCD properties are organized for your device.
First of all, we need a way to specify a property item, element or interface in order to be able to find it. There are GUIDs (Global Unique IDentifiers) for every property item, element and interface defined in the module VCDPropertyIDs. These GUIDs should be used in the VCD property's find methods. All property items that are supported by the currently active video capture device are contained in the VCDPropertyItems collection. This collection provides methods for retrieving a property item, element or interface. They are called VCDPropertyItems.FindItem, VCDPropertyItems.FindElement and VCDPropertyItems.FindInterface. The object to be retrieved has to specified by a single GUID for FindItem and a combination of GUIDs for the other two. In the following, we will call the GUID or combination of GUIDs that specifiy a property object, a GUID path.
As described earlier, an interface is the object that actually allows data to be read from and written to a property. As described in the previous section, we use the GUID path for the desired interface as a parameter to VCDPropertyItems.FindInterface in order to retrieve the interface. Before we do this, we will have to decide which interface we want to use. In case of an auto item ( VCDPropertyElement, GUID: VCDElement_Auto) we will try to retrieve a switch interface ( VCDSwitchProperty, GUID: VCDInterface_Switch) because a switch is the expected functionality of the auto item. In case of the value item - the actual value of the property - we have to search for the best interface. The best or most advanced interface is the absolute value interface ( refer to VCDAbsoluteValueProperty for details).
As described at the beginning, the absolute values interface provide high accuracy and a meaning of the value it represents. The following code retrieves the absolute value interface for the value element of the exposure property item:
' Declare an absolute value interface Dim AbsValItf As VCDAbsoluteValueProperty ' Retrieve an absolute value interface for exposure Set AbsValItf = ICImagingControl1.VCDPropertyItems.FindInterface( VCDID_Exposure + ":" +_ VCDElement_Value + ":" + _ VCDInterface_AbsoluteValue ) If Not AbsValItf Is Nothing Then ' Interface successfully retrieved ... Else ' There is no absolute value interface for the value element ' of the exposure property item. End If
If the absolute values interface does not exist for this property, we try to retrieve the map strings interface ( VCDMapStringsProperty, GUID: VCDInterface_MapStrings). It is not as accurate as the absolute values interface, but it provides a meaning for the value. The following code retrieves the map strings interface for the value element of the exposure property item:
' Declare a map strings interface Dim MapStringsItf As VCDMapStringsProperty ' Retrieve a map strings interface for exposure Set MapStringsItf = ICImagingControl1.VCDPropertyItems.FindInterface( VCDID_Exposure + ":" + _ VCDElement_Value + ":" + _ VCDInterface_MapStrings ) If Not MapStringsItf Is Nothing Then ' Interface successfully retrieved ... Else ' There is no map strings interface for the value element ' of the exposure property item. End If
If the map strings interface does not exist for this property, we try to retrieve the range interface ( VCDRangeProperty, GUID: VCDInterface_Range). This interface does not provide a meaning for the value, but it may provide more values than the map strings interface. The following code retrieves the range interface for the value element of the exposure property item:
' Declare a range interface Dim RangeItf As VCDRangeProperty ' Retrieve a range interface for exposure Set RangeItf = ICImagingControl1.VCDPropertyItems.FindInterface( VCDID_Exposure + ":" + _ VCDElement_Value + ":" + _ VCDInterface_Range ) If Not RangeItf Is Nothing Then ' Interface successfully retrieved ... Else ' There is no range interface for the value element ' of the exposure property item. End If
In the previous section we learned how to get an interface. Now we will discuss how use them in order to get information about the property and manipulate the value. All interfaces provide the following properties:
The absolute values and the range interface provide properties to get information about the minimum, maximum value that can be assigned to the actual value. The absolute values interface provides additional information about the physical dimension of the value. The map strings interface provides a collection of strings, which build the set of possible values that may be assigned to the actual value.
If the absolute values interface could be retrieved, the code for accessing the interface looks as follows:
' AbsValItf is a valid absolute value interface for exposure If AbsValItf.Available Then ' Set the current value to the average AbsValItf.Value = ( AbsValItf.RangeMin + AbsValItf.RangeMax ) / 2 End If
If the map strings interface could be retrieved, the code for accessing the interface looks as follows:
' MapStringsItf is a valid map string interface for exposure If MapStringsItf.Available Then ' Set the current value to the average MapStringsItf.Value = ( MapStringsItf.RangeMin + MapStringsItf.RangeMax ) / 2 End If
If only the range interface could be retrieved, the code for accessing the interface looks as follows:
' RangeItf is a valid range interface for exposure If RangeItf.Available Then ' Set the current value to the average RangeItf.Value = ( RangeItf.RangeMin + RangeItf.RangeMax ) / 2 End If
The VCDPropertyItems collection provides a method called VCDPropertyItems.Save that serializes the current state of all VCD properties of the currently selected device into a string. The property values are stored in XML format. Therefore, it is easy to store the string in the registry or a file for later restore operations. Please note that the XML representation is not documented and may change without notice. The method for restoring all property values is called VCDPropertyItems.Load.
Established in 1990, The Imaging Source is one of the leading manufacturers of industrial cameras, frame grabbers and video converters for production automation, quality assurance, logistics, medicine, science and security.
Our comprehensive range of cameras with USB 3.1, USB 3.0, USB 2.0, GigE interfaces and other innovative machine vision products are renowned for their high quality and ability to meet the performance requirements of demanding applications.