Subject

Technical Application Note (TAN2013008): Using Cognex VisionPro with FLIR GigE Vision Machine Vision Cameras

Applicable Product(s)

• All FLIR machine vision GigE Vision compliant cameras

Application Note Description

This application note provides information on how to configure and use GigE Vision cameras with Cognex VisionPro. It guides new and current VisionPro users to understand the basics of GigE Vision, and how GigE Vision cameras support VisionPro controls.

We tested VisionPro 8.2 SP1.

Preparing for Use

Before you use your camera, we recommend that you are aware of the following resources available from our Downloads page:

• Getting Started Manual for the camera—provides information on installing components and software needed to run the camera. 
• Technical Reference for the camera—provides information on the camera’s specifications, features and operations, as well as imaging and acquisition controls.
• Firmware updates—ensure you are using to most up-to-date firmware for the camera to take advantage of improvements and fixes.

Minimum System Requirements

• Gigabit Ethernet host adapter
• GigE Vision compatible camera
• Cognex VisionPro 5.0 or newer

Installation and Configuration

Cognex eBus Universal Pro Driver

The Cognex eBus Universal Pro Driver is a GigE Vision filter driver that must be enabled in order to use GigE cameras in Cognex. This driver operates between the camera and the Microsoft built-in UDP stack to filter out GigE vision stream protocol (GVSP) packets.  The CPU does not process all the packets, and therefore reduces CPU usage.

Network Properties Menu

Cognex GigE Vision Configuration Tool

Ensure the camera is enumerated correctly. The host adapter and the camera must be on the same subnet. Users can use the tool to manually set the IP address and the subnet mask of the host adapter or the camera.

Cognex GigE Vision Configuration Tool

Understanding GigE Vision

GigE Vision is a standard for camera control developed for Gigabit Ethernet cameras. All cameras supporting GigE Vision will interact the same way with software supporting GigE Vision such as VisionPro. FLIR GigE cameras such as Blackfly S, Blackfly, Flea3, Grasshopper3, and Grasshopper2 are GigE Vision compatible cameras that work seamlessly with GigE Vision software.

Each camera attribute such as shutter time is controlled by a specific GigE Vision attribute. All GigE Vision software provides a Graphical User Interface (GUI) to control these GigE Vision attributes. The following sections will describe what these controls are in VisionPro and how each control is mapped to the respective GigE Vision attribute.

Running Cognex VisionPro

Start a new Cognex VisionPro QuickBuild project and double click on Image Source and select Camera to bring up the Image Source configuration menu.

Accessing the Image Source menu

 In the Image Source configuration menu, users will find 5 different menu tabs that help the user control and configure the camera:

• Settings
• Strobe & Trigger
• Image Properties
• GigE
• Custom Properties

Each of these tabs will be explained in the following sections of this document. Where possible, the GigE Vision equivalent attribute will be described as well.

Settings

The Settings tab is where the basic imaging controls can be found.

Settings Menu

Exposure – Sets how long the image will be exposed.

Equivalent GigE Vision Attribute: ExposureTime

Brightness – Controls the Black level offset.

Equivalent GigE Vision Attribute: BlackLevel

Contrast – Controls signal amplification.

Equivalent GigE Vision Attribute: Gain

Timeout – The length of time VisionPro will wait for an image to return.

Equivalent GigE Vision Attribute: N/A

Strobe & Trigger

The Strobe & Trigger tab manages the GPIO of the camera.

Strobe & Trigger Menu

Manual – VisionPro turns on the camera and transmits an image. Frame rate will be low in this mode.

Equivalent GigE Vision Attribute:TriggerMode = Off

AcquisitionMode = SingleFrame

Free Run – Fee run without any triggering, allowing the camera to run at the maximum frame rate.

Equivalent GigE Vision Attribute: TriggerMode = Off

AcquisitionMode = Continous

Hardware Auto – Hardware trigger mode. Camera will only capture an image when it is externally triggerd.

Equivalent GigE Vision Attribute: TriggerMode = On

AcquisitionMode = Continous

Hardware Semi-Auto – Similar to Hardware Auto mode where an image is only captured when the camera is externally triggered. However, between each acquisiton, the camera will be turned off and on again similar the Manual mode.

Equivalent GigE Vision Attribute:TriggerMode = On

AcquisitionMode = SingleFrame

Image Properties

The Image Properties tab manages the resolution and pixel format of the camera.

Image Properties Menu

Origin X –Horizontal offset from the origin (in pixels).

Equivalent GigE Vision Attribute:OffsetX

Origin Y – Vertical offset from the origin (in pixels).

Equivalent GigE Vision Attribute: OffsetY

Width – Controls the width of the image.

Equivalent GigE Vision Attribute:Width

Height – Controls the height of the image.

Equivalent GigE Vision Attribute:Height

GigE

This tab allows users to read and write from GigE Vision attributes, if the name of the attribute is known. The basic camera and network information is also displayed in this tab.

GigE Menu

Feature – GigE Vision attributes name.

Value – Use this field to read or write the GigE Vision attribute values.

Custom Properties

This tab allows users to browse through all the GigE Vision attributes and change them if desired. The attributes in red are attributes that are controlled by VisionPro and cannot be changed from this control menu. For example, the ExposureTime attribute is red because it is controlled by Exposure, under the Settings tab.

Custom Properties Menu

Once the desired configurations have been set, go back to the Cogjobs window and click on the Live Display icon to enable image display.

Show Live Display

Bandwidth Control

The User Datagram Protocol (UDP) used by the GigE Vision standard provides no guaranteed transmission or fixed timing mechanism. Therefore, bandwidth must be managed by adjusting packet size and packet delay, based on desired resolution and frame rate.

Packet Size (GevSCPSPacketSize)

Packet size influences the number of interrupts generated which affects CPU usage. The larger the packet size, the fewer the interrupts for the same amount of data. To minimize CPU usage, increase the packet size. This attribute can be found in the Custom Properties tab.

The upper limit depends on the host adapter, the Ethernet switches (if used), and the camera.

From the Cognex GigE Vision Configuration Tool, open the Windows Adapter Properties. Adjust the packet size of the host adapter to ~9000 (the standard jumbo packet size). If your adapter does not support such a large packet (or MTU) size, then you will experience slightly higher CPU usage.

Packet Delay (GevSCPD)

The Packet delay acts like a gap between packets during transmission. This delay allows the host to process the current packet before the arrival of the next one. Increasing the packet delay value from zero reduces the effective bandwidth assigned to the camera and also reduces the possibility of dropped frames.

Adjusting Packet Size and Packet Delay

The packet size control is under the GigE tab. The packet delay control is found under the Custom Properties tab. We recommend setting the packet size to the largest packet size supported by the network adapter. Use packet delay to manage the bandwidth allocated to each camera.

Troubleshooting Tips

XML Cache

When the camera firmware is updated, the XML is often updated as well. To ensure the newest XML file is used, users must manually clear the XML cache. Once the XML file is deleted, VisionPro downloads a new XML file from the camera.

The XML cache file is located in C:\Program Files\Cognex\Common\genicam\cache

Missing Custom Properties

In some cases, a property must be changed from auto to manual in order to access further settings. For example, to set the exposure time, exposure must be in manual mode.

VisionPro loads the current properties, either default or user set, into the Image Source window when the camera is selected. Any changes made to the properties, such as changing from auto to manual, must be reloaded to take effect. To reload, close the Image Source window and reopen.

Changing to a Mode that Changes the Resolution

When changing video modes, the user may implement a binning mode which changes the resolution as well. See KB 10085 Understanding Format_7 region of interest and pixel binning for more information.

To change to a mode that also changes the resolution:

1. Connect the camera to the PC.
2. Launch the Cognex Vision Pro QuickBuild Application from Start Menu → Cognex → VisionPro → Quickbuild.
3. Double-click on Image Source to launch the Image Source and VisionPro QuickBuild Job Editor.
4. In the Image Source Configuration window, select Custom Properties tab.
5. Add ImageFormatControl->VideoMode, then switch to the desired mode.
6. Switch to the Image Properties tab, then change the resolution to the appropriate width/height.
7. Exit out of the Image Source window, then in the CogJob1 window, select the Run Job Continuously button.