The first step is to enumerate all of the GenTL frame grabbers in the system. A collection of all GenTL frame grabbers can be created and enumerated as shown:

CogFrameGrabberGenTLs genTLfgs = new CogFrameGrabberGenTLs();
foreach (ICogFrameGrabber fg in genTLfgs)
{
        // Do something with each "fg".
}

CogFrameGrabberGenTLs genTLfgs = new CogFrameGrabberGenTLs();
foreach (ICogFrameGrabber fg in genTLfgs)
{
        // Do something with each "fg".
}

Each ICogFrameGrabber instance represents a single GenTL camera. Remember that the camera is known as the "remote device" in GenTL, and all of its XML features will be prefixed with RD_.

You need to pick a video format for your chosen camera. The video format is a string that tells the camera the desired setting for the PixelFormat feature of the camera, known as RD_PixelFormat in VisionPro. You'll need to pick one of the strings from this list:

• Generic GenICam (Mono8)
• Generic GenICam (Mono10)
• Generic GenICam (Mono12)
• Generic GenICam (Mono14)
• Generic GenICam (Mono16)
• Generic GenICam (Mono10Packed)
• Generic GenICam (Mono12Packed)
• Generic GenICam (BayerGR8)
• Generic GenICam (BayerRG8)
• Generic GenICam (BayerGB8)
• Generic GenICam (BayerBG8)
• Generic GenICam (RGB8)
• Generic GenICam (YCbCr422_8_CbYCrY)
• Generic GenICam (YUV422_8_UYVY)

Each string identifies the format as a "GenICam" format. The exact name of the format – as specified in the GenICam Pixel Format Naming Convention (PFNC) – is contained within the parentheses.

Be aware that your camera will not support all of these formats. You must choose a format from this list that is appropriate for your application and supported by your camera. You can retrieve a list of supported format strings directly from the ICogFrameGrabber interface using code shown in the following example:

ICogFrameGrabber fg = genTLfgs[0];
CogStringCollection vfs = fg.AvailableVideoFormats;
foreach (string vf in vfs)
{
        System.Console.WriteLine(vf); // Print out the video format string
}

ICogFrameGrabber fg = genTLfgs[0];
CogStringCollection vfs = fg.AvailableVideoFormats;
foreach (string vf in vfs)
{
        System.Console.WriteLine(vf); // Print out the video format string
}

Note: Note: If you are acquiring images with the Cognex DSMax camera, the only supported video format is: "Cognex NullFormat". You must use exactly that string as your video format.

After choosing a video format string, you are ready to create an acquisition fifo (i.e. ICogAcqFifo) for your camera. The fifo allows you to acquire images from the camera, and allows you to set camera properties that will be used when acquiring from that fifo. You can create multiple fifos, each with its own set of camera properties, for a single camera. The fifo will ensure that the desired properties are pushed to the camera prior to starting the image acquisition.

Create a fifo with your chosen video format as shown in the following example:

ICogFrameGrabber fg = genTLfgs[0];
CogStringCollection vfs = fg.AvailableVideoFormats;

string chosenVF = vfs[0];  // Choose a video format here
ICogAcqFifo acqFifo = fg.CreateAcqFifo(chosenVF,
        CogAcqFifoPixelFormatConstants.Format8Grey /* This argument is IGNORED */,
        0 /* Always set camera port to zero for GenTL */,
        true);

ICogFrameGrabber fg = genTLfgs[0];
CogStringCollection vfs = fg.AvailableVideoFormats;

string chosenVF = vfs[0];  // Choose a video format here
ICogAcqFifo acqFifo = fg.CreateAcqFifo(chosenVF,
        CogAcqFifoPixelFormatConstants.Format8Grey /* This argument is IGNORED */,
        0 /* Always set camera port to zero for GenTL */,
        true);

Your chosen video format is the first argument to the CreateAcqFifo method. It specifies the desired RD_PixelFormat setting for the camera. The second argument is ignored and does not affect the RD_PixelFormat setting – or anything else.

The video format controls the format of the pixels acquired by the camera (using RD_PixelFormat). You can access the AcquiredPixelFormat property of the ICogAcqFifo to see what pixel format will be used. Notice that the name of the returned enumeration will correspond to a PNFC pixel format even if that name is not an exact match for the PFNC name.

VisionPro software will convert the acquired pixels into a VisionPro image before returning it to you. You can specify that image type using the OutputPixelFormat property of ICogAcqFifo. The four always-supported choices are:

• Grey8: Return an ICogImage8Grey image (with 8-bit monochrome pixels)
• Grey16: Return an ICogImage16Grey image (with 16-bit monochrome pixels)
• PlanarRGB8: Return an ICogImage24PlanarColor image (with 8-bit planes of Red, Green, and Blue pixels)
• Variable: Return one of the three types above: Whichever one is closest to the AcquiredPixelFormat.

The OutputPixelFormat can be set as shown:

acqFifo.OutputPixelFormat = CogImagePixelFormatConstants.Grey8;

acqFifo.OutputPixelFormat = CogImagePixelFormatConstants.Grey8;

There are three different ways to set the properties of a GenTL camera. The first two operate inside the acq fifo:

• A limited number of the most-commonly-used properties can – and must – be set using certain VisionPro interfaces that are available from ICogAcqFifo.
• All remaining camera properties can be set using the ICogAcqCustomProperties interface that is available from ICogAcqFifo.

Both of these techniques ensure that the property is written to the camera prior to every acquisition started by that fifo. The third method operates outside of any acq fifo:

• All camera properties can be set using the ICogGenTLAccess interface that is available directly from ICogFrameGrabber.

The following sections discuss the three methods in more detail, and the interactions between them:

• Interactions Between the Three Methods
• Method #1: Setting VisionPro Acq Fifo Properties
• Method #2: Setting Custom Acq Fifo Properties
• Method #3: Setting Properties Using the Frame Grabber
• What Features Does My Frame Grabber Support?

If you set a particular camera feature using multiple methods the value that will be used when acquiring an image is the value from the lowest-numbered method.

For example, if you set a camera property using the third technique the value is written immediately to the desired camera feature. This changes the state of the camera immediately but does not guarantee that the state will be used during acquisition. A value written by the third method will be overwritten by the second method (when the acq fifo acquires an image), and this value can be overwritten again by the first method (when the fifo acquires an image). If a particular camera feature is set using all three methods, the value used by the first method will be the one in effect when an image is acquired by that fifo.

Commonly-used camera properties are controlled exclusively using VisionPro-specific abstract programming interfaces. These APIs enable users to write application code that is not dependent upon the type of camera in use. These commonly-used properties are shown in the following table:

The following sample code shows a brief example:

ICogAcqFifo acqFifo = fg.CreateAcqFifo(chosenVF,
        CogAcqFifoPixelFormatConstants.Format8Grey /* This argument is IGNORED */,
        0 /* Always set camera port to zero for GenTL */,
        true);

acqFifo.OwnedExposureParams.Exposure = 10;
acqFifo.OwnedContrastParams.Contrast = 0.2;
acqFifo.OwnedBrightnessParams.Brightness = 0.4;

int trigNum = 0;
ICogImage img = acqFifo.Acquire(out trigNum);

ICogAcqFifo acqFifo = fg.CreateAcqFifo(chosenVF,
        CogAcqFifoPixelFormatConstants.Format8Grey /* This argument is IGNORED */,
        0 /* Always set camera port to zero for GenTL */,
        true);

acqFifo.OwnedExposureParams.Exposure = 10;
acqFifo.OwnedContrastParams.Contrast = 0.2;
acqFifo.OwnedBrightnessParams.Brightness = 0.4;

int trigNum = 0;
ICogImage img = acqFifo.Acquire(out trigNum);

Refer to the appropriate sections of the Programming Reference for more information.

Remember that when the acquisition is started the values set using these APIs will overwrite any values that already exist in the camera. The corresponding camera features appear in red in QuickBuild.

If the camera property you wish to set is not one of the commonly-used ones previously listed, you can set its value for every acquire using the CustomProperties API on ICogAcqFifo. Each CustomProperty requires you to specify:

• The name of the camera property (e.g. RD_BalanceWhiteAuto)
• Your desired setting for that property (e.g. Continuous)
• The type of the property (e.g. Enumeration)

The acq fifo keeps a list of your desired custom property settings and will apply them before you acquire an image. The following example shows how to add a custom property to the list:

List<CogAcqCustomProperty> customList = acqFifo.OwnedCustomPropertiesParams.CustomProps;  // Get list

CogAcqCustomProperty cProp1 = new CogAcqCustomProperty("RD_BalanceWhiteAuto", "Continuous",
                                                                        CogCustomPropertyTypeConstants.TypeEnum);
customList.Add(cProp1);  // Add new property to list

acqFifo.OwnedCustomPropertiesParams.CustomProps = customList;  // Update list in fifo

List<CogAcqCustomProperty> customList = acqFifo.OwnedCustomPropertiesParams.CustomProps;  // Get list

CogAcqCustomProperty cProp1 = new CogAcqCustomProperty("RD_BalanceWhiteAuto", "Continuous",
                                                                        CogCustomPropertyTypeConstants.TypeEnum);
customList.Add(cProp1);  // Add new property to list

acqFifo.OwnedCustomPropertiesParams.CustomProps = customList;  // Update list in fifo

You can set any camera property using the OwnedGenTLAccess API that is available directly from ICogFrameGrabber. There are separate functions for setting double values, integer values, and string-based values. For example:

ICogFrameGrabber fg = genTLfgs[0];

try
{
        fg.OwnedGenTLAccess.SetDoubleFeature("RD_Gamma", 2.17);
        fg.OwnedGenTLAccess.SetIntegerFeature("RD_LUTIndex", 8);
        fg.OwnedGenTLAccess.SetFeature("RD_LUTEnable", "0");           // Boolean is "0" or "1".
        fg.OwnedGenTLAccess.SetFeature("RD_BalanceWhiteAuto", "Off");  // Enumeration
}
catch (Exception exc)
{
        Console.WriteLine(exc.ToString());
        throw;
}

ICogFrameGrabber fg = genTLfgs[0];

try
{
        fg.OwnedGenTLAccess.SetDoubleFeature("RD_Gamma", 2.17);
        fg.OwnedGenTLAccess.SetIntegerFeature("RD_LUTIndex", 8);
        fg.OwnedGenTLAccess.SetFeature("RD_LUTEnable", "0");           // Boolean is "0" or "1".
        fg.OwnedGenTLAccess.SetFeature("RD_BalanceWhiteAuto", "Off");  // Enumeration
}
catch (Exception exc)
{
        Console.WriteLine(exc.ToString());
        throw;
}

As shown, you should enclose calls to these functions in a try/catch block to handle any error conditions that may occur.

In addition, recall that settings made via OwnedGenTLAccess are not a part of the acq fifo, and these settings may be overwritten by the fifo if the fifo contains different values for the properties.

To see a list of all the features supported by a particular GenTL frame grabber you can use the GetAvailableFeatures method. For example, the helper function in the following example will return a string listing all available features from the given frame grabber, when used as shown:

// Call the "GetAllSubFeatures()" helper function using code like this:
//
//    ICogFrameGrabber fg = genTLfgs[0];
//    textBox1.Text = GetAllSubFeatures("Root", "", fg);
//
private string GetAllSubFeatures(string nodeName, string pad, ICogFrameGrabber fg)
{
        string tmp = "";
        CogStringCollection strColl = fg.OwnedGenTLAccess.GetAvailableFeatures(nodeName);

        foreach (string s in strColl)
        {
                tmp += pad + s + Environment.NewLine;
                if (fg.OwnedGenTLAccess.GetFeatureType(s) == CogCustomPropertyTypeConstants.TypeCategory)
                        tmp += GetAllSubFeatures(s, pad + "    ", fg);
        }

        return tmp;
}

// Call the "GetAllSubFeatures()" helper function using code like this:
//
//    ICogFrameGrabber fg = genTLfgs[0];
//    textBox1.Text = GetAllSubFeatures("Root", "", fg);
//
private string GetAllSubFeatures(string nodeName, string pad, ICogFrameGrabber fg)
{
        string tmp = "";
        CogStringCollection strColl = fg.OwnedGenTLAccess.GetAvailableFeatures(nodeName);

        foreach (string s in strColl)
        {
                tmp += pad + s + Environment.NewLine;
                if (fg.OwnedGenTLAccess.GetFeatureType(s) == CogCustomPropertyTypeConstants.TypeCategory)
                        tmp += GetAllSubFeatures(s, pad + "    ", fg);
        }

        return tmp;
}

Before exiting your application you should be sure to call Disconnect with the value False on all existing frame grabbers. For example:

foreach (ICogFrameGrabber fg in genTLfgs)
{
        fg.Disconnect(false);   // Disconnect all frame grabbers.
}

foreach (ICogFrameGrabber fg in genTLfgs)
{
        fg.Disconnect(false);   // Disconnect all frame grabbers.
}