Skip to content

Cognex VisionPro Adapter#

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.

Cognex VisionPro Adapter Overview Diagram

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).

Mapping of Video Stream Output to Multiple Frame Grabber Instances

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:

    Select Components Dialog

  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

    Regedit Settings

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:

    Image Source Entry

  4. Select Camera:

    Camera Button

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:

List of Frame Grabbers

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 Configuration Model

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.

Interface State Block Diagram

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#

OldestFirst Acquisition Engine

Buffer Delivery#

OldestFirst Buffer Delivery

OldestFirstOverwrite Buffer Handling Mode#

Acquisition Engine#

OldestFirstOverwrite Acquisition Engine

Buffer Delivery#

OldestFirstOverwrite 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:

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
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

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:

    Parameters 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:

    Setting 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. ↩↩↩↩↩↩