Cognex VisionPro Adapter

Cognex VisionPro Adapter Has Been Discontinued

With version 5.10 of the Framegrabber SDK, the Cognex VisionPro Adapter has been discontinued. See also the Framegrabber SDK 5.10 Release Notes. You can replace the Cognex VisionPro adapter by the GenTL Interface.

Version 4

The Basler adapter to Cognex VisionPro is a supporting tool for the integration of Basler frame grabbers and Framegrabber SDK software into Cognex' VisionPro software package. It maps the Basler Framegrabber API into according interfaces which are needed for the direct integration into VisionPro. The Basler Cognex VisionPro adapter version 4 supports all frame grabbers available from Basler.

The Basler Cognex VisionPro Adapter allows you to implement configuration and control of Basler frame grabbers into your own software while you are using the Cognex VisionPro environment.

In addition, the adapter allows you to implement the configuration of cameras connected to a frame grabber as long as the cameras support the GenICam standard.

The adapter allows you to:

• Load different image processing functionality onto the frame grabber,
• Access and modify frame grabber configuration parameters,
• Grab images according to the frame grabber configuration,
• Use multiple Basler frame grabbers in a single system.

Supported Frame Grabbers

Frame Grabber Models

The Basler Cognex VisionPro adapter supports all frame grabbers available from Basler.

This includes microEnable V, and imaWorx frame grabbers.

Frame Grabber Functionality (Applets)

The functionality of a Basler frame grabber is defined in a specific hardware program, called applet. For each frame grabber model, a broad range of applets (i.e., a broad range of diverse functionalities) is available.

Each applet is optimized for a specific interface, a specific group of cameras, or even a specific field of application. You define the functionality of a Basler frame grabber via the applet you select for use on the grabber.

There are applet sets provided by Basler for each specific frame grabber model. In addition, you can build customized image processing applets using the graphical programming environment VisualApplets.

The Basler Cognex VisionPro adapter supports any functionality of a Basler frame grabber, e.g., the adapter supports frame grabbers running applets provided by Basler as well as frame grabbers running applets built with VisualApplets.

Supported Output Formats

The Basler Cognex VisionPro Adapter supports the following frame grabber output formats:

Cognex Name	Basler Name	Format
ck_pt_mono	FG_GRAY	Gray 8bit
ck_pt_mono16	FG_GRAY16	Gray 16bit
ck_pt_RGBplanar	FG_COL24	Color 24bit
ck_pt_RGB48 (not supported by Cognex)	FG_COL48	Color 48bit

Conversion to RGB Planar Output Formats

Cognex VisionPro supports RGB planar formats, but no RGB packed formats. Basler frame grabbers, however, support RGB packed formats, but no planar formats. Therefore, the Basler Cognex Vision Pro adapter converts the RGB packed formats (output by Basler frame grabbers) into RGB planar formats (supported by Cognex VisionPro). Conversion is done pixel by pixel. The data are buffered in the frame buffer separated by color channel (R,G, and B).

Data storage format for RGB24 on the frame grabber:

R(Px1)G(Px1)B(Px1)R(Px2)G(Px2)B(Px3) ... R(Pxn*m)G(Pxn)B(Pxn)

(Pxn: pixel value on image position n.)

Data storage format in frame buffer planar:

R(Px1)R(Px2)R(Px3) ... R(Pxn*m)
G(Px1)G(Px2)G(Px3) ... G(Pxn*m)
B(Px1)B(Px2)B(Px3) ... B(Pxn*m)

n = Image Width m = Image Height

The formats are handed over to VisionPro according to frame grabber parameter FG_FORMAT.

Multiple Video Streams

Basler frame grabbers are able to deliver multiple video streams. However, in Cognex VisionPro, each frame grabber (ICogFrameGrabber) is associated with only one video stream.

Therefore, the adapter maps each video stream (DMA) output of a Basler frame grabber to one Cognex frame grabber instance (ICogFrameGrabber).

How many DMA channels are created by the frame grabber depends on the applet that is running on the frame grabber.

Requirements

To use the Basler Cognex Adapter, your system needs to meet the following requirements:

Hardware

• At least one correctly installed Basler frame grabber
• Hardware Dongle for Cognex VisionPro (available at Cognex)

Software

• Operating System: Windows 7, Windows 8.1, or Windows 10
• Installation of Cognex VisionPro (installer available via Cognex)
• Installation of Cognex Acquisition Integration Kit (installer available via Cognex)
• Installation of Basler Framegrabber SDK
• Installation of the Basler Cognex Adapter

Info

Basler recommends using version 4 of the Basler Cognex Adapter together with version 9 of the Cognex VisionPro software as the adapter has been optimized for and tested with Cognex VisionPro 9.0. Later versions of VisionPro contain an internal GenTL Consumer that may interfere with the Vision Pro adapter.

Installation

For using the Basler Cognex VisionPro Adapter, it is essential you install

• the Basler Framegrabber SDK, and
• the Basler Cognex VisionPro Adapter itself.

For installation, you have two options. You can either

• install the Basler Framegrabber SDK together with the Cognex VisionPro Adapter in one step (using the Framegrabber SDK installer for both), or
• install Framegrabber SDK and adapter via separate installers.
  This is especially helpful if the Framegrabber SDK is already installed on your system and you want to add the installation of the Basler Cognex VisonPro Adapter.
  In addition, you can install the adapter manually, without using the installer.

The following sections describe all installation options:

Installing Framegrabber SDK and Adapter in One Step

To install the Basler Framegrabber SDK and the Basler Cognex Adapter together in one step:

1. Download the Framegrabber SDK installer from our website's download section. Make sure to select the corresponding installer:
2. Start the Framegrabber SDK installer by double-clicking on the file name.

3. Make sure the Cognex adapter is selected in the Select Components dialog of the Framegrabber SDK installer:

   

4. Finish your Framegrabber SDK installation.

The Basler Cognex VisionPro Adapter will be installed together with the Basler Framegrabber SDK software.

Installing the Adapter Separately

In case you have the Basler Framegrabber SDK already installed on your system, you can run a separate installer to install the Basler Cognex Adapter.

1. Download the Framegrabber SDK installer from the Basler website. Make sure to select the corresponding installer:
2. Double-click on the installer file SetupCognexAdapter_xxx.exe and follow the instructions of the installation wizard.

This is the normal installation procedure. However, in specific situations, e.g., when the adapter doesn't work as you might expect it, you can alternatively install the adapter manually.

Installing the Adapter Manually

To integrate the adapter for Basler frame grabber support manually, take the following steps:

1. Copy the file SiSoCognexAdapter.dll into the subdirectory \bin of your Basler Framegrabber SDK installation.
2. Open the registry editor.
3. In the registry editor, navigate to [HKEY_LOCAL_MACHINE\SOFTWARE\Cognex\AIK\AdapterSiso].
   If you can't find these folders, create them as necessary.
   It is important that the registry key [HKEY_LOCAL_MACHINE\SOFTWARE\Cognex\AIK] has write access for the actual user, otherwise VisionPro will have to be started with admin rights in order to load the Basler adapter DLL.

4. Add the following entries to AdapterSiso:

   PoolSize=dword:04000000
   PoolSizeQuantum=dword:000000002
   ServerNameBase=Cognex.AIKserver.AdapterSiSo
   UseExe=dword:00000001
   LibName=<SISOINSTALLDIR>\bin\SiSoCognexAdapter.dll
   

   where \<SISOINSTALLDIR> is your installation directory of the Basler Framegrabber SDK, e.g.: C:\Program Files\Basler\FramegrabberSDK5.x.x\bin\SiSoCognexAdapter.dll

   

Selecting an Applet

Basler provides acquisition applet sets for each frame grabber model. Every frame grabber must load an applet to be initialized, and a different applet means a different set of features.

For an applet to be loadable, it must be available both for the hardware and the software, and how this is done differs substantially between the different frame grabber families.

You can find more information about how to make an applet loadable in the microDiagnostics documentation.

One of the contained loadable applets is per default the active applet, as long as you don't define another applet to be the active one.

You can select any applet out of the applet set for your specific frame grabber model, or select an applet that has been designed by VisualApplets.

In version 4 of the Cognex adapter, the applet is selected according to these rules:

• First, the adapter checks if there is an environment variable SISO_COGNEX_APPLET_x, where "_x" represents the index for the board, e.g., "_0", pointing to an applet or an applet configuration file.
• If this environment variable isn't found, the adapter searches for the last configuration in the GenTL Producer for the frame grabber, saved under "%Appdata%/Basler" after closing GenTL.
• If this last configuration file also doesn't exist for the frame grabber, the adapter searches the actual active applet for the frame grabber.
• If the adapter doesn't find neither the environment variable, nor the last GenTL Producer configuration, and there is no active applet, the adapter will load the first loadable applet that it finds.

To select an applet using an environment variable:

1. Change the according system environment setting: SISO_COGNEX_APPLET_<x> = <AppletFilename>
   
   • represents the index of the board, e.g. "0" for the first board
   • is the path and file name of the applet to be used, for example: C:\Program Files\Basler\FramegrabberSDK\dll\iW-CXP12-Q\Acq_SingleCXP12x4Area.dll.
     For further details regarding the enumeration of Basler frame grabbers, refer to the Basler Framegrabber SDK documentation.
2. Increase the pool size if necessary:
   1. Open the registry editor.
   2. In the registry editor, navigate to [HKEY_LOCAL_MACHINE\SOFTWARE\Cognex\AIK\AdapterSiso].
   3. Change the value of key "PoolSize".
3. Close Cognex VisionPro.
4. Shut down the AIK Server via the Windows task manager.
5. Restart Cognex VisionPro.

Info

Each time you change an environment variable, you have to shut down the AIK server via the Windows task manager. Closing VisionPro isn't enough since closing this program doesn’t lead to a shut-down of the AIK server.

Only after restarting the VisionPro software (and thus re-starting the AIK server), your changes of system variables are activated.

The selected applet can be configured individually for each frame grabber which is installed in the system.

For information about how to initialize a frame grabber using a pre-defined configuration file, see Frame Grabber Initialization Using an MCF File.

Info

When using Dual applets (supporting two connected cameras) or Quad applets (supporting four connected cameras):

Even if only one physical frame grabber is installed, logically two/four different devices are listed in VisionPro under Image Acquisition Device/Frame Grabber – one for each possible camera. For more information, see Multiple Video Streams.

Testing Your Installation

You can test if the installation of the adapter was successful. You use the VisionPro tool QuickBuild for testing.

To test the installation of the adapter:

1. Make sure you selected an applet as described in Selecting an Applet.
2. Start VisionPro (R) QuickBuild.

3. Double-click on Image Source:

   

4. Select Camera:

   

If the installation of the adapter was successful, the Basler frame grabbers are listed in the combo box Image Acquisition Device / Frame Grabber with their model name, port connection number and serial number:

Available Parameters

This section describes the parameters you have available for specific tasks.

Library Information

The following parameters allow to get information about the used libraries:

Parameter Name	CogAdapterInterfaceID
Description	This feature returns the ID of the interface file used when the adapter was build.
Type	String
Access	Read

Parameter Name	CogAdapterVersion
Description	The version of the adapter DLL.
Type	String
Access	Read

Configuring a Frame Grabber

The functionality of your frame grabber you define via the applet you select for use on your frame grabber. An applet is a hardware program tailored for a specific camera interface, a specific topology, or even a specific field of application.

When you start out to configure your frame grabber, you actually start to configure the applet that is loaded onto your frame grabber. Which parameters are available for frame grabber configuration therefore depends on the applet you use.

Find all information about applet-specific parameters and their configuration in the according applet documentation.

The following parameters allow to set the applet parameters:

Parameter Name	FgFeatureKey
Description	This parameter holds the name of the applet parameter that you want to set or read via one of the parameters FgStringValue, FgIntValue, or FgFloatValue.
Type	String
Access	Read/Write

Parameter Name	FgStringValue
Description	Via this parameter, you can read/write applet parameters of type String. Make sure parameter FgFeatureKey points to the applet parameter you have in mind.
Type	String
Access	Read/Write

Parameter Name	FgIntValue
Description	Via this parameter, you can read/write applet parameters of type Integer. Make sure parameter FgFeatureKey points to the applet parameter you have in mind.
Type	Integer. Signed/unsigned and number of bytes depend on the applet parameter.
Access	Read/Write

Parameter Name	FgFloatValue
Description	Via this parameter, you can read/write applet parameters of type Double. Make sure parameter FgFeatureKey points to the applet parameter you have in mind.
Type	64-bit Float
Access	Read/Write

Info

Alternatively, you can use an *.mcf file to store and retrieve a specific applet configuration. For more information, see Frame Grabber Initialization Using an MCF File.

Configuring the Cameras

Configuring a camera you start by selecting a camera and establishing a connection to this camera. You do this via the Camera Connector Interface. Once you have selected and connected a specific camera, you can start the actual camera configuration.

You can use a Cognex frame grabber object (DMA channel) for configuring any camera on the physical frame grabber, even if the selected camera doesn't influence the data stream of the Cognex frame grabber object you use for camera configuration.

A Cognex frame grabber object has local access to one data stream, but global access to all cameras connected to a physical frame grabber.

Thus, you can configure a camera via any Cognex frame grabber object, no matter if the selected camera sends data to this Cognex frame grabber object or not.

Camera Connector Interface

The camera connector interface allows to detect and configure cameras that support the GenICam standard (CL and CXP). Sending commands via this interface changes the interface's state, as you can see in the figure below.

The following commands and parameters are available:

Parameter Name	InitializeCameraConnector
Description	If you are going to work with GenICam compatible cameras, start with calling this function.
Type	Command
Access	Execute
Availability	Always

Parameter Name	CloseCameraConnector
Description	Call this function when you are done and don't need to use the camera functions any longer.
Type	Command
Access	Execute
Availability	In following states: valid_lib, valid_port, invalid_port, valid_cam, invalid_cam

Parameter Name	Detect
Description	This function detects the available ports and the connected cameras.
Type	Command
Access	Execute
Availability	In following states: valid_lib, valid_port, invalid_port, valid_cam, invalid_cam

Parameter Name	StartAquisition
Description	Use exclusively this function to start image acquisition on the camera. Don't use the GenICam feature AcquisitionStart for this purpose.
Type	Command
Access	Execute
Availability	In state valid_cam

Parameter Name	StopAquisition
Description	Use exclusively this function to stop image acquisition on the camera. Don't use the GenICam feature AcquisitionStop for this purpose.
Type	Command
Access	Execute
Availability	In state valid_cam

Parameter Name	CameraCount
Description	This parameter holds the amount of cameras that have been detected on the active PortIndex.
Type	size_ta
Access	Read
Availability	In following states: valid_port, valid_cam, invalid_cam

Parameter Name	CameraIndex
Description	Use this parameter to select the camera you want to work with from the active PortIndex.
Type	size_ta
Access	Read/Write
Availability	In following states: valid_port, valid_cam, invalid_cam

Parameter Name	CameraName
Description	This parameter holds the name of the currently selected camera.
Type	String
Access	Read
Availability	In state valid_cam

Parameter Name	PortIndex
Description	Use this parameter to select the port you want to work on.
Type	size_ta
Access	Read/Write
Availability	In following states: valid_port, invalid_port, valid_cam, invalid_cam

Parameter Name	PortCount
Description	This parameter holds the number of available ports.
Type	size_ta
Access	Read
Availability	In following states: valid_port, invalid_port, valid_cam, invalid_cam

Configuring a Camera

For configuring a camera (which you have selected and connected as described in the previous sections), you have the following commands available.

Info

For detailed information on the specific target parameter names, refer to the camera documentation of the camera you are going to use.

The following parameters allow to set the camera parameters:

Parameter Name	CameraFeatureKey
Description	Use this parameter to specify the name of the camera parameter you are going to configure via CameraStringValue, CameraIntValue, CameraFloatValue, CameraBooleanValue, CameraEnumerationValue, or CameraCommand (see below).
Type	String
Access	Read/Write

Parameter Name	CameraStringValue
Description	Via this parameter, you can read/write camera parameters of type String. Make sure parameter CameraFeatureKey points to the target parameter you have in mind.
Type	String
Access	Read/Write

Parameter Name	CameraIntValue
Description	Via this parameter, you can read/write camera parameters of type Int. Make sure parameter CameraFeatureKey points to the target parameter you have in mind.
Type	Int
Access	Read/Write

Parameter Name	CameraFloatValue
Description	Via this parameter, you can read/write camera parameters of type Float. Make sure parameter CameraFeatureKey points to the target parameter you have in mind.
Type	Float
Access	Read/Write

Parameter Name	CameraBooleanValue
Description	Via this parameter, you can read/write camera parameters of type Boolean. Make sure parameter CameraFeatureKey points to the target parameter you have in mind.
Type	String
Access	Read/Write

Parameter Name	CameraEnumerationValue
Description	Via this parameter, you can read/write camera parameters of type Enumeration. Make sure parameter CameraFeatureKey points to the target parameter you have in mind.
Type	String
Access	Read/Write

Parameter Name	CameraCommand
Description	Use this parameter to execute the command you specified via parameter CameraFeatureKey.
Type	Command
Access	Read/Write

Image Acquisition

The following parameters allow to configure the actual image acquisition:

Parameter Name	BufferCount
Description	With BufferCount you define the number of buffers that are used for adapter-internal image acquisition. Note that changing this parameter causes deletion or allocation of buffers.
Type	size_ta
Access	Read/Write

Parameter Name	FrameCountSinceLastStart
Description	Counter: Counts the number of images the adapter received after last start of image acquisition.
Type	size_ta
Access	Read

Parameter Name	TimestampFrequency
Description	A time stamp is assigned to each image. This parameter states the resolution of the timer.
Type	Uint64_t
Access	Read

Parameter Name	AcquisitionStrategy
Description	Via parameter AcquisitionStrategy you define the handling mode for the stream buffers.
Type	Enumeration
Values	The following buffer handling modes are available: OldestFirst: See diagram below. The application always gets the buffer from the head of the Output Buffer Queue (thus, the oldest available one). If the Output Buffer Queue is empty, the application waits for a newly acquired buffer until the timeout expires. When data for a new buffer is available, the acquisition engine looks for any available buffer in the Input Buffer Pool, fills it, and appends it to the tail of the Output Buffer Queue. If the Input Buffer Pool is empty, the new data is dropped and an error is triggered. This buffer handling mode is typically used if every image frame is to be acquired and the mean processing time is lower than acquisition time. No buffer is discarded or overwritten in the Output Buffer Queue and all filled buffers are delivered in the order they were acquired. OldestFirstOverwrite: See diagram below. The application always gets the buffer from the head of the Output Buffer Queue (thus, the oldest available one). If the Output Buffer Queue is empty, the application waits for a newly acquired buffer until the timeout expires. When data for a new buffer is available, the acquisition engine looks for any available buffer in the Input Buffer Pool, fills it, and appends it to the tail of the Output Buffer Queue. If the Input Buffer Pool is empty and the Ouput Buffer Queue isn't empty, it discards the head of the Output Buffer Queue (i.e., the oldest buffer), overwrites it with the new data, and appends it to the tail of the Output Buffer Queue. If the Input Buffer Pool and the Output Buffer Queue are empty, the new data is dropped. This buffer handling mode is typically used if not every image frame is to be acquired and the application may not fall behind. NewestOnly: The application always gets the latest completed buffer (the newest one). If the Output Buffer Queue is empty, the application waits for a newly acquired buffer until the timeout expires. This buffer handling mode is typically used in a live display GUI where it is important that there is no lag between camera and display.
Access	Read/Write
Availability	While acquisition isn't active

Parameter Name	Transformation
Description	Cognex VisionPro doesn't accept RGB packed images. Via this parameter you define if images in RGB packed format are transformed into the Cognex compatible planar format or not. If you set the parameter to value NoTransformation, the images are discarded. If you set the parameter to value RGB8PackedToPlanar, RGB 8 packed images are transformed into RGB planar. The transformation is done in the CPU, therefore, setting the parameter to value RGB8PackedToPlanar may reduce the overall system performance. Note: At the moment, the adapter only supports conversion of Rgb8Packed images to planar format (and not, for example, the conversion of RGB16Packed).
Type	Enumeration
Values	NoTransformation RGB8PackedToPlanar
Access	Read/Write
Availability	While acquisition isn't active

OldestFirst Buffer Handling Mode

Acquisition Engine

Buffer Delivery

OldestFirstOverwrite Buffer Handling Mode

Acquisition Engine

Buffer Delivery

Frame Grabber Initialization Using an MCF File

A microEnable environmental configuration file (*.mcf) contains frame grabber parameterization data.

The *.mcf file contains the name of the applet to be used at frame grabber initialization, and the parameterization of this applet.

For information about how to create an *.mcf file, see the microDisplay X documentation.

You can initialize the frame grabber with an *.mcf file in the software you build with VisionPro. The frame grabber is immediately pre-configured and ready-to-run.

To initialize the frame grabber using an *.mcf file, change the following system environment variable:

SISO_COGNEX_APPLET_[x] = [ConfigurationFilename]

• [x] represents the index of the board, e.g. "0" for the first board
• [ConfigurationFilename] is the path and file name of the *.mcf file to be used, for example: C:\Program Files\SiliconSoftware\MyMCFs\my configuration.mcf

Triggering

Trigger Parameters

VisionPro offers the following trigger parameters:

• Manual Triggering
• Hardware Auto
• Hardware Semi-Auto
• Free Run

The parameter values can be changed individually for each parameter.

The VisionPro trigger options aren't used when you initialize the frame grabber within the VisionPro software by using the Frame Grabber Configuration File (microEnable environmental configuration file *.mcf). The configurations taken from this file always overwrite the VisionPro trigger settings.

The VisionPro trigger settings are only available if you don't use an *.mcf file for frame grabber initialization.

The VisionPro trigger modes are mapped to the applet trigger models as follows:

Acquisition Applets Camera Link – Area Scan and Line Scan

Cognex Name	Parameter Basler	Default Value of Basler Cognex Adapter	Basler Name
Manual Triggering	FG_TRIGGERMODE FG_EXSYNCON FG_CCSEL0	ASYNC_SOFTWARE_TRIGGER 1 CCEXSYNC	Software trigger (software triggers image acquisition via frame grabber)
Hardware Auto (setHardwareAutoTriggerMode)	FG_TRIGGERMODE FG_EXSYNCON FG_CCSEL0	ASYNC_SOFTWARE_TRIGGER 1 CCEXSYNC	External trigger
Hardware Semi-Auto	FG_TRIGGERMODE FG_EXSYNCON FG_CCSEL0	ASYNC_SOFTWARE_TRIGGER 1 CCEXSYNC	No Basler name, since Hardware auto and Hardware Semi-Auto are the same in the Basler Cognex Adapter
Free Run	FG_TRIGGERMODE	FREE_RUN	Free run

Advanced Acquisition Applets Camera Link – Area Scan

Cognex Name	Parameter Basler	Default Value of Basler Cognex Adapter	Basler Name
Manual Triggering	FG_AREATRIGGERMODE FG_TRIGGERCC_SELECT0 FG_TRIGGERSTATE	ATM_SOFTWARE CC_PULSEGEN0 TS_ACTIVE	Software trigger (software triggers image acquisition via frame grabber)
Hardware Auto (setHardwareAutoTriggerMode)	FG_AREATRIGGERMODE FG_TRIGGERCC_SELECT0 FG_TRIGGERSTATE	ATM_SOFTWARE CC_PULSEGEN0 TS_ACTIVE	External trigger
Hardware Semi-Auto	FG_AREATRIGGERMODE FG_TRIGGERCC_SELECT0 FG_TRIGGERSTATE	ATM_SOFTWARE CC_PULSEGEN0 TS_ACTIVE	No Basler name, since Hardware auto and Hardware Semi-Auto are the same in the Basler Cognex Adapter
Free Run	FG_TRIGGERSTATE	TS_SYNC_STOP	Free run

Advanced Acquisition Applets Camera Link – Line Scan (And Others)

For Advanced Acquisition Applets Line Scan on Camera Link frame grabbers, any trigger options are only available via the Frame Grabber Configuration File.

Exampleː Configuring and Using the Software Trigger

To get a software trigger pulse in Cognex VisionPro with the Basler Cognex VisionPro Adapter:

1. Set the parameters as shown in the following flow chart:

   

   Info

   The Camera Link parameter "FG_CCSEL0" is called "FG_TRIGGWECC_SELCET0" in the Cognex adapter.

   The following screenshot shows how to set the parameters:

   

2. Send a software trigger pulse to start the acquisition:

   1. Click the yellow Run QuickBuild Application button continuously.
   2. In the Imaging Device tab, enter FgIntValue in the Feature input field and click Read. Value 1 is displayed.
   3. Click Write to send the software trigger pulse.

---

1. This data type is always unsigned. See the C++ reference for details. ↩↩↩↩↩↩