IC Imaging Control .NET Component User's Guide

Introduction

This chapter discusses the following topics: Manual organization, System requirements, Distributing

What's New

This part discusses the new features introduced in the latest IC Imaging Control releases.

Project Wizards for Visual Studio

For Visual Basic and Visual C#, there are wizards that allow to easily setup an application that uses IC Imaging Control, as well as setup a frame filter and frame filter module.

Programmer's Guide

Perform your first steps with IC Imaging Control.

Technical Articles

Complete list of all technical articles.

Reference

Complete list of all classes and functions.

IC Imaging Control Standard Filters

IC Imaging Control comes with several standard frame filters. They can be explored with the Filter Inspector application.


Introduction

This chapter discusses the following topics: Manual organization, System requirements, Distributing

Welcome to IC Imaging Control, the image acquisition toolkit for Visual Basic, Visual C++ and .NET. With IC Imaging Control your application immediately supports Firewire cameras from Sony, The Imaging Source and other Vendors, USB cameras, DV cameras, PCI Frame grabbers andvideo-to-Firewire converters.

System Requirements

Getting Started

How this Manual is Organized

Distributing your Applications

<< IC Imaging Control .NET Component User's Guide


System Requirements

IC Imaging Control requires the following minimum configuration

  • Windows® 2000 with service pack 4, Windows® XP, Windows Vista® 32/64 bit or Windows® 7 32/64 bit
  • DirectX® 9.0c or higher.
  • Microsoft® Visual Studio® .NET 8.0 (2005) or higher
  • One or more WDM compliant video capture devices.

<< Introduction


Getting Started

There are two ways to setup a project that uses IC Imaging Control. The easiest way is to use a project wizard. Please refer to the chapter Project Wizards for Visual Studio for details.

If you want to setup a project maually, please refer to the sub chapters First Steps Visual Studio .NET 2003 - 2008.

<< Introduction


How this Manual is Organized

  • Part 1, Introduction covers the topics: Manual Organization, System Requirements and Distributing Applications developed using IC Imaging Control
  • Part 2, What's New discusses the new features introduced in the last IC Imaging Control releases.
  • Part 3, Programmer's Guide, describes how to use IC Imaging Control with Microsoft™ Visual Basic™ .NET and C#.
  • Part 4, Technical Articles, describes general concepts as well as some special features of IC Imaging Control in detail.
  • Part 5, Reference, contains a list of Imaging Control's classes, properties, methods and events sorted in alphabetical order.
  • Part 6, IC Imaging Control Standard Filters, describes the frame filters that are delivered with IC Imaging Control.

<< Introduction


Distributing your Applications

If you want to distribute an application that uses IC Imaging Control, you have have to install all components of IC Imaging Control on the target system that are required to run the control.

Please refer to the chapter Distributing your Applications for details.

<< Introduction


What's New

This part discusses the new features introduced in the latest IC Imaging Control releases.

What is new in version 3.1 since version 3.0

Description of the changes from IC Imaging Control 3.0 to IC Imaging Control 3.1.

What is new in version 3.0 since version 2.0

Description of the changes from IC Imaging Control 2.0 to IC Imaging Control 3.0.

What is new in version 2.0

Description of the changes from IC Imaging Control 1.41 to IC Imaging Control 2.0.

<< IC Imaging Control .NET Component User's Guide


What is new in version 3.1 since version 3.0

Description of the changes from IC Imaging Control 3.0 to IC Imaging Control 3.1.

.NET Framework Compatibility

  • IC Imaging Control 3.1 introduces a new .NET 2.0 component, that does no longer depend on ICImagingControl.ocx.
  • IC Imaging Control 3.1 supports .NET 2.0 or higher.
  • IC Imaging Control 3.1 is saved in the Global Assembly Cache. Manual searching the DLLs is obsolete.

ICException has completly changed

ICException has completly changed from the older version, so beware.

  • ArgumentException -> argument invalid (and not 0)
  • ArgumentNullException -> null reference passed when object was required
  • ArgumentOutOfRangeException -> out of range
  • NotSupportedException -> on unsupported methods
  • InvalidOperationException -> on invalid objects or invalid states
  • FormatException -> on casting problems in VCDProperty objects

Namespace Changes

The following types were moved from the ICImagingControl3 namespace to TIS.Imaging:

  • VCDAbsoluteValueProperty
  • VCDButtonProperty
  • VCDCategoryMap
  • VCDMapStringsProperty
  • VCDPropertyElement
  • VCDPropertyInterface
  • VCDPropertyItem
  • VCDPropertyItems
  • VCDRangeProperty
  • VCDSwitchProperty

VCDSimpleProperty Class has been moved

The VCDSimpleProperty class has been integrated in the ICImagingControl3 component. Thus it is not longer necessary to add the sources files of this class as reference to a solution.

New Features

New Features Reference

List of all new features

<< What's New


New Features Reference

List of all new features

Extended Classes

List of all classes that have been extended in IC Imaging Control 3.1

New Classes

List of all classes that have been introduced in IC Imaging Control 3.1

New Enumerations

List of all enumerations that have been introduced in IC Imaging Control 3.1

<< What is new in version 3.1 since version 3.0


Extended Classes

List of all classes that have been extended in IC Imaging Control 3.1

New Methods of AviCompressor

List of properties and methods that have been added to the AviCompressor class in IC Imaging Control 3.1

New Methods of FrameHandlerSink

List of properties and methods that have been added to the LastAcquiredBuffer class in IC Imaging Control 3.1

New Methods of FrameType

List of properties and methods that have been added to the FrameType class in IC Imaging Control 3.1

New Methods of MediaStreamContainer

List of properties and methods that have been added to the MediaStreamContainer class in IC Imaging Control 3.1

New Methods of MediaStreamSink

List of properties and methods that have been added to the MediaStreamSink class in IC Imaging Control 3.1

New Methods of VCDCategoryMap

List of properties and methods that have been added to the VCDCategoryMap class in IC Imaging Control 3.1

New Methods of ICImagingControl

List of properties and methods that have been added to the ICImagingControl class in IC Imaging Control 3.1

New Methods of ImageBuffer

List of properties and methods that have been added to the ImageBuffer class in IC Imaging Control 3.1 Furthermore in IC Imaging Control 3.1 the ImageBuffer supports the debugger visulizer.

<< New Features Reference


New Methods of AviCompressor

List of properties and methods that have been added to the AviCompressor class in IC Imaging Control 3.1

AviCompressor.ToString

Returns the name of the AviCompressor.

AviCompressor.CompressorDataString

Returns or sets a string containing the codec parameters.

<< Extended Classes


AviCompressor::ToString

AviCompressor.ToString Method
Returns the name of the AviCompressor.
Syntax:
[VB.NET]
Public Sub ToString As String

[C#]
public String ToString();
Information:

Introduced in version 3.1
See Also: AviCompressor, AviCompressor.Name

<< AviCompressor


AviCompressor::CompressorDataString

AviCompressor.CompressorDataString Property
Returns or sets a string containing the codec parameters.
Syntax:
[VB.NET]
Public CompressorDataString As String

[C#]
public string CompressorDataString;
Information:

Introduced in version 3.1
Sample:

This example shows how to select an AVI compressor, show the its dialog. In this dialog some values should be set. Then the settings are saved in the string variable. In the next step the dialog is shown again to change some values. After the dialog has been closed, the saved settings in the string are passed back to the compressor and the dialog is shown again to validate the restored settings.

[VB.NET]
Dim Compressor As AviCompressor

Compressor = Nothing
' Set MJPEG Compressor as codec.
For Each codec As AviCompressor In IcImagingControl1.AviCompressors
    If codec.Name = "MJPEG Compressor" Then
        Compressor = codec
        Exit For
    End If
Next

' Show the property page to set some values.
Compressor.ShowPropertyPage()

Dim CompressorData As String = Compressor.CompressorDataString

' Show the dialog again and change the settings.
Compressor.ShowPropertyPage()

' Restore the settings from the string.
Compressor.CompressorDataString = CompressorData

' Validate the restored settings.
Compressor.ShowPropertyPage()

[C#]
AviCompressor Compressor = null;
//Set MJPEG Compressor as codec.
foreach (AviCompressor codec in ICImagingControl1.AviCompressors)
{
    if (codec.Name == "MJPEG Compressor")
    {
        Compressor = codec;
        break;
    }
}

// Show the property page to set some values.
Compressor.ShowPropertyPage();

// Now save these values in a string.
String CompressorData = Compressor.CompressorDataString;

// Show the dialog again and change the settings.
Compressor.ShowPropertyPage();

// Restore the settings from the string.
Compressor.CompressorDataString = CompressorData;

// Validate the restored settings.
Compressor.ShowPropertyPage();

How to use avi compressors is shown in the Capturing an AVI File sample.

See also: MediaStreamSink

<< AviCompressor


New Methods of FrameHandlerSink

List of properties and methods that have been added to the LastAcquiredBuffer class in IC Imaging Control 3.1

FrameHandlerSink.LastAcquiredBuffer

Returns the ImageBuffer that contains the last captured frame.

<< Extended Classes


FrameHandlerSink::LastAcquiredBuffer

FrameHandlerSink.LastAcquiredBuffer Property
Returns the ImageBuffer that contains the last captured frame.
Syntax:
[VB.NET]
Public LastAcquiredBuffer As ImageBuffer

[C#]
public ImageBuffer LastAcquiredBuffer;
Limitations:

Read only.
Remarks:

After stopping or pausing the sink, this method returns the image buffer that contains last acquired frame until the sink is restarted.

If an error occurred, the exception INVALID_MEMBUFFER is thrown.

LastAcquiredBuffer returns NULL in case of an error.
Example:

The following example shows how to save the last acquired image in a JPG file:

[C#]
FrameHandlerSink fhs = new FrameHandlerSink();
fhs.SnapMode = false;

ICImagingControl1.Sink = fhs;
ICImagingControl1.LiveStart();

// Do something, wait for user action, ...

ICImagingControl1.LiveStop();

// Save the last acquired image to a JPG file.
fhs.LastAcquiredBuffer.SaveAsJpeg( "last.jpg", 75 );

[VB.NET]
Dim fhs As New FrameHandlerSink
fhs.SnapMode = False

IcImagingControl1.Sink = fhs
IcImagingControl1.LiveStart()

' Do something, wait for user action, ...

IcImagingControl1.LiveStop()

' Save the last acquired image to a JPG file.
fhs.LastAcquiredBuffer.SaveAsJpeg("last.jpg", 75)
See also: FrameHandlerSink, FrameHandlerSink.ImageBuffers, ImageBuffer

<< FrameHandlerSink


New Methods of FrameType

List of properties and methods that have been added to the FrameType class in IC Imaging Control 3.1

FrameType.FrameType

Creates a new FrameType.

FrameType.FourCC

Returns the FourCC pixel format of the frametype as string.

<< Extended Classes


FrameType::FrameType

FrameType.FrameType Method
Creates a new FrameType.
Syntax:
[VB.NET]
Public Sub New()
Public Sub New( fourCC As String )
Public Sub New( subtype As System.Guid )
Public Sub New( subtype As System.Guid, width As Integer, height As Integer )
Public Sub New( subtype As System.Guid, width As Integer, height As Integer, buffersize As Integer )

[C#]
public FrameType();
public FrameType( String fourCC );
public FrameType( System.Guid subtype );
public FrameType( System.Guid subtype, int width, int height );
public FrameType( System.Guid subtype, int width, int height, int buffersize );
Parameter Description
fourCC

A four char string that describes the color format of the frame. Sample strings are "Y800","UYVY", "RGB24","RGB32" or "V210". Any FourCC can be passed to this parameter. If a FourCC is passed to the fourCC parameter is used, then valid colorspace transform filters must exist on the computer. Otherwise an exception will be thrown.

(Annotation: Even if "RGB24" and "RGB32" are no FourCC codes, they are accepted as parameter, because they are very common. They will create an RGB24, respective and RGB32 sink.)

subtype

A GUID describing the color format of the frame. See MediaSubtypes for commonly used constants for this parameter. Omitting this parameter or setting its value to System.Guid.Empty creates a FrameType that is compatible to any other frame type regarding the color format.

width

Width of the frame. Omitting this parameter or setting its value to 0 creates a FrameType that is compatible to any other frame type regarding the width.

height

Height of the frame. Omitting this parameter or setting its value to 0 creates a FrameType that is compatible to any other frame type regarding the height.

buffersize

Number of bytes required to store a frame. Omitting this parameter or setting its value to 0 creates a FrameType that is compatible to any other frame type regarding the buffer size.

Remarks:

The use of the parameters width, height and buffersize is suitable for frame filters, that change the size of the frames.

See also : FrameTypes, MediaSubtypes, ImageBuffer

<< FrameHandlerSink.FrameType


FrameType::FourCC

FrameType.FourCC Property
Returns the FourCC pixel format of the frametype as string.
Syntax:
[VB.NET]
Public FourCC As String

[C#]
public string FourCC;
Limitations:

Read only.
Information:

Introduced in version 3.1
Sample:

This example shows how to get the the current frametype using the FourCC property:

[C#]
TIS.Imaging.FrameHandlerSink Sink = new TIS.Imaging.FrameHandlerSink();
Sink.FrameTypes.Add(new TIS.Imaging.FrameType("Y800"));
Sink.FrameTypes.Add(new TIS.Imaging.FrameType("RGB24"));
ICImagingControl1.Sink = Sink;

ICImagingControl1.LiveStart();
if (Sink.FrameType != null)
{
    Console.WriteLine("FourCC : " + Sink.FrameType.FourCC);
}
else
{
    // Should not happen after LiveStart() has been called.
    Console.WriteLine("FourCC : FrameType is null.");
}
ICImagingControl1.LiveStop();

[VB.NET]
Dim Sink As New TIS.Imaging.FrameHandlerSink
Sink.FrameTypes.Add(New FrameType("Y800"))
Sink.FrameTypes.Add(New FrameType("RGB24"))

IcImagingControl1.Sink = Sink
IcImagingControl1.LiveStart()

If (Sink.FrameType <> Nothing) Then
    Console.WriteLine("FourCC : " + Sink.FrameType.FourCC)
Else
    ' Should not happen after LiveStart() has been called.
    Console.WriteLine("FourCC : FrameType is null.")
End If
See also: FrameHandlerSink.FrameType, ICImagingControl, FrameType

<< FrameHandlerSink.FrameType


New Methods of MediaStreamContainer

List of properties and methods that have been added to the MediaStreamContainer class in IC Imaging Control 3.1

MediaStreamContainer.MediaStreamContainer

Creates an new MediaStreamContainer object.

<< Extended Classes


MediaStreamContainer::MediaStreamContainer

MediaStreamContainer.MediaStreamContainer Method
Creates an new MediaStreamContainer object.
Syntax:
[VB.NET]
Public Sub MediaStreamContainer As MediaStreamContainer

[C#]
Public MediaStreamContainer MediaStreamContainer(StandardContainer container);

Parameter | Description
container | Specifies the StandardContainer for the new created the MediaStreamContainer.
Information:

Introduced in version 3.1
See also: MediaStreamContainer, StandardContainer

<< MediaStreamContainer


New Methods of MediaStreamSink

List of properties and methods that have been added to the MediaStreamSink class in IC Imaging Control 3.1

MediaStreamSink.MediaStreamSink

Creates a new MediaStreamSink.

<< Extended Classes


MediaStreamSink::MediaStreamSink

MediaStreamSink.MediaStreamSink Method
Creates a new MediaStreamSink.
Syntax:
[VB.NET]
Public Sub MediaStreamSink( codec  As AviCompressor, filename As String ) As MediaStreamSink

[C#]
Public MediaStreamSink MediaStreamSink( AviCompressor codec, String filename );

Parameter | Description
codec | Specifies the codec to be used by the MediaStreamSink.
filename | Specifies the filename, to used by the MediaStreamSink when writing an AVI file.
Information:

Introduced in version 3.1
Example:

The following code fragment shows how to select a codec and create a MediaStreamSink to record an AVI file. After doing so a two second AVI file is recorded.

[C#]
AviCompressor Codec = null;
//Set DV Video encoder as codec.
foreach( AviCompressor codec in ICImagingControl1.AviCompressors )
{
    if( codec.Name == "DV Video Encoder" )
    {
        Codec = codec;
        break;
    }
}
// Create the MediaStreamSink using the selected codec and a filename.
MediaStreamSink MSSink = new MediaStreamSink(Codec, "Test.AVI");

// Set the sink.
ICImagingControl1.Sink = MSSink;

// Start recording for two seconds.
ICImagingControl1.LiveStart();
System.Threading.Thread.Sleep(2000);
ICImagingControl1.LiveStop();

[VB.NET]
Dim Compressor As AviCompressor

Compressor = Nothing
' Set DV Video encoder as codec.
For Each codec As AviCompressor In IcImagingControl1.AviCompressors
    If codec.Name = "DV Video Encoder" Then
        Compressor = codec
        Exit For
    End If
Next

' Create the MediaStreamSink using the selected codec and a filename.
Dim MSSink As New MediaStreamSink(Compressor, "Test.AVI")

' Set the sink
IcImagingControl1.Sink = MSSink

'Start recording for two seconds.
IcImagingControl1.LiveStart()
System.Threading.Thread.Sleep(2000)
IcImagingControl1.LiveStop()
See also: ICImagingControl, ICImagingControl.LivePrepare, ICImagingControl.LiveStart, ICImagingControl.LiveVideoRunning

<< MediaStreamSink


New Methods of VCDCategoryMap

List of properties and methods that have been added to the VCDCategoryMap class in IC Imaging Control 3.1

VCDCategoryMap.ItemIDs

Returns the System.Collections.Generic.Dictionary containing the VCD item IDs, ordered by their categories.

VCDCategoryMap.Items

Returns the System.Collections.Generic.Dictionary containing the VCD item names, ordered by their categories.

<< Extended Classes


VCDCategoryMap::ItemIDs

VCDCategoryMap.ItemIDs Property
Returns the System.Collections.Generic.Dictionary containing the VCD item IDs, ordered by their categories.
Syntax:
[VB.NET]
Public ReadOnly ItemIDs() As Dictionary(Of String, Guid())

[C#]
public Dictionary<string,Guid[]> ItemIDs { get; };
Limitations:

Read only.
Information:

Introduced in version 3.1
See also: VCDCategoryMap, VCDCategoryMap.Categories

<< VCDCategoryMap


VCDCategoryMap::Items

VCDCategoryMap.Items Property
Returns the System.Collections.Generic.Dictionary containing the VCD item names, ordered by their categories.
Syntax:
[VB.NET]
Public ReadOnly Items() As Dictionary(Of String, String())

[C#]
public Dictionary<string,string[]> Items { get; };
Limitations:

Read only.
Information:

Introduced in version 3.1
See also: VCDCategoryMap, VCDCategoryMap.Categories

<< VCDCategoryMap


New Methods of ICImagingControl

List of properties and methods that have been added to the ICImagingControl class in IC Imaging Control 3.1

ICImagingControl.DeviceCurrent

Returns a Device object that contains the currently used video capture device.

ICImagingControl.ICImagingControl

Creates a new ICImagingControl object.

ICImagingControl.ImageAvailableExecutionMode

This property controls the execution mode of the ImageAvailable event.

ICImagingControl.ImageSize

Returns the image height and width in pixels of the current video format.

ICImagingControl.LiveDisplayPosition

Returns or sets the top position of the video display window in IC Imaging Control's window.

ICImagingControl.LiveDisplaySize

Returns or sets the height and width of the video display window.

ICImagingControl.LivePrepare

This method tries to setup the image stream by connecting the device with the display and the sink and inserting frame filters and overlays.

ICImagingControl.LivePrepared

This event is called after the LivePrepare was called.

ICImagingControl.LiveSuspend

Suspends a prepared image stream and switches it into prepared state.

ICImagingControl.MemorySnapImage

This method captures a still image from a live video stream.

ICImagingControl.MemorySnapImageSequence

This method captures a sequence of still images from a live video stream and stores the images in a list of internal buffers. The images can be saved to individual files using the ICImagingControl.MemorySaveImageSequence method.

ICImagingControl.VideoFormatCurrent

Returns the selected Videoformat object.

<< Extended Classes


ICImagingControl::DeviceCurrent

ICImagingControl.DeviceCurrent Property
Returns a Device object that contains the currently used video capture device.
Syntax:
[VB.NET]
Public DeviceCurrent As Device

[C#]
public Device DeviceCurrent;
Information:

Introduced in version 3.1
Sample:

This example shows how to query the current used video capture device:

[VB.NET]
Dim MyDevice As TIS.Imaging.Device

MyDevice = IcImagingControl1.DeviceCurrent

If Not MyDevice Is Nothing Then
    Console.WriteLine("Current Device is " + MyDevice.Name)
Else
    Console.WriteLine("Currently no device opened")
End If

[C#]
TIS.Imaging.Device MyDevice = null;

MyDevice = ICImagingControl1.DeviceCurrent;

if (MyDevice != null)
{
    Console.WriteLine("Current Device is " + MyDevice.Name  );
}
else
{
    Console.WriteLine("Currently no device opened");
}
See also: Device

<< ICImagingControl


ICImagingControl::ICImagingControl

ICImagingControl.ICImagingControl Method
Creates a new ICImagingControl object.
Syntax:
[VB.NET]
Public Sub New() As IcImagingControl
Public Sub New( licenseKey As String ) As IcImagingControl

[C#]
Public IcImagingControl IcImagingControl();
Public IcImagingControl IcImagingControl( String LicenseKey );

Parameter | Description
licenseKey | Specifies the licenseKey when creating the ICImagingControl Component dynamically.
Remarks:

If IC Imaging Control is not used on a form or if it is created dynamically, then the constructor that receives the LicenseKey is to be used. The license key is the same key, that was used due to the setup of IC Imaging Control. It is labeled on the IC Imaging Control CD ROM's cover.

Information:

Introduced in version 3.1
See also: ICImagingControl

<< ICImagingControl


ICImagingControl::ImageAvailableExecutionMode

ICImagingControl.ImageAvailableExecutionMode Property
This property controls the execution mode of the ImageAvailable event.
Syntax:
[VB.NET]
Public ImageAvailableExecutionMode As EventExecutionMode

[C#]
public EventExecutionMode ImageAvailableExecutionMode { get; set; };
Remarks:

For a description of the available execution modes, see the EventExecutionMode enumeration.

Information:

Introduced in version 3.1
See also: ICImagingControl, EventExecutionMode

<< ICImagingControl


ICImagingControl::ImageSize

ICImagingControl.ImageSize Property
Returns the image height and width in pixels of the current video format.
Syntax:
[VB.NET]
Public ImageSize As System.Drawing.Size

[C#]
public System.Drawing.Size ImageSize;
Limitations:

Run time only, read only.
Remarks:

The returned image size is affected if the ROIFilter is in use in the device or in the sink path. If the ROIFilter resides in the display path only, then the returned image size is not changed and returns the size of the video format.

Information:

Introduced in version 3.1
See also: ICImagingControl

<< ICImagingControl


ICImagingControl::LiveDisplayPosition

ICImagingControl.LiveDisplayPosition Property
Returns or sets the top position of the video display window in IC Imaging Control's window.
Syntax:
[VB.NET]
Public LiveDisplayPosition As System.Drawing.Point

[C#]
public System.Drawing.Point LiveDisplayPosition;
Limitations:

This property can only be set, if the property LiveDisplayDefault has been set to false.
Remarks:

Whether the position of the live video window can be changed or not can be toggled with the LiveDisplayDefault property. If LiveDisplayDefault returns True, the size of the live video window can not be adjusted. If LiveDisplayDefault is set to False, the size and position of the live video window can be adjusted to the application's needs.

Information:

Introduced in version 3.1
See also: ICImagingControl, LiveDisplayDefault, LiveDisplaySize, LiveDisplayHeight, LiveDisplayLeft

<< ICImagingControl


ICImagingControl::LiveDisplaySize

ICImagingControl.LiveDisplaySize Property
Returns or sets the height and width of the video display window.
Syntax:
[VB.NET]
Public LiveDisplaySize As System.Drawing.Size

[C#]
public System.Drawing.Size LiveDisplaySize;
Limitations:

This property can only be set, if the property LiveDisplayDefault has been set to false.
Remarks:

Whether the size of the live video window can be changed or not can be toggled with the LiveDisplayDefault property. If LiveDisplayDefault returns True, the size of the live video window can not be adjusted. If LiveDisplayDefault is set to False, the size and position of the live video window can be adjusted to the application's needs.

Information:

Introduced in version 3.1
See also: ICImagingControl, LiveDisplayDefault, LiveDisplayPosition, LiveDisplayWidth, LiveDisplayHeight

<< ICImagingControl


ICImagingControl::LivePrepare

ICImagingControl.LivePrepare Method
This method tries to setup the image stream by connecting the device with the display and the sink and inserting frame filters and overlays.
Syntax:
[VB.NET]
Public Sub LivePrepare()

[C#]
Public void LivePrepare();
Return Value:

If the image stream could not have been prepared, an exception is thrown.

Remarks:

LivePrepare prepares the image stream but does not start the live video and also does not allocate bandwidth on the used bus (FireWire or USB). Therefore this method is suitable in an environment with more than one video capture device. Subsequent starts of the live video by a call to LiveStart are much faster than LiveStart without a previous LivePrepare call.

A prepared and started live stream can be stopped and switched back to prepared state by a call to LiveSuspend.

A call to LiveStop clears the prepared live stream.

No operations which may change the layout of the video stream are permitted after LivePrepare was called. These operations are:

  • VideoFormat
  • DeviceFrameRate
  • VideoNorm
  • Sink
  • OverlayBitmap
  • DeviceTrigger
  • DeviceFlipHorizontal
  • DeviceFlipVertical
  • DeviceFrameFilters
  • DisplayFrameFilters
Information:

Introduced in version 3.1
Sample:

This example shows to use some IC Imaging Controls in an array and open some video capture devices. The image streams are prepared right after the video capture devices have been opened.

In a simulated processing loop MemorySnapImage is excuted in sequence on each IC Imaging Control. This loop runs relativly fast, because the live streams for each video capture have already been prepared.

[VB.NET]
' Create ICImagingControl instances for each connected video capture device.
Dim CameraCount As Integer = 2
Dim IC(CameraCount) As TIS.Imaging.ICImagingControl

For Camera As Integer = 0 To CameraCount - 1
    IC(Camera) = New ICImagingControl()
    IC(Camera).ShowDeviceSettingsDialog()
    Try
        'Try to prepare the image stream.
        IC(Camera).LivePrepare()
    Catch Ex As ICException
        MessageBox.Show(Ex.Message)
    End Try

Next

' Now do some processing, e.g. snap an image. This loop simulates
' 10 times image processing for each camera in sequence.
For i As Integer = 0 To 10
    For Camera As Integer = 0 To CameraCount - 1
        If IC(Camera).IsLivePrepared = True Then
            Try
                ' Use a timeout of 1000ms.
                IC(Camera).MemorySnapImage(1000)
                ' Show the snapped image in a PictureBox.
                PictureBox1.Image = IC(Camera).ImageActiveBuffer.Bitmap
                PictureBox1.Update()
            Catch Ex As ICException
                MessageBox.Show(Ex.Message)
            End Try
        End If
    Next
Next

' At the end of the application the prepared live video streams should be stopped.
For Camera As Integer = 0 To CameraCount - 1
    IC(Camera).LiveStop()
Next

[C#]
// Create ICImagingControl instances for each connected video capture device.
int CameraCount = 2;
TIS.Imaging.ICImagingControl[] IC = new ICImagingControl[CameraCount];

// Open the video capture devices and prepare the live video stream
for (int Camera = 0; Camera < CameraCount; Camera++)
{
    IC[Camera] = new ICImagingControl();
    IC[Camera].ShowDeviceSettingsDialog();
    try
    {
        // Try to prepare the image stream.
        IC[Camera].LivePrepare();
    }
    catch (ICException Ex)
    {
        MessageBox.Show(Ex.Message, "LivePrepare Error");
    }
}

// Now do some processing, e.g. snap an image. This loop simulates
// 10 times image processing for each camera in sequence.
for (int i = 0; i < 10; i++)
{
    for (int Camera = 0; Camera < CameraCount; Camera++)
    {
        if (IC[Camera].IsLivePrepared)
        {
            try
            {
                IC[Camera].MemorySnapImage(1000);
                // Show the snapped image in a PictureBox.
                pictureBox1.Image = IC[Camera].ImageActiveBuffer.Bitmap;
                pictureBox1.Update();
            }
            catch (ICException Ex)
            {
                MessageBox.Show(Ex.Message, "MemorySnapImage Error");
            }
        }
    }
}

// At the end of the application the prepared live video streams should be stopped.
for (int Camera = 0; Camera < CameraCount; Camera++)
{
    IC[Camera].LiveStop();
}
See also: ICImagingControl, ICImagingControl.LiveSuspend, ICImagingControl.LiveStart, ICImagingControl.LiveStop, ICImagingControl.LiveVideoRunning, ICImagingControl.IsLivePrepared

<< ICImagingControl


ICImagingControl::LivePrepared

ICImagingControl.LivePrepared Event
This event is called after the LivePrepare was called.
Syntax:
[VB.NET]
Public Event LivePrepared(ByVal sender As Object, ByVal e As System.EventArgs)

[C#]
public event System.EventHandler LivePrepared;

Parameter | Description
sender | The ICImagingControl object that fired the event.
e | A System.EventArgs object.
Limitations:

Run time only, read only.
See also: ICImagingControl, ICImagingControl.LivePrepare

<< ICImagingControl


ICImagingControl::LiveSuspend

ICImagingControl.LiveSuspend Method
Suspends a prepared image stream and switches it into prepared state.
Syntax:
[VB.NET]
Public Sub LiveSuspend() As Boolean

[C#]
Public bool LiveSuspend();
Return Value:

The method returns true, if the operation was successful.

Information:

Introduced in version 3.1
See also: ICImagingControl, ICImagingControl.LivePrepare, ICImagingControl.LiveStart, ICImagingControl.LiveVideoRunning, ICImagingControl.IsLivePrepared

<< ICImagingControl


ICImagingControl::MemorySnapImage

ICImagingControl.MemorySnapImage Method
This method captures a still image from a live video stream.
Syntax:
[VB.NET]
Public Sub MemorySaveImage
Public Sub MemorySaveImage( timeoutInMs As Integer )

[C#]
Public void MemorySaveImage();
Public void MemorySaveImage( int timeoutInMs );

Parameter | Description
timeoutInMs | Specifies the snap timeout value in milliseconds.
Remarks:

This method captures a still image from a live video stream and stores it in the ring buffer. The buffer can be saved to a file using the ICImagingControl.MemorySaveImage Method.

If the live video stream is already running, then the maximum duration of MemorySnapImage is double of the frame rates time intervall. MemorySnapImage captures the next new provided image from the live video stream.

If the live video stream was not started before a call of MemorySnapImage, then the live video stream is started in MemorySnapImage automatically. An image will be captured and the live video stream is stopped automatically. If MemorySnapImage is called often in an application, then this sequence of start - snap - stop can be very time expensive. Thus, it is better to call LiveStart once in the application and stop the live video stream when the application ends.

When LiveCaptureContinuous is true, MemorySnapImage throws an ICException with the error code ICException.ErrorCodes.NotAvailableOutsideSnapMode.

If no image was provided by the video capture device in the timeout time an exception is thrown.

If an external triggered camera is in use, then MemorySnapImage should be avoided, because it blocks the application until it returns. For triggered cameras the ImageAvailable event should be used.

Sample:

The following code snippet shows how to snap an image from the video live stream using a timeout of 1000ms. The snapped image will be shown in a PictureBox:

[VB.NET]
IcImagingControl1.LiveStart()
Try
    ' Use a timeout of 1000ms.
    IcImagingControl1.MemorySnapImage(1000)
    ' Show the snapped image in a PictureBox.
    PictureBox1.Image = IcImagingControl1.ImageActiveBuffer.Bitmap
Catch Ex As ICException
    MessageBox.Show(Ex.Message)
End Try
IcImagingControl1.LiveStop()

[C#]
ICImagingControl1.LiveStart();
try
{
    // Use a timeout of 1000ms.
    ICImagingControl1.MemorySnapImage(1000);
    // Show the snapped image in a PictureBox.
    pictureBox1.Image = ICImagingControl1.ImageActiveBuffer.Bitmap;
}
catch (ICException Ex)
{
    MessageBox.Show(Ex.Message, "MemorySnapImage Error");
}
ICImagingControl1.LiveStop();
See also: ICImagingControl, ICImagingControl.MemorySaveImage, ICImagingControl.ImageActiveBuffer, ICException.ErrorCodes

<< ICImagingControl


ICImagingControl::MemorySnapImageSequence

ICImagingControl.MemorySnapImageSequence Method
This method captures a sequence of still images from a live video stream and stores the images in a list of internal buffers. The images can be saved to individual files using the ICImagingControl.MemorySaveImageSequence method.
Syntax:
[VB.NET]
Public Sub MemorySnapImageSequence(ImageCount As Integer)
Public Sub MemorySnapImageSequence(ImageCount As Integer , timeoutInMs As Integer)

[C#]
public void MemorySnapImageSequence(int ImageCount);
public void MemorySnapImageSequence(int ImageCount, int timeoutInMs);

Parameter | Description
ImageCount | Specifies number of images to be captured.
timeoutInMs | Specifies the snap timeout value in milliseconds.
Remarks:

When LiveCaptureContinuous is true, MemorySnapImageSequence throws a ICException with the error code NotAvailableOutsideSnapMode.

Sample:

The following code snippet shows how to snap 10 images from the video live stream using a timeout of 3000ms. The snapped images will be shown in a PictureBox:

[VB.NET]
' Use 10 image buffers.
IcImagingControl1.ImageRingBufferSize = 10

IcImagingControl1.LiveStart()
Try
    ' Snap 5 images using a timeout of 3000ms.
    IcImagingControl1.MemorySnapImageSequence(10, 3000)
    ' Show the snapped images in a PictureBox.
    For Each Img As TIS.Imaging.ImageBuffer In IcImagingControl1.ImageBuffers
        PictureBox1.Image = Img.Bitmap
        PictureBox1.Update()
        System.Threading.Thread.Sleep(1000)
    Next
Catch Ex As ICException
    MessageBox.Show(Ex.Message)
End Try
IcImagingControl1.LiveStop()

[C#]
// Use 10 image buffers.
ICImagingControl1.ImageRingBufferSize = 10;

ICImagingControl1.LiveStart();
try
{
    // Use a timeout of 3000ms.
    ICImagingControl1.MemorySnapImageSequence(10,3000);
    // Show the snapped images in a PictureBox.
    foreach (TIS.Imaging.ImageBuffer Img in ICImagingControl1.ImageBuffers)
    {
        pictureBox1.Image = Img.Bitmap;
        pictureBox1.Update();
        System.Threading.Thread.Sleep(1000);
    }
}
catch (ICException Ex)
{
    MessageBox.Show(Ex.Message, "MemorySnapImage Error");
}
ICImagingControl1.LiveStop();
See also: ICImagingControl, ICImagingControl.MemorySaveImageSequence, ICImagingControl.ImageRingBufferSize

<< ICImagingControl


ICImagingControl::VideoFormatCurrent

ICImagingControl.VideoFormatCurrent Property
Returns the selected Videoformat object.
Syntax:
[VB.NET]
Public VideoFormatCurrent As TIS.Imaging.VideoFormat

[C#]
public TIS.Imaging.VideoFormat VideoFormatCurrent;
Information:

Introduced in version 3.1
Sample:

This example shows how to query the current used video format and show its height:

[VB.NET]
Dim MyVideoFormat As TIS.Imaging.VideoFormat

MyVideoFormat = IcImagingControl1.VideoFormatCurrent

If Not MyVideoFormat Is Nothing Then
    Console.WriteLine("Current video format height is " + MyVideoFormat.Height.ToString())
Else
    Console.WriteLine("Currently no device opened")
End If

[C#]
TIS.Imaging.VideoFormat CurrentVideoFormat = null;

CurrentVideoFormat = ICImagingControl1.VideoFormatCurrent;

if (CurrentVideoFormat != null)
{
    Console.WriteLine("Current video format height is " + CurrentVideoFormat.Height.ToString() );
}
else
{
    Console.WriteLine("Currently no device opened");
}
See also: VideoFormat

<< ICImagingControl


New Methods of ImageBuffer

List of properties and methods that have been added to the ImageBuffer class in IC Imaging Control 3.1 Furthermore in IC Imaging Control 3.1 the ImageBuffer supports the debugger visulizer.

ImageBuffer.BytesPerLine

Returns the number of Bytes in each line of this ImageBuffer.

ImageBuffer.GetByteData

Gets the Bytedata at an specific index of an imagebuffer.

ImageBuffer.SetByteData

Sets the Bytedata at an specific index of an imagebuffer.

<< Extended Classes


ImageBuffer::BytesPerLine

ImageBuffer.BytesPerLine Property
Returns the number of Bytes in each line of this ImageBuffer.
Syntax:
[VB.NET]
Public ImageSize As int

[C#]
public int ImageSize;
Information:

Introduced in version 3.1
See also: ICImagingControl

<< ImageAvailableEventArgs.ImageBuffer


ImageBuffer::GetByteData

ImageBuffer.GetByteData Method
Gets the Bytedata at an specific index of an imagebuffer.
Syntax:
[VB.NET]
Public Sub GetByteData( ByteIndex As Integer ) As Byte
Public Sub GetByteData( ByteIndex As Integer , LineIndex As Integer ) As Byte

[C#]
Public byte GetByteData( int ByteIndex );
Public byte GetByteData( int ByteIndex, int LineIndex  );

Parameter | Description
ByteIndex | Specifies the absolute index in an imagebuffer.
LineIndex | Specifies the LineIndex in an imagebuffer.
Information:

Introduced in version 3.1
See also: ImageBuffer, ImageBuffer.SetByteData

<< ImageAvailableEventArgs.ImageBuffer


ImageBuffer::SetByteData

ImageBuffer.SetByteData Method
Sets the Bytedata at an specific index of an imagebuffer.
Syntax:
[VB.NET]
Public Sub SetByteData( ByteIndex As Integer )
Public Sub SetByteData( ByteIndex As Integer , LineIndex As Integer )

[C#]
Public void SetByteData( int ByteIndex );
Public void SetByteData( int ByteIndex, int LineIndex  );

Parameter | Description
ByteIndex | Specifies the absolute index in an imagebuffer.
LineIndex | Specifies the LineIndex in an imagebuffer.
Information:

Introduced in version 3.1
See also: ImageBuffer, ImageBuffer.GetByteData

<< ImageAvailableEventArgs.ImageBuffer


New Classes

List of all classes that have been introduced in IC Imaging Control 3.1

DeviceLostEventArgs

This class holds the event arguments for the ICImagingControl.DeviceLost event.

UserFrame

An abstract class, which can be implemented in order to create own additional buffers. This can be requested when an own OverlayBitmap object is needed, for example.

<< New Features Reference


DeviceLostEventArgs

This class holds the event arguments for the ICImagingControl.DeviceLost event.

Information

Namespace: TIS.Imaging.ICImagingControl
Introduced in version 3.1

Properties

Property | Description
Device | The device that was lost. May be null when no information about the device is available.

<< Classes


DeviceLostEventArgs::Device

DeviceLostEventArgs.Device Property
The device that was lost. May be null when no information about the device is available.
Syntax:
[VB.NET]
Public Device As Device

[C#]
public Device Device;
Limitations:

Read only.
See also: ICImagingControl, ICImagingControl.ImageAvailable, ICImagingControl.ImageBuffers, ImageBuffer

<< DeviceLostEventArgs


UserFrame

An abstract class, which can be implemented in order to create own additional buffers. This can be requested when an own OverlayBitmap object is needed, for example.

Information

Namespace: TIS.Imaging
Introduced in version 3.1

Properties

Property | Description
FrameType | Returns the frame type of this frame.
Ptr | Returns a pointer to the image data.
SampleEndTime | Returns the reference end time of the sample represented by the UserFrame.
SampleStartTime | Returns the reference start time of the sample represented by the UserFrame.

Methods

Method | Description
CopyFrom | Copies the image data from a specified IFrame to this UserFrame. This Method must be implemented in a class which implements UserFrame.
GetIntPtr | Returns the pointer to the image data of this frame as an IntPtr. This Method must be implemented in a class which implements UserFrame.
UserFrame | Creates a new instance of an Userframe.

<< Classes


UserFrame::FrameType

UserFrame.FrameType Property
Returns the frame type of this frame.
Syntax:
[VB.NET]
Public FrameType As FrameType

[C#]
public FrameType FrameType
See also: UserFrame, FrameType

<< UserFrame


UserFrame::Ptr

UserFrame.Ptr Property
Returns a pointer to the image data.
Syntax:
[C#]
public byte* Ptr;
Remarks:

Please note, that depending upon the frame type, images may be stored bottom up, therefore the pointer returned by this method may point to the first byte of the first pixel of the last line of the image.

You can get information about how to interpret the data by examining IFrame.FrameType.

See also: UserFrame, UserFrame.FrameType, UserFrame.GetIntPtr

<< UserFrame


UserFrame::SampleEndTime

UserFrame.SampleEndTime Property
Returns the reference end time of the sample represented by the UserFrame.
Syntax:
[VB.NET]
Public SampleEndTime As Double

[C#]
public double SampleEndTime;
Limitations:

Read only.
Remarks:

The SampleEndTime property returns the reference time in seconds at which the sample ended.

See also: UserFrame

<< UserFrame


UserFrame::SampleStartTime

UserFrame.SampleStartTime Property
Returns the reference start time of the sample represented by the UserFrame.
Syntax:
[VB.NET]
Public SampleStartTime As Double

[C#]
public double SampleStartTime;
Limitations:

Read only.
Remarks:

The SampleStartTime property returns the reference time the sample started in seconds.

See also: UserFrame

<< UserFrame


UserFrame::CopyFrom

UserFrame.CopyFrom Method
Copies the image data from a specified IFrame to this UserFrame. This Method must be implemented in a class which implements UserFrame.
Syntax:
[VB.NET]
Public Function CopyFrom(Src As IFrame)

[C#]
public void CopyFrom(IFrame^ Src);

Parameter | Description
Src | Source frame containing the image data to be copied to this frame. FrameType.BufferSize has to be greater than or equal to Src.FrameType.BufferSize.
See also: UserFrame

<< UserFrame


UserFrame::GetIntPtr

UserFrame.GetIntPtr Method
Returns the pointer to the image data of this frame as an IntPtr. This Method must be implemented in a class which implements UserFrame.
Syntax:
[VB.NET]
Public Function GetIntPtr() As IntPtr

[C#]
public IntPtr GetIntPtr();
Return value:

A pointer to the image data.

Remarks:

Please note that depending upon the frame type, images may be stored bottom up, therefore the pointer returned by this method may point to the first byte of the first pixel of the last line of the image.

You can get information about how to interpret the data by examining UserFrame.FrameType.

See also: UserFrame, UserFrame.FrameType, UserFrame.Ptr

<< UserFrame


UserFrame::UserFrame

UserFrame.UserFrame Method
Creates a new instance of an Userframe.
Syntax:
[VB.NET]
Public new UserFrame(type As FrameType, data as IntPtr) As UserFrame

[C#]
public UserFrame(FrameType type, byte* data);
public UserFrame(FrameType type, IntPtr data);

Parameter | Description
type | Specifies the FrameType of the UserFrame.
data | Specifies the data pinter.
See also: UserFrame

<< UserFrame


New Enumerations

List of all enumerations that have been introduced in IC Imaging Control 3.1

refenum.StandardContainer

StandardContainer enumerates the available MediaStreamContainer.

refenum.EventExecutionMode

The EventExecutionMode enumeration describes the possible execution modes of an event, such as the ICImagingControl.ImageAvailable event.

<< New Features Reference


refenum::StandardContainer

refenum.StandardContainer
StandardContainer enumerates the available MediaStreamContainer.
Name | Description
AviContainer | The AVI container format.
OGMContainer | Media Stream Container Format that was developed by the Vorbis dev team. The project is currently set to hold, therefore, it is better to use Matroska (see below).
MatroskaContainer | Media Stream Container Format that was developed to replace avi with an open source multi stream format. See http://www.matroska.org for further information. Currently used for videos with multiple subtitles and/or audio streams, which are not encoded in MPEG2 or windows media.

<< Enumerations


refenum::EventExecutionMode

refenum.EventExecutionMode
The EventExecutionMode enumeration describes the possible execution modes of an event, such as the ICImagingControl.ImageAvailable event.
Name | Description
MultiThreaded | The event is executed on a thread provided by IC Imaging Control. It is not possible to access UI controls from this thread. Trying this will generate an InvalidOperationException. If this execution mode is in use, then Delegates must be used to access controls on the form.
Invoke | The event is executed on the UI thread that owns the ICImagingControl instance. Other UI controls can be accessed from this thread. However, if an exception occurred, the debugger does not break. Instead, the text of the exception is written to the debug output window. If this execution mode is in use, then no Delegates must be used to access controls on the form.
AsyncInvoke | The event is executed on the UI thread that owns the ICImagingControl instance. Other UI controls from this thread. However, if an exception occurred, the debugger does not break. Instead, the text of the exception is written to the debug output window. If this execution mode is in use, then no Delegates must be used to access controls on the form. When using the AsyncInvoke event execution mode, the event source does not wait until the event has been handled. This implies that more events of the same type can be queued. An application using this mode should not perform time consuming computations in frequently occuring asynchronuously executed events.
See also: ICImagingControl.ImageAvailable, ICImagingControl.ImageAvailableExecutionMode

<< Enumerations


What is new in version 3.0 since version 2.0

Description of the changes from IC Imaging Control 2.0 to IC Imaging Control 3.0.

Frame Filter

With frame filters, a versatile and powerful way to manipulate image data has been introduced. Frame filters can be used to do:

  • control which frames will be removed (dropped) from the image stream
  • read and write image data to/from frames of the image stream without having to copy the image data to a ring buffer. In other words: the frame filter allows image processing directly on buffers of the image stream (DirectShow buffers).
  • to change the video format (pixel format and/or width and height) of the image stream
  • implement image processing

Frame filters can be applied to the video stream at 3 locations: directly behind the video capture device, in front of the display and in front of the sink. This concept allows various functions to be implemented, such as a gate filter that passes only specific frames to a media file and drops the other ones. Frame filters can be implemented as part of an application or may reside in a filter container module. IC Imaging Control 3.0 comes with a few often used frame filters that can be loaded from the filter container module stdfilters.ftf:

  • ROI filter: changes the width and height of the image stream
  • DeBayer filter: transforms color raw data in Bayer format into an RGB color format.
  • Flip and rotation filter: Allows the image stream to be rotated (90°, 180° and 270°) and flipped (vertically and horizontally)
  • Denoise Filter: sums up a specified number of frames and divides the result by the number.

For details on the filters that come with IC Imaging Control, please refer to the chapter: IC Imaging Control Standard Filters.

Please note that frame filters cannot be implemented in Visual Basic. They have to be implemented in Visual C++ as part of a filter module.

New Sink Concept

IC Imaging Control 3.0 introduces a new sink concept. For an overview of sinks and image streams, please refer to Concepts and Components. Up to this version, sinks were used and managed internally to provide the functionality of accessing image buffers, using FrameReady Events and writing AVI files. There are two new sink objects:

  • FrameHandlerSink: This sink provides asynchronous grabbing of a specific number of images to the ring buffer and allows frame filters to be used in order to manipulate image data and control the copy process to the ring buffer collection. Using a frame filter, it is possible to create a ring buffer with a user defined pixel organization or omit the ring buffer collection totally by doing image processing directly on the buffers of the image stream (DirectShow buffers)
  • MediaStreamSink: This sink allows other stream containers than AVI to be used. For a description of the currently supported stream containers, please refer to MediaStreamContainer. In addition, the MediaStreamSink allows frame filters to be used in order to manipulate image data and control which frames are written to the stream file. This allows, for example, real time lapse functionality to be implemented.

Advanced Overlay Concept

Instead of having one overlay in the image stream just behind the device, IC Imaging Control 3.0 now allows up to 3 overlay objects to be used. The 3 possible locations are:

  • Behind the device: this overlay will appear in the display as well as in the sink (ring buffer, stream file).
  • In front of the display: this overlay will appear in the display only.
  • In front of the sink: this overlay will appear in the sink (ring buffer, stream file) only.

This new concept, for example, allows you to have an overlay on the display, while doing image processing on the original image data or having different overlays on the display and on the sink (ring buffer and stream file).

Support for Raw Color Data in Bayer Format

Using IC Imaging Conrol 3.0, it is possible to apply color interpolation to raw image data in Bayer format. The color interpolation is called debayering and may be applied to the display, as well as to the data that goes to the sink (ring buffer and stream file). For details, please refer to the chapter Debayering.

Support for 16 bit Monochrome Formats

IC Imaging Control 3.0 now supports high resolution monochrome and raw color (Bayer) formats with a pixel depth of up to 16 bit. A suitable display mode for all these formats is provided. For information about which high resolution formats are supported and how their image data is organized, please refer to the YGB0 format and YGB1 format.

New Features Reference

List of all new features

<< What's New


New Features Reference

List of all new features

Extended Classes

List of all classes that have been extended in IC Imaging Control 3.0

New Classes

List of all classes that have been introduced in IC Imaging Control 3.0

New Enumerations

List of all enumerations that have been introduced in IC Imaging Control 3.0

<< What is new in version 3.0 since version 2.0


Extended Classes

List of all classes that have been extended in IC Imaging Control 3.0

New Methods of ICImagingControl

List of properties and methods that have been added to the ICImagingControl class in IC Imaging Control 3.0

New Methods of ImageBuffer

List of properties and methods that have been added to the ImageBuffer class in IC Imaging Control 3.0

New Methods of OverlayBitmap

List of properties and methods that have been added to the OverlayBitmap class in IC Imaging Control 3.0

<< New Features Reference


New Methods of ICImagingControl

List of properties and methods that have been added to the ICImagingControl class in IC Imaging Control 3.0

ICImagingControl.Sink

Sets or retrieves the currently used sink. A sink is an object that receives the frames coming from the video capture device and either copies them to an ImageBuffers collection or saves them to a media stream file.

ICImagingControl.FrameFilterPath

Sets a path from which frame filters are loaded.

ICImagingControl.FrameFilterInfos

This property returns a list, containing FrameFilterInfo objects that describe the available frame filters, which can be loaded from frame filter modules (.ftf files).

ICImagingControl.FrameFilterCreate

Creates a new instance of a FrameFilter from a FrameFilterInfo.

ICImagingControl.DeviceFrameFilters

The DeviceFrameFilters property provides a FrameFilters collection that contains the frame filters that are inserted in the device path.

ICImagingControl.LiveDisplayOutputWidth

Returns the actual width of the video format of the live display. Due to the use of frame filters, this width can differ from the width of the video capture device's video format and the sink's format.

ICImagingControl.LiveDisplayOutputHeight

Returns the actual height of the video format of the live display. Due to the use of frame filters, this height can differ from the height of the video capture device's video format and the sink's format.

ICImagingControl.ImageActiveBuffer

Returns the ImageBuffer to which the control copied the last frame.

ICImagingControl.DeBayerActive

Returns whether automatic de-bayering of BY8 image data is enabled.

ICImagingControl.DeBayerStartPattern

This property controls how the automatic de-bayering of BY8 image data should treat the pixel data.

ICImagingControl.DeBayerMode

This property selects the algorithm used to de-bayer BY8 image data.

ICImagingControl.OverlayBitmapPosition

This property controls the positions of OverlayBitmap objects in the image stream.

ICImagingControl.DisplayFrameFilters

The DisplayFrameFilters property provides a FrameFilters collection that contains the frame filters that are inserted in the display path.

ICImagingControl.OverlayBitmapAtPath

Returns the OverlayBitmap at a specified path position.

ICImagingControl.LiveShowLastBuffer

This property controls whether IC Imaging Control displays the buffer that was captured on LiveStop when LiveCaptureLastImage is enabled.

<< Extended Classes


ICImagingControl::Sink

ICImagingControl.Sink Property
Sets or retrieves the currently used sink. A sink is an object that receives the frames coming from the video capture device and either copies them to an ImageBuffers collection or saves them to a media stream file.
Syntax:
[VB.NET]
Public Sink As BaseSink

[C#]
public BaseSink Sink;
Limitations:

Run time only. Read only in live mode.

Remarks:

Available sink implementations are FrameHandlerSink and MediaStreamSink
Information:

Introduced in version 3.0
See also: ICImagingControl, BaseSink, MediaStreamSink, FrameHandlerSink

<< ICImagingControl


ICImagingControl::FrameFilterPath

ICImagingControl.FrameFilterPath Property
Sets a path from which frame filters are loaded.
Syntax:
[VB.NET]
Public FrameFilterPath As String

[C#]
public String FrameFilterPath;
Limitations:

Write only.

Remarks:

By default, frame filters are loaded from the directory of ICImagingControl.ocx. This property can be used to set more than one path.

Information:

Introduced in version 3.0
Example:

The following code fragment sets a frame filter path and displays a list of all frame filters that can be loaded:

[C#]
ICImagingControl1.FrameFilterPath = "..\filters\";

foreach( FrameFilterInfo info in ICImagingControl1.FrameFilterInfos )
{
    System.Diagnostics.Trace.WriteLine( "Found filter " + info.Name + " in " + info.ModulePath );
}

[VB.NET]
IcImagingControl1.FrameFilterPath = "..\filters\"

For Each info As FrameFilterInfo In IcImagingControl1.FrameFilterInfos
    System.Diagnostics.Trace.WriteLine("Found filter " + info.Name + " in " + info.ModulePath)
Next
See also: ICImagingControl, ICImagingControl.FrameFilterInfos

<< ICImagingControl


ICImagingControl::FrameFilterInfos

ICImagingControl.FrameFilterInfos Property
This property returns a list, containing FrameFilterInfo objects that describe the available frame filters, which can be loaded from frame filter modules (.ftf files).
Syntax:
[VB.NET]
Public FrameFilterInfos() As FrameFilterInfo

[C#]
public FrameFilterInfo[] FrameFilterInfos;
Limitations:

Ready only, run time only.

Information:

Introduced in version 3.0
Example:

The following code fragment displays a list of all frame filters that can be loaded:

[C#]
foreach( FrameFilterInfo info in ICImagingControl1.FrameFilterInfos )
{
    System.Diagnostics.Trace.WriteLine( "Found filter " + info.Name + " in " + info.ModulePath );
}

[VB.NET]
For Each info As FrameFilterInfo In IcImagingControl1.FrameFilterInfos
    System.Diagnostics.Trace.WriteLine("Found filter " + info.Name + " in " + info.ModulePath)
Next
See also: ICImagingControl, ICImagingControl.FrameFilterPath, FrameFilterInfo

<< ICImagingControl


ICImagingControl::FrameFilterCreate

ICImagingControl.FrameFilterCreate Method
Creates a new instance of a FrameFilter from a FrameFilterInfo.
Syntax:
[VB.NET]
Public Function FrameFilterCreate( Info As FrameFilterInfo ) As FrameFilter
Public Function FrameFilterCreate( FilterName As String ) As FrameFilter
Public Function FrameFilterCreate( FilterName As String, ModuleName As String ) As FrameFilter

[C#]
public FrameFilter FrameFilterCreate( FrameFilterInfo Info );
public FrameFilter FrameFilterCreate( string FilterName );
public FrameFilter FrameFilterCreate( string FilterName, string ModuleName );

Name | Description
Info | The FrameFilterInfo object describing the frame filter to be created.
FilterName | Name of the frame filter to be created.
ModuleName | Filter module from which the frame filter is loaded. Can be omitted.
Information:

Introduced in version 3.0
Example:

The following example shows how to create a FrameFilter instance from a FrameFilterInfo object:

[C#]
// Retrieve the first FrameFilterInfo object.
FrameFilterInfo info = ICImagingControl1.FrameFilterInfos[0];

// Create the frame filter to which the info object refers.
FrameFilter filter = ICImagingControl1.FrameFilterCreate( info );

// Set the  frame filter as the device frame filter.
ICImagingControl1.DeviceFrameFilters.Add( filter );

// Start live mode.
ICImagingControl1.LiveStart();

[VB.NET]
' Retrieve the first FrameFilterInfo object.
Dim info As FrameFilterInfo = IcImagingControl1.FrameFilterInfos(0)

' Create the frame filter to which the info object refers.
Dim filter As FrameFilter = IcImagingControl1.FrameFilterCreate(info)

' Set the  frame filter as the device frame filter.
IcImagingControl1.DeviceFrameFilters.Add(filter)

' Start live mode.
IcImagingControl1.LiveStart()

The frame filter is set as a device frame filter.

The following code fragment shows how to create the DeBayer Filter from stdfilters.ftf:

[C#]
FrameFilter filter = ICImagingControl1.FrameFilterCreate("DeBayer", "");

[VB.NET]
Dim filter As FrameFilter = IcImagingControl1.FrameFilterCreate("DeBayer", "")
See also: ICImagingControl, ICImagingControl.FrameFilterInfos, FrameFilter, FrameFilterInfo

<< ICImagingControl


ICImagingControl::DeviceFrameFilters

ICImagingControl.DeviceFrameFilters Property
The DeviceFrameFilters property provides a FrameFilters collection that contains the frame filters that are inserted in the device path.
Syntax:
[VB.NET]
Public DeviceFrameFilters As FrameFilters

[C#]
public FrameFilters DeviceFrameFilters;
Limitations:

Ready only, run time only.

Information:

Introduced in version 3.0
See also: ICImagingControl, ICImagingControl.DisplayFrameFilters, FrameFilter

<< ICImagingControl


ICImagingControl::LiveDisplayOutputWidth

ICImagingControl.LiveDisplayOutputWidth Property
Returns the actual width of the video format of the live display. Due to the use of frame filters, this width can differ from the width of the video capture device's video format and the sink's format.
Syntax:
[VB.NET]
Public LiveDisplayOutputWidth As Integer

[C#]
public int LiveDisplayOutputWidth;
Limitations:

Ready only, run time only.

Remarks:

This property only returns valid values when either live mode has been started, or SinkCompatibilityMode is True.

Information:

Introduced in version 3.0
See also: ICImagingControl, ICImagingControl.LiveDisplayOutputHeight

<< ICImagingControl


ICImagingControl::LiveDisplayOutputHeight

ICImagingControl.LiveDisplayOutputHeight Property
Returns the actual height of the video format of the live display. Due to the use of frame filters, this height can differ from the height of the video capture device's video format and the sink's format.
Syntax:
[VB.NET]
Public LiveDisplayOutputHeight As Integer

[C#]
public int LiveDisplayOutputHeight;
Limitations:

Ready only, run time only.

Remarks:

This property only returns valid values when either live mode has been started, or SinkCompatibilityMode is True.

Information:

Introduced in version 3.0
See also: ICImagingControl, ICImagingControl.LiveDisplayOutputWidth

<< ICImagingControl


ICImagingControl::ImageActiveBuffer

ICImagingControl.ImageActiveBuffer Property
Returns the ImageBuffer to which the control copied the last frame.
Syntax:
[VB.NET]
Public ImageActiveBuffer As ImageBuffer

[C#]
public ImageBuffer ImageActiveBuffer;
Limitations:

Read only, Run time only.
Information:

Introduced in version 3.0
See also: ICImagingControl, ICImagingControl.ImageBuffers, ImageBuffer

<< ICImagingControl


ICImagingControl::DeBayerActive

ICImagingControl.DeBayerActive Property
Returns whether automatic de-bayering of BY8 image data is enabled.
Syntax:
[VB.NET]
Public DeBayerActive As Boolean

[C#]
public bool DeBayerActive;
Limitations:

Ready only, run time only.

Remarks:

When this property returns True, ICImagingControl.DeBayerStartPattern and ICImagingControl.DeBayerMode can be used to configure the de-bayering algorithm.

Information:

Introduced in version 3.0
See also: ICImagingControl, Debayering

<< ICImagingControl


ICImagingControl::DeBayerStartPattern

ICImagingControl.DeBayerStartPattern Property
This property controls how the automatic de-bayering of BY8 image data should treat the pixel data.
Syntax:
[VB.NET]
Public DeBayerStartPattern As DeBayerStartPatterns

[C#]
public DeBayerStartPatterns DeBayerStartPattern;
Remarks:

You have to select the value that matches the layout of the camera's mosaic filter in front of the CCD. In general, this has to be found out by trial and error, because this information may be hard to find in the camera's documentation.

Information:

Introduced in version 3.0
Example:

The following code fragment shows how to open a bayer camera, set the bayer video format BY8 and set the parameters for automatic de-bayering:

[C#]
ICImagingControl1.Device = "DBK 31BF03";
ICImagingControl1.VideoFormat = "BY8 (1024x768)";
ICImagingControl1.DeBayerStartPattern = DeBayerStartPatterns.GB;
ICImagingControl1.DeBayerMode = DeBayerModes.Edgesensing;

ICImagingControl1.LiveStart();

[VB.NET]
IcImagingControl1.Device = "DBK 31BF03"
IcImagingControl1.VideoFormat = "BY8 (1024x768)"
IcImagingControl1.DeBayerStartPattern = DeBayerStartPatterns.GB
IcImagingControl1.DeBayerMode = DeBayerModes.Edgesensing

IcImagingControl1.LiveStart()
See also: ICImagingControl, DeBayerStartPatterns, DeBayerModes, Debayering

<< ICImagingControl


ICImagingControl::DeBayerMode

ICImagingControl.DeBayerMode Property
This property selects the algorithm used to de-bayer BY8 image data.
Syntax:
[VB.NET]
Public DeBayerMode As DeBayerModes

[C#]
public DeBayerModes DeBayerMode;
Information:

Introduced in version 3.0
Example:

See DeBayerStartPattern for an example how of to configure the automatic de-bayering.

See also: ICImagingControl, DeBayerModes, Debayering

<< ICImagingControl


ICImagingControl::OverlayBitmapPosition

ICImagingControl.OverlayBitmapPosition Property
This property controls the positions of OverlayBitmap objects in the image stream.
Syntax:
[VB.NET]
Public OverlayBitmapPosition As PathPositions

[C#]
public PathPositions OverlayBitmapPosition;
Information:

Introduced in version 3.0
See also: ICImagingControl, PathPositions

<< ICImagingControl


ICImagingControl::DisplayFrameFilters

ICImagingControl.DisplayFrameFilters Property
The DisplayFrameFilters property provides a FrameFilters collection that contains the frame filters that are inserted in the display path.
Syntax:
[VB.NET]
Public DisplayFrameFilters As FrameFilters

[C#]
public FrameFilters DisplayFrameFilters;
Limitations:

Ready only, run time only.

Information:

Introduced in version 3.0
See also: ICImagingControl, ICImagingControl.DeviceFrameFilters, FrameFilter

<< ICImagingControl


ICImagingControl::OverlayBitmapAtPath

ICImagingControl.OverlayBitmapAtPath Property
Returns the OverlayBitmap at a specified path position.
Syntax:
[VB.NET]
Public OverlayBitmapAtPath( OverlayToFetch As PathPosition ) As OverlayBitmap

[C#]
public OverlayBitmap OverlayBitmapAtPath[ PathPosition OverlayToFetch ];
Limitations:

Ready only, run time only.

Information:

Introduced in version 3.0
See also: ICImagingControl, OverlayBitmap, PathPositions

<< ICImagingControl


ICImagingControl::LiveShowLastBuffer

ICImagingControl.LiveShowLastBuffer Property
This property controls whether IC Imaging Control displays the buffer that was captured on LiveStop when LiveCaptureLastImage is enabled.
Syntax:
[VB.NET]
Public LiveShowLastBuffer As Boolean

[C#]
public bool LiveShowLastBuffer;
Information:

Introduced in version 3.0
See also: ICImagingControl

<< ICImagingControl


New Methods of ImageBuffer

List of properties and methods that have been added to the ImageBuffer class in IC Imaging Control 3.0

ImageBuffer.FrameType

Returns a FrameType object describing the image format of this ImageBuffer.

<< Extended Classes


ImageBuffer::FrameType

ImageBuffer.FrameType Property
Returns a FrameType object describing the image format of this ImageBuffer.
Syntax:
[VB.NET]
Public FrameType As FrameType

[C#]
public FrameType FrameType;
Information:

Introduced in version 3.0
See also: ImageBuffer, FrameType

<< ImageAvailableEventArgs.ImageBuffer


New Methods of OverlayBitmap

List of properties and methods that have been added to the OverlayBitmap class in IC Imaging Control 3.0

OverlayBitmap.PathPosition

Returns the path position of this OverlayBitmap.

OverlayBitmap.ColorMode

Set the color mode of this OverlayBitmap. The color mode determines whether the overlay bitmap is painted in color or in grayscale. The images provided by the video capture device are converted into the selected format before drawing the overlay.

OverlayBitmap.OverlayFrameType

This property returns the actual image format of the overlay bitmap.

<< Extended Classes


OverlayBitmap::PathPosition

OverlayBitmap.PathPosition Property
Returns the path position of this OverlayBitmap.
Syntax:
[VB.NET]
Public PathPosition As PathPositions

[C#]
public PathPositions PathPosition;
Information:

Introduced in version 3.0
See also: OverlayBitmap, PathPositions

<< ICImagingControl.OverlayBitmap


OverlayBitmap::ColorMode

OverlayBitmap.ColorMode Property
Set the color mode of this OverlayBitmap. The color mode determines whether the overlay bitmap is painted in color or in grayscale. The images provided by the video capture device are converted into the selected format before drawing the overlay.
Syntax:
[VB.NET]
Public ColorMode As OverlayColorModes

[C#]
public OverlayColorModes ColorMode;
Information:

Introduced in version 3.0
Example:

The following code fragment shows how to draw colored overlay graphics on grayscale live video:

[C#]

// Set a grayscale video format.
ICImagingControl1.VideoFormat = "Y800 (1024x768)";

// Enable the overlay bitmap.
ICImagingControl1.OverlayBitmap.Enable = true;

// Force the overlay bitmap to operate in color mode.
ICImagingControl1.OverlayBitmap.ColorMode = OverlayColorModes.Color;

// Start live video.
ICImagingControl1.LiveStart();

ICImagingControl1.OverlayBitmap.Fill( ICImagingControl1.OverlayBitmap.DropOutColor );

// Draw a red line.
ICImagingControl1.OverlayBitmap.DrawLine( Color.Red, 0, 0, 100, 100 );

ICImagingControl1.LiveStart();

[VB.NET]

' Set a grayscale video format.
IcImagingControl1.VideoFormat = "Y800 (1024x768)"

' Enable the overlay bitmap.
IcImagingControl1.OverlayBitmap.Enable = True

' Force the overlay bitmap to operate in color mode.
IcImagingControl1.OverlayBitmap.ColorMode = OverlayColorModes.Color

' Start live video.
IcImagingControl1.LiveStart()

IcImagingControl1.OverlayBitmap.Fill(IcImagingControl1.OverlayBitmap.DropOutColor)

' Draw a red line.
IcImagingControl1.OverlayBitmap.DrawLine(Color.Red, 0, 0, 100, 100)
See also: OverlayBitmap, OverlayColorModes

<< ICImagingControl.OverlayBitmap


OverlayBitmap::OverlayFrameType

OverlayBitmap.OverlayFrameType Property
This property returns the actual image format of the overlay bitmap.
Syntax:
[VB.NET]
Public OverlayFrameType As FrameType

[C#]
public FrameType OverlayFrameType;
Limitations:

Read only.

Information:

Introduced in version 3.0
See also: OverlayBitmap, FrameType

<< ICImagingControl.OverlayBitmap


New Classes

List of all classes that have been introduced in IC Imaging Control 3.0

BaseSink

IFrame

Interface to an image buffer.

FrameFilter

FrameFilterImpl

A new frame filter must be derived from this class.

FrameFilterInfo

A FrameFilterInfo object contains information about a frame filter that can be loaded from a frame filter module and instantiated, using ICImagingControl.FrameFilterCreate.

FrameFilters

The FrameFilters class represents a chain of FrameFilter objects, that are used to transform the image data along the Device Path, Sink Path and Display Path.

FrameHandlerSink

The FrameHandlerSink is the SinkType used to grab (copy) frames from the image stream. It contains an ImageBuffer collection and optionally allows you to specify one or more FrameFilters that are responsible for copying the image data to the ImageBuffers. The FrameFilter implementation can perform user-defined transformations while copying the data, and they can intentionally drop unwanted frames. If no frame filter is registered, the frames are copied to the ImageBuffer collection without being changed.

FrameType

A FrameType describes the color format and (optionally) dimensions and buffer size of the image format of ImageBuffer objects.

FrameTypes

The FrameTypes collection is used to define a list of FrameTypes. A FrameTypes collection is used, i.e. to determine which FrameTypes are accepted by a frame filter or a sink.

MediaStreamContainer

A MediaStreamContainer describes a video file format. The most common video file format is AVI.

MediaStreamSink

The MediaStreamSink allows video files to be recorded in a more sophisticated manor than is possible using AviStartCapture and AviStopCapture. However, for simple tasks, the methods AviStartCapture and AviStopCapture are better suited, as they are really easy to use. A MediaStreamSink can save image data to video files in various formats and optionally allows you to specify one or more FrameFilters that can analyze and/or transform the image data, before it is written to the video file.

<< New Features Reference


BaseSink

This is the abstract base class for all sinks which cannot be instantiated. A sink specifies the format to which the image stream is converted and it specifies the way in which single frames may be accessed.

Example

The following example illustrates how to use the BaseSink type, when handling a sink object whose actual type is unknown:

[C#]
private void CaptureImageSequence( ICImagingControl ic )
{
    // Save the currently set sink object, using a BaseSink reference.
    BaseSink oldSink = ic.Sink;

    // Create a new sink object.
    FrameHandlerSink fhs = new FrameHandlerSink();

    // Initialize the new sink.
    fhs.BufferCount = 10;

    // Set the new sink.
    ic.Sink = fhs;

    // Use the new sink.
    ic.LiveStart();
    fhs.SnapImageSequence( 10, -1 );
    // ...
    ic.LiveStop();

    // Restore the old sink.
    ic.Sink = oldSink;
}

[VB.NET]
Private Sub CaptureImageSequence(ByVal IC As ICImagingControl)

    ' Save the currently set sink object, using a BaseSink reference.
    Dim oldSink As BaseSink
    oldSink = IC.Sink

    ' Create a new sink object.
    Dim fhs As New FrameHandlerSink

    ' Initialize the new sink.
    fhs.BufferCount = 10

    ' Set the new sink.
    IC.Sink = fhs

    ' Use the new sink.
    IC.LiveStart()
    fhs.SnapImageSequence(10, -1)
    ' ...
    IC.LiveStop()

    ' Restore the old sink.
    IC.Sink = oldSink
End Sub

Information

Namespace: TIS.Imaging
Introduced in version 3.0

Inheritance

BaseSink
FrameHandlerSink
MediaStreamSink

Properties

Property | Description
SinkModeRunning | Gets or sets the "running" state of the sink.

<< Classes


BaseSink::SinkModeRunning

BaseSink.SinkModeRunning Property
Gets or sets the "running" state of the sink.
Syntax:
[VB.NET]
Public SinkModeRunning As Boolean

[C#]
public bool SinkModeRunning;
Remarks:

This method is used to pause and restart an image stream for video capturing and frame grabbing. After the running mode is set to False, frame grabbing and video saving will not start before the running mode is set to True.

If the running mode is set to False and LiveStart is called, the live video is displayed (if enabled) but no frames are passed to the sink. Now, an application can set the running mode to True to start video capturing or frame grabbing without latency because the image stream is already initialized.

See also: BaseSink

<< BaseSink


IFrame

Interface to an image buffer.

Information

Namespace: TIS.Imaging
Introduced in version 3.0

Properties

Property | Description
FrameType | Returns the frame type of this frame.
Ptr | Returns a pointer to the image data.
SampleEndTime | Returns the reference end time of the sample represented by the IFrame.
SampleStartTime | Returns the reference start time of the sample represented by the IFrame.

Methods

Method | Description
CopyFrom | Copies the image data from a specified IFrame to this IFrame.
GetIntPtr | Returns the pointer to the image data of this frame as an IntPtr.

<< Classes


IFrame::FrameType

IFrame.FrameType Property
Returns the frame type of this frame.
Syntax:
[VB.NET]
Public FrameType As FrameType

[C#]
public FrameType FrameType
See also: IFrame, FrameType

<< IFrame


IFrame::Ptr

IFrame.Ptr Property
Returns a pointer to the image data.
Syntax:
[C#]
public byte* Ptr;
Remarks:

Please note, that depending upon the frame type, images may be stored bottom up, therefore the pointer returned by this method may point to the first byte of the first pixel of the last line of the image.

You can get information about how to interpret the data by examining IFrame.FrameType.

See also: IFrame, IFrame.FrameType, IFrame.GetIntPtr

<< IFrame


IFrame::SampleEndTime

IFrame.SampleEndTime Property
Returns the reference end time of the sample represented by the IFrame.
Syntax:
[VB.NET]
Public SampleEndTime As Double

[C#]
public double SampleEndTime;
Limitations:

Read only.
Remarks:

The SampleEndTime property returns the reference time in seconds at which the sample ended.

See also: IFrame

<< IFrame


IFrame::SampleStartTime

IFrame.SampleStartTime Property
Returns the reference start time of the sample represented by the IFrame.
Syntax:
[VB.NET]
Public SampleStartTime As Double

[C#]
public double SampleStartTime;
Limitations:

Read only.
Remarks:

The SampleStartTime property returns the reference time the sample started in seconds.

See also: IFrame

<< IFrame


IFrame::CopyFrom

IFrame.CopyFrom Method
Copies the image data from a specified IFrame to this IFrame.
Syntax:
[VB.NET]
Public Function GetIntPtr() As IntPtr

[C#]
public IntPtr GetIntPtr();

Parameter | Description
Src | Source frame containing the image data to be copied to this frame. FrameType.BufferSize has to be greater than or equal to Src.FrameType.BufferSize.
See also: IFrame

<< IFrame


IFrame::GetIntPtr

IFrame.GetIntPtr Method
Returns the pointer to the image data of this frame as an IntPtr.
Syntax:
[VB.NET]
Public Function GetIntPtr() As IntPtr

[C#]
public IntPtr GetIntPtr();
Return value:

A pointer to the image data.

Remarks:

Please note that depending upon the frame type, images may be stored bottom up, therefore the pointer returned by this method may point to the first byte of the first pixel of the last line of the image.

You can get information about how to interpret the data by examining IFrame.FrameType.

The example Accessing an Image Buffer shows how to access the image data in image buffers.

See also: IFrame, IFrame.FrameType, IFrame.Ptr

<< IFrame


FrameFilter

FrameFilter is the base class of all frame filters. It contains methods to access the filter's parameters, display a configuration dialog and save filter settings. This class provides the interface to use an existing filter.

To create a frame filter, use ICImagingControl.FrameFilterCreate.

Example

The following example illustrates how to create an instance of the first available frame filter and set it as device frame filter:

[C#]
// Retrieve the first FrameFilterInfo object.
FrameFilterInfo info = ICImagingControl1.FrameFilterInfos[0];

// Create the frame filter to which the info object refers.
FrameFilter filter = ICImagingControl1.FrameFilterCreate( info );

// Set the  frame filter as the device frame filter.
ICImagingControl1.DeviceFrameFilters.Add( filter );

// Start live mode.
ICImagingControl1.LiveStart();

[VB.NET]
' Retrieve the first FrameFilterInfo object.
Dim info As FrameFilterInfo = IcImagingControl1.FrameFilterInfos(0)

' Create the frame filter to which the info object refers.
Dim filter As FrameFilter = IcImagingControl1.FrameFilterCreate(info)

' Set the  frame filter as the device frame filter.
IcImagingControl1.DeviceFrameFilters.Add(filter)

' Start live mode.
IcImagingControl1.LiveStart()

Information

Namespace: TIS.Imaging
Introduced in version 3.0

Properties

Property | Description
AvailableParameters | Returns a list, containing the names of the available frame filter parameters.
FilterData | This property returns an XML formatted string, containing the current values of all parameters of this filter.
FilterInfo | Returns the FrameFilterInfo describing this filter.
HasDialog | Returns whether this frame filter has a built-in dialog that allows the user to modify the filter's parameters.
Name | Returns the name of this frame filter.

Methods

Method | Description
BeginParameterTransfer | BeginParameterTransfer and EndParameterTransfer synchronize the access to a frame filter's parameters.
EndParameterTransfer | BeginParameterTransfer and EndParameterTransfer synchronize the access to a frame filter's parameters.
GetBoolParameter | Gets a boolean parameter.
GetDataParameter | Gets a string parameter.
GetFloatParameter | Gets a float parameter.
GetIntParameter | Gets an integer parameter.
GetStringParameter | Gets a string parameter.
LoadFilterData | Loads filter settings from a file.
SaveFilterData | Saves the current values of all parameters of this filter in a file.
SetBoolParameter | Sets an boolean parameter.
SetDataParameter | Sets an data parameter.
SetFloatParameter | Sets an float parameter.
SetIntParameter | Sets an integer parameter.
SetStringParameter | Sets an string parameter.
ShowDialog | Displays a dialog that lets the user configure the filter.

<< Classes


FrameFilter::AvailableParameters

FrameFilter.AvailableParameters Property
Returns a list, containing the names of the available frame filter parameters.
Syntax:
[VB.NET]
Public AvailableParameters() As String

[C#]
public String[] AvailableParameters;
Limitations:

Read only.
See also: FrameFilter

<< FrameFilter


FrameFilter::FilterData

FrameFilter.FilterData Property
This property returns an XML formatted string, containing the current values of all parameters of this filter.
Syntax:
[VB.NET]
Public FilterData As String

[C#]
public string FilterData;
Remarks:

The string returned by this property can be set later to restore the filter's settings.

See also: FrameFilter, FrameFilter.SaveFilterData, FrameFilter.LoadFilterData

<< FrameFilter


FrameFilter::FilterInfo

FrameFilter.FilterInfo Property
Returns the FrameFilterInfo describing this filter.
Syntax:
[VB.NET]
Public FilterInfo As FrameFilterInfo

[C#]
public FrameFilterInfo FilterInfo;
See also: FrameFilter, FrameFilterInfo

<< FrameFilter


FrameFilter::HasDialog

FrameFilter.HasDialog Property
Returns whether this frame filter has a built-in dialog that allows the user to modify the filter's parameters.
Syntax:
[VB.NET]
Public HasDialog As Boolean

[C#]
public bool HasDialog;
Limitations:

Read only.
Remarks:

FrameFilter.ShowDialog only works when this method returns True.

See also: FrameFilter, FrameFilter.ShowDialog

<< FrameFilter


FrameFilter::Name

FrameFilter.Name Property
Returns the name of this frame filter.
Syntax:
[VB.NET]
Public Name As String

[C#]
public string Name;
Limitations:

Read only.
Remarks:

This method returns the same as FilterInfo.Name.

See also: FrameFilter, FrameFilter.FilterInfo

<< FrameFilter


FrameFilter::BeginParameterTransfer

FrameFilter.BeginParameterTransfer Method
BeginParameterTransfer and EndParameterTransfer synchronize the access to a frame filter's parameters.
Syntax:
[VB.NET]
Public Sub BeginParameterTransfer()

[C#]
public void BeginParameterTransfer();
Remarks:

This method acquires a lock that has to be released using EndParameterTransfer as soon as possible.

Example:

For an example of how to set or read parameters, see FrameFilter.SetIntParameter.

See also: FrameFilter, FrameFilter.EndParameterTransfer

<< FrameFilter


FrameFilter::EndParameterTransfer

FrameFilter.EndParameterTransfer Method
BeginParameterTransfer and EndParameterTransfer synchronize the access to a frame filter's parameters.
Syntax:
[VB.NET]
Public Sub EndParameterTransfer()

[C#]
public void EndParameterTransfer();
Example:

For an example of how to set or read parameters, see FrameFilter.SetIntParameter.

See also: FrameFilter, FrameFilter.BeginParameterTransfer

<< FrameFilter


FrameFilter::GetBoolParameter

FrameFilter.GetBoolParameter Method
Gets a boolean parameter.
Syntax:
[VB.NET]
Public Function GetBoolParameter( name As String ) As Boolean

[C#]
public bool GetBoolParameter( string name );

Parameter | Description
name | Name of the parameter to be set. To retrieve a list, containing the valid parameter names, use AvailableParameters.
Return Value:

The current value of the parameter.

Example:

For an example of how to set or read parameters, see FrameFilter.SetIntParameter.

See also: FrameFilter, FrameFilter.SetBoolParameter, FrameFilter.AvailableParameters

<< FrameFilter


FrameFilter::GetDataParameter

FrameFilter.GetDataParameter Method
Gets a string parameter.
Syntax:
[VB.NET]
Public Function GetDataParameter( name As String ) As Byte()

[C#]
public byte[] GetDataParameter( string name );

Parameter | Description
name | Name of the parameter to be set. To retrieve a list, containing the valid parameter names, use AvailableParameters.
Return Value:

The current value of the parameter.

Example:

For an example of how to set or read parameters, see FrameFilter.SetIntParameter.

See also: FrameFilter, FrameFilter.SetDataParameter, FrameFilter.AvailableParameters

<< FrameFilter


FrameFilter::GetFloatParameter

FrameFilter.GetFloatParameter Method
Gets a float parameter.
Syntax:
[VB.NET]
Public Function GetFloatParameter( name As String ) As Single

[C#]
public float GetFloatParameter( string name );

Parameter | Description
name | Name of the parameter to be set. To retrieve a list, containing the valid parameter names, use AvailableParameters.
Return Value:

The current value of the parameter.

Example:

For an example of how to set or read parameters, see FrameFilter.SetIntParameter.

See also: FrameFilter, FrameFilter.SetFloatParameter, FrameFilter.AvailableParameters

<< FrameFilter


FrameFilter::GetIntParameter

FrameFilter.GetIntParameter Method
Gets an integer parameter.
Syntax:
[VB.NET]
Public Function GetIntParameter( name As String ) As Integer

[C#]
public int GetIntParameter( string name );

Parameter | Description
name | Name of the parameter to be set. To retrieve a list, containing the valid parameter names, use AvailableParameters.
Return Value:

The current value of the parameter.

Example:

For an example of how to set or read parameters, see FrameFilter.SetIntParameter.

See also: FrameFilter, FrameFilter.SetIntParameter, FrameFilter.AvailableParameters

<< FrameFilter


FrameFilter::GetStringParameter

FrameFilter.GetStringParameter Method
Gets a string parameter.
Syntax:
[VB.NET]
Public Function GetStringParameter( name As String ) As String

[C#]
public string GetStringParameter( string name );

Parameter | Description
name | Name of the parameter to be set. To retrieve a list containing the valid parameter names, use AvailableParameters.
Return Value:

The current value of the parameter.

Example:

For an example of how to set or read parameters, see FrameFilter.SetIntParameter.

See also: FrameFilter, FrameFilter.SetStringParameter, FrameFilter.AvailableParameters

<< FrameFilter


FrameFilter::LoadFilterData

FrameFilter.LoadFilterData Method
Loads filter settings from a file.
Syntax:
[VB.NET]
Public Sub LoadFilterData( Filename As String )

[C#]
public void LoadFilterData( string Filename );
Remarks:

Filter settings files are created by FrameFilter.SaveFilterData.

See also: FrameFilter, FrameFilter.SaveFilterData, FrameFilter.FilterData

<< FrameFilter


FrameFilter::SaveFilterData

FrameFilter.SaveFilterData Method
Saves the current values of all parameters of this filter in a file.
Syntax:
[VB.NET]
Public Sub SaveFilterData( Filename As String )

[C#]
public void SaveFilterData( string Filename );
Remarks:

This method saves the string returned by FilterData in a file.

FrameFilter.LoadFilterData can be used to restore the saved data.

See also: FrameFilter, FrameFilter.LoadFilterData, FrameFilter.FilterData

<< FrameFilter


FrameFilter::SetBoolParameter

FrameFilter.SetBoolParameter Method
Sets an boolean parameter.
Syntax:
[VB.NET]
Public Sub SetBoolParameter( name As String, value As Boolean )

[C#]
public void SetBoolParameter( string name, bool value );

Parameter | Description
name | Name of the parameter to be set. To retrieve a list, containing the valid parameter names, use AvailableParameters.
value | New value of the parameter.
Example:

For an example of how to set or read parameters, see FrameFilter.SetIntParameter.

See also: FrameFilter, FrameFilter.GetBoolParameter, FrameFilter.AvailableParameters

<< FrameFilter


FrameFilter::SetDataParameter

FrameFilter.SetDataParameter Method
Sets an data parameter.
Syntax:
[VB.NET]
Public Sub SetDataParameter( name As String, value() As Byte )

[C#]
public void SetDataParameter( string name, byte[] value );

Parameter | Description
name | Name of the parameter to be set. To retrieve a list, containing the valid parameter names, use AvailableParameters.
value | New value of the parameter.
Example:

For an example of how to set or read parameters, see FrameFilter.SetIntParameter.

See also: FrameFilter, FrameFilter.GetDataParameter, FrameFilter.AvailableParameters

<< FrameFilter


FrameFilter::SetFloatParameter

FrameFilter.SetFloatParameter Method
Sets an float parameter.
Syntax:
[VB.NET]
Public Sub SetFloatParameter( name As String, value As Single )

[C#]
public void SetFloatParameter( string name, float value );

Parameter | Description
name | Name of the parameter to be set. To retrieve a list, containing the valid parameter names, use AvailableParameters.
value | New value of the parameter.
Example:

For an example of how to set or read parameters, see FrameFilter.SetIntParameter.

See also: FrameFilter, FrameFilter.GetFloatParameter, FrameFilter.AvailableParameters

<< FrameFilter


FrameFilter::SetIntParameter

FrameFilter.SetIntParameter Method
Sets an integer parameter.
Syntax:
[VB.NET]
Public Sub SetIntParameter( name As String, value As Integer )

[C#]
public void SetIntParameter( string name, int value );

Parameter | Description
name | Name of the parameter to be set. To retrieve a list, containing the valid parameter names, use AvailableParameters.
value | New value of the parameter.
Example:

The following example shows how to set the parameters of the Rotate Flip Filter. Please not that the access to the parameters is enclosed in BeginParameterTransfer and EndParameterTransfer.

[C#]
filter.BeginParameterTransfer();

filter.SetIntParameter( "Rotation Angle", 180 );
filter.SetBoolParameter( "Flip H", false );
filter.SetBoolParameter( "Flip V", false );

filter.EndParameterTransfer();

[VB.NET]
filter.BeginParameterTransfer()

filter.SetIntParameter("Rotation Angle", 180)
filter.SetBoolParameter("Flip H", False)
filter.SetBoolParameter("Flip V", False)

filter.EndParameterTransfer()
See also: FrameFilter, FrameFilter.GetIntParameter, FrameFilter.AvailableParameters

<< FrameFilter


FrameFilter::SetStringParameter

FrameFilter.SetStringParameter Method
Sets an string parameter.
Syntax:
[VB.NET]
Public Sub SetStringParameter( name As String, value As String )

[C#]
public void SetStringParameter( string name, string value );

Parameter | Description
name | Name of the parameter to be set. To retrieve a list, containing the valid parameter names, use AvailableParameters.
value | New value of the parameter.
Example:

For an example of how to set or read parameters, see FrameFilter.SetIntParameter.

See also: FrameFilter, FrameFilter.GetStringParameter, FrameFilter.AvailableParameters

<< FrameFilter


FrameFilter::ShowDialog

FrameFilter.ShowDialog Method
Displays a dialog that lets the user configure the filter.
Syntax:
[VB.NET]
Public Sub ShowDialog()

[C#]
public void ShowDialog();
Remarks:

You should only call this method, if HasDialog returns true.

See also: FrameFilter, FrameFilter.HasDialog

<< FrameFilter


FrameFilterImpl

A new frame filter must be derived from this class.

Implementation

A transform filter must at least implement following methods:

  • Transform
  • GetSupportedInputTypes
  • GetTransformOutputTypes

Following methods can be overridden for customized behavior:

  • NotifyStart
  • NotifyStop

To add a dialog box to the transform filter, following methods must be overridden:

  • HasDialog
  • ShowDialog

To register parameters that can be queried and modified using FrameFilter.AvailableParameters, FrameFilter.SetIntParameter, FrameFilter.GetIntParameter etc., use

  • AddBoolParam
  • AddIntParam
  • AddFloatParam
  • AddStringParam
  • AddDataParam

Take a look at Writing a Frame Filter: Binarization to see how to implement a frame filter.

Information

Namespace: TIS.Imaging
Introduced in version 3.0

Methods

Method | Description
AddBoolParam | Registers a boolean parameter than can be accessed using the methods of FrameFilter.
AddDataParam | Registers a data parameter than can be accessed using the methods of FrameFilter.
AddFloatParam | Registers a float parameter than can be accessed using the methods of FrameFilter.
AddIntParam | Registers a integer parameter than can be accessed using the methods of FrameFilter.
AddStringParam | Registers a string parameter than can be accessed using the methods of FrameFilter.
BeginParamTransfer | BeginParamTransfer and EndParamTransfer synchronize the access to a frame filter's parameters.
EndParamTransfer | BeginParamTransfer and EndParamTransfer synchronize access to a frame filter's parameters.
GetSupportedInputTypes | This method is called to request the types which this transform filter supports as input types.
GetTransformOutputTypes | This method is called to request the possible output types.
HasDialog | Returns whether this filter implementation has a configuration dialog.
NotifyStart | This method is called when the transformation process (live mode) is started.
NotifyStop | This method is called when the transformation process (live mode) is stopped.
ShowDialog | Displays a build-in configuration dialog.
Transform | This method is called when a frame must be transformed or copied from the source to the destination IFrame.

<< New Classes


FrameFilterImpl::AddBoolParam

FrameFilterImpl.AddBoolParam Method
Registers a boolean parameter than can be accessed using the methods of FrameFilter.
Syntax:
public delegate void SetBoolParam( bool value );
public delegate bool GetBoolParam();

protected void AddBoolParam( string name, SetBoolParam setFunc, GetBoolParam getFunc );

Name | Description
name | Name of the parameter. This string has to be passed to FrameFilter.SetBoolParameter or FrameFilter.GetBoolParameter to access the parameter.
getFunc | GetBoolParam delegates responsible to return the current state of the parameter.
setFunc | SetBoolParam delegates responsible to receive and handle changes of the parameter.
Remarks:

All parameters of a frame filter should be registered in its constructor.

Example:

For an example on how to register a parameter, see AddIntParam.

See also: FrameFilterImpl, FrameFilterImpl.AddIntParam, FrameFilterImpl.AddFloatParam, FrameFilterImpl.AddStringParam, FrameFilterImpl.AddDataParam

<< FrameFilterImpl


FrameFilterImpl::AddDataParam

FrameFilterImpl.AddDataParam Method
Registers a data parameter than can be accessed using the methods of FrameFilter.
Syntax:
public delegate void SetDataParam( byte[] value );
public delegate byte[] GetDataParam();

protected void AddDataParam( string name, SetDataParam setFunc, GetDataParam getFunc );

Name | Description
name | Name of the parameter. This string has to be passed to FrameFilter.SetDataParameter or FrameFilter.GetDataParameter to access the parameter.
getFunc | Delegate responsible to return the current state of the parameter.
setFunc | Delegate responsible to receive and handle changes of the parameter.
Remarks:

All parameters of a frame filter should be registered in its constructor.

See also: FrameFilterImpl, FrameFilterImpl.AddBoolParam, FrameFilterImpl.AddIntParam, FrameFilterImpl.AddFloatParam, FrameFilterImpl.AddStringParam

<< FrameFilterImpl


FrameFilterImpl::AddFloatParam

FrameFilterImpl.AddFloatParam Method
Registers a float parameter than can be accessed using the methods of FrameFilter.
Syntax:
public delegate void SetFloatParam( float value );
public delegate float GetFloatParam();

protected void AddFloatParam( string name, SetFloatParam setFunc, GetFloatParam getFunc );

Name | Description
name | Name of the parameter. This string has to be passed to FrameFilter.SetFloatParameter or FrameFilter.GetFloatParameter to access the parameter.
getFunc | GetFloatParam delegate responsible to return the current state of the parameter.
setFunc | SetFloatParam delegate responsible to receive and handle changes of the parameter.
Remarks:

All parameters of a frame filter should be registered in its constructor.

Example:

For an example on how to register a parameter, see AddIntParam.

See also: FrameFilterImpl, FrameFilterImpl.AddBoolParam, FrameFilterImpl.AddIntParam, FrameFilterImpl.AddStringParam, FrameFilterImpl.AddDataParam

<< FrameFilterImpl


FrameFilterImpl::AddIntParam

FrameFilterImpl.AddIntParam Method
Registers a integer parameter than can be accessed using the methods of FrameFilter.
Syntax:
public delegate void SetIntParam( int value );
public delegate int GetIntParam();

protected void AddIntParam( string name, SetIntParam setFunc, GetIntParam getFunc );

Name | Description
name | Name of the parameter. This string has to be passed to FrameFilter.SetIntParameter or FrameFilter.GetIntParameter to access the parameter.
getFunc | GetIntParam delegates responsible to return the current state of the parameter.
setFunc | SetIntParam delegates responsible to receive and handle changes of the parameter.
Remarks:

All parameters of a frame filter should be registered in its constructor.

Example:

The following sample code shows how to add two parameters. One is named "enable" and the other one, which is an int parameter is named "threshold":

[C#]
public BinarizationFilter()
{
    AddBoolParam("enable", new SetBoolParam(setEnable), new GetBoolParam(getEnable));
    AddIntParam("threshold", new SetIntParam(setThreshold), new GetIntParam(getThreshold));
}

The functions, that are referenced in AddIntParam to set the integer parameter are implemeted as follows:

[C#]
void setThreshold(int threshold)
{
    m_threshold = threshold;
}

[C#]
int getThreshold()
{
    return m_threshold;
}
See also: FrameFilterImpl, FrameFilterImpl.AddBoolParam, FrameFilterImpl.AddFloatParam, FrameFilterImpl.AddStringParam, FrameFilterImpl.AddDataParam

<< FrameFilterImpl


FrameFilterImpl::AddStringParam

FrameFilterImpl.AddStringParam Method
Registers a string parameter than can be accessed using the methods of FrameFilter.
Syntax:
public delegate void SetStringParam( string value );
public delegate string GetStringParam();

protected void AddStringParam( string name, SetStringParam setFunc, GetStringParam getFunc );

Name | Description
name | Name of the parameter. This string has to be passed to FrameFilter.SetStringParameter or FrameFilter.GetStringParameter to access the parameter.
getFunc | GetStringParam delegates responsible to return the current state of the parameter.
setFunc | SetStringParam delegates responsible to receive and handle changes of the parameter.
Remarks:

All parameters of a frame filter should be registered in its constructor.

Example:

For an example on how to register a parameter, see AddIntParam.

See also: FrameFilterImpl, FrameFilterImpl.AddBoolParam, FrameFilterImpl.AddIntParam, FrameFilterImpl.AddFloatParam, FrameFilterImpl.AddDataParam

<< FrameFilterImpl


FrameFilterImpl::BeginParamTransfer

FrameFilterImpl.BeginParamTransfer Method
BeginParamTransfer and EndParamTransfer synchronize the access to a frame filter's parameters.
Syntax:
[VB.NET]
Protected Sub BeginParamTransfer()

[C#]
protected void BeginParamTransfer();
Remarks:

This method acquires a lock that has to be released using EndParamTransfer as soon as possible.

See also: FrameFilterImpl, FrameFilterImpl.EndParamTransfer

<< FrameFilterImpl


FrameFilterImpl::EndParamTransfer

FrameFilterImpl.EndParamTransfer Method
BeginParamTransfer and EndParamTransfer synchronize access to a frame filter's parameters.
Syntax:
[VB.NET]
Protected Sub EndParamTransfer()

[C#]
protected void EndParamTransfer();
See also: FrameFilterImpl, FrameFilterImpl.BeginParamTransfer

<< FrameFilterImpl


FrameFilterImpl::GetSupportedInputTypes

FrameFilterImpl.GetSupportedInputTypes Method
This method is called to request the types which this transform filter supports as input types.
Syntax:
public void GetSupportedInputTypes( ArrayList frameTypes );

Parameter | Description
frameTypes | ArrayList that has to be filled with FrameType objects that represent the frame types this transform filter can handle.
See also: FrameFilterImpl, FrameType

<< FrameFilterImpl


FrameFilterImpl::GetTransformOutputTypes

FrameFilterImpl.GetTransformOutputTypes Method
This method is called to request the possible output types.
Syntax:
public bool GetTransformOutputTypes( FrameType inType, ArrayList outTypes );

Parameter | Description
inType | The FrameType of the frames passed in the input buffers.
outTypes | An ArrayList that has to be filled with FrameType objects that represent the frame types this transform filter may generate from the given inType.
Return Value:

Value | Description
true | The list with supported output types was filled.
false | No transformation available.
Remarks:

The types should be ordered according to preference of the transform operation. The output type of this transform filter will be chosen based on the capabilities and input preference of the next filter and this filter.

See also: FrameFilterImpl, FrameType

<< FrameFilterImpl


FrameFilterImpl::HasDialog

FrameFilterImpl.HasDialog Method
Returns whether this filter implementation has a configuration dialog.
Syntax:
[VB.NET]
Protected Function HasDialog() As Boolean

[C#]
protected bool HasDialog();
Remarks:

This methods should return True, if the current frame filter has a configuration dialog. Thus a calling application can check, whether a frame filter has a built-in configuration dialog.

The default implementation returns false.

See also: FrameFilterImpl, FrameFilterImpl.ShowDialog

<< FrameFilterImpl


FrameFilterImpl::NotifyStart

FrameFilterImpl.NotifyStart Method
This method is called when the transformation process (live mode) is started.
Syntax:
public void notifyStart( FrameType inType, FrameType outType );

Parameter | Description
inType | The input FrameType for the starting transform process.
outType | The output FrameType for the starting transform process.
Remarks:

If this method it called by the frame work due to the LiveStart call, all properties, e.g. video format, image size, pixel format etc are known. Thus in this method properties can be initilized, e.g. memory can be allocated or variables can be set if needed. It is a good method for preparation of image processing needed parameters.

The default implementation does nothing.

See also: FrameFilterImpl, FrameFilterImpl.NotifyStop

<< FrameFilterImpl


FrameFilterImpl::NotifyStop

FrameFilterImpl.NotifyStop Method
This method is called when the transformation process (live mode) is stopped.
Syntax:
public void NotifyStop();
Remarks:

The implementation of this method is a good place to free any resources that were allocated in NotifyStart.

The default implementation does nothing.

See also: FrameFilterImpl, FrameFilterImpl.NotifyStart

<< FrameFilterImpl


FrameFilterImpl::ShowDialog

FrameFilterImpl.ShowDialog Method
Displays a build-in configuration dialog.
Syntax:
[VB.NET]
Protected Sub ShowDialog()

[C#]
protected void ShowDialog();
Remarks:

This method must be overridden to implement the call for displaying a built-in configuration dialog.

See also: FrameFilterImpl, FrameFilterImpl.HasDialog

<< FrameFilterImpl


FrameFilterImpl::Transform

FrameFilterImpl.Transform Method
This method is called when a frame must be transformed or copied from the source to the destination IFrame.
Syntax:
[C#]
public bool Transform( IFrame src, IFrame dest );

Parameter | Description
src | Source frame. The source frame can not be overwritten or changed.
dest | Destination frame. This frame will receive the changes. If the destination frame was changed, the method shoud return True.
Return Value:

Value | Description
true | The transformation was successful.
false | Discard the frame.
Remarks:

The image data pointer returned by IFrame.Ptr may be null for the destination frame dest. In this case, no target for the copy operation is available, e.g. all buffers of the ImageBuffers are locked. The transform filter is called, because the implementation may need to analyze the input data.

See also: FrameFilterImpl, IFrame

<< FrameFilterImpl


FrameFilterInfo

A FrameFilterInfo object contains information about a frame filter that can be loaded from a frame filter module and instantiated, using ICImagingControl.FrameFilterCreate.

A list of FrameFilterInfo objects for all available frame filters can be obtained from ICImagingControl.FrameFilterInfos.

Information

Namespace: TIS.Imaging
Introduced in version 3.0

Properties

Property | Description
ModuleName | Returns the filename of the module from which the filter can be loaded.
ModulePath | Returns the complete path to the module from which the filter can be loaded.
Name | Returns the name of the frame filter.

<< Classes


FrameFilterInfo::ModuleName

FrameFilterInfo.ModuleName Property
Returns the filename of the module from which the filter can be loaded.
Syntax:
[VB.NET]
Public ModuleName As String

[C#]
public String ModuleName;
Limitations:

Read only.
See also: FrameFilterInfo, FrameFilterInfo.ModulePath

<< FrameFilterInfo


FrameFilterInfo::ModulePath

FrameFilterInfo.ModulePath Property
Returns the complete path to the module from which the filter can be loaded.
Syntax:
[VB.NET]
Public ModulePath As String

[C#]
public String ModulePath;
Limitations:

Read only.
See also: FrameFilterInfo, FrameFilterInfo.ModuleName

<< FrameFilterInfo


FrameFilterInfo::Name

FrameFilterInfo.Name Property
Returns the name of the frame filter.
Syntax:
[VB.NET]
Public Name As String

[C#]
public string Name;
Limitations:

Read only.
See also: FrameFilterInfo

<< FrameFilterInfo


FrameFilters

The FrameFilters class represents a chain of FrameFilter objects, that are used to transform the image data along the Device Path, Sink Path and Display Path.

Instances of FrameFilters can be accessed through ICImagingControl.DeviceFrameFilters, ICImagingControl.DisplayFrameFilters, MediaStreamSink.FrameFilters and FrameHandlerSink.FrameFilters.

The FrameFilters collection can not be modified when live mode is running.

Information

Namespace: TIS.Imaging
Introduced in version 3.0

Properties

Property | Description
Count | Returns the number of FrameFilter objects in the collection.
Item | Returns or sets the FrameFilter at the specified position.

Methods

Method | Description
Add | Inserts a FrameFilter object at the end of the collection.
Clear | Removes all FrameFilter objects from the collection.
Remove | Removes the FrameFilter at a specified position.

<< Classes


FrameFilters::Count

FrameFilters.Count Property
Returns the number of FrameFilter objects in the collection.
Syntax:
[VB.NET]
Public Count As Int

[C#]
Int Count;
Limitations:

Read only.
See also: FrameFilters, FrameFilter

<< FrameFilters


FrameFilters::Item

FrameFilters.Item Property
Returns or sets the FrameFilter at the specified position.
Syntax:
[VB.NET]
Public Item(Index As Integer) As FrameFilter

[C#]
public FrameFilter this[int Index];

Parameter | Description
Index | Specifies the Index of the FrameFilter to set or return. The Index must lie in int the range [1, FrameFilters.Count ], otherwise an error occurs.
Limitations:

Read only in live mode.

See also: FrameFilters, FrameFilters.Count, FrameFilter

<< FrameFilters


FrameFilters::Add

FrameFilters.Add Method
Inserts a FrameFilter object at the end of the collection.
Syntax:
[VB.NET]
Public Sub Add( Filter As FrameFilter )

[C#]
Public void Add( FrameFilter Filter );

Parameter | Description
Filter | Specifies the FrameFilter that is inserted into the collection.
Limitations:

Not available in live mode.

See also: FrameFilters, FrameFilters.Remove, FrameFilters.Clear

<< FrameFilters


FrameFilters::Clear

FrameFilters.Clear Method
Removes all FrameFilter objects from the collection.
Syntax:
[VB.NET]
Public Sub Clear()

[C#]
Public void Clear();
Limitations:

Not available in live mode.

See also: FrameFilters, FrameFilters.Add, FrameFilters.Remove

<< FrameFilters


FrameFilters::Remove

FrameFilters.Remove Method
Removes the FrameFilter at a specified position.
Syntax:
[VB.NET]
Public Sub Remove( Index As Integer )

[C#]
Public void Remove( int Index );

Parameter | Description
Index | Specifies the index of the FrameFilter to be removed.
Limitations:

Not available in live mode.

See also: FrameFilters, FrameFilters.Add, FrameFilters.Clear

<< FrameFilters


FrameHandlerSink

The FrameHandlerSink is the SinkType used to grab (copy) frames from the image stream. It contains an ImageBuffer collection and optionally allows you to specify one or more FrameFilters that are responsible for copying the image data to the ImageBuffers. The FrameFilter implementation can perform user-defined transformations while copying the data, and they can intentionally drop unwanted frames. If no frame filter is registered, the frames are copied to the ImageBuffer collection without being changed.

Frames are copied one after another to the ImageBuffer collection, starting with the first buffer of the collection. When a frame is copied into the last buffer, the next frame is copied to the first buffer and so on.

The FrameHandlerSink can operate in snap mode or in grab mode. The mode can be toggled by using the FrameHandlerSink.SnapMode property. In grab mode, frames are copied continuously to the ImageBuffers, as soon as ICImagingControl.LiveStart is called. A call to ICImagingControl.LiveStop ends the copy process. On the other hand, in snap mode, every call to FrameHandlerSink.SnapImage, FrameHandlerSink.SnapImageSequence or FrameHandlerSink.SnapImageSequenceAsync copies the specified number of frames to the ImageBuffers.

Information

Namespace: TIS.Imaging
Introduced in version 3.0

Inheritance

BaseSink
FrameHandlerSink

Properties

Property | Description
BufferCount | Returns and sets the number of buffers in FrameHandlerSink.ImageBuffers.
FrameCount | Returns the total number of frames that this sink processed since the last call of ICImagingControl.LiveStart.
FrameFilters | Returns a frame filter collection. The last filter in the collection is responsible to copy the image data to the Membuffer collection while the others are used to manipulate the image data that go to the sink.
FrameType | Returns the current used frame type of the sink.
FrameTypes | The FrameTypes collections allows the specification of valid image formats for the ImageBuffer collection.
ImageBuffers | Returns the collections of ImageBuffer objects in this sink.
LastAcquiredBuffer | Returns the ImageBuffer that contains the last captured frame.
SnapMode | Changes this sink's operating mode between Grab and Snap mode. In grab mode, all frames reaching the sink are presented to the frame filter or filter chain and then copied into the ImageBuffers. After that, the ICImagingControl.ImageAvailable event is raised. In snap mode, SnapImage, SnapImageSequence or SnapImageSequenceAsync has to be called in order to trigger the image acquisition process.

Methods

Method | Description
SnapImage | Queues up a snap job, thus allowing one frame to be copied into the ImageBuffer collection. The method returns when either the frame was snapped, or the timeout has occurred.
SnapImageSequence | Queues up a snap job, thus allowing a number of frames to be copied into the ImageBuffer collection. The method returns when either the specified number of frames are snapped, or the timeout has occurred.
SnapImageSequenceAsync | Queues up a snap job, thus copying a number of frames into the ImageBuffer collection. The method returns immediately after queuing the job.

<< Classes


FrameHandlerSink::BufferCount

FrameHandlerSink.BufferCount Property
Returns and sets the number of buffers in FrameHandlerSink.ImageBuffers.
Syntax:
[VB.NET]
Public BufferCount As Integer

[C#]
public int BufferCount;
See also: FrameHandlerSink

<< FrameHandlerSink


FrameHandlerSink::FrameCount

FrameHandlerSink.FrameCount Property
Returns the total number of frames that this sink processed since the last call of ICImagingControl.LiveStart.
Syntax:
[VB.NET]
Public FrameCount As Integer

[C#]
public int FrameCount;
Limitations:

Read only.
See also: FrameHandlerSink

<< FrameHandlerSink


FrameHandlerSink::FrameFilters

FrameHandlerSink.FrameFilters Property
Returns a frame filter collection. The last filter in the collection is responsible to copy the image data to the Membuffer collection while the others are used to manipulate the image data that go to the sink.
Syntax:
[VB.NET]
Public FrameFilters As FrameFilters

[C#]
public FrameFilters FrameFilters;
Limitations:

Read only.
See also: FrameHandlerSink, FrameFilters, FrameFilter

<< FrameHandlerSink


FrameHandlerSink::FrameType

FrameHandlerSink.FrameType Property
Returns the current used frame type of the sink.
Syntax:
[VB.NET]
Public FT As FrameType

[C#]
public FrameType FT;
Limitations:

Read only.
Remarks:

If only one frame type was added to the sink, then this property will return a value without calling ICImagingControl.LiveStart previously.

If only several frame types have been added to the sink, then this property is null until ICImagingControl.LiveStart was called.

See also: FrameHandlerSink

<< FrameHandlerSink


FrameHandlerSink::FrameTypes

FrameHandlerSink.FrameTypes Property
The FrameTypes collections allows the specification of valid image formats for the ImageBuffer collection.
Syntax:
[VB.NET]
Public FrameTypes As FrameTypes

[C#]
public FrameTypes FrameTypes;
Limitations:

Read only.
Example:

The following example shows how to setup a FrameHandlerSink that only accepts the 8-bit-gray image formats Y800 and RGB8.

[C#]
FrameHandlerSink fhs = new FrameHandlerSink();
fhs.FrameTypes.Add( new FrameType( MediaSubtypes.Y800 ) );
fhs.FrameTypes.Add( new FrameType( MediaSubtypes.RGB8 ) );

ICImagingControl1.Sink = fhs;

ICImagingControl1.LiveStart();

[VB.NET]
Dim fhs As New FrameHandlerSink
fhs.FrameTypes.Add(New FrameType(MediaSubtypes.Y800))
fhs.FrameTypes.Add(New FrameType(MediaSubtypes.RGB8))

IcImagingControl1.Sink = fhs

IcImagingControl1.LiveStart()

To let a sink only accept images in the bayer format BY8, the following source code can be used:

[C#]
FrameHandlerSink fhs = new FrameHandlerSink();
fhs.FrameTypes.Add( new FrameType( MediaSubtypes.BY8 ) );

ICImagingControl1.Sink = fhs;

ICImagingControl1.LiveStart();

[VB.NET]
Dim fhs As New FrameHandlerSink
fhs.FrameTypes.Add(New FrameType(MediaSubtypes.BY8))

IcImagingControl1.Sink = fhs

IcImagingControl1.LiveStart()
See also: FrameHandlerSink, FrameTypes

<< FrameHandlerSink


FrameHandlerSink::ImageBuffers

FrameHandlerSink.ImageBuffers Property
Returns the collections of ImageBuffer objects in this sink.
Syntax:
[VB.NET]
Public ImageBuffers() As ImageBuffer

[C#]
public ImageBuffer[] ImageBuffers;
Limitations:

Read only.
See also: FrameHandlerSink

<< FrameHandlerSink


FrameHandlerSink::SnapMode

FrameHandlerSink.SnapMode Property
Changes this sink's operating mode between Grab and Snap mode. In grab mode, all frames reaching the sink are presented to the frame filter or filter chain and then copied into the ImageBuffers. After that, the ICImagingControl.ImageAvailable event is raised. In snap mode, SnapImage, SnapImageSequence or SnapImageSequenceAsync has to be called in order to trigger the image acquisition process.
Syntax:
[VB.NET]
Public SnapMode As Boolean

[C#]
public bool SnapMode;
See also: FrameHandlerSink, ImageBuffer, ICImagingControl.ImageAvailable

<< FrameHandlerSink


FrameHandlerSink::SnapImage

FrameHandlerSink.SnapImage Method
Queues up a snap job, thus allowing one frame to be copied into the ImageBuffer collection. The method returns when either the frame was snapped, or the timeout has occurred.
Syntax:
[VB.NET]
Public Sub SnapImage()
Public Sub SnapImage( TimeOut As Integer )

[C#]
public void SnapImage();
public void SnapImage( int TimeOut );

Parameter | Description
TimeOut | Number of milliseconds to wait before returning from this function, if no frames are available from the device.
See also: FrameHandlerSink, FrameHandlerSink.SnapImageSequence, FrameHandlerSink.SnapImageSequenceAsync

<< FrameHandlerSink


FrameHandlerSink::SnapImageSequence

FrameHandlerSink.SnapImageSequence Method
Queues up a snap job, thus allowing a number of frames to be copied into the ImageBuffer collection. The method returns when either the specified number of frames are snapped, or the timeout has occurred.
Syntax:
[VB.NET]
Public Sub SnapImageSequence( Count As Integer )
Public Sub SnapImageSequence( Count As Integer, TimeOut As Integer )

[C#]
public void SnapImageSequence( int Count );
public void SnapImageSequence( int Count, int TimeOut );

Parameter | Description
Count | Number of frames to be copied into the image buffers.
TimeOut | Number of milliseconds to wait before returning from this function, when insufficient frames are available from the device.
See also: FrameHandlerSink, FrameHandlerSink.SnapImage, FrameHandlerSink.SnapImageSequenceAsync

<< FrameHandlerSink


FrameHandlerSink::SnapImageSequenceAsync

FrameHandlerSink.SnapImageSequenceAsync Method
Queues up a snap job, thus copying a number of frames into the ImageBuffer collection. The method returns immediately after queuing the job.
Syntax:
[VB.NET]
Public Sub SnapImageSequenceAsync( Count As Integer )

[C#]
public void SnapImageSequenceAsync( int Count );

Parameter | Description
Count | Number of frames to be copied into the image buffers.
Remarks:

You cannot terminate this snap job unless you stop live mode by calling ICImagingControl.LiveStop.

See also: FrameHandlerSink, FrameHandlerSink.SnapImage, FrameHandlerSink.SnapImageSequence

<< FrameHandlerSink


FrameType

A FrameType describes the color format and (optionally) dimensions and buffer size of the image format of ImageBuffer objects.

Information

Namespace: TIS.Imaging
Introduced in version 3.0

Properties

Property | Description
BitsPerPixel | Returns the number of bits needed to store one pixel in this frame type.
BufferSize | Returns or sets the number of bytes that is needed to store one frame of image data in this frame type.
FourCC | Returns the FourCC pixel format of the frametype as string.
Height | Returns or sets height of a frame.
IsBottomUp | Returns whether this frame type stores the image data bottom up.
Name | The name of this frame type.
PixelFormat | Sets or gets the color format of this frametype as a System.Drawing.PixelFormat.
Subtype | Returns or sets the GUID of the video subtype of this frame type.
Width | Returns or sets width of a frame.

Methods

Method | Description
FrameType | Creates a new FrameType.

<< Classes


FrameType::BitsPerPixel

FrameType.BitsPerPixel Property
Returns the number of bits needed to store one pixel in this frame type.
Syntax:
[VB.NET]
Public BitsPerPixel As Integer

[C#]
public int BitsPerPixel;
Limitations:

Read only.
Remarks:

The bit depth depends on the FrameType.Subtype property.

See also: FrameType

<< FrameHandlerSink.FrameType


FrameType::BufferSize

FrameType.BufferSize Property
Returns or sets the number of bytes that is needed to store one frame of image data in this frame type.
Syntax:
[VB.NET]
Public BufferSize As Integer

[C#]
public int BufferSize;
See also: FrameType

<< FrameHandlerSink.FrameType


FrameType::Height

FrameType.Height Property
Returns or sets height of a frame.
Syntax:
[VB.NET]
Public Height As Integer

[C#]
public int Height;
See also: FrameType, FrameType.Width

<< FrameHandlerSink.FrameType


FrameType::IsBottomUp

FrameType.IsBottomUp Property
Returns whether this frame type stores the image data bottom up.
Syntax:
[VB.NET]
Public IsBottomUp As Boolean

[C#]
public bool IsBottomUp;
Limitations:

Read only.
Remarks:

For bottom up frame types. the first bytes of the image buffer contain the image data of the last row of the image. In images with a top down frame type, the first bytes of the image buffer contain the image data of the first row of the image.

See also: FrameType

<< FrameHandlerSink.FrameType


FrameType::Name

FrameType.Name Property
The name of this frame type.
Syntax:
[VB.NET]
Public Name As String

[C#]
public string Name;
Limitations:

Read only.

See also: FrameType

<< FrameHandlerSink.FrameType


FrameType::PixelFormat

FrameType.PixelFormat Property
Sets or gets the color format of this frametype as a System.Drawing.PixelFormat.
Syntax:
[VB.NET]
Public PixelFormat As System.Drawing.PixelFormat

[C#]
public System.Drawing.PixelFormat PixelFormat;
Remarks:

When the assigned PixelFormat can not be used a FrameType color format, an ArgumentException is thrown.

When the FrameType 's color format is unknown or not convertible into a PixelFormat, a NotSupportedException is thrown.

<< FrameHandlerSink.FrameType


FrameType::Subtype

FrameType.Subtype Property
Returns or sets the GUID of the video subtype of this frame type.
Syntax:
[VB.NET]
Public Subtype As Guid

[C#]
public Guid Subtype;
See also: FrameType, MediaSubtypes

<< FrameHandlerSink.FrameType


FrameType::Width

FrameType.Width Property
Returns or sets width of a frame.
Syntax:
[VB.NET]
Public Width As Integer

[C#]
public int Width;
See also: FrameType, FrameType.Height

<< FrameHandlerSink.FrameType


FrameTypes

The FrameTypes collection is used to define a list of FrameTypes. A FrameTypes collection is used, i.e. to determine which FrameTypes are accepted by a frame filter or a sink.

Information

Namespace: TIS.Imaging
Introduced in version 3.0

Properties

Property | Description
Count | Returns the number of FrameType objects in the collection.
Item | Returns or sets the FrameType at the specified position.

Methods

Method | Description
Add | Inserts a FrameType object at the end of the collection.
Clear | Removes all FrameType objects from the collection.
Remove | Removes the FrameType at a specified position.

<< Classes


FrameTypes::Count

FrameTypes.Count Property
Returns the number of FrameType objects in the collection.
Syntax:
Limitations:

Read only.
See also: FrameTypes, FrameType

<< FrameHandlerSink.FrameTypes


FrameTypes::Item

FrameTypes.Item Property
Returns or sets the FrameType at the specified position.
Syntax:
[VB.NET]
Public Item(Index As Integer) As FrameType

[C#]
public FrameType this[int Index];

Parameter | Description
Index | Specifies the Index of the FrameType to set or return. The Index must lie in the range [1, FrameTypes.Count ], otherwise an error occurs.
See also: FrameTypes, FrameTypes.Count, FrameType

<< FrameHandlerSink.FrameTypes


FrameTypes::Add

FrameTypes.Add Method
Inserts a FrameType object at the end of the collection.
Syntax:
[VB.NET]
Public Sub Add( NewType As FrameType )

[C#]
Public void Add( FrameType NewType );

Parameter | Description
Filter | Specifies the FrameType that is inserted into the collection.
See also: FrameTypes, FrameTypes.Remove, FrameTypes.Clear

<< FrameHandlerSink.FrameTypes


FrameTypes::Clear

FrameTypes.Clear Method
Removes all FrameType objects from the collection.
Syntax:
[VB.NET]
Public Sub Clear()

[C#]
Public void Clear();
See also: FrameTypes, FrameTypes.Add, FrameTypes.Remove

<< FrameHandlerSink.FrameTypes


FrameTypes::Remove

FrameTypes.Remove Method
Removes the FrameType at a specified position.
Syntax:
[VB.NET]
Public Sub Remove( Index As Integer )

[C#]
Public void Remove( int Index );

Parameter | Description
Index | Specifies the index of the FrameType to be removed.
See also: FrameTypes, FrameTypes.Add, FrameTypes.Clear

<< FrameHandlerSink.FrameTypes


MediaStreamContainer

A MediaStreamContainer describes a video file format. The most common video file format is AVI.

A list of valid MediaStreamContainer objects can be obtained from ICImagingControl.MediaStreamContainers.

Example

The following code fragment shows how to create a MediaStreamSink to record an AVI file:

[C#]
// Create the MediaStreamSink.
MediaStreamSink aviSink = new MediaStreamSink();

// Set AVI as the video file format.
foreach( MediaStreamContainer msc in ICImagingControl1.MediaStreamContainers )
{
    if( msc.Name == "AVI" )
    {
        aviSink.StreamContainer = msc;
        break;
    }
}

// Set DV Video encoder as the codec.
foreach( AviCompressor codec in ICImagingControl1.AviCompressors )
{
    if( codec.Name == "DV Video Encoder" )
    {
        aviSink.Codec = codec;
        break;
    }
}

// Set a target file name.
aviSink.Filename = "video.avi";

// Set the sink.
ICImagingControl1.Sink = aviSink;

// Start recording.
ICImagingControl1.LiveStart();

[VB.NET]
' Create the MediaStreamSink.
Dim aviSink As New MediaStreamSink

' Set AVI as the video file format.
For Each msc As MediaStreamContainer In IcImagingControl1.MediaStreamContainers
    If msc.Name = "AVI" Then
        aviSink.StreamContainer = msc
        Exit For
    End If
Next

' Set DV Video encoder as the codec.
For Each codec As AviCompressor In IcImagingControl1.AviCompressors
    If codec.Name = "DV Video Encoder" Then
        aviSink.Codec = codec
        Exit For
    End If
Next

' Set the  target file name.
aviSink.Filename = "video.avi"

' Set the sink.
IcImagingControl1.Sink = aviSink

' Start recording.
IcImagingControl1.LiveStart()

Information

Namespace: TIS.Imaging
Introduced in version 3.0

Properties

Property | Description
CustomCodecSupported | Returns whether a MediaStreamContainer allows an AviCompressor to be used to compress the recorded video.
ID | Returns the GUID of a MediaStreamContainer.
Name | Returns the name of the MediaStreamContainer.
PreferredFileExtension | Returns the default file extension for video files saved by this MediaStreamContainer.

Methods

Method | Description
MediaStreamContainer | Creates an new MediaStreamContainer object.

<< Classes


MediaStreamContainer::CustomCodecSupported

MediaStreamContainer.CustomCodecSupported Property
Returns whether a MediaStreamContainer allows an AviCompressor to be used to compress the recorded video.
Syntax:
[VB.NET]
Public CustomCodecSupported As Boolean

[C#]
public bool CustomCodecSupported;
Limitations:

Read only.
Remarks:

Some media stream containers do not support using an AviCompressor.

See also: MediaStreamContainer, MediaStreamSink.StreamContainer, MediaStreamSink.Codec

<< MediaStreamContainer


MediaStreamContainer::ID

MediaStreamContainer.ID Property
Returns the GUID of a MediaStreamContainer.
Syntax:
[VB.NET]
Public ID As String

[C#]
public string ID;
Limitations:

Read only.
See also: MediaStreamContainer

<< MediaStreamContainer


MediaStreamContainer::Name

MediaStreamContainer.Name Property
Returns the name of the MediaStreamContainer.
Syntax:
[VB.NET]
Public Name As String

[C#]
public string Name;
Limitations:

Read only.
Remarks:

The name of a media stream container should not be used for identification purposes. The MediaStreamContainer.ID property can be used to identify the media stream container that is currently in use.

See also: MediaStreamContainer

<< MediaStreamContainer


MediaStreamContainer::PreferredFileExtension

MediaStreamContainer.PreferredFileExtension Property
Returns the default file extension for video files saved by this MediaStreamContainer.
Syntax:
[VB.NET]
Public PreferredFileExtension As String

[C#]
public string PreferredFileExtension;
Limitations:

Read only.
Remarks:

The value of this property can be used for customizing a file saveing dialog.

See also: MediaStreamContainer

<< MediaStreamContainer


MediaStreamSink

The MediaStreamSink allows video files to be recorded in a more sophisticated manor than is possible using AviStartCapture and AviStopCapture. However, for simple tasks, the methods AviStartCapture and AviStopCapture are better suited, as they are really easy to use. A MediaStreamSink can save image data to video files in various formats and optionally allows you to specify one or more FrameFilters that can analyze and/or transform the image data, before it is written to the video file.

The FrameFilter implementation can also drop certain frames, thus enabling lapse recording applications to be easily authored. The video file format is specified by a MediaStreamContainer, while the format of the image data in the file is determined by a codec, represented as an AviCompressor object. The MediaStreamContainer determines the video file format; the most common MediaStreamContainer is AVI. Many media stream containers allow the specification of an AviCompressor to compress the image data before writing it to the file.

Example

The following code fragment shows how to create a MediaStreamSink to record an AVI file.

[C#]
// Create the MediaStreamSink.
MediaStreamSink aviSink = new MediaStreamSink();
// We do not set aviSink.StreamContainer to record an AVI file,
// as AVI is the default file format.

// Set DV Video encoder as the codec.
foreach( AviCompressor codec in ICImagingControl1.AviCompressors )
{
    if( codec.Name == "DV Video Encoder" )
    {
        aviSink.Codec = codec;
        break;
    }
}

// Set a target file name.
aviSink.Filename = "video.avi";

// Set the sink.
ICImagingControl1.Sink = aviSink;

// Start recording.
ICImagingControl1.LiveStart();

[VB.NET]
' Create the MediaStreamSink.
Dim aviSink As New MediaStreamSink

' We do not set aviSink.StreamContainer to record an AVI file,
' as AVI is the default file format.

' Set DV Video encoder as the codec.
For Each codec As AviCompressor In IcImagingControl1.AviCompressors
    If codec.Name = "DV Video Encoder" Then
        aviSink.Codec = codec
        Exit For
    End If
Next

' Set a target file name.
aviSink.Filename = "video.avi"

' Set the sink.
IcImagingControl1.Sink = aviSink

' Start recording.
IcImagingControl1.LiveStart()

Information

Namespace: TIS.Imaging
Introduced in version 3.0

Inheritance

BaseSink
MediaStreamSink

Properties

Property | Description
Codec | Returns or sets the used AviCompressor.
Filename | Returns or sets the name of the target video file.
FrameFilters | The FrameFilters property grants access to a FrameFilters collection that can be used to manipulate the filter chain used to transform the image data, before it is written to the video file.
StreamContainer | Returns or sets the used MediaStreamContainer.

Methods

Method | Description
MediaStreamSink | Creates a new MediaStreamSink.

<< Classes


MediaStreamSink::Codec

MediaStreamSink.Codec Property
Returns or sets the used AviCompressor.
Syntax:
[VB.NET]
Public Codec As AviCompressor

[C#]
public AviCompressor Codec;
Limitations:

Read only in live mode.
Remarks:

Some media stream containers do not support using an AviCompressor. If MediaStreamContainer.CustomCodecSupported returns false, it is not possible to assgin an AviCompressor to the Codec property.

See also: MediaStreamSink, AviCompressor

<< MediaStreamSink


MediaStreamSink::Filename

MediaStreamSink.Filename Property
Returns or sets the name of the target video file.
Syntax:
[VB.NET]
Public Filename As String

[C#]
public string Filename;
Limitations:

Read only in live mode.

See also: MediaStreamSink

<< MediaStreamSink


MediaStreamSink::FrameFilters

MediaStreamSink.FrameFilters Property
The FrameFilters property grants access to a FrameFilters collection that can be used to manipulate the filter chain used to transform the image data, before it is written to the video file.
Syntax:
[VB.NET]
Public FrameFilters As FrameFilters

[C#]
public FrameFilters FrameFilters;
Limitations:

Read only.

The filter chain can not be changed in live mode.
Example:

See ICImagingControl.FrameFilterCreate for an example that illustrates how to create a frame filter and insert the filter into a FrameFilters collection.

See also: MediaStreamSink, FrameFilters, FrameFilter

<< MediaStreamSink


MediaStreamSink::StreamContainer

MediaStreamSink.StreamContainer Property
Returns or sets the used MediaStreamContainer.
Syntax:
[VB.NET]
Public StreamContainer As MediaStreamContainer

[C#]
public MediaStreamContainer StreamContainer;
Limitations:

Read only in live mode.
See also: MediaStreamSink, MediaStreamContainer

<< MediaStreamSink


New Enumerations

List of all enumerations that have been introduced in IC Imaging Control 3.0

refenum.DeBayerModes

The DeBayerModes enumeration is used to set the debayering algorithm.

refenum.DeBayerStartPatterns

Enumeration containing all possible bayer start patterns of the first row of the image data.

refenum.PathPositions

PathPositions enumerates the possible positions of the OverlayBitmap in the image stream.

refenum.OverlayColorModes

The members of this enumeration are used to set the color format of the OverlayBitmap, using OverlayBitmap.ColorMode.

<< New Features Reference


refenum::DeBayerModes

refenum.DeBayerModes
The DeBayerModes enumeration is used to set the debayering algorithm.
Name | Description
NearestColor | Simplest and fastest algorithm, but inferior output image quality.
Bilinear | Algorithm with both acceptable speed and image quality.
EdgeSensing | This algorithm creates the best image quality, but is rather slow.

<< Enumerations


refenum::DeBayerStartPatterns

refenum.DeBayerStartPatterns
Enumeration containing all possible bayer start patterns of the first row of the image data.
Name | Description
BG | The first two pixels of the pattern are interpreted as blue and green.
GB | The first two pixels of the pattern are interpreted as green and blue.
GR | The first two pixels of the pattern are interpreted as green and red.
RG | The first two pixels of the pattern are interpreted as red and green.

<< Enumerations


refenum::PathPositions

refenum.PathPositions
PathPositions enumerates the possible positions of the OverlayBitmap in the image stream.
Name | Description
None | The OverlayBitmap will not be visible at all.
Device | The OverlayBitmap will be visible in both the live video display and grabbed images/videos.
Sink | The OverlayBitmap will be visible in grabbed images and videos, but not in the live display.
Display | The OverlayBitmap will be visible in the live display, but not in grabbed images or videos.

<< Enumerations


refenum::OverlayColorModes

refenum.OverlayColorModes
The members of this enumeration are used to set the color format of the OverlayBitmap, using OverlayBitmap.ColorMode.
Name | Description
BestFit | Let the OverlayBitmap select the best matching color format.
Grayscale | Use grayscale mode.
Color | Use color mode.

<< Enumerations


What is new in version 2.0

Description of the changes from IC Imaging Control 1.41 to IC Imaging Control 2.0.

.NET component

With IC Imaging Control 2.0, a .NET component is introduced that provides the same functionality as the OCX. There is separate online documentation for this component. It can be found in the IC Imaging Control start sub menu

Video Capture Device Properties

Video capture device properties provide a generic, hardware independent and extendable way to control the settings of a video capture device. In the following, the shortcut VCD is used for Video Capture Device.

DCAM Prop DLL

The DCAM Prop DLL is not needed anymore. The special DCAM features can now be accessed and manipulated using the appropriate VCD properties.

A detailed list of equivalent functionality for all functions and procedures of the DCAM Prop DLL can be found in the technical article DCAM_Prop_DLL.

LivePause

The new ICImagingControl.LivePause property allows to pause both the live display and the delivery of frames to the ImageAvailable event.

Count dropped frames

It is possible to retrieve the number of frames that have been dropped or not dropped with the new functions

  • ICImagingControl.DeviceCountOfFramesDropped
  • ICImagingControl.DeviceCountOfFramesNotDropped

Serializing the device state

A new set of functions allows the settings of the currently opened device to be saved to a string or a file and restored.

  • ICImagingControl.SaveDeviceState
  • ICImagingControl.SaveDeviceStateToFile
  • ICImagingControl.LoadDeviceState
  • ICImagingControl.LoadDeviceStateFromFile

Built-in Dialogs

ICImagingControl comes with 2 dialogs that allow the user to open a device and adjust device settings.

  • ICImagingControl.ShowDeviceSettingsDialog shows a dialog box that lets the user open a device and configure video norm, video format, input channel, frame rate and flip states.
  • ICImagingControl.ShowPropertyDialog shows a dialog allowing the user to adjust the VCD Properties.

Saving image buffers

The ImageBuffer class has 2 new methods to save the contents of the image buffer. Images can be saved to JPEG and various BMP files.

  • ImageBuffer.SaveAsJpeg
  • ImageBuffer.SaveAsBitmap

Image buffer access

The ImageBuffer class was enhanced with methods to simplify access to the image data.

The ImageBuffer.Lines and ImageBuffer.PixelPerLine properties expose information about the size of the image buffer.

OverlayBitmap

The following methods have been added to the OverlayBitmap class:

  • OverlayBitmap.DrawFrameRect
  • OverlayBitmap.DrawSolidEllipse
  • OverlayBitmap.DrawFrameEllipse

New Features Reference

List of all new features

<< What's New


New Features Reference

List of all new features

VCDAbsoluteValueProperty

This class represents an absolute value interface to a value of a video capture device property.

VCDButtonProperty

This class represents a button interface to a video capture device property. Button interfaces allow invoking an operation at the property.

VCDCategoryMap

This class describes how VCD property items are organized in categories.

VCDMapStringsProperty

This class represents an interface to a value of a video capture device property, that uses names for the values.

VCDPropertyElement

This class represents an element of video capture device property.

VCDPropertyElements

This class is a collection of VCDPropertyElement objects.

VCDPropertyInterface

This class represents an interface to a value of a video capture device property. It is an abstract base class for several more specialized interfaces.

VCDPropertyItem

A VCDPropertyItem object provides the functionality to access a video capture device property.

VCDPropertyItems

This class contains a collection of all VCDPropertyItem objects that are supported by the currently opened device.

VCDRangeProperty

This class represents a range interface to a value of a video capture device property.

VCDSwitchProperty

This class represents a switch interface to a value of a video capture device property. A switch interface is used to enable or disable settings of a property.

VCDSimpleProperty

This class wraps the concept of VCDProperties to make them easier to use.

ICImagingControl.VCDPropertyItems

Returns a VCDPropertyItems collection representing the properties of the currently opened device.

ICImagingControl.LivePause

This property suspends and restarts the current delivery of images.

ICImagingControl.SaveDeviceState

Saves the currently opened device and its settings to a string.

ICImagingControl.LoadDeviceState

Restores the device settings saved with ICImagingControl.SaveDeviceState.

ICImagingControl.SaveDeviceStateToFile

Saves the currently opened device and its settings to a file.

ICImagingControl.LoadDeviceStateFromFile

Restores the device settings saved with ICImagingControl.SaveDeviceStateToFile.

ICImagingControl.DeviceCountOfFramesDropped

Returns the number dropped frames.

ICImagingControl.DeviceCountOfFramesNotDropped

Returns the number of frames that were not dropped.

ICImagingControl.ShowDeviceSettingsDialog

This method opens a video capture device selection dialog.

ICImagingControl.ShowPropertyDialog

This method opens a dialog to adjust all properties of the currently opened video capture device.

ICImagingControl.SignalDetectedAvailable

Returns whether the current video capture device supports signal detection on its input ports.

ICImagingControl.SignalDetected

Returns whether a video signal is detected on the currently selected input channel of the selected video capture device.

ImageBuffer.SaveAsJpeg

Saves the contents of the buffer to a JPEG compressed file to disk.

ImageBuffer.SaveAsBitmap

Saves the contents of the buffer to a bitmap file on disk.

ImageBuffer.Lines

Returns the number of lines in this ImageBuffer.

ImageBuffer.PixelPerLine

Returns the number of pixels in each line of this ImageBuffer.

OverlayBitmap.DrawFrameRect

This method draws an empty frame rectangle on the live video.

OverlayBitmap.DrawFrameEllipse

This method draws an empty frame ellipse on the live video.

OverlayBitmap.DrawSolidRect

This method draws a solid, filled rectangle on the live video.

<< What is new in version 2.0


VCDAbsoluteValueProperty

This class represents an absolute value interface to a value of a video capture device property.

Information

Namespace: TIS.Imaging
Introduced in version 2.0

Inheritance

VCDPropertyInterface
VCDAbsoluteValueProperty

Properties

Property | Description
Default | Returns the default value for this property.
DimFunction | Returns the dimension function, which describes how to map a linear range like a slider to the absolute values' range in order to achieve the best usability for your programs.
DimType | Returns the dimension type. This is a hint for applications how to connect this interface to UI elements like scrollbars to allow the best possible control.
RangeMax | Returns the maximum value.
RangeMin | Returns the minimum value.
Value | Returns or sets the absolute value.

<< Classes


VCDPropertyInterface

This class represents an interface to a value of a video capture device property. It is an abstract base class for several more specialized interfaces.

Information

Namespace: TIS.Imaging
Introduced in version 2.0

Inheritance

VCDPropertyInterface
VCDAbsoluteValueProperty
VCDButtonProperty
VCDRangeProperty
VCDMapStringsProperty
VCDSwitchProperty

Properties

Property | Description
Available | Returns whether this interface is currently available for reading and/or writing operations.
InterfaceID | Returns the interface ID of this property interface.
Parent | Returns the element this interface belongs to.
ReadOnly | Returns whether this interface allows write operations.

Methods

Method | Description
Update | Updates the internal cache of the property to match the device's state.

<< Classes


VCDPropertyInterface::Available

VCDPropertyInterface.Available Property
Returns whether this interface is currently available for reading and/or writing operations.
Syntax:
[VB.NET]
Public Available As Boolean

[C#]
public bool Available;
Limitations:

Run time only.
See also: VCDPropertyInterface, VCDPropertyInterface.ReadOnly

<< VCDPropertyInterface


VCDPropertyInterface::InterfaceID

VCDPropertyInterface.InterfaceID Property
Returns the interface ID of this property interface.
Syntax:
[VB.NET]
Public InterfaceID As String

[C#]
public string InterfaceID;
Limitations:

Run time only.
See also: VCDPropertyInterface, Standard Interface Identifier Strings

<< VCDPropertyInterface


VCDPropertyInterface::Parent

VCDPropertyInterface.Parent Property
Returns the element this interface belongs to.
Syntax:
[VB.NET]
Public Parent As VCDPropertyElement

[C#]
public VCDPropertyElement Parent;
Limitations:

Run time only.
See also: VCDPropertyInterface, VCDPropertyElement

<< VCDPropertyInterface


VCDPropertyInterface::ReadOnly

VCDPropertyInterface.ReadOnly Property
Returns whether this interface allows write operations.
Syntax:
[VB.NET]
Public ReadOnly As Boolean

[C#]
public bool ReadOnly;
Limitations:

Run time only.
See also: VCDPropertyInterface, VCDPropertyInterface.Available

<< VCDPropertyInterface


VCDPropertyInterface::Update

VCDPropertyInterface.Update Method
Updates the internal cache of the property to match the device's state.
Syntax:
[VB.NET]
Public Sub Update()

[C#]
public void Update();
Remarks:

Some properties may be controlled externally at the device, while the VCDPropertyInterface derived class does not know about that. To prevent that inconsistency from happening, you can use this function to update the cache.

See also: VCDPropertyInterface

<< VCDPropertyInterface


VCDAbsoluteValueProperty::Default

VCDAbsoluteValueProperty.Default Property
Returns the default value for this property.
Syntax:
[VB.NET]
Public Default As Double

[C#]
public double Default;
Limitations:

Run time only, read only.
See also: VCDAbsoluteValueProperty, VCDAbsoluteValueProperty.Value

<< VCDAbsoluteValueProperty


VCDAbsoluteValueProperty::DimFunction

VCDAbsoluteValueProperty.DimFunction Property
Returns the dimension function, which describes how to map a linear range like a slider to the absolute values' range in order to achieve the best usability for your programs.
Syntax:
[VB.NET]
Public DimFunction As Integer

[C#]
public int DimFunction;
Limitations:

Run time only, read only.
Remarks:

The DimFunction value is a member of the AbsDimFunction enumeration.

See also: VCDAbsoluteValueProperty

<< VCDAbsoluteValueProperty


VCDAbsoluteValueProperty::DimType

VCDAbsoluteValueProperty.DimType Property
Returns the dimension type. This is a hint for applications how to connect this interface to UI elements like scrollbars to allow the best possible control.
Syntax:
[VB.NET]
Public DimType As String

[C#]
public string DimType
Limitations:

Run time only, read only.
See also: VCDAbsoluteValueProperty

<< VCDAbsoluteValueProperty


VCDAbsoluteValueProperty::RangeMax

VCDAbsoluteValueProperty.RangeMax Property
Returns the maximum value.
Syntax:
[VB.NET]
Public RangeMax As Double

[C#]
public double RangeMax;
Limitations:

Run time only, read only.
See also: VCDAbsoluteValueProperty, VCDAbsoluteValueProperty.RangeMin

<< VCDAbsoluteValueProperty


VCDAbsoluteValueProperty::RangeMin

VCDAbsoluteValueProperty.RangeMin Property
Returns the minimum value.
Syntax:
[VB.NET]
Public RangeMin As Double

[C#]
public double RangeMin;
Limitations:

Run time only, read only.
See also: VCDAbsoluteValueProperty, VCDAbsoluteValueProperty.RangeMax

<< VCDAbsoluteValueProperty


VCDAbsoluteValueProperty::Value

VCDAbsoluteValueProperty.Value Property
Returns or sets the absolute value.
Syntax:
[VB.NET]
Public Value As Double

[C#]
public double Value;
Limitations:

Run time only.
See also: VCDAbsoluteValueProperty, VCDAbsoluteValueProperty.RangeMin, VCDAbsoluteValueProperty.RangeMax, VCDAbsoluteValueProperty.Default

<< VCDAbsoluteValueProperty


VCDButtonProperty

This class represents a button interface to a video capture device property. Button interfaces allow invoking an operation at the property.

Information

Namespace: TIS.Imaging
Introduced in version 2.0

Inheritance

VCDPropertyInterface
VCDButtonProperty

Methods

Method | Description
Push | Invokes the operation controlled by this interface.

<< Classes


VCDButtonProperty::Push

VCDButtonProperty.Push Method
Invokes the operation controlled by this interface.
Syntax:
[VB.NET]
Public Sub Push

[C#]
public void Push();
See also: VCDButtonProperty

<< VCDButtonProperty


VCDCategoryMap

This class describes how VCD property items are organized in categories.

Information

Namespace: TIS.Imaging
Introduced in version 2.0

Properties

Property | Description
Categories | Returns a list of all property item categories of the opened device.
ItemIDs | Returns the System.Collections.Generic.Dictionary containing the VCD item IDs, ordered by their categories.
Items | Returns the System.Collections.Generic.Dictionary containing the VCD item names, ordered by their categories.

<< Classes


VCDCategoryMap::Categories

VCDCategoryMap.Categories Property
Returns a list of all property item categories of the opened device.
Syntax:
[VB.NET]
Public ReadOnly Property Categories() As String()

[C#]
public string[] Categories { get; }
Limitations:

Read only.
See also: VCDCategoryMap, VCDCategoryMap.Items, VCDCategoryMap.ItemIDs

<< VCDCategoryMap


VCDMapStringsProperty

This class represents an interface to a value of a video capture device property, that uses names for the values.

Information

Namespace: TIS.Imaging
Introduced in version 2.0

Inheritance

VCDPropertyInterface
VCDRangeProperty
VCDMapStringsProperty

Properties

Property | Description
String | Sets or gets the name current value of the property controlled through this interface.
Strings | Returns a list with the available strings this property can be set to.

<< Classes


VCDRangeProperty

This class represents a range interface to a value of a video capture device property.

Information

Namespace: TIS.Imaging
Introduced in version 2.0

Inheritance

VCDPropertyInterface
VCDRangeProperty
VCDMapStringsProperty

Properties

Property | Description
Default | Returns the default value of the range.
Delta | Returns the length of the interval between the valid values in the range.
RangeMax | Returns the maximum value of the range.
RangeMin | Returns the minimum value of the range.
Value | Returns or sets the current value of the range.

<< Classes


VCDRangeProperty::Default

VCDRangeProperty.Default Property
Returns the default value of the range.
Syntax:
[VB.NET]
Public Default As Integer

[C#]
public int Default;
Limitations:

Run time only, read only.
See also: VCDRangeProperty, VCDRangeProperty.RangeMin, VCDRangeProperty.RangeMax

<< VCDRangeProperty


VCDRangeProperty::Delta

VCDRangeProperty.Delta Property
Returns the length of the interval between the valid values in the range.
Syntax:
[VB.NET]
Public Delta As Integer

[C#]
public int Delta;
Limitations:

Run time only, read only.
See also: VCDRangeProperty

<< VCDRangeProperty


VCDRangeProperty::RangeMax

VCDRangeProperty.RangeMax Property
Returns the maximum value of the range.
Syntax:
[VB.NET]
Public RangeMax As Integer

[C#]
public int RangeMax;
Limitations:

Run time only, read only.
See also: VCDRangeProperty, VCDRangeProperty.RangeMin, VCDRangeProperty.Default

<< VCDRangeProperty


VCDRangeProperty::RangeMin

VCDRangeProperty.RangeMin Property
Returns the minimum value of the range.
Syntax:
[VB.NET]
Public RangeMin As Integer

[C#]
public int RangeMin;
Limitations:

Run time only, read only.
See also: VCDRangeProperty, VCDRangeProperty.RangeMax, VCDRangeProperty.Default

<< VCDRangeProperty


VCDRangeProperty::Value

VCDRangeProperty.Value Property
Returns or sets the current value of the range.
Syntax:
[VB.NET]
Public Value As Integer

[C#]
public int Value;
Limitations:

Run time only.
See also: VCDRangeProperty, VCDRangeProperty.RangeMin, VCDRangeProperty.RangeMax, VCDRangeProperty.Default, VCDRangeProperty.Delta

<< VCDRangeProperty


VCDMapStringsProperty::String

VCDMapStringsProperty.String Property
Sets or gets the name current value of the property controlled through this interface.
Syntax:
[VB.NET]
Public String As String

[C#]
public string String;
Limitations:

Run time only.
See also: VCDMapStringsProperty, VCDMapStringsProperty.Strings

<< VCDMapStringsProperty


VCDMapStringsProperty::Strings

VCDMapStringsProperty.Strings Property
Returns a list with the available strings this property can be set to.
Syntax:
[VB.NET]
Public ReadOnly Property Strings() As String()

[C#]
public string[] Strings { get; }
Limitations:

Run time only, read only.
See also: VCDMapStringsProperty, VCDMapStringsProperty.String

<< VCDMapStringsProperty


VCDPropertyElement

This class represents an element of video capture device property.

Information

Namespace: TIS.Imaging
Introduced in version 2.0

Properties

Property | Description
Count | Returns the number of interfaces this element exposes to access its data.
ElementID | Returns a string with the GUID of the element
Item | Returns one of this element's interfaces.
Name | Returns the display name of this element.
Parent | Returns the item this element belongs to.

Methods

Method | Description
FindInterface | Returns the desired interface to this element, if it exists.
Update | Updates the internal cache of the element to match the device's state.

<< Classes


VCDPropertyElement::Count

VCDPropertyElement.Count Property
Returns the number of interfaces this element exposes to access its data.
Syntax:
[VB.NET]
Public Count As Integer

[C#]
public int Count;
Limitations:

Run time only.
See also: VCDPropertyElement

<< VCDPropertyElement


VCDPropertyElement::ElementID

VCDPropertyElement.ElementID Property
Returns a string with the GUID of the element
Syntax:
[VB.NET]
Public ElementID As String

[C#]
public string ElementID;
Limitations:

Run time only.
See also: VCDPropertyElement, Standard Element Identifier Strings

<< VCDPropertyElement


VCDPropertyElement::Item

VCDPropertyElement.Item Property
Returns one of this element's interfaces.
Syntax:
[VB.NET]
Public Item(Index As Integer) As VCDPropertyInterface

[C#]
public VCDPropertyInterface Item( int Index );

Parameter | Description
Index | Specifies the index of the interface to return. The index must lie in the range [1, VCDPropertyElement.Count ], otherwise an error occurs.
Limitations:

Run time only.
See also: VCDPropertyElement, VCDPropertyElement.Count, VCDPropertyInterface

<< VCDPropertyElement


VCDPropertyElement::Name

VCDPropertyElement.Name Property
Returns the display name of this element.
Syntax:
[VB.NET]
Public Name As String

[C#]
public string Name;
Limitations:

Run time only.
See also: VCDPropertyElement

<< VCDPropertyElement


VCDPropertyElement::Parent

VCDPropertyElement.Parent Property
Returns the item this element belongs to.
Syntax:
[VB.NET]
Public Parent As VCDPropertyItem

[C#]
public VCDPropertyItem Parent;
Limitations:

Run time only.
See also: VCDPropertyElement, VCDPropertyItem

<< VCDPropertyElement


VCDPropertyElement::FindInterface

VCDPropertyElement.FindInterface Method
Returns the desired interface to this element, if it exists.
Syntax:
[VB.NET]
Public Function FindInterface( InterfaceID As String ) As VCDPropertyInterface

[C#]
public VCDPropertyInterface FindInterface( string InterfaceID );
Return Value:

The desired VCDPropertyInterface if it exists, otherwise an exception occurs.

See also: VCDPropertyElement, Standard Interface Identifier Strings

<< VCDPropertyElement


VCDPropertyElement::Update

VCDPropertyElement.Update Method
Updates the internal cache of the element to match the device's state.
Syntax:
[VB.NET]
Public Sub Update()

[C#]
public void Update();
Remarks:

Some properties may be controlled externally at the device, while the element does not know about that. To prevent that inconsistency from happening, you can use this function to update the cache.

See also: VCDPropertyElement

<< VCDPropertyElement


VCDPropertyElements

This class is a collection of VCDPropertyElement objects.

Example

This example lists all VCDPropertyItems and VCDPropertyElements in the debug output window.

[VB.NET]
Dim PropertyItem As VCDPropertyItem
Dim PropertyElement As VCDPropertyElement

For Each PropertyItem In IcImagingControl1.VCDPropertyItems
    Trace.WriteLine(PropertyItem.Name)
    For Each PropertyElement In PropertyItem.Elements
        Trace.WriteLine("    " + PropertyElement.Name)
    Next
Next

[C#]
// In order to enable tracing, the line "#define TRACE" must inserted at the very
// beginning of the source code.
foreach( VCDPropertyItem PropertyItem in ICImagingControl1.VCDPropertyItems )
{
    Trace.WriteLine(PropertyItem.Name);
    foreach( VCDPropertyElement PropertyElement in PropertyItem.Elements)
    {
        Trace.WriteLine("    " + PropertyElement.Name);
    }
}

Information

Namespace: TIS.Imaging
Introduced in version 2.0

Properties

Property | Description
Count | Returns the number of elements in the VCDPropertyElements collection.
Item | Returns the VCDPropertyElement at the specified position.

Methods

Method | Description
FindElement | Searches the collection for a VCDPropertyElement with a given element id.
FindInterface | This method returns the VCDPropertyInterface that is specified by the passed string.

<< Classes


VCDPropertyElements::Count

VCDPropertyElements.Count Property
Returns the number of elements in the VCDPropertyElements collection.
Syntax:
[VB.NET]
Public Count As Integer

[C#]
public int Count;
Limitations:

Read only.
See also: VCDPropertyElements, VCDPropertyElements.Item

<< VCDPropertyElements


VCDPropertyElements::Item

VCDPropertyElements.Item Property
Returns the VCDPropertyElement at the specified position.
Syntax:
[VB.NET]
Public Item(Index As Integer) As VCDPropertyElement

[C#]
Public VCDPropertyElement Item( int Index );

Parameter | Description
Index | Specifies the index of the VCDPropertyElement to return. The index must lie in the range [1, VCDPropertyElements.Count ].
Limitations:

Read only.
See also: VCDPropertyElements, VCDPropertyElements.Count

<< VCDPropertyElements


VCDPropertyElements::FindElement

VCDPropertyElements.FindElement Method
Searches the collection for a VCDPropertyElement with a given element id.
Syntax:
[VB.NET]
Public Function FindElement( ElementID As String ) As VCDPropertyElement

[C#]
public VCDPropertyElement FindElement( string ElementID );

Parameter | Description
ElementID | Specifies the element identifier string of the VCDPropertyElement to be returned.
Return Value:

If the collection contains an VCDPropertyElement with an element identifier string equal to the passed element identifier string, the FindElement method returns this VCDPropertyElement.

If the identifier string was not found, the function returns Nothing and null respectively.

Remarks:

The element identifier strings are GUIDs. A list of strings can be found in Standard Element Identifier Strings list.

The Basic Use of VCD Properties article in the Programmer's Guide shows how to use the element identifier strings.

See also: VCDPropertyElements, VCDPropertyElement, Standard Element Identifier Strings, Basic Use of VCD Properties

<< VCDPropertyElements


VCDPropertyElements::FindInterface

VCDPropertyElements.FindInterface Method
This method returns the VCDPropertyInterface that is specified by the passed string.
Syntax:
[VB.NET]
Public Function FindInterface( InterfacePath As String ) As VCDPropertyInterface

[C#]
public VCDPropertyInterface FindInterface( string InterfacePath );

Parameter | Description
InterfacePath | Specifies the path to the VCDPropertyInterface. The string contains an element identifier string and an interface identifier string. The identifier strings are separated by a colon: "element_id:interface_id".
Return Value:

If the VCDPropertyElements collection contains an VCDPropertyInterface with an interface identifier string equal to the passed interface identifier string, the FindInterface method returns this VCDPropertyInterface.

If the identifier string was not found, the function returns Nothing and null respectively.

Remarks:

The interface identifier strings are GUIDs. A list of strings can be found in Standard Interface Identifier Strings list.

The Basic Use of VCD Properties article in the Programmer's Guide shows how to use the interface identifier strings.

See also: VCDPropertyElements, VCDPropertyElement, VCDPropertyInterface, Standard Element Identifier Strings, Standard Interface Identifier Strings, Basic Use of VCD Properties

<< VCDPropertyElements


VCDPropertyItem

A VCDPropertyItem object provides the functionality to access a video capture device property.

Usage

A VCDPropertyItem is retrieved from a VCDPropertyItems collection. It provides the properties's elements ( VCDPropertyElement ) like "range", "auto" etc. It also provides the property's name and identifier string.

A property item can contain one or more VCDPropertyElements. It may contains a VCDPropertyElement that provides the propertie's value and a second VCDPropertyElement that provides the automation switch.

Sample

The method VCDPropertyItems.FindItem is used to retrieve a VCDPropertyItem. The property to be retrieved is specified by an item identifier string. To retrieve the brightness property, the string VCDID_Brightness is used. The item identifier strings are defined in the class VCDPropertyIDs. The source code of this class can be found in VCDPropertyID.vb and VCDPropertyID.cs respectively.

[VB.NET]
Dim Brightness As TIS.Imaging.VCDPropertyItem
Brightness = IcImagingControl1.VCDPropertyItems.FindItem(TIS.Imaging.VCDIDs.VCDID_Brightness)

[C#]
TIS.Imaging.VCDPropertyItem Brightness = null;
Brightness = icImagingControl1.VCDPropertyItems.FindItem(TIS.Imaging.VCDIDs.VCDID_Brightness);

Information

Namespace: TIS.Imaging
Introduced in version 2.0

Properties

Property | Description
Elements | The Elements property is a VCDPropertyElements collection contained in the current VCDPropertyItem.
ItemID | Returns a string that contains the GUID of the property item.
Name | Returns the display name of the property item.

Methods

Method | Description
Update | Updates the internal cache of the item to match the video capture device's current state.

<< Classes


VCDPropertyItem::Elements

VCDPropertyItem.Elements Property
The Elements property is a VCDPropertyElements collection contained in the current VCDPropertyItem.
Syntax:
[VB.NET]
Public Elements As VCDPropertyElements

[C#]
public VCDPropertyElements Elements;
Limitations:

Run time only, read only.
Remarks:

The Elements collection is used to retrieve all available VCDPropertyElements that are provided by the current VCDPropertyItem.

A property item can contain one or more VCDPropertyElements. It may contains a VCDPropertyElement that provides the propertie's value and a second VCDPropertyElement that provides the automation switch.

See also: VCDPropertyItem, VCDPropertyElement, VCDPropertyElements

<< VCDPropertyItem


VCDPropertyItem::ItemID

VCDPropertyItem.ItemID Property
Returns a string that contains the GUID of the property item.
Syntax:
[VB.NET]
Public ItemID As String

[C#]
public string ItemID;
Limitations:

Run time only, read only.
See also: VCDPropertyItem, Standard Property Item Identifier Strings

<< VCDPropertyItem


VCDPropertyItem::Name

VCDPropertyItem.Name Property
Returns the display name of the property item.
Syntax:
[VB.NET]
Public Name As String

[C#]
public string Name;
Limitations:

Run time only, read only.
Remarks:

The name of the property is the readable name like "Brightness", "Exposure" etc.

See also: VCDPropertyItem

<< VCDPropertyItem


VCDPropertyItem::Update

VCDPropertyItem.Update Method
Updates the internal cache of the item to match the video capture device's current state.
Syntax:
[VB.NET]
Public Sub Update

[C#]
public void Update
Remarks:

Some properties may be controlled externally at the video capture device while the element does not know about that. To prevent that inconsistency from happening, this function is used to update the property values of the property item.

See also: VCDPropertyItem

<< VCDPropertyItem


VCDPropertyItems

This class contains a collection of all VCDPropertyItem objects that are supported by the currently opened device.

The VCDPropertyItems class provides methods to search a VCDPropertyItem, VCDPropertyElement or VCDPropertyInterface. In addition, a VCDCategoryMap can be optained from the collection that maps the individual properties to categories.

Example

This samples demonstrates how to retrieve the property brightness from the VCDPropertyItems collection:

[VB.NET]
Dim Brightness As ICImagingControl.VCDPropertyItem
Brightness = IcImagingControl1.VCDPropertyItems.FindItem(VCDHelpers.VCDIDs.VCDID_Brightness)

[C#]
ICImagingControl.VCDPropertyItem Brightness = null;
Brightness = IcImagingControl1.VCDPropertyItems.FindItem(VCDHelpers.VCDIDs.VCDID_Brightness);

Information

Namespace: TIS.Imaging
Introduced in version 2.0

Properties

Property | Description
CategoryMap | The CategoryMap property returns a VCDCategoryMap object.
Count | Returns the number of VCDPropertyItems supported by the current video capture device.
Item | Returns the VCDPropertyItem at the specified index.

Methods

Method | Description
FindElement | This method returns the VCDPropertyElement that is referred by the passed identifier string.
FindInterface | This method returns the VCDPropertyInterface that is referred by the passed identifier string.
FindItem | Returns the VCDPropertyItem that is referred by the passed identifier string.
Load | This method sets all property values to the values specified in the passed string.
Save | This method returns a string with the current values of all property items in this collection.
Supported | This method returns, whether the specified property item is supported by the current video capture device.
Update | Updates the property values of all VCDPropertyItems in this collection with the property values of the current video capture device.

<< Classes


VCDPropertyItems::CategoryMap

VCDPropertyItems.CategoryMap Property
The CategoryMap property returns a VCDCategoryMap object.
Syntax:
[VB.NET]
Public CategoryMap As VCDCategoryMap

[C#]
public VCDCategoryMap CategoryMap;
Limitations:

Run time only, read only.
Remarks:

A VCDCategoryMap is used to sort VCDPropertyItems in categories like "Color","Image", "Exposure", "Special" etc.

See also: VCDPropertyItems, VCDCategoryMap

<< VCDPropertyItems


VCDPropertyItems::Count

VCDPropertyItems.Count Property
Returns the number of VCDPropertyItems supported by the current video capture device.
Syntax:
[VB.NET]
Public Count As Integer

[C#]
public int Count;
Limitations:

Run time only, read only.
Remarks:

The Count is used to retrieve the range of the index for the VCDPropertyItems.Item method.

See also: VCDPropertyItems, VCDPropertyItems.Item

<< VCDPropertyItems


VCDPropertyItems::Item

VCDPropertyItems.Item Property
Returns the VCDPropertyItem at the specified index.
Syntax:
[VB.NET]
Public Item(Index As Integer) As VCDPropertyItem

[C#]
public VCDPropertyItem Item(int Index);

Parameter | Description
Index | Specifies the index of the VCDPropertyItem to be returned. The range of the index starts at 1 and ends at VCDPropertyItems.Count. If the specified index is out of this range an exception is thrown.
Limitations:

Run time only, read only.
See also: VCDPropertyItems, VCDPropertyItems.Count

<< VCDPropertyItems


VCDPropertyItems::FindElement

VCDPropertyItems.FindElement Method
This method returns the VCDPropertyElement that is referred by the passed identifier string.
Syntax:
[VB.NET]
Public Function FindElement(ElementPath As String) As VCDPropertyElement

[C#]
public VCDPropertyElement FindElement(string ElementPath);

Parameter | Description
ElementPath | The element path string consists of an item identifier and an element identifier string. The identifier strings are separated by a colon: "item_id:element_id"
Return Value:

If the collection contains an item with an element matching the given element path, the FindElement method returns the VCDPropertyElement.

If the element path string was not found, the function returns Nothing and null respectively.

Remarks:

For available property item identifier and element identifier strings see VCDPropertyIDs
See also: VCDPropertyItems, VCDPropertyItem, VCDPropertyElement, Standard Property Item Identifier Strings, Standard Element Identifier Strings

<< VCDPropertyItems


VCDPropertyItems::FindInterface

VCDPropertyItems.FindInterface Method
This method returns the VCDPropertyInterface that is referred by the passed identifier string.
Syntax:
[VB.NET]
Public Function FindInterface(InterfacePath As String) As VCDPropertyInterface

[C#]
public VCDPropertyInterface FindInterface(string InterfacePath);

Parameter | Description
InterfacePath | The interface path string consists of an item identifier, an element identifier and an interface identifier string. The identifier strings are separated by a colon: "item_id:element_id:interface_id"
Return Value:

If the collection contains a property item with an interface matching the given interface path, the FindInterface method returns the VCDPropertyInterface.

If the identifier string was not found, the function returns Nothing and null respectively.

Remarks:

For available property item identifier and element identifier strings see VCDPropertyIDs.

See also: VCDPropertyItems, VCDPropertyItem, VCDPropertyInterface, Standard Property Item Identifier Strings, Standard Element Identifier Strings, Standard Interface Identifier Strings

<< VCDPropertyItems


VCDPropertyItems::FindItem

VCDPropertyItems.FindItem Method
Returns the VCDPropertyItem that is referred by the passed identifier string.
Syntax:
[VB.NET]
Public Function FindItem(ItemIdentifier As String) As VCDPropertyItem

[C#]
public VCDPropertyItem FindItem(string ItemIdentifier);

Parameter | Description
ItemIdentifier | Specifies the item identifier string.
Return Value:

If the collection contains an item with an identifier string equal to the given item identifier string, the FindItem method returns the VCDPropertyItem.

If the identifier string was not found, the function returns Nothing and null respectively.

Remarks:

For available property item identifier strings see Standard Property Item Identifier Strings. A sample can be found in the Basic Use of VCD Properties tutorial.

See also: VCDPropertyItems, VCDPropertyItem, Standard Property Item Identifier Strings, Basic Use of VCD Properties

<< VCDPropertyItems


VCDPropertyItems::Load

VCDPropertyItems.Load Method
This method sets all property values to the values specified in the passed string.
Syntax:
[VB.NET]
Public Sub Load(LoadString As String)

[C#]
public void Load(string LoadString);

Parameter | Description
LoadString | A string containing property states in XML format.
Remarks:

The passed string is organized in an XML format. It contains the settings of properties of a video capture device. If the Load method is performed, all properties that are referred in this string are tried to be set to the values in this string. Properties that are not listed in the passed string keep unchanged. If properties are listed in the string that are not supported by the current video capture device, then they are ignored.

See also: VCDPropertyItems, VCDPropertyItems.Save

<< VCDPropertyItems


VCDPropertyItems::Save

VCDPropertyItems.Save Method
This method returns a string with the current values of all property items in this collection.
Syntax:
[VB.NET]
Public Function Save As String

[C#]
public string Save();
Return Value:

The returned string contains the property values in XML format. It can be passed

Remarks:

The returned string can be saved to a file. It also can be passed to the VCDPropertyItems.Load method. This loads the current video capture device with predefined property values.

See also: VCDPropertyItems, VCDPropertyItems.Load

<< VCDPropertyItems


VCDPropertyItems::Supported

VCDPropertyItems.Supported Method
This method returns, whether the specified property item is supported by the current video capture device.
Syntax:
[VB.NET]
Public Function Supported(ItemIdentifier As String) As Boolean

[C#]
public bool get_Supported(string ItemIdentifier);

Parameter | Description
ItemIdentifier | A string containing the identifier string of the property item.
Return Value:

The method returns True, if the property item specified by ItemIdentifier is supported by the current video capture device. If the property item is not supported, this method returns False.

Remarks:

For available identifier strings see Standard Property Item Identifier Strings.

See also: VCDPropertyItems, Standard Property Item Identifier Strings

<< VCDPropertyItems


VCDPropertyItems::Update

VCDPropertyItems.Update Method
Updates the property values of all VCDPropertyItems in this collection with the property values of the current video capture device.
Syntax:
[VB.NET]
Public Sub Update

[C#]
public void Update();
Remarks:

Some properties may be controlled externally at the device, while the element does not know about that. To prevent that inconsistency from happening, this function can be called to update the cache.

See also: VCDPropertyItems, VCDPropertyItem

<< VCDPropertyItems


VCDSwitchProperty

This class represents a switch interface to a value of a video capture device property. A switch interface is used to enable or disable settings of a property.

Information

Namespace: TIS.Imaging
Introduced in version 2.0

Inheritance

VCDPropertyInterface
VCDSwitchProperty

Properties

Property | Description
Switch | Returns or changes the state of the switch property.

<< Classes


VCDSwitchProperty::Switch

VCDSwitchProperty.Switch Property
Returns or changes the state of the switch property.
Syntax:
[VB.NET]
Public Switch As Boolean

[C#]
public bool Switch;
Limitations:

Run time only.
See also: VCDSwitchProperty

<< VCDSwitchProperty


VCDSimpleProperty

This class wraps the concept of VCDProperties to make them easier to use.

Information

Namespace: TIS.Imaging.VCDHelpers
Introduced in version 2.0

Properties

Property | Description
Automation | Returns or sets the automation of the property item with the specified id.
DefaultValue | Returns the default value of the specified property item.
RangeMax | Returns the maximum value of the specified property item.
RangeMin | Returns the minimum value of the specified property item.
RangeValue | Returns or sets the value of the property item with the specified id.

Methods

Method | Description
AutoAvailable | Returns whether automation for the specified property item is available.
Available | Checks whether the specified property item is supported by the current video capture device.
OnePush | Invokes the operation of the specified property item.
VCDSimpleProperty | Creates a new VCDSimpleProperty object and connects it to a VCDPropertyItems collection.

<< Classes


VCDSimpleProperty::Automation

VCDSimpleProperty.Automation Property
Returns or sets the automation of the property item with the specified id.
Syntax:
[VB.NET]
Public Automation(id As String) As Boolean

[C#]
public bool Automation[ string id ];

Parameter | Description
id | ID of the VCDPropertyItem whose automation is to be set or get.
See Also: VCDSimpleProperty, VCDSimpleProperty.AutoAvailable, VCDPropertyIDs

<< VCDSimpleProperty


VCDSimpleProperty::DefaultValue

VCDSimpleProperty.DefaultValue Property
Returns the default value of the specified property item.
Syntax:
[VB.NET]
Public DefaultValue(id As String) As Integer

[C#]
public int DefaultValue(string id);

Parameter | Description
id | ID of the VCDPropertyItem whose default value is to be retrieved.
See Also: VCDSimpleProperty, VCDPropertyIDs

<< VCDSimpleProperty


VCDSimpleProperty::RangeMax

VCDSimpleProperty.RangeMax Property
Returns the maximum value of the specified property item.
Syntax:
[VB.NET]
Public RangeMax(id As String) As Integer

[C#]
public int RangeMax(string id);

Parameter | Description
id | ID of the VCDPropertyItem whose maximum value is to be retrieved.
See Also: VCDSimpleProperty, VCDPropertyIDs

<< VCDSimpleProperty


VCDSimpleProperty::RangeMin

VCDSimpleProperty.RangeMin Property
Returns the minimum value of the specified property item.
Syntax:
[VB.NET]
Public RangeMin(id As String) As Integer

[C#]
public int RangeMin( string id );

Parameter | Description
id | ID of the VCDPropertyItem whose minimum value is to be retrieved.
See Also: VCDSimpleProperty, VCDPropertyIDs

<< VCDSimpleProperty


VCDSimpleProperty::RangeValue

VCDSimpleProperty.RangeValue Property
Returns or sets the value of the property item with the specified id.
Syntax:
[VB.NET]
Public RangeValue(id As String) As Integer

[C#]
public int RangeValue[ string id ];

Parameter | Description
id | ID of the VCDPropertyItem whose range value is to be set or get.
Remarks:

jkl

Sample:

jlkghsdf

See Also: VCDSimpleProperty, VCDPropertyIDs

<< VCDSimpleProperty


VCDSimpleProperty::AutoAvailable

VCDSimpleProperty.AutoAvailable Method
Returns whether automation for the specified property item is available.
Syntax:
[VB.NET]
Public Function AutoAvailable(id As String) As Boolean

[C#]
Public bool AutoAvailable(string id);

Parameter | Description
id | Identifier string of a VCDPropertyItem. A list of valid strings can be found in Standard Property Item Identifier Strings.
Return value:

True, if the VCDPropertyItem specified by id supports automation, otherwise False.

Sample:

For a sample see Using the VCD Simple Property Class.

See Also: VCDSimpleProperty, VCDSimpleProperty.Automation, Standard Property Item Identifier Strings

<< VCDSimpleProperty


VCDSimpleProperty::Available

VCDSimpleProperty.Available Method
Checks whether the specified property item is supported by the current video capture device.
Syntax:
[VB.NET]
Public Function Available(id As String) As Boolean

[C#]
public bool Available(string id);

Parameter | Description
id | Identifier string of the VCDPropertyItem. A list of valid strings can be found in Standard Property Item Identifier Strings.
Return value:

True, if the VCDPropertyItem specified by id is available, otherwise False.

Sample:

For a sample see Using the VCD Simple Property Class.

See Also: VCDSimpleProperty, VCDPropertyIDs, Standard Property Item Identifier Strings

<< VCDSimpleProperty


VCDSimpleProperty::OnePush

VCDSimpleProperty.OnePush Method
Invokes the operation of the specified property item.
Syntax:
[VB.NET]
Public Sub OnePush(id As String)

[C#]
public void OnePush(string id);

Parameter | Description
id | ID of the VCDPropertyItem whose operation is to be invoked.
See Also: VCDSimpleProperty, VCDPropertyIDs

<< VCDSimpleProperty


VCDSimpleProperty::VCDSimpleProperty

VCDSimpleProperty.VCDSimpleProperty Method
Creates a new VCDSimpleProperty object and connects it to a VCDPropertyItems collection.
Syntax:
[VB.NET]
Public Sub New(tree As VCDPropertyItems)

[C#]
Public VCDSimpleProperty( VCDPropertyItems tree );

Parameter | Description
tree | A VCDPropertyItems collection.
Sample:

For a sample code, take a look at Using the VCD Simple Property Class.

See Also: VCDSimpleProperty, VCDPropertyItems, ICImagingControl.VCDPropertyItems, Using the VCD Simple Property Class

<< VCDSimpleProperty


ICImagingControl::VCDPropertyItems

ICImagingControl.VCDPropertyItems Property
Returns a VCDPropertyItems collection representing the properties of the currently opened device.
Syntax:
[VB.NET]
Public VCDPropertyItems As ICImagingControl.VCDPropertyItems

[C#]
public ICImagingControl.VCDPropertyItems VCDPropertyItems;
Information:

Introduced in version 2.0
See also: ICImagingControl, VCDPropertyItems

<< ICImagingControl


ICImagingControl::LivePause

ICImagingControl.LivePause Property
This property suspends and restarts the current delivery of images.
Syntax:
[VB.NET]
Public LivePause As Boolean

[C#]
public bool LivePause;
Limitations:

Runtime only
Remarks:

If LivePause is set to True, no images are delivered. This saves CPU load while no images are needed. The live video is restarted very fast, if LivePause is set to False again.

Information:

Introduced in version 2.0
See also: ICImagingControl, ICImagingControl.LiveStart, ICImagingControl.LiveStop, ICImagingControl.LiveCapturePause

<< ICImagingControl


ICImagingControl::SaveDeviceState

ICImagingControl.SaveDeviceState Method
Saves the currently opened device and its settings to a string.
Syntax:
[VB.NET]
Public Function SaveDeviceState() As String

[C#]
public string SaveDeviceState();
Return Value:

A string containing information about the opened device.

Limitations:

A valid device must be opened.
Remarks:

SaveDeviceState saves the following settings of ICImagingControl:

  • Opened Device and its serial number
  • Video norm
  • Video format
  • Input channel
  • Frame rate
  • Vertical Flip
  • Horizontal Flip
  • All VCDProperties

With ICImagingControl.LoadDeviceState, you can re-open the device with the saved settings.

Information:

Introduced in version 2.0
Sample:

The following example saves the currently opened device to a file named "device.dat".

[VB.NET]
IcImagingControl1.SaveDeviceStateToFile("device.dat")

[C#]
ICImagingControl1.SaveDeviceStateToFile("device.dat");
See also: ICImagingControl, ICImagingControl.LoadDeviceState

<< ICImagingControl


ICImagingControl::LoadDeviceState

ICImagingControl.LoadDeviceState Method
Restores the device settings saved with ICImagingControl.SaveDeviceState.
Syntax:
[VB.NET]
Public Sub LoadDeviceState( deviceStateString As String, OpenDevice As Boolean )

[C#]
public void LoadDeviceState( string deviceStateString, bool OpenDevice );

Parameter | Description
deviceStateString | A string containing device information created by ICImagingControl.SaveDeviceState.
OpenDevice | If this parameter is set to false, the method does not open a new device. if the device stored in the settings is different from the one that is already opened, an error is returned. Otherwise the settings are applied to the device. If this parameter is set to true, the method will open the device specified in the settings.
Information:

Introduced in version 2.0
Sample:

The following example loads device settings from a string and starts live video:

[VB.NET]
Try
    IcImagingControl1.LoadDeviceStateFromFile("device.dat", False)
Catch
    MessageBox.Show("Load device failed.")
End Try
If IcImagingControl1.DeviceValid Then
    IcImagingControl1.LiveStart()
End If

[C#]
try
{
    ICImagingControl1.LoadDeviceStateFromFile("device.dat", false);
}
catch(Exception ICEx)
{
    MessageBox.Show(this,"Load device failed.");
}
if (ICImagingControl1.DeviceValid)
{
    ICImagingControl1.LiveStart();
}
See also: ICImagingControl, ICImagingControl.SaveDeviceState

<< ICImagingControl


ICImagingControl::SaveDeviceStateToFile

ICImagingControl.SaveDeviceStateToFile Method
Saves the currently opened device and its settings to a file.
Syntax:
[VB.NET]
Public Sub SaveDeviceStateToFile( filename As String )

[C#]
public void SaveDeviceStateToFile( string filename );

Parameter | Description
filename | The name of a device settings file to be (re-)created.
Limitations:

A valid device must be opened.
Remarks:

SaveDeviceStateToFile saves the following settings of IC Imaging Control:

  • Opened Device and its serial number
  • Video norm
  • Video format
  • Input channel
  • Frame rate
  • Vertical Flip
  • Horizontal Flip
  • All VCDProperties

With ICImagingControl.LoadDeviceStateFromFile, you can re-open the device with the saved settings.

Information:

Introduced in version 2.0
Sample:

The following example saves the currently opened device to a file named "device.dat".

[VB.NET]
IcImagingControl1.SaveDeviceStateToFile("device.dat")

[C#]
ICImagingControl1.SaveDeviceStateToFile("device.dat");
See also: ICImagingControl, ICImagingControl.LoadDeviceStateFromFile

<< ICImagingControl


ICImagingControl::LoadDeviceStateFromFile

ICImagingControl.LoadDeviceStateFromFile Method
Restores the device settings saved with ICImagingControl.SaveDeviceStateToFile.
Syntax:
[VB.NET]
Public Sub LoadDeviceStateFromFile( filename As String, OpenDevice As Boolean )

[C#]
public void LoadDeviceStateFromFile( string filename, bool OpenDevice );

Parameter | Description
filename | A file containing device information created by ICImagingControl.SaveDeviceStateToFile.
OpenDevice | If this parameter is set to false, the method does not open a new device. if the device stored in the settings is different from the one that is already opened, an error is returned. Otherwise the settings are applied to the device. If this parameter is set to true, the method will open the device specified in the settings.
Information:

Introduced in version 2.0
Sample:

The following example loads device settings from "device.dat" and starts live video:

[VB.NET]
Try
    IcImagingControl1.LoadDeviceStateFromFile("device.dat", False)
Catch
    MessageBox.Show("Load device failed.")
End Try
If IcImagingControl1.DeviceValid Then
    IcImagingControl1.LiveStart()
End If

[C#]
try
{
    ICImagingControl1.LoadDeviceStateFromFile("device.dat", false);
}
catch(Exception ICEx)
{
    MessageBox.Show(this,"Load device failed.");
}
if (ICImagingControl1.DeviceValid)
{
    ICImagingControl1.LiveStart();
}
See also: ICImagingControl, ICImagingControl.SaveDeviceStateToFile

<< ICImagingControl


ICImagingControl::DeviceCountOfFramesDropped

ICImagingControl.DeviceCountOfFramesDropped Property
Returns the number dropped frames.
Syntax:
[VB.NET]
Public DeviceCountOfFramesDropped As Integer

[C#]
public int DeviceCountOfFramesDropped;
Limitations:

Read only, live mode must be started.
Information:

Introduced in version 2.0
See also: ICImagingControl, ICImagingControl.DeviceCountOfFramesNotDropped, ICImagingControl.LiveStart

<< ICImagingControl


ICImagingControl::DeviceCountOfFramesNotDropped

ICImagingControl.DeviceCountOfFramesNotDropped Property
Returns the number of frames that were not dropped.
Syntax:
[VB.NET]
Public DeviceCountOfFramesNotDropped As Integer

[C#]
public int DeviceCountOfFramesNotDropped;
Limitations:

Read only, live mode must be started before.
Information:

Introduced in version 2.0
See also: ICImagingControl, ICImagingControl.DeviceCountOfFramesDropped, ICImagingControl.LiveStart

<< ICImagingControl


ICImagingControl::ShowDeviceSettingsDialog

ICImagingControl.ShowDeviceSettingsDialog Method
This method opens a video capture device selection dialog.
Syntax:
[VB.NET]
Public Function ShowDeviceSettingsDialog() As DialogResult
Public Function ShowPropertyDialog( IntPtr hParentWindow ) As DialogResult
Public Function ShowPropertyDialog( System.Windows.Forms.IWin32Window owner ) As DialogResult

[C#]
public DialogResult ShowDeviceSettingsDialog();
public DialogResult ShowDeviceSettingsDialog( IntPtr hParentWindow );
public DialogResult ShowDeviceSettingsDialog( IWin32Window owner );

Parameter | Description
hParentWindow | Handle to the parent window used when creating the dialog.
owner | A System.Windows.Forms.IWin32Window identifying the parent window used when creating the dialog.
Return Value:

This function returns System.Windows.Forms.DialogResult.OK, if the user selected a device and clicked the OK button. If the user clicked the Cancel button instead, the return value is System.Windows.Forms.DialogResult.Cancel.

Remarks:

The method ShowDeviceSettingsDialog opens the IC Imaging Control built-in device selection dialog. In the dialog the end user can select a video capture device and adjust it's video norm, video format and input channel. If supported, frame rate, vertical and horizontal flip property can also be set.

Information:

Introduced in version 2.0
Sample:

This example demonstrates how to show the dialog and start live mode:

[VB.NET]
' We have to stop live mode.
If IcImagingControl1.LiveVideoRunning Then
    IcImagingControl1.LiveStop()
End If

' Show the dialog.
IcImagingControl1.ShowDeviceSettingsDialog()

' If the user has selected a device, start live mode.
If IcImagingControl1.DeviceValid Then
    IcImagingControl1.LiveStart()
End If

[C#]
// We have to stop live mode here.
if (ICImagingControl1.LiveVideoRunning)
{
    ICImagingControl1.LiveStop();
}

// Show the dialog.
ICImagingControl1.ShowDeviceSettingsDialog();

// If the user selected a device, start live mode.
if (ICImagingControl1.DeviceValid)
{
    ICImagingControl1.LiveStart();
}
See also: ICImagingControl, ICImagingControl.ShowPropertyDialog

<< ICImagingControl


ICImagingControl::ShowPropertyDialog

ICImagingControl.ShowPropertyDialog Method
This method opens a dialog to adjust all properties of the currently opened video capture device.
Syntax:
[VB.NET]
Public Sub ShowPropertyDialog()
Public Sub ShowPropertyDialog( IntPtr hParentWindow )
Public Sub ShowPropertyDialog( System.Windows.Forms.IWin32Window owner )

[C#]
public void ShowPropertyDialog();
public void ShowPropertyDialog( IntPtr hParentWindow );
public void ShowPropertyDialog( IWin32Window owner );

Parameter | Description
hParentWindow | Handle to the parent window used when creating the dialog.
owner | A System.Windows.Forms.IWin32Window identifying the parent window used when creating the dialog.
Information:

Introduced in version 2.0
Sample:

This example demonstrates how to show the dialog:

[VB.NET]
IcImagingControl1.ShowPropertyDialog()

[C#]
ICImagingControl1.ShowPropertyDialog();
See also: ICImagingControl, ICImagingControl.ShowDeviceSettingsDialog

<< ICImagingControl


ICImagingControl::SignalDetectedAvailable

ICImagingControl.SignalDetectedAvailable Property
Returns whether the current video capture device supports signal detection on its input ports.
Syntax:
[VB.NET]
Public SignalDetectedAvailable As Boolean

[C#]
public bool SignalDetectedAvailable;
Limitations:

Run time only, read only.

Remarks:

If SignalDetectedAvailable is True, SignalDetected returns whether a video signal is detected on the currently selected input channel of the open video capture device.

Information:

Introduced in version 2.0
See also: ICImagingControl, ICImagingControl.SignalDetected

<< ICImagingControl


ICImagingControl::SignalDetected

ICImagingControl.SignalDetected Property
Returns whether a video signal is detected on the currently selected input channel of the selected video capture device.
Syntax:
[VB.NET]
Public SignalDetected As Boolean

[C#]
public bool SignalDetected;
Limitations:

Run time only, read only.
Remarks:

This availability of this property can be checked using ICImagingControl.SignalDetectedAvailable.

Information:

Introduced in version 2.0
See also: ICImagingControl, ICImagingControl.SignalDetectedAvailable

<< ICImagingControl


ImageBuffer::SaveAsJpeg

ImageBuffer.SaveAsJpeg Method
Saves the contents of the buffer to a JPEG compressed file to disk.
Syntax:
[VB.NET]
Public Sub SaveAsJpeg(Filename As String, Quality As Integer)

[C#]
public void SaveAsJpeg(string Filename, int Quality);

Parameter | Description
Filename | The name of the file to which the buffer is saved.
Quality | Desired image quality. Should be in the range between 0 and 100.
Information:

Introduced in version 2.0
Sample:

This example shows how to save the contents of an ImageBuffer to a file called "test.jpg":

[VB.NET]
Dim Buf As ImageBuffer
Buf = IcImagingControl1.ImageBuffers(0)
Buf.SaveAsJpeg("test.jpg", 100)

[C#]
ImageBuffer Buf = ICImagingControl1.ImageBuffers[0];
Buf.SaveAsJpeg("test.jpg", 100);
See also: ImageBuffer, ImageBuffer.SaveAsBitmap

<< ImageAvailableEventArgs.ImageBuffer


ImageBuffer::SaveAsBitmap

ImageBuffer.SaveAsBitmap Method
Saves the contents of the buffer to a bitmap file on disk.
Syntax:
[VB.NET]
Public Sub SaveAsBitmap(Filename As String, colorformat As ICImagingControlColorformats)

[C#]
public void SaveAsBitmap(string Filename, ICImagingControlColorformats colorformat);

Parameter | Description
Filename | The name of the file to which the buffer is saved.
colorformat | The desired color format of the bitmap file.
Information:

Introduced in version 2.0
Sample:

This example shows how to save the contents of an ImageBuffer as an 8-bit gray bitmap:

[VB.NET]
Dim Buf As ImageBuffer
Buf = IcImagingControl1.ImageBuffers(0)
Buf.SaveAsBitmap("test.bmp", ICImagingControlColorformats.ICY8)

[C#]
ImageBuffer Buf = ICImagingControl1.ImageBuffers[0];
Buf.SaveAsBitmap("test.bmp", ICImagingControlColorformats.ICY8);
See also: ImageBuffer, ImageBuffer.SaveAsJpeg

<< ImageAvailableEventArgs.ImageBuffer


ImageBuffer::Lines

ImageBuffer.Lines Property
Returns the number of lines in this ImageBuffer.
Syntax:
[VB.NET]
Public Lines As Integer

[C#]
public int Lines;
Limitations:

Read only.
Information:

Introduced in version 2.0
See also: ImageBuffer, ImageBuffer.PixelPerLine

<< ImageAvailableEventArgs.ImageBuffer


ImageBuffer::PixelPerLine

ImageBuffer.PixelPerLine Property
Returns the number of pixels in each line of this ImageBuffer.
Syntax:
[VB.NET]
Public PixelPerLine As Integer

[C#]
public int PixelPerLine;
Limitations:

Read only.
Information:

Introduced in version 2.0
See also: ImageBuffer, ImageBuffer.Lines, ImageBuffer.BitsPerPixel

<< ImageAvailableEventArgs.ImageBuffer


OverlayBitmap::DrawFrameRect

OverlayBitmap.DrawFrameRect Method
This method draws an empty frame rectangle on the live video.
Syntax:
[VB.NET]
Public Sub DrawFrameRect( clr As System.Drawing.Color, XStart As Integer, YStart As Integer, XEnd As Integer, YEnd As Integer )

[C#]
public void DrawFrameRect( System.Drawing.Color clr, int XStart, int YStart, int XEnd, int YEnd );

Parameter | Description
color, clr | Specifies the color of the frame.
startcolumn, XStart | Specifies the column in pixel units of the upper left hand corner of the rectangle on the live video.
startrow, YStart | Specifies the row in pixel units of the upper left hand corner of the rectangle on the live video.
endcolumn, XEnd | Specifies the column in pixel of the lower right hand corner of the rectangle on the live video.
endrow, YEnd | Specifies the row in pixel units of the lower right hand corner of the rectangle on the live video.
Limitations:

Run time only. Only after ICImagingControl.LiveStart has been called once.
Information:

Introduced in version 2.0
Example:

This example demonstrates how to draw a red frame on the live video.

[VB.NET]
Dim ob As OverlayBitmap
ob = IcImagingControl1.OverlayBitmap

ob.DrawFrameRect(System.Drawing.Color.Red, 10, 10, 10, 250)

[C#]
OverlayBitmap ob = ICImagingControl1.OverlayBitmap;

ob.DrawFrameRect(System.Drawing.Color.Red, 10, 10, 10, 250);
See also: OverlayBitmap, OverlayBitmap.DrawSolidRect, ICImagingControl.LiveStart

<< ICImagingControl.OverlayBitmap


OverlayBitmap::DrawFrameEllipse

OverlayBitmap.DrawFrameEllipse Method
This method draws an empty frame ellipse on the live video.
Syntax:
[VB.NET]

Public Sub DrawFrameEllipse( clr As System.Drawing.Color, x0 As Integer, y0 As Integer, x1 As Integer, y1 As Integer )

[C#]

public void DrawFrameEllipse( System.Drawing.Color clr, int x0, int y0, int x1, int y1 );

Parameter | Description
clr | Specifies the color of the ellipse.
x0 | Specifies the column in pixel units of the upper left hand corner of the bounding rectangle of the ellipse on the live video.
y0 | Specifies the row in pixel units of the upper left hand corner of the bounding rectangle of the ellipse on the live video.
x1 | Specifies the column in pixel units of the lower right hand corner of the bounding rectangle of the ellipse on the live video.
y1 | Specifies the row in pixel units of the lower right hand corner of the bounding rectangle of the ellipse on the live video.
Limitations:

Run time only. Only after ICImagingControl.LiveStart has been called once.
Information:

Introduced in version 2.0
Example:

This example demonstrates how to draw a empty yellow ellipse on the live video.

[VB.NET]
Dim ob As OverlayBitmap
ob = IcImagingControl1.OverlayBitmap

ob.DrawFrameEllipse(System.Drawing.Color.Yellow, 100, 100, 250, 200)

[C#]
OverlayBitmap ob = ICImagingControl1.OverlayBitmap;

ob.DrawFrameEllipse(System.Drawing.Color.Yellow, 100, 100, 250, 200);
See also: OverlayBitmap, OverlayBitmap.DrawSolidEllipse, ICImagingControl.LiveStart

<< ICImagingControl.OverlayBitmap


OverlayBitmap::DrawSolidRect

OverlayBitmap.DrawSolidRect Method
This method draws a solid, filled rectangle on the live video.
Syntax:
[VB.NET]
Public Sub DrawSolidRect( clr As System.Drawing.Color, XStart As Integer, YStart As Integer, XEnd As Integer, YEnd As Integer )

[C#]
public void DrawSolidRect( System.Drawing.Color clr, int XStart, int YStart, int XEnd, int YEnd );

Parameter | Description
color, clr | Specifies the color of the rectangle.
startcolumn, XStart | Specifies the column in pixel units of the upper left hand corner of the rectangle on the live video.
startrow, YStart | Specifies the row in pixel units of the upper left hand corner of the rectangle on the live video.
endcolumn, XEnd | Specifies the column in pixel of the lower right hand corner of the rectangle on the live video.
endrow, YEnd | Specifies the row in pixel units of the lower right hand corner of the rectangle on the live video.
Limitations:

Run time only. Only after ICImagingControl.LiveStart has been called once.
Example:

This example demonstrates how to draw a red rectangle on the live video.

[VB.NET]
Dim ob As OverlayBitmap
ob = IcImagingControl1.OverlayBitmap

ob.DrawSolidRect(System.Drawing.Color.Red, 10, 10, 10, 250)

[C#]
OverlayBitmap ob = ICImagingControl1.OverlayBitmap;

ob.DrawSolidRect(System.Drawing.Color.Red, 10, 10, 10, 250);
See also: OverlayBitmap, OverlayBitmap.DrawFrameRect, ICImagingControl.LiveStart

<< ICImagingControl.OverlayBitmap


Project Wizards for Visual Studio

For Visual Basic and Visual C#, there are wizards that allow to easily setup an application that uses IC Imaging Control, as well as setup a frame filter and frame filter module.

All IC Imaging Control wizard names start with "IC" e.g. "IC Frame Filter Class".

Application Wizard

This chapter shows how to create a new imaging application, using the application wizard.

Frame Filter Class Wizard

This chapter shows how to create a new frame filter class, using the frame filter class wizard.

<< IC Imaging Control .NET Component User's Guide


Application Wizard

This chapter shows how to create a new imaging application, using the application wizard.

Introduction

The application wizard creates the project for a complete imaging application. The following functionality is available out of the box:

  • Event handler to open a video capture device
  • Event handler for image settings
  • Event handler to start and stop the live video
  • Automatic reload the previously used video capture device

Optional functions are:

  • Add image processing capabilities
  • Display the result of the image processing, instead of the live video

How to use

First of all, start Visual Studio. As soon as the Start Page appears, click on the New Project button. If this dialog does not appear, select File -> New -> Project from Visual Studio's menu.

This article describes the wizard for C#. The VB wizard is similar.

You should see the following dialog:

Select the icon labeled IC 3.1 C# Application and enter a valid project name into the Name input field, for example "ImageProcessing". Then, click on the OK button. Once this step has been competed, you can set the projects parameters:

Add toolbar check box
When this check box is checked, an toolbar is inserted into the applications form. This check box is not in the dialog application available.
Add image processing functionality check box
When this check box is checked, an image processing method is inserted into the application. For demonstration purposes, the image is inverted.
Process image manually / Process images automatically radio buttons
This setting determines whether: i) the image processing method is applied to a frame only when the user clicks on a menu entry or a button; or whether: ii) the image processing method is applied to all frames.
Display processed image check box
When this check box is checked, the resulting image of the image processing is displayed instead of a live video.

Resulting Application

Once you have followed all the steps on this page, click on the Finish button to finish the project. The project will then be created by the wizard. The newly created application should look as follows:

<< Project Wizards for Visual Studio


Frame Filter Class Wizard

This chapter shows how to create a new frame filter class, using the frame filter class wizard.

Introduction

The frame filter class wizard creates the source code for a frame filter class. For demonstration purposes, the image processing that has been implemented shows how to inverts the incoming frames. This should be overwritten by the programmer.

How to use

Right-click your project in the Solution Explorer and select Add... -> New Item... or use the main menu and select Project -> Add New Item.... In the following dialog, select the entry Add IC 3.1 Frame Filter.

Click the Add button and the next dialog shows the available options to create a frame filter class:

Input field description

Class name
This is the name of the class e.g. InverterFilter.
Namespace
This is the name of the namespace in which the new class will be declared. The programmer may overwrite this name.
Filename
This is the name of the source code file of the class. The name is generated by the class wizard. The programmer may overwrite this name.
Notify at start and stop live video
If this check box is checked, then the frame filter class wizard overrides the methods of FrameFilterImpl that are called when LiveStart and LiveStop are called. The methods are named NotifyStart and NotifyStop. A new boolean member variable, called m_bLiveVideoRunning is added to the class. In your Transform method, you can use this variable to determine whether live video is running and thus certain actions have to be performed.

Once you have made all the above inputs, click on the Finish button in order for the wizard to create the class.

<< Project Wizards for Visual Studio


Programmer's Guide

Perform your first steps with IC Imaging Control.

First Steps Visual Studio .NET 2003 - 2008

This chapter shows you how to get started with IC Imaging Control in Visual Studio 2003 to 2008.

First Steps Visual Studio .NET 2010

This chapter shows you how to get started with IC Imaging Control in Visual Studio 2010.

Update from 3.0 to 3.1

This chapter shows how to update an existing project from IC Imaging Control 3.0 to 3.1

Grabbing an Image

This chapter shows you how to grab a still image from the video stream and save it to a .BMP file.

Adjust Image Settings

This chapter shows you how to adjust image settings such as brightness, contrast, saturation, etc.

Capturing an AVI File

This chapter shows you how to save a video stream as a compressed AVI file.

Saving Codec Properties

This chapter shows you how to handle codecs and how to save and load the properties of a codec.

Controlling DV Devices

This sample shows you how to control the external transport features of your DV device from IC Imaging Control. External Transport means starting, stopping, winding etc. of the tape in the DV device.

Making Device Settings

This chapter shows you how to create a custom device settings dialog. The code is provided in reusable form, thus it can be easily integrated into your own applications.

Building an Application

This sample program shows you how to use all the building blocks from the previous chapters to create a real program.

Performing Image Processing

This chapter shows you how to create your own image processing functions.

Using Multiple Buffers

In the previous chapters, IC Imaging Control appeared to work with only one image buffer. In fact, IC Imaging Control uses multiple buffers to store image data. This chapter describes how multiple buffers are organized inside IC Imaging Control and in which way a program can access these buffers. Internally, IC Imaging Control uses a ring buffer to store image data. The next section will describe the idea behind the ring buffer concept.

Displaying Buffers on the ImageAvailable Event

This chapter shows how to control the display of image buffers using the ImageAvailable event.

Accessing an Image Buffer

This example shows the how to handle image buffers.

Performing Advanced Image Processing

This chapter illustrates how to perform sophisticated image processing.

Creating an Overlay

This chapter shows you how to write text and draw graphics on the live video images.

Scroll and Zoom

This chapter shows you how to use the scroll and zoom capabilities of IC Imaging Control.

Basic Use of VCD Properties

This chapter illustrates the basic functionality of the VCDProperties. It shows you how to retrieve interfaces which allow you to manipulate elements, such as the value or the automation state of a property.

List VCDProperties

This chapter shows you how to retrieve all properties of a video capture device using the new VCD property interface.

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.

Capturing a Video File

This chapter shows you how to save a video stream as a compressed video file. In contrast to the Capturing an AVI File example, the MediaStreamSink is used to allow several video file formats to be recorded.

Filter Inspector

This example demonstrates how to use frame filters to perform basic image processing.

Writing a Frame Filter: Binarization

This example demonstrates how to create frame filters to apply binarization to live video.

<< IC Imaging Control .NET Component User's Guide


First Steps Visual Studio .NET 2003 - 2008

This chapter shows you how to get started with IC Imaging Control in Visual Studio 2003 to 2008.

With just a few mouse clicks and one line of code, you will be able to display a live video image in your .NET program. This article shows how to create a Visual Basic™ project. The steps to create a C#™ project are similar.

Creating the Project

Assuming that you have already run the IC Imaging Control installation program and started Visual Studio .NET, the next step is to create a project. To do this select the "New" command from the "File" menu, then select "Project".

Now choose "Visual Basic Project" as "Project Type" and "Windows Application" as "Template". Name the application "FirstStep" and click the OK button to create the new project.

Now that the project has been created, select the "Components" tab from the "Toolbox". If there is no "Toolbox", select "Toolbox" from the "View" menu.

Right click on the "Toolbox" and choose "Choose Items..." from the context menu. The "Choose Toolbox Items" dialog is displayed. Scroll down until ICImagingControl is shown:

Make sure its version starting with 3.2 and it is checked. Then click the "OK" button.

ICImagingControl is now listed in the "Toolbox" and ready to use.

Creating the Control

Select the ICImagingControl component from the "Toolbox" and draw it on the form. A white rectangle should appear on the form. Right click on that control and select "Properties" from the context menu to make the "Properties" window of the ICImagingControl appear.

Selecting a Video Source

In the properties window select the "Device" property and click the button "..."

Making Device Settings

A dialog will appear and you can select a device. You can also configure the video norm, the video format, and the input channel.

Adjusting Image Settings

If you want to adjust the image settings, select the "VCDPropertyItems" property and click the "..." button:

A dialog appears in which you can configure the image settings. The live video is also running, while the property dialog is open, so that you can see the result of your adjustments

Adding Program Code

Now that the video capture device is configured, only a single line of code in the FormLoad event is needed to display a live image:

[VB.NET]
Private Sub Form1_Load(ByVal sender As System.Object, ByVal e As System.EventArgs) Handles MyBase.Load
    IcImagingControl1.LiveStart()
End Sub

[C#]
private void Form1_Load(object sender, System.EventArgs e)
{
    icImagingControl1.LiveStart();
}

Running the Program

You have now finished. You are now ready to hit F5 and watch your program display a live video.

<< Programmer's Guide


First Steps Visual Studio .NET 2010

This chapter shows you how to get started with IC Imaging Control in Visual Studio 2010.

With just a few mouse clicks and one line of code, you will be able to display a live video image in your .NET program. This article shows how to create a Visual Basic™ project. The steps to create a C#™ project are similar.

Creating the Project

Assuming that you have already run the IC Imaging Control installation program and started Visual Studio .NET, the next step is to create a project. To do this select the "New" command from the "File" menu, then select "Project".

Now choose "Visual Basic" from the templates and "Windows Forms Application". Name the application "FirstStep". You may select the .NET Framework version here. It can be every version starting from 2.0. Then click the OK button to create the new project.

Now that the project has been created, select the "Components" tab from the "Toolbox". If there is no "Toolbox", select "Toolbox" from the "View" menu.

Right click on the "Toolbox" and choose "Choose Items..." from the context menu. The "Choose Toolbox Items" dialog is displayed. Scroll down until ICImagingControl is shown:

Make sure its version starting with 3.2 and it is checked. Then click the "OK" button.

ICImagingControl is now listed in the "Toolbox" and ready to use.

Creating the Control

Select the ICImagingControl component from the "Toolbox" and draw it on the form of your project. A white rectangle should appear on the form. Right click on that control and select "Properties" from the context menu to make the "Properties" window of the ICImagingControl appear.

Selecting a Video Source

In the properties window select the "Device" property and click the button "..."

Making Device Settings

A dialog will appear and you can select a device. You can also configure the video norm, the video format, and the input channel.

Adjusting Image Settings

If you want to adjust the image settings, select the "VCDPropertyItems" property and click the "..." button:

A dialog appears in which you can configure the image settings. The live video is also running, while the property dialog is open, so that you can see the result of your adjustments

Adding Program Code

Now that the video capture device is configured, only a single line of code in the FormLoad event is needed to display a live image:

[VB.NET]
Private Sub Form1_Load(ByVal sender As System.Object, ByVal e As System.EventArgs) Handles MyBase.Load
    IcImagingControl1.LiveStart()
End Sub

[C#]
private void Form1_Load(object sender, System.EventArgs e)
{
    icImagingControl1.LiveStart();
}

Running the Program

You have now finished. You are now ready to start, debug and watch your program display a live video.

<< Programmer's Guide


Update from 3.0 to 3.1

This chapter shows how to update an existing project from IC Imaging Control 3.0 to 3.1

Following steps must be performed for an update:

  • Load the solution.
  • Remove IC Imaging Control from the form.
  • Remove following references from the solution: AxInterop.ICImagingControl3, Interop.ICImagingControl3, dotnetfilter and imagingcontrol3
  • Close the solution.
  • Delete the file "licenses.licx".
  • Open the solution, make sure the old references are away.
  • The file "licenses.licx" will be shown as missing. Delete it from the solution.
  • Rebuild solution and ignore the errors.
  • Insert the IC Imaging Control 3.2 component. Make sure, the version number starts with "3.2". Make sure, it's name is "icImagingControl1", or the name you used for it in your project.
  • You may need to reimplement the message handlers. Just add them as usually and copy the the content of the old functions into the new ones. This is necessary for ImageAvailable, DeviceLost etc.

<< Programmer's Guide


Grabbing an Image

This chapter shows you how to grab a still image from the video stream and save it to a .BMP file.

The source code for the VB.NET and C# versions of this sample program can be found in the directories samples\VB *\Grabbing an Image and samples\C# *\Grabbing an Image in your My Documents/IC Imaging Control 3.2 directory.

Setting up the Project

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 FirstSteps 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.

Now, add 3 buttons to the form and label them "Start Live", "Stop Live" and "Save Bitmap". Name the buttons cmdStartLive, cmdStopLive and cmdSaveBitmap respectively.

Add calls to IC Imaging Control's LiveStart and LiveStop methods:

[VB.NET]
Private Sub cmdStartLive_Click(ByVal sender As System.Object, ByVal e As System.EventArgs) Handles cmdStartLive.Click
    IcImagingControl1.LiveStart()
End Sub

[C#]
private void cmdStartLive_Click(object sender, EventArgs e)
{
    icImagingControl1.LiveStart();
}

[VB.NET]
Private Sub cmdStopLive_Click(ByVal sender As System.Object, ByVal e As System.EventArgs) Handles cmdStopLive.Click
    IcImagingControl1.LiveStop()
End Sub

[C#]
private void cmdStopLive_Click(object sender, EventArgs e)
{
    if (icImagingControl1.LiveVideoRunning == true)
        icImagingControl1.LiveStop();
}

Run the program. You can now start and stop the live image by clicking on the respective buttons.

The video format describes the width, height and color depth of the video stream. Select the one you would like to use.

When the live video is running, a call to the MemorySnapImage method will grab the image that is currently being displayed and store it in IC Imaging Control's image buffer. When you stop the live image, however, the last frame of the live image is stored automatically. In both cases, the grabbed image can be saved with the MemorySaveImage method. Only a common dialog box has to be added, so that a filename can be selected.

[VB.NET]
Private Sub cmdSaveBitmap_Click(ByVal sender As System.Object, ByVal e As System.EventArgs) Handles cmdSaveBitmap.Click
    IcImagingControl1.MemorySnapImage()
    ' Call the save file dialog to enter the file name of the image
    Dim saveFileDialog1 As New SaveFileDialog
    saveFileDialog1.Filter = "bmp files (*.bmp)|*.bmp|All files (*.*)|*.*"
    saveFileDialog1.FilterIndex = 1
    saveFileDialog1.RestoreDirectory = True

    If saveFileDialog1.ShowDialog() = DialogResult.OK Then
        ' Save the image.
        IcImagingControl1.MemorySaveImage(saveFileDialog1.FileName)
    End If
End Sub

[C#]
private void cmdSaveBitmap_Click(object sender, EventArgs e)
{
    SaveFileDialog saveFileDialog1;
    icImagingControl1.MemorySnapImage();
    saveFileDialog1 = new SaveFileDialog();
    saveFileDialog1.Filter = "bmp files (*.bmp)|*.bmp|All files (*.*)|*.*";
    saveFileDialog1.FilterIndex = 1;
    saveFileDialog1.RestoreDirectory = true;

    if (saveFileDialog1.ShowDialog() == DialogResult.OK)
    {
        icImagingControl1.MemorySaveImage(saveFileDialog1.FileName);
    }
}

Now you can start the live image to adjust your cameras brightness and focus, and then stop the live display and save the captured image.

<< Programmer's Guide


Adjust Image Settings

This chapter shows you how to adjust image settings such as brightness, contrast, saturation, etc.

The source code for the VB.NET and C# versions of this sample program can be found in the directories samples\VB *\Adjusting Image Settings and samples\C# *\Adjusting Image Settings in your My Documents/IC Imaging Control 3.2 directory.

Setting up the Project

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 FirstSteps 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.

Add a Label control and a Slider to the form. Set the Label control's Caption property to "Brightness".

Image Settings such as brightness are provided through the VCDRangeProperty. To enable easy access to the range properties, this sample uses the VCDSimpleProperty class. This class is declared in the TIS.Imaging.VCDHelpers namespace. Please add the namespaces to the form:

[VB.NET]
Imports TIS.Imaging
Imports TIS.Imaging.VCDHelpers

[C#]
using TIS.Imaging;
using TIS.Imaging.VCDHelpers;

Writing the source code

First of all add a new variable to your form:

[VB.NET]
private VCDProp as VCDSimpleProperty

[C#]
private VCDSimpleProperty VCDProp;

You then need to initialize the VCDProp variable to get access to the properties of the video capture device.

[VB.NET]
VCDProp = VCDHelpers.VCDSimpleModule.GetSimplePropertyContainer(IcImagingControl1.VCDPropertyItems)

[C#]
VCDProp = VCDHelpers.VCDSimpleModule.GetSimplePropertyContainer(icImagingControl1.VCDPropertyItems);

Then the slider is initialized, thus it has the correct value for minimum and maximum.

After initializing the range, the VCDProp.RangeValue(VCDID_Brightness) return value is used to initialize the thumb position of the slider. A call to the LiveStart method starts the live image display.

[VB.NET]
Private Sub Form1_Load(ByVal sender As System.Object, ByVal e As System.EventArgs) Handles MyBase.Load

    IcImagingControl1.ShowDeviceSettingsDialog()

    If Not IcImagingControl1.DeviceValid Then
        System.Windows.Forms.MessageBox.Show("No device was selected.", "Adjusting Image Setting", System.Windows.Forms.MessageBoxButtons.OK, MessageBoxIcon.Information)
        Me.Close()
        Return
    End If

    If IcImagingControl1.DeviceValid = True Then

        IcImagingControl1.LiveStart()

        VCDProp = VCDSimpleModule.GetSimplePropertyContainer(IcImagingControl1.VCDPropertyItems)

        '  Setup the range of the brightness slider.
        trackBar1.Minimum = VCDProp.RangeMin(VCDIDs.VCDID_Brightness)
        trackBar1.Maximum = VCDProp.RangeMax(VCDIDs.VCDID_Brightness)

        '  Set the slider to the current brightness value.
        trackBar1.Value = VCDProp.RangeValue(VCDIDs.VCDID_Brightness)

    End If

End Sub

[C#]
private void Form1_Load(object sender, EventArgs e)
{
    if (!icImagingControl1.DeviceValid)
    {
        icImagingControl1.ShowDeviceSettingsDialog();

        if (!icImagingControl1.DeviceValid)
        {
            MessageBox.Show("No device was selected.", "Adjusting Image Setting",
                             MessageBoxButtons.OK, MessageBoxIcon.Information);
            this.Close();
            return;
        }
    }

    if (icImagingControl1.DeviceValid == true)
    {
        icImagingControl1.LiveStart();

        VCDProp = VCDSimpleModule.GetSimplePropertyContainer(icImagingControl1.VCDPropertyItems);

        //  Setup the range of the brightness slider.
        trackBar1.Minimum = VCDProp.RangeMin(VCDIDs.VCDID_Brightness);
        trackBar1.Maximum = VCDProp.RangeMax(VCDIDs.VCDID_Brightness);

        //  Set the slider to the current brightness value.
        trackBar1.Value = VCDProp.RangeValue[VCDIDs.VCDID_Brightness];
    }
}

Finally, only a single line of code is required to adjust the brightness setting when the slider is moved:

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

[C#]
private void trackBar1_Scroll(object sender, EventArgs e)
{
    VCDProp.RangeValue[VCDIDs.VCDID_Brightness] = trackBar1.Value;
}

You are now ready to run the program, and move the slider's thumb with the mouse to adjust brightness. All image settings are handled in the same way, so once you know how to adjust brightness, you also know how to handle contrast, hue, zoom, and all the other settings.

<< Programmer's Guide


Capturing an AVI File

This chapter shows you how to save a video stream as a compressed AVI file.

To see how to save video streams in different file formats, see the Capturing a Video File example.

The source code for the VB.NET and C# versions of this sample program can be found in the directories samples\VB *\Capturing an AVI File and samples\C# *\Capturing an AVI File in your My Documents/IC Imaging Control 3.2 directory.

Setting up the Project

Create a new project and add IC Imaging Control to the form. Before you run the program, select the video capture device, input and video format as shown in the FirstSteps 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 first made a selection, the program will display an error message and terminate.

Now add 3 buttons to the form and label them Start Live, Stop Live and Capture AVI. Name the buttons cmdStartLive, cmdStopLive and cmdCaptureVideo respectively.

Add calls to IC Imaging Control's LiveStart and LiveStop methods:

[VB.NET]
Private Sub cmdStartLive_Click(ByVal sender As System.Object, ByVal e As System.EventArgs) Handles cmdStartLive.Click
    IcImagingControl1.LiveStart()
End Sub

[C#]
private void cmdStartLive_Click(object sender, EventArgs e)
{
    icImagingControl1.LiveStart();
}

[VB.NET]
Private Sub cmdStopLive_Click(ByVal sender As System.Object, ByVal e As System.EventArgs) Handles cmdStopLive.Click
    IcImagingControl1.LiveStop()
End Sub

[C#]
private void cmdStopLive_Click(object sender, EventArgs e)
{
    icImagingControl1.LiveStop();
}

Run the program. You can now start and stop the live image by clicking on the respective buttons. This does not yet create an AVI file, but is required to create a preview for the live video stream. This is usually required to set up the camera before actually starting to record.

The AVI Recording Dialog

Now add another form to your project. Name it frmWriteAVI. Add a combo box for the available video codecs, a text box for the AVI filename, and buttons to start and stop AVI capture. (You may want to load the sample project instead of creating the form manually).

In the FormLoad event, the selection list is filled with the names of all video codecs installed on your computer. These can be used as an AVI compressor.

[VB.NET]
Private Sub writeavi_Load(ByVal sender As System.Object, ByVal e As System.EventArgs) Handles MyBase.Load
    'Insert all installed codecs into the cboVideoCodec combobox.
    For Each Codec As TIS.Imaging.AviCompressor In ICControl.AviCompressors
        cboVideoCodec.Items.Add(Codec)
    Next
    ' Show the first codec in the combobox.
    cboVideoCodec.SelectedIndex = 0
End Sub

[C#]
private void WriteAvi_Load(object sender, EventArgs e)
{
    cboVideoCodec.DataSource = ICControl.AviCompressors;

    // Show the first codec in the combobox.
    cboVideoCodec.SelectedIndex = 0;
    cmdStopCapture.Enabled = true;
    cmdStartCapture.Enabled = true;

}

The Click event of the Start Capture button calls IC Imaging Control's AviStartCapture method, with the filename and the name of the video codec as a parameter. There is also some code to disable the Close button and enable the Stop Capture button and to check whether the user has selected a codec and a filename:

[VB.NET]
Private Sub cmdStartCapture_Click(ByVal sender As System.Object, ByVal e As System.EventArgs) Handles cmdStartCapture.Click
    If txtFilename.Text = "" Then
        MsgBox("Please select an AVI filename first.", vbExclamation + vbOKOnly)
    Else
        ICControl.AviStartCapture(txtFilename.Text, cboVideoCodec.SelectedItem)
        cmdStopCapture.Enabled = True
        cmdStartCapture.Enabled = False
    End If
End Sub

[C#]
private void cmdStartCapture_Click(object sender, EventArgs e)
{
    if (txtFilename.Text == "")
    {
        MessageBox.Show("Please select an AVI filename first.");
    }
    else
    {
        ICControl.AviStartCapture(txtFilename.Text, cboVideoCodec.SelectedItem.ToString());
        cmdStopCapture.Enabled = true;
        cmdStartCapture.Enabled = true;
    }
}

The Pause button is a check box with a graphical style. It is used to set and reset the LiveCapturePause property of IC Imaging Control. If the LiveCapturePause property is set to True, AVI capture is paused. This means, that only the sink path of the image stream is paused. The live video is still displayed, but the video is not saved to the video file. If the LiveCapturePause property is set to False, IC Imaging Control immediately continues AVI capture. A previously started AVI file will be continued.

[VB.NET]
Private Sub chkPause_CheckedChanged(ByVal sender As System.Object, ByVal e As System.EventArgs) Handles chkPause.CheckedChanged
    ICControl.LiveCapturePause = chkPause.CheckState
End Sub

[C#]
private void chkPause_CheckedChanged(object sender, EventArgs e)
{
    ICControl.LiveCapturePause = chkPause.Checked;
}

The AVI capture can be started by a call to AviStartCapture, even if the LiveCapturePause property is set to True. In this case, the image stream is initialized and started and the live video is displayed. The images are not saved to the AVI file because the sink path is paused. As soon as the LiveCapturePause property is set to False, the sink path is started and images are written to the AVI file. The advantage of this is that the AVI capturing can be started, paused and restarted immediately on an event.

Finished. You can now run the program, select a codec, and create an AVI file. Note that compressing a video stream is a highly CPU intensive operation and not all codecs will be able to work at full image resolution and full frame rate.

<< Programmer's Guide


Saving Codec Properties

This chapter shows you how to handle codecs and how to save and load the properties of a codec.

Introduction

The source code for the VB.NET and C# versions of this sample program can be found in the directories samples\VB *Saving Codec Properties and samples\C# *\Saving Codec Properties in your My Documents/IC Imaging Control 3.2 directory.

A codec compresses and decompresses video streams. Sometimes, a codec is also referred to as a "compressor" or an "avicompressor".

The properties of some (but not all) codecs can be retrieved and assigned with IC Imaging Control. For example, the quality of a video stream may be set before it is saved.

Codec properties are supplied as a binary data stream. It is very important to know the length of the data stream, as later when an application loads the data stream, it is required to allocate memory for it.

The saving file format must be binary, because the data stream is also binary.

You should not alter the binary data stream from a codec. Doing so would make the data no longer fit the codec, thus causing unpredictable errors. Furthermore, the codec properties of one codec will not match each other. IC Imaging Control prevents this situation from happening at all - it causes an error message.

A codec is an external DLL file that is handled by an AviCompressor object. If an AviCompressor object becomes invalid, the DLL will be removed from memory. In this case, most codecs will loose their previously set properties. You should, therefore, declare a global AviCompressor object in your form in order to avoid loosing properties.

You can retrieve data from or assign data to codecs where the property PropertyPageAvailable is True. It is therefore necessary to check this property before performing an operation.

Setting up the Project

Create a new project and add IC Imaging Control to the form. Now add 3 buttons to the form and label them Save Data, Load Data and Show Property Page. Name the buttons cmdSaveData, cmdLoadData and cmdShowPropertyPage respectively. Add at least one combo box to the form and name it cboVideoCodec. This combo box will contain the names of the codecs.

Setting Up the Codec

First of all, an application needs a global AviCompressor object that contains the data of the codec. This must be global, because the AviCompressor 's properties will be lost when it is removed from memory. So add the following line to the beginning of the form:

[VB.NET]
Dim Codec As TIS.Imaging.AviCompressor

[C#]
private TIS.Imaging.AviCompressor Codec;

Add a Form_Load event procedure to the form and enter the following code to fill the combo box with the available codecs:

[VB.NET]
Private Sub Form1_Load(ByVal sender As System.Object, ByVal e As System.EventArgs) Handles MyBase.Load
    'Insert all installed codecs into the cboVideoCodec combobox.
    For Each Codec As TIS.Imaging.AviCompressor In IcImagingControl1.AviCompressors
        cboVideoCodec.Items.Add(Codec)
    Next
    ' Show the first codec in the combobox.
    cboVideoCodec.SelectedIndex = 0

    Codec = CType(cboVideoCodec.SelectedItem(), TIS.Imaging.AviCompressor)

    ' Enable or disable the buttons.
    cmdShowPropertyPage.Enabled = Codec.PropertyPageAvailable
    cmdLoadData.Enabled = Codec.PropertyPageAvailable
    cmdSaveData.Enabled = Codec.PropertyPageAvailable
End Sub

[C#]
private void Form1_Load(object sender, EventArgs e)
{
    // Insert all installed codecs into the cboVideoCodec combobox.
    foreach (TIS.Imaging.AviCompressor _Codec in icImagingControl1.AviCompressors)
    {
        cboVideoCodec.Items.Add(_Codec);
    }
    // Show the first codec in the combobox.
    cboVideoCodec.SelectedIndex = 0;

    Codec = (TIS.Imaging.AviCompressor)cboVideoCodec.SelectedItem;

    // Enable or disable the buttons.
    cmdShowPropertyPage.Enabled = Codec.PropertyPageAvailable;
    cmdLoadData.Enabled = Codec.PropertyPageAvailable;
    cmdSaveData.Enabled = Codec.PropertyPageAvailable;
}

This code uses the AviCompressors property of IC Imaging Control to generate a list of all available codecs. As you can see, the global variable Codec is used as item in the For Each .. In .. statement. The first available codec will be assigned to the global AviCompressor object Codec. The three buttons will be enabled or disabled according to the property PropertyPageAvailable in the AviCompressor object. This avoids performing operations that are not supported by the codec.

Now add the SelectedValueChanged event procedure of the combo box cboVideoCodec to your form:

[VB.NET]
Private Sub cboVideoCodec_SelectedIndexChanged(ByVal sender As System.Object, ByVal e As System.EventArgs) Handles cboVideoCodec.SelectedIndexChanged
    Codec = CType(cboVideoCodec.SelectedItem(), TIS.Imaging.AviCompressor)

    ' Enable or disable the buttons.
    cmdShowPropertyPage.Enabled = Codec.PropertyPageAvailable
    cmdLoadData.Enabled = Codec.PropertyPageAvailable
    cmdSaveData.Enabled = Codec.PropertyPageAvailable
End Sub

[C#]
private void cboVideoCodec_SelectedIndexChanged(object sender, EventArgs e)
{
    Codec = (TIS.Imaging.AviCompressor)cboVideoCodec.SelectedItem;
    // Enable or disable the buttons.
    cmdShowPropertyPage.Enabled = Codec.PropertyPageAvailable;
    cmdLoadData.Enabled = Codec.PropertyPageAvailable;
    cmdSaveData.Enabled = Codec.PropertyPageAvailable;
}

The selected item of the combo box refers to an AviCompressor object. This item is assigned to the global AviCompressor object Codec.

The AviCompressor 's property PropertyPageAvailable is used to disable or enable the buttons. This prevents, for example, the user from pressing the cmdShowPropertyPage button when no property dialog is available for the codec.

Now, add the Click event procedure of the cmdShowPropertyPage button to your form:

[VB.NET]
Private Sub cmdShowPropertyPage_Click(ByVal sender As System.Object, ByVal e As System.EventArgs) Handles cmdShowPropertyPage.Click
    Codec.ShowPropertyPage()
End Sub

[C#]
private void cmdShowPropertyPage_Click(object sender, EventArgs e)
{
    Codec.ShowPropertyPage();
}

Saving the Codec Properties

As described above, the codec properties are supplied as a binary data stream. A binary data stream is simply a list of bytes. It is recommended to save the byte count in the data stream as the first element in the file. Using this first element, when the data is loaded from file, a dynamic array can be sized or resized to the matching byte count in order to accommodate the data.

Add the Click event procedure of cmdSaveData to your form:

[VB.NET]
Private Sub cmdSaveData_Click(ByVal sender As System.Object, ByVal e As System.EventArgs) Handles cmdSaveData.Click
    Try
        Dim Filestream As New System.IO.FileStream("test.bin", System.IO.FileMode.Create, System.IO.FileAccess.Write)

        ' Create the writer for data.
        Dim BinWriter As New System.IO.BinaryWriter(Filestream)

        BinWriter.Write(Codec.ToString())
        BinWriter.Write(Codec.CompressorDataSize)
        BinWriter.Write(Codec.CompressorData)

        BinWriter.Close()
        Filestream.Close()

    Catch ex As System.Exception
        MsgBox(ex.Message, MsgBoxStyle.Critical, "Write error")
    End Try
End Sub

[C#]
private void cmdSaveData_Click(object sender, EventArgs e)
{
    try
    {
        System.IO.FileStream Filestream = new System.IO.FileStream("test.bin", System.IO.FileMode.Create, System.IO.FileAccess.Write);
        System.IO.BinaryWriter BinWriter = new System.IO.BinaryWriter(Filestream);
        BinWriter.Write(Codec.Name);
        BinWriter.Write(Codec.CompressorDataSize);
        BinWriter.Write(Codec.CompressorData);

        BinWriter.Close();
        Filestream.Close();
    }
    catch (Exception Ex)
    {
        MessageBox.Show(Ex.Message);
    }
}

The codec properties will be saved in the file test.bin. Remember that the cmdSaveData button is only enabled, if AviCompressor.PropertyPageAvailable returns True. Alternatively, you can implement the following lines of code:

[VB.NET]
If Codec.PropertyPageAvailable Then
    ' Do something like saving etc.
Else
    MsgBox "This codec does not support properties!"
End If

[C#]
if( Codec.PropertyPageAvailable )
{
    //  Do something like saving etc.
}
else
{
    MessageBox.Show( "This codec does not support properties!");
}

Loading the Codec Properties

Add the Click event procedure of cmdLoadData to your form:

[VB.NET]
Private Sub cmdLoadData_Click(ByVal sender As System.Object, ByVal e As System.EventArgs) Handles cmdLoadData.Click
    Try
        ' Create the reader for data.
        Dim Filestrem As New System.IO.FileStream("test.bin", System.IO.FileMode.Open, System.IO.FileAccess.Read)
        Dim BinReader As New System.IO.BinaryReader(Filestrem)

        Dim CodecName As String

        ' Retrieve the name of the codec from the codec configuration file.
        CodecName = BinReader.ReadString()

        ' Compare the codec name in the file with the current codec's name.
        If Codec.Name = CodecName Then
            Dim codecDataLen As Integer = BinReader.ReadInt32()
            ' Assign the configuration data to the codec.
            Codec.CompressorData = BinReader.ReadBytes(codecDataLen)
        Else
            MsgBox("The saved data does not match to the used codec." + Chr(13) + _
                   "saved: " + CodecName + Chr(13) + _
                   "used: " + Codec.Name)
        End If
        BinReader.Close()
        Filestrem.Close()
    Catch ex As System.Exception
        MsgBox(ex.Message, MsgBoxStyle.Critical, "Read error")
    End Try
End Sub

[C#]
private void cmdLoadData_Click(object sender, EventArgs e)
{
    try
    {
        System.IO.FileStream Filestream = new System.IO.FileStream("test.bin", System.IO.FileMode.Open, System.IO.FileAccess.Read);
        System.IO.BinaryReader BinReader = new System.IO.BinaryReader(Filestream);
        String CodecName;

        // Retrieve the name of the codec from the codec configuration file
        CodecName = BinReader.ReadString();

        //Compare the codec name in the file with the current codec's name.
        if (Codec.Name == CodecName)
        {
            // Read the length of the binary data.
            int codecDataLen = BinReader.ReadInt32();
            // Assign the configuration data to the codec.
            Codec.CompressorData = BinReader.ReadBytes(codecDataLen);
        }
        else
        {
            MessageBox.Show("The saved data does not match to the used codec.\n" +
                    "saved: " + CodecName + "\n" +
                    "used: " + Codec.Name);
        }
        BinReader.Close();
        Filestream.Close();
    }
    catch (Exception Ex)
    {
        MessageBox.Show(Ex.Message);
    }
}

As described above at the cmdSaveData button, the cmdLoadData button is only enabled if AviCompressor.PropertyPageAvailable returns True. Before assigning data to a codec, you should check whether it supports properties:

[VB.NET]
If Codec.PropertyPageAvailable Then
    ' Do something like loading etc.
Else
    MsgBox "This codec does not support properties!"
End If

[C#]
if( Codec.PropertyPageAvailable )
{
    //  Do something like loading etc.
}
else
{
    MessageBox.Show( "This codec does not support properties!");
}

Using the Codec for Capture

For the sake of completeness, we have included the following statement that shows how to use the codec to capture an AVI file:

[VB.NET]
IcImagingControl1.AviStartCapture("test.avi", Codec)

[C#]
icImagingControl1.AviStartCapture("test.avi",Codec);

This is not included in the example.

<< Programmer's Guide


Controlling DV Devices

This sample shows you how to control the external transport features of your DV device from IC Imaging Control. External Transport means starting, stopping, winding etc. of the tape in the DV device.

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\VB *\Controlling DV Devices and samples\C# *Controlling DV Devicese in your My Documents/IC Imaging Control 3.2 directory.

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 2003 - 2008 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.

Now, add 2 buttons to the form and label them Start and Stop. Name the buttons cmdStart and cmdStop respectively.

Add calls to IC Imaging Control's LiveStart and LiveStop methods:

[VB.NET]
Private Sub cmdStart_Click(ByVal sender As System.Object, ByVal e As System.EventArgs) Handles cmdStart.Click
    IcImagingControl1.LiveStart()
    If IcImagingControl1.ExternalTransportAvailable = True Then
        cmdETPlay_Click(sender, e)
    End If
End Sub

[C#]
private void cmdStart_Click(object sender, EventArgs e)
{
    icImagingControl1.LiveStart();
    if (icImagingControl1.ExternalTransportAvailable)
    {
        cmdETPlay_Click(sender, e);
    }
}

[VB.NET]
Private Sub cmdStop_Click(ByVal sender As System.Object, ByVal e As System.EventArgs) Handles cmdStop.Click
    IcImagingControl1.LiveStop()
End Sub

[C#]
private void cmdStop_Click(object sender, EventArgs e)
{
    icImagingControl1.LiveStop();
}

The sub cmdStart_Click contains additional code to advise the DV device to start playing after the Start button has been clicked. If this additional code is missing, you could click the start button, but IC Imaging Control would stay empty, until the external transport mode has been set to "play".

Now, add four new buttons to the form and label them Play, Stop, Rewind and FF. Name the buttons cmdETPlay, cmdETStop, cmdETRewind and cmdETFastForward respectively. These four new buttons are used to set the external transport mode.

Add the click events for the new buttons. Each of the four new buttons sets an external transport mode for IC Imaging Control.

[VB.NET]
Private Sub cmdETPlay_Click(ByVal sender As System.Object, ByVal e As System.EventArgs) Handles cmdETPlay.Click
    IcImagingControl1.ExternalTransportMode = TIS.Imaging.ExternalTransportModes.ET_MODE_PLAY
End Sub

[C#]
private void cmdETPlay_Click(object sender, EventArgs e)
{
    icImagingControl1.ExternalTransportMode = TIS.Imaging.ExternalTransportModes.ET_MODE_PLAY;
}

[VB.NET]
Private Sub cmdETStop_Click(ByVal sender As System.Object, ByVal e As System.EventArgs) Handles cmdETStop.Click
    IcImagingControl1.ExternalTransportMode = TIS.Imaging.ExternalTransportModes.ET_MODE_STOP
End Sub

[C#]
private void cmdETStop_Click(object sender, EventArgs e)
{
    icImagingControl1.ExternalTransportMode = TIS.Imaging.ExternalTransportModes.ET_MODE_STOP;
}

[VB.NET]
Private Sub cmdETRewind_Click(ByVal sender As System.Object, ByVal e As System.EventArgs) Handles cmdETRewind.Click
    IcImagingControl1.ExternalTransportMode = TIS.Imaging.ExternalTransportModes.ET_MODE_REWIND
End Sub

[C#]
private void cmdETRewind_Click(object sender, EventArgs e)
{
    icImagingControl1.ExternalTransportMode = TIS.Imaging.ExternalTransportModes.ET_MODE_REWIND;
}

[VB.NET]
Private Sub cmdETFastForward_Click(ByVal sender As System.Object, ByVal e As System.EventArgs) Handles cmdETFastForward.Click
    IcImagingControl1.ExternalTransportMode = TIS.Imaging.ExternalTransportModes.ET_MODE_FASTFORWARD
End Sub

[C#]
private void cmdETFastForward_Click(object sender, EventArgs e)
{
    icImagingControl1.ExternalTransportMode = TIS.Imaging.ExternalTransportModes.ET_MODE_FASTFORWARD;
}

At least, the Form_Load event should check, whether the current video capture device supports external transport. If the device supports external transport, the four buttons, that are used to set the external transport mode, should be enabled.

[VB.NET]
Private Sub Form1_Load(ByVal sender As System.Object, ByVal e As System.EventArgs) Handles MyBase.Load
    cmdETPlay.Enabled = False
    cmdETStop.Enabled = False
    cmdETFastForward.Enabled = False
    cmdETRewind.Enabled = False
    cmdStart.Enabled = False
    cmdStop.Enabled = False

    If Not IcImagingControl1.DeviceValid Then
        IcImagingControl1.ShowDeviceSettingsDialog()

        If Not IcImagingControl1.DeviceValid Then
            MessageBox.Show("No device was selected.")
            Me.Close()
            Exit Sub
        End If
    End If

    cmdStart.Enabled = True
    cmdStop.Enabled = True

    ' Check whether external transport is available.
    If IcImagingControl1.ExternalTransportAvailable = True Then
        cmdETPlay.Enabled = True
        cmdETStop.Enabled = True
        cmdETFastForward.Enabled = True
        cmdETRewind.Enabled = True
    End If
End Sub

[C#]
private void Form1_Load(object sender, EventArgs e)
{
    cmdETPlay.Enabled = false;
    cmdETStop.Enabled = false;
    cmdETFastForward.Enabled = false;
    cmdETRewind.Enabled = false;
    cmdStart.Enabled = false;
    cmdStop.Enabled = false;

    if (!icImagingControl1.DeviceValid)
    {
        icImagingControl1.ShowDeviceSettingsDialog();

        if (!icImagingControl1.DeviceValid)
        {
            MessageBox.Show("No device was selected.");
            this.Close();
            return;
        }
    }

    cmdStart.Enabled = true;
    cmdStop.Enabled = true;

    // Check whether external transport is available.
    if (icImagingControl1.ExternalTransportAvailable)
    {
        cmdETPlay.Enabled = true;
        cmdETStop.Enabled = true;
        cmdETFastForward.Enabled = true;
        cmdETRewind.Enabled = true;
    }
}

Calling IC Imaging Control's LiveStart method starts the image stream to capture images from the DV device. If the DV device has not got the "Play" command, no images are delivered from the DV device to IC Imaging Control. Thus, in order to get a live image from a DV device, LiveStart has to be called and then the transport mode has to be set to "Play":

[VB.NET]
IcImagingControl1.LiveStart()
IcImagingControl1.ExternalTransportMode = TIS.Imaging.ET_MODE_PLAY

[C#]
icImagingControl1.LiveStart();
icImagingControl1.ExternalTransportMode = TIS.Imaging.ET_MODE_PLAY;

<< Programmer's Guide


Making Device Settings

This chapter shows you how to create a custom device settings dialog. The code is provided in reusable form, thus it can be easily integrated into your own applications.

IC Imaging Control also offers a built-in dialog, which can be used to select and set up a device. If, however, the dialog provided by IC Imaging Control does not fit your needs, this chapter shows you how to create a custom dialog. It will first show you how to integrate the sample code into your own projects and then how to actually build the dialog.

Integrating the sample code into your project

The source code for the VB.NET and C# versions of this sample program can be found in the directories samples\VB *\Making Device Settings and samples\C# *\Making Device Settings in your My Documents/IC Imaging Control 3.2 directory. To integrate the code into your project, you just have to add the file frmDeviceSettings.vb or frmDeviceSettings.cs. Select Project from the menu and then select Add Existing Item.... Now browse to the sample folder and open the file frmDeviceSettings.vb or frmDeviceSettings.cs.

To call the dialog from your application, you will need an instance of the dialog first. After the instance is created, assign the ICImagingControl variable (here: IcImagingControl1, or icImagingControl1 if you are using C#) to the dialog and then show the dialog. After this, Dispose should be called for the dialog:

[VB.NET]
Dim DeviceDialog As New frmDeviceSettings

DeviceDialog.ImagingControl = IcImagingControl1
DeviceDialog.ShowDialog()

DeviceDialog.Dispose()

[C#]
using( frmDeviceSettings DeviceDialog = new frmDeviceSettings() )
{
    DeviceDialog.ImagingControl = icImagingControl1;
    DeviceDialog.ShowDialog();
}

Creating the Dialog

In this chapter, we will focus on the device settings dialog. In addition to the dialog, you will of course need an application that calls it. The sample code of this chapter contains a ready-to-run project with a small application that calls the dialog.

Assuming you have already set up a main project, you now have to add a new form to the project. This form will contain the elements of the custom dialog. To add a new form, select Project from the menu and then choose Add Windows Form. Name it frmDeviceSettings and click the Open button.

Now add 5 combo boxes to the form. Name them cboDevice, cboVideoNorm, cboVideoFormat, cboFrameRate and cboInputChannel. Also add a text box, called txtSerial and two check boxes named chkFlipV and chkFlipH.

In addition to the controls mentioned above, the sample dialog also contains a label named lblErrorMessage. The Visible property of this label is set to false, so that it will not be displayed when the dialog is called. The reason for this is explained when the Form_Load event is discussed.

Adding Functionality to the Dialog

First add some global variables:

[VB.NET]
Public ImagingControl As TIS.Imaging.ICImagingControl
Private DeviceState As String
Const NOT_AVAILABLE = "n/a"

[C#]
public TIS.Imaging.ICImagingControl ImagingControl;
private string DeviceState;
private const string NOT_AVAILABLE = "n\a";

ImagingControl must be public since it is assigned from the main program before the dialog is called.

Now add a Form_Load event and insert the following code:

[VB.NET]
Private Sub frmDeviceSettings_Load(ByVal sender As Object, ByVal e As System.EventArgs) Handles MyBase.Load
    If ImagingControl.DeviceValid Then
        If ImagingControl.LiveVideoRunning Then
            lblErrorMessage.Text = "The device settings dialog is not available while the live video is running.\n\nStop the live video first."
            lblErrorMessage.AutoSize = False
            lblErrorMessage.Padding = New Padding(8)
            lblErrorMessage.SetBounds(0, 0, 100, cmdOK.Top)
            lblErrorMessage.Dock = DockStyle.Top
            lblErrorMessage.Visible = True
            Exit Sub
        Else
            lblErrorMessage.Visible = False
        End If
    End If

    SaveDeviceSettings()

    UpdateDevices()
End Sub

[C#]
private void frmDeviceSettings_Load( object sender, EventArgs e )
{
    if( ImagingControl.DeviceValid )
    {
        if( ImagingControl.LiveVideoRunning )
        {
            lblErrorMessage.Text = "The device settings dialog is not available while the live video is running.\n\nStop the live video first.";
            lblErrorMessage.AutoSize = false;
            lblErrorMessage.Padding = new Padding( 8 );
            lblErrorMessage.SetBounds( 0, 0, 100, cmdOK.Top );
            lblErrorMessage.Dock = DockStyle.Top;
            lblErrorMessage.Visible = true;
            return;
        }
        else
        {
            lblErrorMessage.Visible = false;
        }
    }

    SaveDeviceSettings();

    UpdateDevices();
}

The Form_Load event checks, whether the live video is running. If it is, it reformats the dialog box to display a message to tell you that the dialog will not be displayed, while the live video is running. This behavior was implemented to point out that changing the device will cause side effects. The ring buffer collection ICImagingControl.ImageBuffers is reset when the device is changed. Therefore, image data in the collection is lost.

Now add the click events of the OK and the Cancel button and insert the following code accordingly:

[VB.NET]
Private Sub cmdOK_Click(ByVal sender As Object, ByVal e As System.EventArgs) Handles cmdOK.Click
    Me.Close()
End Sub

[C#]
private void cmdOK_Click( object sender, System.EventArgs e )
{
    this.Close();
}

[VB.NET]
Private Sub cmdCancel_Click(ByVal sender As Object, ByVal e As System.EventArgs) Handles cmdCancel.Click
    RestoreDeviceSettings()

    Me.Close()
End Sub

[C#]
private void cmdCancel_Click( object sender, System.EventArgs e )
{
    RestoreDeviceSettings();

    this.Close();
}

As can be seen above, the Form_Load event calls a procedure SaveDeviceSettings and the CancelButton_Click event calls RestoreDeviceSettings.

The UpdateDevices procedure that is called on the Form_Load event updates the controls of the dialog, but this will be discussed later.

Now add the SelectedIndexChanged events for all 5 combo boxes and the click event for the 2 check boxes. On the SelectedIndexChanged event of the device combo box, the currently selected device must be changed and all other combo boxes, the check boxes and the output of the serial number text field must be updated. This is done with the following code:

[VB.NET]
Private Sub cboDevice_SelectedIndexChanged(ByVal sender As Object, ByVal e As System.EventArgs) Handles cboDevice.SelectedIndexChanged
    Dim Serial As String = ""

    Try
        'Open the device
        If cboDevice.Enabled Then

            Dim Item As Object
            Dim index As Integer
            index = 0

            ImagingControl.Device = cboDevice.Text
            txtSerial.Text = NOT_AVAILABLE

            For Each Item In ImagingControl.Devices
                If Item.Name = cboDevice.Text Then
                    If ImagingControl.Devices(index).GetSerialNumber(Serial) Then
                        txtSerial.Text = Serial
                        Exit For
                    End If
                End If
                index = index + 1
            Next

            ' Get supported video norms, formats and inputs
            UpdateVideoNorms()
            UpdateInputChannels()
            UpdateFlip()
        End If

    Catch ex As System.Exception
        MessageBox.Show(ex.Message)
    End Try
End Sub

[C#]
private void cboDevice_SelectedIndexChanged( object sender, System.EventArgs e )
{
    string Serial = "";

    try
    {
        // Open the device
        if( cboDevice.Enabled )
        {
            int index = 0;
            ImagingControl.Device = cboDevice.Text;

            txtSerial.Text = NOT_AVAILABLE;

            foreach( object Item in ImagingControl.Devices )
            {
                if( Item.ToString() == cboDevice.Text )
                {
                    if( ImagingControl.Devices[index].GetSerialNumber( out Serial ) )
                    {
                        txtSerial.Text = Serial;
                        break;
                    }
                }
                index++;
            }
        }
        // Get supported video norms, formats and inputs
        UpdateVideoNorms();
        UpdateInputChannels();
        UpdateFlip();
    }
    catch( Exception ex )
    {
        MessageBox.Show( ex.Message );
    }
}

After the new device is selected, its serial number is retrieved. If a serial number is not available, n/a is displayed. The procedures UpdateVideoNorms, UpdateInputChannels and UpdateFlip update the controls. They will be discussed later. Please note that the video format and the frame rate are updated implicitly by UpdateVideoNorms and UpdateVideoFormat.

The SelectedIndexChanged events for the other combo boxes are quite similar. The SelectedIndexChanged event for the cboVideoNorm combo box includes a procedure UpdateVideoFormats, which is used to update the video format combo box according to the selected video norm. The SelectedIndexChanged event for the cboVideoFormat combo box includes a procedure UpdateFrameRates that updates the frame rate combo box after the video format has changed. The other combo boxes just set the currently selected value. Here is the code for the video norm combo box:

[VB.NET]
Private Sub cboVideoNorm_SelectedIndexChanged(ByVal sender As Object, ByVal e As System.EventArgs) Handles cboVideoNorm.SelectedIndexChanged
    Try
        If cboVideoNorm.Enabled Then
            ImagingControl.VideoNorm = cboVideoNorm.Text
        End If

        UpdateVideoFormats()

    Catch ex As System.Exception
        MessageBox.Show(ex.Message)
    End Try
End Sub

[C#]
private void cboVideoNorm_SelectedIndexChanged( object sender, System.EventArgs e )
{
    try
    {
        if( cboVideoNorm.Enabled )
        {
            ImagingControl.VideoNorm = cboVideoNorm.Text;
        }

        UpdateVideoFormats();
    }
    catch( Exception ex )
    {
        MessageBox.Show( ex.Message );
    }
}

The SelectedIndexChanged events for the other combo boxes are implemented accordingly, except a minor detail regarding the frame rate combo box. If you assign the new value for the frame rate, make sure you do a typecast, since cboFrameRate.Text returns a string, but ICImagingControl.DeviceFrameRate needs a floating point value.

Finally, add click events for the check boxes. They just toggle the horizontal and vertical flip:

[VB.NET]
Private Sub chkFlipV_Click(ByVal sender As Object, ByVal e As System.EventArgs) Handles chkFlipV.Click
    If ImagingControl.DeviceFlipVerticalAvailable Then
        ImagingControl.DeviceFlipVertical = (chkFlipV.Checked = True)
    End If
End Sub

[C#]
private void chkFlipV_CheckedChanged( object sender, System.EventArgs e )
{
    if( ImagingControl.DeviceFlipVerticalAvailable )
    {
        ImagingControl.DeviceFlipVertical = ( chkFlipV.Checked == true );
    }
}

The event for chkFlipH is implemented the same way.

The Update Procedures

As mentioned before, there is an Update procedure for every combo box and one for the two check boxes. The Update procedures for the combo boxes just fill the appropriate combo box with currently valid values. If the value that was selected before the update is still contained in the combo box, it is selected automatically. The code for the UpdateDevice procedure looks as follows:

[VB.NET]
Private Sub UpdateDevices()
    cboDevice.Items.Clear()
    If ImagingControl.Devices.Length > 0 Then
        Dim Item As Object

        For Each Item In ImagingControl.Devices
            cboDevice.Items.Add(Item.ToString())
        Next

        If ImagingControl.DeviceValid Then
            cboDevice.SelectedItem = ImagingControl.Device
        Else
            cboDevice.SelectedIndex = 0
        End If
        cboDevice.Enabled = True
    Else
        cboDevice.Items.Add(NOT_AVAILABLE)
        cboDevice.Enabled = False
        cboDevice.SelectedIndex = 0
    End If
End Sub

[C#]
private void UpdateDevices()
{
    cboDevice.Items.Clear();
    if( ImagingControl.Devices.Length > 0 )
    {
        foreach( object Item in ImagingControl.Devices )
        {
            cboDevice.Items.Add( Item.ToString() );
        }

        if( ImagingControl.DeviceValid )
        {
            cboDevice.SelectedItem = ImagingControl.Device;
        }
        else
        {
            cboDevice.SelectedIndex = 0;
        }
        cboDevice.Enabled = true;
    }
    else
    {
        cboDevice.Items.Add( NOT_AVAILABLE );
        cboDevice.Enabled = false;
        cboDevice.SelectedIndex = 0;
    }
}

The Update procedures for the other combo boxes are implemented accordingly, but note that ImagingControl.DeviceFrameRates returns a collection that contains floating point values. Therefore, in the UpdateFrameRates procedure, you must typecast them into a string before you can add them to the combo box.

The UpdateFlip procedure checks whether there is a vertical or horizontal flip available with the current device and sets their current state if possible:

[VB.NET]
Private Sub UpdateFlip()
    If ImagingControl.DeviceFlipHorizontalAvailable Then
        chkFlipH.Enabled = True
        If ImagingControl.DeviceFlipHorizontal Then
            chkFlipH.Checked = True
        Else
            chkFlipH.Checked = False
        End If
    Else
        chkFlipH.Enabled = False
        chkFlipH.Checked = False
    End If

    If ImagingControl.DeviceFlipVerticalAvailable Then
        chkFlipV.Enabled = True
        If ImagingControl.DeviceFlipVertical Then
            chkFlipV.Checked = True
        Else
            chkFlipV.Checked = False
        End If
    Else
        chkFlipV.Enabled = False
        chkFlipV.Checked = False
    End If
End Sub

[C#]
private void UpdateFlip()
{
    if( ImagingControl.DeviceFlipHorizontalAvailable )
    {
        chkFlipH.Enabled = true;
        if( ImagingControl.DeviceFlipHorizontal )
        {
            chkFlipH.Checked = true;
        }
        else
        {
            chkFlipH.Checked = false;
        }
    }
    else
    {
        chkFlipH.Enabled = false;
        chkFlipH.Checked = false;
    }

    if( ImagingControl.DeviceFlipVerticalAvailable )
    {
        chkFlipV.Enabled = true;
        if( ImagingControl.DeviceFlipVertical )
        {
            chkFlipV.Checked = true;
        }
        else
        {
            chkFlipV.Checked = false;
        }
    }
    else
    {
        chkFlipV.Enabled = false;
        chkFlipV.Checked = false;
    }
}
//>

// ------------------------------------------------------------------------------
// UI events
// ------------------------------------------------------------------------------

//
// cboDevice_SelectedIndexChanged
//
// Get available inputs and video formats for the selected
// device and enter the information in the respective combo
// boxes.
//
//<<cboDevice
private void cboDevice_SelectedIndexChanged( object sender, System.EventArgs e )
{
    string Serial = "";

    try
    {
        // Open the device
        if( cboDevice.Enabled )
        {
            int index = 0;
            ImagingControl.Device = cboDevice.Text;

            txtSerial.Text = NOT_AVAILABLE;

            foreach( object Item in ImagingControl.Devices )
            {
                if( Item.ToString() == cboDevice.Text )
                {
                    if( ImagingControl.Devices[index].GetSerialNumber( out Serial ) )
                    {
                        txtSerial.Text = Serial;
                        break;
                    }
                }
                index++;
            }
        }
        // Get supported video norms, formats and inputs
        UpdateVideoNorms();
        UpdateInputChannels();
        UpdateFlip();
    }
    catch( Exception ex )
    {
        MessageBox.Show( ex.Message );
    }
}

<< Programmer's Guide


Building an Application

This sample program shows you how to use all the building blocks from the previous chapters to create a real program.

In addition to the code already presented, it contains a tool bar, error handling and uses the built-in dialogs to select and set up a device.

First Application

The source code for the VB.NET and C# versions of this sample program can be found in the directories samples\VB *\DemoApp and samples\C# *\DemoApp in your My Documents/IC Imaging Control 3.2 directory.

<< Programmer's Guide


Performing Image Processing

This chapter shows you how to create your own image processing functions.

The source code for the VB.NET and C# versions of this sample program can be found in the directories samples\VB *\Image Processing and samples\C# *\Image Processing in your My Documents/IC Imaging Control 3.2 directory.

Setting up the Project

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 2003 - 2008 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.

Add 3 buttons to the form and label them Start Live, Stop Live and Process. Name them cmdStartLive, cmdStopLive and cmdProcess respectively. Now add the following code to the Click events of the buttons:

[VB.NET]
Private Sub cmdStartLive_Click(ByVal sender As System.Object, ByVal e As System.EventArgs) Handles cmdStartLive.Click
    IcImagingControl1.LiveStart()

    ' Store in VideoHasStarted whether a video stream
    ' has been started once. If VideoHasStarted is True,
    ' you can be sure that there is an image that can be processed.
    VideoHasStarted = True

    ' VideoHasStopped is set to False, because the live
    ' video has just been started.
    VideoHasStopped = False
End Sub

[C#]
private void cmdStartLive_Click_1(object sender, EventArgs e)
{
    icImagingControl1.LiveStart();

    // Store in VideoHasStarted whether a video stream
    // has been started once. If VideoHasStarted is True,
    // you can be sure that there is an image that can be processed.
    VideoHasStarted = true;

    // VideoHasStopped is set to False, because the live
    // video has just been started.
    VideoHasStopped = false;
}

[VB.NET]
Private Sub cmdStopLive_Click(ByVal sender As System.Object, ByVal e As System.EventArgs) Handles cmdStopLive.Click
    IcImagingControl1.LiveStop()

    If VideoHasStarted = True Then
        VideoHasStopped = True
    End If
End Sub

[C#]
private void cmdStopLive_Click(object sender, EventArgs e)
{
    icImagingControl1.LiveStop();

    if (VideoHasStarted == true)
    {
        VideoHasStopped = true;
    }
}

[VB.NET]
Private Sub cmdProcess_Click(ByVal sender As System.Object, ByVal e As System.EventArgs) Handles cmdProcess.Click
    Dim ImgBuffer As TIS.Imaging.ImageBuffer
    Dim x As Integer, y As Integer
    Dim BytesPerLine As Integer
    Cursor = Cursors.WaitCursor
    Try
        ' Check whether the video stream has been started once.
        ' If it has been started once, there are two possible situations:
        ' 1) The live video is running. In this case we stop the live video
        '       in order to get the last frame and display the processed image.
        ' 2) The live video has been stopped. In this case the last frame of the
        '       live video was grabbed automatically and can be processed and
        '       displayed.

        If VideoHasStarted Then
            If VideoHasStopped = False Then
                IcImagingControl1.LiveStop()
            End If

            ImgBuffer = IcImagingControl1.ImageActiveBuffer
            ' Calculate the count of bytes ber line using the color format and the
            ' pixels per line of the image buffer.
            BytesPerLine = ImgBuffer.BitsPerPixel / 8 * ImgBuffer.PixelPerLine - 1
            For y = 0 To ImgBuffer.Lines - 1
                For x = 0 To BytesPerLine
                    ImgBuffer(x, y) = 255 - ImgBuffer(x, y)
                Next x
            Next y

            IcImagingControl1.Display()
        Else
            MessageBox.Show("Please click the Start Live button first!", _
                            "Image Processing", _
                            MessageBoxButtons.OK, _
                            MessageBoxIcon.None)
        End If

    Catch ex As System.Exception
        MessageBox.Show(ex.Message)
    End Try
    Cursor = Cursors.Default
End Sub

[C#]
private void cmdProcess_Click(object sender, EventArgs e)
{
    TIS.Imaging.ImageBuffer ImgBuffer;
    int x, y;
    int BytesPerLine;

    Cursor = Cursors.WaitCursor;
    try
    {
        // Check whether the video stream has been started once.
        // If it has been started once, there are two possible situations:
        // 1) The live video is running. In this case we stop the live video
        //       in order to get the last frame and display the processed image.
        // 2) The live video has been stopped. In this case the last frame of the
        //       live video was grabbed automatically and can be processed and
        //       displayed.
        if (VideoHasStarted)
        {
            if (VideoHasStopped == false)
            {
                icImagingControl1.LiveStop();
            }

            ImgBuffer = icImagingControl1.ImageActiveBuffer;
            // Calculate the count of bytes per line.
            BytesPerLine = ImgBuffer.BitsPerPixel / 8 * ImgBuffer.PixelPerLine;
            unsafe
            {
                byte* pDatabyte = ImgBuffer.GetImageData();
                for (y = 0; y < ImgBuffer.Lines; y++)
                {
                    for (x = 0; x < BytesPerLine; x++)
                    {
                        *pDatabyte = (byte)(255 - *pDatabyte);
                        pDatabyte++;
                    }
                }
            }

            icImagingControl1.DisplayImageBuffer(ImgBuffer);
        }
        else
        {
            MessageBox.Show("Please click the Start Live button first!",
                "Image Processing",
                MessageBoxButtons.OK,
                MessageBoxIcon.None);
        }
    }
    catch (Exception ex)
    {
        MessageBox.Show(ex.Message);
    }
    Cursor = Cursors.Default;
}

First, an image is captured automatically when the LiveStop method is called. This can either be done directly by clicking the Stop Live button, or implicitly by clicking the Process button. The variable VideoHasStarted is used to determine whether live video has been started at least once, in which case image processing can be performed.

Then the active buffer is retrieved. This is the buffer that contains the data of the previously snapped image. The image data can be accessed with the Item property. The two nested for..next loops are typical for image processing algorithms, in that they access individual pixels of the image by specifying their coordinates. The algorithm shown here simply inverts the image.

The sample code above requires 8-bit or 24-bit image data, so we need to select an appropriate value for the MemoryCurrentGrabberColorformat Property:

Using Color Formats

If a video format is selected, which has more than 8 bits per pixel, it must be considered that the image buffer still contains the same number of pixel per line, but that each pixel contains more than 1 byte now, meaning the size of the buffer has increased. For instance, if the video format is RGB24(640x480), 640 by 480 pixels with 3 bytes per pixel, then the image buffer will be 1920 by 480 bytes in size.

For RGB24, the pixel data has to be interpreted as follows: The first byte of a row is the blue value of the first pixel, the second byte is the green value of the first pixel and the third byte is the red value of the first pixel. The fourth byte is the blue value of pixel 2, and so on.

And this is what the result will look like:

While possible and required in some cases, you should avoid using different formats for VideoFormat and MemoryCurrentGrabberColorformat, because the image data then needs to be converted, resulting in poor performance.

<< Programmer's Guide


Using Multiple Buffers

In the previous chapters, IC Imaging Control appeared to work with only one image buffer. In fact, IC Imaging Control uses multiple buffers to store image data. This chapter describes how multiple buffers are organized inside IC Imaging Control and in which way a program can access these buffers. Internally, IC Imaging Control uses a ring buffer to store image data. The next section will describe the idea behind the ring buffer concept.

What is a Ring Buffer

A ring buffer is an array of image buffers, which are accessed in the following way: IC Imaging Control writes the first frame, coming from a video capture device, to the first element of the ring buffer. The second frame is written to the second buffer and so on. As soon as a frame has been written to the last element of the ring buffer, IC Imaging Control writes the next frame to the first buffer, overwriting the image data of the first frame.

This concept has the following benefits:

  • The image from one image buffer can be processed, while incoming image data is being written to another buffer simultaneously.
  • Previously acquired images can be accessed without copying the image data. This is particularly useful, if an image processing function detects an event (e.g. motion detection) in the current image. It is possible to go back the number of frames the image buffer is large, minus 1 frame. In other words, you can look into the past.

How to Access Image Buffers

Index-based access to an image buffer is provided by the ImageBuffers collection. If, for example, you want to access the first buffer, you should use the following code:

[VB.NET]
Dim FirstBuffer As TIS.Imaging.ImageBuffer

FirstBuffer = IcImagingControl1.ImageBuffers(0)

[C#]
TIS.Imaging.ImageBuffer FirstBuffer;

FirstBuffer = icImagingControl1.ImageBuffers[0];

Locking Buffers

If you want to prevent IC Imaging Control from copying data to a buffer, you have to lock this buffer with a call to ImageBuffer.Lock. You may want to do so, if time intensive image processing is carried out on the buffer. If you do not lock the buffer, IC Imaging Control may overwrite the data in the buffer while you are processing its data.

You have to call ImageBuffer.Unlock to allow IC Imaging Control to copy data to the buffer again.

<< Programmer's Guide


Displaying Buffers on the ImageAvailable Event

This chapter shows how to control the display of image buffers using the ImageAvailable event.

Normally, IC Imaging Control shows the live display automatically in its control window. However, using the ImageAvailable event, this behavior can be changed, thus enabling an application to modify the image data in the buffer (image processing), before it is displayed.

The source code for the VB.NET and C# versions of this sample program can be found in the directories samples\VB *\Display Buffer and samples\C# *\Display Buffer in your My Documents/IC Imaging Control 3.2 directory.

Setting up the Project

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 2003 - 2008 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 making a selection, the program displays an error message and terminates.

Specifying the Size of the Ring Buffer

As described in the chapter Using Multiple Buffers, IC Imaging Control uses a ring buffer to manage multiple buffers. The number of buffers contained in the ring buffer may be specified in the property browser by clicking on the property ImageRingBufferSize. On the one hand, a large size reduces the probability that IC Imaging Control attempts to overwrite the buffer. However, on the other hand, a large ring buffer size uses a large amount of memory. Choosing a suitable ring buffer size should be based on balancing these two contrary aspects. For our application, a ring buffer size of 5 is suitable because no processing is carried out on the buffers.

Disabling the Automatic Live Display

Set LiveDisplay in the property browser to False. This prevents IC Imaging Control from displaying the live stream automatically.

Enabling Continuous Capture Mode

Set LiveCaptureContinuous in the property browser to True, in order to enable the continuous capture mode. In this mode, IC Imaging Control copies every frame automatically to the ring buffer. In addition, an ImageAvailable event is sent every time a frame has been copied completely to the ring buffer.

Adding Initialization Code

Create a Form_Load event procedure and add the following code:

[VB.NET]
Private Sub Form1_Load(ByVal sender As System.Object, ByVal e As System.EventArgs) Handles MyBase.Load
    ' Check if a valid video capture device has been selected, otherwise
    ' show the device selection dialog of Imaging Control.
    If Not IcImagingControl1.DeviceValid Then
        IcImagingControl1.ShowDeviceSettingsDialog()

        If Not IcImagingControl1.DeviceValid Then
            MessageBox.Show("No device was selected.", "Display Buffer Sample")
            Me.Close()
            Exit Sub
        End If
    End If

    cmdStop.Enabled = False
    IcImagingControl1.Width = IcImagingControl1.ImageWidth
    IcImagingControl1.Height = IcImagingControl1.ImageHeight
End Sub

[C#]
private void Form1_Load(object sender, EventArgs e)
{
    // Check if a valid video capture device has been selected, otherwise
    // show the device selection dialog of Imaging Control.
    if (!icImagingControl1.DeviceValid)
    {
        icImagingControl1.ShowDeviceSettingsDialog();

        if (!icImagingControl1.DeviceValid)
        {
            MessageBox.Show("No device was selected.", "Display Buffer",
                            MessageBoxButtons.OK, MessageBoxIcon.Information);
            this.Close();
            return;
        }
    }

    cmdStop.Enabled = false;
    icImagingControl1.LiveDisplayDefault = false;
    icImagingControl1.LiveDisplayHeight = icImagingControl1.Height;
    icImagingControl1.LiveDisplayWidth = icImagingControl1.Width;

    icImagingControl1.LiveCaptureContinuous = true;
    icImagingControl1.LiveDisplay = false;
}

This enables the "Start" button only, if the currently selected video capture device is valid. The following lines with ControlName.Width = ControlName.ImageWidth set the size of the control as specified by the currently selected video format.

Implementing Start/Stop Commands

Add a button to the form, set its Caption to "Start" and its Name to "cmdStart". Add the following code to its click event procedure:

[VB.NET]
Private Sub cmdStart_Click(ByVal sender As System.Object, ByVal e As System.EventArgs) Handles cmdStart.Click
    IcImagingControl1.LiveStart()
    cmdStart.Enabled = False
    cmdStop.Enabled = True
End Sub

[C#]
private void cmdStart_Click(object sender, EventArgs e)
{
    icImagingControl1.LiveStart();
    cmdStart.Enabled = false;
    cmdStop.Enabled = true;
}

Add a second button to the form, set its Caption to "Stop" and its Name to "cmdStop". Add the following code to its click event procedure:

[VB.NET]
Private Sub cmdStop_Click(ByVal sender As System.Object, ByVal e As System.EventArgs) Handles cmdStop.Click
    cmdStart.Enabled = True
    cmdStop.Enabled = False
    IcImagingControl1.LiveStop()
End Sub

[C#]
private void cmdStop_Click(object sender, EventArgs e)
{
    cmdStart.Enabled = true;
    cmdStop.Enabled = false;
    icImagingControl1.LiveStop();
}

The ImageAvailable Event Procedure

Now, add an ImageAvailable event procedure to your code.

Insert the following lines of code to the event procedure:

[VB.NET]
Private Sub IcImagingControl1_ImageAvailable(ByVal sender As System.Object, ByVal e As TIS.Imaging.ICImagingControl.ImageAvailableEventArgs) Handles IcImagingControl1.ImageAvailable
    Try
        Dim CurrentBuffer As TIS.Imaging.ImageBuffer

        CurrentBuffer = IcImagingControl1.ImageBuffers(e.bufferIndex)
        IcImagingControl1.DisplayImageBuffer(CurrentBuffer)

    Catch ex As System.Exception
        System.Diagnostics.Trace.WriteLine(ex.Message)
    End Try
End Sub

[C#]
private void icImagingControl1_ImageAvailable(object sender, TIS.Imaging.ICImagingControl.ImageAvailableEventArgs e)
{
    try
    {
        TIS.Imaging.ImageBuffer CurrentBuffer = null;

        CurrentBuffer = icImagingControl1.ImageBuffers[e.bufferIndex];
        icImagingControl1.DisplayImageBuffer(CurrentBuffer);
    }
    catch (Exception ex)
    {
        System.Diagnostics.Trace.WriteLine(ex.Message);
    }
}

The ImageAvailable event handler receives ImageAvailableEventArgs event arguments in the parameter e. ImageAvailableEventArgs.bufferIndex specifies the buffer that contains the last copied image. This image buffer is assigned to the local variable CurrentBuffer. The buffer is actually displayed by calling ICImagingControl.DisplayImageBuffer. The image buffer may be manipulated before the it is displayed.

<< Programmer's Guide


Accessing an Image Buffer

This example shows the how to handle image buffers.

The source code for the VB.NET and C# versions of this sample program can be found in the directories samples\VB *\PixelFormat and samples\C# *\PixelFormat in your My Documents/IC Imaging Control 3.2 directory.

Available Data Formats

Y800

The Y800 color format is an 8 bit monochrome format. Every pixel is represented by one byte. The organization of the pixels in the image buffer is from left to right and top down. In other words: The first byte of the image buffer corresponds to the first pixel of the first line of the image.

RGB8

The RGB8 color format is an 8 bit monochrome format. Every pixel is represented by one byte. The organization of the pixels in the image buffer is from left to right and bottom up. In other words: The first byte of the image buffer corresponds to the first pixel of the last line of the image.

RGB24

RGB24 is a 24 bit color format. Every pixel is represented by 3 bytes, while every byte of this triple corresponds to one color value. The letters 'RGB' mean Red, Green and Blue, so one byte represents the red value, one byte represents the green value and the last byte represents the blue value.

RGB32

RGB32 is a 32 bit color format. It is like RGB24, except that every pixel has an additional byte to store an alpha value. An alpha value describes the transparency of the pixel. Therefore, every pixel consists of 4 bytes. RGB32 is also referred to as RGBA, where the A stands for Alpha. The A value is not used in IC Imaging Control and is therefore always 0. As for the RGB24 pixel format, IC Imaging Control uses the BGRA byte order for the RGB32 pixel format. The organization of the pixels in the image buffer is from left to right and bottom up.

YGB0

YGB0 is a 10 bit grayscale format. Every pixel is stored in two bytes. Only 10 of the 16 bits of these two bytes contain relevant image data, the other bits are unused. The organization of the pixels in the image buffer is from left to right and top down.

YGB1

YGB1 is a 10 bit grayscale format. Every pixel is stored in two bytes. Only 10 of the 16 bits of these two bytes contain relevant image data, the other bits are unused. The organization of the pixels in the image buffer is from left to right and top down.

<< Programmer's Guide


Y800

The Y800 color format is an 8 bit monochrome format. Every pixel is represented by one byte. The organization of the pixels in the image buffer is from left to right and top down. In other words: The first byte of the image buffer corresponds to the first pixel of the first line of the image.

How to read and write pixel data

A video capture device, video format, FrameHandlerSink with a ImageBuffers collections, which defines the image data color format must have been setup. The following code fragments show step-by-step how to access and manipulate the pixel data of Y800.

First of all, we have to capture an image. Otherwise, the image buffer would be empty. To do so, live mode is started and FrameHandlerSink.SnapImage is called.

Accessing the buffer

To access the bytes of the image buffer, you can write buf[column,line] in C# and buf(column,line) in VB.NET.

In this example, we want to read out the first (upper left hand) two pixels of the image. In a second step we manipulate the first 3 pixels. Because Y800 images are stored top-down, the index of the first line is 0.

[C#]
// Y800 is top-down, the first line has index 0
int y = 0;

txtOutput.Text = "Image buffer pixel format is Y800\r\n";
txtOutput.Text += "Pixel 1: " + buf[0, y] + "\r\n";
txtOutput.Text += "Pixel 2: " + buf[1, y];

[VB.NET]
' Y800 is top-down, the first line has index 0
Dim y As Integer = 0

txtOutput.Text = "Image buffer pixel format is Y800" & vbCrLf
txtOutput.Text &= "Pixel 1: " & buf(0, y) & vbCrLf
txtOutput.Text &= "Pixel 2: " & buf(1, y)

Manipulating Image Data

Instead of only reading pixel data, it is, of course, possible to manipulate the data as well. The following code sets the upper left hand pixel to black and the next 2 pixels to gray and white. After this manipulation, the image is saved to a BMP file.

[C#]
// Set the first pixel to 0 (black)
buf[0, y] = 0;
// Set the second pixel to 128 (gray)
buf[1, y] = 128;
// Set the third pixel to 255 (white)
buf[2, y] = 255;

buf.SaveAsBitmap("Y800.bmp");

[VB.NET]
' Set the first pixel to 0 (black)
buf(0, y) = 0
' Set the second pixel to 128 (gray)
buf(1, y) = 128
' Set the third pixel to 255 (white)
buf(2, y) = 255

buf.SaveAsBitmap("Y800.bmp")

To check the result, open the saved image and take a look at the upper left hand pixels. They should look as follows:

<< Accessing an Image Buffer


RGB8

The RGB8 color format is an 8 bit monochrome format. Every pixel is represented by one byte. The organization of the pixels in the image buffer is from left to right and bottom up. In other words: The first byte of the image buffer corresponds to the first pixel of the last line of the image.

How to read and write pixel data

A video capture device, video format, FrameHandlerSink with a ImageBuffers collections, which defines the image data color format must have been setup. The following code fragments show step-by-step how to access and manipulate the pixel data of RGB8.

First of all, we have to capture an image. Otherwise, the image buffer would be empty. To do so, live mode is started and FrameHandlerSink.SnapImage is called.

Accessing the buffer

To access the bytes of the image buffer, you can write buf[column,line] in C# and buf(column,line) in VB.NET.

In this example, we want to read out the first (upper left) two pixels of the image. In a second step we manipulate the first 3 pixels. Because RGB images are stored bottom-up, the index of the first line is lines-1.

[C#]
// RGB8 is bottom-up, the first line has index lines-1
int y = buf.Lines - 1;

txtOutput.Text = "Image buffer pixel format is RGB8\r\n";
txtOutput.Text += "Pixel 1: " + buf[0, y] + "\r\n";
txtOutput.Text += "Pixel 2: " + buf[1, y];

[VB.NET]
' RGB8 is top-down, the first line has index lines-1
Dim y As Integer = buf.Lines - 1

txtOutput.Text = "Image buffer pixel format is RGB8" & vbCrLf
txtOutput.Text &= "Pixel 1: " & buf(0, y) & vbCrLf
txtOutput.Text &= "Pixel 2: " & buf(1, y)

Manipulating Image Data

Instead of only reading pixel data, it is, of course, possible to manipulate the data as well. The following code sets the upper left hand pixel to black and the next 2 pixels to gray and white. After this manipulation, the image is saved to a BMP file.

[C#]
// Set the first pixel to 0 (black)
buf[0, y] = 0;
// Set the second pixel to 128 (gray)
buf[1, y] = 128;
// Set the third pixel to 255 (white)
buf[2, y] = 255;

buf.SaveAsBitmap("RGB8.bmp");

[VB.NET]
' Set the first pixel to 0 (black)
buf(0, y) = 0
' Set the second pixel to 128 (gray)
buf(1, y) = 128
' Set the third pixel to 255 (white)
buf(2, y) = 255

buf.SaveAsBitmap("RGB8.bmp")

To check the result, open the saved image and take a look at the upper left hand pixels. They should look as follows:

<< Accessing an Image Buffer


RGB24

RGB24 is a 24 bit color format. Every pixel is represented by 3 bytes, while every byte of this triple corresponds to one color value. The letters 'RGB' mean Red, Green and Blue, so one byte represents the red value, one byte represents the green value and the last byte represents the blue value.

Please note that the name RGB can be misleading, since the first byte of a pixel does not necessarily have to represent the red value. In the Windows© environment, RGB data is typically organized in the order BGR. This means that the first byte represents the blue value, the second byte represents the green value and the third byte represents the red value of a RGB24 pixel. IC Imaging Control uses BGR order for the RGB24 pixel format. The organization of the pixels in the image buffer is from left to right and bottom up.

How to read and write pixel data

A video capture device, video format, FrameHandlerSink with a ImageBuffers collections, which defines the image data color format must have been setup. The following code fragments show step-by-step how to access and manipulate the pixel data of RGB24.

First of all, we have to capture an image. Otherwise, the image buffer would be empty. To do so, live mode is started and FrameHandlerSink.SnapImage is called.

Accessing the buffer

To access the bytes of the image buffer, you can write buf[column,line] in C# and buf(column,line) in VB.NET.

In this example, we want to read out the first (upper left hand) two pixels of the image. In a second step, we manipulate the first 3 pixels. Because RGB images are stored bottom-up, the index of the first line is lines-1.

To calculate the x-coordinate of the pixel data, the number of bytes required for one pixel (3) is multiplied with the column of the pixel to be retrieved. After that, an offset is added to access the red, blue or green component of the pixel.

[C#]
// RGB24 is bottom-up, the first line has index lines-1
int y = buf.Lines - 1;

txtOutput.Text = "Image buffer pixel format is RGB24\r\n";
txtOutput.Text += "Pixel 1: ";
txtOutput.Text += "R=" + buf[0 * 3 + 2, y] + ", ";
txtOutput.Text += "G=" + buf[0 * 3 + 1, y] + ", ";
txtOutput.Text += "B=" + buf[0 * 3 + 0, y] + "\r\n";
txtOutput.Text += "Pixel 2: ";
txtOutput.Text += "R=" + buf[1 * 3 + 2, y] + ", ";
txtOutput.Text += "G=" + buf[1 * 3 + 1, y] + ", ";
txtOutput.Text += "B=" + buf[1 * 3 + 0, y];

[VB.NET]
' RGB24 is bottom-up, the first line has index lines-1
Dim y As Integer = buf.Lines - 1

txtOutput.Text = "Image buffer pixel format is RGB24" & vbCrLf
txtOutput.Text &= "Pixel 1: "
txtOutput.Text &= "R=" & buf(0 * 3 + 2, y) & ", "
txtOutput.Text &= "G=" & buf(0 * 3 + 1, y) & ", "
txtOutput.Text &= "B=" & buf(0 * 3 + 0, y) & vbCrLf
txtOutput.Text &= "Pixel 2: "
txtOutput.Text &= "R=" & buf(1 * 3 + 2, y) & ", "
txtOutput.Text &= "G=" & buf(1 * 3 + 1, y) & ", "
txtOutput.Text &= "B=" & buf(1 * 3 + 0, y)

Manipulating Image Data

Instead of only reading pixel data, it is, of course, possible to manipulate the data as well. The following code sets the upper left pixel to red and the next 2 pixels to green and blue. After this manipulation, the image is saved to a .bmp file.

[C#]
// Set the first pixel to red (255 0 0)
buf[0 * 3 + 2, y] = 255;
buf[0 * 3 + 1, y] = 0;
buf[0 * 3 + 0, y] = 0;
// Set the second pixel to 128 (gray)
buf[1 * 3 + 2, y] = 0;
buf[1 * 3 + 1, y] = 255;
buf[1 * 3 + 0, y] = 0;
// Set the third pixel to 255 (white)
buf[2 * 3 + 2, y] = 0;
buf[2 * 3 + 1, y] = 0;
buf[2 * 3 + 0, y] = 255;

buf.SaveAsBitmap("RGB24.bmp");

[VB.NET]
' Set the first pixel to red (255 0 0)
buf(0 * 3 + 2, y) = 255
buf(0 * 3 + 1, y) = 0
buf(0 * 3 + 0, y) = 0
' Set the second pixel to 128 (gray)
buf(1 * 3 + 2, y) = 0
buf(1 * 3 + 1, y) = 255
buf(1 * 3 + 0, y) = 0
' Set the third pixel to 255 (white)
buf(2 * 3 + 2, y) = 0
buf(2 * 3 + 1, y) = 0
buf(2 * 3 + 0, y) = 255

buf.SaveAsBitmap("RGB24.bmp")

To check the result, open the saved image and take a look at the upper left hand pixels. They should look as follows:

<< Accessing an Image Buffer


RGB32

RGB32 is a 32 bit color format. It is like RGB24, except that every pixel has an additional byte to store an alpha value. An alpha value describes the transparency of the pixel. Therefore, every pixel consists of 4 bytes. RGB32 is also referred to as RGBA, where the A stands for Alpha. The A value is not used in IC Imaging Control and is therefore always 0. As for the RGB24 pixel format, IC Imaging Control uses the BGRA byte order for the RGB32 pixel format. The organization of the pixels in the image buffer is from left to right and bottom up.

How to read and write pixel data

A video capture device, video format, FrameHandlerSink with a ImageBuffers collections, which defines the image data color format must have been setup. The following code fragments show step-by-step how to access and manipulate the pixel data of RGB32.

First of all, we have to capture an image. Otherwise, the image buffer would be empty. To do so, live mode is started and FrameHandlerSink.SnapImage is called.

Accessing the buffer

To access the bytes of the image buffer, you can write buf[column,line] in C# and buf(column,line) in VB.NET.

In this example, we want to read out the first (upper left) two pixels of the image. In a second step we manipulate the first 3 pixels. Because RGB images are stored bottom-up, the index of the first line is lines-1.

To calculate the x-coordinate of the pixel data, the number of bytes required for one pixel (4) is multiplied with the column of the pixel to be retrieved. After that, an offset is added to access the red, blue or green component of the pixel.

[C#]
// RGB32is bottom-up, the first line has index lines-1
int y = buf.Lines - 1;

txtOutput.Text = "Image buffer pixel format is RGB32\r\n";
txtOutput.Text += "Pixel 1: ";
txtOutput.Text += "R=" + buf[0 * 4 + 2, y] + ", ";
txtOutput.Text += "G=" + buf[0 * 4 + 1, y] + ", ";
txtOutput.Text += "B=" + buf[0 * 4 + 0, y] + "\r\n";
txtOutput.Text += "Pixel 2: ";
txtOutput.Text += "R=" + buf[1 * 4 + 2, y] + ", ";
txtOutput.Text += "G=" + buf[1 * 4 + 1, y] + ", ";
txtOutput.Text += "B=" + buf[1 * 4 + 0, y];

[VB.NET]
' RGB32 is bottom-up, the first line has index lines-1
Dim y As Integer = buf.Lines - 1

txtOutput.Text = "Image buffer pixel format is RGB32" & vbCrLf
txtOutput.Text &= "Pixel 1: "
txtOutput.Text &= "R=" & buf(0 * 4 + 2, y) & ", "
txtOutput.Text &= "G=" & buf(0 * 4 + 1, y) & ", "
txtOutput.Text &= "B=" & buf(0 * 4 + 0, y) & vbCrLf
txtOutput.Text &= "Pixel 2: "
txtOutput.Text &= "R=" & buf(1 * 4 + 2, y) & ", "
txtOutput.Text &= "G=" & buf(1 * 4 + 1, y) & ", "
txtOutput.Text &= "B=" & buf(1 * 4 + 0, y)

Manipulating Image Data

Instead of only reading pixel data, it is, of course, possible to manipulate the data as well. The following code sets the upper left hand pixel to red and the next 2 pixels to green and blue. After this manipulation, the image is saved as a .bmp file.

[C#]
// Set the first pixel to red (255 0 0)
buf[0 * 4 + 2, y] = 255;
buf[0 * 4 + 1, y] = 0;
buf[0 * 4 + 0, y] = 0;
// Set the second pixel to 128 (gray)
buf[1 * 4 + 2, y] = 0;
buf[1 * 4 + 1, y] = 255;
buf[1 * 4 + 0, y] = 0;
// Set the third pixel to 255 (white)
buf[2 * 4 + 2, y] = 0;
buf[2 * 4 + 1, y] = 0;
buf[2 * 4 + 0, y] = 255;

buf.SaveAsBitmap("RGB32.bmp");

[VB.NET]
' Set the first pixel to red (255 0 0)
buf(0 * 4 + 2, y) = 255
buf(0 * 4 + 1, y) = 0
buf(0 * 3 + 0, y) = 0
' Set the second pixel to 128 (gray)
buf(1 * 4 + 2, y) = 0
buf(1 * 4 + 1, y) = 255
buf(1 * 4 + 0, y) = 0
' Set the third pixel to 255 (white)
buf(2 * 4 + 2, y) = 0
buf(2 * 4 + 1, y) = 0
buf(2 * 4 + 0, y) = 255

buf.SaveAsBitmap("RGB32.bmp")

To check the result, open the saved image and take a look at the upper left hand pixels. They should look as follows:

<< Accessing an Image Buffer


YGB0

YGB0 is a 10 bit grayscale format. Every pixel is stored in two bytes. Only 10 of the 16 bits of these two bytes contain relevant image data, the other bits are unused. The organization of the pixels in the image buffer is from left to right and top down.

Memory Layout

As illustrated above, the low byte contains the bits 2 to 9, while the least significant bits 0 and 1 are stored in the high byte. To convert two bytes from the image buffer to a 16-bit-value (in range 0-1023) that can be used in image processing, the bytes have to be swapped and a right-shift has to be performed. The following code shows how to convert to and from YGB0 format:

[C#]
private UInt16 UInt16ValueFromYGB0Bytes(byte b1, byte b2)
{
    return (UInt16)(((b1 << 8) | b2) >> 6);
}

private void YGB0BytesFromUInt16Value(UInt16 val, out byte b1, out byte b2)
{
    val <<= 6;
    b1 = (byte)(val >> 8);
    b2 = (byte)(val & 0xff);
}

[VB.NET]
Private Function IntValueFromYGB0Bytes(ByVal b1 As Byte, ByVal b2 As Byte) As Integer
    Return (((CInt(b1) << 8) Or CInt(b2)) >> 6)
End Function

Private Function YGB0BytesFromIntValue(ByVal val As Integer, ByRef b1 As Byte, ByRef b2 As Byte)
    val <<= 6
    b1 = CByte(val >> 8)
    b2 = CByte(val & 255)
End Function

The function UInt16ValueFromYGB0Bytes takes a 16-bit word from the image buffer and converts it to a logical brightness value for that pixel in the range 0 to 1023.

YGB0BytesFromUInt16Value reverses that operation by converting a brightness value to a number that can be stored in the image buffer.

How to read and write pixel data

A video capture device, video format, FrameHandlerSink with a ImageBuffers collections, which defines the image data color format must have been setup. The following code fragments show step-by-step how to access and manipulate the pixel data of YGB0.

First of all, we have to capture an image. Otherwise, the image buffer would be empty. To do so, live mode is started and FrameHandlerSink.SnapImage is called.

Accessing the buffer

To access the bytes of the image buffer, you can write buf[column,line] in C# and buf(column,line) in VB.NET.

In this example, we want to read out the first (upper left) two pixels of the image. In a second step we manipulate the first 3 pixels. Because RGB images are stored bottom-up, the index of the first line is lines-1.

To calculate the x-coordinate of the pixel data, the number of bytes required for one pixel (2) is multiplied with the column of the pixel to be retrieved. After that, an offset is added to access the two bytes of one pixel.

To convert the pixel data to brightness values, the function UInt16ValueFromYGB0Bytes from above is used:

[C#]
// YGB0 is top-down, the first line has index 0
int y = 0;

UInt16 val0 = UInt16ValueFromYGB0Bytes(buf[0 * 2 + 0, y], buf[0 * 2 + 1, y]);
UInt16 val1 = UInt16ValueFromYGB0Bytes(buf[1 * 2 + 0, y], buf[1 * 2 + 1, y]);

txtOutput.Text = "Image buffer pixel format is YGB0\r\n";
txtOutput.Text += "Pixel 1: " + val0 + "\r\n";
txtOutput.Text += "Pixel 2: " + val1;

[VB.NET]
' YGB0 is top-down, the first line has index 0
Dim y As Integer = 0

Dim val0 As Integer = IntValueFromYGB0Bytes(buf(0, y), buf(1, y))
Dim val1 As Integer = IntValueFromYGB0Bytes(buf(2, y), buf(3, y))

txtOutput.Text = "Image buffer pixel format is YGB0" & vbCrLf
txtOutput.Text &= "Pixel 1: " & val0 & vbCrLf
txtOutput.Text &= "Pixel 2: " & val1

Manipulating Image Data

Now we set the upper left three pixels to black, gray and white. The function YGB0BytesFromUInt16Value from above is used to convert from brightness values to pixel data:

[C#]
byte b1, b2;
YGB0BytesFromUInt16Value(0, out b1, out b2);
buf[0 * 2 + 0, y] = b1;
buf[0 * 2 + 1, y] = b2;
YGB0BytesFromUInt16Value(512, out b1, out b2);
buf[1 * 2 + 0, y] = b1;
buf[1 * 2 + 1, y] = b2;
YGB0BytesFromUInt16Value(1023, out b1, out b2);
buf[2 * 2 + 0, y] = b1;
buf[2 * 2 + 1, y] = b2;

buf.SaveAsBitmap("ygb0.bmp", TIS.Imaging.ICImagingControlColorformats.ICY800);

[VB.NET]
Dim b1, b2 As Byte
YGB0BytesFromIntValue(0, b1, b2)
buf(0, y) = b1
buf(1, y) = b2
YGB0BytesFromIntValue(512, b1, b2)
buf(2, y) = b1
buf(3, y) = b2
YGB0BytesFromIntValue(1023, b1, b2)
buf(4, y) = b1
buf(5, y) = b2

buf.SaveAsBitmap("ygb0.bmp", TIS.Imaging.ICImagingControlColorformats.ICY800)

To check the result, just open the saved image and examine the upper left hand pixels. They should look as follows:

<< Accessing an Image Buffer


YGB1

YGB1 is a 10 bit grayscale format. Every pixel is stored in two bytes. Only 10 of the 16 bits of these two bytes contain relevant image data, the other bits are unused. The organization of the pixels in the image buffer is from left to right and top down.

Memory Layout

As illustrated above, the high byte contains the bits 0 to 7, while the most significant bits 8 and 9 are stored in the low byte. To convert a 16-bit-pixel from the image buffer to a 16-bit-value (in range 0-1023) that can be used in image processing, the bytes have to be swapped. The following code shows how to convert to and from the YGB1 format:

[C#]
private UInt16 UInt16ValueFromYGB1Bytes(byte b1, byte b2)
{
    return (UInt16)((b1 << 8) | b2);
}

private void YGB1BytesFromUInt16Value(UInt16 val, out byte b1, out byte b2)
{
    b1 = (byte)(val >> 8);
    b2 = (byte)(val & 0xff);
}

[VB.NET]
Private Function IntValueFromYGB1Bytes(ByVal b1 As Byte, ByVal b2 As Byte) As Integer
    Return (CInt(b1) << 8) Or CInt(b2)
End Function

Private Function YGB1BytesFromIntValue(ByVal val As Integer, ByRef b1 As Byte, ByRef b2 As Byte)
    b1 = CByte(val >> 8)
    b2 = CByte(val And 255)
End Function

The function UInt16ValueFromYGB1Bytes takes a 16-bit word from the image buffer and converts it to a logical brightness value for that pixel in the range 0 to 1023.

YGB1BytesFromUInt16Value reverses that operation by converting a brightness value to a number that can be stored in the image buffer.

How to read and write pixel data

A video capture device, video format, FrameHandlerSink with a ImageBuffers collections, which defines the image data color format must have been setup. The following code fragments show step-by-step how to access and manipulate the pixel data of YGB1.

First of all, we have to capture an image. Otherwise, the image buffer would be empty. To do so, live mode is started and FrameHandlerSink.SnapImage is called.

Accessing the buffer

To access the bytes of the image buffer, you can write buf[column,line] in C# and buf(column,line) in VB.NET.

In this example, we want to read out the first (upper left hand) two pixels of the image. In a second step we manipulate the first 3 pixels. Because RGB images are stored bottom-up, the index of the first line is lines-1.

To calculate the x-coordinate of the pixel data, the number of bytes required for one pixel (2) is multiplied with the column of the pixel to be retrieved. After that, an offset is added to access the two bytes of one pixel.

To convert the pixel data to brightness values, the function UInt16ValueFromYGB1Bytes from above is used:

[C#]
// YGB1 is top-down, the first line has index 0
int y = 0;

UInt16 val0 = UInt16ValueFromYGB1Bytes(buf[0, y], buf[1, y]);
UInt16 val1 = UInt16ValueFromYGB1Bytes(buf[2, y], buf[3, y]);

txtOutput.Text = "Image buffer pixel format is YGB1\r\n";
txtOutput.Text += "Pixel 1: " + val0 + "\r\n";
txtOutput.Text += "Pixel 2: " + val1;

[VB.NET]
' YGB1 is top-down, the first line has index 0
Dim y As Integer = 0

Dim val0 As Integer = IntValueFromYGB1Bytes(buf(0, y), buf(1, y))
Dim val1 As Integer = IntValueFromYGB1Bytes(buf(2, y), buf(3, y))

txtOutput.Text = "Image buffer pixel format is YGB1" & vbCrLf
txtOutput.Text &= "Pixel 1: " & val0 & vbCrLf
txtOutput.Text &= "Pixel 2: " & val1

Manipulating Image Data

Now we set the upper left three pixels to black, gray and white. The function YGB1BytesFromUInt16Value from above is used to convert from brightness values to pixel data:

[C#]
byte b1, b2;
YGB1BytesFromUInt16Value(0, out b1, out b2);
buf[0, y] = b1;
buf[1, y] = b2;
YGB1BytesFromUInt16Value(512, out b1, out b2);
buf[2, y] = b1;
buf[3, y] = b2;
YGB1BytesFromUInt16Value(1023, out b1, out b2);
buf[4, y] = b1;
buf[5, y] = b2;

buf.SaveAsBitmap("ygb1.bmp", TIS.Imaging.ICImagingControlColorformats.ICY800);

[VB.NET]
Dim b1, b2 As Byte
YGB1BytesFromIntValue(0, b1, b2)
buf(0, y) = b1
buf(1, y) = b2
YGB1BytesFromIntValue(512, b1, b2)
buf(2, y) = b1
buf(3, y) = b2
YGB1BytesFromIntValue(1023, b1, b2)
buf(4, y) = b1
buf(5, y) = b2

buf.SaveAsBitmap("ygb1.bmp", TIS.Imaging.ICImagingControlColorformats.ICY800)

To check the result, open the saved image and examine the upper left hand pixels. They should look as follows:

<< Accessing an Image Buffer


Performing Advanced Image Processing

This chapter illustrates how to perform sophisticated image processing.

The source code for the VB.NET and C# versions of this sample program can be found in the directories samples\VB *\Advanced Image Processing and samples\C# *\Advanced Image Processing in your My Documents/IC Imaging Control 3.2 directory.

Overview

This chapter illustrates how to:

  • display image buffers
  • render an overlay on the live image
  • process mouse events
  • process data contained in image buffers

The sample described in this chapter lets you draw a rectangle on the live image using the mouse. The region specified by the rectangle is used to check whether the live image has changed. If so, the changed image is displayed. The threshold for the difference between the images can be set by the user.

Setting up the Project

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 2003 - 2008 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 making a selection, the displays error message and terminates.

Add two buttons to the form and label them Device and Settings. Name them cmdDevice and cmdSettings respectively. If you click the "Device" button, a device selection dialog is displayed. After you have selected a valid device, setupDevice is called. This is a helper procedure, which sets up a FrameHandlerSink that is used to grab images. The sink is initialized with a ring buffer size of 5 and Y800 as color format. ICImagingControl.LiveDisplay is disabled, because the buffers are drawn by hand in this sample. The Settings button shows a dialog that allows you to adjust the VCDProperties of the currently selected device. The code for both buttons looks as follows:

[VB.NET]
Private Sub cmdDevice_Click(ByVal sender As System.Object, ByVal e As System.EventArgs) Handles cmdDevice.Click
    With IcImagingControl1
        If .LiveVideoRunning Then
            .LiveStop()
        End If

        .ShowDeviceSettingsDialog()

        If .DeviceValid Then
            cmdStart.Enabled = True
            cmdSettings.Enabled = True
            MakeDeviceSettings()
        End If
    End With
End Sub

[C#]
private void cmdDevice_Click(object sender, EventArgs e)
{
    if (icImagingControl1.LiveVideoRunning)
    {
        icImagingControl1.LiveStop();
    }

    icImagingControl1.ShowDeviceSettingsDialog();

    if (icImagingControl1.DeviceValid)
    {
        cmdStart.Enabled = true;
        cmdSettings.Enabled = true;
        MakeDeviceSettings();
    }
}

[VB.NET]
Private Sub cmdSettings_Click(ByVal sender As System.Object, ByVal e As System.EventArgs) Handles cmdSettings.Click
    IcImagingControl1.ShowPropertyDialog()
End Sub

[C#]
private void cmdSettings_Click(object sender, EventArgs e)
{
    icImagingControl1.ShowPropertyDialog();
}

Declaring Global Variables

Create a user data type named RECT to hold the coordinates for a rectangle by inserting the following code at the beginning of your Form class.

[VB.NET]
Private Structure RECT
    Dim Left As Integer
    Dim Top As Integer
    Dim Right As Integer
    Dim Bottom As Integer
End Structure

[C#]
private struct RECT
{
    public int Left;
    public int Top;
    public int Right;
    public int Bottom;
}

Now, insert three global variables.

[VB.NET]
Private DisplayBuffer As TIS.Imaging.ImageBuffer
Private UserROI As RECT
Private UserROICommited As Boolean
Private Threshold As Integer

[C#]
private delegate void ShowBufferDelegate(TIS.Imaging.ImageBuffer buffer);
private ImageBuffer DisplayBuffer;
private RECT UserROI;
private bool UserROICommited = false;
private int threshold = 0;
  • DisplayBuffer will contain a reference to the buffer that will be displayed on the ImageAvailable event. When deciding whether displaying a new buffer is necessary, the new buffer is compared to DisplayBuffer.
  • UserROI will contain the region of interest the user has set with the mouse.
  • UserROICommited will be used to toggle between drawing and testing.

Adding the Mouse Event Procedures

Add event procedures for ICImagingControl's MouseDown, MouseUp, and MouseMove events. Insert the following code into the event procedures:

MouseDown:

[VB.NET]
If Not UserROICommited And (e.Button = Forms.MouseButtons.Left) Then
    UserROI.Left = e.X
    UserROI.Top = IcImagingControl1.Height - e.Y
End If

[C#]
if (!UserROICommited && (e.Button == MouseButtons.Left))
{
    UserROI.Left = e.Location.X;
    UserROI.Top = icImagingControl1.Height - e.Location.Y;
}

MouseUp:

[VB.NET]
If Not UserROICommited And Not (e.Button = Forms.MouseButtons.Left) Then
    UserROI.Right = e.X
    UserROI.Bottom = IcImagingControl1.Height - e.Y
End If

[C#]
if (!UserROICommited && !(e.Button == MouseButtons.Left))
{
    UserROI.Right = e.Location.X;
    UserROI.Bottom = icImagingControl1.Height - e.Location.Y;
}

MouseMove:

[VB.NET]
If Not UserROICommited And (e.Button = Forms.MouseButtons.Left) Then
    UserROI.Right = e.X
    UserROI.Bottom = IcImagingControl1.Height - e.Y
End If

[C#]
if (!UserROICommited && (e.Button == MouseButtons.Left))
{
    UserROI.Right = e.Location.X;
    UserROI.Bottom = icImagingControl1.Height - e.Location.Y;
}

Because we use Y800 as sink color format, the mouse positions are identical to the pixel positions in the image buffers. Thus, we can set the UserROI.bottom and .top members to YPos.

When using a bottom-up sink color format such as RGB8, you had to transform the mouse positions to ICImagingControl1.Height - YPos.

Adding Functionality to the Application

As described in Displaying Buffers on the ImageAvailable Event, create two buttons ( Start / Stop ), the Form_Load event procedure and an ImageAvailable event handler. Add the line DisplayBuffer.ForceUnlock to the Stop_Click event handler. This is necessary as the DisplayBuffer will be locked in the ImageAvailable event procedure. When the control is stopped, the DisplayBuffer needs to be unlocked. Insert the following code into the ImageAvailable handler:

[VB.NET]
Private Sub IcImagingControl1_ImageAvailable(ByVal sender As Object, ByVal e As TIS.Imaging.ICImagingControl.ImageAvailableEventArgs) Handles IcImagingControl1.ImageAvailable
    Try
        Dim Region As RECT
        Region = NormalizeRect(UserROI)

        ContinousMode(e.bufferIndex, Region)
    Catch ex As Exception
        System.Diagnostics.Trace.WriteLine(ex.Message)
    End Try
End Sub

[C#]
private void icImagingControl1_ImageAvailable(object sender, TIS.Imaging.ICImagingControl.ImageAvailableEventArgs e)
{
    try
    {
        RECT Region;
        Region = NormalizeRect(UserROI)

        ContinousMode(e.bufferIndex, Region)
    }
    catch(Exception ex)
    {
        System.Diagnostics.Trace.WriteLine(ex.Message);
    }
}

This event handler uses the function NormalizeRect to make sure the rectangle's coordinates are not exchanged, e.g. left greater than right. It also calls the sub ContinousMode to paint that rectangle onto the image buffer. NormalizeRect is implemented as follows:

[VB.NET]
Private Function NormalizeRect(ByRef val As RECT) As RECT
    Dim Tmp As Integer
    Dim r As RECT
    r = val
    If r.Top > r.Bottom Then
        Tmp = r.Top
        r.Top = r.Bottom
        r.Bottom = Tmp
    End If
    If r.Left > r.Right Then
        Tmp = r.Left
        r.Left = r.Right
        r.Right = Tmp
    End If
    If r.Top < 0 Then
        r.Top = 0
    End If
    If r.Left < 0 Then
        r.Left = 0
    End If
    If r.Bottom >= IcImagingControl1.ImageHeight Then
        r.Bottom = IcImagingControl1.ImageHeight - 1
    End If
    If r.Right >= IcImagingControl1.ImageWidth Then
        r.Right = IcImagingControl1.ImageWidth - 1
    End If
    NormalizeRect = r
End Function

[C#]
private RECT NormalizeRect(RECT val)
{
    int Tmp;
    RECT r;

    r = val;

    if (r.Top > r.Bottom)
    {
        Tmp = r.Top;
        r.Top = r.Bottom;
        r.Bottom = Tmp;
    }

    if (r.Left > r.Right)
    {
        Tmp = r.Left;
        r.Left = r.Right;
        r.Right = Tmp;
    }

    if (r.Top < 0)
    {
        r.Top = 0;
    }

    if (r.Left < 0)
    {
        r.Left = 0;
    }

    if (r.Bottom >= icImagingControl1.ImageHeight)
    {
        r.Bottom = icImagingControl1.ImageHeight - 1;
    }

    if (r.Right >= icImagingControl1.ImageWidth)
    {
        r.Right = icImagingControl1.ImageWidth - 1;
    }

    return r;
}

The sub ContinousMode is implemented in the following way:

[VB.NET]
Private Sub ContinousMode(ByVal BufferIndex As Integer, ByVal Region As RECT)
    DisplayBuffer = IcImagingControl1.ImageBuffers(BufferIndex)
    DisplayBuffer.Lock()
    DrawRectangleY8(DisplayBuffer, Region)
    IcImagingControl1.DisplayImageBuffer(DisplayBuffer)
    DisplayBuffer.Unlock()
End Sub

[C#]
private void ContinousMode(int BufferIndex, RECT Region)
{
    //DisplayBuffer.Unlock();
    DisplayBuffer = icImagingControl1.ImageBuffers[BufferIndex];
    //DisplayBuffer.Lock();

    DrawRectangleY8(DisplayBuffer, Region);

    this.BeginInvoke(new ShowBufferDelegate(ShowImageBuffer), DisplayBuffer);
}

First the DisplayBuffer is unlocked. It is generally good practice to release locks that are no longer required, otherwise the control can not write to that buffer. Then the image buffer specified by BufferIndex of the ImageBuffers collection is assigned to DisplayBuffer. This buffer is locked with DisplayBuffer.Lock to prevent DisplayBuffer from being overwritten by IC Imaging Control. Then the DrawRectangleY8 sub procedure draws a rectangle specified by Region into the image buffer. To display the buffer, ICImagingControl.DisplayImageBuffer is called with DisplayBuffer as its parameter. The buffer now contains a white rectangle that represents the current region of interest.

Implemented this way, IC Imaging Control enables the user to select a region by painting a rectangle on the control while a live video is running.

Inserting the "CompareMode"

Now, we add the functionality to only update the display, if something changes in the region of interest. Create a button, named cmdROICommit and add the following code to it's click event procedure:

[VB.NET]
Private Sub cmdROICommit_Click(ByVal sender As System.Object, ByVal e As System.EventArgs) Handles cmdROICommit.Click
    If Not UserROICommited Then
        UserROICommited = True
        cmdROICommit.Text = "Reset ROI"
    Else
        UserROICommited = False
        cmdROICommit.Text = "Set current ROI"
    End If
End Sub

[C#]
private void cmdROICommit_Click(object sender, EventArgs e)
{
    if (!UserROICommited)
    {
        UserROICommited = true;
        cmdROICommit.Text = "Reset ROI";
    }
    else
    {
        UserROICommited = false;
        cmdROICommit.Text = "Set current ROI";
    }
}

When this button is clicked, the region of interest is committed. The application then switches to the "CompareMode". In this mode, the display is only updated, if something within the region of interest has changed. When the "CompareMode" is already running, the button toggles to "ContinousMode".

Updating the Code in the Event Procedures

Add the the following code to the cmdStart_Click event procedure:

[VB.NET]
cmdROICommit.Enabled = True

[C#]
cmdROICommit.Enabled = true;

This enables the painting of the ROI every time you start the live video. This is named "ContinousMode" in this example.

Add the following code to the cmdStop_Click event procedure:.

[VB.NET]
If UserROICommited Then
    cmdROICommit_Click(sender, e)  ' Change CompareMode to ContinousMode.
End If
cmdROICommit.Enabled = False

[C#]
if( UserROICommited )
{
    cmdROICommit_Click(sender, e);  // Change CompareMode to ContinousMode.
}
cmdROICommit.Enabled = false;

This will reset the mode from "CompareMode" to "ContinousMode" when the "Stop" button is clicked and the "CompareMode" is active. Further, add the line cmdROICommit.Enabled = False to the Form_Load event procedure.

Then alter the code in the ImageAvailable event procedure:

[VB.NET]
Dim Region As RECT
Region = NormalizeRect(UserROI)

If Not UserROICommited Then
    ContinousMode(e.bufferIndex, Region)
Else
    CompareMode(e.bufferIndex, Region)
End If

[C#]
RECT Region;
Region = NormalizeRect(UserROI);

if (!UserROICommited)
{
    ContinousMode(e.bufferIndex, Region);
}
else
{
    CompareMode(e.bufferIndex, Region);
}

This calls the appropriate sub procedures, depending on UserROICommited.

The "CompareMode" Procedure

The new ImageAvailable event procedure calls the sub procedure CompareMode, which is implemented as follows:

[VB.NET]
Private Sub CompareMode(ByVal BufferIndex As Integer, ByVal Region As RECT)
    Dim IBOld, IBNew As TIS.Imaging.ImageBuffer
    IBOld = DisplayBuffer
    IBNew = IcImagingControl1.ImageBuffers(BufferIndex)

    If CompareRegion(IBOld, IBNew, Region, Threshold) Then
        DisplayBuffer.Unlock()
        DisplayBuffer = IBNew
        DisplayBuffer.Lock()

        DrawRectangleY8(IBNew, Region)

        IcImagingControl1.DisplayImageBuffer(DisplayBuffer)
    End If
End Sub

[C#]
private void CompareMode(int BufferIndex, RECT Region)
{
    TIS.Imaging.ImageBuffer IBOld, IBNew;

    IBOld = DisplayBuffer;
    IBNew = icImagingControl1.ImageBuffers[BufferIndex];

    if (CompareRegion(IBOld, IBNew, Region, threshold) )
    {
        //DisplayBuffer.Unlock()
        DisplayBuffer = IBNew;
        //DisplayBuffer.Lock()

        DrawRectangleY8(IBNew, Region);

        this.BeginInvoke(new ShowBufferDelegate(ShowImageBuffer), DisplayBuffer);
    }
}

This sub calls the CompareRegion sub function, which compares the region of interest of the image buffers. If they differ, the old DisplayBuffer is unlocked and the new image buffer IBNew is assigned to DisplayBuffer. DisplayBuffer then contains the new image. The new DisplayBuffer is locked to prevent it from being overwritten by IC Imaging Control. The region of interest is drawn as a rectangle into the buffer, and the buffer is displayed, using ICImagingControl.DisplayImageBuffer.

The CompareRegion Function

The CompareRegion function compares the region of interest of the two image buffers Buf and Buf2. The differences of the pixels in the specified Region are added. The result is saved in the variable GreyscaleDifference. After adding, GreyscaleDifference is divided by the count of pixels in the region. GreyscaleDifference is compared to the threshold value passed to the function. If the threshold is lower or equal to GreyscaleDifference, the regions differ and the function returns True, False otherwise. The CompareRegion function is implemented as follows:

[VB.NET]
Private Function CompareRegion(ByVal Buf As TIS.Imaging.ImageBuffer, ByVal Buf2 As TIS.Imaging.ImageBuffer, ByVal Region As RECT, ByVal Threshold As Integer) As Boolean
    Dim x, y As Integer
    Dim GreyscaleDifference As Integer
    Dim PixelCount As Integer

    PixelCount = (Region.Bottom - Region.Top) * (Region.Right - Region.Left)
    If PixelCount > 0 Then
        GreyscaleDifference = 0
        For y = Region.Top To Region.Bottom
            For x = Region.Left To Region.Right
                GreyscaleDifference = GreyscaleDifference + Math.Abs(CInt(Buf(x, y)) - CInt(Buf2(x, y)))
            Next x
        Next y
        GreyscaleDifference = GreyscaleDifference / PixelCount
        If GreyscaleDifference > Threshold Then
            CompareRegion = True
        Else
            CompareRegion = False
        End If
    Else
        CompareRegion = False
    End If
End Function

[C#]
private bool CompareRegion(TIS.Imaging.ImageBuffer Buf, TIS.Imaging.ImageBuffer Buf2, RECT Region, int Threshold)
{
    int x, y;
    int GreyscaleDifference;
    int PixelCount;

    PixelCount = (Region.Bottom - Region.Top) * (Region.Right - Region.Left);
    if (PixelCount > 0)
    {
        GreyscaleDifference = 0;
        for (y = Region.Top; y <= Region.Bottom; y++)
        {
            for (x = Region.Left; x <= Region.Right; x++)
            {
                GreyscaleDifference = GreyscaleDifference + Math.Abs((int)(Buf[x, y]) - (int)(Buf2[x, y]));
            }
        }
        GreyscaleDifference = GreyscaleDifference / PixelCount;
        if (GreyscaleDifference > Threshold)
        {
            return true;
        }
        else
        {
            return false;
        }
    }
    else
    {
        return false;
    }
}

<< Programmer's Guide


Creating an Overlay

This chapter shows you how to write text and draw graphics on the live video images.

The source code for the VB.NET and C# versions of this sample program can be found in the directories samples\VB *\Creating an Overlay and samples\C# *\Creating an Overlay in your My Documents/IC Imaging Control 3.2 directory.

Setting up the Project

First of all, create a new project and add IC Imaging Control to the form as shown in the FirstSteps chapter.

Then, insert three new buttons to your form and name them cmdSelectDevice, cmdLiveVideo and cmdImageSetting. Label the buttons Device, Start and Settings respectively. These buttons will be used to select the video capture device, start and stop the live video and open the image settings dialog.

Now, implement the handler subs for the three buttons:

[VB.NET]
Private Sub cmdDevice_Click(ByVal sender As System.Object, ByVal e As System.EventArgs) Handles cmdDevice.Click
    cmdStartStop.Text = "Start"

    Dim wasLive As Boolean = IcImagingControl1.LiveVideoRunning
    If wasLive Then IcImagingControl1.LiveStop()

    IcImagingControl1.ShowDeviceSettingsDialog()

    If IcImagingControl1.DeviceValid Then

        If wasLive Then
            IcImagingControl1.LiveStart()
            cmdStartStop.Text = "Stop"
        End If

        cmdStartStop.Enabled = True
        cmdSettings.Enabled = True
    End If
End Sub

[VB.NET]
Private Sub cmdStartStop_Click(ByVal sender As System.Object, ByVal e As System.EventArgs) Handles cmdStartStop.Click
    With IcImagingControl1
        If .LiveVideoRunning Then
            .LiveStop()
            cmdStartStop.Text = "Start"
        Else
            .LiveStart()
            cmdStartStop.Text = "Stop"
        End If
    End With
End Sub

[VB.NET]
Private Sub cmdSettings_Click(ByVal sender As System.Object, ByVal e As System.EventArgs) Handles cmdSettings.Click
    If IcImagingControl1.DeviceValid Then
        IcImagingControl1.ShowPropertyDialog()
    End If
End Sub

[C#]
private void cmdDevice_Click(object sender, EventArgs e)
{
    cmdStartStop.Text = "Start";

    bool wasLive = icImagingControl1.LiveVideoRunning;
    if (wasLive)
        icImagingControl1.LiveStop();

    icImagingControl1.ShowDeviceSettingsDialog();

    if (icImagingControl1.DeviceValid)
    {
        if (wasLive)
        {
            icImagingControl1.LiveStart();
            cmdStartStop.Text = "Stop";
        }

        cmdStartStop.Enabled = true;
        cmdSettings.Enabled = true;
    }
}

[C#]
private void cmdStartStop_Click(object sender, EventArgs e)
{
    if (icImagingControl1.LiveVideoRunning)
    {
        icImagingControl1.LiveStop();
        cmdStartStop.Text = "Start";
    }
    else
    {
        if( icImagingControl1.DeviceValid )
        {
            icImagingControl1.LiveStart();
            cmdStartStop.Text = "Stop";
        }
    }
}

[C#]
private void cmdSettings_Click(object sender, EventArgs e)
{
    if (icImagingControl1.DeviceValid)
    {
        icImagingControl1.ShowPropertyDialog();
    }
}

Run the program: You should be able to select a video capture device and see the live video.

Using the OverlayBitmap Object

IC Imaging Control provides a special object for drawing and writing on the live video. The object is called OverlayBitmap.

The OverlayBitmap object contains a bitmap, which has the same size as the video format, or the size of a frame filter that transforms the image data before the overlay bitmap is applied. An application can draw text and graphics on this overlay bitmap. The overlay bitmap is copied to each sample of the video. A dropout color can be specified to determine, which pixels of the overlay bitmap are transparent and therefore not copied to the live video.

The overlay bitmap can only be used, if ICImagingControl.LiveStart has been called at least once after the video format has been changed. It is only visible, if the live video is running.

Enabling and disabling overlay for device, sink and display paths

Since version 3.0, IC Imaging Control allows you to select whether the overlay is drawn on live video, on grabbed and recorded images, or both.

You can use ICImagingControl.OverlayBitmapPosition to set an ORed combination of PathPositions values that specify the path positions at which overlay bitmap objects are inserted.

Enabling the overlay bitmap is a two-step process: The OverlayBitmapPosition has to be set before starting live mode and determines, at which path positions overlay operations are possible. OverlayBitmap.Enable enables or disables the application of a specific overlay bitmap while live mode is running.

Accessing the OverlayBitmap Objects

To access one of the 3 OverlayBitmap objects, use ICImagingControl.OverlayBitmapAtPath. The parameter of that property selects the position of the OverlayBitmap that is accessed.

The ICImagingControl.OverlayBitmap property returns the OverlayBitmap for the device path.

Setting up the Overlay

A program can draw on any of the overlay bitmaps once live mode has been prepared or started. Live mode has to be prepared first, because the actual size and color format of the overlay bitmaps can depend on frame filters, thus it is impossible to determine the formats before.

The ICImagingControl.LivePrepared event is raised when live mode has been successfully prepared. Implement an event handler that draws several graphics on the 3 overlay bitmaps:

[VB.NET]
Private Sub IcImagingControl1_LivePrepared(ByVal sender As System.Object, ByVal e As System.EventArgs) Handles IcImagingControl1.LivePrepared

    If IcImagingControl1.DeviceValid Then

        SetupOverlay(IcImagingControl1.OverlayBitmapAtPath(PathPositions.Device))
        SetupOverlay(IcImagingControl1.OverlayBitmapAtPath(PathPositions.Sink))
        SetupOverlay(IcImagingControl1.OverlayBitmapAtPath(PathPositions.Display))

        ' Display a coordinate system on the device overlay
        DrawCoordinatesystem(IcImagingControl1.OverlayBitmapAtPath(PathPositions.Device))

        ' Load a  bitmap file and display it on the display overlay
        ShowBitmap(IcImagingControl1.OverlayBitmapAtPath(PathPositions.Display))

        ' Draw overlay info boxes
        DrawOverlayInfo(IcImagingControl1.OverlayBitmapAtPath(PathPositions.Device))
        DrawOverlayInfo(IcImagingControl1.OverlayBitmapAtPath(PathPositions.Sink))
        DrawOverlayInfo(IcImagingControl1.OverlayBitmapAtPath(PathPositions.Display))
    End If
End Sub

[C#]
private void icImagingControl1_LivePrepared(object sender, EventArgs e)
{
    if (icImagingControl1.DeviceValid)
    {
        if( (icImagingControl1.OverlayBitmapPosition & PathPositions.Device) != 0 )
        {
            SetupOverlay(icImagingControl1.OverlayBitmapAtPath[PathPositions.Device]);

            // Display a coordinate system on the device overlay
            DrawCoordinatesystem(icImagingControl1.OverlayBitmapAtPath[PathPositions.Device]);

            // Draw overlay info box
            DrawOverlayInfo(icImagingControl1.OverlayBitmapAtPath[PathPositions.Device]);
        }

        if ((icImagingControl1.OverlayBitmapPosition & PathPositions.Sink) != 0)
        {
            SetupOverlay(icImagingControl1.OverlayBitmapAtPath[PathPositions.Sink]);

            // Draw overlay info box
            DrawOverlayInfo(icImagingControl1.OverlayBitmapAtPath[PathPositions.Sink]);
        }

        if ((icImagingControl1.OverlayBitmapPosition & PathPositions.Display) != 0)
        {
            SetupOverlay(icImagingControl1.OverlayBitmapAtPath[PathPositions.Display]);

            // Load a  bitmap file and display it on the display overlay
            ShowBitmap(icImagingControl1.OverlayBitmapAtPath[PathPositions.Display]);

            // Draw overlay info box
            DrawOverlayInfo(icImagingControl1.OverlayBitmapAtPath[PathPositions.Display]);
        }
    }
}

The SetupOverlay sub is used to initialize each of the 3 overlays. It is called after live mode has been started.

[VB.NET]
Private Sub SetupOverlay(ByVal ob As TIS.Imaging.OverlayBitmap)

    ' Enable the overlay bitmap for drawing.
    ob.Enable = True

    ' Set magenta as dropout color.
    ob.DropOutColor = Color.Magenta

    ' Fill the overlay bitmap with the dropout color.
    ob.Fill(ob.DropOutColor)

    Dim OldFont As Font = ob.Font
    ob.Font = New Font("Arial", 10)

    ' Print text in red.
    ob.FontTransparent = True
    ob.DrawText(Color.Red, 10, 10, "IC Imaging Control 3.2")

    ob.Font = OldFont
End Sub

[C#]
private void SetupOverlay( TIS.Imaging.OverlayBitmap ob )
{
    // Enable the overlay bitmap for drawing.
    ob.Enable = true;

    // Set magenta as dropout color.
    ob.DropOutColor = Color.Magenta;

    // Fill the overlay bitmap with the dropout color.
    ob.Fill( ob.DropOutColor );

    // Print text in red.
    ob.FontTransparent = true;
    ob.DrawText( Color.Red, 10, 10, "IC Imaging Control 3.2" );
}

The overlay is enabled by calling OverlayBitmap.Enable, and a text is displayed in the upper left hand corner of the bitmap. The sub also sets a dropout color.

Dropout Color

The OverlayBitmap.DropOutColor property of the OverlayBitmap object determines, which pixel color is transparent on the live video. Each pixel that has the dropout color is not copied to the live video. The dropout color can be set with Visual Basic's RGB function. It defaults to black. For this reason, the background of the text written above is transparent. The FontBackColor property of the OverlayBitmap object is set to black as default too.

In order to be able to use black color in the overlay, we change OverlayBitmap.DropOutColor to another color, for example magenta (RGB(255,0,255)). If the application is started, only a black image with our text can be seen. The image is black, because the overlay bitmap is black and the dropout color has been changed to magenta. Therefore, the overlay bitmap must be filled with magenta. The method OverlayBitmap.Fill does this for us. When the dropout color is changed, the text background is visible as a solid black rectangle. To hide this, the property OverlayBitmap.FontTransparent can be set to True.

Drawing a Coordinate Plane

In the next step, we are going to draw a coordinate plane, consisting of lines and labels. To do this, we are going to use the DrawLine and DrawText methods of the OverlayBitmap object. Additionally, we are going to change the font used to write the labels.

We are going to implement a new sub called DrawCoordinatesystem. We want to use an 8 dpi Arial font for the labels. To achieve this, a new StdFont object Font must be created. This object has font properties like font name, font size and other font attributes. Before changing the font, we save the current font in order to be able to restore it after we have completed the coordinate plane.

The Font property of the OverlayBitmap object receives the StdFont object. Now, the new font is used for all following OverlayBitmap.DrawText calls.

The complete sub that draws the coordinate plane is implemented as follows:

[VB.NET]
Private Sub DrawCoordinatesystem(ByVal ob As TIS.Imaging.OverlayBitmap)

    ' Calculate the center of the video image.
    Dim Col As Integer = IcImagingControl1.ImageWidth / 2
    Dim Row As Integer = IcImagingControl1.ImageHeight / 2

    Dim OldFont As Font = ob.Font
    ob.Font = New Font("Arial", 8)

    ob.DrawLine(Color.Red, Col, 0, Col, IcImagingControl1.ImageHeight)
    ob.DrawLine(Color.Red, 0, Row, IcImagingControl1.ImageWidth, Row)

    Dim i As Integer
    For i = 0 To Row Step 20
        ob.DrawLine(Color.Red, Col - 5, Row - i, Col + 5, Row - i)
        ob.DrawLine(Color.Red, Col - 5, Row + i, Col + 5, Row + i)
        If i > 0 Then
            ob.DrawText(Color.Red, Col + 10, Row - i - 7, i / 10)
            ob.DrawText(Color.Red, Col + 10, Row + i - 7, -i / 10)
        End If
    Next

    For i = 0 To Col Step 20
        ob.DrawLine(Color.Red, Col - i, Row - 5, Col - i, Row + 5)
        ob.DrawLine(Color.Red, Col + i, Row - 5, Col + i, Row + 5)
        If i > 0 Then
            ob.DrawText(Color.Red, Col + i - 5, Row - 17, i / 10)
            ob.DrawText(Color.Red, Col - i - 10, Row - 17, -i / 10)
        End If
    Next
    ob.Font = OldFont

End Sub

[C#]
private void DrawCoordinatesystem(TIS.Imaging.OverlayBitmap ob)
{
    // Calculate the center of the video image.
    int Col = icImagingControl1.ImageWidth / 2;
    int Row = icImagingControl1.ImageHeight / 2;

    Font OldFont = ob.Font;
    ob.Font = new Font("Arial", 8);

    ob.DrawLine(Color.Red, Col, 0, Col, icImagingControl1.ImageHeight);
    ob.DrawLine(Color.Red, 0, Row, icImagingControl1.ImageWidth, Row);

    for (int i = 0; i < Row; i += 20)
    {
        ob.DrawLine(Color.Red, Col - 5, Row - i, Col + 5, Row - i);
        ob.DrawLine(Color.Red, Col - 5, Row + i, Col + 5, Row + i);
        if (i > 0)
        {
            ob.DrawText(Color.Red, Col + 10, Row - i - 7, string.Format("{0}", i / 10));
            ob.DrawText(Color.Red, Col + 10, Row + i - 7, string.Format("{0}", -i / 10));
        }
    }

    for (int i = 0; i < Col; i += 20)
    {
        ob.DrawLine(Color.Red, Col - i, Row - 5, Col - i, Row + 5);
        ob.DrawLine(Color.Red, Col + i, Row - 5, Col + i, Row + 5);
        if (i > 0)
        {
            ob.DrawText(Color.Red, Col + i - 5, Row - 17, string.Format("{0}", i / 10));
            ob.DrawText(Color.Red, Col - i - 10, Row - 17, string.Format("{0}", -i / 10));
        }
    }

    ob.Font = OldFont;
}

Displaying the Current Time

To display the current time on the live video, a timer is inserted in the form. It is called timer1 by default and its timer interval is set to 1000 milliseconds in the property window. The timer event handler sub is called Timer1_timer. The current time is displayed in the lower right hand corner. It has a white font with a black background. Furthermore, it has its own font. Therefore, a StdFont object must be created and used, as described above. The property OverlayBitmap.FontTransparent is set to False and OverlayBitmap.FontBackColor is set to black (RGB 0 0 0).

[VB.NET]
Private Sub Timer1_Tick(ByVal sender As System.Object, ByVal e As System.EventArgs) Handles Timer1.Tick
    Dim ob = IcImagingControl1.OverlayBitmap

    If IcImagingControl1.LiveVideoRunning Then
        Dim OldFont As Font = ob.Font
        ob.Font = New Font("Arial", 14, FontStyle.Bold)

        ' Draw the time in the lower left corner of the video window.
        Dim Col As Integer = IcImagingControl1.ImageWidth - 81
        Dim Row As Integer = IcImagingControl1.ImageHeight - 20

        ' Setup the background color and drawing mode.
        ob.FontTransparent = False
        ob.FontBackColor = Color.Black

        ' Draw the text with white color.
        ob.DrawText(Color.White, Col, Row, DateTime.Now.ToString("T"))

        ' Reset the font and drawing mode.
        ob.FontTransparent = True
        ob.Font = OldFont
    End If
End Sub

[C#]
private void timer1_Tick(object sender, EventArgs e)
{
    TIS.Imaging.OverlayBitmap ob = icImagingControl1.OverlayBitmapAtPath[TIS.Imaging.PathPositions.Device];

    if (icImagingControl1.LiveVideoRunning)
    {
        // Save the current font.
        Font OldFont = ob.Font;

        ob.Font = new Font("Arial", 14, FontStyle.Bold);

        // Draw the time in the lower left corner of the video window.
        int Col = icImagingControl1.ImageWidth - 81;
        int Row = icImagingControl1.ImageHeight - 20;

        // Setup the background color and drawing mode.
        ob.FontTransparent = false;
        ob.FontBackColor = Color.Black;

        // Draw the current time with white color.
        ob.DrawText(Color.White, Col, Row, DateTime.Now.ToString("T"));

        // Restore the previously used font.
        ob.Font = OldFont;
    }
}

OverlayUpdate Event

IC Imaging Control provides an OverlayUpdate event. This event is called after a new frame has been delivered from the video capture device. Therefore, it is possible to insert individual information on to each frame (i.e. frame counter).

The OverlayUpdate sub in the example counts the frames in the variable FrameCount. The frame counter is used to draw a growing triangle. If the frame counter is greater than 25, it is reset to 0 and the triangle is deleted. Therefore, if a solid rectangle of the same size is drawn over the triangle. The color of the rectangle must be set to the DropOutColor to make it transparent. The method DrawSolidRect provides this functionality.

The OverlayUpdate event handler is implemented as follows:

[VB.NET]
Private Sub IcImagingControl1_OverlayUpdate(ByVal sender As System.Object, ByVal e As TIS.Imaging.ICImagingControl.OverlayUpdateEventArgs) Handles IcImagingControl1.OverlayUpdate
    Dim ob As TIS.Imaging.OverlayBitmap = e.overlay

    Dim lineIndex As Integer = Sink.FrameCount Mod 25

    If lineIndex = 0 Then
        ' Delete the triangle.
        ob.DrawSolidRect(ob.DropOutColor, 10, _
                                      IcImagingControl1.ImageHeight - 70, _
                                      62, _
                                      IcImagingControl1.ImageHeight - 9)
    End If

    ' Draw the new triangle line.
    ob.DrawLine(Color.Yellow, lineIndex * 2 + 10, _
        IcImagingControl1.ImageHeight - 10, _
        lineIndex * 2 + 10, _
        IcImagingControl1.ImageHeight - 10 - lineIndex)

    ' Print the current frame number:

    ' Set the background color to the current dropout color
    ' and make the font opaque.
    ob.FontBackColor = ob.DropOutColor
    ob.FontTransparent = False

    ' Save the current font.
    Dim OldFont As Font = ob.Font

    ' Set the new created font.
    ob.Font = New Font("Arial", 8)

    ' Draw the text.
    ob.DrawText(Color.Yellow, 70, IcImagingControl1.ImageHeight - 19, Str(Sink.FrameCount) + "  ")

    ' Restore the previously used font.
    ob.Font = OldFont
End Sub

[C#]
private void icImagingControl1_OverlayUpdate(object sender, TIS.Imaging.ICImagingControl.OverlayUpdateEventArgs e)
{
    TIS.Imaging.OverlayBitmap ob = e.overlay;

    int lineIndex = m_sink.FrameCount % 25;
    if (lineIndex == 0)
    {
        ob.DrawSolidRect(ob.DropOutColor, 10, icImagingControl1.ImageHeight - 70, 62,
                         icImagingControl1.ImageHeight - 9);
    }

    ob.DrawLine(Color.Yellow, lineIndex * 2 + 10,
                                    icImagingControl1.ImageHeight - 10,
                                    lineIndex * 2 + 10,
                                    icImagingControl1.ImageHeight - 10 - lineIndex);

    // Print the current frame number:
    // Set the background color to the current dropout color
    // and make the font opaque.
    ob.FontBackColor = ob.DropOutColor;
    ob.FontTransparent = false;

    // Save the current font.
    Font OldFont = ob.Font;

    // Draw the text.
    ob.Font = new Font("Arial", 8);
    ob.DrawText(Color.Yellow, 70, icImagingControl1.ImageHeight - 19,
                m_sink.FrameCount.ToString());

    // Restore the previously used font.
    ob.Font = OldFont;
}

Graphics Functions in Visual Basic .NET and C#

A new sub ShowBitmap is implemented to demonstrate how to render a bitmap onto the overlay bitmap. It uses the method OverlayBitmap.GetGraphics to retrieve a .NET Graphics object that can be used to draw on the overlay bitmap.

[VB.NET]
Private Sub ShowBitmap(ByVal ob As TIS.Imaging.OverlayBitmap)

    Try
        ' Load the sample bitmap from the application's directory.
        Dim TheBitmap As Image = Bitmap.FromFile(Application.StartupPath & "\..\..\hardware.bmp")

        ' Calculate the column to display the bitmap in the
        ' upper right corner of Imaging Control.
        Dim Col As Integer = IcImagingControl1.ImageWidth - 5 - TheBitmap.Width

        'Retrieve the Graphics object of the OverlayBitmap.
        Dim g As Graphics = ob.GetGraphics()

        g.DrawImage(TheBitmap, Col, 5)

        ' Release the Graphics after drawing is finished.
        ob.ReleaseGraphics(g)

    Catch Ex As System.Exception
        MsgBox("File not found: " + Ex.Message, MsgBoxStyle.Information, "ShowBitmap")
    End Try
End Sub

[C#]
private void ShowBitmap(TIS.Imaging.OverlayBitmap ob)
{
    try
    {
        // Load the sample bitmap from the project file's directory.
        Image bmp = Bitmap.FromFile(Application.StartupPath + @"\..\..\hardware.bmp");

        // Calculate the column to display the bitmap in the
        // upper right corner of Imaging Control.
        int col = icImagingControl1.ImageWidth - 5 - bmp.Width;

        // Retrieve the Graphics object of the OverlayBitmap.
        Graphics g = ob.GetGraphics();

        // Draw the image
        g.DrawImage(bmp, col, 5);

        // Release the Graphics after drawing is finished.
        ob.ReleaseGraphics(g);
    }
    catch (Exception Ex)
    {
        MessageBox.Show("File not found: " + Ex.Message);
    }
}

Setting the Overlay Path position

The end user of our example program can control which of the 3 overlay bitmaps are drawn on the live video. To change the PathPositions, the following helper sub is used:

[VB.NET]
Private Sub ShowBitmap(ByVal ob As TIS.Imaging.OverlayBitmap)

    Try
        ' Load the sample bitmap from the application's directory.
        Dim TheBitmap As Image = Bitmap.FromFile(Application.StartupPath & "\..\..\hardware.bmp")

        ' Calculate the column to display the bitmap in the
        ' upper right corner of Imaging Control.
        Dim Col As Integer = IcImagingControl1.ImageWidth - 5 - TheBitmap.Width

        'Retrieve the Graphics object of the OverlayBitmap.
        Dim g As Graphics = ob.GetGraphics()

        g.DrawImage(TheBitmap, Col, 5)

        ' Release the Graphics after drawing is finished.
        ob.ReleaseGraphics(g)

    Catch Ex As System.Exception
        MsgBox("File not found: " + Ex.Message, MsgBoxStyle.Information, "ShowBitmap")
    End Try
End Sub

[C#]
private void EnableOverlayBitmapAtPath(PathPositions pos, bool enabled)
{
    bool wasLive = icImagingControl1.LiveVideoRunning;
    if (wasLive)
        icImagingControl1.LiveStop();

    PathPositions oldPos = icImagingControl1.OverlayBitmapPosition;
    if (enabled)
        icImagingControl1.OverlayBitmapPosition = oldPos | pos;
    else
        icImagingControl1.OverlayBitmapPosition = oldPos & ~pos;

    if (wasLive)
        icImagingControl1.LiveStart();
}

This sub enables or disables the overlay at a specified path position.

Setting the Overlay's Color Mode

An application can decide whether it wants a color or grayscale overlay. The OverlayBitmap.ColorMode property can be used to select one of the available color modes:

OverlayBitmap.OverlayColorModes.BestFit
The overlay bitmap format is chosen to match the format of the image stream at the position of the overlay bitmap.
OverlayBitmap.OverlayColorModes.Color
The overlay bitmap format is color. You can draw colored lines and text on the overlay.
OverlayBitmap.OverlayColorModes.Grayscale
The overlay bitmap format is grayscale. You can only draw grayscale lines and text.

When the format of the image data stream does not match the overlay bitmap color mode, the image data is automatically converted.

<< Programmer's Guide


Scroll and Zoom

This chapter shows you how to use the scroll and zoom capabilities of IC Imaging Control.

The source code for the VB.NET and C# versions of this sample program can be found in the directories samples\VB *\Scroll And Zoom and samples\C# *\Scroll And Zoom in your My Documents/IC Imaging Control 3.2 directory.

Setting up the Project

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 2003 - 2008 chapter. Alternatively, run the program without selecting a device. In this case, the program shows the device selection dialog that ships with IC Imaging Control. If you close this dialog without making a selection, the program displays an error message and terminates.

Now add 2 buttons to the form and label them Start and Stop. Name the buttons cmdStart and cmdStop respectively.

Add a call to ICImagingControl.LiveStart method. In addition, a red rectangle is drawn around the whole image to visualize its perimeter:

[VB.NET]
Private Sub cmdStart_Click(ByVal sender As System.Object, ByVal e As System.EventArgs) Handles cmdStart.Click
    With IcImagingControl1
        If .DeviceValid Then
            .LiveStart()
            ' Draw a rectangle around the whole image to visualize its perimeter.
            .OverlayBitmap.Enable = True
            .OverlayBitmap.DrawLine(Color.FromArgb(255, 0, 0), 0, 0, .ImageWidth - 1, 0)
            .OverlayBitmap.DrawLine(Color.FromArgb(255, 0, 0), .ImageWidth - 1, 0, .ImageWidth - 1, .ImageHeight - 1)
            .OverlayBitmap.DrawLine(Color.FromArgb(255, 0, 0), .ImageWidth - 1, .ImageHeight - 1, 0, .ImageHeight - 1)
            .OverlayBitmap.DrawLine(Color.FromArgb(255, 0, 0), 0, 0, 0, .ImageHeight)
            .OverlayBitmap.DrawText(Color.FromArgb(255, 0, 0), 5, 5, "Scroll and Zoom Sample")
        End If
    End With
End Sub

[C#]
private void cmdStart_Click(object sender, EventArgs e)
{
    if( icImagingControl1.DeviceValid )
    {
        icImagingControl1.LiveStart();
        // Draw a rectangle around the whole image to visualize its perimeter.;
        icImagingControl1.OverlayBitmap.Enable = true;
        icImagingControl1.OverlayBitmap.DrawLine( Color.FromArgb( 255, 0, 0 ), 0, 0, icImagingControl1.ImageWidth - 1, 0 );
        icImagingControl1.OverlayBitmap.DrawLine( Color.FromArgb( 255, 0, 0 ), icImagingControl1.ImageWidth - 1, 0, icImagingControl1.ImageWidth - 1, icImagingControl1.ImageHeight - 1 );
        icImagingControl1.OverlayBitmap.DrawLine( Color.FromArgb( 255, 0, 0 ), icImagingControl1.ImageWidth - 1, icImagingControl1.ImageHeight - 1, 0, icImagingControl1.ImageHeight - 1 );
        icImagingControl1.OverlayBitmap.DrawLine( Color.FromArgb( 255, 0, 0 ), 0, 0, 0, icImagingControl1.ImageHeight );
        icImagingControl1.OverlayBitmap.DrawText( Color.FromArgb( 255, 0, 0 ), 5, 5, "Scroll and Zoom Sample" );
    }
}

Add a call to ICImagingControl.LiveStop:

[VB.NET]
Private Sub cmdStop_Click(ByVal sender As System.Object, ByVal e As System.EventArgs) Handles cmdStop.Click
    IcImagingControl1.LiveStop()
End Sub

[C#]
private void cmdStop_Click(object sender, EventArgs e)
{
    icImagingControl1.LiveStop();
}

Now add two check boxes and name them chkDisplayDefault and chkScrollbarsEnable. Label them Default window size and Scrollbars respectively. They will be used to set the LiveDisplayDefault and the ScrollBarsEnabled properties.

Also add a slider control to the form and name it sldZoom. It will be used to set the LiveDisplayZoomFactor property. In the property window of the slider, set the range of the slider from 1 to 30. The slider's value will be divided by 10, before it is passed to the LiveDisplayZoomFactor property. This allows a zoom from 10% up to 300%.

Now add 2 buttons to the form and label them Device and Settings. Name the buttons cmdDevice and cmdImageSettings respectively. Add the button handler functions:

[VB.NET]
Private Sub cmdImageSettings_Click(ByVal sender As System.Object, ByVal e As System.EventArgs) Handles cmdImageSettings.Click
    IcImagingControl1.ShowPropertyDialog()
End Sub

[C#]
private void cmdImageSettings_Click(object sender, EventArgs e)
{
    icImagingControl1.ShowPropertyDialog();
}

Enhance the cmdDevice_Click procedure to setup the check boxes and the slider control:

[VB.NET]
Private Sub cmdDevice_Click(ByVal sender As System.Object, ByVal e As System.EventArgs) Handles cmdDevice.Click
    If IcImagingControl1.DeviceValid Then
        If IcImagingControl1.LiveVideoRunning Then
            IcImagingControl1.LiveStop()
        End If
    End If
    IcImagingControl1.ShowDeviceSettingsDialog()
    If IcImagingControl1.DeviceValid Then
        cmdStart.Enabled = True
        cmdStop.Enabled = True
        cmdImageSettings.Enabled = True
        chkDisplayDefault.Enabled = True
        chkScrollbarsEnable.Enabled = True
        sldZoom.Enabled = True
        lblZoom.Enabled = True

        IcImagingControl1.LiveDisplayDefault = False
        chkDisplayDefault.Checked = False
        IcImagingControl1.LiveDisplayHeight = IcImagingControl1.ImageHeight
        IcImagingControl1.LiveDisplayWidth = IcImagingControl1.ImageWidth

        chkScrollbarsEnable.Checked = IcImagingControl1.ScrollbarsEnabled

        ' Enable or disable the slider for the zoom factor, depending
        ' on the LiveDisplayDefault property.
        sldZoom.Enabled = Not IcImagingControl1.LiveDisplayDefault
        sldZoom.Value = IcImagingControl1.LiveDisplayZoomFactor * 10
        lblZoomPercent.Text = Str(sldZoom.Value * 10) + "%"
    End If
End Sub

[C#]
private void cmdDevice_Click(object sender, EventArgs e)
{
    if (icImagingControl1.DeviceValid)
    {
        if (icImagingControl1.LiveVideoRunning)
        {
            icImagingControl1.LiveStop();
        }
    }
    icImagingControl1.ShowDeviceSettingsDialog();
    if (icImagingControl1.DeviceValid)
    {
        cmdStart.Enabled = true;
        cmdStop.Enabled = true;
        cmdImageSettings.Enabled = true;
        chkDisplayDefault.Enabled = true;
        chkScrollbarsEnable.Enabled = true;
        sldZoom.Enabled = true;
        lblZoom.Enabled = true;

        icImagingControl1.LiveDisplayDefault = false;
        chkDisplayDefault.Checked = false;
        icImagingControl1.LiveDisplayHeight = icImagingControl1.ImageHeight;
        icImagingControl1.LiveDisplayWidth = icImagingControl1.ImageWidth;

        chkScrollbarsEnable.Checked = icImagingControl1.ScrollbarsEnabled;

        // Enable or disable the slider for the zoom factor, depending
        // on the LiveDisplayDefault property.
        sldZoom.Enabled = !icImagingControl1.LiveDisplayDefault;
        sldZoom.Value = (int)(icImagingControl1.LiveDisplayZoomFactor * 10);
        lblZoomPercent.Text = (sldZoom.Value * 10).ToString() + "%";
    }
}

The check box chkDisplayDefault is used to toggle the LiveDisplayDefault property. Add a chkDisplayDefault_Click function to the form's source code. In this function, the current value of the chkDisplayDefault check box is retrieved and LiveDisplayDefault is set. Setting the LiveDisplayDefault property changes the value of the LiveDisplayZoomFactor property. Therefore, the value for the sldZoom slider control is updated to the LiveDisplayZoomFactor property value. Also, the slider control will be disabled, if the LiveDisplayDefault property returns True. If the LiveDisplayDefault property returns False, the slider control will be enabled, because now the zoom factor can be set.

[VB.NET]
Private Sub chkDisplayDefault_CheckedChanged(ByVal sender As System.Object, ByVal e As System.EventArgs) Handles chkDisplayDefault.CheckedChanged
    IcImagingControl1.LiveDisplayDefault = chkDisplayDefault.Checked
    sldZoom.Value = IcImagingControl1.LiveDisplayZoomFactor * 10
    lblZoomPercent.Text = Str(sldZoom.Value * 10) + "%"
    sldZoom.Enabled = Not IcImagingControl1.LiveDisplayDefault
End Sub

[C#]
private void chkDisplayDefault_CheckedChanged(object sender, EventArgs e)
{
    icImagingControl1.LiveDisplayDefault = chkDisplayDefault.Checked;
    sldZoom.Value = (int)(icImagingControl1.LiveDisplayZoomFactor * 10.0f);
    lblZoomPercent.Text = (sldZoom.Value * 10).ToString() + "%";
    sldZoom.Enabled = !chkDisplayDefault.Checked;
}

The check box chkScrollBarsEnable is used to enable and disable the scrollbars. Add a chkScrollbarsEnable_Click function to the form's source code. In this function, the current value of the chkScrollbarsEnable check box is retrieved and ScrollBarsEnabled is set. This allows you to show or hide the scrollbars in IC Imaging Control's window. Disabling the scrollbars will reset the live displays window position to 0/0.

[VB.NET]
Private Sub chkScrollbarsEnable_CheckedChanged(ByVal sender As System.Object, ByVal e As System.EventArgs) Handles chkScrollbarsEnable.CheckedChanged
    IcImagingControl1.ScrollbarsEnabled = chkScrollbarsEnable.Checked
End Sub

[C#]
private void chkScrollbarsEnable_CheckedChanged(object sender, EventArgs e)
{
    icImagingControl1.ScrollbarsEnabled = chkScrollbarsEnable.Checked;
}

The Slider sldZoom is used to set the zoom factor of the live video image. Add a sldZoom_Scroll function to the form's source code, to handle the change of the slider control. Because the range of the slider has been set from 1 to 30, the slider's value has to be divided by 10, before it is passed to LiveDisplayZoomFactor.

[VB.NET]
Private Sub sldZoom_Scroll(ByVal sender As System.Object, ByVal e As System.EventArgs) Handles sldZoom.Scroll
    If IcImagingControl1.LiveDisplayDefault = False Then
        IcImagingControl1.LiveDisplayZoomFactor = sldZoom.Value / 10
        lblZoomPercent.Text = Str(sldZoom.Value * 10) + "%"
    Else
        MsgBox("The zoom factor can only be set" + Chr(13) + _
               "if LiveDisplayDefault returns False!")
    End If
End Sub

[C#]
private void sldZoom_Scroll(object sender, EventArgs e)
{
    if (icImagingControl1.LiveDisplayDefault == false)
    {
        icImagingControl1.LiveDisplayZoomFactor = (float)sldZoom.Value / 10.0f;
        lblZoomPercent.Text = (sldZoom.Value * 10).ToString() + "%";
    }
    else
    {
        MessageBox.Show("The zoom factor can only be set" + "\n" + "if LiveDisplayDefault returns False!");
    }
}

Run the program. You can now start and stop the live image by clicking on the respective buttons. You can enable or disable the LiveDisplayDefault property and see, how IC Imaging Control reacts. You can also show and hide the scrollbars and zoom the live video.

If the scrollbar values are changed, the ScrollableControl.Scroll event is raised by Windows Forms.

Add a new label to the form and name it lblScrollPosition. This new label is used to display the current scroll position. Also add the ScrollableControl.Scroll event function to the form's source code. Enhance the function as follows:

[VB.NET]
Private Sub IcImagingControl1_Scroll(ByVal sender As System.Object, ByVal e As System.Windows.Forms.ScrollEventArgs) Handles IcImagingControl1.Scroll
    Dim p As Point = IcImagingControl1.AutoScrollPosition
    lblScrollPosition.Text = String.Format("{0}/{1}", p.X, p.Y)
End Sub

[C#]
private void icImagingControl1_Scroll( object sender, ScrollEventArgs e )
{
    Point p = icImagingControl1.AutoScrollPosition;
    lblScrollPosition.Text = string.Format( "{0}/{1}", p.X, p.Y );
}

Now, the current scroll position is displayed in the new label, each time, you scroll the live display with the scroll bars.

<< Programmer's Guide


Basic Use of VCD Properties

This chapter illustrates the basic functionality of the VCDProperties. It shows you how to retrieve interfaces which allow you to manipulate elements, such as the value or the automation state of a property.

Introduction

This sample uses the "Brightness" property to demonstrate how the properties are organized and how they are accessed. First, the VCDPropertyItem for "Brightness" is retrieved from the VCDPropertyItems collection. Then a switch and a range interface is retrieved from the respective elements of this VCDPropertyItem. The switch interface is used to turn the automation state of this property on and off. The range interface is used to manipulate the value of this property.

The source code for the VB.NET and C# versions of this sample program can be found in the directories samples\VB *\VCD Simple and samples\C# *\VCD Simple in your My Documents/IC Imaging Control 3.2 directory.

Creating the Project

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 2003 - 2008 chapter. Alternatively, run the program without selecting a device. In this case, the program shows the device selection dialog that ships with IC Imaging Control. If you close this dialog without selecting a device, the program displays an error message and terminates.

Now add a check box and a slider (or 'trackbar') to the form. Name the check box chkBrightnessAuto and the slider sldBrightness.

Retrieving a VCDPropertyItem

After a valid video capture device has been selected, the VCDPropertyItem for "Brightness" is retrieved:

[VB.NET]
Dim Brightness As TIS.Imaging.VCDPropertyItem
Brightness = IcImagingControl1.VCDPropertyItems.FindItem(TIS.Imaging.VCDIDs.VCDID_Brightness)

[C#]
TIS.Imaging.VCDPropertyItem Brightness = null;
Brightness = icImagingControl1.VCDPropertyItems.FindItem(TIS.Imaging.VCDIDs.VCDID_Brightness);

Just declare a variable of type VCDPropertyItem and use the VCDPropertyItems.FindItem method to assign the appropriate property. The property item that should be retrieved must be specified by its ID as mentioned above. In this case, it is VCDID_Brightness for the "Brightness" property item.

Retrieving Interfaces and Initialize the Controls

Properties consist of one or more elements like the value, automation state, one push operation and further parameters, if supported. To manipulate a property, interfaces are used. They can be retrieved from the elements of a property item. Declare 2 global variables that will hold the interfaces to the value and the automation state:

[VB.NET]
Dim BrightnessRange As TIS.Imaging.VCDRangeProperty
Dim BrightnessSwitch As TIS.Imaging.VCDSwitchProperty

[C#]
private TIS.Imaging.VCDRangeProperty BrightnessRange;
private TIS.Imaging.VCDSwitchProperty BrightnessSwitch;

The following code shows you how to actually retrieve a switch and a range interface and how to get their current states in order to initialize the associated user controls.

[VB.NET]
If Not Brightness Is Nothing Then
    ' Acquire interfaces to the range and switch interface for value and auto
    BrightnessRange = Brightness.Elements.FindInterface(TIS.Imaging.VCDIDs.VCDElement_Value + _
                                                        ":" + _
                                                        TIS.Imaging.VCDIDs.VCDInterface_Range)
    Try
        BrightnessSwitch = Brightness.Elements.FindInterface(TIS.Imaging.VCDIDs.VCDElement_Auto + _
                                                            ":" + _
                                                            TIS.Imaging.VCDIDs.VCDInterface_Switch)
    Catch ex As System.Exception
        MsgBox("Automation of brightness is not supported by the current device!")
    End Try
End If

[C#]
// Acquire interfaces to the range and switch interface for value and auto
BrightnessRange = (TIS.Imaging.VCDRangeProperty)Brightness.Elements.FindInterface(
                                                    TIS.Imaging.VCDIDs.VCDElement_Value + ":" +
                                                    TIS.Imaging.VCDIDs.VCDInterface_Range);
BrightnessSwitch = (TIS.Imaging.VCDSwitchProperty)Brightness.Elements.FindInterface(
                                                    TIS.Imaging.VCDIDs.VCDElement_Auto + ":" +
                                                    TIS.Imaging.VCDIDs.VCDInterface_Switch);
if (BrightnessSwitch == null)
{
    MessageBox.Show("Automation of brightness is not supported by the current device!");
}

The VCDPropertyElements.FindInterface method of the property item is used to retrieve an interface. As described above, a property item consists of one or more elements which provide one or more interfaces. Therefore, the element ID and the interface ID have to be specified when calling the VCDPropertyElements.FindInterface method.

Now that the we have the interfaces, the user controls can be initialized. The following code shows you how this is done:

[VB.NET]
' Initialize the slider with the current range and value of the
' BrightnessRange object.
sldBrightness.Enabled = True
sldBrightness.Minimum = BrightnessRange.RangeMin
sldBrightness.Maximum = BrightnessRange.RangeMax
sldBrightness.Value = BrightnessRange.Value

' Initialize the checkbox with the BrightnessSwitch object
If Not BrightnessSwitch Is Nothing Then
    chkBrightnessAuto.Enabled = True
    sldBrightness.Enabled = Not BrightnessSwitch.Switch
    chkBrightnessAuto.Checked = BrightnessSwitch.Switch
End If

[C#]
// Initialize the slider with the current range and value of the
// BrightnessRange object.
sldBrightness.Enabled = true;
sldBrightness.Minimum = BrightnessRange.RangeMin;
sldBrightness.Maximum = BrightnessRange.RangeMax;
sldBrightness.Value = BrightnessRange.Value;

// Initialize the checkbox with the BrightnessSwitch object
if (BrightnessSwitch != null)
{
    chkBrightnessAuto.Enabled = true;
    sldBrightness.Enabled = !BrightnessSwitch.Switch;
    chkBrightnessAuto.Checked = BrightnessSwitch.Switch;
}
icImagingControl1.LiveStart();

As the code above shows, the interface classes let you easily access the elements of a property item.

Manipulating the elements of a Property

In this final step, we want to show you how to use the interfaces to manipulate a property. Add a Click event for the check box and a Scroll event for the slider. The check box toggles the automation state of the "Brightness" property. The code looks as follows:

[VB.NET]
Private Sub chkBrightnessAuto_CheckedChanged(ByVal sender As System.Object, ByVal e As System.EventArgs) Handles chkBrightnessAuto.CheckedChanged
    BrightnessSwitch.Switch = chkBrightnessAuto.Checked
    sldBrightness.Enabled = Not chkBrightnessAuto.Checked
End Sub

[C#]
private void chkBrightnessAuto_CheckedChanged(object sender, EventArgs e)
{
    BrightnessSwitch.Switch = chkBrightnessAuto.Checked;
    sldBrightness.Enabled = !chkBrightnessAuto.Checked;
}

The code above just assigns the current state of the check box to the automation element of the "Brightness" property. Additionally, the slider will be disabled, if the automation state is on.

The code for the Scroll event of the slider is even simpler:

[VB.NET]
Private Sub sldBrightness_Scroll(ByVal sender As System.Object, ByVal e As System.EventArgs) Handles sldBrightness.Scroll
    BrightnessRange.Value = sldBrightness.Value
End Sub

[C#]
private void sldBrightness_Scroll(object sender, EventArgs e)
{
    BrightnessRange.Value = sldBrightness.Value;
}

Now you can run the program and manipulate the "Brightness" property, using the slider and the check box.

<< Programmer's Guide


List VCDProperties

This chapter shows you how to retrieve all properties of a video capture device using the new VCD property interface.

All properties that are retrieved from the video capture device are displayed in a TreeView. The TreeView was chosen, because it perfectly matches the organization of the properties, since they establish a tree structure. The root of the tree is the VCDPropertyItems collection. The collection contains all VCDPropertyItems that are provided by the current video capture device. Every VCDPropertyItem has one or more VCDPropertyElements, which have one or more VCDPropertyInterfaces that are used to access the property.

The source code for the VB.NET and C# versions of this sample program can be found in the directories samples\VB *\List VCDProperties and samples\C# *\List VCDProperties in your My Documents/IC Imaging Control 3.2 directory.

Setting up the Project

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 2003 - 2008 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 making a selection, the program displays an error message and terminate.

This sample uses some user controls. They can be found in the directory samples\VB71\common or samples\C#\common. Before you can use them, you have to add them to the project. Select Project from the menu and then choose Add Existing Item.... Now browse to the samples\VB71\common or samples\C#\common folder. Select the files Switch.vb, StringCombo.vb, RangeSlider.vb, PushButton.vb, ICControlBase.vb and AbsValSlider.vb. If you are using C#, the file extension is of course .cs instead of .vb. Now click on the little arrow next to the Open button and select Link File. Now you are ready to use the user controls.

Add 2 buttons to the form, name them btnSelectDevice and btnShowPage and label them Select Device and Show Property Page. They will be used to show the device settings resp. property page dialog provided by IC Imaging Control. Now add one instance of every user control to the form. Name them btnPush, cboMapStrings, chkSwitch, sldAbsVal and sldRange accordingly. Each of the user controls represents a special type of interface derived from VCDPropertyInterface.

Now add an image list and a tree view to the form. The image list will contain the graphical elements that are used to visualize the tree. Name the tree view Tree. In order to add graphical elements to the image list, click the ... button in the property window of the image list under Images. Now add the following images in the given order: item.bmp, value.bmp, auto.bmp, button.bmp, slider.bmp, switch.bmp and combo.bmp. All these bitmap files can be found in the directory of this sample. Change the Modifiers property of the image list to Friend (or internal if you use C#). Now, the image list can be added to the tree view. To do so, set the property ImageList of the tree view to the name of the image list. This will bind the image list to the tree view.

Adding Functionality

Add the Click events for the Select Device and Show Property Page buttons and insert the following code:

[VB.NET]
Private Sub btnSelectDevice_Click(ByVal sender As System.Object, ByVal e As System.EventArgs) Handles btnSelectDevice.Click
    ' The device settings dialog needs the live mode to be stopped.
    If IcImagingControl1.LiveVideoRunning Then
        IcImagingControl1.LiveStop()
    End If

    ' Show the device settings dialog
    IcImagingControl1.ShowDeviceSettingsDialog()

    ' If no device was selected, exit the program.
    If Not IcImagingControl1.DeviceValid Then
        MessageBox.Show("No device was selected.")
        Close()
        Exit Sub
    End If

    ListAllPropertyItems()

    ' Start live mode
    IcImagingControl1.LiveStart()

    ' Query all properties of the video capture device and list
    ' them in a tree control.
    QueryVCDProperties()
End Sub

[C#]
private void btnSelectDevice_Click(object sender, EventArgs e)
{
    // The device settings dialog needs the live mode to be stopped
    if (icImagingControl1.LiveVideoRunning)
    {
        icImagingControl1.LiveStop();
    }

    // Show the device settings dialog
    icImagingControl1.ShowDeviceSettingsDialog();

    // If no device was selected, exit
    if (!icImagingControl1.DeviceValid)
    {
        MessageBox.Show("No device was selected.");
        this.Close();
        return;
    }

    // Start live mode
    icImagingControl1.LiveStart();

    // (re-)initialize the tree view
    QueryVCDProperties();
}

[VB.NET]
Private Sub btnShowPage_Click(ByVal sender As System.Object, ByVal e As System.EventArgs) Handles btnShowPage.Click
    If IcImagingControl1.DeviceValid Then
        IcImagingControl1.ShowPropertyDialog()
    End If
End Sub

[C#]
private void btnShowPage_Click(object sender, EventArgs e)
{
    if (icImagingControl1.DeviceValid)
    {
        // Show the built-in properties dialog
        icImagingControl1.ShowPropertyDialog();
    }
}

Now add a Form_Load event and insert the code below:

[VB.NET]
Private Sub Form1_Load(ByVal sender As System.Object, ByVal e As System.EventArgs) Handles MyBase.Load
    If IcImagingControl1.DeviceValid = False Then
        ' Show the device settings dialog.
        btnSelectDevice_Click(Me, Nothing)
    End If

    If IcImagingControl1.DeviceValid = True Then

        ' Start live mode.
        IcImagingControl1.LiveStart()

        ' Query all properties of the video capture device and list
        ' them in a tree control.
        QueryVCDProperties()
    End If
End Sub

[C#]
private void Form1_Load(object sender, EventArgs e)
{
    if (!icImagingControl1.DeviceValid)
    {
        // Show the device settings dialog.
        btnSelectDevice_Click(btnSelectDevice, new System.EventArgs());
    }

    if (icImagingControl1.DeviceValid)
    {
        ListAllPropertyItems();
        // Start live mode.
        icImagingControl1.LiveStart();

        // Query all properties of the video capture device and list
        // them in a tree control.
        QueryVCDProperties();
    }
}

As you can see in the code above, the btnSelectDevice_Click and the Form_Load event both call the procedures ListAllPropertyItems and QueryVCDProperties. QueryVCDProperties fills the tree view with the properties of the current video capture device. Additionally, ListAllPropertyItems prints the tree structure of those properties to the debug output window. The debug output shows you the pure organization of the VCDProperties without taking care of other aspects like controls. Let's have a look at the code for the procedure ListAllPropertyItems:

[VB.NET]
Private Sub ListAllPropertyItems()
    Dim PropertyItem As TIS.Imaging.VCDPropertyItem
    Dim PropertyElement As TIS.Imaging.VCDPropertyElement
    Dim PropertyInterFace As TIS.Imaging.VCDPropertyInterface ' Default interface type.

    ' Interface types for the different property interfaces.
    Dim Range As TIS.Imaging.VCDRangeProperty
    Dim Switch As TIS.Imaging.VCDSwitchProperty
    Dim AbsoluteValue As TIS.Imaging.VCDAbsoluteValueProperty
    Dim MapString As TIS.Imaging.VCDMapStringsProperty
    Dim Button As TIS.Imaging.VCDButtonProperty

    ' Get all property items
    For Each PropertyItem In IcImagingControl1.VCDPropertyItems
        System.Diagnostics.Debug.WriteLine(PropertyItem.Name)

        ' Get all property elements of the current property item.
        For Each PropertyElement In PropertyItem.Elements
            System.Diagnostics.Debug.WriteLine("    Element : " + PropertyElement.Name)

            ' Get all interfaces of the current property element.
            For Each PropertyInterFace In PropertyElement
                System.Diagnostics.Debug.Write("        Interface ")

                Try

                    ' Cast the current interface into the apropriate type to access
                    ' the special interface properties.
                    Select Case PropertyInterFace.InterfaceID
                        Case VCDIDs.VCDInterface_AbsoluteValue
                            AbsoluteValue = PropertyInterFace
                            System.Diagnostics.Debug.WriteLine("Absolut Value : " + AbsoluteValue.Value.ToString)

                        Case VCDIDs.VCDInterface_MapStrings
                            MapString = PropertyInterFace
                            System.Diagnostics.Debug.WriteLine("Mapstring : " + MapString.String)

                        Case VCDIDs.VCDInterface_Switch
                            Switch = PropertyInterFace
                            System.Diagnostics.Debug.WriteLine("Switch : " + Switch.Switch.ToString)

                        Case VCDIDs.VCDInterface_Button
                            Button = PropertyInterFace
                            System.Diagnostics.Debug.WriteLine("Button")

                        Case VCDIDs.VCDInterface_Range
                            Range = PropertyInterFace
                            System.Diagnostics.Debug.WriteLine("Range : " + Range.Value.ToString)
                    End Select
                Catch ex As System.Exception
                    System.Diagnostics.Debug.WriteLine("<error>")
                End Try
            Next
        Next
    Next
End Sub

[C#]
private void ListAllPropertyItems()
{
    // Interface types for the different property interfaces.
    TIS.Imaging.VCDRangeProperty Range;
    TIS.Imaging.VCDSwitchProperty Switch;
    TIS.Imaging.VCDAbsoluteValueProperty AbsoluteValue;
    TIS.Imaging.VCDMapStringsProperty MapString;
    TIS.Imaging.VCDButtonProperty Button;

    // Get all property items
    foreach (TIS.Imaging.VCDPropertyItem PropertyItem in icImagingControl1.VCDPropertyItems)
    {
        System.Diagnostics.Debug.WriteLine(PropertyItem.Name);

        // Get all property elements of the current property item.
        foreach (TIS.Imaging.VCDPropertyElement PropertyElement in PropertyItem.Elements)
        {
            System.Diagnostics.Debug.WriteLine("    Element : " + PropertyElement.Name);

            // Get all interfaces of the current property element.
            foreach (TIS.Imaging.VCDPropertyInterface PropertyInterFace in PropertyElement)
            {
                System.Diagnostics.Debug.Write("        Interface ");

                try
                {

                    // Cast the current interface into the appropriate type to access
                    // the special interface properties.

                    if (PropertyInterFace.InterfaceID == TIS.Imaging.VCDIDs.VCDInterface_AbsoluteValue)
                    {
                        AbsoluteValue = (TIS.Imaging.VCDAbsoluteValueProperty)PropertyInterFace;
                        System.Diagnostics.Debug.Write("Absolut Value : ");
                        System.Diagnostics.Debug.WriteLine(AbsoluteValue.Value.ToString());
                    }
                    else if ( PropertyInterFace.InterfaceID == TIS.Imaging.VCDIDs.VCDInterface_MapStrings )
                    {
                            MapString = (TIS.Imaging.VCDMapStringsProperty)PropertyInterFace;
                            System.Diagnostics.Debug.Write("Mapstring : ");
                            System.Diagnostics.Debug.WriteLine(MapString.String);
                    }
                     else if ( PropertyInterFace.InterfaceID == TIS.Imaging.VCDIDs.VCDInterface_Switch )
                    {
                            Switch = (TIS.Imaging.VCDSwitchProperty)PropertyInterFace;
                            System.Diagnostics.Debug.Write("Switch : ");
                            System.Diagnostics.Debug.WriteLine(Switch.Switch.ToString());
                     }
                     else if (PropertyInterFace.InterfaceID == TIS.Imaging.VCDIDs.VCDInterface_Button)
                     {
                         Button = (TIS.Imaging.VCDButtonProperty)PropertyInterFace;
                         System.Diagnostics.Debug.WriteLine("Button");
                     }
                     else if (PropertyInterFace.InterfaceID == TIS.Imaging.VCDIDs.VCDInterface_Range)
                     {
                         Range = (TIS.Imaging.VCDRangeProperty)PropertyInterFace;
                         System.Diagnostics.Debug.Write("Range : ");
                         System.Diagnostics.Debug.WriteLine(Range.Value.ToString());
                     }

                }
                catch (Exception ex)
                {
                    System.Diagnostics.Debug.WriteLine("<error>");
                }
            }
        }
    }
}

The three nested For Each loops in the code above reflects the tree structure of the VCDProperties. The first loop covers all available VCDPropertyItems and prints their names to the debug output. For each item, the second loop prints out all available VCDPropertyElements. The third loop prints out all types of interfaces that the element provides. Please note that the interfaces are sorted according to their extend of detail. The most detailed one is the "AbsoluteValue" interface, followed by the "MapStrings" interface. "Switch" and "Button" are detailed interfaces providing simple functionality: toggle On/Off, trigger. The "Range" interface is the most generic one, but does not provide a meaning for the values that represents. For example the "Brightness" range may be from 0 to 255. There is no way to tell, whether 0 or 255 is the maximum brightness value.

Now let's have a look at the QueryVCDProperties procedure. This procedure fills the tree view with appropriate values. The code for this procedure looks as follows:

[VB.NET]
Private Sub QueryVCDProperties()
    ' Erase the complete tree.
    Tree.Nodes.Clear()

    ' Create the root node.
    Dim root As New TreeNode("VCDPropertyItems")
    root.Tag = Nothing
    Tree.Nodes.Add(root)

    ' Query the VCDPropertyItems and fill the tree.
    QueryVCDPropertyItems(root, IcImagingControl1.VCDPropertyItems)

    ' Make sure the tree is expanded
    root.ExpandAll()
End Sub

[C#]
private void QueryVCDProperties()
{
    // Erase the complete tree.
    Tree.Nodes.Clear();

    // Fill the tree.
    TreeNode root = new TreeNode("VCDPropertyItems");
    Tree.Nodes.Add(root);

    QueryVCDPropertyItems(root, icImagingControl1.VCDPropertyItems);

    root.ExpandAll();
    Tree.SelectedNode = root;
}

The procedure above clears the tree view and creates a new root node. The root node is labeled VCDPropertyItems. Then the procedure QueryVCDPropertyItems inserts all available property items. This procedure looks as follows:

[VB.NET]
Private Sub QueryVCDPropertyItems(ByVal ParentNode As TreeNode, ByVal PropertyItems As TIS.Imaging.VCDPropertyItems)
    ' Iterate through all VCDPropertyItems and insert them into the tree control.
    For Each item As TIS.Imaging.VCDPropertyItem In PropertyItems
        ' Create a new tree node for the property item.
        ' The item identifier string is stored in the tag
        ' property of the tree node.
        Dim newNode As New TreeNode(item.Name, 0, 0)
        newNode.Tag = Nothing

        ParentNode.Nodes.Add(newNode)

        ' Now query the elements of the property item.
        QueryVCDPropertyElements(newNode, item)

    Next
End Sub

[C#]
private void QueryVCDPropertyItems(TreeNode pp, TIS.Imaging.VCDPropertyItems props)
{
    // Iterate through all VCDPropertyItems and insert them into the tree
    foreach (TIS.Imaging.VCDPropertyItem item in props)
    {
        // Create a new tree node for the item
        TreeNode newNode = new TreeNode(item.Name, 0, 0);
        //                newNode.Tag = item.ItemID;
        newNode.Tag = null;
        pp.Nodes.Add(newNode);

        QueryVCDPropertyElements(newNode, item);
    }
}

QueryVCDPropertyItems iterates through all available property items. For every item, it creates a new node. All of these nodes are direct children of the root node. The name of the VCDPropertyItem (e.g. "Brightness", "Gain" or "Exposure") is assigned to the Text property of the node. Nothing (or null if you use C#) is assigned to the tag property of the node. Then, QueryVCDPropertyElements is called for the new node. QueryVCDPropertyElements looks as follows:

[VB.NET]
Private Sub QueryVCDPropertyElements(ByVal ParentNode As TreeNode, ByVal PropertyItem As TIS.Imaging.VCDPropertyItem)
    ' generate a display name
    Dim name As String
    Dim Image As Integer
    Dim Element As TIS.Imaging.VCDPropertyElement

    For Each Element In PropertyItem.Elements
        ' Create a name for the property element.
        Select Case Element.ElementID
            Case VCDIDs.VCDElement_Value
                name = "VCDElement_Value"
                Image = 1
            Case VCDIDs.VCDElement_Auto
                name = "VCDElement_Auto"
                Image = 2
            Case VCDIDs.VCDElement_OnePush
                name = "VCDElement_OnePush"
                Image = 3
            Case VCDIDs.VCDElement_WhiteBalanceRed
                name = "VCDElement_WhiteBalanceRed"
                Image = 4
            Case VCDIDs.VCDElement_WhiteBalanceBlue
                name = "VCDElement_WhiteBalanceBlue"
                Image = 4
            Case Else
                name = "Other Element ID"
                Image = 4
        End Select

        ' Create a tree node for the element and insert it into the tree control.
        ' The item and element identifier strings are stored in the tag property
        ' of the tree node.
        Dim newNode As New TreeNode(name + ": " + Element.Name, Image, Image)
        newNode.Tag = Nothing

        ParentNode.Nodes.Add(newNode)

        ' Now query the interfaces of the property element.
        QueryVCDPropertyInterface(newNode, Element)

    Next

End Sub

[C#]
private void QueryVCDPropertyElements(TreeNode pp, TIS.Imaging.VCDPropertyItem item)
{
    TreeNode newNode = null;

    foreach (TIS.Imaging.VCDPropertyElement elem in item.Elements)
    {
        newNode = new TreeNode(elem.ElementID+": '" + elem.Name + "'", 1, 1);

        if ( elem.ElementID == TIS.Imaging.VCDIDs.VCDElement_Value )
            newNode = new TreeNode("VCDElement_Value: '" + elem.Name + "'", 1, 1);
        else if ( elem.ElementID == TIS.Imaging.VCDIDs.VCDElement_Auto )
            newNode = new TreeNode("VCDElement_Auto: '" + elem.Name + "'", 2, 2);
        else if ( elem.ElementID == TIS.Imaging.VCDIDs.VCDElement_OnePush )
            newNode = new TreeNode("VCDElement_OnePush: '" + elem.Name + "'", 3, 3);
        else if ( elem.ElementID == TIS.Imaging.VCDIDs.VCDElement_WhiteBalanceRed )
            newNode = new TreeNode("VCDElement_WhiteBalanceRed: '" + elem.Name + "'", 4, 4);
        else if ( elem.ElementID == TIS.Imaging.VCDIDs.VCDElement_WhiteBalanceBlue )
            newNode = new TreeNode("VCDElement_WhiteBalanceBlue: '" + elem.Name + "'", 4, 4);
        else
            newNode = new TreeNode("Other Element ID: '" + elem.Name + "'", 4, 4);

        newNode.Tag = null;
        pp.Nodes.Add(newNode);

        // Insert all interfaces
        QueryVCDPropertyInterface(newNode, elem);
    }
}

QueryVCDPropertyElements iterates through all available elements. For every element, it creates a new node. All of these nodes are children of the node, which represents the VCDPropertyItem to which these VCDPropertyElements belong. The Select block (or switch block in C#) determines the appropriate graphical tree element for the node and sets its base name, depending on the type of the element. The name of the VCDPropertyElement (e.g. "Value", "Auto" or "Enable") is added to the base name and then assigned to the Text property of the node. Nothing (or null, if you use C#) is assigned to the tag property of the node. Then, QueryVCDPropertyInterface is called for the new node. QueryVCDPropertyInterface looks as follows:

[VB.NET]
Private Sub QueryVCDPropertyInterface(ByVal ParentNode As TreeNode, ByVal PropertyElement As TIS.Imaging.VCDPropertyElement)
    Dim Name As String
    Dim image As Integer
    Dim Itf As TIS.Imaging.VCDPropertyInterface

    ' Iterate through all VCDPropertyInterfaces of the passed VCDPropertyElement
    ' and insert them into the tree control.
    For Each Itf In PropertyElement
        ' Create an appropriate interface name.
        Select Case Itf.InterfaceID
            Case VCDIDs.VCDInterface_AbsoluteValue
                Name = "AbsoluteValue"
                image = 4
            Case VCDIDs.VCDInterface_MapStrings
                Name = "MapStrings"
                image = 6
            Case VCDIDs.VCDInterface_Range
                Name = "Range"
                image = 4
            Case VCDIDs.VCDInterface_Switch
                Name = "Switch"
                image = 5
            Case VCDIDs.VCDInterface_Button
                Name = "Button"
                image = 3
        End Select

        ' Insert the node.
        ' The item, element and interface identifier strings are stored in the tag property
        ' of the tree node.
        Dim newNode As New TreeNode(Name, image, image)
        newNode.Tag = Itf.Parent.Parent.ItemID + ":" + Itf.Parent.ElementID + ":" + Itf.InterfaceID

        ParentNode.Nodes.Add(newNode)
    Next
End Sub

[C#]
private void QueryVCDPropertyInterface(TreeNode pp, TIS.Imaging.VCDPropertyElement elem)
{
    TreeNode newNode = null;

    foreach (TIS.Imaging.VCDPropertyInterface itf in elem)
    {
        newNode = new TreeNode(itf.InterfaceID, 4, 4);

        if ( itf.InterfaceID ==  TIS.Imaging.VCDIDs.VCDInterface_AbsoluteValue )
            newNode = new TreeNode("AbsoluteValue", 4, 4);
        else if( itf.InterfaceID == TIS.Imaging.VCDIDs.VCDInterface_MapStrings )
            newNode = new TreeNode("MapStrings", 6, 6);
        else if( itf.InterfaceID == TIS.Imaging.VCDIDs.VCDInterface_Range )
            newNode = new TreeNode("Range", 4, 4);
        else if( itf.InterfaceID == TIS.Imaging.VCDIDs.VCDInterface_Switch )
            newNode = new TreeNode("Switch", 5, 5);
        else if( itf.InterfaceID == TIS.Imaging.VCDIDs.VCDInterface_Button )
            newNode = new TreeNode("Button", 3, 3);

        // The Tag property holds the interface at the node.
        newNode.Tag = itf.Parent.Parent.ItemID + ":" + itf.Parent.ElementID + ":" + itf.InterfaceID;
        pp.Nodes.Add(newNode);
    }
}

QueryVCDPropertyInterface iterates through all available interfaces of an element. For every interface, it creates a new node. All of these nodes are children of the node which represents the VCDPropertyElement to which these VCDPropertyInterface belong. The Select block (or switch block in C#) determines the appropriate graphical tree element for the node and sets its name, depending on the type of the element. The name is then assigned to the Text property of the node. The interface path that consists of an itemID, an elementID and an interfaceID is assigned to the tag property of the node. The interface node makes up a leaf of the tree.

Accessing and Manipulating a VCDProperty

Now that the tree is built up, we want to access the properties. To do this, add an AfterSelect event for the tree view and insert the following code:

[VB.NET]
Private Sub Tree_AfterSelect(ByVal sender As System.Object, ByVal e As System.Windows.Forms.TreeViewEventArgs) Handles Tree.AfterSelect

    ' If the Tag property is empty, no leaf node was selected
    If Tree.SelectedNode.Tag Is Nothing Then Exit Sub

    If Not RangeCtrl Is Nothing Then RangeCtrl.Dispose()
    If Not SwitchCtrl Is Nothing Then SwitchCtrl.Dispose()
    If Not MapStringsCtrl Is Nothing Then MapStringsCtrl.Dispose()
    If Not ButtonCtrl Is Nothing Then ButtonCtrl.Dispose()
    If Not AbsValCtrl Is Nothing Then AbsValCtrl.Dispose()

    Dim itfPath As String = Tree.SelectedNode.Tag
    Dim itf As TIS.Imaging.VCDPropertyInterface = IcImagingControl1.VCDPropertyItems.FindInterface(itfPath)

    If Not itf Is Nothing Then

        itf.Update()

        ' Show the control group matching the type of the selected interface
        ' and initialize it
        Select Case itf.InterfaceID
            Case VCDIDs.VCDInterface_AbsoluteValue
                ShowAbsoluteValueControl(itf)

            Case VCDIDs.VCDInterface_MapStrings
                ShowComboBoxControl(itf)

            Case VCDIDs.VCDInterface_Range
                ShowRangeControl(itf)

            Case VCDIDs.VCDInterface_Switch
                ShowSwitchControl(itf)

            Case VCDIDs.VCDInterface_Button
                ShowButtonControl(itf)

        End Select

    End If

End Sub

[C#]
private void treeView1_AfterSelect(object sender, TreeViewEventArgs e)
{
    // If the Tag property is empty, no leaf node was selected.
    if (Tree.SelectedNode.Tag == null)
    {
        return;
    }

    // Hide all control groups
    if (RangeCtrl != null) RangeCtrl.Dispose();
    if (SwitchCtrl != null) SwitchCtrl.Dispose();
    if (MapStringsCtrl != null) MapStringsCtrl.Dispose();
    if (ButtonCtrl != null) ButtonCtrl.Dispose();
    if (AbsValCtrl != null) AbsValCtrl.Dispose();

    string itfPath = Tree.SelectedNode.Tag.ToString();
    TIS.Imaging.VCDPropertyInterface itf = icImagingControl1.VCDPropertyItems.FindInterface(itfPath);

    if (itf != null)
    {
        itf.Update();
        // Show the control group matching the type of the selected interface
        // and initialize it.
        if ( itf.InterfaceID == TIS.Imaging.VCDIDs.VCDInterface_AbsoluteValue )
             ShowAbsoluteValueControl(itf);
        else if( itf.InterfaceID == TIS.Imaging.VCDIDs.VCDInterface_MapStrings)
            ShowComboBoxControl(itf);
        else if( itf.InterfaceID == TIS.Imaging.VCDIDs.VCDInterface_Range)
            ShowRangeControl(itf);
        else if( itf.InterfaceID == TIS.Imaging.VCDIDs.VCDInterface_Switch)
            ShowSwitchControl(itf);
        else if( itf.InterfaceID == TIS.Imaging.VCDIDs.VCDInterface_Button)
            ShowButtonControl(itf);
    }
}

Now it becomes clear, why the tags of the interface nodes store the interface path. If you click an interface node, the appropriate control should appear on the form, so that you can manipulate the setting of the property. To get the correct interface, the method FindInterface is used. FindInterface needs the interface path (or GUID) as a parameter. The tag of an interface node represents this interface path (or GUID). The Select block (or switch in C#) maps the appropriate user control to the desired interface and calls the respective "Show%%" procedure. These procedures set the "Visible" property of the user control to True, so that it can be used to manipulate the setting of the specified property. The ShowAbsoluteValueControl procedure for example is implemented as follows:

[VB.NET]
Private Sub ShowAbsoluteValueControl(ByVal itf As TIS.Imaging.VCDPropertyInterface)
    AbsValCtrl = New AbsValSlider()
    CtrlFrame.Controls.Add(AbsValCtrl)
    AbsValCtrl.SetBounds(20, 20, 500, 27)
    AbsValCtrl.AssignItf(itf)
    CtrlFrame.Text = itf.Parent.Parent.Name + ": " + itf.Parent.Name ' Property item name
End Sub

[C#]
private void ShowAbsoluteValueControl(TIS.Imaging.VCDPropertyInterface itf)
{
    TIS.Imaging.VCDAbsoluteValueProperty AbsValItf = (TIS.Imaging.VCDAbsoluteValueProperty)itf;
    AbsValCtrl = new AbsValSlider();
    CtrlFrame.Controls.Add(AbsValCtrl);
    AbsValCtrl.SetBounds(20, 20, 500, 27);
    AbsValCtrl.AssignItf(AbsValItf);
    CtrlFrame.Text = "Absolute Value";
}

The appropriate procedures for the other user controls are implemented in the same way, except the last line of code of the VB.NET sample, which is left out.

<< Programmer's Guide


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

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 2003 - 2008 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#]
private 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.VCDElement_WhiteBalanceBlue) Then
    WhiteBalanceTrackBar.Enabled = False
Else
    WhiteBalanceTrackBar.Enabled = True
    WhiteBalanceTrackBar.Minimum = VCDProp.RangeMin(VCDIDs.VCDElement_WhiteBalanceBlue)
    WhiteBalanceTrackBar.Maximum = VCDProp.RangeMax(VCDIDs.VCDElement_WhiteBalanceBlue)
    WhiteBalanceTrackBar.Value = VCDProp.RangeValue(VCDIDs.VCDElement_WhiteBalanceBlue)
    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.VCDElement_WhiteBalanceBlue))
{
    WhiteBalanceTrackBar.Enabled = false;
}
else
{
    WhiteBalanceTrackBar.Enabled = true;
    WhiteBalanceTrackBar.Minimum = VCDProp.RangeMin(VCDIDs.VCDElement_WhiteBalanceBlue);
    WhiteBalanceTrackBar.Maximum = VCDProp.RangeMax(VCDIDs.VCDElement_WhiteBalanceBlue);
    WhiteBalanceTrackBar.Value = VCDProp.RangeValue[VCDIDs.VCDElement_WhiteBalanceBlue];
    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#]
private 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 Form1_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 Form1_Load(object sender, 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, 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, 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, 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, EventArgs e)
{
    VCDProp.OnePush(VCDIDs.VCDID_WhiteBalance);
}

<< Programmer's Guide


Capturing a Video File

This chapter shows you how to save a video stream as a compressed video file. In contrast to the Capturing an AVI File example, the MediaStreamSink is used to allow several video file formats to be recorded.

The source code for the VB.NET and C# versions of this sample program can be found in the directories samples\VB *\Capturing a Video File and samples\C# *\Capturing a Video File in your My Documents/IC Imaging Control 3.2 directory.

Setting up the Project

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 FirstSteps 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 selecting a device, the program will display an error message and terminate.

Now, add 3 buttons to the form and label them Start Live, Stop Live and Capture Video. Name the buttons cmdStartLive, cmdStopLive and cmdCaptureVideo respectively.

Add calls to IC Imaging Control's LiveStart and LiveStop methods:

[VB.NET]
Private Sub btnStartLive_Click(ByVal sender As System.Object, ByVal e As System.EventArgs) Handles btnStartLive.Click
    IcImagingControl1.LiveStart()
End Sub

[C#]
private void btnStartLive_Click(object sender, EventArgs e)
{
    icImagingControl1.LiveStart();
}

[VB.NET]
Private Sub btnStopLive_Click(ByVal sender As System.Object, ByVal e As System.EventArgs) Handles btnStopLive.Click
    IcImagingControl1.LiveStop()
End Sub

[C#]
private void btnStopLive_Click(object sender, EventArgs e)
{
    icImagingControl1.LiveStop();
}

Run the program. You can now start and stop the live image by clicking on the respective buttons. This does not yet create a video file, but is required to create a preview for the live video stream. This is usually required to set up the camera before actually starting to record.

The Video Recording Dialog

Now add another form to your project. Name it frmSaveVideo. Add a combo box for the available media stream containers (video file types) and a combo box for the available video codecs. Insert a text box for the video filename, and buttons to start and stop video capture. (You may want to load the sample project instead of creating the form manually).

In the FormLoad event, the combo boxes are filled with the names of all media stream containers and video codecs installed on your computer.

[VB.NET]
Private Sub SaveVideoForm_Load(ByVal sender As System.Object, ByVal e As System.EventArgs) Handles MyBase.Load
    cboMediaStreamContainer.DataSource = m_ImagingControl.MediaStreamContainers
    cboVideoCodec.DataSource = m_ImagingControl.AviCompressors

    txtFileName.Text = System.IO.Path.ChangeExtension("video.avi", CurrentMediaStreamContainer.PreferredFileExtension)

    btnStopCapture.Enabled = False
End Sub

[C#]
private void SaveVideoForm_Load(object sender, EventArgs e)
{
    cboMediaStreamContainer.DataSource = m_ImagingControl.MediaStreamContainers;

    cboVideoCodec.DataSource = m_ImagingControl.AviCompressors;

    txtFileName.Text = System.IO.Path.ChangeExtension("video.avi", CurrentMediaStreamContainer.PreferredFileExtension);

    btnStopCapture.Enabled = false;
}

The Click event of the "Start Capture" button initializes the dialog's m_Sink variable with the currently selected media stream container, codec and filename. The recording process is started by calling LiveStart:

[VB.NET]
Private Sub btnStartCapture_Click(ByVal sender As System.Object, ByVal e As System.EventArgs) Handles btnStartCapture.Click
    m_Sink = New TIS.Imaging.MediaStreamSink
    m_Sink.StreamContainer = CurrentMediaStreamContainer
    m_Sink.Codec = CurrentVideoCodec
    m_Sink.Filename = txtFileName.Text
    m_Sink.SinkModeRunning = Not chkPause.Checked

    m_OldLiveMode = m_ImagingControl.LiveVideoRunning
    m_OldSink = m_ImagingControl.Sink

    m_ImagingControl.LiveStop()

    m_ImagingControl.Sink = m_Sink

    m_ImagingControl.LiveStart()

    btnStartCapture.Enabled = False
    btnStopCapture.Enabled = True
    btnClose.Enabled = False
End Sub

[C#]
private void btnStartCapture_Click(object sender, EventArgs e)
{
    m_Sink = new TIS.Imaging.MediaStreamSink();
    m_Sink.StreamContainer = CurrentMediaStreamContainer;
    m_Sink.Codec = CurrentVideoCodec;
    m_Sink.Filename = txtFileName.Text;
    m_Sink.SinkModeRunning = !chkPause.Checked;

    m_OldLiveMode = m_ImagingControl.LiveVideoRunning;
    m_OldSink = m_ImagingControl.Sink;

    m_ImagingControl.LiveStop();

    m_ImagingControl.Sink = m_Sink;

    m_ImagingControl.LiveStart();

    btnStartCapture.Enabled = false;
    btnStopCapture.Enabled = true;
    btnClose.Enabled = false;
}

The Pause button is a check box with a graphical style. It is used to set and reset the MediaStreamSink.SinkModeRunning property. If the SinkModeRunning property is set to False, video capture is paused. This means, that only the sink path of the image stream is paused. The live video is still displayed, but the video is not saved to the video file. If the SinkModeRunning property is set to True, IC Imaging Control immediately continues video capture. A previously started video file will be continued.

[VB.NET]
Private Sub chkPause_CheckedChanged(ByVal sender As System.Object, ByVal e As System.EventArgs) Handles chkPause.CheckedChanged
    If Not m_Sink Is Nothing Then
        m_Sink.SinkModeRunning = Not chkPause.Checked
    End If
End Sub

[C#]
private void chkPause_CheckedChanged(object sender, EventArgs e)
{
    if (m_Sink != null)
    {
        m_Sink.SinkModeRunning = !chkPause.Checked;
    }
}

The video capture can be started even if the SinkModeRunning property is set to False. In this case, the image stream will be initialized and started and the live video is displayed. But the images are not saved to the video file until the SinkModeRunning property is set to True. This has the advantage that video capturing can be immediately started, paused and restarted on an event.

Finished. You can now run the program, select a codec and create a video file. Note that compressing a video stream is a highly CPU intensive operation and not all codecs will be able to work at full image resolution and full frame rate.

<< Programmer's Guide


Filter Inspector

This example demonstrates how to use frame filters to perform basic image processing.

It shows, how to:

  • Enumerate the available frame filters.
  • Create frame filter instances.
  • Set a frame filter to do image processing on live video.

The source code for the VB.NET and C# versions of this sample program can be found in the directories samples\VB *\Filter Inspector and samples\C# *\Filter Inspector in your My Documents/IC Imaging Control 3.2 directory.

Using the Example

On the left side of the dialog box, there are two list boxes. The upper list box shows all filter modules that were found by IC Imaging Control. When you select one of the filter modules in this list, the lower list box displays the frame filters that can be loaded from the selected module.

When you click on one of the frame filters in the second list box, the filter is inserted in the Device Path. The live video displayed on the right side of the dialog box should now visualize the work of the frame filter.

You can click the Dialog... button to display the selected filter's property dialog.

If you select a new filter, the old filter will be removed and the new one will be used instead.

To see the untransformed image data from the video capture device, click the Remove button.

Initialization

In the Form_Load event, ICImagingControl is initialized. If no device has been selected, ShowDeviceSettingsDialog is used to display a device selection dialog box. An important part here is to disable graphic overlay completely by setting ICImagingControl.OverlayBitmapPosition to PathPositions.None, thus avoiding interference with the possible color formats of the frame filters.

[VB.NET]
If Not IcImagingControl1.DeviceValid Then
    IcImagingControl1.ShowDeviceSettingsDialog()
    If Not IcImagingControl1.DeviceValid Then
        Close()
        Return
    End If
End If

' Disable all overlays, so that they do not influence the
' color format of the image stream.
IcImagingControl1.OverlayBitmapPosition = TIS.Imaging.PathPositions.None

' Start live mode.
IcImagingControl1.LiveStart()

[C#]
if (!icImagingControl1.DeviceValid)
{
    icImagingControl1.ShowDeviceSettingsDialog();

    if (!icImagingControl1.DeviceValid)
    {
        Close();
        return;
    }
}

// Disable all overlays, so that they do not influence the
// color format of the image stream.
icImagingControl1.OverlayBitmapPosition = TIS.Imaging.PathPositions.None;

// Start live mode.
icImagingControl1.LiveStart();

Enumerating Available Frame Filters

To obtain a list of available frame filters, use ICImagingControl.FrameFilterInfos, which returns a collection of FrameFilterInfo objects.

Now we want to fill a list box with the names of the files in which the filters have been found. To do that, we look at each filter and add its module name to the list box, while filling ModulePaths with the module paths of the filters. The module names are not added, if the module path is already in the collection:

[VB.NET]
' Use a collection to save the full paths to the filter modules.
modulePathCollection = New System.Collections.Specialized.StringCollection

' For each filter info:
' - Check if the filter's path is already in the module paths collection
' - If not, add the module name to the filter module list box.
For Each ffi As TIS.Imaging.FrameFilterInfo In IcImagingControl1.FrameFilterInfos
    If modulePathCollection.IndexOf(ffi.ModulePath) < 0 Then
        lstFrameFilterModules.Items.Add(ffi.ModuleName)
        modulePathCollection.Add(ffi.ModulePath)
    End If
Next

[C#]
// Use a collection to save the full paths to the filter modules.
modulePathCollection = new System.Collections.Specialized.StringCollection();

// For each filter info:
// - Check if the filter's path is already in the module paths collection
// - If not, add the module name to the filter module list box.
foreach (TIS.Imaging.FrameFilterInfo ffi in icImagingControl1.FrameFilterInfos)
{
    if (modulePathCollection.IndexOf(ffi.ModulePath) < 0)
    {
        lstFrameFilterModules.Items.Add(ffi.ModuleName);
        modulePathCollection.Add(ffi.ModulePath);
    }
}

In the event handler, which is called when the user selects a filter module name from the list box, a second list box is filled with the names of the filters in that module:

[VB.NET]
Private Sub lstFrameFilterModules_SelectedIndexChanged(ByVal sender As System.Object, ByVal e As System.EventArgs) Handles lstFrameFilterModules.SelectedIndexChanged
    ' Get the full path to the selected module from the ModulePaths collection.
    Dim selectedModulePath As String = modulePathCollection(lstFrameFilterModules.SelectedIndex)

    lstFrameFilters.Items.Clear()
    For Each ffi As TIS.Imaging.FrameFilterInfo In IcImagingControl1.FrameFilterInfos
        If ffi.ModulePath = selectedModulePath Then
            lstFrameFilters.Items.Add(ffi)
        End If
    Next
End Sub

[C#]
private void lstFrameFilterModules_SelectedIndexChanged(object sender, EventArgs e)
{
    // Get the full path to the selected module from the ModulePaths collection.
    string selectedModulePath = modulePathCollection[lstFrameFilterModules.SelectedIndex];

    lstFrameFilters.Items.Clear();
    foreach (TIS.Imaging.FrameFilterInfo ffi in icImagingControl1.FrameFilterInfos)
    {
        if (ffi.ModulePath == selectedModulePath)
        {
            lstFrameFilters.Items.Add(ffi);
        }
    }
}

The loop fills a list box with all the frame filters that were loaded from the specified module. The index of the added filters in the original filter list (that was retrieved from ICImagingControl.FrameFilterInfos ) are stored in the list box's item data by setting ListBox.ItemData, thus allowing the filter info to be found when an end user clicks the item.

Creating Frame Filter Instances

When the user selects a filter from the filter list, the item data of the selected item is read, using ListBox.ItemData. Because we previously stored the filter's index in the list of available filters in the item data, we can use this number now to select the FrameFilterInfo in ICImagingControl.FrameFilterInfos:

[VB.NET]
' Get the selected FrameFilterInfo object
Dim ffi As TIS.Imaging.FrameFilterInfo = CType(lstFrameFilters.SelectedItem, TIS.Imaging.FrameFilterInfo)

If Not ffi Is Nothing Then
    ' Create the new FrameFilter instance.
    Dim newFrameFilter As TIS.Imaging.FrameFilter = IcImagingControl1.FrameFilterCreate(ffi)

[C#]
// Get the selected FrameFilterInfo object
TIS.Imaging.FrameFilterInfo ffi = (TIS.Imaging.FrameFilterInfo)lstFrameFilters.SelectedItem;

if (ffi != null)
{
    // Create the new FrameFilter instance.
    TIS.Imaging.FrameFilter newFrameFilter = icImagingControl1.FrameFilterCreate(ffi);

The frame filter instance is created by calling ICImagingControl.FrameFilterCreate with the FrameFilterInfo object as its parameter.

Set the Frame Filter

To activate the frame filter, it has to be registered at the ICImagingControl object. The ICImagingControl.DeviceFrameFilters collection is cleared and the new filter is inserted. Device frame filters are used to transform the image data that comes from the video capture device.

[VB.NET]
' If live mode is active, stop.
Dim wasLive As Boolean = IcImagingControl1.LiveVideoRunning
If wasLive Then
    IcImagingControl1.LiveStop()
End If

' Set the new frame filter.
IcImagingControl1.DeviceFrameFilters.Clear()
IcImagingControl1.DeviceFrameFilters.Add(newFrameFilter)

' If live mode was active, restart.
If wasLive Then
    IcImagingControl1.LiveStart()
End If

[C#]
// If live mode is active, stop.
bool wasLive = icImagingControl1.LiveVideoRunning;
if (wasLive)
{
    icImagingControl1.LiveStop();
}

// Set the new frame filter.
icImagingControl1.DeviceFrameFilters.Clear();
icImagingControl1.DeviceFrameFilters.Add(newFrameFilter);

// If live mode was active, restart.
if (wasLive)
{
    icImagingControl1.LiveStart();
}

Live mode has to be stopped in order to set a frame filter.

<< Programmer's Guide


Writing a Frame Filter: Binarization

This example demonstrates how to create frame filters to apply binarization to live video.

As frame filters need perform quickly and efficiently, only languages that can handle plain pointers (like Managed C++ or C# in unsafe blocks) can be used to implement them. This example only uses C#.

It shows, how to:

  • Derive a class from FrameFilterImpl and implement the pure virtual methods.
  • Set the frame filter to affect only the live display.
  • Alter frame filter parameters.

The example is located in the samples\C# *\Binarization directory in your My Documents/IC Imaging Control 3.2 directory.

Implementing a Frame Filter

All frame filter implementations have to be derived from FrameFilterImpl:

[C#]
public class BinarizationFilter : FrameFilterImpl

Two member variables contain the current settings of the frame filter. m_bEnabled controls whether the filter applies the binarization at all. m_threshold controls the value that determines whether a pixel is transformed to the maximum gray value or zero.

[C#]
private bool m_bEnabled = false;
private int m_threshold = 127;

To create a working frame filter, the methods GetSupportedInputTypes, GetTransformOutputTypes and Transform have to be implemented.

In the GetSupportedInputTypes method, an ArrayList is filled with FrameType objects that describe the frame types that our frame filter accepts as inputs. To keep it simple, we are only going to accept the 8-bit formats RGB8 and Y800. When the video format of the video capture device differs from this, the image data is automatically converted before it is presented to the frame filter.

[C#]
public override void GetSupportedInputTypes(System.Collections.ArrayList frameTypes)
{
    // This filter works for 8-bit-gray images only
    frameTypes.Add(new TIS.Imaging.FrameType(TIS.Imaging.MediaSubtypes.Y800));
    frameTypes.Add(new TIS.Imaging.FrameType(TIS.Imaging.MediaSubtypes.RGB8));
}

The GetTransformOutputTypes method fills the ArrayList outTypes with frame types that the filter can produce from a specified input frame type. Because the binarization filter does not change the frame type or size, we just insert the input type into the list:

[C#]
public override bool GetTransformOutputTypes(FrameType inType, System.Collections.ArrayList outTypes)
{
    // We don't change the image type, output = input
    outTypes.Add(inType);

    return true;
}

The Transform method is called for every frame. It is responsible to do the binarization according to the current settings.

Because the Transform method runs in a different thread from the user interface, the access to the member variables m_bEnabled and m_threshold has to be protected from parallel adjustments by the application program.

First, FrameFilterImpl.BeginParamTransfer is called. Internally, this method enters a critical section. When a user of the frame filter wants to set parameters, s/he has to call FrameFilter::BeginParamTransfer, which tries to acquire the same lock. FrameFilterImpl.EndParamTransfer leaves the critical section. The values of the member variables are copied to local stack variables so that they remain constant for the whole transformation.

The binarization itself is a simple operation: Compare each pixel's gray value to the threshold. If the gray value is greater than the threshold, set the pixel to the maximum gray value, otherwise set it to zero.

[C#]
public override bool Transform(IFrame src, IFrame dest)
{
    unsafe
    {
        // Check whether the destination frame is available
        if (dest.Ptr == null) return false;

        // Copy the member variables to the function's stack, to protect them from being
        // overwritten by parallel calls to setThreshold() etc.
        //
        // beginParamTransfer/endParamTransfer makes sure that the values from various
        // member variables are consistent, because the user of this filter must enclose
        // writing parameter access into beginParamTransfer/endParamTransfer, too.

        BeginParameterTransfer();
        int threshold = m_threshold;
        bool enabled = m_bEnabled;
        EndParameterTransfer();

        byte* pIn = src.Ptr;
        byte* pOut = dest.Ptr;

        // Check whether binarization is enabled
        if (enabled)
        {
            // For each byte in the input buffer, check whether it is greater or
            // equal to the threshold.
            int bufferSize = src.FrameType.BufferSize;
            while (bufferSize-- > 0)
            {
                if (*pIn++ >= threshold)
                {
                    *pOut++ = 255;
                }
                else
                {
                    *pOut++ = 0;
                }
            }
        }
        else
        {
            // Binarization is disabled: Copy the image data without modifying it.
            dest.CopyFrom(src);
        }
    }

    return true;
}

Using the Frame Filter

First of all, we create an instance of BinarizationFilter and pass it to ICImagingControl.FrameFilterCreate.

There is a special overload of that method that takes a FrameFilterImpl object and returns a FrameFilter object that can be used in ICImagingControl.DeviceFrameFilters, ICImagingControl.DisplayFrameFilters and the sink types.

We save a reference to the FrameFilter object in a member variable of the dialog class so that we can access the filter's parameters later.

When the ICImagingControl object is initialized, ICImagingControl.DisplayFrameFilters.Add is called to set our frame filter:

[C#]
// Disable overlay bitmap
icImagingControl1.OverlayBitmapPosition = TIS.Imaging.PathPositions.None;

// Create an instance of the frame filter implementation
BinarizationFilter binFilterImpl = new BinarizationFilter();

// Create a FrameFilter object wrapping the implementation
m_FrameFilter = icImagingControl1.FrameFilterCreate(binFilterImpl);

// Set the FrameFilter as display frame filter.
icImagingControl1.DisplayFrameFilters.Add(m_FrameFilter);

// Start live mode
icImagingControl1.LiveStart();

When live mode is started, all images are binarized just before they are displayed by IC Imaging Control.

Implementing the Parameter Interface

The frame filter works with the code above, but the host application can not alter the filter's behavior. To let the application access the filter's settings, the filter can define a set of parameters that can be accessed using the generic functions of FrameFilter, such as SetBoolParameter or GetIntParameter.

To create boolean a parameter to switch the filter on and off, call FrameFilterImpl.AddBoolParam in your filter's constructor. To add a parameter to control the threshold value, call AddIntParam.

[C#]
public BinarizationFilter()
{
    AddBoolParam("enable", new SetBoolParam(setEnable), new GetBoolParam(getEnable));
    AddIntParam("threshold", new SetIntParam(setThreshold), new GetIntParam(getThreshold));
}

Those two methods both take three parameters. The first is the name of the parameter, that has to be specified when altering the parameter, such as a method like FrameFilter.SetIntParameter. The second and third parameters are delegates of the type SetBoolParam and GetBoolParameter or SetIntParameter and GetIntParameter. These delegates connect the parameter with the member methods of your filter implementation:

[C#]
void setEnable(bool bEnable)
{
    m_bEnabled = bEnable;
}

[C#]
bool getEnable()
{
    return m_bEnabled;
}

[C#]
void setThreshold(int threshold)
{
    m_threshold = threshold;
}

[C#]
int getThreshold()
{
    return m_threshold;
}

Accessing Frame Filter Parameters

In the event handler for the check box that enables or disables the binarization, FrameFilter.SetBoolParameter is called.

All calls to methods modifying filter parameters have to be enclosed by FrameFilter.BeginParameterTransfer and FrameFilter.EndParameterTransfer.

[C#]
private void chkEnable_CheckedChanged(object sender, EventArgs e)
{
    m_FrameFilter.BeginParameterTransfer();

    m_FrameFilter.SetBoolParameter("enable", chkEnable.Checked);
    sldThreshold.Enabled = m_FrameFilter.GetBoolParameter("enable");
    lblThreshold.Enabled = m_FrameFilter.GetBoolParameter("enable");

    m_FrameFilter.EndParameterTransfer();
}

In the event handler for the threshold slider, FrameFilter.SetIntParameter is called.

This call also has to be enclosed by FrameFilter.BeginParameterTransfer and FrameFilter.EndParameterTransfer.

[C#]
private void sldThreshold_Scroll(object sender, EventArgs e)
{
    m_FrameFilter.BeginParameterTransfer();

    m_FrameFilter.SetIntParameter("threshold", sldThreshold.Value);
    lblThreshold.Text = m_FrameFilter.GetIntParameter("threshold").ToString();

    m_FrameFilter.EndParameterTransfer();
}

<< Programmer's Guide


Technical Articles

Complete list of all technical articles.

Concepts and Components

This chapter describes the components that make up IC Imaging Control and the basic concepts behind the library.

Frame Filters

With frame filters, a versatile and powerful way to manipulate image data is introduced. Besides other features, frame filters can be used to change or convert the video format of the image stream, implement image processing and control which frames are processed.

Debayering

Certain color cameras output image data in raw format, which is called Bayer format. This chapter discusses what is involved to transform this raw data into a real color format that can be displayed as a color image.

VCDProperties

VCD Properties provide a generic, hardware independent and extendable way to control the settings of a video capture device.

Distributing your Applications

This section describes how to distribute an application that uses IC Imaging Control® and install it on another computer.

DCAMprop DLL

The DCAM Prop DLL that provided access to special DCAM properties in version 1.41 is not needed anymore, because these special properties can now be accessed and manipulated using the new VCD properties. This document describes alternatives for all functions and procedures of the DCAM Prop DLL.

<< IC Imaging Control .NET Component User's Guide


Concepts and Components

This chapter describes the components that make up IC Imaging Control and the basic concepts behind the library.

Introduction

IC Imaging Control is an API that covers all aspects of DirectShow that are related to managing, controlling and accessing imaging devices and image data. It simplifies the usage of DirectShow by maintaining hardware independence. The abstraction implemented by IC Imaging Control addresses all programmers who are familiar with frame grabbers. In other words: IC Imaging Control lets DirectShow look like a frame grabber.

Basic Components

Because the idea behind IC Imaging Control is to build something similar to a frame grabber, the main component IC Imaging Control provides methods to control the inputs, video formats, and the grabbing process which are typical for frame grabber APIs. In contrast to most frame grabber APIs, IC Imaging Control provides:

  • A sink concept for creating image stream files ( MediaStreamSink, MediaStreamContainer ) including software compression ( AviCompressor )
  • A sink concept for handling image buffers ( FrameHandlerSink ) with ring buffer management ( ImageBuffers, ImageBuffer ) including buffer locking and image data access through callbacks ( ImageAvailable event).
  • Advanced display capabilities including scrolling and zooming that can be controlled using properties and methods of the main component ICImagingControl.

The image data is generated by the video capture device as consecutive frames that build an image stream running from the device to the sink. If the display is activated, the image stream is split, feeding the sink and the display. In this case, the image stream is a graph that looks like a "Y" and consists of the following segments:

  • Device Path: Segment between the device and the split point
  • Display Path: Segment between the split point and the display
  • Sink Path: Segment between the split point and the sink

While the figure above illustrates the flow of image data, the next figure shows the relationship between the image stream and the classes.

Advanced Components

IC Imaging Control provides generic access to device properties, multiple overlays and filter chains at different locations of the image stream:

  • Generic device properties: Although DirectShow allows device independent code to be written, by using the two defined sets of properties VideoProcAmp and CameraControl, this concept suffers from serious limitations. On the one hand, a lot of video capture devices provide more properties, than defined by DirectShow. On the other hand, the values that may be specified for a property do not have a meaning. With VCDProperties, IC Imaging Control provides a totally generic and extendable way to handle unknown properties and add a meaning to property values.
  • Multiple Overlays: The class OverlayBitmap implements an overlay that can be rendered on the image stream at three locations: device path, display path and sink path. Methods for drawing text and graphical elements, such as rectangles and lines, as well as callbacks for generating frame based overlays are provided.
  • Filter Chains: IC Imaging Control allows filters or filter chains to be inserted in the image stream at three locations: device path, display path and sink path. Filters are called frame filters and are used to change or convert the video format of the image stream, implement image processing and control which frames are processed. For details on frame filters, please refer to the section Frame Filters.

Performance

As described above, IC Imaging Control provides very powerful components to manipulate and control the acquisition and display of image streams. It is obvious that this functionality requires a certain overhead for internal management and processing. This may lead to the conclusion that IC Imaging Control is not suitable for high speed image processing application. This is absolutely not the case, as all features that make it easy to build complex applications with IC Imaging Control may be switched off. For applications that require as much CPU time for image processing as possible, IC Imaging Control may be configured in a way that the overhead to process the image stream is comparable to a low level frame grabber or FireWire library. In order to reduce the internal overhead to a minimum, you have to:

  • Switch off the display: this will remove the display path completely from the image stream.
  • Prevent automatic color space conversion: by specifying the same video format for the device and the sink.
  • Switching off all overlays.
  • Do not use the ring buffer: by inserting one frame filter in the sink path that will implement the image processing or interface a third party image processing library instead of sending frames to the sink.
  • Do not insert additional frame filters in the device path or in the sink path.

Doing so guarantees that the image data is not modified or copied by IC Imaging Control nor DirectShow. The figure below shows the layout of the image stream for this configuration.

<< Technical Articles


Frame Filters

With frame filters, a versatile and powerful way to manipulate image data is introduced. Besides other features, frame filters can be used to change or convert the video format of the image stream, implement image processing and control which frames are processed.

Introduction

In contrast to other DirectShow libraries, the frame filters of IC Imaging Control are not DirectShow filters. But they are executed in the context of a DirectShow thread that processes the image stream. This saves the programmer the hassle of creating a DirectShow filter module, registering it and defining interfaces for the parameters. Frame filters are implemented in C++ as part of a filter module. They are loaded on demand by the OCX from the module and may be inserted at three locations in the image stream. Frame filters are basically far easier to implement and to use as DirectShow filters by providing the same performance with regard to image processing. In VB 6, there is no way to neither implement a frame filter nor a frame filter module. VB.NET and C# allow frame filters to be implemented as part of a program. In order to create a frame filter module, C++ has to be used.

Filter Categories

Frame filters open the door to a vast number of new IC Imaging Control based applications. In order to show you what is possible with this new concept, we discuss categories of tasks that can be implemented with frames filters. For some of these tasks, frame filters are shipped with IC Imaging Control.

Gate:
Gate filters drop unwanted frames based on image analysis or other information like the frame count or time stamps.
Color Space Conversion:
All kinds of transformations from one color format to another fall in to this category. In addition, the reduction of the pixel depth, e.g. extracting the 8 most significant bits out of a 10 or 12 bit monochrome format is regarded as a color space conversion. The reduction of the pixel depth is used to display a 10 or 12 bit monochrome image. A good example for a color space conversion is the DeBayer Filter contained in stdfilters.ftf. It converts color raw data in Bayer format to RGB.
ROI:
Filters in this category allow a Region Of Interest to be cropped out of an image stream. The ROI Filter that is contained in stdfilters.ftf implements this functionality.
Rotation:
This category includes rotatation and flipping. The Rotate Flip Filter that is contained in stdfilters.ftf provides rotation by 90°, 180° and 270°, aswell as flipping on the horizontal and vertical axis. There is a filter in the DemoFilter.ftf that provides rotation by any angle, but this filter is a demo implementation and very slow.
Scaling:
Scaling up and down may be necessary to match a predefined display size or to save disk space for surveillance applications.
Sink:
Sink filters are consumers. They process the image stream in their Transform method completely and do not send frames to the IC Imaging Control sink. If you want to use professional high performance codecs, you would inplement a sink filter in order to interface the codec's API. This approach is necessary because most professional codecs come as a DLL instead of a DirectShow codec. These codecs provides functionality to compress image data and write it to a file at the same time, which makes a sink obsolete. Of course, you could use the ImageBuffers of a FrameHandlerSink to access the image data and send it to the codec's API. In this case, the image data would have been copied by the sink to the ImageBuffers which is not the case, if the codec is interfaced using a frame filter. In other words, the sink filter approach saves one copy operation per frame, which can increase the performance significantly, especially if large frames are processed.
Extraction:
Extraction filters take specific frames out of the image stream and apply processing on them, e.g. saving them to disk as image files. The image stream itself remains unchanged and is sent further to the sink. Such a filter allows specific images to be saved uncompressed, while a MediaStreamSink generates a compressed video file.
Image Processing:
All image processing functions that produce one image as output can be implemented easily by a frame filter. For functions that produce more than one image, special concepts have to be developed. One possible concept would be to write the output images one after the other into the resulting image. If data other than images is generated by the function (e.g. data generated by a blob analysis), the application could read out this data by using filter parameters.
Buffer Format Conversion:
Most image processing libraries have a special internal image buffer format. Frame filters can be used to convert image buffers of the image stream to such a special image buffer format. Doing so, the elements in the ring buffer of the FrameHandlerSink contain data in the special format. Therefore, the data of these buffers may be passed directly to the according image processing library. This saves one copy step and, therefore, increases the preformance of the system.

Using Existing Frame Filters

As described earlier, frame filters can be created directly in an application or loaded from a filter module. IC Imaging Control provides some filters in the module stdfilters.ftf. In order to obtain a list of the frame filters in all currently available filter modules, examine the ICImagingControl.FrameFilterInfos collection. With the ICImagingControl.FrameFilterPath property, an additional path for filter modules may be specified. A call to ICImagingControl.FrameFilterCreate creates an instance of a filter that was selected from the list of available filters. Now that we have a frame filter instance, we can insert it at three different locations in the image stream:

  • Behind the device: DeviceFrameFilters
  • In front of the display: DisplayFrameFilters
  • In front of the sink: MediaStreamSink.FrameFilters, FrameHandlerSink.FrameFilters

Please note that the same instance of a frame filter should not be used at more than one place in the image stream because its internal state may get inconsistent, especially if FrameFilterImpl.NotifyStart and FrameFilterImpl.NotifyStop are used. If it is necessary to insert the same filter at more than one location in the image stream, different instances of the frame filter should be used.

The internal data of a frame filter can be accessed through the parameter interface. With the methods FrameFilter.SetIntParameter, FrameFilter.GetIntParameter, FrameFilter.SetBoolParameter, FrameFilter.GetBoolParameter, FrameFilter.SetStringParameter, FrameFilter.GetStringParameter, FrameFilter.SetFloatParameter, FrameFilter.GetFloatParameter, the following basic data types can be read from or written to the filter: bool, long, float and string. A block of binary data can be exchanged with a frame filter with the FrameFilter.SetDataParameter and FrameFilter.GetDataParameter methods. Since the transform method of a filter is executed within a DirectShow thread, it is very important to synchronize external and internal access to the filter's data. Therefore, it is very important that a sequence of calls to the four methods mentioned above is preceded by a call to FrameFilter.BeginParameterTransfer and is followed by a call to FrameFilter.EndParameterTransfer:

If a frame filter is used by generic applications, such as the Filter Inspector, a dialog should be implemented that allows the parameters to be altered interactively. A frame filter indicates that it provides a parameter dialog by returning true in the method FrameFilter.HasDialog. The dialog should be displayed when the method FrameFilter.ShowDialog is called.

To serialize the settings of a frame filter, use the FrameFilter.FilterData property. To save the settings directly to a file, use the FrameFilter.SaveFilterData and FrameFilter.LoadFilterData methods.

Creating a Frame Filter

For Visual Studio .NET, there is a wizard that allows a frame filter to be created with just a few mouse clicks. For details, please refer to Project Wizards for Visual Studio. If you want to understand what the wizard is doing, a detailed step by step description can be found in the section: Writing a Frame Filter: Binarization.

<< Technical Articles


Debayering

Certain color cameras output image data in raw format, which is called Bayer format. This chapter discusses what is involved to transform this raw data into a real color format that can be displayed as a color image.

Introduction

IC Imaging Control provides built-in functionality to debayer raw image data. There are 3 methods ( DeBayerActive, DeBayerStartPattern and DeBayerMode ) that allow the debayering process to be controlled. The prerequisite to use this buit-in functionality is that the camera provides BY8 video formats that identify raw data in Bayer format. Some cameras provide only grayscale video formats (e.g. Y800, RGB8 etc.) but output color raw data when these formats are selected. This is possible because the color raw data in Bayer format consists of only one value per pixel (for detailed information about color raw data, please refer to the glossary of our website www.theimagingsource.com and search for Bayer camera ). In this case the debayering has to be done explicitly by using the DeBayer frame filter that can be loaded from the StdFilters.ftf module.

Automatic Debayering

If a BY8 video format is selected, IC Imaging Control applies debayering to the image data. The method DeBayerActive can be used to determine whether automatic debayering is active. For details on debayering modes and parameters, please refer to DeBayerStartPattern and DeBayerMode. In order to switch off automatic debayering for the sink, you have to assign a bayer format, e.g. eBY8 or MediaSubtypes.BY8 to the sink ( MemoryCurrentGrabberColorformat, FrameHandlerSink.FrameTypes ). The only way to switch off automatic debayering for the display is to insert a frame filter in the display path that accepts only a bayer format at the input and outputs a monochrome format. All this filter has to do is to copy the data from the input to the output without any changes. In the filter module StdFilter.ftf, there is a filter Bayer To Y800 that does exactly this. The following code fragment shows how to display raw color data in Bayer format:

Explicit Debayering

In oder to apply debayering explicitly to the image stream, you have to load the DeBayer frame filter from the StdFilter.ftf module, insert it in to the desired segment of the image stream and setup the filters parameters to match the Bayer pattern and the desired algorithm:

For details on frame filters please refer to Frame Filters.

<< Technical Articles


VCDProperties

VCD Properties provide a generic, hardware independent and extendable way to control the settings of a video capture device.

Introduction

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:

  • Some video capture devices provide more properties than the ones defined by DirectShow.
  • If the values of some properties such as "exposure" are mapped to a "long", the meaning of the value gets lost. With regard to "exposure" the question is for example: which value corresponds to 1/20.000 sec? There is an approach in DirectShow to overcome this problem with negative values. The value -2, for example, means 2 to the power of -2, which is 1/4 seconds. These negative values are called "physical values" because they have a physical meaning (in this case in terms of seconds). There is one problem with this approach, it suffers from inaccuracy. There is no way to specify 1/3 second as an exposure time in "physical values". There is the same problem with the properties "iris" and "zoom".

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.

Basic concepts

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.

Finding Property objects

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.

Finding Interfaces

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:

[VB.NET]
' Declare an absolute value interface
Dim AbsValItf As ICImagingControl.VCDAbsoluteValueProperty

' Retrieve an absolute value interface for exposure
AbsValItf = ICImagingControl1.VCDPropertyItems.FindInterface( VCDHelpers.VCDIDs.VCDID_Exposure + ":" + _
                                                                    VCDHelpers.VCDIDs.VCDElement_Value + ":" + _
                                                                 VCDHelpers.VCDIDs.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

[C#]
// Declare an absolute value interface
private ICImagingControl.VCDAbsoluteValueProperty AbsValItf;

// Retrieve an absolute value interface for exposure
AbsValItf = (ICImagingControl.VCDAbsoluteValueProperty)IcImagingControl1.VCDPropertyItems.FindInterface(
                                                              VCDHelpers.VCDIDs.VCDID_Exposure + ":" +
                                                                    VCDHelpers.VCDIDs.VCDElement_Value + ":" +
                                                                 VCDHelpers.VCDIDs.VCDInterface_AbsoluteValue );

if( AbsValItf != null )
{
    // Interface successfully retrieved ...
}
else
{
    // There is no absolute value interface for the value element
    // of the exposure property item.
}

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:

[VB.NET]
' Declare a map strings interface
Dim MapStringsItf As ICImagingControl.VCDMapStringsProperty

' Retrieve a map strings interface for exposure
MapStringsItf = ICImagingControl1.VCDPropertyItems.FindInterface( VCDHelpers.VCDIDs.VCDID_Exposure + ":" + _
                                                                    VCDHelpers.VCDIDs.VCDElement_Value + ":" + _
                                                                 VCDHelpers.VCDIDs.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

[C#]
// Declare a map strings interface
private ICImagingControl.VCDMapStringsProperty MapStringsItf;

// Retrieve a map strings interface for exposure
MapStringsItf = (ICImagingControl.VCDAbsoluteValueProperty)IcImagingControl1.VCDPropertyItems.FindInterface(
                                                              VCDHelpers.VCDIDs.VCDID_Exposure + ":" +
                                                                    VCDHelpers.VCDIDs.VCDElement_Value + ":" +
                                                                 VCDHelpers.VCDIDs.VCDInterface_MapStrings );

if( MapStringsItf != null )
{
    // Interface successfully retrieved ...
}
else
{
    // There is no map strings interface for the value element
    // of the exposure property item.
}

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:

[VB.NET]
' Declare a range interface
Dim RangeItf As ICImagingControl.VCDRangeProperty

' Retrieve a range interface for exposure
RangeItf = ICImagingControl1.VCDPropertyItems.FindInterface( VCDHelpers.VCDIDs.VCDID_Exposure + ":" + _
                                                                    VCDHelpers.VCDIDs.VCDElement_Value + ":" + _
                                                                 VCDHelpers.VCDIDs.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

[C#]
// Declare a range interface
private ICImagingControl.VCDRangeProperty RangeItf;

// Retrieve a range interface for exposure
RangeItf = (ICImagingControl.VCDAbsoluteValueProperty)IcImagingControl1.VCDPropertyItems.FindInterface(
                                                              VCDHelpers.VCDIDs.VCDID_Exposure + ":" +
                                                                    VCDHelpers.VCDIDs.VCDElement_Value + ":" +
                                                                 VCDHelpers.VCDIDs.VCDInterface_Range );

if( RangeItf != null )
{
    // Interface successfully retrieved ...
}
else
{
    // There is no range interface for the value element
    // of the exposure property item.
}

Using Interfaces

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:

  • Available: Indicates whether this interface is currently available. For example, interfaces for the trigger property item may not be available while the image stream is running.
  • ReadOnly: Indicates whether a value may be assigned to the Value of the interface.
  • Default: Is the default value.
  • Value: The Value of the interface.

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:

[VB.NET]
' 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

[C#]
// AbsValItf is a valid absolute value interface for exposure
if( AbsValItf.Available )
{
    // Set the current value to the average
    AbsValItf.Value = ( AbsValItf.RangeMin + AbsValItf.RangeMax ) / 2;
}

If the map strings interface could be retrieved, the code for accessing the interface looks as follows:

[VB.NET]
' 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

[C#]
// MapStringsItf is a valid map string interface for exposure
if( MapStringsItf.Available )
{
    // Set the current value to the average
    MapStringsItf.Value = ( MapStringsItf.RangeMin + MapStringsItf.RangeMax ) / 2;
}

If only the range interface could be retrieved, the code for accessing the interface looks as follows:

[VB.NET]
' 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

[C#]
// RangeItf is a valid range interface for exposure
if( RangeItf.Available )
{
    // Set the current value to the average
    RangeItf.Value = ( RangeItf.RangeMin + RangeItf.RangeMax ) / 2;
}

Serialization of property values

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.

<< Technical Articles


Distributing your Applications

This section describes how to distribute an application that uses IC Imaging Control® and install it on another computer.

Distributing your Applications using the Publish Wizard of Visual Studio 2008

This section describes how to distribute your applications using the publish wizard of Visual Studio 2008.

Distributing an Application using a Setup Toolkit

<< Technical Articles


Distributing your Applications using the Publish Wizard of Visual Studio 2008

This section describes how to distribute your applications using the publish wizard of Visual Studio 2008.

Run the Publish Wizard

Right-Click your project in the Solution Explorer, and select Publish... from the context menu. Follow the steps of the wizard and finish it.

Visual Studio will now publish your application to the selected location. However, the published files are not able to work an a production machine yet. The following steps show how to modify your project settings so that the published application can work on computers without IC Imaging Control or Visual Studio installed.

Add required IC Imaging Control files to the project

Select Project -> Add Existing Item from the main menu. Navigate to the installation folder of IC Imaging Control in C:\Program Files\Common Files\IC Imaging Control 3.2\bin\v2.0.50727\x86 and select the following files for a 32 bit application:

  • TIS_UDSHL09_vc9.dll
  • TIS_DShowLib09.dll

If a 64 bit application was built, then navigate to C:\Program Files\Common Files\IC Imaging Control 3.2\bin\v2.0.50727\x64 and select following files:

  • TIS_UDSHL09_vc9_x64.dll
  • TIS_DShowLib09_x64.dll

Use the Add As Link command to add these files as links into your project.

Mark all these links in your Solution Explorer, right-click them and select Properties. In the Properties window, set Build Action to Content. This makes sure the publish wizard puts the files next to the program's executable.

Adjust publishing options

Right-Click your project in the Solution Explorer, and select Properties from the context menu. Activate the Publish tab.

Click the Application Files... button to show the Applications Files dialog. In the dialog, set the Publish Status of TIS.Imaging.ICImagingControl31.dll to Include. Press OK to close the dialog.

Click the Prerequisites... button to show the Prerequisites dialog. IC Imaging Control 3.2 requires that you check .NET Framwork 2.0 (x86) and Visual C++ Runtime Libraries (x86). If your application requires features from a higher .NET framework, you have to check the higher framework's entry, e.g. .NET Framework 3.5.

Testing the publishing process

Right-Click your project in the Solution Explorer, and select Properties from the context menu. Activate the Publish tab.

Press the Publish Now button.

Visual Studio should now compile your application and copy the published setup to the location you earlier specified in the Publish Wizard.

Use a computer without IC Imaging Control or Visual Studio installed and navigate to the publishing location. The setup should install all missing preriquisites and start the application.

<< Distributing your Applications


Distributing an Application using a Setup Toolkit

Setup Toolkit

If a setup toolkit is used, the lists below show all the files necessary for IC Imaging Control to operate properly. All of the required DLL files have to be installed into the application directory.

The exact files required depend on the target platform of the application (32bit or 64bit) and the used .NET Framework.

Required files if an application is built using .NET Framework 2.0, 3.0 and 3.5 (32 bit)

  • TIS.Imaging.ICImagingControl32.dll
  • TIS_UDSHL09_vc9.dll
  • TIS_DShowLib09.dll
  • Microsoft®Visual C++® 2008 Redistributable Package (x86)

The DLL files can be found in the C:\Program Files\Common Files\IC Imaging Control 3.2\bin\v2.0.50727\x86 directory on the development machine. Please keep in mind that the names "Program Files" and "Common Files" may be localized to the language of the operating system. On 64 bit Windows, the path name is Program Files (x86).

The Microsoft® Visual C++® 2008 Redistributable Package setup has to be executed on the target computer. The installer does not have to be copied itself. It can be downloaded from the Microsoft® Website.

Required files if an application is built using .NET Framework 2.0, 3.0 and 3.5 (64 bit)

  • TIS.Imaging.ICImagingControl32.dll
  • TIS_UDSHL09_vc9_x64.dll
  • TIS_DShowLib09_x64.dll
  • Microsoft®Visual C++® 2008 Redistributable Package (x64)

The DLL files can be found in the C:\Program Files\Common Files\IC Imaging Control 3.2\bin\v2.0.50727\x64 directory on the development machine. Please keep in mind that the names "Program Files" and "Common Files" may be localized to the language of the operating system.

The Microsoft® Visual C++® 2008 Redistributable Package setup has to be executed on the target computer. The installer does not have to be copied itself. It can be downloaded from the Microsoft® Website.

Required files if an application is built using .NET Framework 4.0 (32 bit)

  • TIS.Imaging.ICImagingControl32.dll
  • TIS_UDSHL09_vc10.dll
  • TIS_DShowLib09.dll
  • msvcp100.dll
  • msvcr100.dll

The TIS*-DLL files can be found in the C:\Program Files\Common Files\IC Imaging Control 3.2\bin\v4.0.30319\x86 directory on the development machine. Please keep in mind that the names "Program Files" and "Common Files" may be localized to the language of the operating system. On 64 bit Windows, the path name is Program Files (x86).

If Visual C++® 2010 is installed on the development machine, the msvc*-DLL files are located in the C:\Program Files (x86)\Microsoft® Visual Studio 10.0\VC\redist\x86\Microsoft®.VC100.CRT directory. Otherwise, the Microsoft® Visual C++® 2010 Redistributable Package (x86) can be downloaded from Microsoft®'s website, in order to use their setup to install those DLLs.

Required files if an application is built using .NET Framework 4.0 (64 bit)

  • TIS.Imaging.ICImagingControl32.dll
  • TIS_UDSHL09_vc10_x64.dll
  • TIS_DShowLib09_x64.dll
  • msvcp100.dll
  • msvcr100.dll

The TIS*-DLL files can be found in the C:\Program Files\Common Files\IC Imaging Control 3.2\bin\v4.0.30319\x64 directory on the development machine. Please keep in mind that the names "Program Files" and "Common Files" may be localized to the language of the operating system.

If Visual C++® 2010 is installed on the development machine, the msvc*-DLL files can be found in the C:\Program Files (x86)\Microsoft® Visual Studio 10.0\VC\redist\x64\Microsoft®.VC100.CRT directory. Otherwise, the Microsoft® Visual C++® 2010 Redistributable Package (x64) can be downloaded from Microsoft®'s website, in order to use their setup to install those DLLs.

Remarks

The component TIS.Imaging.ICImagingControl32.dll has the same name in the 32 and the 64 bit versions. Thus a setup toolkit should install either 32 or 64 bit, but not both of them in parallel.

<< Distributing your Applications


DCAMprop DLL

The DCAM Prop DLL that provided access to special DCAM properties in version 1.41 is not needed anymore, because these special properties can now be accessed and manipulated using the new VCD properties. This document describes alternatives for all functions and procedures of the DCAM Prop DLL.

IsPhysicalUnits%%%, SetPhysicalUnits%%%

If physical units are supported for the property %%%, the appropriate VCD property provides a map strings interface ( VCDMapStringsProperty ). It might be necessary to activate physical units support for a specific device explicitly by a special driver setup. Please refer to the device documentation for details. There is a new interface called absolute value ( VCDAbsoluteValueProperty ). Like the physical units of the map strings interface, it provides a meaning for the values. In addition, it provides a high resolution. Therefore, you should use the absolute values interface, if supported.

IsWhiteBalance%%%, GetWhiteBalace%%%, SetWhiteBalance%%%

Basically there are two ways to handle these functions. The first one is to use the VCDSimpleProperty class. The usage of this class is described in the Using the VCD Simple Property Class chapter of the user's guide. The helper class offers methods to set and retrieve property values and to check the availability of a certain property. Every method of this helper class needs an ID that specifies the property for which the method is to be called. The IDs for "WhiteBalanceBlue" and "WhiteBalanceRed" are VCDElement_WhiteBalanceBlue and VCDElement_WhiteBalanceRed. For detailed information, please refer to the VCDSimpleProperty class.

The second way is to directly use the new VCDProperties. The chapters Basic Use of VCD Properties and List VCDProperties of the user's guide show you how to use them. When using the new VCDProperties, it is important to know how they are organized. There are VCDPropertyItems, VCDPropertyElements and VCDPropertyInterfaces. Each item has one or more elements and each element has one ore more interfaces. The interfaces allow the related property elements to be manipulated. In order to check, whether "WhiteBalance%%%" is available, use the VCDPropertyItems.FindElement method with VCDID_WhiteBalance + ":" + VCDElement_WhiteBalance%%% as a parameter. VCDID_WhiteBalance describes the property item, while VCDElement_WhiteBalance%%% describes the element "WhiteBalanceRed" or "WhiteBalanceBlue". If the property is supported, the respective element is returned. If it is not supported, Nothing is returned.

To get or set the values for "WhiteBalance%%%", retrieve the appropriate interface with the VCDPropertyItems.FindInterface, VCDPropertyElement.FindInterface or VCDPropertyElements.FindInterface method. As soon as the interface is retrieved, its methods can be used to manipulate the property. For detailed information, please refer to VCDPropertyInterface.

[VB.NET]
' Declare a range interface
Dim Range As ICImagingControl.VCDRangeProperty

' Retrieve a range interface for WhiteBalanceRed
Range = ICImagingControl1.VCDPropertyItems.FindInterface( VCDHelpers.VCDIDs.VCDID_WhiteBalance + ":" + _
                                                                VCDHelpers.VCDIDs.VCDElement_WhiteBalanceRed + ":" + _
                                                             VCDHelpers.VCDIDs.VCDInterface_Range )

' Initialize a slider sldWhiteBalanceRed with the values of the WhiteBalanceRed property
If Not Range Is Nothing Then
    sldWhiteBalanceRed.Minimum = Range.RangeMin
    sldWhiteBalanceRed.Maximum = Range.RangeMax
    sldWhiteBalanceRed.Value = Range.Value
    sldWhiteBalanceRed.Enabled = True
Else
    sldWhiteBalanceRed.Enabled = False
End If

[C#]
// Declare a range interface
private ICImagingControl.VCDRangeProperty Range;

// Retrieve a range interface for WhiteBalanceRed
Range = (ICImagingControl.VCDRangeProperty)IcImagingControl1.VCDPropertyItems.FindInterface(
                                                              VCDHelpers.VCDIDs.VCDID_WhiteBalance + ":" +
                                                                    VCDHelpers.VCDIDs.VCDElement_WhiteBalanceRed + ":" +
                                                                 VCDHelpers.VCDIDs.VCDInterface_Range );

// Initialize a slider sldWhiteBalanceRed with the values of the WhiteBalanceRed property
if( Range != null )
{
    sldWhiteBalanceRed.Minimum = Range.RangeMin
    sldWhiteBalanceRed.Maximum = Range.RangeMax
    sldWhiteBalanceRed.Value = Range.Value
    sldWhiteBalanceRed.Enabled = True
}
else
{
    sldWhiteBalanceRed.Enabled = False
}

IsHorizontalFlipAvailable, GetHorizontalFlip, SetHorizontalFlip

To check whether the horizontal flip is available, use the DeviceFlipHorizontalAvailable property. To get or set the horizontal flip, the DeviceFlipHorizontal property is used.

<< Technical Articles


Reference

Complete list of all classes and functions.

Constants

Complete list of all constants.

Helper Classes

Complete list of Helper Classes.

Classes

This page provides a complete list of IC Imaging Control's classes and its properties, methods and events sorted in alphabetical order.

Enumerations

Complete list of all enumerations.

<< IC Imaging Control .NET Component User's Guide


Constants

Complete list of all constants.

Constants

Constant | Description
Standard Element Identifier Strings | The Standard Element Identifier Strings are used to find a VCDPropertyElement of a VCDPropertyItem.
Standard Interface Identifier Strings | The Standard Interface Identifier Strings are used to find interface objects of a VCDPropertyElement.
Standard Property Item Identifier Strings | The Standard Property Item Identifier Strings are used to retrieve a VCDPropertyItem from the VCDPropertyItems collection. The strings are passed to the VCDPropertyItems.FindItem method.

<< Reference


constants::Standard Element Identifier Strings

constants.Standard Element Identifier Strings
The Standard Element Identifier Strings are used to find a VCDPropertyElement of a VCDPropertyItem.
After a VCDPropertyItem object has been retrieved with one of the Standard Property Item Identifier Strings, the property elements of the property item can be retrieved.
The strings are passed to the VCDPropertyElement.FindInterface method. The element type is used to retrieve a sub property of a camera property. For example the exposure camera property can have a value and an auto element. The value element is used to retrieve and set an value (e.g. 114). The auto element is used to enable or disable automation for exposure. An interface to an element is retrieved by adding a string from the Standard Interface Identifier Strings to the Standard Element Identifier String.
The Standard Element Identifier Strings are declared in the class TIS.VCDHelpers.VCDIDs.
The Basic Use of VCD Properties article in the Programmer's Guide shows how to use the element identifier strings.
Constant | Description
VCDElement_Value | Finds a value element with minimum and maximum.
VCDElement_Auto | Finds an auto element for enable or disable automation of a property.
VCDElement_OnePush | Finds a button element like the white balance OnePush.
VCDElement_ResetValue | Retrieves the reset value element.
VCDElement_WhiteBalanceBlue | Retrieves the white balance blue element of DCAM cameras.
VCDElement_WhiteBalanceRed | Retrieves the white balance red element of DCAM cameras.
VCDElement_AutoReference | Retrieves the auto reference value for the exposure element of the Dxx 21F04 camera series.
VCDElement_TriggerPolarity | Retrieves the trigger polarity element.
VCDElement_TriggerMode | Retrieves the trigger mode element.
VCDElement_MultiSlope_SlopeValue0 | Retrieves the multi slope 0 value element.
VCDElement_MultiSlope_ResetValue0 | Retrieves the multi slope reset 1 value element.
VCDElement_MultiSlope_SlopeValue1 | Retrieves the multi slope 1 value element.
VCDElement_MultiSlope_ResetValue1 | Retrieves the multi slope reset 1 value element.
VCDElement_MultiSlope_SlopeValue2 | Retrieves the multi slope 2 value element.
VCDElement_MultiSlope_ResetValue2 | Retrieves the multi slope reset 3 value element.
VCDElement_MultiSlope_SlopeValue3 | Retrieves the multi slope 3 value element.
VCDElement_MultiSlope_ResetValue3 | Retrieves the multi slope reset 3 value element.
VCDElement_MultiSlope_SlopeValue4 | Retrieves the multi slope 4 value element.
VCDElement_MultiSlope_ResetValue4 | Retrieves the multi slope reset 4 value element.
VCDElement_MultiSlope_SlopeValue5 | Retrieves the multi slope 5 value element.
VCDElement_MultiSlope_ResetValue5 | Retrieves the multi slope reset 5 value element.
VCDElement_MultiSlope_SlopeValue6 | Retrieves the multi slope 6 value element.
VCDElement_MultiSlope_ResetValue6 | Retrieves the multi slope reset 6 value element.
VCDElement_MultiSlope_SlopeValue7 | Retrieves the multi slope 7 value element.
VCDElement_MultiSlope_ResetValue7 | Retrieves the multi slope reset 7 value element.

<< Constants


constants::Standard Interface Identifier Strings

constants.Standard Interface Identifier Strings
The Standard Interface Identifier Strings are used to find interface objects of a VCDPropertyElement.
The interface of a VCDPropertyElement determines the handling of the regared property element. For example an auto element should be handled by a switch interface. These strings are combined with a string from the Standard Element Identifier Strings. The resulting string is passed to the VCDPropertyElement.FindInterface method.
The Standard Interface Identifier Strings are declared in the class TIS.VCDHelpers.VCDIDs.
The Basic Use of VCD Properties article in the Programmer's Guide shows how to use the interface identifier strings.
Constant | Description
VCDInterface_Range | Finds a VCDRangeProperty.
VCDInterface_Switch | Finds a VCDSwitchProperty.
VCDInterface_Button | Finds a VCDButtonProperty.
VCDInterface_MapStrings | Finds a VCDMapStringsProperty.
VCDInterface_AbsoluteValue | Finds a VCDAbsoluteValueProperty.

<< Constants


constants::Standard Property Item Identifier Strings

constants.Standard Property Item Identifier Strings
The Standard Property Item Identifier Strings are used to retrieve a VCDPropertyItem from the VCDPropertyItems collection. The strings are passed to the VCDPropertyItems.FindItem method.
A Standard Property Item Identifier String can be combined with a string from the Standard Element Identifier Strings and a string from the Standard Interface Identifier Strings. The strings are separeted by a colon. The resulting string can be passed to the VCDPropertyItems.FindItem method to retrieve an interface to the specified property.
The Standard Property Item Identifier Strings are declared in the class TIS.VCDHelpers.VCDIDs.
The Basic Use of VCD Properties article in the Programmer's Guide shows how to use the property item identifier strings.
Constant | Description
VCDID_Brightness | Retrieves the brightness property item.
VCDID_Contrast | Retrieves the contrast property item.
VCDID_Hue | Retrieves the hue property item.
VCDID_Saturation | Retrieves the saturation property item.
VCDID_Sharpness | Retrieves the sharpness property item.
VCDID_Gamma | Retrieves the gamma property item.
VCDID_ColorEnable | Retrieves the color enable property item.
VCDID_WhiteBalance | Retrieves the white balance property item.
VCDID_BacklightCompensation | Retrieves the backlight compensation property item.
VCDID_Gain | Retrieves the gain property item.
VCDID_Pan | Retrieves the pan property item.
VCDID_Tilt | Retrieves the tilt property item.
VCDID_Roll | Retrieves the roll property item.
VCDID_Zoom | Retrieves the zoom property item.
VCDID_Exposure | Retrieves the exposure property item.
VCDID_Iris | Retrieves the iris property item.
VCDID_Focus | Retrieves the focus property item.
VCDID_VCRCompatibilityMode | Retrieves the VCR compatibility mode property item.
VCDID_AutoReference | Retrieves the auto reference value for the exposure property item of the Dxx 21F04 camera series.
VCDID_TriggerPolarity | Retrieves the trigger polarity property item.
VCDID_Trigger | Retrieves the trigger mode property item.
VCDID_TestPattern | Retrieves the test pattern property of the Dxx 21F04 camera series
VCDID_MultiSlope | Retrieves the multi slope property item.

<< Constants


Helper Classes

Complete list of Helper Classes.

VCDIDs

This class contains the strings to be passed to the FindItem and FindInterface methods of the VCDProperties classes.

<< Reference


VCDIDs

This class contains the strings to be passed to the FindItem and FindInterface methods of the VCDProperties classes.

The class contains the following string constants:

Standard Property Item Identifier Strings

Standard Element Identifier Strings

Standard Interface Identifier Strings

Sample

The Basic Use of VCD Properties article in the Programmer's Guide shows how to use the property item identifier strings.

With the release of IC Imaging Control 3.0, the IDs were moved into the IC Imaging Control .NET component. The namespace was changed from VCDHelpers to TIS.Imaging.

Information

Namespace: TIS.Imaging
Introduced in version 2.0

<< Helper Classes


Classes

This page provides a complete list of IC Imaging Control's classes and its properties, methods and events sorted in alphabetical order.

AviCompressor

An AviCompressor object represents an avi compressor (codec). The properties of an avi compressor can be altered by displaying its property dialog.

BaseSink

Device

A Device object contains the information about a video capture device. The Name property of this object is used to set the ICImagingControl.Device property. This sets the current video capture device. A Device can be obtained out of the Devices collection.

DeviceLostEventArgs

This class holds the event arguments for the ICImagingControl.DeviceLost event.

FrameFilter

FrameFilterInfo

A FrameFilterInfo object contains information about a frame filter that can be loaded from a frame filter module and instantiated, using ICImagingControl.FrameFilterCreate.

FrameFilters

The FrameFilters class represents a chain of FrameFilter objects, that are used to transform the image data along the Device Path, Sink Path and Display Path.

FrameHandlerSink

The FrameHandlerSink is the SinkType used to grab (copy) frames from the image stream. It contains an ImageBuffer collection and optionally allows you to specify one or more FrameFilters that are responsible for copying the image data to the ImageBuffers. The FrameFilter implementation can perform user-defined transformations while copying the data, and they can intentionally drop unwanted frames. If no frame filter is registered, the frames are copied to the ImageBuffer collection without being changed.

FrameType

A FrameType describes the color format and (optionally) dimensions and buffer size of the image format of ImageBuffer objects.

FrameTypes

The FrameTypes collection is used to define a list of FrameTypes. A FrameTypes collection is used, i.e. to determine which FrameTypes are accepted by a frame filter or a sink.

ICException

This class represents errors that occur during application execution.

ICImagingControl

The ICImagingControl object provides the main functionality of this library. It enables you to select and set up devices, control image acquisition and manage image buffers and image streams.

IFrame

Interface to an image buffer.

ImageAvailableEventArgs

This class holds the event arguments for the ICImagingControl.ImageAvailable event.

ImageBuffer

An ImageBuffer object contains the image data of one frame. IC Imaging Control's internal ring buffer consists of ImageBuffers.

InputChannel

An InputChannel object contains the information about an analog input channel that is available on the current video capture device.

MediaStreamContainer

A MediaStreamContainer describes a video file format. The most common video file format is AVI.

MediaStreamSink

The MediaStreamSink allows video files to be recorded in a more sophisticated manor than is possible using AviStartCapture and AviStopCapture. However, for simple tasks, the methods AviStartCapture and AviStopCapture are better suited, as they are really easy to use. A MediaStreamSink can save image data to video files in various formats and optionally allows you to specify one or more FrameFilters that can analyze and/or transform the image data, before it is written to the video file.

MediaSubtypes

This class contains constants defining the available mediasubtype GUIDs that can be used when specifying a FrameType.

OverlayBitmap

An OverlayBitmap object contains the overlay data, methods and properties for drawing text and graphics on the live video stream.

OverlayUpdateEventArgs

This class holds the event arguments for the ICImagingControl.OverlayUpdate event.

UserFrame

An abstract class, which can be implemented in order to create own additional buffers. This can be requested when an own OverlayBitmap object is needed, for example.

VCDAbsoluteValueProperty

This class represents an absolute value interface to a value of a video capture device property.

VCDButtonProperty

This class represents a button interface to a video capture device property. Button interfaces allow invoking an operation at the property.

VCDCategoryMap

This class describes how VCD property items are organized in categories.

VCDMapStringsProperty

This class represents an interface to a value of a video capture device property, that uses names for the values.

VCDPropertyElement

This class represents an element of video capture device property.

VCDPropertyElements

This class is a collection of VCDPropertyElement objects.

VCDPropertyInterface

This class represents an interface to a value of a video capture device property. It is an abstract base class for several more specialized interfaces.

VCDPropertyItem

A VCDPropertyItem object provides the functionality to access a video capture device property.

VCDPropertyItems

This class contains a collection of all VCDPropertyItem objects that are supported by the currently opened device.

VCDRangeProperty

This class represents a range interface to a value of a video capture device property.

VCDSimpleModule

This class wraps the concept of VCDProperties to make them easier to use. It replaces the VCDSimpleProperty class, which was located in an extra source code file.

VCDSimpleProperty

This class wraps the concept of VCDProperties to make them easier to use.

VCDSwitchProperty

This class represents a switch interface to a value of a video capture device property. A switch interface is used to enable or disable settings of a property.

VideoFormat

A VideoFormat object contains information about a video format supported by the current video capture device.

VideoFormatDesc

A VideoFormatDesc describes an available video format using the media subtype, a binning factor and size constraints. The size constraints are described by a minimum size, a maximum size and a step size.

VideoNorm

A VideoNorm object contains information about a video norm supported by the current video capture device.

<< Reference


AviCompressor

An AviCompressor object represents an avi compressor (codec). The properties of an avi compressor can be altered by displaying its property dialog.

Example

[VB.NET]
Dim Codec As AviCompressor
Codec = IcImagingControl1.AviCompressors(0)

[C#]
AviCompressor Codec = ICImagingControl1.AviCompressors[0];

Information

Namespace: TIS.Imaging
Introduced in version 1.x

Properties

Property | Description
CompressorData | Returns or sets the data of an AviCompressor.
CompressorDataSize | Returns the size of the SAFEARRAY of Byte returned by CompressorData.
CompressorDataString | Returns or sets a string containing the codec parameters.
Name | Returns the name of the AviCompressor
PropertyPageAvailable | Returns True, if the AviCompressor has a property page, otherwise False.

Methods

Method | Description
ShowPropertyPage | Shows the property page of the AviCompressor, if available. If a property page is not available, an error is returned.
ToString | Returns the name of the AviCompressor.

<< Classes


AviCompressor::CompressorData

AviCompressor.CompressorData Property
Returns or sets the data of an AviCompressor.
Syntax:
[VB.NET]
Public CompressorData As Byte()

[C#]
public byte[] CompressorData;
Remarks:

The returned data should only be used to store the state of the codecs. The data in the array is not to be modified. If inconsistent data is passed to the codec, an error is returned. Furthermore, the data of one codec will not match each other.

Sample:

The following example shows how to save and load codec data into and from a binary file. The codec which is currently used, must be declared globally. If it is declared locally in the sub procedure, it would loose its settings after exiting the sub procedure, because it would be removed from memory. The complete example can be found in the samples directory in Saving Codec Properties.

Save the data from a codec that was selected in a combo box.

[VB.NET]
Private Sub cmdSaveCodecData_Click(ByVal sender As System.Object, ByVal e As System.EventArgs) Handles cmdSaveCodecData.Click
    If edtConfigFile.Text <> "" Then
        Try
            Dim Filestream As New System.IO.FileStream(edtConfigFile.Text, System.IO.FileMode.Create, System.IO.FileAccess.Write)

            ' Create the writer for data.
            Dim BinWriter As New System.IO.BinaryWriter(Filestream)

            ' Write data to Test.data.
            Dim aviComp As AviCompressor
            aviComp = CType(CodecBox.SelectedItem(), AviCompressor)

            BinWriter.Write(aviComp.ToString())
            BinWriter.Write(aviComp.CompressorDataSize)
            BinWriter.Write(aviComp.CompressorData)

            BinWriter.Close()
            Filestream.Close()

        Catch Ex As System.Exception
            MsgBox(Ex.Message, MsgBoxStyle.Critical, "Write error")
        End Try
    End If
End Sub

[C#]
private void cmdSaveCodecData_Click(object sender, System.EventArgs e)
{
    if (edtConfigFile.Text != "")
    {
        try
        {
            System.IO.FileStream Filestream = new System.IO.FileStream(edtConfigFile.Text, System.IO.FileMode.Create, System.IO.FileAccess.Write);

            // Create the writer for data.
            System.IO.BinaryWriter BinWriter = new System.IO.BinaryWriter(Filestream);

            // Write data to Test.data.
            AviCompressor aviComp = null;
            aviComp = ((AviCompressor)(CodecBox.SelectedItem));

            BinWriter.Write(aviComp.ToString());
            BinWriter.Write(aviComp.CompressorDataSize);
            BinWriter.Write(aviComp.CompressorData);

            BinWriter.Close();
            Filestream.Close();

        }
        catch (Exception Ex)
        {
            MessageBox.Show(Ex.Message, "Write error", MessageBoxButtons.OK, MessageBoxIcon.Error);
        }
    }
}

Load the previously saved data and assign it to a codec.

[VB.NET]
Private Sub cmdLoadCodecData_Click(ByVal sender As System.Object, ByVal e As System.EventArgs) Handles cmdLoadCodecData.Click
    If edtConfigFile.Text <> "" Then
        Try
            ' Create the reader for data.
            Dim Filestrem As New System.IO.FileStream(edtConfigFile.Text, System.IO.FileMode.Open, System.IO.FileAccess.Read)
            Dim BinReader As New System.IO.BinaryReader(Filestrem)

            Dim CodecName As String
            Dim Codec As AviCompressor
            Dim CodecFound As Boolean

            ' Retrieve the name of the codec from the codec configuration file
            CodecName = BinReader.ReadString()

            ' Search this codec in the codec combo box
            CodecFound = False
            For Each item As AviCompressor In CodecBox.Items
                If item.ToString() = CodecName Then
                    CodecBox.SelectedItem = item
                    Codec = item
                    CodecFound = True
                End If
            Next

            If CodecFound = True Then
                Dim codecDataLen As Integer = BinReader.ReadInt32()
                ' Assign the configuration data to the codec.
                Codec.CompressorData = BinReader.ReadBytes(codecDataLen)
            Else
                ' If the codec was not found, display an error message.
                MsgBox("The codec " + CodecName + " was not found!", MsgBoxStyle.Information, "Load codec configuration")
            End If
            BinReader.Close()
            Filestrem.Close()

        Catch Ex As System.Exception
            MsgBox(Ex.Message, MsgBoxStyle.Critical, "Read error")
        End Try
    End If
End Sub

[C#]
private void cmdLoadCodecData_Click(object sender, System.EventArgs e)
{
    if (edtConfigFile.Text != "")
    {
        try
        {
            // Create the reader for data.
            System.IO.FileStream Filestrem = new System.IO.FileStream(edtConfigFile.Text, System.IO.FileMode.Open, System.IO.FileAccess.Read);
            System.IO.BinaryReader BinReader = new System.IO.BinaryReader(Filestrem);

            string CodecName = "";
            AviCompressor Codec = null;
            bool CodecFound = false;

            // Retrieve the name of the codec from the codec configuration file
            CodecName = BinReader.ReadString();

            // Search this codec in the codec combo box
            CodecFound = false;
            foreach (AviCompressor item in CodecBox.Items)
            {
                if (item.ToString() == CodecName)
                {
                    CodecBox.SelectedItem = item;
                    Codec = item;
                    CodecFound = true;
                }
            }

            if (CodecFound == true)
            {
                int codecDataLen = BinReader.ReadInt32();
                // Assign the configuration data to the codec.
                Codec.CompressorData = BinReader.ReadBytes(codecDataLen);
            }
            else
            {
                // If the codec was not found, display an error message.
                MessageBox.Show("The codec " + CodecName + " was not found!", "Load codec configuration", MessageBoxButtons.OK, MessageBoxIcon.Information);
            }
            BinReader.Close();
            Filestrem.Close();

        }
        catch (Exception Ex)
        {
            MessageBox.Show(Ex.Message, "Read error", MessageBoxButtons.OK, MessageBoxIcon.Error);
        }
    }
}
See Also: AviCompressor, AviCompressor.CompressorDataSize

<< AviCompressor


AviCompressor::CompressorDataSize

AviCompressor.CompressorDataSize Property
Returns the size of the SAFEARRAY of Byte returned by CompressorData.
Syntax:
[VB.NET]
Public CompressorDataSize As Integer

[C#]
public int CompressorDataSize;
Limitations:

Read only.
Remarks:

The CompressorDataSize is useful, if codec properties are to be saved to a file. Reading the size value first from file, enables an application to create an array of the matching size that will get the codec properties.

Sample:

How to use the CompressorDataSize is shown in the sample Saving Codec Properties.

Save the data from a codec that was selected in a combo box.

[VB.NET]
Private Sub cmdSaveCodecData_Click(ByVal sender As System.Object, ByVal e As System.EventArgs) Handles cmdSaveCodecData.Click
    If edtConfigFile.Text <> "" Then
        Try
            Dim Filestream As New System.IO.FileStream(edtConfigFile.Text, System.IO.FileMode.Create, System.IO.FileAccess.Write)

            ' Create the writer for data.
            Dim BinWriter As New System.IO.BinaryWriter(Filestream)

            ' Write data to Test.data.
            Dim aviComp As AviCompressor
            aviComp = CType(CodecBox.SelectedItem(), AviCompressor)

            BinWriter.Write(aviComp.ToString())
            BinWriter.Write(aviComp.CompressorDataSize)
            BinWriter.Write(aviComp.CompressorData)

            BinWriter.Close()
            Filestream.Close()

        Catch Ex As System.Exception
            MsgBox(Ex.Message, MsgBoxStyle.Critical, "Write error")
        End Try
    End If
End Sub

[C#]
private void cmdSaveCodecData_Click(object sender, System.EventArgs e)
{
    if (edtConfigFile.Text != "")
    {
        try
        {
            System.IO.FileStream Filestream = new System.IO.FileStream(edtConfigFile.Text, System.IO.FileMode.Create, System.IO.FileAccess.Write);

            // Create the writer for data.
            System.IO.BinaryWriter BinWriter = new System.IO.BinaryWriter(Filestream);

            // Write data to Test.data.
            AviCompressor aviComp = null;
            aviComp = ((AviCompressor)(CodecBox.SelectedItem));

            BinWriter.Write(aviComp.ToString());
            BinWriter.Write(aviComp.CompressorDataSize);
            BinWriter.Write(aviComp.CompressorData);

            BinWriter.Close();
            Filestream.Close();

        }
        catch (Exception Ex)
        {
            MessageBox.Show(Ex.Message, "Write error", MessageBoxButtons.OK, MessageBoxIcon.Error);
        }
    }
}

Load the previously saved data and assign it to a codec.

[VB.NET]
Private Sub cmdLoadCodecData_Click(ByVal sender As System.Object, ByVal e As System.EventArgs) Handles cmdLoadCodecData.Click
    If edtConfigFile.Text <> "" Then
        Try
            ' Create the reader for data.
            Dim Filestrem As New System.IO.FileStream(edtConfigFile.Text, System.IO.FileMode.Open, System.IO.FileAccess.Read)
            Dim BinReader As New System.IO.BinaryReader(Filestrem)

            Dim CodecName As String
            Dim Codec As AviCompressor
            Dim CodecFound As Boolean

            ' Retrieve the name of the codec from the codec configuration file
            CodecName = BinReader.ReadString()

            ' Search this codec in the codec combo box
            CodecFound = False
            For Each item As AviCompressor In CodecBox.Items
                If item.ToString() = CodecName Then
                    CodecBox.SelectedItem = item
                    Codec = item
                    CodecFound = True
                End If
            Next

            If CodecFound = True Then
                Dim codecDataLen As Integer = BinReader.ReadInt32()
                ' Assign the configuration data to the codec.
                Codec.CompressorData = BinReader.ReadBytes(codecDataLen)
            Else
                ' If the codec was not found, display an error message.
                MsgBox("The codec " + CodecName + " was not found!", MsgBoxStyle.Information, "Load codec configuration")
            End If
            BinReader.Close()
            Filestrem.Close()

        Catch Ex As System.Exception
            MsgBox(Ex.Message, MsgBoxStyle.Critical, "Read error")
        End Try
    End If
End Sub

[C#]
private void cmdLoadCodecData_Click(object sender, System.EventArgs e)
{
    if (edtConfigFile.Text != "")
    {
        try
        {
            // Create the reader for data.
            System.IO.FileStream Filestrem = new System.IO.FileStream(edtConfigFile.Text, System.IO.FileMode.Open, System.IO.FileAccess.Read);
            System.IO.BinaryReader BinReader = new System.IO.BinaryReader(Filestrem);

            string CodecName = "";
            AviCompressor Codec = null;
            bool CodecFound = false;

            // Retrieve the name of the codec from the codec configuration file
            CodecName = BinReader.ReadString();

            // Search this codec in the codec combo box
            CodecFound = false;
            foreach (AviCompressor item in CodecBox.Items)
            {
                if (item.ToString() == CodecName)
                {
                    CodecBox.SelectedItem = item;
                    Codec = item;
                    CodecFound = true;
                }
            }

            if (CodecFound == true)
            {
                int codecDataLen = BinReader.ReadInt32();
                // Assign the configuration data to the codec.
                Codec.CompressorData = BinReader.ReadBytes(codecDataLen);
            }
            else
            {
                // If the codec was not found, display an error message.
                MessageBox.Show("The codec " + CodecName + " was not found!", "Load codec configuration", MessageBoxButtons.OK, MessageBoxIcon.Information);
            }
            BinReader.Close();
            Filestrem.Close();

        }
        catch (Exception Ex)
        {
            MessageBox.Show(Ex.Message, "Read error", MessageBoxButtons.OK, MessageBoxIcon.Error);
        }
    }
}
See Also: AviCompressor, AviCompressor.CompressorData

<< AviCompressor


AviCompressor::Name

AviCompressor.Name Property
Returns the name of the AviCompressor
Syntax:
[VB.NET]
Public Name As String

[C#]
public string Name;
Limitations:

Read only.
Sample:

This example starts an avi capture with the first compressor in the collection:

[VB.NET]
Dim AviComp As AviCompressor ' Create the AviCompressor object

' Get the first available AviCompressor.
AviComp = IcImagingControl1.AviCompressors(0)

' Start capturing with the target file and the name of the
' AviCompressor previously selected.
IcImagingControl1.AviStartCapture("test.avi", AviComp.Name)

[C#]
// Get the first available AviCompressor.
AviCompressor AviComp = ICImagingControl1.AviCompressors[0];

// Start capturing with the target file and the name of the
// previously selected AviCompressor.
ICImagingControl1.AviStartCapture("test.avi", AviComp.Name);

How to use avi compressors is shown in the Capturing an AVI File sample.

See Also: AviCompressor, AviCompressor.ToString

<< AviCompressor


AviCompressor::PropertyPageAvailable

AviCompressor.PropertyPageAvailable Property
Returns True, if the AviCompressor has a property page, otherwise False.
Syntax:
[VB.NET]
Public PropertyPageAvailable As Boolean

[C#]
public bool PropertyPageAvailable;
Limitations:

Read only.
Sample:

This example shows how to enable/disable a button that calls the property page of the first avi compressor:

[VB.NET]
Dim AviComp As AviCompressor
AviComp = IcImagingControl1.AviCompressors(0)
cmdShowPropertyPage.Enabled = AviComp.PropertyPageAvailable

[C#]
AviCompressor AviComp = ICImagingControl1.AviCompressors[0];
cmdShowPropertyPage.Enabled = AviComp.PropertyPageAvailable;

How to use avi compressors is shown in the Capturing an AVI File sample.

See Also: AviCompressor, AviCompressor.ShowPropertyPage

<< AviCompressor


AviCompressor::ShowPropertyPage

AviCompressor.ShowPropertyPage Method
Shows the property page of the AviCompressor, if available. If a property page is not available, an error is returned.
Syntax:
[VB.NET]
Public Sub ShowProperyPage

[C#]
public void ShowPropertyPage();
Sample:

This example shows how to display the property page of the avi compressor (codec) that is currently selected in a combo box:

[VB.NET]
Dim AviComp As AviCompressor
AviComp = IcImagingControl1.AviCompressors(0)

If AviComp.PropertyPageAvailable Then
    AviComp.ShowPropertyPage()
Else
    ' The AVI compressor has no property page.
End If

[C#]
AviCompressor AviComp = ICImagingControl1.AviCompressors[0];

if (AviComp.PropertyPageAvailable)
{
    AviComp.ShowPropertyPage();
}
else
{
    // The AVI compressor has no property page.
}

How to use avi compressors is shown in the Capturing an AVI File sample.

See Also: AviCompressor, AviCompressor.PropertyPageAvailable

<< AviCompressor


Device

A Device object contains the information about a video capture device. The Name property of this object is used to set the ICImagingControl.Device property. This sets the current video capture device. A Device can be obtained out of the Devices collection.

Example

The following example shows how to get the first available device object.

[VB.NET]
Dim Dev As Device
Dev = IcImagingControl1.Devices(0)

[C#]
Device Dev = ICImagingControl1.Devices[0];

Information

Namespace: TIS.Imaging
Introduced in version 1.x

Properties

Property | Description
Name | Returns the name of the Device.

Methods

Method | Description
GetSerialNumber | Retrieves the serial number of the video capture device.

<< Classes


Device::Name

Device.Name Property
Returns the name of the Device.
Syntax:
[VB.NET]
Public Name As String

[C#]
public string Name;
Limitations:

Read only.
Sample:

This example selects the first available device.

[VB.NET]
Dim dev As Device
dev = IcImagingControl1.Devices(0)
IcImagingControl1.Device = dev.Name

[C#]
Device dev = ICImagingControl1.Devices[0];
ICImagingControl1.Device = dev.Name;
See also: Device, Devices

<< DeviceLostEventArgs.Device


Device::GetSerialNumber

Device.GetSerialNumber Method
Retrieves the serial number of the video capture device.
Syntax:
[VB.NET]
Public Function GetSerialNumber( ByRef Number As String ) As Boolean

[C#]
bool GetSerialNumber( out string Number );

Parameter | Description
Number | Specifies the string that will receive the serial number.
Return Value:

True, if the serial number of the video capture device could be retrieved. If the video capture device does not support serial numbers, False is returned.

Limitations:

Runtime only.
Sample:

This example demonstrates how to use the GetSerialNumber method.

[VB.NET]
Dim SN As String
Dim Dev As Device

' Get the first video capture device.
Dev = IcImagingControl1.Devices(0)

' Check whether a serial number can be retrieved.
If Dev.GetSerialNumber(SN) Then
    MessageBox.Show("The serial number is " + SN)
Else
    MessageBox.Show("The device does not have a serial number")
End If

[C#]
string SN = "";

// Get the first video capture device.
Device Dev = ICImagingControl1.Devices[0];

// Check whether a serial number can be retrieved.
if (Dev.GetSerialNumber( out SN ))
{
    MessageBox.Show("The serial number is " + SN);
}
else
{
    MessageBox.Show("The device does not have a seial number");
}
See also: Device, Devices

<< DeviceLostEventArgs.Device


ICException

This class represents errors that occur during application execution.

ICException is inherited from System.Exception.

Information

Namespace: TIS.Imaging
Introduced in version 3.0

Properties

Property | Description
ErrorCode | This property returns an errorcode from the ErrorCodes enumeration.
Message | This property returns a message that describes the current exception

Enumerations

Enumeration | Description
ErrorCodes | This enumeration contains the available error codes.

<< Classes


ICException::ErrorCode

ICException.ErrorCode Property
This property returns an errorcode from the ErrorCodes enumeration.
Syntax:
[VB.NET]
Public ErrorCode As ICException.ErrorCodes

[C#]
public ICException.ErrorCodes ErrorCode;
Limitations:

Read only.
See also: ErrorCodes

<< ICException


ICException::Message

ICException.Message Property
This property returns a message that describes the current exception
Syntax:
[VB.NET]
Public Message As String

[C#]
public string Message;
Limitations:

Read only.

<< ICException


ICException::ErrorCodes

ICException.ErrorCodes
This enumeration contains the available error codes.
Error code | Message
Unknown | An unknown error occurred.
ModeAlreadyActive | Mode already active.
NoDeviceOpen | No device opened. You cannot alter device specific behavior without opening a device.
DeviceLost | Device is lost. This may happens when the user unplugs the device from the computer.
OptionNotAvailable | Option is not available.
DeviceNotFound | Device not found.
OptionNotAvailableInLiveMode | Option is not available in live mode.
OptionNotAvailableOutsideLiveMode | Option is only available in live mode.
OptionNotAvailableWithoutFrameHandlerSink | No frame handler sink set. Certain functionality does only work, if a FrameHandlerSink is set in the main object.
OptionNotAvailable_LiveDisplayDefault | This option is not available, because of current LiveDisplayDefault property value.
NotAvailableOutsideSnapMode | The requested operation is not available while SnapMode is false.
NotAvailableInImageAvailableExecutionModeInvoke | The requested operation is not available while ImageAvailableExecutionMode is set to EventExecutionMode.Invoke. Calling SnapImage will cause a deadlock.
ObjectInvalid | Object is invalid.
VCDPropertyGetFailed | A get operation on a VCDProperty object failed.
VCDPropertySetFailed | A set operation on a VCDProperty object failed.
FrameFilterNotFound | The specified frame filter could not be found.
FrameFilterParamNotFound | A parameter with this name is not available.
FrameFilterParamIncompatibleValue | The parameter you passed or requested is incompatible to the current parameter.
FrameFilterParamInvalidState | The filter is in a state, where the requested parameter can not be used.
NoImageBufferAvailable | There is no ImageBuffer available to be returned.
TimeoutElapsed | Timeout elapsed.
DataIncompatible | Passed data does not fit to the compressor.
SerialNumberInvalid | Serial number invalid.
OutOfMemory | The computer ran out of memory.

<< ICException


ICImagingControl

The ICImagingControl object provides the main functionality of this library. It enables you to select and set up devices, control image acquisition and manage image buffers and image streams.

The ICImagingControl object is created by the framework when the IC Imaging Control component is inserted into a form.

Information

Namespace: TIS.Imaging
Introduced in version 1.x

Properties

Property | Description
AviCompressors | Returns a collection of available avi compressors (video codecs).
DeBayerActive | Returns whether automatic de-bayering of BY8 image data is enabled.
DeBayerMode | This property selects the algorithm used to de-bayer BY8 image data.
DeBayerStartPattern | This property controls how the automatic de-bayering of BY8 image data should treat the pixel data.
Device | Returns or sets a video capture device. A list of all available video capture devices can be obtained using the Devices collection, which can be retrieved with a call to ICImagingControl.Devices.
DeviceCountOfFramesDropped | Returns the number dropped frames.
DeviceCountOfFramesNotDropped | Returns the number of frames that were not dropped.
DeviceCurrent | Returns a Device object that contains the currently used video capture device.
DeviceCurrentActualFrameRate | Returns the frame rate currently used by the video capture device. A value of 0 indicates that this property is not supported by the video capture device.
DeviceFlipHorizontal | Returns or sets the horizontal flipping of the live video image.
DeviceFlipHorizontalAvailable | This property determines whether horizontal flip is available for the currently selected device.
DeviceFlipVertical | Returns or sets the vertical flipping of the live video image.
DeviceFlipVerticalAvailable | This property determines whether vertical flip is available for the currently selected device.
DeviceFrameFilters | The DeviceFrameFilters property provides a FrameFilters collection that contains the frame filters that are inserted in the device path.
DeviceFrameRate | Returns or sets the desired frame rate (in frames per second) of the current video capture device.
DeviceFrameRateAvailable | Returns True, if setting of frame rates is supported by the video capture device.
DeviceFrameRates | Returns a collection of frame rates supported by the video capture device. May be empty if the device does not support frame rates.
DeviceTrigger | Enables/disables external triggering of the current video capture device.
DeviceTriggerAvailable | Returns True if the device has an external trigger.
DeviceValid | Returns True when a device is open and valid, otherwise False.
Devices | Returns a collection of all available video capture devices.
DisplayFrameFilters | The DisplayFrameFilters property provides a FrameFilters collection that contains the frame filters that are inserted in the display path.
ExternalTransportAvailable | Returns True if the video capture device has an external transport interface (e.g. DV-Devices).
ExternalTransportMode | Returns or sets the mode of the external transport device, if available.
FrameFilterInfos | This property returns a list, containing FrameFilterInfo objects that describe the available frame filters, which can be loaded from frame filter modules (.ftf files).
FrameFilterPath | Sets a path from which frame filters are loaded.
ImageActiveBuffer | Returns the ImageBuffer to which the control copied the last frame.
ImageAvailableExecutionMode | This property controls the execution mode of the ImageAvailable event.
ImageBitsPerPixel | Returns the bits per pixel of the buffers in the control. The bytes per pixel are calculated by dividing ImageBitsPerPixel by 8. The value of this property is determined by the value of the ICImagingControl.MemoryCurrentGrabberColorformat property.
ImageBuffers | Returns a collection of ImageBuffers, which represent the buffers in the ringbuffer.
ImageHeight | Returns the image height (in pixels) of the current video source.
ImageRingBufferSize | Returns or sets the size of the internal ring buffer. Must lie in the range [1,...[.
ImageSize | Returns the image height and width in pixels of the current video format.
ImageWidth | Returns the image width (in pixels) of the current video source.
InputChannel | Returns or sets the input channel of the current video capture device. Available input channels can be enumerated using the InputChannels collection, which can be retrieved with a call to ICImagingControl.InputChannels.
InputChannelAvailable | Returns True if the current video capture device supports input channels.
InputChannels | Returns a collection of available input channels for the current video capture device.
IsLivePrepared | Returns whether the image stream was is prepared after a previous call to LivePrepare, or LiveSuspend.
LiveCaptureContinuous | Enables/disables the continuous capture mode. In this mode ICImagingControl.MemorySnapImage may not be called, because all frames are copied to the ring buffer automatically. After an image has been copied completely to a buffer, an ICImagingControl.ImageAvailable event is sent. If an ICImagingControl.ImageAvailable event is currently processed, a new event will not be sent.
LiveCaptureLastImage | Enables/disables the automatic call to ICImagingControl.MemorySnapImage in ICImagingControl.LiveStop. This property should be set to True if ICImagingControl is to display the last frame after LiveStop has been called.
LiveCapturePause | Returns or sets the pause for AVI capture.
LiveDisplay | Enables/disables live display in the control window. If live display is disabled, the image buffers may be shown by a call to ICImagingControl.Display.
LiveDisplayDefault | Returns or enables the use of the default size and position of the video display window.
LiveDisplayHeight | Returns or sets the height of the video display window.
LiveDisplayLeft | Returns or sets the left position of the video display window in IC Imaging Control's window.
LiveDisplayOutputHeight | Returns the actual height of the video format of the live display. Due to the use of frame filters, this height can differ from the height of the video capture device's video format and the sink's format.
LiveDisplayOutputWidth | Returns the actual width of the video format of the live display. Due to the use of frame filters, this width can differ from the width of the video capture device's video format and the sink's format.
LiveDisplayPosition | Returns or sets the top position of the video display window in IC Imaging Control's window.
LiveDisplaySize | Returns or sets the height and width of the video display window.
LiveDisplayTop | Returns or sets the top position of the video display window in IC Imaging Control's window.
LiveDisplayWidth | Returns or sets the width of the video display window.
LiveDisplayZoomFactor | Returns or sets the zoom factor of the video display window.
LivePause | This property suspends and restarts the current delivery of images.
LiveShowLastBuffer | This property controls whether IC Imaging Control displays the buffer that was captured on LiveStop when LiveCaptureLastImage is enabled.
LiveVideoRunning | Indicates whether a live video is running, i.e. has been started with the LiveStart Method.
MediaStreamContainers | Returns a list containing all available MediaStreamContainers.
MemoryCurrentGrabberColorformat | Determines the color format of the image buffers in the internal ring buffer.
MemoryPixelFormat | Sets the pixel format of the ring buffer.
OverlayBitmap | Returns an OverlayBitmap object.
OverlayBitmapAtPath | Returns the OverlayBitmap at a specified path position.
OverlayBitmapPosition | This property controls the positions of OverlayBitmap objects in the image stream.
OverlayUpdateEventEnable | This property is used to return or set whether the overlay update event should be called by IC Imaging Control.
ReferenceTimeCurrent | Returns the current reference time.
ReferenceTimeStart | Returns the reference time at which the image stream was started.
ScrollBarsEnabled | Returns whether scrollbars are enabled or enables/disables scrollbars.
SignalDetected | Returns whether a video signal is detected on the currently selected input channel of the selected video capture device.
SignalDetectedAvailable | Returns whether the current video capture device supports signal detection on its input ports.
Sink | Sets or retrieves the currently used sink. A sink is an object that receives the frames coming from the video capture device and either copies them to an ImageBuffers collection or saves them to a media stream file.
SinkCompatibilityMode | SinkCompatibilityMode is for compatibility to IC Imaging Control 2.1.
VCDPropertyItems | Returns a VCDPropertyItems collection representing the properties of the currently opened device.
VideoFormat | Returns or sets the video format of the current video capture device. A list of available video formats can be obtained using the VideoFormats collection, which can be retrieved with a call to ICImagingControl.VideoFormats.
VideoFormatCurrent | Returns the selected Videoformat object.
VideoFormatDescs | Returns a list of VideoFormatDesc objects describing all video formats supported by the current video capture device.
VideoFormats | Returns a collection of available video formats for the current device and video norm.
VideoNorm | Returns or sets the video norm of the current video capture device. A list of available video norms can be obtained using the VideoNorms collection, which can be retrieved with by calling ICImagingControl.VideoNorms.
VideoNormAvailable | Returns whether the current device supports video norms.
VideoNorms | Returns a collection of available video norms for the current device.

Methods

Method | Description
AviStartCapture | This method writes a compressed AVI file to the computer's hard disk.
AviStopCapture | This method stops writing an AVI file.
Display | Displays the current image buffer in IC Imaging Control's window.
DisplayImageBuffer | When the property ICImagingControl.LiveDisplay is False , then a call to ICImagingControl.DisplayImageBuffer displays the given buffer in the control window
FrameFilterCreate | Creates a new instance of a FrameFilter from a FrameFilterInfo.
ICImagingControl | Creates a new ICImagingControl object.
LivePrepare | This method tries to setup the image stream by connecting the device with the display and the sink and inserting frame filters and overlays.
LiveStart | This method starts the processing of images delivered by the video capture device.
LiveStop | Calling this method stops the display of a live image previously started with the LiveStart method.
LiveSuspend | Suspends a prepared image stream and switches it into prepared state.
LoadDeviceState | Restores the device settings saved with ICImagingControl.SaveDeviceState.
LoadDeviceStateFromFile | Restores the device settings saved with ICImagingControl.SaveDeviceStateToFile.
MemorySaveImage | This method saves the current buffer as a .bmp file.
MemorySaveImageSequence | This method saves a sequence of images as a sequence of single .bmp files.
MemorySnapImage | This method captures a still image from a live video stream.
MemorySnapImageSequence | This method captures a sequence of still images from a live video stream and stores the images in a list of internal buffers. The images can be saved to individual files using the ICImagingControl.MemorySaveImageSequence method.
SaveDeviceState | Saves the currently opened device and its settings to a string.
SaveDeviceStateToFile | Saves the currently opened device and its settings to a file.
ShowDeviceSettingsDialog | This method opens a video capture device selection dialog.
ShowPropertyDialog | This method opens a dialog to adjust all properties of the currently opened video capture device.

Events

Event | Description
DeviceLost | This event is called if the video capture device is no longer valid; for example if it was unplugged.
ImageAvailable | This event is called each time a frame has been copied completely to the internal ring buffer.
LivePrepared | This event is called after the LivePrepare was called.
OverlayUpdate | This event is called after a new frame has been delivered by the video capture device.

<< Classes


ICImagingControl::AviCompressors

ICImagingControl.AviCompressors Property
Returns a collection of available avi compressors (video codecs).
Syntax:
[VB.NET]
Public AviCompressors As AviCompressor()

[C#]
public AviCompressor[] AviCompressors;
Limitations:

Run time only, read only.
Sample:

This example displays all available compressors in a combo box. If no compressors are installed, the text "n/a" will be displayed in the combo box and it will be disabled. The combo box for the compessors is named "cboVideoCodec" in this example.

[VB.NET]
cboVideoCodec.Items.Clear()
If IcImagingControl1.AviCompressors.Length > 0 Then
    '  If compressors have been found, add them to the combobox.
    Dim Item As AviCompressor
    For Each Item In IcImagingControl1.AviCompressors
        cboVideoCodec.Items.Add(Item.Name)
    Next
    cboVideoCodec.Enabled = True
Else
    '  No compressors have been found.
    cboVideoCodec.Items.Add("n/a")
    cboVideoCodec.Enabled = False
End If
cboVideoCodec.SelectedIndex = 0

[C#]
cboVideoCodec.Items.Clear();
if (ICImagingControl1.AviCompressors.Length > 0)
{
    //  If compressors have been found, add them to the combobox.
    foreach (AviCompressor Item in ICImagingControl1.AviCompressors)
    {
        cboVideoCodec.Items.Add(Item.Name);
    }
    cboVideoCodec.Enabled = true;
}
else
{
    //  No compressors have been found.
    cboVideoCodec.Items.Add("n/a");
    cboVideoCodec.Enabled = false;
}
cboVideoCodec.SelectedIndex = 0;
See also: ICImagingControl, AviCompressors, ICImagingControl.AviStartCapture, ICImagingControl.AviStopCapture

<< ICImagingControl


ICImagingControl::Device

ICImagingControl.Device Property
Returns or sets a video capture device. A list of all available video capture devices can be obtained using the Devices collection, which can be retrieved with a call to ICImagingControl.Devices.
Syntax:
Remarks:

Changing the device invalidates the ICImagingControl.VideoNorm and the ICImagingControl.InputChannel property and those which depend on these.

Sample:

This example selects the first available device:

[VB.NET]
Dim dev As Device
dev = IcImagingControl1.Devices(0)
IcImagingControl1.Device = dev.Name

[C#]
Device dev = ICImagingControl1.Devices[0];
ICImagingControl1.Device = dev.Name;

Selecting devices, input channels, video norms and video formats is shown in the Making Device Settings chapter.

See also: ICImagingControl, ICImagingControl.Devices, ICImagingControl.DeviceValid

<< ICImagingControl


ICImagingControl::DeviceCurrentActualFrameRate

ICImagingControl.DeviceCurrentActualFrameRate Property
Returns the frame rate currently used by the video capture device. A value of 0 indicates that this property is not supported by the video capture device.
Syntax:
[VB.NET]
Public DeviceCurrentActualFrameRate As Single

[C#]
public float DeviceCurrentActualFrameRate;
Limitations:

Run time only, read only. Only available in live mode.
Remarks:

DeviceCurrentActualFrameRate returns the number of frames actually sent by the video capture device. The actual frame rate depends on the bandwith and the video format. Therefore, the DeviceCurrentActualFrameRate may differ from the desired frame rate that has been set with the ICImagingControl.DeviceFrameRate property. It can be less than the desired frame rate if the bandwith is too low, but will never be greater.

If an application needs to display the actual frame rate, it is recommended to check the frame rate with DeviceCurrentActualFrameRate as shown in the example below.

Sample:

This example shows how to display the actual frame rate of the video capture device. A timer has been added to the application in order to update the display of the current frame rate periodically.

[VB.NET]
Dim dev As Device
dev = IcImagingControl1.Devices(0)
IcImagingControl1.Device = dev.Name

[C#]
Device dev = ICImagingControl1.Devices[0];
ICImagingControl1.Device = dev.Name;
See also: ICImagingControl, ICImagingControl.DeviceFrameRateAvailable, ICImagingControl.DeviceFrameRate, ICImagingControl.DeviceFrameRates

<< ICImagingControl


ICImagingControl::DeviceFlipHorizontal

ICImagingControl.DeviceFlipHorizontal Property
Returns or sets the horizontal flipping of the live video image.
Syntax:
[VB.NET]
Public DeviceFlipHorizontal As Boolean

[C#]
public bool DeviceFlipHorizontal;
See also: ICImagingControl, DeviceFlipHorizontalAvailable, DeviceFlipVertical, DeviceFlipVerticalAvailable

<< ICImagingControl


ICImagingControl::DeviceFlipHorizontalAvailable

ICImagingControl.DeviceFlipHorizontalAvailable Property
This property determines whether horizontal flip is available for the currently selected device.
Syntax:
[VB.NET]
Public DeviceFlipHorizontalAvailable As Boolean

[C#]
public bool DeviceFlipHorizontalAvailable;
Limitations:

Run time only, read only.
See also: ICImagingControl, ICImagingControl.DeviceFlipHorizontal, ICImagingControl.DeviceFlipVertical, ICImagingControl.DeviceFlipVerticalAvailable

<< ICImagingControl


ICImagingControl::DeviceFlipVertical

ICImagingControl.DeviceFlipVertical Property
Returns or sets the vertical flipping of the live video image.
Syntax:
[VB.NET]
Public DeviceFlipVertical As Boolean

[C#]
public bool DeviceFlipVertival;
See also: ICImagingControl, DeviceFlipVerticalAvailable, DeviceFlipHorizontal, DeviceFlipHorizontalAvailable

<< ICImagingControl


ICImagingControl::DeviceFlipVerticalAvailable

ICImagingControl.DeviceFlipVerticalAvailable Property
This property determines whether vertical flip is available for the currently selected device.
Syntax:
[VB.NET]
Public DeviceFlipVerticalAvailable As Boolean

[C#]
public bool DeviceFlipVerticalAvailable;
Limitations:

Run time only, read only.
See also: ICImagingControl, ICImagingControl.DeviceFlipVertical, ICImagingControl.DeviceFlipHorizontal, ICImagingControl.DeviceFlipHorizontalAvailable

<< ICImagingControl


ICImagingControl::DeviceFrameRate

ICImagingControl.DeviceFrameRate Property
Returns or sets the desired frame rate (in frames per second) of the current video capture device.
Syntax:
[VB.NET]
Public DeviceFrameRate As Single

[C#]
public float DeviceFrameRate;
Limitations:

Only available when a device is open and valid.
Remarks:

A call to ICImagingControl.DeviceFrameRates retrieves all valid frame rates. Only valid frame rates may be set. If an invalid frame rate is specified, the default frame rate of the video capture device will be set instead.

The device frame rate depends on the current video format. Changing the ICImagingControl.VideoFormat property invalidates the device frame rate.

If the bandwidth is too low, the video capture device is not able to send frames according to the desired frame rate which is stored in DeviceFrameRate. The actual frame rate of the current device can be retrieved by using ICImagingControl.DeviceCurrentActualFrameRate.

Sample:

This example shows how to set a frame rate. Assume, that lstFrameRateList is a combo box, which was previously filled with the frame rates the video capture device supports:

[VB.NET]
Dim SelectedRate As Single

'  Get the selected frame rate from the combobox.
SelectedRate = IcImagingControl1.DeviceFrameRates(lstFrameRateList.SelectedIndex)

'  Stop the grabber before setting the new frame rate.
IcImagingControl1.LiveStop()

'  Now, set the new frame rate.
IcImagingControl1.DeviceFrameRate = SelectedRate

[C#]
//  Get the selected frame rate from the combobox.
float SelectedRate = ICImagingControl1.DeviceFrameRates[lstFrameRateList.SelectedIndex];

//  Stop the grabber before setting the new frame rate.
ICImagingControl1.LiveStop();

//  Now, set the new frame rate.
ICImagingControl1.DeviceFrameRate = SelectedRate;
See also: ICImagingControl, ICImagingControl.DeviceFrameRateAvailable, ICImagingControl.DeviceFrameRates, ICImagingControl.DeviceCurrentActualFrameRate

<< ICImagingControl


ICImagingControl::DeviceFrameRateAvailable

ICImagingControl.DeviceFrameRateAvailable Property
Returns True, if setting of frame rates is supported by the video capture device.
Syntax:
[VB.NET]
Public DeviceFrameRateAvailable As Boolean

[C#]
public bool DeviceFrameRateAvailable;
Limitations:

Run time only, read only. Only available when an ICImagingControl.Device is open and valid.

See also: ICImagingControl, ICImagingControl.DeviceFrameRates, ICImagingControl.DeviceFrameRate, ICImagingControl.DeviceCurrentActualFrameRate

<< ICImagingControl


ICImagingControl::DeviceFrameRates

ICImagingControl.DeviceFrameRates Property
Returns a collection of frame rates supported by the video capture device. May be empty if the device does not support frame rates.
Syntax:
[VB.NET]
Public DeviceFrameRates() As DeviceFrameRate

[C#]
public DeviceFrameRate[] DeviceFrameRates;
Limitations:

Run time only, read only. Only available when an ICImagingControl.Device is open and valid.

Sample:

This example shows how to fill the a combo box named lstFrameRateList with the framerates the video capture device supports:

[VB.NET]
'  Do not forget to clear the combobox.
lstFrameRateList.Items.Clear()

'  Get all frame rates from the DeviceFrameRates collection
'  and fill the combobox with the frame rates.
For Each Rate As Single In IcImagingControl1.DeviceFrameRates
    lstFrameRateList.Items.Add(Rate)
Next

[C#]
//  Do not forget to clear the combobox.
lstFrameRateList.Items.Clear();

//  Get all frame rates from the DeviceFrameRates collection
//  and fill the combobox with the frame rates.
foreach (float Rate in ICImagingControl1.DeviceFrameRates)
{
    lstFrameRateList.Items.Add(Rate);
}
See also: ICImagingControl, ICImagingControl.DeviceFrameRates, ICImagingControl.DeviceFrameRateAvailable, ICImagingControl.DeviceFrameRate, ICImagingControl.DeviceCurrentActualFrameRate

<< ICImagingControl


ICImagingControl::DeviceTrigger

ICImagingControl.DeviceTrigger Property
Enables/disables external triggering of the current video capture device.
Syntax:
[VB.NET]
Public DeviceTrigger As Boolean

[C#]
public bool DeviceTrigger;
Limitations:

Only available when a device is open and valid.
Remarks:

If the trigger is enabled, the video capture device will not send images if no trigger event occurs. This may block an application while it waits for MemorySnapImage to return.

See also: ICImagingControl, ICImagingControl.DeviceTriggerAvailable

<< ICImagingControl


ICImagingControl::DeviceTriggerAvailable

ICImagingControl.DeviceTriggerAvailable Property
Returns True if the device has an external trigger.
Syntax:
[VB.NET]
Public DeviceTriggerAvailable As Boolean

[C#]
public bool DeviceTriggerAvailable;
Limitations:

Run time only, read only.
See also: ICImagingControl, ICImagingControl.DeviceTrigger

<< ICImagingControl


ICImagingControl::DeviceValid

ICImagingControl.DeviceValid Property
Returns True when a device is open and valid, otherwise False.
Syntax:
[VB.NET]
Public DeviceValid As Boolean

[C#]
public bool DeviceValid;
Limitations:

Run time only, read only.
Remarks:

Since the video capture device can become invalid at any time, this property should be checked whether it returns True before performing an action on the ICImagingControl.

See also: ICImagingControl, ICImagingControl.Device

<< ICImagingControl


ICImagingControl::Devices

ICImagingControl.Devices Property
Returns a collection of all available video capture devices.
Syntax:
[VB.NET]
Public Devices() As Device

[C#]
public Device[] Devices;
Limitations:

Run time only, read only.
Sample:

This example displays all available video capture devices in a combo box. If no video capture devices are installed, the text "no devices found" will be displayed in the combo box. In this case the combo box will be disabled. The combo box for the video capture devices is named "cboVideoSource" in this example.

[VB.NET]
cboVideoSource.Items.Clear()

If IcImagingControl1.Devices.Length > 0 Then
    '  If devices have been found, add them to the combobox.
    Dim ICDevice As Device
    For Each ICDevice In IcImagingControl1.Devices
        cboVideoSource.Items.Add(ICDevice.Name)
    Next

    cboVideoSource.Enabled = True
    cboVideoSource.SelectedIndex = cboVideoSource.Items.IndexOf(IcImagingControl1.Device)
Else
    '  No devices have been found.
    cboVideoSource.Items.Add("no devices found")
    cboVideoSource.Enabled = False
    cboVideoSource.SelectedIndex = 0
End If

[C#]
cboVideoSource.Items.Clear();

if (ICImagingControl1.Devices.Length > 0)
{
    //  If devices have been found, add them to the combobox.
    foreach (Device Dev in ICImagingControl1.Devices)
    {
        cboVideoSource.Items.Add(Dev.Name);
    }

    cboVideoSource.Enabled = true;
    cboVideoSource.SelectedIndex = cboVideoSource.Items.IndexOf(ICImagingControl1.Device);
}
else
{
    //  No devices have been found.
    cboVideoSource.Items.Add("no devices found");
    cboVideoSource.Enabled = false;
    cboVideoSource.SelectedIndex = 0;
}

A complete example of how to get the video capture device properties can be found in Making Device Settings.

See also: ICImagingControl, Devices, Device

<< ICImagingControl


ICImagingControl::ExternalTransportAvailable

ICImagingControl.ExternalTransportAvailable Property
Returns True if the video capture device has an external transport interface (e.g. DV-Devices).
Syntax:
[VB.NET]
Public ExternalTransportAvailable As Boolean

[C#]
public bool ExternalTransportAvailable;
Limitations:

Read only.

<< ICImagingControl


ICImagingControl::ExternalTransportMode

ICImagingControl.ExternalTransportMode Property
Returns or sets the mode of the external transport device, if available.
Syntax:
[VB.NET]
Public ExternalTransportMode As ExternalTransportModes

[C#]
public ExternalTransportModes ExternalTransportMode
Limitations:

Run time only.
See also: ICImagingControl, ICImagingControl.ExternalTransportAvailable, ExternalTransportModes

<< ICImagingControl


ICImagingControl::ImageBitsPerPixel

ICImagingControl.ImageBitsPerPixel Property
Returns the bits per pixel of the buffers in the control. The bytes per pixel are calculated by dividing ImageBitsPerPixel by 8. The value of this property is determined by the value of the ICImagingControl.MemoryCurrentGrabberColorformat property.
Syntax:
[VB.NET]
Public ImageBitsPerPixel As Integer

[C#]
public int ImageBitsPerPixel;
Limitations:

Run time only, read only.
See also: ICImagingControl, ICImagingControl.MemoryCurrentGrabberColorformat

<< ICImagingControl


ICImagingControl::ImageBuffers

ICImagingControl.ImageBuffers Property
Returns a collection of ImageBuffers, which represent the buffers in the ringbuffer.
Syntax:
[VB.NET]
Public ImageBuffers As ImageBuffer()

[C#]
public ImageBuffer[] ImageBuffers;
Limitations:

Run time only, read only.
See also: ICImagingControl, ImageBuffers, ICImagingControl.ImageRingBufferSize

<< ICImagingControl


ICImagingControl::ImageHeight

ICImagingControl.ImageHeight Property
Returns the image height (in pixels) of the current video source.
Syntax:
[VB.NET]
Public ImageHeight As Integer

[C#]
public int ImageHeight;
Limitations:

Run time only, read only.
See also: ICImagingControl, ICImagingControl.ImageWidth

<< ICImagingControl


ICImagingControl::ImageRingBufferSize

ICImagingControl.ImageRingBufferSize Property
Returns or sets the size of the internal ring buffer. Must lie in the range [1,...[.
Syntax:
[VB.NET]
Public ImageRingBufferSize As Long

[C#]
public int ImageRingBufferSize;
Limitations:

Only available when a device is open and valid. Not available in live mode.

Remarks:

This method destroys the internal ring buffer if the new size is not equal to the current size of the ring buffer.

Exisiting references to ImageBuffer objects and collections are still valid, but they do not refer to the internal ring buffer anymore.

If there are global references to ImageBuffer objects or collections they have to be reassigned after setting this property.

See also: ICImagingControl, ICImagingControl.ImageBuffers

<< ICImagingControl


ICImagingControl::ImageWidth

ICImagingControl.ImageWidth Property
Returns the image width (in pixels) of the current video source.
Syntax:
[VB.NET]
Public ImageWidth As Integer

[C#]
public int ImageWidth;
Limitations:

Run time only, read only.
See also: ICImagingControl, ICImagingControl.ImageHeight

<< ICImagingControl


ICImagingControl::InputChannel

ICImagingControl.InputChannel Property
Returns or sets the input channel of the current video capture device. Available input channels can be enumerated using the InputChannels collection, which can be retrieved with a call to ICImagingControl.InputChannels.
Syntax:
[VB.NET]
Public InputChannel As String

[C#]
public string InputChannel;
Limitations:

Only available when a device is open and valid.
Remarks:

When the input channel is invalidated, the default input channel is selected, which depends on the current device.

The input channel depends on the current video capture device. So changing the ICImagingControl.Device property, will invalidate the input channel.

Note that input channels may not be supported on all video devices. While a frame grabber usually has several inputs to choose from, a camera that is connected directly to a USB or FireWire port will not have this feature. The Imaging Control's ICImagingControl.InputChannelAvailable can be used to determine whether input channels are supported.

Input channels may be set in live mode.

Sample:

This example selects the first channel supported by the current video capture device:

[VB.NET]
Dim Inp As InputChannel
Inp = IcImagingControl1.InputChannels(0)
IcImagingControl1.InputChannel = Inp.Name

[C#]
InputChannel Inp = ICImagingControl1.InputChannels[0];
ICImagingControl1.InputChannel = Inp.Name;

Selecting devices, input channels, video norms and video formats is shown in the Making Device Settings chapter.

See also: ICImagingControl, ICImagingControl.InputChannelAvailable, ICImagingControl.InputChannels, InputChannels

<< ICImagingControl


ICImagingControl::InputChannelAvailable

ICImagingControl.InputChannelAvailable Property
Returns True if the current video capture device supports input channels.
Syntax:
[VB.NET]
Public InputChannelAvailable As Boolean

[C#]
public bool InputChannelAvailable;
Limitations:

Run time only, read only. Only available when a device is open and valid.

See also: ICImagingControl, ICImagingControl.InputChannel, ICImagingControl.InputChannels

<< ICImagingControl


ICImagingControl::InputChannels

ICImagingControl.InputChannels Property
Returns a collection of available input channels for the current video capture device.
Syntax:
[VB.NET]
Public InputChannels As InputChannel()

[C#]
public InputChannel[] InputChannels;
Limitations:

Run time only, read only. Only available when a device is open and valid.

Sample:

This example displays all available input channels in a combo box. If no input channels are available, the text "n/a" will be displayed in the combo box. In this case the combo box will be disabled. The combo box for the input channels is named "cboInputChannel" in this example.

[VB.NET]
cboInputChannel.Items.Clear()
If IcImagingControl1.InputChannelAvailable Then
    If IcImagingControl1.InputChannels.Length > 0 Then
        '  If input channels have been found,
        '  add them to the combobox.
        For Each Item As InputChannel In IcImagingControl1.InputChannels
            cboInputChannel.Items.Add(Item.Name)
        Next

        cboInputChannel.SelectedIndex = cboInputChannel.Items.IndexOf(IcImagingControl1.InputChannel)
        cboInputChannel.Enabled = True
    End If
Else
    '  No input channels have been found.
    cboInputChannel.Items.Add("n/a")
    cboInputChannel.Enabled = False
    cboInputChannel.SelectedIndex = 0
End If

[C#]
cboInputChannel.Items.Clear();
if (ICImagingControl1.InputChannelAvailable)
{
    //  If input channels have been found, add them to the combobox.
    foreach (InputChannel Item in ICImagingControl1.InputChannels)
    {
        cboInputChannel.Items.Add(Item.Name);
    }

    cboInputChannel.SelectedIndex = cboInputChannel.Items.IndexOf(ICImagingControl1.InputChannel);
    cboInputChannel.Enabled = true;
}
else
{
    //  No input channels have been found.
    cboInputChannel.Items.Add("n/a");
    cboInputChannel.Enabled = false;
    cboInputChannel.SelectedIndex = 0;
}

A complete example of how to get the video capture device properties can be found in the Making Device Settings chapter.

See also: ICImagingControl, InputChannels, ICImagingControl.InputChannelAvailable, ICImagingControl.InputChannel

<< ICImagingControl


ICImagingControl::IsLivePrepared

ICImagingControl.IsLivePrepared Property
Returns whether the image stream was is prepared after a previous call to LivePrepare, or LiveSuspend.
Syntax:
[VB.NET]
Public IsLivePrepared As Boolean

[C#]
public bool IsLivePrepared;
Limitations:

Read only.
Information:

Introduced in version 3.1
See also: ICImagingControl.LivePrepare, ICImagingControl.LiveSuspend

<< ICImagingControl


ICImagingControl::LiveCaptureContinuous

ICImagingControl.LiveCaptureContinuous Property
Enables/disables the continuous capture mode. In this mode ICImagingControl.MemorySnapImage may not be called, because all frames are copied to the ring buffer automatically. After an image has been copied completely to a buffer, an ICImagingControl.ImageAvailable event is sent. If an ICImagingControl.ImageAvailable event is currently processed, a new event will not be sent.
Syntax:
[VB.NET]
Public LiveCaptureContinuous As Boolean

[C#]
public bool LiveCaptureContinuous;
Limitations:

Has only an effect if set before a call to ICImagingControl.LiveStart.
Remarks:

The value of the ICImagingControl.LiveCaptureLastImage property is ignored.

Sample:

See Displaying Buffers on the ImageAvailable Event for an example on how to control the display of images buffers in the live capture continuous mode.

See also: ICImagingControl, ICImagingControl.LiveStart, ICImagingControl.MemorySnapImage, ICImagingControl.ImageAvailable

<< ICImagingControl


ICImagingControl::LiveCaptureLastImage

ICImagingControl.LiveCaptureLastImage Property
Enables/disables the automatic call to ICImagingControl.MemorySnapImage in ICImagingControl.LiveStop. This property should be set to True if ICImagingControl is to display the last frame after LiveStop has been called.
Syntax:
[VB.NET]
Public LiveCaptureLastImage As Boolean

[C#]
public bool LiveCaptureLastImage;
Limitations:

Only affects the LiveStop call.
Remarks:

If the ICImagingControl.LiveCaptureContinuous property is enabled, the LiveCaptureLastImage property is ignored.

See also: ICImagingControl, ICImagingControl.MemorySnapImage, ICImagingControl.LiveStop

<< ICImagingControl


ICImagingControl::LiveCapturePause

ICImagingControl.LiveCapturePause Property
Returns or sets the pause for AVI capture.
Syntax:
[VB.NET]
Public LiveCapturePause As Boolean

[C#]
public bool LiveCapturePause;
Remarks:

The LiveCapturePause property is used to pause and restart AVI capture.

The LiveCapturePause property is used to pause and restart the image stream that goes to the sink. The sink is either an image buffers collection or an AVI file. The live display is not affected by this property. The LiveCapturePause property can be used to start an AVI recording when an event occurs (i.e. a click on a button) without latency. To do so, you have to set LiveCapturePause to true prior to a call to AviStartCapture. The call to AviStartCapture initializes the image stream and starts the live display (if the live display is enabled). Now, setting LiveCapturePause to False starts the AVI recording immediately because the image is already initialized.

If the LiveCapturePause property is set to True, the image stream going to the sink is paused. This means that the live display is not affected and the image stream remains initialized. LiveCapturePause may be set to True at any time and as often as you like.

If the LiveCapturePause property is set to False, the image stream going to the sink is started immediately if LiveStart was set to True or AviStartCapture was previously called.

If LiveCapturePause is set to True, while an image stream to an image buffers collection is active, MemorySnapImage and MemorySnapImageSequence are paused. This is typically the case when no AVI recording is taking place. if the timeout elapse before LiveCapturePause is set to False, MemorySnapImage and MemorySnapImageSequence return and report the timeout.

See also: ICImagingControl, ICImagingControl.AviStartCapture, ICImagingControl.AviStopCapture, ICImagingControl.MemorySnapImage, ICImagingControl.MemorySnapImageSequence, ICImagingControl.LivePause

<< ICImagingControl


ICImagingControl::LiveDisplay

ICImagingControl.LiveDisplay Property
Enables/disables live display in the control window. If live display is disabled, the image buffers may be shown by a call to ICImagingControl.Display.
Syntax:
[VB.NET]
Public LiveDisplay As Boolean

[C#]
public bool LiveDisplay;
Limitations:

Only affects the ICImagingControl.LiveStart call. So setting a new value in live mode does not affect the display.

Sample:

See Displaying Buffers on the ImageAvailable Event for an example on how to do process live display.

See also: ICImagingControl, ICImagingControl.Display, ICImagingControl.DisplayImageBuffer, ICImagingControl.LiveStart

<< ICImagingControl


ICImagingControl::LiveDisplayDefault

ICImagingControl.LiveDisplayDefault Property
Returns or enables the use of the default size and position of the video display window.
Syntax:
[VB.NET]
Public LiveDisplayDefault As Boolean

[C#]
public bool LiveDisplayDefault;
Remarks:

Whether the size of the live video window can be changed or not can be toggled with the LiveDisplayDefault property. If LiveDisplayDefault returns True, the size of the live video window can not be adjusted. If LiveDisplayDefault is set to False, the size and position of the live video window can be adjusted to the application's needs.

If the LiveDisplayDefault is set to True, the values of LiveDisplayHeight and LiveDisplayWidth are reset to the video format's height and width. Also, the values of LiveDisplayTop and LiveDisplayLeft are reset to 0.

See also: ICImagingControl, ICImagingControl.LiveDisplayHeight, ICImagingControl.LiveDisplayLeft, ICImagingControl.LiveDisplayTop, ICImagingControl.LiveDisplayWidth, ICImagingControl.LiveDisplayZoomFactor, ICImagingControl.ScrollBarsEnabled

<< ICImagingControl


ICImagingControl::LiveDisplayHeight

ICImagingControl.LiveDisplayHeight Property
Returns or sets the height of the video display window.
Syntax:
[VB.NET]
Public LiveDisplayHeight As Integer

[C#]
public int LiveDisplayHeight;
Remarks:

The LiveDisplayHeight property is used to set a new height for the display window of the live video. If LiveDisplayHeight is set to a value different from the video format's height, the video image is distorted.

If the LiveDisplayHeight and the LiveDisplayWidth properties are changed, but the video image's ratio is preserved, the live video appears to be zoomed in or out. With these properties, the live video image can be fitted into IC Imaging Control's window.

Passing a value to LiveDisplayHeight takes only an effect, if the LiveDisplayDefault property was set to False. If the LiveDisplayDefault property is set to True, the LiveDisplayHeight property's value is reset to the video formats height.

The LiveDisplayHeight property's unit is pixel.

Sample:

This example demonstrates how to fit the live video display in IC Imaging Control's window.

[VB.NET]
With IcImagingControl1
    '  Disable the default values of the live display.
    .LiveDisplayDefault = False

    '  Set the width and height of the live video display to
    '  the width and height of IC Imaging Control. Now, the
    '  live video image fits into IC Imaging Control's window.
    .LiveDisplayHeight = .Height
    .LiveDisplayWidth = .Width

    '  Start the live video to see the result.
    .LiveStart()
End With

[C#]
//  Disable the default values of the live display.
ICImagingControl1.LiveDisplayDefault = false;

//  Set the width and height of the live video display to
//  the width and height of IC Imaging Control. Now, the
//  live video image fits into IC Imaging Control's window.
ICImagingControl1.LiveDisplayHeight = ICImagingControl1.Height;
ICImagingControl1.LiveDisplayWidth = ICImagingControl1.Width;

//  Start the live video to see the result.
ICImagingControl1.LiveStart();
See also: ICImagingControl, ICImagingControl.LiveDisplayDefault, ICImagingControl.LiveDisplayLeft, ICImagingControl.LiveDisplayTop, ICImagingControl.LiveDisplayWidth, ICImagingControl.LiveDisplayZoomFactor, ICImagingControl.ScrollBarsEnabled

<< ICImagingControl


ICImagingControl::LiveDisplayLeft

ICImagingControl.LiveDisplayLeft Property
Returns or sets the left position of the video display window in IC Imaging Control's window.
Syntax:
[VB.NET]
Public LiveDisplayLeft As Integer

[C#]
public int LiveDisplayLeft;
Remarks:

The LiveDisplayLeft property is used to move the video display window in IC Imaging Control's window. The value passed to LiveDisplayLeft is relative to the upper left corner of IC Imaging Control.

Passing a value to LiveDisplayLeft takes an effect, even if the LiveDisplayDefault property returns True.

If the LiveDisplayDefault property is set to True, the LiveDisplayLeft property's value is reset to 0.

The LiveDisplayLeft property's unit is pixel. It defaults to 0.

See also: ICImagingControl, ICImagingControl.LiveDisplayDefault, ICImagingControl.LiveDisplayHeight, ICImagingControl.LiveDisplayTop, ICImagingControl.LiveDisplayWidth, ICImagingControl.LiveDisplayZoomFactor, ICImagingControl.ScrollBarsEnabled

<< ICImagingControl


ICImagingControl::LiveDisplayTop

ICImagingControl.LiveDisplayTop Property
Returns or sets the top position of the video display window in IC Imaging Control's window.
Syntax:
[VB.NET]
Public Integer LiveDisplayTop(Top As Integer)

[C#]
public int LiveDisplayTop(int Top);
Remarks:

The LiveDisplayTop property is used to move the video display window in IC Imaging Control's window. The value passed to LiveDisplayTop is relative to the upper left corner of IC Imaging Control.

Passing a value to LiveDisplayTop takes an effect, even if the LiveDisplayDefault property returns True.

If the LiveDisplayDefault property is set to True, the LiveDisplayTop property's value is reset to 0.

The LiveDisplayTop property's unit is pixel. It defaults to 0.

See also: ICImagingControl, ICImagingControl.LiveDisplayDefault, ICImagingControl.LiveDisplayHeight, ICImagingControl.LiveDisplayLeft, ICImagingControl.LiveDisplayWidth, ICImagingControl.LiveDisplayZoomFactor, ICImagingControl.ScrollBarsEnabled

<< ICImagingControl


ICImagingControl::LiveDisplayWidth

ICImagingControl.LiveDisplayWidth Property
Returns or sets the width of the video display window.
Syntax:
[VB.NET]
Public LiveDisplayWidth As Integer

[C#]
public int LiveDisplayWidth;
Remarks:

The LiveDisplayWidth property is used to set a new width for the display window of the live video. If LiveDisplayWidth is set to a value different from the video format's width, the video image is distorted.

If the LiveDisplayHeight and the LiveDisplayWidth properties are changed, but the video image's ratio is preserved, the live video appears to be zoomed in or out. With these properties, the live video image can be fitted into IC Imaging Control's window.

Passing a value to LiveDisplayWidth takes only an effect, if the LiveDisplayDefault property was set to False. If the LiveDisplayDefault property is set to True, the LiveDisplayWidth property's value is reset to the video formats width.

The LiveDisplayWidth property's unit is pixel.

Sample:

This example demonstrates how to fit the live video display in IC Imaging Control's window.

[VB.NET]
With IcImagingControl1
    '  Disable the default values of the live display.
    .LiveDisplayDefault = False

    '  Set the width and height of the live video display to
    '  the width and height of IC Imaging Control. Now, the
    '  live video image fits into IC Imaging Control's window.
    .LiveDisplayHeight = .Height
    .LiveDisplayWidth = .Width

    '  Start the live video to see the result.
    .LiveStart()
End With

[C#]
//  Disable the default values of the live display.
ICImagingControl1.LiveDisplayDefault = false;

//  Set the width and height of the live video display to
//  the width and height of IC Imaging Control. Now, the
//  live video image fits into IC Imaging Control's window.
ICImagingControl1.LiveDisplayHeight = ICImagingControl1.Height;
ICImagingControl1.LiveDisplayWidth = ICImagingControl1.Width;

//  Start the live video to see the result.
ICImagingControl1.LiveStart();
See also: ICImagingControl, ICImagingControl.LiveDisplayDefault, ICImagingControl.LiveDisplayHeight, ICImagingControl.LiveDisplayLeft, ICImagingControl.LiveDisplayTop, ICImagingControl.LiveDisplayZoomFactor, ICImagingControl.ScrollBarsEnabled

<< ICImagingControl


ICImagingControl::LiveDisplayZoomFactor

ICImagingControl.LiveDisplayZoomFactor Property
Returns or sets the zoom factor of the video display window.
Syntax:
[VB.NET]
Public LiveDisplayZoomFactor As Double

[C#]
public double LiveDisplayZoomFactor;
Remarks:

The LiveDisplayZoomFactor property is used to zoom the video display window in IC Imaging Control's window.

Passing a value to LiveDisplayZoomFactor only takes an effect, if the LiveDisplayDefault property returns False.

If the LiveDisplayDefault property is set to True, the LiveDisplayZoomFactor property's value is reset to 1.0.

Changing the value of the LiveDisplayZoomFactor property causes scrollbars to be adjusted anew. It also changes the values of LiveDisplayHeight and LiveDisplayWidth.

Setting the LiveDisplayZoomFactor property will restore the original video format's image ratio.

The LiveDisplayZoomFactor defaults to 1.0. Valid values must be greater than 0. 1.0 means the original size of the video image.

See also: ICImagingControl, ICImagingControl.LiveDisplayDefault, ICImagingControl.LiveDisplayHeight, ICImagingControl.LiveDisplayLeft, ICImagingControl.LiveDisplayTop, ICImagingControl.LiveDisplayWidth, ICImagingControl.ScrollBarsEnabled

<< ICImagingControl


ICImagingControl::LiveVideoRunning

ICImagingControl.LiveVideoRunning Property
Indicates whether a live video is running, i.e. has been started with the LiveStart Method.
Syntax:
[VB.NET]
Public LiveVideoRunning As Boolean

[C#]
public bool LiveVideoRunning;
Limitations:

Run time only, read only.
See also: ICImagingControl, ICImagingControl.LiveStart, ICImagingControl.LiveStop

<< ICImagingControl


ICImagingControl::MediaStreamContainers

ICImagingControl.MediaStreamContainers Property
Returns a list containing all available MediaStreamContainers.
Syntax:
[VB.NET]
Public MediaStreamContainers() As MediaStreamContainer

[C#]
public MediaStreamContainer[] MediaStreamContainers;
Limitations:

Run time only, read only.

Information:

Introduced in version 3.0
See also: ICImagingControl, MediaStreamContainer

<< ICImagingControl


ICImagingControl::MemoryCurrentGrabberColorformat

ICImagingControl.MemoryCurrentGrabberColorformat Property
Determines the color format of the image buffers in the internal ring buffer.
Syntax:
[VB.NET]
Public MemoryCurrentGrabberColorformat As ICImagingControlColorformats

[C#]
public ICImagingControlColorformats MemoryCurrentGrabberColorformat;
Limitations:

Not available in live mode.
See also: ICImagingControl, ImageBuffer, ICImagingControlColorformats

<< ICImagingControl


ICImagingControl::MemoryPixelFormat

ICImagingControl.MemoryPixelFormat Property
Sets the pixel format of the ring buffer.
Syntax:
[VB.NET]
Public MemoryPixelFormat As System.Drawing.Imaging.PixelFormat

[C#]
public System.Drawing.Imaging.PixelFormat MemoryPixelFormat;
Remarks:

The pixel format of the ring buffer is also accessible with ICImagingControl.MemoryCurrentGrabberColorformat.

Information:

Introduced in version 2.0
See also: ICImagingControl, ICImagingControl.MemoryCurrentGrabberColorformat

<< ICImagingControl


ICImagingControl::OverlayBitmap

ICImagingControl.OverlayBitmap Property
Returns an OverlayBitmap object.
Syntax:
[VB.NET]
Public OverlayBitmap As OverlayBitmap

[C#]
public OverlayBitmap OverlayBitmap
Limitations:

Run time only, read only.
Remarks:

The OverlayBitmap object is used for drawing and text operations on the live video.

See also: ICImagingControl, OverlayBitmap Object

<< ICImagingControl


ICImagingControl::OverlayUpdateEventEnable

ICImagingControl.OverlayUpdateEventEnable Property
This property is used to return or set whether the overlay update event should be called by IC Imaging Control.
Syntax:
[VB.NET]
Public OverlayUpdateEventEnable As Boolean

[C#]
public bool OverlayUpdateEventEnable
Limitations:

Run time only.
Remarks:

The OverlayUpdateEvent property is set to True per default.

Sample:

This example demonstrates how to check, whether the overlay update event should be called.

[VB.NET]
If IcImagingControl1.DeviceValid = True Then
    '  Check whether the overlay update event is enabled.
    If IcImagingControl1.OverlayUpdateEventEnable = False Then
        '  Enable the overlay update event.
        IcImagingControl1.OverlayUpdateEventEnable = True
    End If
End If

[C#]
if (ICImagingControl1.DeviceValid)
{
    //  Check whether the overlay update event is enabled.
    if ( !ICImagingControl1.OverlayUpdateEventEnable )
    {
        //  Enable the overlay update event.
        ICImagingControl1.OverlayUpdateEventEnable = true;
    }
}
See also: ICImagingControl, OverlayUpdate event, OverlayBitmap Class

<< ICImagingControl


ICImagingControl::ReferenceTimeCurrent

ICImagingControl.ReferenceTimeCurrent Property
Returns the current reference time.
Syntax:
[VB.NET]
Public ReferenceTimeCurrent As Double

[C#]
public double ReferenceTimeCurrent;
Remarks:

The property's unit is seconds.

If the ReferenceTimeCurrent is retrieved while the live video is not running, the error message "Run-time error '20' This function cannot be called if livemode is inactive" is issued.

Sample:

This example demonstrates how to show a live video for five seconds.

[VB.NET]
If IcImagingControl1.DeviceValid = True Then
    With IcImagingControl1
        .LiveStart()
        While .ReferenceTimeCurrent - .ReferenceTimeStart < 5
            System.Diagnostics.Trace.WriteLine(.ReferenceTimeCurrent - .ReferenceTimeStart)
        End While
        .LiveStop()
    End With
End If

[C#]
if (ICImagingControl1.DeviceValid)
{
    ICImagingControl1.LiveStart();
    while (ICImagingControl1.ReferenceTimeCurrent - ICImagingControl1.ReferenceTimeStart < 5)
    {
        System.Diagnostics.Trace.WriteLine(ICImagingControl1.ReferenceTimeCurrent - ICImagingControl1.ReferenceTimeStart);
    }
    ICImagingControl1.LiveStop();
}
See also: ICImagingControl, ICImagingControl.LiveStart, ICImagingControl.ReferenceTimeStart

<< ICImagingControl


ICImagingControl::ReferenceTimeStart

ICImagingControl.ReferenceTimeStart Property
Returns the reference time at which the image stream was started.
Syntax:
[VB.NET]
Public ReferenceTimeStart As Double

[C#]
public double ReferenceTimeStart;
Remarks:

If ICImagingControl.LiveStart has been called, all necessary filters are connected. This could take some time. After the all filters have been connected, the video stream started. This is the time that is returned by the ReferenceTimeStart property.

The property's unit is seconds.

If the ReferenceTimeStart is retrieved while the live video is not running, the error message "Run-time error '20' This function cannot be called if livemode is inactive" is displayed.

Sample:

This example demonstrates how to show a live video for five seconds.

[VB.NET]
If IcImagingControl1.DeviceValid = True Then
    With IcImagingControl1
        .LiveStart()
        While .ReferenceTimeCurrent - .ReferenceTimeStart < 5
            System.Diagnostics.Trace.WriteLine(.ReferenceTimeCurrent - .ReferenceTimeStart)
        End While
        .LiveStop()
    End With
End If

[C#]
if (ICImagingControl1.DeviceValid)
{
    ICImagingControl1.LiveStart();
    while (ICImagingControl1.ReferenceTimeCurrent - ICImagingControl1.ReferenceTimeStart < 5)
    {
        System.Diagnostics.Trace.WriteLine(ICImagingControl1.ReferenceTimeCurrent - ICImagingControl1.ReferenceTimeStart);
    }
    ICImagingControl1.LiveStop();
}
See also: ICImagingControl, ICImagingControl.LiveStart, ICImagingControl.ReferenceTimeCurrent

<< ICImagingControl


ICImagingControl::ScrollBarsEnabled

ICImagingControl.ScrollBarsEnabled Property
Returns whether scrollbars are enabled or enables/disables scrollbars.
Syntax:
[VB.NET]
Public ScrollBarsEnabled As Boolean

[C#]
public bool ScrollBarsEnabled;
Remarks:

If the ScrollbarsEnabled property is set to True and the window of IC Imaging Control is smaller than the live video window, scrollbars are displayed at the borders of Imaging Control. With the scrollbars, the user can move the live video in IC Imaging Control's window.

If the live video image is scrolled, the event ScrollableControl.Scroll is raised.

The ScrollbarsEnabled property defaults to False. This means, the scrollbars are not visible.

See also: ICImagingControl, ICImagingControl.LiveDisplayHeight, ICImagingControl.LiveDisplayWidth

<< ICImagingControl


ICImagingControl::SinkCompatibilityMode

ICImagingControl.SinkCompatibilityMode Property
SinkCompatibilityMode is for compatibility to IC Imaging Control 2.1.
Syntax:
[VB.NET]
Public SinkCompatibilityMode As Boolean

[C#]
public bool SinkCompatibilityMode;
Remarks:

The default setting is True. If it is set to False, then the application is faster when a new video format is set.

If a frame filter is in use, then this property is automatically set to False.

Information:

Introduced in version 3.0
See also: ICImagingControl

<< ICImagingControl


ICImagingControl::VideoFormat

ICImagingControl.VideoFormat Property
Returns or sets the video format of the current video capture device. A list of available video formats can be obtained using the VideoFormats collection, which can be retrieved with a call to ICImagingControl.VideoFormats.
Syntax:
[VB.NET]
Public VideoFormat As String

[C#]
public string VideoFormat;
Limitations:

Only available when a device is open and valid. Not available in live mode.
Remarks:

When the video format is invalidated, the first available video format for the device is selected.

The video format depends on the current video norm. So changing the ICImagingControl.VideoNorm property, will invalidate the video format.

Changing the video format invalidates the ICImagingControl.DeviceFrameRate property.

Sample:

This example selects the first video format that is supported by the current video capture device:

[VB.NET]
Dim Fmt As VideoFormat
Fmt = IcImagingControl1.VideoFormats(0)
IcImagingControl1.VideoFormat = Fmt.Name

[C#]
VideoFormat Fmt = ICImagingControl1.VideoFormats[0];
ICImagingControl1.VideoFormat = Fmt.Name;
See also: ICImagingControl, ICImagingControl.VideoFormats, VideoFormats

<< ICImagingControl


ICImagingControl::VideoFormatDescs

ICImagingControl.VideoFormatDescs Property
Returns a list of VideoFormatDesc objects describing all video formats supported by the current video capture device.
Syntax:
[VB.NET]
Public VideoFormatDescs As VideoFormatDesc()

[C#]
public VideoFormatDesc[] VideoFormatDescs;
Limitations:

Read only.
Information:

Introduced in version 3.2
See also: VideoFormatDesc

<< ICImagingControl


ICImagingControl::VideoFormats

ICImagingControl.VideoFormats Property
Returns a collection of available video formats for the current device and video norm.
Syntax:
[VB.NET]
Public VideoFormats As VideoFormat()

[C#]
public VideoFormat[] VideoFormats;
Limitations:

Run time only, read only. Only available when a device is open and valid. Not available in live mode.

Sample:

This example displays all available video formats of the current selected video capture device in a combo box. If no video formats are available, the text "n/a" will be displayed in the combo box . In this case the combo box will be disabled. The combo box for the video formats is named "cboVideoFormat" in this example.

[VB.NET]
cboVideoFormat.Items.Clear()
If IcImagingControl1.VideoFormats.Length > 0 Then
    '  If video formats have been found, add them to the combobox.
    For Each Item As VideoFormat In IcImagingControl1.VideoFormats
        cboVideoFormat.Items.Add(Item.Name)
    Next
    cboVideoFormat.Enabled = True

    cboVideoFormat.SelectedIndex = cboVideoFormat.Items.IndexOf(IcImagingControl1.VideoFormat)
Else
    '  No video formats have been found.
    cboVideoFormat.Items.Add("n/a")
    cboVideoFormat.Enabled = False
    cboVideoFormat.SelectedIndex = 0
End If

[C#]
cboVideoFormat.Items.Clear();
if (ICImagingControl1.VideoFormats.Length > 0)
{
    //  If video formats have been found, add them to the combobox.
    foreach (VideoFormat Item in ICImagingControl1.VideoFormats)
    {
        cboVideoFormat.Items.Add(Item.Name);
    }
    cboVideoFormat.Enabled = true;

    cboVideoFormat.SelectedIndex = cboVideoFormat.Items.IndexOf(ICImagingControl1.VideoFormat);
}
else
{
    //  No video formats have been found.
    cboVideoFormat.Items.Add("n/a");
    cboVideoFormat.Enabled = false;
    cboVideoFormat.SelectedIndex = 0;
}

A complete example of how to get the video capture device properties can be found in Making Device Settings.

See also: ICImagingControl, VideoFormats, VideoFormat

<< ICImagingControl


ICImagingControl::VideoNorm

ICImagingControl.VideoNorm Property
Returns or sets the video norm of the current video capture device. A list of available video norms can be obtained using the VideoNorms collection, which can be retrieved with by calling ICImagingControl.VideoNorms.
Syntax:
[VB.NET]
Public VideoNorm As String

[C#]
public string VideoNorm;
Limitations:

Only available when a device is open and valid. Not available in live mode.

Remarks:

When the video norm is invalidated, the default video norm is selected, which depends on the device.

The video norm depends on the current device. So changing the ICImagingControl.Device property, will invalidate the video norm.

Changing the video norm invalidates the ICImagingControl.VideoFormat property.

Note that video norms may not be supported on all video capture devices. A video camera that is connected to a frame grabber usually supports either NTSC or PAL as a video norm, and the correct one must be selected in order to get an image from the grabber. Cameras that are connected directly via USB or FireWire ports usually do not use a video norm. The ICImagingControl.VideoNormAvailable property can be used to determine whehter video norms are supported.

Sample:

This example selects the first video norm supported by the current video capture device :

[VB.NET]
cboVideoFormat.Items.Clear()
If IcImagingControl1.VideoFormats.Length > 0 Then
    '  If video formats have been found, add them to the combobox.
    For Each Item As VideoFormat In IcImagingControl1.VideoFormats
        cboVideoFormat.Items.Add(Item.Name)
    Next
    cboVideoFormat.Enabled = True

    cboVideoFormat.SelectedIndex = cboVideoFormat.Items.IndexOf(IcImagingControl1.VideoFormat)
Else
    '  No video formats have been found.
    cboVideoFormat.Items.Add("n/a")
    cboVideoFormat.Enabled = False
    cboVideoFormat.SelectedIndex = 0
End If

[C#]
cboVideoFormat.Items.Clear();
if (ICImagingControl1.VideoFormats.Length > 0)
{
    //  If video formats have been found, add them to the combobox.
    foreach (VideoFormat Item in ICImagingControl1.VideoFormats)
    {
        cboVideoFormat.Items.Add(Item.Name);
    }
    cboVideoFormat.Enabled = true;

    cboVideoFormat.SelectedIndex = cboVideoFormat.Items.IndexOf(ICImagingControl1.VideoFormat);
}
else
{
    //  No video formats have been found.
    cboVideoFormat.Items.Add("n/a");
    cboVideoFormat.Enabled = false;
    cboVideoFormat.SelectedIndex = 0;
}
See also: ICImagingControl, ICImagingControl.VideoNormAvailable, ICImagingControl.VideoNorms, VideoNorms

<< ICImagingControl


ICImagingControl::VideoNormAvailable

ICImagingControl.VideoNormAvailable Property
Returns whether the current device supports video norms.
Syntax:
[VB.NET]
Public VideoNormAvailable As Boolean

[C#]
public bool VideoNormAvailable;
Limitations:

Run time only, read only. Only available when a device is open and valid.

See also: ICImagingControl, ICImagingControl.VideoNorm, ICImagingControl.VideoNorms

<< ICImagingControl


ICImagingControl::VideoNorms

ICImagingControl.VideoNorms Property
Returns a collection of available video norms for the current device.
Syntax:
[VB.NET]
Public VideoNorms As VideoNorm()

[C#]
public VideoNorm[] VideoNorms;
Limitations:

Run time only, read only. Only available when a device is open and valid.

Sample:

This example displays all available video norms supported by the current selected video capture device in a combo box. If no video norms are availalbe, the text "n/a" will be displayed in the combo box. In this case the combo box will be disabled. If a device is valid, it must have a video norm anyway. The combo box for the video norms is named "cboVideoNorm" in this example.

[VB.NET]
cboVideoFormat.Items.Clear()
If IcImagingControl1.VideoFormats.Length > 0 Then
    '  If video formats have been found, add them to the combobox.
    For Each Item As VideoFormat In IcImagingControl1.VideoFormats
        cboVideoFormat.Items.Add(Item.Name)
    Next
    cboVideoFormat.Enabled = True

    cboVideoFormat.SelectedIndex = cboVideoFormat.Items.IndexOf(IcImagingControl1.VideoFormat)
Else
    '  No video formats have been found.
    cboVideoFormat.Items.Add("n/a")
    cboVideoFormat.Enabled = False
    cboVideoFormat.SelectedIndex = 0
End If

[C#]
cboVideoFormat.Items.Clear();
if (ICImagingControl1.VideoFormats.Length > 0)
{
    //  If video formats have been found, add them to the combobox.
    foreach (VideoFormat Item in ICImagingControl1.VideoFormats)
    {
        cboVideoFormat.Items.Add(Item.Name);
    }
    cboVideoFormat.Enabled = true;

    cboVideoFormat.SelectedIndex = cboVideoFormat.Items.IndexOf(ICImagingControl1.VideoFormat);
}
else
{
    //  No video formats have been found.
    cboVideoFormat.Items.Add("n/a");
    cboVideoFormat.Enabled = false;
    cboVideoFormat.SelectedIndex = 0;
}

A complete example of how to get the video capture device properties can be found in Making Device Settings.

See also: ICImagingControl, VideoNorms, VideoNormAvailable, VideoNorm

<< ICImagingControl


ICImagingControl::AviStartCapture

ICImagingControl.AviStartCapture Method
This method writes a compressed AVI file to the computer's hard disk.
Syntax:
[VB.NET]
Public Sub AviStartCapture(Filename As String, Compressor As AviCompressor)
Public Sub AviStartCapture(Filename As String, CompressorName As String)

[C#]
public void AviStartCapture(string Filename, AviCompressor Compressor);
public void AviStartCapture(string Filename, string CompressorName);

Parameter | Description
Filename | Specifies a filename for the AVI file.
Compressor | Specifies a video compressor. A list of available compressors can be obtained from an AviCompressors collection.
CompressorName | Specifies the name of a video compressor. A list of available compressors can be obtained from an AviCompressors collection.
Remarks:

During capture the only allowed operation with ICImagingControl is to pause and stop capture.

It is suggested to disable the live display, by assigning ICImagingControl.LiveDisplay property to False, in order to save performance.

See also: ICImagingControl, ICImagingControl.AviCompressors, AviCompressor, AviCompressors, ICImagingControl.AviStopCapture, ICImagingControl.LiveCapturePause

<< ICImagingControl


ICImagingControl::AviStopCapture

ICImagingControl.AviStopCapture Method
This method stops writing an AVI file.
Syntax:
[VB.NET]
Public Sub AviStopCapture()

[C#]
public void AviStopCapture();
See also: ICImagingControl, ICImagingControl.AviCompressors, AviCompressor, AviCompressors, ICImagingControl.AviStartCapture, ICImagingControl.LiveCapturePause

<< ICImagingControl


ICImagingControl::Display

ICImagingControl.Display Method
Displays the current image buffer in IC Imaging Control's window.
Syntax:
[VB.NET]
Public Sub Display()

[C#]
public void Display();
Remarks:

This method can only be used, if the property ICImagingControl.LiveDisplay was set to False. In this case, IC Imaging Control would not display the live video. When the Display method is called, only the current frame in the image buffer is displayed.

See also: ICImagingControl, ICImagingControl.LiveDisplay, ICImagingControl.DisplayImageBuffer

<< ICImagingControl


ICImagingControl::DisplayImageBuffer

ICImagingControl.DisplayImageBuffer Method
When the property ICImagingControl.LiveDisplay is False , then a call to ICImagingControl.DisplayImageBuffer displays the given buffer in the control window
Syntax:
[VB.NET]
Public Sub DisplayImageBuffer(Buffer As ImageBuffer)

[C#]
public void DisplayImageBuffer(ImageBuffer Buffer);

Parameter | Description
Buffer | Specifies the buffer to display.
Limitations:

Run time only, read only.
See also: ICImagingControl, ICImagingControl.LiveDisplay, ImageBuffer, ICImagingControl.Display

<< ICImagingControl


ICImagingControl::LiveStart

ICImagingControl.LiveStart Method
This method starts the processing of images delivered by the video capture device.
Syntax:
[VB.NET]
Public Sub LiveStart()

[C#]
Public void LiveStart();
Remarks:

It is not allowed to call this method while the control is writing image data to an AVI file.

Imaging Control provides different modes for the processing of image data, i.e. displaying a live image. The different live modes are determined by two properties:

  • ICImagingControl.LiveDisplay: determines whether a live image is displayed.
  • ICImagingControl.LiveCaptureContinuous: deteremines whether frames are copied continuously to the internal ring buffer.

After ICImagingControl.LiveStart has been called, ICImagingControl.LiveDisplay and ICImagingControl.LiveCaptureContinuous may not be altered.

See also: ICImagingControl, ICImagingControl.LiveStop, ICImagingControl.LiveVideoRunning

<< ICImagingControl


ICImagingControl::LiveStop

ICImagingControl.LiveStop Method
Calling this method stops the display of a live image previously started with the LiveStart method.
Syntax:
[VB.NET]
Public Sub LiveStop()

[C#]
public void LiveStop();
Remarks:

The property ICImagingControl.LiveCaptureLastImage determines if the LiveStop method should snap a frame before stopping the live mode.

See also: ICImagingControl, ICImagingControl.LiveStart, ICImagingControl.LiveVideoRunning

<< ICImagingControl


ICImagingControl::MemorySaveImage

ICImagingControl.MemorySaveImage Method
This method saves the current buffer as a .bmp file.
Syntax:
[VB.NET]
Public Sub MemorySaveImage(Filename As String)

[C#]
public void MemorySaveImage(string Filename);

Parameter | Description
Filename | Specifies the filename of the image file to be saved.
Remarks:

The pixel format of the bitmap is determined by the ICImagingControl.MemoryCurrentGrabberColorformat property.

Sample:

This example opens a common dialog box for the user to select a filename and then saves an image under this name:

[VB.NET]
Try
    '  Snap an image, if live image is running. Else use the existing image.
    If IcImagingControl1.LiveVideoRunning Then
        IcImagingControl1.MemorySnapImage()
    End If

    '  Open a common dialog to let the user select a filename and
    '  save the image.
    Dim dialog As New System.Windows.Forms.SaveFileDialog
    dialog.Filter = "Bitmap (*.bmp)|*.bmp"

    If dialog.ShowDialog() = DialogResult.OK Then
        IcImagingControl1.MemorySaveImage(dialog.FileName)
    End If
Catch ex As System.Exception
    MsgBox(Err.Description)
End Try

[C#]
try
{
    //  Snap an image, if live video is running. Else use the existing image.
    if (ICImagingControl1.LiveVideoRunning)
    {
        ICImagingControl1.MemorySnapImage();
    }

    //  Open a common dialog to enable the user to select a filename and save the image.
    System.Windows.Forms.SaveFileDialog dialog = new System.Windows.Forms.SaveFileDialog();
    dialog.Filter = "Bitmap (*.bmp)|*.bmp";

    if (dialog.ShowDialog() == DialogResult.OK)
    {
        ICImagingControl1.MemorySaveImage(dialog.FileName);
    }
}
catch (Exception ex)
{
    MessageBox.Show(ex.Message);
}
See also: ICImagingControl, ICImagingControl.MemorySnapImage, ICImagingControl.MemoryCurrentGrabberColorformat

<< ICImagingControl


ICImagingControl::MemorySaveImageSequence

ICImagingControl.MemorySaveImageSequence Method
This method saves a sequence of images as a sequence of single .bmp files.
Syntax:
[VB.NET]
Public Sub MemorySaveImageSequence(SequenceLength As Integer, Filename As String)

[C#]
public void MemorySaveImageSequence(int SequenceLength, string Filename);

Parameter | Description
SequenceLength | Specifies the number of images to be saved.
Filename | Specifies the base filename of the image files to be saved. It must contain a "*" character, which will be replaced by a frame number. For example, specifying a SequenceLength of 3 and "c:\test*.bmp" as a Filename will create the 3 files "c:\test000.bmp", "c:\test001.bmp" and "c:\test002.bmp".
Sample:

This example will capture a sequence of 25 images to memory, and then save the images to 25 individual files. A "*" character is added to the filename to enable Imaging Control to insert a frame number:

[VB.NET]
Try

    Const NumberOfImages As Integer = 25

    IcImagingControl1.ImageRingBufferSize = NumberOfImages
    IcImagingControl1.MemorySnapImageSequence(NumberOfImages)

    Dim dialog As New System.Windows.Forms.SaveFileDialog
    dialog.Filter = "Bitmap (*.bmp)|*.bmp"
    dialog.DefaultExt = "bmp"

    If dialog.ShowDialog() = DialogResult.OK Then
        Dim filenames As String
        filenames = dialog.FileName.Substring(0, dialog.FileName.Length - 4)
        filenames = filenames + "*" + dialog.FileName.Substring(dialog.FileName.Length - 4)

        IcImagingControl1.MemorySaveImageSequence(NumberOfImages, filenames)
    End If

Catch ex As System.Exception
    MsgBox(Err.Description)
End Try

[C#]
try
{

    const int NumberOfImages = 25;

    ICImagingControl1.ImageRingBufferSize = NumberOfImages;
    ICImagingControl1.MemorySnapImageSequence(NumberOfImages);

    System.Windows.Forms.SaveFileDialog dialog = new System.Windows.Forms.SaveFileDialog();
    dialog.Filter = "Bitmap (*.bmp)|*.bmp";
    dialog.DefaultExt = "bmp";

    if (dialog.ShowDialog() == DialogResult.OK)
    {
        string filenames = "";
        filenames = dialog.FileName.Substring(0, dialog.FileName.Length - 4);
        filenames = filenames + "*" + dialog.FileName.Substring(dialog.FileName.Length - 4);

        ICImagingControl1.MemorySaveImageSequence(  NumberOfImages, filenames );
    }

}
catch (Exception ex)
{
    MessageBox.Show(ex.Message);
}
See also: ICImagingControl, ICImagingControl.MemorySnapImageSequence, ICImagingControl.ImageRingBufferSize

<< ICImagingControl


ICImagingControl::DeviceLost

ICImagingControl.DeviceLost Event
This event is called if the video capture device is no longer valid; for example if it was unplugged.
Syntax:
[VB.NET]
Public Event DeviceLost( ByVal sender As Object, ByVal e As TIS.Imaging.ICImagingControl.DeviceLostEventArgs )

[C#]
public event System.EventHandler<ICImagingControl.DeviceLostEventArgs> DeviceLost;

Parameter | Description
sender | The object in that the event occured, in this case the appropriate instance if ICImagingControl
e | A DeviceLostEventArgs object containing information about the lost device.
Remarks:

The ICImagingControl.Device property should be cleared by setting it to an empty string ("") in the DeviceLost sub.

See also: ICImagingControl, ICImagingControl.Device, ICImagingControl.LiveStart, ICImagingControl.LiveStop, DeviceLostEventArgs

<< ICImagingControl


ICImagingControl::ImageAvailable

ICImagingControl.ImageAvailable Event
This event is called each time a frame has been copied completely to the internal ring buffer.
Syntax:
[VB.NET]
Public Event ImageAvailable( ByVal sender As Object, ByVal e As ICImagingControl.ImageAvailableEventArgs )

[C#]
public event System.EventHandler<ICImagingControl.ImageAvailableEventArgs> ImageAvailable;

Parameter | Description
sender | The object in which the event occured. In this case the appropriate instance of ICImagingControl.
e | An ImageAvailableEventArgs object containing the index of the buffer for which the event is called.
Limitations:

Before the ImageAvailable event will be fired, ICImagingControl.LiveCaptureContinuous must be set to True, the control must run in live mode and an event sink has to be registered (which is done by Visual Basic).

Remarks:

Inside an event procedure no Windows API functions should be called which cause a SendMessage (i.e. adding text to an edit box) because this may block the application.

While an event procedure is running, no new events are sent, but frames are still copied.

Exceptions that occur in the ImageAvailable event will get lost in the system. Therefore, bugs in the code that cause an exception cannot be recognized. To avoid this, all code in the event handler should be enclosed by a try ... catch block. If you need to display error messages, do not use a message box. Use a "debug trace" instead (e.g. System.Diagnostics.Trace.WriteLine(...) ). This is very important, because otherwise the system may run into a deadlock which will cause the application to hang.

Sample:

This example implements an event procedure for the ImageAvailable event. In the event procedure an ImageBuffer ojbect is declared, which is used to take the image, for that the event has been called.

See the Displaying Buffers on the ImageAvailable Event example.

See also: ICImagingControl, ICImagingControl.LiveCaptureContinuous

<< ICImagingControl


ICImagingControl::OverlayUpdate

ICImagingControl.OverlayUpdate Event
This event is called after a new frame has been delivered by the video capture device.
Syntax:
[VB.NET]
Public Event OverlayUpdate( ByVal sender As Object, ByVal e As ICImagingControl.OverlayUpdateEventArgs)

[C#]
public event System.EventHandler<ICImagingControl.OverlayUpdateEventArgs> OverlayUpdate;

Parameter | Description
sender | The object in that the event occured, in this case the appropriate instance if ICImagingControl.
e | An OverlayUpdateEventArgs object containing the scroll information.
Remarks:

The OverlayUpdate event is called after a new frame is available. In the OverlayUpdate event sub, text or graphical elements can be drawn in the new frame. Therefore, it is possible to insert individual information on each individual frame.

The sample time is the time that has been passed, since ICImagingControl.LiveStart has been called. The time resolution is seconds. The duration between SampleStartTime and SampleEndTime is equal to the current frame rate.

This event is called before the ICImagingControl.ImageAvailable event occurs.

Exceptions that occur in the OverlayUpdate event will get lost in the system. Therefore, bugs in the code that cause an exception cannot be recognized. To avoid this, all code in the event handler should be enclosed by a try ... catch block. If you need to display error messages, do not use a message box. Use a "debug trace" instead (e.g. System.Diagnostics.Trace.WriteLine(...) ). This is very important, because otherwise the system may run into a deadlock which will cause the application to hang.

Sample:

This example demonstrates how to write a frame counter on the live video. FrameCount is a global declared variable in the form.

[VB.NET]
If IcImagingControl1.DeviceValid = True Then
    '  Check whether the overlay update event is enabled.
    If IcImagingControl1.OverlayUpdateEventEnable = False Then
        '  Enable the overlay update event.
        IcImagingControl1.OverlayUpdateEventEnable = True
    End If
End If

[C#]
if (ICImagingControl1.DeviceValid)
{
    //  Check whether the overlay update event is enabled.
    if ( !ICImagingControl1.OverlayUpdateEventEnable )
    {
        //  Enable the overlay update event.
        ICImagingControl1.OverlayUpdateEventEnable = true;
    }
}
See also: ICImagingControl, OverlayBitmap, ICImagingControl.LiveStart, ICImagingControl.ReferenceTimeStart, ICImagingControl.ReferenceTimeCurrent

<< ICImagingControl


ImageAvailableEventArgs

This class holds the event arguments for the ICImagingControl.ImageAvailable event.

Information

Namespace: TIS.Imaging.ICImagingControl
Introduced in version 2.0

Properties

Property | Description
ImageBuffer | Returns a reference to the ImageBuffer in the ring buffer for which the event is called.
bufferIndex | Returns the index of the ImageBuffer in the ring buffer for which the event is called.

<< Classes


ImageAvailableEventArgs::ImageBuffer

ImageAvailableEventArgs.ImageBuffer Property
Returns a reference to the ImageBuffer in the ring buffer for which the event is called.
Syntax:
[VB.NET]
Public ImageBuffer As ImageBuffer

[C#]
public ImageBuffer ImageBuffer;
Limitations:

Read only.
Information:

Introduced in version 3.0
See also: ICImagingControl, ICImagingControl.ImageAvailable, ICImagingControl.ImageBuffers, ImageBuffer

<< ImageAvailableEventArgs


ImageAvailableEventArgs::bufferIndex

ImageAvailableEventArgs.bufferIndex Property
Returns the index of the ImageBuffer in the ring buffer for which the event is called.
Syntax:
[VB.NET]
Public bufferIndex As Integer

[C#]
public int bufferIndex;
Limitations:

Read only.
Example:

See the Displaying Buffers on the ImageAvailable Event example.

See also: ICImagingControl, ICImagingControl.ImageAvailable, ICImagingControl.ImageBuffers, ImageBuffer

<< ImageAvailableEventArgs


ImageBuffer

An ImageBuffer object contains the image data of one frame. IC Imaging Control's internal ring buffer consists of ImageBuffers.

Example

This example illustrates how to obtain the first available image buffer:

[VB.NET]
Dim bmp As Bitmap
bmp = IcImagingControl1.ImageActiveBuffer.Bitmap

bmp.Save("C:\membuf.png", System.Drawing.Imaging.ImageFormat.Png)

[C#]
Bitmap bmp = ICImagingControl1.ImageActiveBuffer.Bitmap;

bmp.Save("C:\membuf.png", System.Drawing.Imaging.ImageFormat.Png);

Information

Namespace: TIS.Imaging
Introduced in version 1.x

Properties

Property | Description
Bitmap | Returns a bitmap object representing the image data of this ImageBuffer.
BitsPerPixel | Retrieves the bits per pixel in this ImageBuffer.
BytesPerLine | Returns the number of Bytes in each line of this ImageBuffer.
FrameType | Returns a FrameType object describing the image format of this ImageBuffer.
Index | Returns the index of this buffer in the ring buffer.
Item | Gets or sets bytes in the image data of this ImageBuffer
Lines | Returns the number of lines in this ImageBuffer.
Locked | Returns True if the ImageBuffer is locked.
PixelPerLine | Returns the number of pixels in each line of this ImageBuffer.
SampleEndTime | Returns the reference end time of the sample in the image buffer.
SampleStartTime | Returns the reference start time of the sample in the image buffer.
WasLockedFlag | Returns the WasLockedFlag.

Methods

Method | Description
ForceUnlock | Reduces the lock count immediately to 0. Therefore, an image buffer is unlocked, enabling IC Imaging Control to copy an image to it.
GetByteData | Gets the Bytedata at an specific index of an imagebuffer.
GetImageData | Returns a pointer to the image data.
Lock | Locks the buffer
SaveAsBitmap | Saves the contents of the buffer to a bitmap file on disk.
SaveAsJpeg | Saves the contents of the buffer to a JPEG compressed file to disk.
SaveImage | Saves the contents of the buffer to disk.
SetByteData | Sets the Bytedata at an specific index of an imagebuffer.
Unlock | Unlocks the buffer

<< Classes


ImageBuffer::Bitmap

ImageBuffer.Bitmap Property
Returns a bitmap object representing the image data of this ImageBuffer.
Syntax:
[VB.NET]
Public Bitmap As System.Drawing.Bitmap

[C#]
public System.Drawing.Bitmap Bitmap;
Limitations:

Read only.
Sample:

The following example shows how to retrieve a Bitmap object and save it as a PNG file.

[VB.NET]
Dim bmp As Bitmap
bmp = IcImagingControl1.ImageActiveBuffer.Bitmap

bmp.Save("C:\membuf.png", System.Drawing.Imaging.ImageFormat.Png)

[C#]
Bitmap bmp = ICImagingControl1.ImageActiveBuffer.Bitmap;

bmp.Save("C:\membuf.png", System.Drawing.Imaging.ImageFormat.Png);
See also: ImageBuffer

<< ImageAvailableEventArgs.ImageBuffer


ImageBuffer::BitsPerPixel

ImageBuffer.BitsPerPixel Property
Retrieves the bits per pixel in this ImageBuffer.
Syntax:
[VB.NET]
Public BitsPerPixel As Integer

[C#]
Public int BitsPerPixel
Limitations:

Read only.
See also: ImageBuffer, ImageBuffer.PixelPerLine, ImageBuffer.Lines, ImageBuffer.Item

<< ImageAvailableEventArgs.ImageBuffer


ImageBuffer::Index

ImageBuffer.Index Property
Returns the index of this buffer in the ring buffer.
Syntax:
[VB.NET]
Public Index As Integer

[C#]
public Integer Index;
Information:

Introduced in version 3.0
See also: ImageBuffer, ImageBuffers

<< ImageAvailableEventArgs.ImageBuffer


ImageBuffer::Item

ImageBuffer.Item Property
Gets or sets bytes in the image data of this ImageBuffer
Syntax:
[VB.NET]
Public Item( ByteIndex As Integer, LineIndex As Integer ) As Byte
Public Item( ByteIndex As Integer ) As Byte

[C#]
Public byte Item[ int ByteIndex, int LineIndex ]
Public byte Item[ int ByteIndex ]

Parameter | Description
ByteIndex | Index of the selected byte in the selected line or the image.
LineIndex | Index of the selected line.
Remarks:

The image data is stored bottom-up: the bottom line has line index 0; the bottom left pixel has byte index 0. The bytes per pixel depend on the color format of this ImageBuffer.

Example:

The following example shows how to access the image data by addressing the bytes of the image buffer. It adds brightness to the image.

[VB.NET]
Dim Buf As ImageBuffer
Buf = IcImagingControl1.ImageActiveBuffer

Dim p As Integer
Dim imageSize As Integer
imageSize = Buf.Lines * Buf.PixelPerLine * Buf.BitsPerPixel / 8

For p = 0 To imageSize - 1
    Dim c As Integer

    ' Get the value of the byte.
    c = Buf(p)

    ' Make it a bit brighter.
    c = c + 20
    If c > 255 Then c = 255

    ' Write it back to the buffer.
    Buf(p) = c
Next

[C#]
ImageBuffer Buf = ICImagingControl1.ImageActiveBuffer;

int p = 0;
int imageSize = Buf.Lines * Buf.PixelPerLine * Buf.BitsPerPixel / 8;

for (p = 0; p < imageSize; p++)
{
    // Get the value of the byte.
    int c = Buf[p];

    // Make it a bit brighter.
    c = c + 20;
    if (c > 255)
    {
        c = 255;
    }

    // Write it back to the buffer.
    Buf[p] = (byte)c;
}

The other access variant of specifying a line and a byte in the line is shown in the following example. It inverts an image buffer.

[VB.NET]
Dim Buf As ImageBuffer
Buf = IcImagingControl1.ImageActiveBuffer

Dim y As Integer
Dim x As Integer
Dim lineWidth As Integer
lineWidth = Buf.PixelPerLine * Buf.BitsPerPixel / 8

For y = 0 To Buf.Lines - 1
    For x = 0 To lineWidth - 1
        ' Invert the color value.
        Buf(x, y) = 255 - Buf(x, y)
    Next
Next

[C#]
ImageBuffer Buf = ICImagingControl1.ImageActiveBuffer;

int y = 0;
int x = 0;
int lineWidth = Buf.PixelPerLine * Buf.BitsPerPixel / 8;

for (y = 0; y < Buf.Lines; y++)
{
    for (x = 0; x < lineWidth; x++)
    {
        // Invert the color value.
        Buf[x, y] = (byte)(255 - Buf[x, y]);
    }
}
See also: ImageBuffer, ImageBuffer.Lines, ImageBuffer.PixelPerLine, ImageBuffer.BitsPerPixel

<< ImageAvailableEventArgs.ImageBuffer


ImageBuffer::Locked

ImageBuffer.Locked Property
Returns True if the ImageBuffer is locked.
Syntax:
[VB.NET]
Public Locked Boolean

[C#]
public bool Locked;
Limitations:

Read only.
Sample:

This example shows how to determine whether an ImageBuffer is locked:

[VB.NET]
Dim Buf As ImageBuffer
Buf = IcImagingControl1.ImageBuffers(0)
If Buf.Locked Then
    '   The buffer is locked.
Else
    '   The buffer is not locked.
End If

[C#]
ImageBuffer Buf = ICImagingControl1.ImageBuffers[0];
if (Buf.Locked)
{
    //   The buffer is locked.
}
else
{
    //   The buffer is not locked.
}
See also: ImageBuffer, ImageBuffer.Unlock, ImageBuffer.ForceUnlock, ImageBuffer.Lock

<< ImageAvailableEventArgs.ImageBuffer


ImageBuffer::SampleEndTime

ImageBuffer.SampleEndTime Property
Returns the reference end time of the sample in the image buffer.
Syntax:
[VB.NET]
Public SampleEndTime As Double

[C#]
public double SampleEndTime;
Limitations:

Run time only, read only.
Remarks:

The SampleEndTime property returns the reference time at which the sample ended, in seconds.

See also: ImageBuffer, SampleStartTime, ICImagingControl.ReferenceTimeStart, ICImagingControl.ReferenceTimeCurrent

<< ImageAvailableEventArgs.ImageBuffer


ImageBuffer::SampleStartTime

ImageBuffer.SampleStartTime Property
Returns the reference start time of the sample in the image buffer.
Syntax:
[VB.NET]
Public SampleStartTime Double

[C#]
public double SampleStartTime;
Limitations:

Run time only, read only.
Remarks:

The SampleStartTime property returns the reference time the sample started in seconds.

See also: ImageBuffer, SampleEndTime, ICImagingControl.ReferenceTimeStart, ICImagingControl.ReferenceTimeCurrent

<< ImageAvailableEventArgs.ImageBuffer


ImageBuffer::WasLockedFlag

ImageBuffer.WasLockedFlag Property
Returns the WasLockedFlag.
Syntax:
[VB.NET]
Public WasLockedFlag As Boolean

[C#]
public bool WasLockedFlag;
Remarks:

If IC Imaging Control tries to write to a locked buffer, it sets the WasLockedFlag to True and tries to write to the next buffer in the ring buffer. If a buffer was not locked, WasLockedFlag is set to False.

See also: ImageBuffer, ImageBuffer.Lock, ImageBuffer.Unlock, ImageBuffer.Locked

<< ImageAvailableEventArgs.ImageBuffer


ImageBuffer::ForceUnlock

ImageBuffer.ForceUnlock Method
Reduces the lock count immediately to 0. Therefore, an image buffer is unlocked, enabling IC Imaging Control to copy an image to it.
Syntax:
[VB.NET]
Public Sub ForceUnlock()

[C#]
public void ForceUnlock();
Remarks:

ImageBuffer.Unlock should be used instead of ForceUnlock. If an application needs to unlock an image buffer and it is unknown how often this buffer was previously locked, the application should use ForceUnlock.

See also: ImageBuffer, ImageBuffer.Unlock, ImageBuffer.Lock, ImageBuffer.Locked

<< ImageAvailableEventArgs.ImageBuffer


ImageBuffer::GetImageData

ImageBuffer.GetImageData Method
Returns a pointer to the image data.
Syntax:
[C#]
unsafe public byte* GetImageData();
Remarks:

This method is declared unsafe, and therefore not accessible from VB.NET.

Please note that the images are stored bottom up, therefore the byte at the address returned by this method is the first byte of the first pixel of the last line of the image.

See also: ImageBuffer, ImageBuffer.Lines, ImageBuffer.PixelPerLine, ImageBuffer.BitsPerPixel

<< ImageAvailableEventArgs.ImageBuffer


ImageBuffer::Lock

ImageBuffer.Lock Method
Locks the buffer
Syntax:
[VB.NET]
Public Sub Lock()

[C#]
public void Lock();
Remarks:

Increments the lock count of the buffer by one, so that the control does not overwrite the data in the ImageBuffer. Each call to lock must be matched with a call to ImageBuffer.Unlock, so that the buffer can be used again by the control.

Sample:

This example locks and unlocks an ImageBuffer:

[VB.NET]
Dim Buf As ImageBuffer
Buf = IcImagingControl1.ImageBuffers(0)
If Buf.Locked Then
    '   The buffer is locked.
Else
    '   The buffer is not locked.
End If

[C#]
ImageBuffer Buf = ICImagingControl1.ImageBuffers[0];
if (Buf.Locked)
{
    //   The buffer is locked.
}
else
{
    //   The buffer is not locked.
}

A sample on how to use ImageBuffer and ImageBuffer.Lock is shown in Performing Advanced Image Processing.

See also: ImageBuffer, ImageBuffer.Unlock, ImageBuffer.ForceUnlock, ImageBuffer.Locked, ImageBuffer.WasLockedFlag

<< ImageAvailableEventArgs.ImageBuffer


ImageBuffer::SaveImage

ImageBuffer.SaveImage Method
Saves the contents of the buffer to disk.
Syntax:
[VB.NET]
Public Sub SaveImage(Filename As String)

[C#]
public void SaveImage(string Filename);

Parameter | Description
Filename | The name of the file to which the buffer is saved.
Sample:

This example shows how to save the contents of an ImageBuffer to a file called "test.bmp":

[VB.NET]
IcImagingControl1.LiveStart()
Try
    ' Use a timeout of 1000ms.
    IcImagingControl1.MemorySnapImage(1000)
    ' Save the snapped image, which is stored in the ImageBuffer "ImageActiveBuffer" to a file.
    IcImagingControl1.ImageActiveBuffer.SaveImage("test.bmp")
Catch Ex As ICException
    MessageBox.Show(Ex.Message)
End Try
IcImagingControl1.LiveStop()

[C#]
ICImagingControl1.LiveStart();
try
{
    // Use a timeout of 1000ms.
    ICImagingControl1.MemorySnapImage(1000);
    // Save the snapped image, which is stored in the ImageBuffer "ImageActiveBuffer" to a file.
    ICImagingControl1.ImageActiveBuffer.SaveImage("test.bmp");
}
catch (ICException Ex)
{
    MessageBox.Show(Ex.Message, "MemorySnapImage Error");
}
ICImagingControl1.LiveStop();
See also: ImageBuffer

<< ImageAvailableEventArgs.ImageBuffer


ImageBuffer::Unlock

ImageBuffer.Unlock Method
Unlocks the buffer
Syntax:
[VB.NET]
Public Sub Unlock()

[C#]
public void Unlock();
Remarks:

Calling ImageBuffer.Lock prevents an image buffer from being overwritten by IC Imaging Control. Internally, a lock count is incremented. Calling Unlock decrements the lock count until it is 0. If the internal lock count is 0, the image buffer is unlocked and can be overwritten by IC Imaging Control.

Sample:

See ImageBuffer.Lock for an example.

See also: ImageBuffer, ImageBuffer.Lock, ImageBuffer.ForceUnlock, ImageBuffer.Locked, ImageBuffer.WasLockedFlag

<< ImageAvailableEventArgs.ImageBuffer


InputChannel

An InputChannel object contains the information about an analog input channel that is available on the current video capture device.

Example

[VB.NET]
Dim Inp As InputChannel
Inp = IcImagingControl1.InputChannels(0)

[C#]
InputChannel Inp = ICImagingControl1.InputChannels[0];

Information

Namespace: TIS.Imaging
Introduced in version 1.x

Properties

Property | Description
Name | Returns the name of the InputChannel.

<< Classes


InputChannel::Name

InputChannel.Name Property
Returns the name of the InputChannel.
Syntax:
[VB.NET]
Public Name As String

[C#]
public string Name;
Limitations:

Read only.
Remarks:

This property is used to enable and disable the displaying of the overlay bitmap on the live video. Setting this property to False causes IC Imaging Control to hide the overlay bitmap. No drawings or texts can be seen. Setting this property to True causes IC Imaging Control to show the overlay bitmap on the live video. All texts and drawings can be seen.

The default value of Enable is False.

Sample:

This example selects the first available input channel.

[VB.NET]
Dim Inp As InputChannel
Inp = IcImagingControl1.InputChannels(0)
IcImagingControl1.InputChannel = Inp.Name

[C#]
InputChannel Inp = ICImagingControl1.InputChannels[0];
ICImagingControl1.InputChannel = Inp.Name;

Selecting devices, input channels, video norms and video formats is shown in the Making Device Settings chapter.

See also: InputChannel

<< ICImagingControl.InputChannel


MediaSubtypes

This class contains constants defining the available mediasubtype GUIDs that can be used when specifying a FrameType.

Information

Namespace: TIS.Imaging
Introduced in version 3.0

Properties

Property | Description
BY8 | 8-bit color raw format, top down.
RGB24 | 24-bit color image format, bottom up.
RGB32 | 32-bit color image format, bottom up.
RGB555 | 16-bit color image format, bottom up.
RGB565 | 16-bit color image format, bottom up.
RGB8 | 8-bit gray image format, bottom up.
UYVY | UYVY color image format.
Y800 | 8-bit gray image format, top down.
YGB0 | 10-bit grayscale format, top down.
YGB1 | 10-bit grayscale format, top down.

<< Classes


MediaSubtypes::BY8

MediaSubtypes.BY8 Property
8-bit color raw format, top down.
Syntax:
[VB.NET]
Public Shared ReadOnly BY8 As Guid

[C#]
public static readonly Guid BY8;
See also: MediaSubtypes

<< MediaSubtypes


MediaSubtypes::RGB24

MediaSubtypes.RGB24 Property
24-bit color image format, bottom up.
Syntax:
[VB.NET]
Public Shared ReadOnly RGB24 As Guid

[C#]
public static readonly Guid RGB24;
See also: MediaSubtypes

<< MediaSubtypes


MediaSubtypes::RGB32

MediaSubtypes.RGB32 Property
32-bit color image format, bottom up.
Syntax:
[VB.NET]
Public Shared ReadOnly RGB32 As Guid

[C#]
public static readonly Guid RGB32;
See also: MediaSubtypes

<< MediaSubtypes


MediaSubtypes::RGB555

MediaSubtypes.RGB555 Property
16-bit color image format, bottom up.
Syntax:
[VB.NET]
Public Shared ReadOnly RGB555 As Guid

[C#]
public static readonly Guid RGB555;
See also: MediaSubtypes

<< MediaSubtypes


MediaSubtypes::RGB565

MediaSubtypes.RGB565 Property
16-bit color image format, bottom up.
Syntax:
[VB.NET]
Public Shared ReadOnly RGB565 As Guid

[C#]
public static readonly Guid RGB565;
See also: MediaSubtypes

<< MediaSubtypes


MediaSubtypes::RGB8

MediaSubtypes.RGB8 Property
8-bit gray image format, bottom up.
Syntax:
[VB.NET]
Public Shared ReadOnly RGB8 As Guid

[C#]
public static readonly Guid RGB8;
See also: MediaSubtypes

<< MediaSubtypes


MediaSubtypes::UYVY

MediaSubtypes.UYVY Property
UYVY color image format.
Syntax:
[VB.NET]
Public Shared ReadOnly UYVY As Guid

[C#]
public static readonly Guid UYVY;
See also: MediaSubtypes

<< MediaSubtypes


MediaSubtypes::Y800

MediaSubtypes.Y800 Property
8-bit gray image format, top down.
Syntax:
[VB.NET]
Public Shared ReadOnly Y800 As Guid

[C#]
public static readonly Guid Y800;
See also: MediaSubtypes

<< MediaSubtypes


MediaSubtypes::YGB0

MediaSubtypes.YGB0 Property
10-bit grayscale format, top down.
Syntax:
[VB.NET]
Public Shared ReadOnly YGB0 As Guid

[C#]
public static readonly Guid YGB0;
See also: MediaSubtypes

<< MediaSubtypes


MediaSubtypes::YGB1

MediaSubtypes.YGB1 Property
10-bit grayscale format, top down.
Syntax:
[VB.NET]
Public Shared ReadOnly YGB1 As Guid

[C#]
public static readonly Guid YGB1;
See also: MediaSubtypes

<< MediaSubtypes


OverlayBitmap

An OverlayBitmap object contains the overlay data, methods and properties for drawing text and graphics on the live video stream.

Example

[VB.NET]
Dim ob As OverlayBitmap
ob = IcImagingControl1.OverlayBitmap

'   Enable the overlay bitmap for drawing.
ob.Enable = True

'   Set magenta as the dropout color.
ob.DropOutColor = System.Drawing.Color.Magenta

'   Fill the overlay bitmap with the dropout color.
ob.Fill(ob.DropOutColor)

'   Print some text in red.
ob.FontTransparent = True
ob.DrawText(System.Drawing.Color.Red, 10, 10, "IC Imaging Control 2.0")

[C#]
OverlayBitmap ob = ICImagingControl1.OverlayBitmap;
//   Enable the overlay bitmap for drawing.
ob.Enable = true;

//   Set magenta as the dropout color.
ob.DropOutColor = System.Drawing.Color.Magenta;

//   Fill the overlay bitmap with the dropout color.
ob.Fill(ob.DropOutColor);

//   Print some text in red.
ob.FontTransparent = true;
ob.DrawText(System.Drawing.Color.Red, 10, 10, "IC Imaging Control 2.0");

Information

Namespace: TIS.Imaging
Introduced in version 1.x

Properties

Property | Description
ColorMode | Set the color mode of this OverlayBitmap. The color mode determines whether the overlay bitmap is painted in color or in grayscale. The images provided by the video capture device are converted into the selected format before drawing the overlay.
DropOutColor | Returns or sets the current dropout color.
Enable | Returns or sets the currently enabled state of the overlay bitmap.
FlipVertical | Returns or sets vertical flipping of the overlay bitmap.
Font | Returns or sets the font for OverlayBitmap.DrawText.
FontBackColor | Returns or sets the background color for OverlayBitmap.DrawText.
FontTransparent | Returns or sets the background mode for OverlayBitmap.DrawText.
OverlayFrameType | This property returns the actual image format of the overlay bitmap.
PathPosition | Returns the path position of this OverlayBitmap.

Methods

Method | Description
DrawFrameEllipse | This method draws an empty frame ellipse on the live video.
DrawFrameRect | This method draws an empty frame rectangle on the live video.
DrawLine | This method draws a line on the live video.
DrawSolidEllipse | This method draws a solid, filled ellipse on the live video.
DrawSolidRect | This method draws a solid, filled rectangle on the live video.
DrawText | This method draws text on the live video.
Fill | This method fills the entire overlay bitmap with the passed color.
GetGraphics | Thie method retrieves a Graphics object that represents the overlay bitmap as a GDI+ drawing surface.
ReleaseGraphics | This method releases the GDI+ Graphics object that was previously retrieved with OverlayBitmap.GetGraphics.

<< Classes


OverlayBitmap::DropOutColor

OverlayBitmap.DropOutColor Property
Returns or sets the current dropout color.
Syntax:
[VB.NET]
Public DropOutColor As System.Drawing.Color

[C#]
public System.Drawing.Color DropOutColor;
Limitations:

Run time only. Only after ICImagingControl.LiveStart has been called once.

Remarks:

This property is used to return and set the dropout color of the overlay bitmap. All pixels of the dropout color are not painted on the live video.

The dropout color can be set using the RGB method.

The default value for DropOutColor is black.

Example:

This example demonstrates how to use the dropout color.

[VB.NET]
Dim ob As OverlayBitmap
ob = IcImagingControl1.OverlayBitmap

'   Enable the overlay bitmap for drawing.
ob.Enable = True

'   Set magenta as the dropout color.
ob.DropOutColor = System.Drawing.Color.Magenta

'   Fill the overlay bitmap with the dropout color.
ob.Fill(ob.DropOutColor)

[C#]
OverlayBitmap ob = ICImagingControl1.OverlayBitmap;

//   Enable the overlay bitmap for drawing.
ob.Enable = true;

//   Set magenta as the dropout color.
ob.DropOutColor = System.Drawing.Color.Magenta;

//   Fill the overlay bitmap with the dropout color.
ob.Fill(ob.DropOutColor);
See also: OverlayBitmap, OverlayBitmap.Fill

<< ICImagingControl.OverlayBitmap


OverlayBitmap::Enable

OverlayBitmap.Enable Property
Returns or sets the currently enabled state of the overlay bitmap.
Syntax:
[VB.NET]
Public Enable As Boolean

[C#]
public bool Enable;
Limitations:

Run time only.
Remarks:

This property is used to enable and disable the displaying of the overlay bitmap on the live video. Setting this property to False causes IC Imaging Control to hide the overlay bitmap. No drawings or texts can be seen. Setting this property to True causes IC Imaging Control to show the overlay bitmap on the live video. All texts and drawings can be seen.

The default value of Enable is False.

Example:

This example demonstrates how to enable the display of the overlay bitmap.

[VB.NET]
Dim ob As OverlayBitmap

ob = IcImagingControl1.OverlayBitmap
'   Enable the overlay bitmap for drawing.
ob.Enable = True

[C#]
OverlayBitmap ob = ICImagingControl1.OverlayBitmap;

//   Enable the overlay bitmap for drawing.
ob.Enable = true;
See also: OverlayBitmap

<< ICImagingControl.OverlayBitmap


OverlayBitmap::FlipVertical

OverlayBitmap.FlipVertical Property
Returns or sets vertical flipping of the overlay bitmap.
Syntax:
[VB.NET]
Public FlipVertical As Boolean

[C#]
public bool FlipVertical;
Limitations:

Run time only.
Remarks:

This property is used to enable and disable the vertical flipping of the overlay bitmap on the live video. If vertical flipping is enabled, the overlay bitmap will be drawn bottom up.

The default value of FlipVertical is False.

Example:

This example demonstrates how to enable vertical flipping.

[VB.NET]
Dim ob As OverlayBitmap

ob = IcImagingControl1.OverlayBitmap
'   Enable vertical flipping.
ob.FlipVertical = True

[C#]
OverlayBitmap ob = ICImagingControl1.OverlayBitmap;

//   Enable vertical flipping.
ob.FlipVertical = true;
See also: OverlayBitmap

<< ICImagingControl.OverlayBitmap


OverlayBitmap::Font

OverlayBitmap.Font Property
Returns or sets the font for OverlayBitmap.DrawText.
Syntax:
[VB.NET]
Public Font As System.Drawing.Font

[C#]
public System.Drawing.Font Font;
Limitations:

Run time only.
Example:

This example demonstrates how to create a font object and set it to the OverlayBitmap object to draw text.

[VB.NET]
Dim ob As OverlayBitmap

ob = IcImagingControl1.OverlayBitmap
'   Enable the overlay bitmap for drawing.
ob.Enable = True

[C#]
OverlayBitmap ob = ICImagingControl1.OverlayBitmap;

//   Enable the overlay bitmap for drawing.
ob.Enable = true;
See also: OverlayBitmap, OverlayBitmap.DrawText, OverlayBitmap.FontBackColor, OverlayBitmap.FontTransparent

<< ICImagingControl.OverlayBitmap


OverlayBitmap::FontBackColor

OverlayBitmap.FontBackColor Property
Returns or sets the background color for OverlayBitmap.DrawText.
Syntax:
[VB.NET]
Public FontBackColor As System.Drawing.Color

[C#]
public System.Drawing.Color FontBackColor;
Limitations:

Run time only.
Remarks:

If the FontBackColor is equal to the DropOutColor, the surrounding solid rectangle of the text (text background) is not visible.

The default value for FontBackColor> is black.

Example:

This example demonstrates how to use the FontBackColor property.

[VB.NET]
Dim ob As OverlayBitmap
ob = IcImagingControl1.OverlayBitmap

'   Use a blue background with red text.
ob.FontTransparent = False
ob.FontBackColor = System.Drawing.Color.Blue
ob.DrawText(System.Drawing.Color.Red, 10, 10, "IC Imaging Control red on blue")

[C#]
OverlayBitmap ob = ICImagingControl1.OverlayBitmap;

//   Use a blue background with red text.
ob.FontTransparent = false;
ob.FontBackColor = System.Drawing.Color.Blue;
ob.DrawText(System.Drawing.Color.Red, 10, 10, "IC Imaging Control red on blue");
See also: OverlayBitmap, OverlayBitmap.DrawText, OverlayBitmap.Font, OverlayBitmap.FontTransparent

<< ICImagingControl.OverlayBitmap


OverlayBitmap::FontTransparent

OverlayBitmap.FontTransparent Property
Returns or sets the background mode for OverlayBitmap.DrawText.
Syntax:
[VB.NET]
Public FontTransparent As Boolean

[C#]
public bool FontTransparent;
Limitations:

Run time only.
Remarks:

This property is used to return and set the background mode to draw text.

If FontTransparent is set to True, OverlayBitmap.DrawText writes the text without a surrounding solid rectangle. The live video image can be seen through the text. If changing text is repeatedly written to the same position, it becomes unreadable, because the background is not cleared.

If FontTransparent is set to False, OverlayBitmap.DrawText writes the text with a surrounding solid rectangle. The rectangle has the color set with the OverlayBitmap.FontBackColor property. If changing text is repeatedly written to the same position, it stays readable, because the background is overwritten every time. If the FontBackColor is equal to OverlayBitmap.DropOutColor, the surrounding solid rectangle is not visible.

Hint: If changing text is displayed on the live video repeatedly (such as a clock), an application should set FontTransparent to False and OverlayBitmap.FontBackColor to the OverlayBitmap.DropOutColor. In doing so, the text remains readable.

The default value for FontTransparent is False.

Example:

This example demonstrates how to use the FontTransparent property:

[VB.NET]
Dim ob As OverlayBitmap
ob = IcImagingControl1.OverlayBitmap

'   Print some text with red color and transparent background.
ob.FontTransparent = True
ob.DrawText(System.Drawing.Color.Red, 10, 10, "IC Imaging Control")

[C#]
OverlayBitmap ob = ICImagingControl1.OverlayBitmap;

//   Print some text in red and transparent background.
ob.FontTransparent = true;
ob.DrawText(System.Drawing.Color.Red, 10, 10, "IC Imaging Control");
See also: OverlayBitmap, OverlayBitmap.DrawText, OverlayBitmap.DropOutColor, OverlayBitmap.FontBackColor

<< ICImagingControl.OverlayBitmap


OverlayBitmap::DrawLine

OverlayBitmap.DrawLine Method
This method draws a line on the live video.
Syntax:
[VB.NET]
Public Sub DrawLine( clr As System.Drawing.Color, XStart As Integer, YStart As Integer, XEnd As Integer, YEnd As Integer )

[C#]
public void DrawLine( System.Drawing.Color clr, int XStart, int YStart, int XEnd, int YEnd );

Parameter | Description
color, clr | Specifies the color of the line.
startcolumn, XStart | Specifies the column in pixel units where the line should start on the live video.
startrow, YStart | Specifies the row in pixel units where the line should start on the live video.
endcolumn, XEnd | Specifies the column in pixel units where the line should end on the live video.
endrow, YEnd | Specifies the row in pixel units where the line should end on the live video.
Limitations:

Run time only. Only after ICImagingControl.LiveStart has been called once.
Example:

This example demonstrates how to draw a line on the live video.

[VB.NET]
Dim ob As OverlayBitmap
ob = IcImagingControl1.OverlayBitmap

ob.DrawLine(System.Drawing.Color.Red, 10, 10, 10, 250)

[C#]
OverlayBitmap ob = ICImagingControl1.OverlayBitmap;

ob.DrawLine(System.Drawing.Color.Red, 10, 10, 10, 250);
See also: OverlayBitmap, ICImagingControl.LiveStart

<< ICImagingControl.OverlayBitmap


OverlayBitmap::DrawSolidEllipse

OverlayBitmap.DrawSolidEllipse Method
This method draws a solid, filled ellipse on the live video.
Syntax:
[VB.NET]
Public Sub DrawSolidEllipse( clr As System.Drawing.Color, x0 As Integer, y0 As Integer, x1 As Integer, y1 As Integer )

[C#]

public void DrawSolidEllipse( System.Drawing.Color clr, int x0, int y0, int x1, int y1 );

Parameter | Description
clr | Specifies the color of the ellipse.
x0 | Specifies the column in pixel units of the of the upper left hand corner of the bounding rectangle of the ellipse on the live video.
y0 | Specifies the row in pixel units of the of the upper left hand corner of the bounding rectangle of the ellipse on the live video.
x1 | Specifies the column in pixel units of the of the lower right hand corner of the bounding rectangle of the ellipse on the live video.
y1 | Specifies the row in pixel units of the of the lower right hand corner of the bounding rectangle of the ellipse on the live video.
Limitations:

Run time only. Only after ICImagingControl.LiveStart has been called once.
Information:

Introduced in version 2.0
Example:

This example demonstrates how to draw a solid green ellipse on the live video.

[VB.NET]
Dim ob As OverlayBitmap
ob = IcImagingControl1.OverlayBitmap

ob.DrawSolidEllipse(System.Drawing.Color.Green, 10, 10, 250, 200)

[C#]
OverlayBitmap ob = ICImagingControl1.OverlayBitmap;

ob.DrawSolidEllipse(System.Drawing.Color.Green, 10, 10, 250, 200);
See also: OverlayBitmap, OverlayBitmap.DrawFrameEllipse, ICImagingControl.LiveStart

<< ICImagingControl.OverlayBitmap


OverlayBitmap::DrawText

OverlayBitmap.DrawText Method
This method draws text on the live video.
Syntax:
[VB.NET]

Public Sub DrawText( clr As System.Drawing.Color, XStart As Integer, YStart As Integer, text As String )

[C#]

public void DrawText( System.Drawing.Color clr, int XStart, int YStart, String text );

Parameter | Description
color, clr | Specifies the color of the text to be written.
column, XStart | Specifies the column in pixel units where the text should start on the live video.
row, YStart | Specifies the row in pixel units where the text should start on the live video
text | Specifies the text to be written.
Limitations:

Run time only. Only after ICImagingControl.LiveStart has been called once.
Remarks:

The method DrawText draws text on the live video. It uses the currently set Font, FontBackColor and the FontTransparent setting.

Example:

This example demonstrates how to draw text at the coordinates (10/10) on the live video.

[VB.NET]
Dim ob As OverlayBitmap
ob = IcImagingControl1.OverlayBitmap
'   Print some text in red.
ob.DrawText(Color.FromArgb(255, 0, 0), 10, 10, "IC Imaging Control")

[C#]
OverlayBitmap ob = ICImagingControl1.OverlayBitmap;

//   Print some text in red.
ob.DrawText(Color.FromArgb(255, 0, 0), 10, 10, "IC Imaging Control");
See also: OverlayBitmap, OverlayBitmap.Font, OverlayBitmap.FontBackColor, OverlayBitmap.FontTransparent, ICImagingControl.LiveStart, ICImagingControl.LiveStop

<< ICImagingControl.OverlayBitmap


OverlayBitmap::Fill

OverlayBitmap.Fill Method
This method fills the entire overlay bitmap with the passed color.
Syntax:
[VB.NET]

Public Sub Fill( clr As System.Drawing.Color )

[C#]

public void Fill( System.Drawing.Color clr );

Parameter | Description
color, clr | Specifies the color used to fill the OverlayBitmap.
Limitations:

Run time only. Only after ICImagingControl.LiveStart has been called once.
Remarks:

The Fill method is used to fill an entire overlay bitmap with the passed color. This overwrites all previously drawn texts and graphics. If the dropout color is passed to the Fill method, there is no overlay on the video (as the overlay is empty). The Fill method is only successful, after ICImagingControl.LiveStart has been called once.

Example:

This example demonstrates how to fill the entire overlay bitmap with the dropout color.

[VB.NET]
Dim ob As OverlayBitmap
ob = IcImagingControl1.OverlayBitmap

'   Enable the overlay bitmap for drawing.
ob.Enable = True

'   Set magenta as the dropout color.
ob.DropOutColor = System.Drawing.Color.Magenta

'   Fill the overlay bitmap with the dropout color.
ob.Fill(ob.DropOutColor)

[C#]
OverlayBitmap ob = ICImagingControl1.OverlayBitmap;

//   Enable the overlay bitmap for drawing.
ob.Enable = true;

//   Set magenta as the dropout color.
ob.DropOutColor = System.Drawing.Color.Magenta;

//   Fill the overlay bitmap with the dropout color.
ob.Fill(ob.DropOutColor);
See also: OverlayBitmap, OverlayBitmap.DropOutColor, ICImagingControl.LiveStart

<< ICImagingControl.OverlayBitmap


OverlayBitmap::GetGraphics

OverlayBitmap.GetGraphics Method
Thie method retrieves a Graphics object that represents the overlay bitmap as a GDI+ drawing surface.
Syntax:
[VB.NET]
Public Function GetGraphics() As System.Drawing.Graphics

[C#]
public System.Drawing.Graphics GetGraphics();
Return Value:

A Graphics object usable for drawing operations on the overlay bitmap.

Limitations:

Run time only. Only after ICImagingControl.LiveStart has been called once.

Remarks:

If the returned Graphics object is no longer used, an application must call OverlayBitmap.ReleaseGraphics to release the object.

Example:

This Basic example demonstrates how do drawing operations with the graphics object.

[VB.NET]
Dim ob As OverlayBitmap
ob = IcImagingControl1.OverlayBitmap

Dim gfx As System.Drawing.Graphics
gfx = ob.GetGraphics()

Dim pen As New System.Drawing.Pen(System.Drawing.Color.Green)
gfx.DrawLine(pen, 0, 0, 80, 60)

ob.ReleaseGraphics(gfx)

[C#]
OverlayBitmap ob = ICImagingControl1.OverlayBitmap;

System.Drawing.Graphics gfx = ob.GetGraphics();

System.Drawing.Pen pen = new System.Drawing.Pen(System.Drawing.Color.Green);
gfx.DrawLine(pen, 0, 0, 80, 60);

ob.ReleaseGraphics(gfx);
See also: OverlayBitmap, OverlayBitmap.ReleaseGraphics, ICImagingControl.LiveStart

<< ICImagingControl.OverlayBitmap


OverlayBitmap::ReleaseGraphics

OverlayBitmap.ReleaseGraphics Method
This method releases the GDI+ Graphics object that was previously retrieved with OverlayBitmap.GetGraphics.
Syntax:
[VB.NET]
Public Sub ReleaseGraphics( gr As System.Drawing.Graphics

[C#]
public void ReleaseGraphics( System.Drawing.Graphics gr );
Limitations:

Run time only. Must release a Graphics object that was retrieved with OverlayBitmap.GetGraphics.

Example:

For an example of how to use the Graphics object for drawing, see OverlayBitmap.GetGraphics.

See also: OverlayBitmap, OverlayBitmap.GetGraphics

<< ICImagingControl.OverlayBitmap


OverlayUpdateEventArgs

This class holds the event arguments for the ICImagingControl.OverlayUpdate event.

Information

Namespace: TIS.Imaging.ICImagingControl
Introduced in version 2.0

Properties

Property | Description
Overlay | Specifies IC Imaging Control's OverlayBitmap object.
SampleEndTime | Specifies the sample end time in seconds. See remarks section for more information.
SampleStartTime | Specifies the sample start time in seconds. See remarks section for more information.

<< Classes


OverlayUpdateEventArgs::Overlay

OverlayUpdateEventArgs.Overlay Property
Specifies IC Imaging Control's OverlayBitmap object.
Syntax:
[VB.NET]
Public Overlay As OverlayBitmap

[C#]
public OverlayBitmap Overlay;
Limitations:

Read only.
Remarks:

In the OverlayUpdate event, text or graphical elements can be drawn in the new frame. Therefore, it is possible to insert individual information on each individual frame.

See also: ICImagingControl, ICImagingControl.OverlayUpdate

<< OverlayUpdateEventArgs


OverlayUpdateEventArgs::SampleEndTime

OverlayUpdateEventArgs.SampleEndTime Property
Specifies the sample end time in seconds. See remarks section for more information.
Syntax:
[VB.NET]
Public SampleEndTime As Double

[C#]
public double SampleEndTime;
Limitations:

Read only.
Remarks:

The sample time is the time that has been passed, since ICImagingControl.LiveStart has been called. The time resolution is seconds. The duration between OverlayUpdateEventArgs.SampleStartTime and SampleEndTime is equal to the current frame rate.

See also: ICImagingControl, ICImagingControl.OverlayUpdate

<< OverlayUpdateEventArgs


OverlayUpdateEventArgs::SampleStartTime

OverlayUpdateEventArgs.SampleStartTime Property
Specifies the sample start time in seconds. See remarks section for more information.
Syntax:
[VB.NET]
Public SampleStartTime As Double

[C#]
public double SampleStartTime;
Limitations:

Read only.
Remarks:

The sample time is the time that has been passed, since ICImagingControl.LiveStart has been called. The time resolution is seconds. The duration between SampleStartTime and OverlayUpdateEventArgs.SampleEndTime is equal to the current frame rate.

See also: ICImagingControl, ICImagingControl.OverlayUpdate

<< OverlayUpdateEventArgs


VCDSimpleModule

This class wraps the concept of VCDProperties to make them easier to use. It replaces the VCDSimpleProperty class, which was located in an extra source code file.

Usage

[VB.NET]
VCDSimpleModule.GetSimplePropertyContainer(VCDPropertyItems)

[C#]
VCDSimpleModule.GetSimplePropertyContainer(VCDPropertyItems);

A sample that shows the usage of the VCDSimpleModule class is documented in the Using the VCD Simple Property Class chapter.

Information

Namespace: TIS.Imaging.VCDHelpers
Introduced in version 3.1

<< Classes


VideoFormat

A VideoFormat object contains information about a video format supported by the current video capture device.

Example

This example illustrates how to obtain the first available video format.

[VB.NET]
Dim Fmt As VideoFormat
Fmt = IcImagingControl1.VideoFormats(0)

[C#]
VideoFormat Fmt = ICImagingControl1.VideoFormats[0];

Information

Namespace: TIS.Imaging
Introduced in version 1.x

Properties

Property | Description
BinningFactor | Returns the binning factor of the VideoFormat.
BitsPerPixel | Returns the bits per pixel of the VideoFormat. The byte count per pixel is calculated by dividing the bits per pixel count by 8.
Height | Returns the height of the VideoFormat.
Name | Returns the name of the VideoFormat.
Width | Returns the width of the VideoFormat.

<< Classes


VideoFormat::BinningFactor

VideoFormat.BinningFactor Property
Returns the binning factor of the VideoFormat.
Syntax:
[VB.NET]
Public BinningFactor As Integer

[C#]
public int BinningFactor;
Limitations:

Read only.
See also: VideoFormat, VideoFormatDesc

<< ICImagingControl.VideoFormat


VideoFormat::BitsPerPixel

VideoFormat.BitsPerPixel Property
Returns the bits per pixel of the VideoFormat. The byte count per pixel is calculated by dividing the bits per pixel count by 8.
Syntax:
[VB.NET]
Public BitsPerPixel As Integer

[C#]
public int BitsPerPixel;
Limitations:

Read only.
Remarks:

Selecting devices, input channels, video norms and video formats is shown in the Making Device Settings chapter.

See also: VideoFormat, VideoFormat.Width, VideoFormat.Height

<< ICImagingControl.VideoFormat


VideoFormat::Height

VideoFormat.Height Property
Returns the height of the VideoFormat.
Syntax:
[VB.NET]
Public Height As Integer

[C#]
public int Height;
Limitations:

Read only.
Remarks:

Selecting devices, input channels, video norms and video formats is shown in the Making Device Settings chapter.

See also: VideoFormat, VideoFormat.Width, VideoFormat.BitsPerPixel

<< ICImagingControl.VideoFormat


VideoFormat::Name

VideoFormat.Name Property
Returns the name of the VideoFormat.
Syntax:
[VB.NET]
Public Name As String

[C#]
public string Name;
Limitations:

Read only.
Remarks:

Selecting devices, input channels, video norms and video formats is shown in the Making Device Settings chapter.

Sample:

This example selects the first available video format.

[VB.NET]
Dim Fmt As VideoFormat
Fmt = IcImagingControl1.VideoFormats(0)
IcImagingControl1.VideoFormat = Fmt.Name

[C#]
VideoFormat Fmt = ICImagingControl1.VideoFormats[0];
ICImagingControl1.VideoFormat = Fmt.Name;
See also: VideoFormat

<< ICImagingControl.VideoFormat


VideoFormat::Width

VideoFormat.Width Property
Returns the width of the VideoFormat.
Syntax:
[VB.NET]
Public Width As Integer

[C#]
public int Width;
Limitations:

Read only.
Remarks:

Selecting devices, input channels, video norms and video formats is shown in the Making Device Settings chapter.

See also: VideoFormat, VideoFormat.Height, VideoFormat.BitsPerPixel

<< ICImagingControl.VideoFormat


VideoFormatDesc

A VideoFormatDesc describes an available video format using the media subtype, a binning factor and size constraints. The size constraints are described by a minimum size, a maximum size and a step size.

To set a video format for a device, a VideoFormat instance has to be created by using VideoFormatDesc.CreateVideoFormat.

Information

Namespace: TIS.Imaging
Introduced in version 3.2

Properties

Property | Description
BinningFactor | Returns the binning factor of the VideoFormatDesc.
IsROIFormat | Returns whether this VideoFormatDesc describes a ROI format.
MaxSize | Returns the maximum possible size for video formats created from this VideoFormatDesc.
MinSize | Returns the minimum possible size for video formats created from this VideoFormatDesc.
Name | Returns a text representation of the VideoFormatDesc.
StepSize | Returns the step size for video formats created from this VideoFormatDesc.
Subtype | Returns the GUID of the media subtype of this video format description.

Methods

Method | Description
CreateVideoFormat | This method creates a VideoFormat with the specified size based on the specification of this VideoFormatDesc.
IsValidSize | This method checks whether a specified size matches the size constraints of this VideoFormatDesc.

<< Classes


VideoFormatDesc::BinningFactor

VideoFormatDesc.BinningFactor Property
Returns the binning factor of the VideoFormatDesc.
Syntax:
[VB.NET]
Public BinningFactor As Integer

[C#]
public int BinningFactor;
Limitations:

Read only.
See also: VideoFormatDesc, VideoFormat.BinningFactor

<< VideoFormatDesc


VideoFormatDesc::IsROIFormat

VideoFormatDesc.IsROIFormat Property
Returns whether this VideoFormatDesc describes a ROI format.
Syntax:
[VB.NET]
Public IsROIFormat As Boolean

[C#]
public bool IsROIFormat;
Limitations:

Read only.
See also: VideoFormatDesc

<< VideoFormatDesc


VideoFormatDesc::MaxSize

VideoFormatDesc.MaxSize Property
Returns the maximum possible size for video formats created from this VideoFormatDesc.
Syntax:
[VB.NET]
Public MaxSize As System.Drawing.Size

[C#]
public System.Drawing.Size MaxSize;
Limitations:

Read only.
See also: VideoFormatDesc, VideoFormatDesc.MinSize, VideoFormatDesc.StepSize

<< VideoFormatDesc


VideoFormatDesc::MinSize

VideoFormatDesc.MinSize Property
Returns the minimum possible size for video formats created from this VideoFormatDesc.
Syntax:
[VB.NET]
Public MinSize As System.Drawing.Size

[C#]
public System.Drawing.Size MinSize;
Limitations:

Read only.
See also: VideoFormatDesc, VideoFormatDesc.MaxSize, VideoFormatDesc.StepSize

<< VideoFormatDesc


VideoFormatDesc::Name

VideoFormatDesc.Name Property
Returns a text representation of the VideoFormatDesc.
Syntax:
[VB.NET]
Public Name As String

[C#]
public string Name;
Limitations:

Read only.
See also: VideoFormatDesc

<< VideoFormatDesc


VideoFormatDesc::StepSize

VideoFormatDesc.StepSize Property
Returns the step size for video formats created from this VideoFormatDesc.
Syntax:
[VB.NET]
Public StepSize As System.Drawing.Size

[C#]
public System.Drawing.Size StepSize;
Limitations:

Read only.
See also: VideoFormatDesc, VideoFormatDesc.MinSize, VideoFormatDesc.MaxSize

<< VideoFormatDesc


VideoFormatDesc::Subtype

VideoFormatDesc.Subtype Property
Returns the GUID of the media subtype of this video format description.
Syntax:
[VB.NET]
Public Subtype As Guid

[C#]
public Guid Subtype;
Limitations:

Read only.
See also: VideoFormatDesc, MediaSubtypes

<< VideoFormatDesc


VideoFormatDesc::CreateVideoFormat

VideoFormatDesc.CreateVideoFormat Method
This method creates a VideoFormat with the specified size based on the specification of this VideoFormatDesc.
Syntax:
[VB.NET]
Public Function CreateVideoFormat( sz As System.Drawing.Size ) As VideoFormat
Public Function CreateVideoFormat( width As Integer, height As Integer ) As VideoFormat

[C#]
public VideoFormat CreateVideoFormat( System.Drawing.Size sz );
public VideoFormat CreateVideoFormat( int width, int height );

Parameter | Description
sz | Size of the video format to be created.
width | Width of the video format to be created.
height | Height of the video format to be created.
Return value:

A VideoFormat instance with the specified size. An invalid VideoFormat is returned if the specified size does not match this VideoFormatDesc.

See also: VideoFormatDesc, VideoFormatDesc.IsValidSize, VideoFormat

<< VideoFormatDesc


VideoFormatDesc::IsValidSize

VideoFormatDesc.IsValidSize Method
This method checks whether a specified size matches the size constraints of this VideoFormatDesc.
Syntax:
[VB.NET]
Public Function IsValidSize( sz As System.Drawing.Size ) As Boolean
Public Function IsValidSize( width As Integer, height As Integer ) As Boolean

[C#]
public bool IsValidSize( System.Drawing.Size sz );
public bool IsValidSize( int width, int height );

Parameter | Description
sz | Size to be checked for validity.
width | Width to be checked for validity.
height | Height to be checked for validity.
Return value:

true, if a valid VideoFormat can be created with the specified size, otherwise false.

See also: VideoFormatDesc, VideoFormatDesc.CreateVideoFormat

<< VideoFormatDesc


VideoNorm

A VideoNorm object contains information about a video norm supported by the current video capture device.

Example

This example illustrates how to obtain the first available video norm.

[VB.NET]
Dim Nrm As VideoNorm
Nrm = IcImagingControl1.VideoNorms(0)

[C#]
VideoNorm Nrm = ICImagingControl1.VideoNorms[0];

Information

Namespace: TIS.Imaging
Introduced in version 1.x

Properties

Property | Description
Name | Returns the name of the VideoNorm.

<< Classes


VideoNorm::Name

VideoNorm.Name Property
Returns the name of the VideoNorm.
Syntax:
[VB.NET]
Public Name As String

[C#]
public string Name;
Limitations:

Read only.
Remarks:

Selecting devices, input channels, video norms and video formats is shown in the Making Device Settings chapter.

Sample:

This example selects the first available video norm.

[VB.NET]
Dim Nrm As VideoNorm
Nrm = IcImagingControl1.VideoNorms(0)
IcImagingControl1.VideoNorm = Nrm.Name

[C#]
VideoNorm Nrm = ICImagingControl1.VideoNorms[0];
ICImagingControl1.VideoNorm = Nrm.Name;
See also: VideoNorm

<< ICImagingControl.VideoNorm


Enumerations

Complete list of all enumerations.

Enumerations

Enumeration | Description
AbsDimFunction | tAbsDimFunction enumerates all the possible dimension functions. The dimension functions describe how to map slider values to property values to achieve the best usability for your programs.
DeBayerModes | The DeBayerModes enumeration is used to set the debayering algorithm.
DeBayerStartPatterns | Enumeration containing all possible bayer start patterns of the first row of the image data.
EventExecutionMode | The EventExecutionMode enumeration describes the possible execution modes of an event, such as the ICImagingControl.ImageAvailable event.
ExternalTransportModes | The ExternalTransportModes represent the modes that can set, by calling ICImagingControl.ExternalTransportMode
ICImagingControlColorformats | The ICImagingControlColorformats represent the formats that specify the pixel depth of all image buffers. The pixel depth of all image buffers is set with a call to ICImagingControl.MemoryCurrentGrabberColorformat
OverlayColorModes | The members of this enumeration are used to set the color format of the OverlayBitmap, using OverlayBitmap.ColorMode.
PathPositions | PathPositions enumerates the possible positions of the OverlayBitmap in the image stream.
StandardContainer | StandardContainer enumerates the available MediaStreamContainer.

<< Reference


refenum::AbsDimFunction

refenum.AbsDimFunction
tAbsDimFunction enumerates all the possible dimension functions. The dimension functions describe how to map slider values to property values to achieve the best usability for your programs.
AbsDimFunction is declared in ICImagingControl.
Name | Description
eAbsDimFunc_Linear | The dimension function is linear.
eAbsDimFunc_Log | The dimension function is logarithmic.
eAbsDimFunc_Other | The dimension function is of another type. This is currently not defined, if you encounter this value use linear mapping instead.

<< Enumerations


refenum::ExternalTransportModes

refenum.ExternalTransportModes
The ExternalTransportModes represent the modes that can set, by calling ICImagingControl.ExternalTransportMode
ExternalTransportModes is declared in TIS.Imaging.
Name | Description
ET_MODE_PLAY | Play
ET_MODE_STOP | Stop
ET_MODE_FREEZE | Pause
ET_MODE_REWIND | Rewind
ET_MODE_FASTFORWARD | Fast forward

<< Enumerations


refenum::ICImagingControlColorformats

refenum.ICImagingControlColorformats
The ICImagingControlColorformats represent the formats that specify the pixel depth of all image buffers. The pixel depth of all image buffers is set with a call to ICImagingControl.MemoryCurrentGrabberColorformat
ICImagingControlColorformats is declared in TIS.Imaging.
Name | Description
ICRGB32 | 32 bit color depth
ICRGB24 | 24 bit color depth
ICRGB565 | 16 bit color depth with red 5 green 6 blue 5 bit encoding
ICRGB555 | 16 bit color depth with red 5 green 5 blue 5 bit encoding
ICY8 | 8 bit grayscale, bottom up
ICUYVY | UYVY color format
eY800 | 8 bit Y format, top down
eYGB0 | 16 bit Y (10 bit valid) format
eYGB1 | 16 bit Y (10 bit valid) format
eBY8 | 8 bit bayer raw format. See Debayering for information on how to handle this format.

<< Enumerations


IC Imaging Control Standard Filters

IC Imaging Control comes with several standard frame filters. They can be explored with the Filter Inspector application.

The frame filter module stdfilters.ftf contains four filters:

  • DeBayer: Converts raw image data to RGB
  • DeNoise: Denoising by image integration
  • ROI: Region of Interest
  • Rotate Flip: Rotation and Flipping
  • Bayer to Y800: Converts BY8 to Y800

Module Files

The module file stdfilters.ftf is located in the classlib\release directory and the ICImagingControl.ocx's directory (common files directory). The debug compiled version of the module is named stdfiltersd.ftf and is located in the classlib\debug directory of the IC Imaging Control installation path.

Bayer to Y800 Filter

The Bayer to Y800 filter reinterprets the raw color data in BY8 images as Y800. Using this filter, it is possible to display the raw color data. The BY8 image data is de-bayered automatically before the video stream is rendered on screen.

DeBayer Filter

The DeBayer filter is used to convert raw image data into an RGB image. In a raw color image, every pixel represents a value for one basic color, instead of three as is the case for an RGB image. In order to get a real color image, the two missing colors have to be interpolated. This is exactly what this filter does.

DeNoise Filter

The DeNoise filter reduces noise in the frames by averaging a number of frames.

ROI Filter

The ROI filter cuts a region of interest out of the incoming frames. It creates a new output video format.

Rotate Flip Filter

The Rotate Flip filter allows image data to be flipped and rotated in steps of 90 degrees.

<< IC Imaging Control .NET Component User's Guide


Bayer to Y800 Filter

The Bayer to Y800 filter reinterprets the raw color data in BY8 images as Y800. Using this filter, it is possible to display the raw color data. The BY8 image data is de-bayered automatically before the video stream is rendered on screen.

Using the Bayer to Y800 Filter

The Bayer to Y800 filter is loaded by an application using following code:

[VB.NET]
Dim BY8toY800Filter As FrameFilter
BY8toY800Filter = IcImagingControl1.FrameFilterCreate("Bayer to Y800", "")
If BY8toY800Filter Is Nothing Then
    MsgBox("Failed to create BY8toY800Filter")
Else
    IcImagingControl1.DeviceFrameFilters.Add(BY8toY800Filter)
End If

[C#]
FrameFilter BY8toY800Filter;
BY8toY800Filter = ICImagingControl1.FrameFilterCreate("Bayer to Y800", "");

if (BY8toY800Filter == null)
    MessageBox.Show("Failed to create BY8toY800Filter");
else
    ICImagingControl1.DeviceFrameFilters.Add(BY8toY800Filter);

Parameters

The Bayer to Y800 filter does not have any parameters.

Property Dialog

The Bayer to Y800 filter does not have a property dialog.

<< IC Imaging Control Standard Filters


DeBayer Filter

The DeBayer filter is used to convert raw image data into an RGB image. In a raw color image, every pixel represents a value for one basic color, instead of three as is the case for an RGB image. In order to get a real color image, the two missing colors have to be interpolated. This is exactly what this filter does.

Using the DeBayer Filter

The DeBayer filter is loaded by an application using the following code:

[VB.NET]
Dim DeBayerFilter As FrameFilter
DeBayerFilter = IcImagingControl1.FrameFilterCreate("DeBayer", "")

If DeBayerFilter Is Nothing Then
    MsgBox("Failed to create DeBayerFilter")
Else
    IcImagingControl1.DeviceFrameFilters.Add(DeBayerFilter)
End If

[C#]
FrameFilter DeBayerFilter;
DeBayerFilter = ICImagingControl1.FrameFilterCreate("DeBayer", "");

if( DeBayerFilter == null )
    MessageBox.Show("Failed to create DeBayerFilter");
else
    ICImagingControl1.DeviceFrameFilters.Add(DeBayerFilter);

Parameters

There are two parameters that control the de-bayering process:

Start Pattern
The parameter Start Pattern defines how the Bayer Mosaic pattern in the raw image data is to be interpreted.
Available start patterns are:
  • BG: The raw image data starts with a blue/green line. Set Start Pattern to 0.
  • GB: The raw image data starts with a green/blue line. Set Start Pattern to 1.
  • GR: The raw image data starts with a green/red line. Set Start Pattern to 2.
  • RG: The raw image data starts with a red/green line. Set Start Pattern to 3.
Mode
The Mode parameter selects the algorithm used to de-bayer the raw image data.
Available algorithms are:
  • Nearest Color: Simple and fast algorithm, but rather bad output image quality. Set Mode to 0.
  • Bilinear: Fast algorithm producing good output image quality. Set Mode to 1.
  • Edge Sensing: This algorithm has the best output image quality but is rather slow. Set Mode to 2.

If the algorithm should be set programmatically, then following code can be used:

[VB.NET]
' Retrieve the current mode.
Dim mode As Integer
mode = DeBayerFilter.GetIntParameter("Mode")

' Set a new Mode.
mode = 1
DeBayerFilter.SetIntParameter("Mode", mode)

[C#]
// Retrieve the current mode.
int mode = DeBayerFilter.GetIntParameter("Mode");

// Set a new Mode.
mode = 1;
DeBayerFilter.SetIntParameter("Mode", mode);

Property Dialog

All parameters can be accessed using the built-in property dialog. The property dialog of the DeBayer filter is as follows:

<< IC Imaging Control Standard Filters


DeNoise Filter

The DeNoise filter reduces noise in the frames by averaging a number of frames.

Using the DeNoise Filter

The DeNoise filter is loaded by an application using the following code:

[VB.NET]
Dim DeNoiseFilter As FrameFilter
DeNoiseFilter = IcImagingControl1.FrameFilterCreate("DeNoise", "")

If DeNoiseFilter Is Nothing Then
    MsgBox("Failed to create DeNoiseFilter")
Else
    IcImagingControl1.DeviceFrameFilters.Add(DeNoiseFilter)
End If

[C#]
FrameFilter DeNoiseFilter;
DeNoiseFilter = ICImagingControl1.FrameFilterCreate("DeNoise", "");

if( DeNoiseFilter == null )
    MessageBox.Show("Failed to create DeNoiseFilter");
else
    ICImagingControl1.DeviceFrameFilters.Add(DeNoiseFilter);

Parameters

The only parameter of the DeNoise filter is the DeNoise Level:

DeNoise Level
The parameter DeNoise Level determines the number of frames to be averaged.
Note: The actual number of frames that are averaged is 2^n, so when setting DeNoise Level to 2, 4 frames are averaged.
This parameter can only be set while the live video stream is stopped.

Property Dialog

The number of frames to be averaged can be adjusted in the filter's property dialog:

Programmatically Access the Parameter

The following source code can be used, if the parameter should be set by an application:

[VB.NET]
' Retrieve the current denoise level.
Dim level As Integer
level = DeNoiseFilter.GetIntParameter("DeNoise Level")

' Set a new denoise level.
level = 3
If Not IcImagingControl1.LiveVideoRunning Then
    ' A new denoise level can only be set, while the live video is stopped.
    DeNoiseFilter.SetIntParameter("DeNoise Level2", level)
End If

[C#]
// Retrieve the current denoise level.
int level = DeNoiseFilter.GetIntParameter("DeNoise Level");

// Set a new denoise level.
level = 3;
if( !ICImagingControl1.LiveVideoRunning )
{
    // A new denoise level can only be set, while the live video is stopped.
    DeNoiseFilter.SetIntParameter("DeNoise Level2", level);
}

<< IC Imaging Control Standard Filters


ROI Filter

The ROI filter cuts a region of interest out of the incoming frames. It creates a new output video format.

Using the ROI Filter

The ROI filter is loaded by an application using following code:

[VB.NET]
Dim ROIFilter As FrameFilter
ROIFilter = IcImagingControl1.FrameFilterCreate("ROI", "")

If ROIFilter Is Nothing Then
    MsgBox("Failed to create ROIFilter")
Else
    IcImagingControl1.DeviceFrameFilters.Add(ROIFilter)
End If

[C#]
FrameFilter ROIFilter;
ROIFilter = ICImagingControl1.FrameFilterCreate("ROI", "");

if (ROIFilter == null)
    MessageBox.Show("Failed to create ROIFilter");
else
    ICImagingControl1.DeviceFrameFilters.Add(ROIFilter);

Parameters

The part of the image that is copied to the destination frame is determined by four filter parameters:

Left
This value specifies the left column on the source frame at which the region of interest (ROI) starts. This value is used to move the region of interest horizontally to the source frame. It can be changed regardless of whether the live video is running or not.
Top
This value specifies the top row on the source frame at which the region of interest starts. This value is used to move the region of interest vertically to the source frame. It can be changed regardless of whether the live video is running or not.
Width
This value specifies the width of the region of interest. It can only be set while the live video is stopped. Otherwise, the resulting video format would be changed.
The width will be aligned to eight pixels in the filter.
Height
This value specifies the height of the region of interest. It can only be set while the live video is stopped. Otherwise, the resulting video format would be changed.

Property Dialog

The dimensions and the start positions of the region of interest can be specified in the ROI filter's property dialog:

Programmatically Access the Parameter

The following source code can be used, if the parameter should be set by an application:

[VB.NET]
Dim left As Integer
Dim top As Integer
Dim height As Integer
Dim width As Integer

' Retrieve the current ROI rectangle.
left = ROIFilter.GetIntParameter("Left")
top = ROIFilter.GetIntParameter("Top")
height = ROIFilter.GetIntParameter("Height")
width = ROIFilter.GetIntParameter("Width")

' Set a new ROI.
left = 100
top = 50
' The position of the ROI can be set, regardless of whether the live video is running
' because the size of the resulting video format is not changed.
ROIFilter.SetIntParameter("Left", left)
ROIFilter.SetIntParameter("Top", top)

If Not IcImagingControl1.LiveVideoRunning Then
    ' A new ROI width and height can only be set, while the live video is stopped. Otherwise,
    ' an error is returned by setParameter();
    height = 120
    width = 180
    ROIFilter.SetIntParameter("Height", height)
    ROIFilter.SetIntParameter("Width", width)
End If

[C#]
// Retrieve the current ROI rectangle.
int left = ROIFilter.GetIntParameter("Left");
int top = ROIFilter.GetIntParameter("Top");
int height = ROIFilter.GetIntParameter("Height");
int width = ROIFilter.GetIntParameter("Width");

// Set a new ROI.
left = 100;
top = 50;

// The position of the ROI can be set regardless of whether the live video is running
// because the size of the resulting video format is not changed.
ROIFilter.SetIntParameter("Left", left);
ROIFilter.SetIntParameter("Top", top);

if( !ICImagingControl1.LiveVideoRunning )
{
    // A new ROI width and height can only be set, while the live video is stopped.
    // Otherwise, an error is returned by setParameter();
    height = 120;
    width = 180;
    ROIFilter.SetIntParameter("Height", height);
    ROIFilter.SetIntParameter("Width", width);
}

<< IC Imaging Control Standard Filters


Rotate Flip Filter

The Rotate Flip filter allows image data to be flipped and rotated in steps of 90 degrees.

Using the Rotate Flip Filter

The Rotate Flip filter is loaded by an application using the following code:

[VB.NET]
Dim RotateFlipFilter As FrameFilter
RotateFlipFilter = IcImagingControl1.FrameFilterCreate("Rotate Flip", "")

If RotateFlipFilter Is Nothing Then
    MsgBox("Failed to create RotateFlipFilter")
Else
    IcImagingControl1.DeviceFrameFilters.Add(RotateFlipFilter)
End If

[C#]
FrameFilter RotateFlipFilter;
RotateFlipFilter = ICImagingControl1.FrameFilterCreate("Rotate Flip", "");

if( RotateFlipFilter == null )
    MessageBox.Show("Failed to create RotateFlipFilter");
else
    ICImagingControl1.DeviceFrameFilters.Add(RotateFlipFilter);

Parameters

The part of the image that is copied to the destination frame is determined by four filter parameters:

Rotation Angle
This parameter sets the rotation angle.
Available angles are:
  • 0°
  • 90°
  • 180°
  • 270°
Please note that this parameter can only be changed in steps of 180° when live mode is running. Otherwise, the changes would alter the output video format.
Flip V
This parameter determines whether the image should be flipped vertically. As it is a boolean parameter, valid values are true and false. The setting of the flip parameters does not cause a video format change. Thus, they can be set regardless of whether the live video is running or not.
Flip H
This parameter determines whether the image should be flipped horizontally. As it is a boolean parameter, valid values are true and false. The setting of the flip parameters does not cause a video format change. Thus, they can be set regardless of whether the live video is running or not.

Property Dialog

The rotation angle and flipping modes can be specified in the filter's property dialog:

Programmatically Access the Parameters

If the parameters should be set by an application, following source code can be used:

[VB.NET]
Dim angle As Integer
Dim newAngle As Integer
Dim flipVertical As Boolean
Dim flipHorizontal As Boolean

' Retrieve the current parameter settings.
angle = RotateFlipFilter.GetIntParameter("Rotation Angle")
flipVertical = RotateFlipFilter.GetBoolParameter("Flip V")
flipHorizontal = RotateFlipFilter.GetBoolParameter("Flip H")

' Change the parameters.
newAngle = 90 ' Only the values 0, 90, 180 270 are allowed.

' If the rotation value is 90 or 270, then the resulting video format
' is changed. Thus, the new value can only be set while the live video is
' stopped. Otherwise, an error is returned.
If Math.Abs(angle - newAngle) = 90 Or Math.Abs(angle - newAngle) = 270 Then
    If Not IcImagingControl1.LiveVideoRunning Then
        RotateFlipFilter.SetIntParameter("Rotation Angle", newAngle)
    End If
Else
    RotateFlipFilter.SetIntParameter("Rotation Angle", newAngle)
End If

' The flip parameters do not cause a video format change, so they can be
' set regardless of whether the live video is running.
flipVertical = True
flipHorizontal = True
RotateFlipFilter.SetBoolParameter("Flip V", flipVertical)
RotateFlipFilter.SetBoolParameter("Flip H", flipHorizontal)

[C#]
// Retrieve the current parameter settings.
int angle = RotateFlipFilter.GetIntParameter("Rotation Angle");
bool flipVertical = RotateFlipFilter.GetBoolParameter("Flip V");
bool flipHorizontal = RotateFlipFilter.GetBoolParameter("Flip H");

// Change the parameters.
int newAngle = 90; // Only the values 0, 90, 180 270 are allowed.

// If the rotation value is 90 or 270, then the resulting video format
// is changed. Thus, the new value can only be set while the live video is
// stopped. Otherwise, an error is returned.
if( Math.Abs(angle - newAngle) == 90 || Math.Abs(angle - newAngle) == 270 )
{
    if( !ICImagingControl1.LiveVideoRunning )
    {
        RotateFlipFilter.SetIntParameter("Rotation Angle", newAngle);
    }
}
else
{
    RotateFlipFilter.SetIntParameter("Rotation Angle", newAngle);
}

// The flip parameters do not cause a video format change, so they can be
// set regardless of whether the live video is running.
flipVertical = true;
flipHorizontal = true;
RotateFlipFilter.SetBoolParameter("Flip V", flipVertical);
RotateFlipFilter.SetBoolParameter("Flip H", flipHorizontal);

<< IC Imaging Control Standard Filters


Project Wizards for Visual Studio

For Visual Basic and Visual C#, there are wizards that allow to easily setup an application that uses IC Imaging Control, as well as setup a frame filter and frame filter module.

All IC Imaging Control wizard names start with "IC" e.g. "IC Frame Filter Class".

Application Wizard

This chapter shows how to create a new imaging application, using the application wizard.

Frame Filter Class Wizard

This chapter shows how to create a new frame filter class, using the frame filter class wizard.


Application Wizard

This chapter shows how to create a new imaging application, using the application wizard.

Introduction

The application wizard creates the project for a complete imaging application. The following functionality is available out of the box:

  • Event handler to open a video capture device
  • Event handler for image settings
  • Event handler to start and stop the live video
  • Automatic reload the previously used video capture device

Optional functions are:

  • Add image processing capabilities
  • Display the result of the image processing, instead of the live video

How to use

First of all, start Visual Studio 2003. As soon as the Start Page appears, click on the New Project button. If this dialog does not appear, select File -> New -> Project from Visual Studio's menu.

You should see the following dialog:

Select the icon labeled IC Application, and enter a valid project name into the Name input field, for example "ImageProcessing". Then, click on the OK button. Once this step has been competed, you can set the projects parameters:

Create menubar / Create buttons radio buttons
This setting determines whether: i) the application design contains an menubar for user input; or whether: ii) the application design uses buttons for the user input
Create toolbar check box
When this check box is checked, an toolbar is inserted into the applications form. This checkbox is only aveilable, if Create menubar is enabled.
Add image processing functionality check box
When this check box is checked, an image processing method is inserted into the application. For demonstration purposes, the image is inverted.
Snap an image manually / Snap images automatically radio buttons
This setting determines whether: i) the image processing method is applied to a frame only when the user clicks on a menu entry; or whether: ii) the image processing method is applied to all frames.
Display processed image check box
When this check box is checked, the resulting image of the image processing is displayed instead of a live video.
Installation path text box
Enter the install directory of IC Imaging Control in this field. It is needed to find the IC Imaging Control .NET component.

Resulting Application

Once you have followed all the steps on this page, click on the Finish button to finish the project. The project will then be created by the wizard. The newly created application should look as follows:

<< Project Wizards for Visual Studio


Frame Filter Class Wizard

This chapter shows how to create a new frame filter class, using the frame filter class wizard.

Introduction

The frame filter class wizard creates the source code for a frame filter class. For demonstration purposes, the image processing that has been implemented shows how to inverts the incoming frames. This should be overwritten by the programmer.

How to use

Right-click your project in the Solution Explorer and select Add... -> Add New Item... or use the main menu and select Project -> Add New Item.... In the following dialog, select the entry IC Add Frame Filter.

Click the Open button and the next dialog shows the available options to create a frame filter class:

Input field description

Class name
This is the name of the class e.g. InverterFilter.
Namespace
This is the name of the namespace in which the new class will be declared. The programmer may overwrite this name.
Filename
This is the name of the source code file of the class. The name is generated by the class wizard. The programmer may overwrite this name.
Notify at start and stop live video
If this check box is checked, then the frame filter class wizard overrides the methods of FrameFilterImpl that are called when LiveStart and LiveStop are called. The methods are named NotifyStart and NotifyStop. A new boolean member variable, called m_bLiveVideoRunning is added to the class. In your Transform method, you can use this variable to determine whether live video is running and thus certain actions have to be performed.

Once you have made all the above inputs, click on the Finish button in order for the wizard to create the class.

<< Project Wizards for Visual Studio