Open topic with navigation

Vision_Object ToolProperty Property

Sets or gets a property value of a PreciseVision tool or a general "system" property for the vision server connected to a vision object.

vision_object.ToolProperty (property_name_string) = <property_value_string>
-or-
…vision_object.ToolProperty (property_name_string)

Prerequisites

None

Parameters

property_name_string

A required String expression that contains the name of the tool property to get or set.  This String is normally in the form:   tool_name.property_name, where tool_name is the name of a tool defined in PreciseVision, and property_name is the name of a property within that tool.

Remarks

This property permits a GPL program to dynamically change the properties of a tool defined within PreciseVision. This capability allows a GPL program to use the results of a previous vision process to adjust or refine the tools used by a future vision process.

The vision tools available depend on what has been defined in your particular vision application. The properties associated with each tool, and the possible property values are described fully in the PreciseVision documentation.

Each time a ToolProperty procedure is invoked, messages are exchanged between the Precise Controller and the PreciseVision system connected to the vision object. If an Ethernet network connection does not exist when this property is referenced, a connection is automatically established.  If a connection cannot be setup or the communication link fails for any reason, this method will throw an exception.

As a means for transmitting system information to and from Precise Vision, Tool Property recognizes "System" as a special tool name.  The information that can be exchanged using this special name is defined in Table 19-95.

Table 19-95: System.<property>
System.<property> Operation Description

Clear Calibration

Sets the calibration data for the specified camera (1-n) to the identity (cleared) value so that returned position values are in pixels instead of mm.  Should be executed before loading new calibration data.

DisplayMode

Defines the contents of the PreciseVision main window in the PC screen.  It accepts a single parameter, mode, that is interpreted as follows:

   0 - Resets the display mode to the standard default PV display.  All standard windows, toolbars, menus, etc. are visible and available for use.
   1 - Displays only the camera window and the current Tool's window.  The PV form border, title, and status bars are hidden.
   2 - Displays only the camera window. The PV form border, title, status bars and all dockable controls are hidden.
   3 - Minimizes the PV main window.

Info

Returns "{PV Version},{CameraAcquireType},{Camera Status1, …,Camera Status6}.  This indicates the version of PV that is being executed together with indications of which cameras have been properly connected to the system.

ImportProject

Loads in the PreciseVision project contained in the file specified by <property_value_string> and merges its contents with the currently loaded project. If the new project contains any processes or tools whose names conflict with items that are already loaded, "_r" is appended to the name of the new item. Also, any camera calibration information that is contained in the new project is ignored.

LastProcessTime

Returns the total execution time for the last vision process that was run, in seconds. This is the same information that is displayed in the Application Status Bar at the bottom of the PreciseVision window.

LayOut

Selects one of the predefined panel layouts to be displayed within the main PV window.  Requires a single parameter, layout, whose value is interpreted as follows:

   1 - Edit mode
   2 - Runtime mode
   3 - Calibration mode

LoadCal1

Dynamically loads a specified calibration file into PreciseVision and assigns it to camera #1. To load camera #n, specify "LoadCaln".  If the calibration file cannot be located, a -4022 error code will be returned.

LoadImage

Loads an image from the file specified by <property_value_string> into the camera display buffer.

LoadProject

Deletes the currently loaded PreciseVision project and loads in the project contained in the file specified by <property_value_string>.  If the currently loaded project has been modified, a -4023 error code will be returned and the load will not be attempted.  To ignore the any project modifications, please see the System.ProjectModified property.

Lock

Performs the same function as the "Lock/Unlock Application" button in the PreciseVision Main Menu bar.  If set to the string value "true", the user interface prohibits any changes from being made.  If set to "false", changes are again permitted.

MMToPixelTrans1

(Superceded by new CamCal properties)  Read the values of the calibration matrices for camera #1.  The elements of each 3x3 transformation are return as 9 numeric values delimited by commas (",") in a String.  The values are returned in the following order:  t11, t12, t13, t21, t22, t23, t31, t32, t33. To access the data for camera #n, specify ...Transn.

PixelToMMTrans1

Position

Positions and sizes the main PV window relative to the PC's screen.  This property requires four parameters whose values are delimited by ",":

   <xpos> - X position relative to the top-left of the screen
   <ypos> - Y position relative to the top-left of the screen
   <width> - Width of the main PV window (optional)
   <height> - Height of the main PV window (optional)

All units are in pixels.

ProjectModified

Returns or sets a True/False flag that indicates if the currently loaded vision project has been modified.  If the current project has been modified and you wish to load in a new project without saving the new changes, you can set this property to False.  If this flag is True and you attempt to load a new project, a -4023 error code will be returned.

ProjectName

Returns the name of the currently loaded vision project or its file path including the project name or its user settable version number.

ProjectPath

ProjectVersion

RefreshGraphics

Equivalent to pressing the "Refresh Camera Display Window Graphics" button in PreciseVision.  It redraws any graphics generated by vision tools in the Camera Display window.

SaveImage{n}

Stores the image contained in the specified camera buffer into the file specified by <property_value_string>.

SaveProject

Stores the currently loaded PreciseVision project into the file specified by <property_value_string>.

TopMost

Specifies whether the main PV window is on top of other windows on the PC's screen.  It requires a single parameter, mode, which is defined as follows:

   0 - Normal (resets topmost property)
   1 - Keeps window on top

This property permits PV to stay on top of other applications while the user clicks or drags other windows on the screen.

Zoom

Sets the "zoom" scale factor for the camera display window.  It requires a single parameter, scale_factor, that ranges from 0 to 5 in steps of 0.1.  A value of 0 will automatically set the zoom so that the entire frame buffer will be displayed within the camera display window.

 

In situations where a GPL program wishes to trigger the execution of a camera calibration procedure, ToolProperty recognizes "Camcal" as a special tool name.  For a "Camera only" area calibration, the information that can be exchanged using the Camcal tool name is defined in Table 19-96.

Table 19-96: Camcal.<property
Camcal.<property> Operation Description>

Camera

Sets the number of the camera to be used, "1" to "n".

CalType

Indicates the type of camera calibration to be performed.  This must be set to "1" for the simple stationary camera area calibration.

CalErrorNum

Returns an indication of whether or not the calibration process executed without an error.  CalErrorNum will be 0 if the calibration was successful.

CalErrorString

CalFileName

Saves the calibration results into the specified disk file.

CalSave

Execute

Initiates the calibration procedure.

SquareIsDark

When the standard calibration target is utilized that consists of a grid of squares, these parameters define the size and the pitch of the squares in mm.  The SquareDark indicates if the squares are dark (1) or white (0).  The SquareMinArea specifies the minimum acceptable area of each square in pixels.

SquareMinArea

SquarePitch

SquareSize

ResultMaxError

Returns statistical results of the calibration process.  This includes the maximum and RMS error that indicate how well the calibration target was matched, and information on the number of corners of the grid of squares that were located and utilized.

ResultNumCornerFound

ResultNumCornerUsed

ResultRMS

Threshold

Defines the binary threshold applied during the calibration process to initially locate the squares in the grid (0-255).

Width

Defines the size and center of the AOI to be processed during the calibration procedure.  These parameters are in units of pixels.

Height

X

Y

 

If the calibration scale factors for a camera are to be explicitly set, the following information in Table 19-97 can be exchanged using the Camcal tool name.

Table 19-97: Camcal.<property>
Camcal.<property> Operation Description

Camera

Sets the number of the camera to be used, "1" to "n".

CalType

Indicates the type of camera calibration to be performed.  This is must be set to "0" for explicitly setting the values of the calibration matrix.

CalErrorNum

Returns an indication of whether or not the calibration process executed without an error.  CalErrorNum will be 0 if the calibration was successful.

CalErrorString

CalFileName

Saves the calibration results into the specified disk file.

CalSave

dxPixPerMM

Explicitly specifies the pixel per MM scale factors in both the X and Y directions.

dyPixPerMM

Execute

Initiates the calibration procedure.

 

Independent of the camera calibration method, the following properties in Table 19-98 can be utilized to retrieve camera setup and calibration results information.

Table 19-98: Camcal.<property>
Camcal.<property> Operation Description

Camera

Sets the number of the camera to be accessed, "1" to "n".

CameraFrameSize

Returns the camera frame buffer size as "Width, Height" in pixels.  The actual camera image may be smaller than the frame buffer size.

PixelPerMM

Returns the average pixel per mm ratio for the specified camera.

PixelToMMTrans

Returns the calibration matrices that convert between camera pixels and units of millimeters.  These matrices are computed as a result of performing the camera calibration using the standard grid of squares.

The elements of each 3x3 transformation are return as 9 numeric values delimited by commas (",") in a String.  The values are returned in the following order:  t11, t12, t13, t21, t22, t23, t31, t32, t33.  These matrices are 3x3's to include perspective distortion correction.

For example, given a PixelToMMTrans value, a camera pixel coordinate (Px,Py) can be converted to millimeters (adjusted for perspective distortion) using the following equations:

     Cx = (t11*Px+t12*Py+t13)/pscale
     Cy = (t21*Px+t22*Py+t23)/pscale
   where
     pscale = (t31*Px+t32*Py+t33)

MMToPixelTrans

CameraToRobot

Returns the calibration matrices that convert between a camera's frame of reference and a robot's frame of reference.  These matrices are computed as a result of performing a "robot vision camera calibration".  After a camera pixel coordinate has been transformed to mm and corrected for perspective distortion using the PixelToMMTrans, the camera coordinate value can be multiplied times the CameraToRobot transformation to compute the equivalent position in the coordinate system of a robot.

The elements of each 4x4 homogeneous calibration transformation are return as 16 numeric values delimited by commas (",") in a String.  The values are returned in the following order:  t11, t12, t13, t14, t21, t22, t23, t24, t31, t32, t33, t34, t41, t42, t43, t44.

For example, given a CameraToRobot value, a camera X, Y position (Cx, Cy) in millimeters can be converted to a robot XYZ position using the following equations:

     Rx = t11*Cx+t12*Cy+t14
     Ry = t21*Cx+t22*Cy+t24
     Rz = t31*Cx+t32*Cy+t34

RobotToCamera

 

Examples

Dim prop As String
Dim vobject As New Vision
prop = vobject.ToolProperty("hist.angle")
vobject.ToolProperty("system.loadcal1") = "C:\cal1.dat"
prop = vobject.ToolProperty("system.mmtopixeltrans1")

See Also

Vision Classes