Scripting

Scripting Agenda

• Discover the uses of scripting in QuickBuild

• Discuss the two different types of scripts

• Understand how to use scripting with ToolBlocks

• Create different scripts to accomplish various tasks not

available in the QuickBuild environment

Lab: Use ToolBlocks to create scripts

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

3
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”)

4
Scripting Uses
• Create a “Custom Tool” to perform an action not available
– Add two numbers
– Perform mathematical, logical, or string manipulation
• Expose parts of the API that are not available via Tool
Terminals.
– [Link]()
• 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
• Save particular images to file
• Change or add the Graphics related to a particular inspection

5
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

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

7
 Opening Script Editor for Job

1) Click on “Configure Job Properties”

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

8
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

9
Opening Script Editor for Tool Group

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

11
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 [Link] – 1
[Link]([Link](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

12
Records Overrides
#Region "When the Current Run Record is Created"
Overrides Sub ModifyCurrentRunRecord(ByVal currentRecord As
[Link])

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 [Link])

End Sub
#End Region

• Allows you to customize

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

13
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
[Link](host)
End Sub
#End Region

• Setting up variables and other things used by your script

– Script Terminals
– Event Handlers

14
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

15
Example of ToolGroup Scripting
• Imports System
• Imports [Link]
• Imports [Link]

Public Class UserScript

• Inherits CogToolGroupBaseScript
• Private radians as double
• Private degrees as double
• Overrides Function GroupRun(ByRef message As String, ByRef result As CogToolResultConstants) As Boolean
•
• [Link]("Radians", radians)
• degrees = (radians * 180) / 3.14159
• [Link]("Degrees", degrees)

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

• #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
• [Link](host)
• [Link](radians,"Radians", True)
• [Link](degrees, "Degrees", False)
• End Sub
• #End Region
• End Class

16
Using ToolBlocks
• ToolBlocks is the preferred way to create a custom script
• Terminals are defined in the tool
• Programming is simplified
• Choice of Simple or Advanced
– Simple creates an easy programming environment
– Advanced is closer to
the detailed access
points like the
ToolGroup

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

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

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

• Useful 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
20
Example 1a – Convert Radians to Degrees
• We’re going to do the same example again – this time with
ToolBlocks
• The tool will
– Take a Double as an input (our calculated distance)
– Multiplies by 180
– Divides by pi (3.1415)
– Outputs the result

21
Example 1a – Convert to Degrees – Step 1
• Declare input and
output terminals in the
Inputs/Outputs tab
• Input
– Radians as
[Link]
• Output
– Degrees as
[Link]

22
Example 1a – Convert to Degrees– Step 2

Add this.

23
Example 1a – 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)

24
 Creating a Template File for our Tool
• Save the ToolBlock to re-use in QuickBuild

Note: You can remove old templates by deleting the

appropriate file from the VisionPro\bin\Templates\Tools
directory.
25
Example 2 –Saving only Failed Images

Ability to save image as .BMP to hard drive

- based on the DataAnalysis tool 26
Example 2 – Save Failed Images – Step 1
• Declare input and output terminals in the Inputs/Outputs tab
• Input
– Image as [Link].CogImage8Grey
– RunStatus as [Link]
• Output
– None (the saved image is the output)

27
Example 2 – Save Failed Images – Step 2

Add these

28
Example 2 – Save Failed Images – Step 3

• Connect the Terminals and

note the images that are
saved when results are not
“Accept”
• Make sure that appropriate
terminals are available

29
Example 3 –Center of Bounding Box
• Actual customer issue solved by scripting

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

31
Example 3 –Center of Bounding Box – Step 1
• Create a new blob tool that will find only the C and the 1 from
the text in the image.

32
Example 3 – Center of Bounding Box – Step 2
• Create a ToolBlock script with:
– Two inputs of type
CogBlobResult

– Four outputs of type double

• Pass the two blob results into

the two CogBlobResult inputs
– Hint: You will have to expose
more outputs terminals from
the blob tool.

33
Example 3 – Center of Bounding Box – Step 3
• Add this.

34
Example 3 – Center of Bounding Box – Step 4
• Insert a
CogDistancePointPoint tool
and send the output x and y
coordinates of the two new
blob locations

35
Example 3 –Center of Bounding Box – Step 5
• Compare the default coordiantes from the original blob tool
(center of mass) to the new ones extracted by the script (center
of bounding box)

36
Example 4 – Custom Behavior – Step 1
• Use a script to check a user set tolerance.
• Control the message displayed to the user as well as the result displayed by the
application.

• Notice this documentation near the top of every script:

• By assigning values to variables “message” and “result” you can custom change the
behavior of a tool.

• Create a new CogCaliper tool to find an edge pair and measure the distance.

37
Example 4 – Custom Behavior
• Notice the message in the status bar of the CogJobEdit
Window when the Distance falls outside the valid range.

38
Example 4 – Custom Behavior – Step 2
• Create a ToolBlock script with:
– Three inputs of type double
• Width
• MinDistance
• MaxDistance

• Pass the width result value into

the Width input
– Hint: You will have to expose
more outputs terminals from
the caliper tool.

39
Example 4 – Custom Behavior – Step 3
• Run the App Wizard and add an Input for MinDistance and MaxDistance
• The Path For MinDistance is:
[Link]["CustomTolerance"].([Link]).[Link]["Min
Distance"].Value

40
Example 4 – Custom Behavior
Notice we can easily set the range values in the App Wizard App

41
Example 5 – Custom Code & Graphics
• This section will explain the MultiTarget app
• The application is part of the QuickBuild sample code
• This will teach you about:
– Customizing the execution Order of the Tools.
– Working with the LastRunRecord script point to customize the
Records/Graphics.

• This code uses both CogJob (for the synthetic acquisition) and
CogToolGroup (looping tools) scripting

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

43
Example 5 – Custom Code & Graphics
• 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

44
Example 5 – Custom Code & Graphics
• Note the one CogBlobTool and one CogCaliperTool created in
the ToolGroup

45
Example 5 – Custom Code & Graphics
The Blob Tool is set to find all the rectangles

46
Example 5 – Custom Code & Graphics
• The Caliper Tool finds the Edges of the black region in the
center of a rectangle.

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

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

[Link]([Link]("Synthetic Image"), message, result)

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

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

[Link](blobTool, message, result)
Dim blobResults As CogBlobResultCollection = [Link]()

'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.
[Link] = [Link]
[Link] = [Link]
[Link](caliperTool, message, result)
Next
End Function

49
 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.
[Link] = [Link]
[Link] = [Link]
[Link](caliperTool, message, result)

If [Link] = 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 = [Link]
End If

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

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

51
 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.
[Link] = [Link]
[Link] = [Link]
[Link](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
[Link] = [Link]
If [Link] > 0 Then
[Link]([Link], [Link], "Good")
[Link] = [Link]
Else
[Link]([Link], [Link], "Bad")
[Link] = [Link]
BadObjectFound = True
End If
[Link](myLabel)

Next

52
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 [Link])
For Each label As CogGraphicLabel In labels
[Link](label, lastRecord, "Synthetic [Link]", "script")
Next
End Sub

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

Image Source… Let’s remove it

[Link]("[Link]")

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

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

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

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

57