Locator Tutorial: Setting up Locator to work with UR robots

From 3D scanning Knowledge base - Photoneo wiki
Revision as of 20:36, 9 February 2019 by Durovsky (talk | contribs)

Jump to: navigation, search

Users are strongly recommended to read Locator Tutorial: Introduction prior to installation of specific robot interface

1. Prerequisites

Prior to setup, please ensure that your UR controller meets the following criteria:

- CB3.1 or E-series Controller

- System version 3.2 and higher

Click Menu -> About to verify your controller System Version (see figure below):


Locator Setting Up Guide About 2.png

2. UR Controller Setup

2.1 Set IP Address of Ethernet Port

The first step of the process is to configure the IP address of the Robot Controller. Using the Teach Pendant, browse to Menu -> System -> Network:

Amend the IP Address and Subnet Mask to match the network configuration of the Vision Controller running Locator and click Apply:


Setting UP Guide Locator URCap Network.png


3. Locator UR Cap Setup

The Locator UR Interface is distributed as an URCap and simple URScript program template. As the first step, URCap needs to be installed.

Extract the Locator URCap archive (.zip file) to the USB stick and plug it into the Teach Pendant.

Browse to Menu -> System -> URCaps:


Setting UP Guide Locator URCap Active.png


Select the PhotoneoLocator URCap file from USB and click Open:


Setting UP Guide Locator URCap Installation 1.png


Locator URCap should now appear in the list of active URCaps. As usual, Restart is needed in order to enable the proper functionality of newly installed URCap.


Setting UP Guide Locator URCap Installation 2.png


After the restart, Locator URCap should be ready for use:


Setting UP Guide Locator URCap Installation 3.png


As the last step before Calibration, copy the LocatorTemplate.urp program from USB Stick to the Robot Controller:


Setting UP Guide Locator URCap Load Program.png


The configuration of LocatorTemplate will be explained in detial in section 5.

4. Calibration

Robot Camera Calibration is a crucial step in Locator configuration. Accurate calibration guarantees that object positions will be calculated directly in Robot Base coordinates.

Photoneo Robot Camera Calibration for URCap is configured to search for the sphere object, which radius is known. Usually, Ping-Pong or Snooker ball is used for this purpose. Sphere object can be attached to the gripper using peg, suction cup two-finger gripper or another method. The pose of the ping pong ball is not important (doesn't need to be in axis) the only requirement is that is should be mounted firmly so it does not move during transitions between waypoints. It should also be visible from the scanner in each waypoint.

NOTE: Tool Point setting does not affect the calibration process, therefore, it is not necessary to clear tool pose configuration before starting the calibration.

4.1 Robot - Camera Calibration

Mount the Scanner firmly, ensure that the scene is properly captured from the final scanner position and open the Calibration tab on the Installation page:


Setting Up Guide Locator UR Calibration Step 0.png


As the first step, set the IP address of Vision Controller and press the Connect button to establish a connection to the Calibration Tool:


Setting Up Guide Locator UR Calibration Step 1 up.png


As the second step of the calibration insert and set Sphere radius (Standard Ping Pong Ball = 20mm, Snooker Ball = 26.25mm):


Setting Up Guide Locator UR Calibration Step 2.png


The third step requires Scanner ID to be set. Both old & new notations are supported. (Old notation example: 1703001 / New notation example: 2018-03-001-LC3)

NOTE: If you have inserted a wrong value and need to restart the calibration process, just switch from Instalation Tab to Program Tab and back. Calibration will be restarted.


Setting Up Guide Locator UR Calibration Step 3.png


You are now ready to start adding calibration points. Hold the Enable button and manually move the robot to the first calibration pose. The recommended procedure is to cover all four corners of the scanning volume/bin + two positions in the center of the scanning volume. Change the orientation of the tool in all axes to achieve a wider range of input values.

Press the Capture button to trigger the scan and store the current calibration position. Repeat the same procedure for all 6 calibration points:

NOTE: If calibration ball has not been detected properly or the calibration pose is too close to existing one a popup window notifies the user that calibration point needs to be changed and recaptured!


Setting Up Guide Locator UR Calibration Step 4.png


If all 6 points have been added successfully it is a time to calculate calibration matrix and store result to the scanner. Press Calibrate to finalize the calibration procedure:

NOTE: If calibration error is too high it is necessary to repaet the whole calibration with different calibration waypoints!


Setting Up Guide Locator UR Calibration Step 5.png


4.2 Tool Configuration

After finalizing Robot Camera calibration it is necessary to configure the Tool Point.

Browse to Menu -> Setup -> Frames and select the tool frame you want to use within your program.


Setting UP Guide Locator URCap Z Tool 1.png


Set the X,Y,Z coordinates which denote the position of the tool point of the current gripper with respect to the flange:


Setting UP Guide Locator URCap Z Tool 2.png


It is important to perform this step before reteaching of application poses!

5. Runtime

5.1 Reteach Application poses

Once the Robot-Camera and Tool calibration processes have been completed, application poses needs to be retaught. Prior to starting this process, please ensure that you have selected the correct Tool Frame.

Go through the LocatorTemplate program and reteach Home Start, End + Placing positions using the standard procedure as shown in the figure below:


Setting UP Guide URCap Reteach Home Position.png


5.2 Remaining Locator Configuration

Locator configuration on UR side comprises few more options. First of them is related to the gripper logic.

Replace the following comments in the UR Script code by specific commands for attaching the object to the gripper:


Setting UP Guide URCap Gripper Attach Logic.png


Repeat the same step with the gripper Detach command:


Setting UP Guide URCap Gripper Dettach Logic.png


Locator for URCap always works in Multiple Result Mode - the user specifies how many results should be retrieved from a single scan. This is implemented through the parameter in locator_trigger function call e.g. locator_trigger(20). This configuration is closely coupled to the Stop Criteria settings of Photoneo Localization Configuration File (PLCF) on the Locator side.

EXAMPLE: The only enabled Stop Criteria is - Total time is configured to 20000ms. Let's assume that Localization finds 32 objects during this period. Locator Best Result Selector is set to Max X criteria. Locator receives 32 results from localization, sorts them according to the X coordinate and transmits 20 top results to the URCap. URCap Receives 20 results and starts picking objects one by one. In case if only 15 objects are found by the Localization, Locator transmits all 15 sorted results to the URCap.

During locator_trigger execution, all results are being received to the internal Locator URCap buffer. Following function call - locator_get_coordinates retrieves values from this buffer and attempts to execute picks one by one.


Setting UP Guide URCap Num Of Results.png


For picking, it is recommended to approach the object in Z-axis linearly. The parameter in locator_get_coordinates(z_axis_offset) sets the approaching height in Z-axis (Unit = millimeters).

During locator_get_coordinates execution, the next Cartesian Coordinates is retrieved from the buffer and stored to the target_pose variable. The target_pose_up is calculated as a simple sum of target_pose and Z-axis offset. If both poses are kinematically reachable, the actual pick begins, if not, the next Cartesian Result is processed.


Setting UP Guide URCap Get Coordinates.png


5.3 Run Locator

You are now ready to run the program. Select 10% speed; this option is recommended for safety reasons.

Ensure that you are ready to stop the motion execution immediately if something goes wrong.


Setting Up Locator Runtime.png


If everything is working correctly, you should that the scan has been triggered, the result from Locator has been transmitted to the Robot Controller and the robot is approaching the very first object.

The VisualizeLocatorTab line of code shows the Texture from the scanner and picking statistics such as the number of scanns totally triggered, the total number of picks, and average cycle time.

6. UR Script

The Locator URCap utilizes Python Daemon, which runs in the background and handles communication with Locator. This approach enables simplification of Locator API to only three URScript functions.

6.1 Main

The following figure contains the LocatorTemplate.upr program. As can be seen, 20 results are requested and approaching height to each of the objects is set to 100mm.

If at least one object pose is received, the program will attempt to execute motion towards the returned target/s. Attached object/s will be then placed in predefined positions.


Setting UP Guide Locator URCap Program.png


Users can adapt this URScript code to meet their application requirements, change the speed, blend or logic if needed.

6.2 UR Script API

Locator URScript API comprises of three functions which provide a high-level interface to Locator:

  • - locator_trigger(num_of_results) - this function triggers the scan and start localization. Input Argument: Number of Requested Results. Return Value: Num of Localized Objects
  • - locator_get_coordinates(z_axis_offset) - this function fetches next coordinate from the result buffer and validate reachability for both approaching and grasping pose. Input Argument: Z-Axis Approaching Offset, Return Value: Reachable - True/False
  • - locator_update_statistics() - this function updates picking statistics at the visualization pane after each pick. Input Argument: None, Return Value: None

6.3 Communication Protocol

The following illustrations explain the Locator - UR communication protocol. As has already been mentioned, Locator URCap always works in Multiple Result Mode.

The current implementation prevents the user from programming communication routines, communication routines are completely handled by the Python Daemon.


Setting Up Locator Guide Communication.png