Technical Application Note (TAN2013008): Using Cognex VisionPro with FLIR GigE Vision Machine Vision Cameras
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.
Before you use your camera, we recommend that you are aware of the following resources available from our Downloads page:
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
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
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.
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:
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.
The Settings tab is where the basic imaging controls can be found.
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
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
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
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.
Feature – GigE Vision attributes name.
Value – Use this field to read or write the GigE Vision attribute values.
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
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 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.
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.
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.
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
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.
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: