Interface Viper.NET to Cognex VisionPro

Within Viper.NET some blocks in ToolGroups get special functions. For example, results of a tool of Viper.NET can be displayed elsewhere or configuration options for saving images can be adjusted.

Naming conventions

Some special functions are implemented as a naming convention: standard blocks, for example a CogToolBlock and its Terminals, get a special function within Viper.NET as soon as their name matches a pattern. Depending on which function it is, the name must match exactly, or the name must start with the pattern. If the name must match exactly, the CogToolBlock must be created on the top level (e.g. at InputDataBlock).

Using Viper.NET, templates for the naming convention ToolBlocks are installed and integrated via the Cognex VisionPro ToolBox:



Images that are acquired by the Image acquisition job before the toolgroup is executed are given to the toolgroup in a CogToolBlock named Images. Each output terminal of type ICogImage is assigned a Image source: in ToolGroup Item Editor. If the image source is active, the terminal value is set to the corresponding image before the ToolGroup is executed.



At job level, BV parameters can be managed centrally. Definition and use takes the form of a CogToolBlock named InputBlock: the output terminals of such a block are automatically recognized as parameters. When changes are made to the parameterization, the values of the terminals are adjusted.



Overarching Global parameters are provided in CogToolBlock, whose name starts with GlobalVisionParams. Simply creating an output terminal does not define a new global parameter: The configuration is done within the job-editor.



Input values from external data sources like a controller are provided as output terminals in a CogToolBlock named InputDataBlock. Linking GIO data to the terminals is done in the Data tab of the Toolgroup Item Editor. When the ToolgroupItem is executed by an external trigger, the values of the output terminals are updated based on the configured source.

The Input-Terminal values of the InputDataBlock are also stored with the input images, and can be loaded with RunFromDir when checked again.

Some Input Terminals of the InputDataBlock with predefined names can provide special input values. In particular, project-specific Viper.NET plugins can provide input data for image processing via such terminals.



In a CogToolBlock named JobInputDataBlock information about the Job configuration in Viper.NET is provided.


Viper.NET sets in this toolblock the values of output terminals with the following names:

  • LoadedType: Name of the currently loaded Types.

  • JobName: Name of the Job.

  • TgId: ID of ToolGroup Item

  • TgName: Name of the ToolGroup Item

  • JobName_TgName: Combination of Job name and ToolGroup-Item name in the form <Job name>\<ToolGroup-Item name>. Example: “DemoJob\DemoTG”.

  • Trigger: Type of trigger of the toolgroup execution. Possible values:

  • RunFromDir_FullPath: Specifies the absolute path of the input image when executed as part of RunFromDir.


In order to forward results of the ToolGroup as output to recipients such as a controller, a CogToolBlock named OutputDataBlock must be defined. Data from the Input-Terminal of the ToolBlock is linked to output targets by the configuration in the tab Data.



The location to save-input-images the toolgroup can be dynamically customized. The configuration is done by output terminals of the CogToolBlock named JobDataBlock.


The following output terminals are evaluated by Viper.NET:

  • ImageNamePrefix [String]: Prefix that defines the constant part of the file name.

  • ImageSubdirectory [String]: Name of a subdirectory to save to. The directory will be recreated if it does not exist.

  • OverrideSaveImageFlags [String]: Forces saving regardless of the flags set in the global-settings.

  • IgnoreScriptErrors [bool]: In Cognex VisionPro compile errors in scripts are ignored, the scripts are then simply not executed. Since this can lead to unwanted behavior, Viper.NET by default checks all tools with scripts for errors after execution, and raises a RunError if a script error is detected. With IgnoreScriptError=true this check can be disabled.

  • UpdateDisplay [bool]: Can be set to false to suppress updating the display.


In a CogToolGroup named CounterData, additional information is specified for counters.


In particular, CounterGroups can be used to control which counter groups are incremented. With PartInfo additional information can be stored into the database. The function is explained in Counters.


Custom saving of arbitrary images can be realized in Viper.NET by a CogToolBlock whose name starts with SaveImagesEx. Image data from the flow can be saved, as well as image-displays from Views and SubDisplays including overlaid graphics. Configuration parameters can be dynamically changed by terminals.

To store images from the flow, Input terminals of type ICogImage are created. By default, the name of the terminal becomes part of the output filename.

To store images from Image-Displays, Input-Terminals of type System.Int32 are created, whose names start with FromSubdisplay. Viper.NET interprets the value of these terminals as the ID of a SubDisplay from the configuration. The SubDisplay, including the overlaid graphics, is saved to an image file, where the generated filename contains the name of the terminal by default.


The Gefasoft VisionPro Tools contain a tool template with an input image terminal and terminals for all supported configuration variables.


The following terminals can be used to control the behavior when saving:

  • Enabled (bool): Only if the value is True, images are saved.

  • Synchronous (bool): If the value is True, saving is synchronous within the process. In this case, errors during saving lead to a NIO status of the ToolBlock.

  • OverwriteImage (bool): If the value is True and potentially existing files at the destination will be overwritten.

  • ImageSubdirectory (String): Optional path of a subdirectory in which the images are to be stored. The path is interpreted relative to the set image output directory of the *job*.

  • UsePrefixAsImageName (bool): If True, the output filename exactly matches the ImageNamePrefix. Otherwise, the name is generated dynamically according to the ImageNamePattern.

  • ImageNamePrefix (String): Part of the generated output filename. The generation of the file name is determined by the parameters UsePrefixAsImageName and ImageNamePattern.

  • OverrideSaveImageFlags (bool): If True, the Global conditions for saving images will be ignored and always saved if the local conditions are met.

  • OutputFormat (String): Defines the output file format in terms of the file name extension. Valid values are, regardless of capitalization: bmp, png, jpg, jpeg, tif, tiff, idb, cdb.

  • Compression (Integer): If png or jp(e)g is set as file format, the compression level can be adjusted: 0 means maximum compression (with highest quality loss for jp(e)g, 100 minimum compression.

  • TextToWriteInImage (String): If set, the given text will be drawn into the output image as an overlay.

  • TextToWriteInImageFontSize (Double): Font size of the TextToWriteInImage.

  • AppendTerminalNameToTxt (String): If TextToWriteInImage is not empty, the terminal name of the image is added to it.

  • SaveInputData/SaveResultData (bool): If the value is True, the input and result data are saved in addition to the images. The file names are derived from the file name of the first image of the SaveImagesEx block.

  • ImageNamePattern (string): Defines the filename of the output images using wildcards (as long as UsePrefixAsImageName is not active). At runtime, the filenames are generated by replacing the placeholders with appropriate values. The following placeholders are supported:

    • $(ImgName): Name of the imaging input terminal in the SaveImagesEx.

    • $(Job): The name of the job. If the job contains a ToolgroupArray, a compound name is generated: “<Job Name>.<Toolgroup-Item Name>”. An example: “JobTopside.01_CheckCracks”.

    • $(Timestamp): Timestamp of the creation time in the form: yyyyMMdd_HHmmssfff.

    • $(ResultInfo): Result status of the toolgroup at the end of execution as a string: “pass”, “warn” or “fail”.

    • $(Prefix) The value of the “ImageNamePrefix”.

  • SaveImagesPass, SaveImagesWarn and SaveImagesFail (bool): Depending on the result status of the toolgroup (IO,*Warning*,*NIO*), the images are only saved if the corresponding setting is True. At the same time, depending on OverrideSaveImageFlags, the behavior can also be influenced by global flags.


In the default configuration, saving images with SaveImagesEx is done asynchronously after the job has been completed. The execution time of the process is thus unaffected by the time required for the actual saving process (see also WorkerStoreImage).


When running the job as part of the RunFromDir, images will only be saved if this is set.


A CogToolBlock whose name starts with ValueBlock collects results for visualization and analysis, for example measured part sizes.


All input terminals with primitive system types, for example int, double or string, are captured as values. The values can be added to Trends or Views and SubDisplays for example.


ToolgroupItems can use a CogToolBlock named TrendResults to hold values in a Trend and control the collection of trend data. The block must be located immediately within the toolgroup in the toolblock hierarchy.


All output terminals of type double are recorded as trend results. The terminal name serves as the identification key of the trend entry. Special terminals control the behavior of trend data collection:

  • Enabled [bool]: (Dis)Enables the collection of trend values of an execution. For example, values can only be captured when the trigger mode “ePlc” is active.

  • PartInfo [string]: Optional information about the part. The text is displayed as ToolTip of the trend data points.


Values evaluated in a CogDataAnalysisTool are automatically available as trend entries and do not have to be entered separately in a TrendResults block.


Values can also be captured in trends using ValueBlock tool blocks. Unlike the TrendResults block, these can also be created in nested toolgroups or toolblocks and are recommended for this purpose. The TrendResults block should preferably only be used for configuring data collection.

Special VisionPro Tools


Measured values or results of image processing tools are usually available without evaluation at an output terminal. Within Viper.NET it is recommended to realize the result evaluations as IO, NIO or Warning with a CogDataAnalysisTool.

All entries from all CogDataAnalysisTools in a ToolGroup are included in the Analysis (limit value test).


To define a result, a new Channel must first be added and configured in the tool’s editor. In the ToolGroup editor, an input terminal for the value (CurrentValue) of the channel must then be added via the context menu to make it visible.


Changing the names of channels has an effect on the assignment to the terminals. Therefore, after a change, affected terminals of the CogDataAnalysisTool must be removed and added again.