Using the VCD Simple Property Class

Up to the version 1.41 of IC Imaging Control, the properties of a device could be accessed using the properties %%Auto, %%AutoAvailable, %%Available, %%Default and %%Range. These properties have been depreciated as of version 2.0. The new VCD properties allow more detailed and generic access to the device's properties but require a little more code to be written. If you are happy with the old properties, a new helper class is introduced in version 2.0 that provides access methods to the VCD properties, which are similar to the old way. This chapter shows you how to use this helper class.

Setting up the Project

The source code for the VB.NET and C# versions of this sample program can be found in the directories samples\VB71\VCD Simple Property, samples\C#\VCD Simple Property.

Create a new project and add IC Imaging Control to the form. Before you run the program, select the video device, input and video format as shown in the First Steps Visual Studio .NET 7.1 chapter. Alternatively, run the program without selecting a device. In this case, the program shows the device selection dialog provided by IC Imaging Control. If you close this dialog without having made a selection, the program will display an error message and terminate.

Accessing a Property

First, we add some controls to the form. They will allow us to manipulate a device property. Add a track bar, a label and a check box to the form. Name the track bar WhiteBalanceTrackBar, the label WhiteBalanceValueLabel and the check box WhiteBalanceAutoCheckBox. These controls will be used to manipulate the "WhiteBalance" property of a device.

Of course we need an instance of the helper class in order to use it. Therefore, add a global variable:

[VB.NET]
Private VCDProp As TIS.Imaging.VCDHelpers.VCDSimpleProperty

[C#]
TIS.Imaging.VCDHelpers.VCDSimpleProperty VCDProp;

The helper class and the controls are initialized in the Form_Load event, so add a Form_Load and insert the following code:

[VB.NET]
' If no device has not yet been selected, show the device selection dialog.
If Not IcImagingControl1.DeviceValid Then
    IcImagingControl1.ShowDeviceSettingsDialog()
 
    If Not IcImagingControl1.DeviceValid Then
        MsgBox("No device was selected.", MsgBoxStyle.Information, "VCD Simple Property")
        Me.Close()
        Exit Sub
    End If
End If
 
' Initialize the VCDProp class to access the properties of our ICImagingControl object.
VCDProp = VCDSimpleModule.GetSimplePropertyContainer(IcImagingControl1.VCDPropertyItems)
 
' Initialize the auto checkbox.
If Not VCDProp.AutoAvailable(VCDIDs.VCDID_WhiteBalance) Then
    WhiteBalanceAutoCheckBox.Enabled = False
Else
    VCDProp.Automation(VCDIDs.VCDID_WhiteBalance) = False
End If
 
' Initialize the track bars.
If Not VCDProp.Available(VCDIDs.VCDID_WhiteBalance) Then
    WhiteBalanceTrackBar.Enabled = False
Else
    WhiteBalanceTrackBar.Enabled = True
    WhiteBalanceTrackBar.Minimum = VCDProp.RangeMin(VCDIDs.VCDID_WhiteBalance)
    WhiteBalanceTrackBar.Maximum = VCDProp.RangeMax(VCDIDs.VCDID_WhiteBalance)
    WhiteBalanceTrackBar.Value = VCDProp.RangeValue(VCDIDs.VCDID_WhiteBalance)
    WhiteBalanceTrackBar.TickFrequency = (WhiteBalanceTrackBar.Maximum - WhiteBalanceTrackBar.Minimum) / 10
    WhiteBalanceValueLabel.Text = WhiteBalanceTrackBar.Value
End If
 
' Start live mode.
IcImagingControl1.LiveStart()

[C#]
// If no device has been selected, show the device selection dialog.
if( !ICImagingControl1.DeviceValid )
{
    ICImagingControl1.ShowDeviceSettingsDialog();
 
    if( !ICImagingControl1.DeviceValid )
    {
        MessageBox.Show("No device was selected.");
        this.Close();
        return;
    }
}
 
// Initialize the VCDProp class to access the properties of our ICImagingControl object.
VCDProp = VCDSimpleModule.GetSimplePropertyContainer(ICImagingControl1.VCDPropertyItems);
 
// Initialize the auto checkbox.
if( !VCDProp.AutoAvailable(VCDIDs.VCDID_WhiteBalance) )
{
    WhiteBalanceAutoCheckBox.Enabled = false;
}
else
{
    VCDProp.Automation[VCDIDs.VCDID_WhiteBalance] = false;
}
 
// Initialize the trackbars.
if( !VCDProp.Available(VCDIDs.VCDID_WhiteBalance) )
{
    WhiteBalanceTrackBar.Enabled = false;
}
else
{
    WhiteBalanceTrackBar.Enabled = true;
    WhiteBalanceTrackBar.Minimum = VCDProp.RangeMin(VCDIDs.VCDID_WhiteBalance);
    WhiteBalanceTrackBar.Maximum = VCDProp.RangeMax(VCDIDs.VCDID_WhiteBalance);
    WhiteBalanceTrackBar.Value = VCDProp.RangeValue[VCDIDs.VCDID_WhiteBalance];
    WhiteBalanceTrackBar.TickFrequency = (WhiteBalanceTrackBar.Maximum - WhiteBalanceTrackBar.Minimum) / 10;
    WhiteBalanceValueLabel.Text = WhiteBalanceTrackBar.Value.ToString();
}
 
// Start live mode.
ICImagingControl1.LiveStart();

To add functionality to the controls, add a Scroll event for the track bar and a CheckedChanged event for the check box. If these events are called, the "WhiteBalance" property is updated appropriately. The following code will do this:

[VB.NET]
Private Sub WhiteBalanceTrackBar_Scroll(ByVal sender As Object, ByVal e As System.EventArgs) Handles WhiteBalanceTrackBar.Scroll
    ' Set the value for the WhiteBalance.
    VCDProp.RangeValue(VCDIDs.VCDID_WhiteBalance) = WhiteBalanceTrackBar.Value
 
    ' Display the current value for the WhiteBalance.
    WhiteBalanceValueLabel.Text = VCDProp.RangeValue(VCDIDs.VCDID_WhiteBalance)
End Sub

[C#]
private void WhiteBalanceTrackBar_Scroll(object sender, System.EventArgs e)
{
    // Set the value for WhiteBalance.
    VCDProp.RangeValue[VCDIDs.VCDID_WhiteBalance] = WhiteBalanceTrackBar.Value;
 
    // Display the current value for WhiteBalance.
    WhiteBalanceValueLabel.Text = VCDProp.RangeValue[VCDIDs.VCDID_WhiteBalance].ToString();    
}

[VB.NET]
Private Sub WhiteBalanceAutoCheckBox_CheckedChanged(ByVal sender As System.Object, ByVal e As System.EventArgs) Handles WhiteBalanceAutoCheckBox.CheckedChanged
    If WhiteBalanceAutoCheckBox.Checked Then
        VCDProp.Automation(VCDIDs.VCDID_WhiteBalance) = True
        WhiteBalanceTrackBar.Enabled = False
    Else
        VCDProp.Automation(VCDIDs.VCDID_WhiteBalance) = False
        WhiteBalanceTrackBar.Enabled = True
    End If
End Sub

[C#]
private void WhiteBalanceAutoCheckBox_CheckedChanged(object sender, System.EventArgs e)
{
    if( WhiteBalanceAutoCheckBox.Checked )
    {
        VCDProp.Automation[VCDIDs.VCDID_WhiteBalance] = true;
        WhiteBalanceTrackBar.Enabled = false;
    }
    else
    {
        VCDProp.Automation[VCDIDs.VCDID_WhiteBalance] = false;
        WhiteBalanceTrackBar.Enabled = true;
    }
}

Accessing advanced Properties

There are some properties that allow a more detailed access than the one described above. In case of "WhiteBalance" it is possible to specify a value for red and blue and to perform an automatic adjustment for a limited time called one push. These advanced properties can be accessed using the following IDs: VCDElement_WhiteBalanceBlue and VCDElement_WhiteBalanceRed. The "One Push" operation is triggered by calling the VCDSimpleProperty.OnePush method with either VCDID_WhiteBalance, VCDElement_WhiteBalanceBlue or VCDElement_WhiteBalanceRed as a parameter.

The following sample shows you how to access "WhiteBalanceBlue" and "WhiteBalanceRed" property. It will also access the "Brightness" property to show the difference between the standard property and the advanced way.

After setting up the project as described in the "Setting up the Project" section of this document, add some controls to the form. Add 3 track bars and name them BrightnessTrackBar, WhiteBalanceBlueTrackBar and WhiteBalanceRedTrackBar. Now add 2 check boxes. Label them Auto and name them BrightnessAutoCheckBox and WhiteBalanceAutoCheckBox respectively. Finally add a button to the form and name it WhiteBalanceOnePushButton. Label the button One Push.

Now add an instance of the helper class to your code:

[VB.NET]
Private VCDProp As TIS.Imaging.VCDHelpers.VCDSimpleProperty

[C#]
TIS.Imaging.VCDHelpers.VCDSimpleProperty VCDProp;

The helper class and the controls are initialized in the Form_Load event. Add a Form_Load event and insert the following code:

[VB.NET]
Private Sub VCDSimplePropertyForm_Load(ByVal sender As System.Object, ByVal e As System.EventArgs) Handles MyBase.Load
 
    ' If no device is selected yet, show the selection dialog
    If Not ICImagingControl1.DeviceValid Then
        ICImagingControl1.ShowDeviceSettingsDialog()
 
        If Not ICImagingControl1.DeviceValid Then
            MsgBox("No device was selected.", MsgBoxStyle.Information, "VCD Simple Property")
 
            Me.Close()
            Exit Sub
        End If
    End If
 
    ' Initialize the VCDProp class to access the properties of our ICImagingControl
    ' object
    VCDProp = TIS.Imaging.VCDHelpers.VCDSimpleModule.GetSimplePropertyContainer(IcImagingControl1.VCDPropertyItems)
 
    ' Initialize the auto checkboxes
    If Not VCDProp.AutoAvailable(VCDIDs.VCDID_Brightness) Then
        BrightnessAutoCheckBox.Enabled = False
    Else
        VCDProp.Automation(VCDIDs.VCDID_Brightness) = False
    End If
 
    If Not VCDProp.AutoAvailable(VCDIDs.VCDID_WhiteBalance) Then
        WhitebalanceCheckBox.Enabled = False
        WhitebalanceOnePushButton.Enabled = False
    Else
        VCDProp.Automation(VCDIDs.VCDID_WhiteBalance) = False
    End If
 
 
    ' Initialize the track bars
    If Not VCDProp.Available(VCDIDs.VCDID_Brightness) Then
        BrightnessTrackBar.Enabled = False
    Else
        BrightnessTrackBar.Enabled = True
        BrightnessTrackBar.Minimum = VCDProp.RangeMin(VCDIDs.VCDID_Brightness)
        BrightnessTrackBar.Maximum = VCDProp.RangeMax(VCDIDs.VCDID_Brightness)
        BrightnessTrackBar.Value = VCDProp.RangeValue(VCDIDs.VCDID_Brightness)
        BrightnessTrackBar.TickFrequency = (BrightnessTrackBar.Maximum - BrightnessTrackBar.Minimum) / 10
        BrightnessValueLabel.Text = BrightnessTrackBar.Value
    End If
 
    If Not VCDProp.Available(VCDIDs.VCDElement_WhiteBalanceBlue) Then
        WhiteBalBlueTrackBar.Enabled = False
    Else
        WhiteBalBlueTrackBar.Enabled = True
        WhiteBalBlueTrackBar.Minimum = VCDProp.RangeMin(VCDIDs.VCDElement_WhiteBalanceBlue)
        WhiteBalBlueTrackBar.Maximum = VCDProp.RangeMax(VCDIDs.VCDElement_WhiteBalanceBlue)
        WhiteBalBlueTrackBar.Value = VCDProp.RangeValue(VCDIDs.VCDElement_WhiteBalanceBlue)
        WhiteBalBlueTrackBar.TickFrequency = (WhiteBalBlueTrackBar.Maximum - WhiteBalBlueTrackBar.Minimum) / 10
        WhiteBalBlueLabel.Text = WhiteBalBlueTrackBar.Value
    End If
 
    If Not VCDProp.Available(VCDIDs.VCDElement_WhiteBalanceRed) Then
        WhiteBalRedTrackBar.Enabled = False
    Else
        WhiteBalRedTrackBar.Enabled = False
        WhiteBalRedTrackBar.Enabled = True
        WhiteBalRedTrackBar.Minimum = VCDProp.RangeMin(VCDIDs.VCDElement_WhiteBalanceRed)
        WhiteBalRedTrackBar.Maximum = VCDProp.RangeMax(VCDIDs.VCDElement_WhiteBalanceRed)
        WhiteBalRedTrackBar.Value = VCDProp.RangeValue(VCDIDs.VCDElement_WhiteBalanceRed)
        WhiteBalRedTrackBar.TickFrequency = (WhiteBalRedTrackBar.Maximum - WhiteBalRedTrackBar.Minimum) / 10
        WhiteBalRedLabel.Text = WhiteBalRedTrackBar.Value
    End If
 
    ' start live mode
    ICImagingControl1.LiveStart()
End Sub

[C#]
private void VCDSimplePropertyForm_Load(object sender, System.EventArgs e)
{
    // If no device is selected yet, show the selection dialog
    if( !icImagingControl1.DeviceValid )
    {
        icImagingControl1.ShowDeviceSettingsDialog();
 
        if( !icImagingControl1.DeviceValid )
        {
            MessageBox.Show("No device was selected.");
            this.Close();
            return;
        }
    }
 
    // Initialize the VCDProp class to access the properties of our ICImagingControl
    // object
    VCDProp = TIS.Imaging.VCDHelpers.VCDSimpleModule.GetSimplePropertyContainer(icImagingControl1.VCDPropertyItems);
 
    // Initialize the auto checkboxes
    if( !VCDProp.AutoAvailable(VCDIDs.VCDID_Brightness) )
        BrightnessAutoCheckBox.Enabled = false;
    else
        VCDProp.Automation[VCDIDs.VCDID_Brightness] = false;
 
    if( !VCDProp.AutoAvailable(VCDIDs.VCDID_WhiteBalance) )
    {
        WhitebalanceCheckBox.Enabled = false;
        WhitebalanceOnePushButton.Enabled = false;
    }
    else        
        VCDProp.Automation[VCDIDs.VCDID_WhiteBalance] = false;
 
 
    // Initialize the sliders
    if( !VCDProp.Available(VCDIDs.VCDID_Brightness) )
    {
        BrightnessTrackBar.Enabled = false;
    }
    else
    {
        BrightnessTrackBar.Enabled = true;
        BrightnessTrackBar.Minimum = VCDProp.RangeMin(VCDIDs.VCDID_Brightness);
        BrightnessTrackBar.Maximum = VCDProp.RangeMax(VCDIDs.VCDID_Brightness);
        BrightnessTrackBar.Value = VCDProp.RangeValue[VCDIDs.VCDID_Brightness];
        BrightnessTrackBar.TickFrequency = (BrightnessTrackBar.Maximum - BrightnessTrackBar.Minimum) / 10;
        BrightnessValueLabel.Text = BrightnessTrackBar.Value.ToString();
    }
 
    if( !VCDProp.Available(VCDIDs.VCDElement_WhiteBalanceBlue) )
        WhiteBalBlueTrackBar.Enabled = false;
    else
    {
        WhiteBalBlueTrackBar.Enabled = true;
        WhiteBalBlueTrackBar.Minimum = VCDProp.RangeMin(VCDIDs.VCDElement_WhiteBalanceBlue);
        WhiteBalBlueTrackBar.Maximum = VCDProp.RangeMax(VCDIDs.VCDElement_WhiteBalanceBlue);
        WhiteBalBlueTrackBar.Value = VCDProp.RangeValue[VCDIDs.VCDElement_WhiteBalanceBlue];
        WhiteBalBlueTrackBar.TickFrequency = (WhiteBalBlueTrackBar.Maximum - WhiteBalBlueTrackBar.Minimum) / 10;
        WhiteBalBlueLabel.Text = WhiteBalBlueTrackBar.Value.ToString();
    }
 
    if( !VCDProp.Available(VCDIDs.VCDElement_WhiteBalanceRed) )
        WhiteBalRedTrackBar.Enabled = false;
    else
    {
        WhiteBalRedTrackBar.Enabled = false;
        WhiteBalRedTrackBar.Enabled = true;
        WhiteBalRedTrackBar.Minimum = VCDProp.RangeMin(VCDIDs.VCDElement_WhiteBalanceRed);
        WhiteBalRedTrackBar.Maximum = VCDProp.RangeMax(VCDIDs.VCDElement_WhiteBalanceRed);
        WhiteBalRedTrackBar.Value = VCDProp.RangeValue[VCDIDs.VCDElement_WhiteBalanceRed];
        WhiteBalRedTrackBar.TickFrequency = (WhiteBalRedTrackBar.Maximum - WhiteBalRedTrackBar.Minimum) / 10;
        WhiteBalRedLabel.Text = WhiteBalRedTrackBar.Value.ToString();
    }
 
    // start live mode
    icImagingControl1.LiveStart();
}

As you can see above, the initialization of the track bars for the "WhiteBalanceBlue" and "WhiteBalanceRed" value is done in exactly the same way as the initialization of the track bar for the "Brightness" value. The only difference is that you use the appropriate "Element ID" to specify the property instead of the "Item ID".

Now we need some events to update the properties accordingly. First add a Scroll event for every track bar. The code for the Scroll event of the "Brightness" track bar looks as follows:

[VB.NET]
Private Sub BrightnessTrackBar_Scroll(ByVal sender As System.Object, ByVal e As System.EventArgs) Handles BrightnessTrackBar.Scroll
    VCDProp.RangeValue(VCDIDs.VCDID_Brightness) = BrightnessTrackBar.Value
    BrightnessValueLabel.Text = VCDProp.RangeValue(VCDIDs.VCDID_Brightness)
End Sub

[C#]
private void BrightnessTrackBar_Scroll(object sender, System.EventArgs e)
{
    VCDProp.RangeValue[VCDIDs.VCDID_Brightness] = BrightnessTrackBar.Value;
    BrightnessValueLabel.Text = VCDProp.RangeValue[VCDIDs.VCDID_Brightness].ToString();
}

The Scroll event for the "WhiteBalanceBlue" resp. "WhiteBalanceRed" track bar is similar.

Add a CheckedChanged event for both check boxes. The code for these looks as follows:

[VB.NET]
Private Sub BrightnessAutoCheckBox_CheckedChanged(ByVal sender As System.Object, ByVal e As System.EventArgs) Handles BrightnessAutoCheckBox.CheckedChanged
    VCDProp.Automation(VCDIDs.VCDID_Brightness) = BrightnessAutoCheckBox.Checked
    BrightnessTrackBar.Enabled = Not BrightnessAutoCheckBox.Checked
End Sub

[C#]
private void BrightnessAutoCheckBox_CheckedChanged(object sender, System.EventArgs e)
{
    VCDProp.Automation[VCDIDs.VCDID_Brightness] = BrightnessAutoCheckBox.Checked;
    BrightnessTrackBar.Enabled = !BrightnessAutoCheckBox.Checked;        
}

[VB.NET]
Private Sub WhitebalanceCheckBox_CheckedChanged(ByVal sender As System.Object, ByVal e As System.EventArgs) Handles WhitebalanceCheckBox.CheckedChanged
    VCDProp.Automation(VCDIDs.VCDID_WhiteBalance) = WhitebalanceCheckBox.Checked
    WhiteBalBlueTrackBar.Enabled = Not WhitebalanceCheckBox.Checked
    WhiteBalRedTrackBar.Enabled = Not WhitebalanceCheckBox.Checked
End Sub

[C#]
private void WhitebalanceCheckBox_CheckedChanged(object sender, System.EventArgs e)
{
    VCDProp.Automation[VCDIDs.VCDID_WhiteBalance] = WhitebalanceCheckBox.Checked;
    WhiteBalBlueTrackBar.Enabled = !WhitebalanceCheckBox.Checked;
    WhiteBalRedTrackBar.Enabled = !WhitebalanceCheckBox.Checked;
}

Now add the Click event for the cmdWhiteBalanceOnePush button and insert the following code:

[VB.NET]
Private Sub WhitebalanceOnePushButton_Click(ByVal sender As System.Object, ByVal e As System.EventArgs) Handles WhitebalanceOnePushButton.Click
    VCDProp.OnePush(VCDIDs.VCDID_WhiteBalance)
End Sub

[C#]
private void WhitebalanceOnePushButton_Click(object sender, System.EventArgs e)
{
    VCDProp.OnePush(VCDIDs.VCDID_WhiteBalance);
}

<< Programmer's Guide