Scripting

Before We Officially Get Started…

• Introductions
– Name?
– Company?
– Location?
– Position there / responsibilities?
– Previous vision experience?
– Your VisionPro application?
• Orientation
• Course Agenda

1
Scripting Agenda
• What is VisionPro Scripting
– What can Scripting be used for
– Using the Script Editor
– Scripting Access Points
• ToolGroup Scripting Examples:
– Example 1 – Convert Radians to Degrees
• Creating and using Script Terminal
• Overriding GroupRun
• Saving a “custom tool” template for re-use
– Example 2 – Save only Failed Images
• Saving images to hard drive dynamically
– Example 3 – Center of Bounding Box
• Exposing API not available w/ standard terminals
– Example 4 – Custom Behavior
• Easily control the RunStatus(Accept/Reject) of a CogJob
• Add inputs that are accesible in an AppWizard App
– Example 5 – Custom Code & Graphics
• Demo of Multiple Targets sample job
• Finer Points on Scripting

What is VisionPro Scripting

• VisionPro has specific points in its execution where it will call
script functions.
• Your script function runs in addition to, or in place of, regular
VisionPro code.

2
Reasons for Scripting
• If QuickBuild and AppWizard do not quite accomplish what you
need
• Extend the abilities of QuickBuild and AppWizard
• No DevStudio (Quick, “Easy”)

Scripting Uses
• Create a “Custom Tool” to perform an action that there is no VisionPro tool for.
– Add two numbers
– Perform mathematical, logical, or string manipulation
• Expose parts of the API that are not available via Tool Terminals.
– CogBlobResult.BoundingBox()
• Easily allow an AppWizard application to have additional control over your inspection routine
– Add a flag to retrain a PMAlignPatten
– Switch between different modes in the same job
• Stitch acquired images together
• Conditionally run tools or change the execution order
• Situations in which you need to do the same thing many times (avoid Jobs with hundreds of
tools and terminals)
– MultiTarget Sample
• Evaluate a complicated RunStatus expression of an inspection much easier than using the
ResultsAnalysisTool
• Save particular images to file
• Write to a log File
• Change or add the Graphics related to a particular inspection
• Creative uses to solve problems the designers of VisionPro never anticipated

3
Two Kinds of Scripting
• CogJob Scripting
– CogJob Scripting access to CogJob properties (the AcqFifo for
instance)
– CogJob scripts will tend to deal with setup and execution of the image
acquisition process.
• CogToolGroup Scripting
– Remember that each Job contains a CogToolGroup, ToolGroup
Scripting allows access to properties of a ToolGroup and to override
some of the methods that we have already talked about in a
ToolGroup
– Scripts here will deal mainly with Tools, and how they are run

Job Scripting Access Points

UserScript : CogJobBaseScript

Initialize :
Called when the job script is
initialized

AcqFifoConstruction :
Called after constructing the AcqFifo,
can be used to modify the initial
acquisition properties

PreAcquisition :
Called before an acquisition is started
only when using Manual and Semi-
Automatic trigger models

PostAcquisition :
Called when acquisition has completed
(applies to all trigger models)

4
 Opening Script Editor for Job

• 1) Click on “Configure Job Properties”

• 2) Click on “Edit Job Script” to bring up the script editor

ToolBlock Scripting(introduced in VisionPro 6.1)

• Enhanced ToolGroup
– Script free terminals
• Simply drag & drop
– Increase application structure visibility
• Too many connections in complex applications
– Improve connectivity of ToolGroups
• After copy & paste no need to reconnect terminals that connect into ToolGroup
• Simple programmatic interface
• Added some goodies to simplify development
– Simple Script
• Does most of the .NET infrastructure work for you
• Fast access to inputs/outputs and vision tools
– Input /Output Terminal value tab
• See at a glance what‘s going on in ToolBlock

10

5
Simple Scripting Using ToolBlocks
• Choosing the simple
scripting option
automates most of the
setup work involved
with scripting
• Inputs and outputs are
created in the GUI
• This allows you to
focus on the
application code
instead of the setup
code

11

Setting Up Inputs and Outputs

• The Inputs/Outputs tab
allows you to create:
– System variables
• Integers
• Doubles
• Booleans
– VisionPro variables
• CogImage8Grey
• CogToolResultConst
ants

12

6
 ToolBlock Benefits
• Easy to use Inputs and Outputs
– Drag & Drop Terminals
– Assign any type, enter values manually
– No need to connect to Terminal

13

ToolBlock benefits
• Increase understanding of application
– Break application into functional blocks
– Expose inside of blocks through Terminals
Find and count application Organized with ToolGroup Organized with
Block

14

7
Scripting in ToolBlocks
• Simple Script for both C# and VB.NET
– Minimize coding effort
• Upon script creation all references of Vision Tools used in ToolBlock
are loaded and included
• Auto generated code simplfies access to ToolBlock terminals and VisionTools
• No overloaded functions such as Initialize(), ModifyLastRunRecord()
• No ToolLoop Run function

– Simplify coding effort

• Accessing Terminals in VB#
– a = Me.Inputs.TerminalName
– Me.Outputs.TerminalName = a + 5.8

• Accessing Vision Tool CogBlobTool1

– Count = Me.Tools.CogBlobTool1. Results.Count

15

Scripting in ToolBlocks
• Simple Script example
for a ToolBlock
containing a Blob Tool

• New buttons
– Remove script in case
script is no longer
needed
– Refresh from Tool to
recreate auto
generated code in
case new Vision
Tools or terminals
have been added
16

8
Scripting in ToolBlock
• Advanced Script
– Comparable to ToolGroup Script
• Automatically includes VisionTool References and includes them

– Accessing Terminals in VB#

• a = Me.ToolBlock.Inputs.Item(„TerminalName")
• Me.ToolBlock.Outputs.Item(„TerminalName“) = a + 5.8

– Accessing Vision Tool CogBlobTool1

• BlobResult = Me.ToolBlock.Tools.Item(„CogBlobTool1“)
• Count = BlobResult.Results.Count

17

Example 1 – Convert Radians to Degrees

• We’re going to add a simple arithmetic “tool” to our CogJob
from the first Section
• The tool will
– Take a Double as an input (our calculated distance)
– Multiplies by 180
– Divides by pi (3.1415)
– Outputs the result

18

9
Example 1 – Convert to Degrees – Step 1
• Declare input and
output terminals in the
Inputs/Outputs tab
• Input
– Radians as
System.Double
• Output
– Degrees as
System.Double

19

Example 1 – Convert to Degrees– Step 2

Add this.

20

10
 Example 1 – Convert to Degrees – Step 3

• Connect the
Terminals and add
the Output to Posted
Items (remember that
this is now available
in the App Wizard)

21

Creating a Template File for our Tool

• We can save a template file of the script tool we just created so that it is
available to be re-used from the QuickBuild Toolbox

Note: You can remove old templates by deleting the

appropriate file from the VisionPro\bin\Templates\Tools
directory.
22

11
Example 2 –Saving only Failed Images

Ability to save image as .BMP to hard drive

- based on the DataAnalysis tool

23

Adding/Removing References

1
2

24

12
Example 2 – Save Failed Images – Step 2

Add this.

25

Example 2 – Save Failed Images – Step 3

• Connect the
Terminals and note
the images that are
saved when results
are not “Accept”

26

13
ToolGroup Advanced Scripting Access Points

UserScript : CogToolGroupBaseScript

GroupRun :
Used to control the order of
execution of the tools in the tool
group

ModifyCurrentRunRecord :
Used to modify the current run
record after the tool has completed

ModifyLastRunRecord :
Used to modify the last run record
after the tool has completed

Initialize :
Run When the Script is created, used
for script setup, adding terminals, and
subscribing to Events

27

Opening Script Editor for Tool Group

28

14
ToolGroup Scripting Template Access Points
• When you open the ToolGroup script editor you are given an
empty template to get you started

29

GroupRun
'The GroupRun function is called when the tool group is run. The default
'implementation provided here is equivalent to the normal behavior of the
'tool group. Modifying this function will allow you to change the behavior
'when the tool group is run.
Overrides Function GroupRun(ByRef message As String, _
ByRef result As CogToolResultConstants) _
As Boolean

'Run each tool in the tool group using the RunTool function
For toolIdx As Int32 = 0 To ToolGroup.Tools.Count – 1
ToolGroup.RunTool(ToolGroup.Tools(toolIdx), message, result)
Next

'Returning False indicates we ran the tools in script, and they should not be
'run by VisionPro
Return False
End Function

• Note the default behavior

• Probably the most important script point.
Gives you complete control over the running of the
ToolGroup.
• This is where you would customize the run order,
implement a “custom tool”, or change the RunStatus
30

15
Records Overrides
#Region "When the Current Run Record is Created"
Overrides Sub ModifyCurrentRunRecord(ByVal currentRecord As
Cognex.VisionPro.ICogRecord)

End Sub
#End Region

#Region "When the Last Run Record is Created"

'Allows you to add or modify the contents of the last run record when it is
'created. For example, you might add custom graphics to the run record here.
Overrides Sub ModifyLastRunRecord(ByVal lastRecord As Cognex.VisionPro.ICogRecord)

End Sub
#End Region

• Allows you to customize

what shows up in the records
window of QuickBuild and in
an AppWizard app

31

Initialize
#Region "When the Script is Initialized"
'Perform any initialization required by your script here
Overrides Sub Initialize(ByVal host As CogToolGroup)
'DO NOT REMOVE - Call the base class implementation first - DO NOT REMOVE
MyBase.Initialize(host)
End Sub
#End Region

• Setting up variables and other things used by your script

– Script Terminals
– Event Handlers

32

16
Example 3 –Center of Bounding Box
• This example was an actual customer problem that was solved with scripting
We have been measuring the distance between
Blobs using the CenterOfMass of the Blobs
This customer had a need to measure the distances
between the center of the pixel aligned bounding box
(the rectangle shown below)

33

Example 3 –Center of Bounding Box

• The problem is that the property
representing the Image Aligned
Bounding Box is not available in the
QuickBuild property browser.

• This is because the method that

returns the Image Aligned Bounding
Box takes and argument which you
cannot pass using the interface.
?
• It’s not there so stop looking for it and
get your scripting on.

34

17
Example 3 –Center of Bounding Box – Step 1
• Remember to initialize input terminals for the two blob results
and the X and Y for each of the calculated positions for the
bounding boxes (four values)

35

Example 3 –Center of Bounding Box – Step 2

• Even after adding the reference to the DLL, you must import
the Cognex.VisionPro.Blob namespace before you can use
CogBlobResult variable type

36

18
Example 3 –Center of Bounding Box – Step 3

37

Example 3 –Center of Bounding Box – Step 4

• To test your new script, create a Blob tool that finds the C and the 1 in the
demo plate image and a distance tool that measure the distance between
the bounding box centers
• Use the Blob graphics to see that there is a difference between the center of
mass and the center of the bounding box

38

19
Example 4 – Custom Behavior
• Replace Data Analysis with a script because it’s easier and we can expose the terminals to
the App Wizard
• Add a new CogToolGroup and in its ToolGroup script add three terminals for the Distance,
a RangeHigh and a RangeLow.
• The script should return a reject result if the distance does not fall within the range we
specify

Overrides Function GroupRun(ByRef message As String, _

ByRef result As CogToolResultConstants) _
As Boolean

MyBase.toolGroup.GetScriptTerminalData("Distance", distance)
MyBase.toolGroup.GetScriptTerminalData("RangeHigh", rangehigh)
MyBase.toolGroup.GetScriptTerminalData("RangeLow", rangelow)

If Distance > RangeHigh Or Distance < RangeLow Then

message = ("The Input Distance (" & Distance.ToString() & _
") fell outside of the valid range")
result = Cognex.VisionPro.CogToolResultConstants.Reject
End If

Return False
End Function

39

Example 4 – Custom Behavior

• Notice the message in the status bar of the CogJobEdit
Window when the Distance falls outside the valid range.

40

20
Example 4 – Custom Behavior
• Run the App Wizard and add an Input for RangeHigh and RangeLow
• The values for the Terminals are stored in the ScriptData property of the CogToolGroup
• The Path For Range High is:
Tools.Item["ResultsAnalysis_Script"].(Cognex.VisionPro.ToolGroup.CogToolGroup).ScriptData
.Item["RangeHigh"].(System.Double)

41

Example 4 – Custom Behavior

Notice we can easily set the range values in the App Wizard App

42

21
Example 5 – Custom Code & Graphics
• This section will reconstruct the MultiTarget app that some of
you may have seen previously.
• This will teach you about:
– Customizing the execution Order of the Tools.
– Working with the LastRunRecord script point to customize the
Records/Graphics.
• Start a new job, I’ve saved a tool template called Synthetic
Image to your ToolBox, add one to your job and run it a few
times.

43

Example 5 Cont.

• We won’t be using the Image Source in

this section so click “no” and we’ll
change our Job so that it ignores the
fact that the AcqFifo has not been set
up.
• From the top Menu Bar Select
Configure->Job Properties then un-
check Acquire Images from Image
Source in the Dialog shown on the
right.

44

22
Example 5 – Custom Code & Graphics
• You should see something like this

45

Example 5 – Custom Code & Graphics

• The idea is that good parts have a black bar across the middle of the square
• We’ll determine if a part is good by using a CobBlobTool to find the squares, and
CogCaliperTool to find if the bar is there

46

23
Example 5 – Custom Code & Graphics
• Add a CogBlobTool and a CogCaliperTool

47

Example 5 – Custom Code & Graphics

Set up your Blob Tool to Find all the rectangles

48

24
Example 5 – Custom Code & Graphics
• Set Up a Caliper Tool to find the Edges of the black region in the center of a
rectangle.
• Make sure your scan and search Directions are correct and that you get a result

49

Example 5 – Custom Code & Graphics

• Add a Caliper Tool for each Blob Result?
• How many Blob Results are there going to be?
• Never mind, let’s add one CaliperTool and use scripting to run
it at each location a BlobResult is found.

50

25
 Example 5 – Custom Code & Graphics
Group Run Override
Overrides Function GroupRun(ByRef message As String, _
ByRef result As CogToolResultConstants) _
As Boolean

'Run the Synthetic Image tool to generate an image for inspection.

toolGroup.RunTool(ToolGroup.Tools("Synthetic Image"), message, result)

'Get references to the blob and caliper tool from the ToolGroup
Dim blobTool As CogBlobTool = ToolGroup.Tools("Blob")
Dim caliperTool As CogCaliperTool = ToolGroup.Tools("Caliper")
Dim caliperRegion As CogRectangleAffine = caliperTool.Region

'Run the blob tool and get a reference to the results.

toolGroup.RunTool(blobTool, message, result)
Dim blobResults As CogBlobResultCollection = blobTool.Results.GetBlobs()

'Run the caliper tool once for each target found using the blob tool.
For Each blob As CogBlobResult In blobResults
'Use the blob center of mass to set the region where we run caliper for each target.
caliperRegion.CenterX = blob.CenterOfMassX
caliperRegion.CenterY = blob.CenterOfMassY
toolGroup.RunTool(caliperTool, message, result)
Next
End Function

51

Example 5 – Custom Code & Graphics

• Set the RunStatus to Reject if we find a Bad Widget

= New Code
Dim BadObjectFound As Boolean = False

'Run the caliper tool once for each target found using the blob tool.
For Each blob As CogBlobResult In blobResults
'Use the blob center of mass to set the region where we run caliper for each target.
caliperRegion.CenterX = blob.CenterOfMassX
caliperRegion.CenterY = blob.CenterOfMassY
toolGroup.RunTool(caliperTool, message, result)

If caliperTool.Results.Count = 0 Then
BadObjectFound = True
End If

Next

'Set the result of our inspection to Reject if one or more of the objects were bad
If BadObjectFound Then
result = CogToolResultConstants.Reject
End If

'Returning False indicates we ran the tools in script, and they should not be
'run by VisionPro
Return False

52

26
 Example 5 – Custom Code & Graphics
• Define a labels collection to hold some Graphics

53

Example 5 – Custom Code & Graphics

• Clear the labels before the loop to run the CogCaliperTool.
• Fill the collection with labels inside the loop.

Dim badObjectFound As Boolean = False

'Reset any labels from previous runs

labels = New ArrayList

'Run the caliper tool once for each target found using the blob tool.
For Each blob As CogBlobResult In blobResults
'Use the blob center of mass to set the region where we run caliper for each target.
caliperRegion.CenterX = blob.CenterOfMassX
caliperRegion.CenterY = blob.CenterOfMassY
toolGroup.RunTool(caliperTool, message, result)

'If the caliper got a result, this inspection passes. We then create an appropriate graphic label
Dim myLabel As CogGraphicLabel = New CogGraphicLabel
myLabel.Alignment = CogGraphicLabelAlignmentConstants.BaselineCenter
If caliperTool.Results.Count > 0 Then
myLabel.SetXYText(blob.CenterOfMassX, blob.CenterOfMassY, "Good")
myLabel.Color = CogColorConstants.Green
Else
myLabel.SetXYText(blob.CenterOfMassX, blob.CenterOfMassY, "Bad")
myLabel.Color = CogColorConstants.Red
BadObjectFound = True
End If
labels.Add(myLabel)

Next

54

27
Example 5 – Custom Code & Graphics
• Use the ModifyLastRunRecord override to add the labels we
created to the LastRun record
'Add the labels in our array list as part of the inspection record for the synthetic image.
Overrides Sub ModifyLastRunRecord(ByVal lastRecord As Cognex.VisionPro.ICogRecord)
For Each label As CogGraphicLabel In labels
toolGroup.AddGraphicToRunRecord(label, lastRecord, "Synthetic Image.OutputImage", "script")
Next
End Sub

• Also it annoys me that a record is still being created for the

Image Source… Let’s remove it

lastRecord.SubRecords.Remove("CogInputImageTool1.OutputImage")

55

Working With Scripts

• Scripts are automatically saved when you save your
QuickBuild job or application.
• When loading a .VPP file containing script, it is automatically
recompiled and initialized.
• You do not have to press the compile button in the script
editor. It is only a convenience to allow you to see any compile
errors in your script without closing the editor.

56

28
Invalid Scripts
• A script is considered invalid if
– There is an error compiling the script
– An exception is thrown from the initialize routine
• Invalid scripts will not be used. VisionPro will behave as if you
had not written the script.
• If a tool group script is invalid, you will not lose the terminals
defined in the script.
• You can save a job or application with invalid scripts, and
reload it later to continue development.

57

Scripting Guidelines
• Your script effectively becomes QuickBuild code. Any errors in your script
can cause QuickBuild to become unstable.
• Save frequently. QuickBuild is your development environment for scripting.
You will lose your unsaved work when (not if) a bug in your script causes
QuickBuild to become unstable.
• Like any program environment, many problems will result in unexpected
behavior instead of an error message. For example, there is nothing to stop
you from writing and running an infinite loop.

58

29
Summary
• ToolGroup and ToolBlock scripting provide additional
functionality within QuickBuild including:
– Custom tool creation
– Drawing custom graphics
– Creating custom application behavior

59

30