Difference between revisions of "Locator Tutorial: Setup and Runtime"

From 3D scanning Knowledge base - Photoneo wiki
Jump to: navigation, search
 
(10 intermediate revisions by the same user not shown)
Line 1: Line 1:
The main aim of this page is to provide a detail information of prerequisites, configuration and runtime of PhoXi Locator
+
The main aim of this page is to provide a detailed overview of the prerequisites, configuration and runtime of the PhoXi Locator
  
'''It is highly recommended that users read [http://wiki.photoneo.com/index.php/Locator_Tutorial:_Introduction Locator Tutorial: Introduction] prior to this page'''
+
'''Users are strongly recommended to read the [http://wiki.photoneo.com/index.php/Locator_Tutorial:_Introduction Locator Tutorial: Introduction] before starting this page!'''
 +
 
 +
== Locator - First Launch ==
 +
 
 +
'''Locator Core is configured to start immediately after the boot'''. The original image comes with the example 3D Scan of several T-fitting objects placed in the bin and the basic T-fitting PLCF file.
 +
 
 +
When you launch Vision Controller with Locator for the first time, the default configuration of the Locator uses these two data sources for initial run. 3D scan of T-fitting objects in the PhoXi Control screen which you can see immediately after the boot, is a sign that Locator Core has connected to the example PhoXi device and triggered the first scan successfully. In addition to establishing a connection with PhoXi device, Locator Core has also loaded PLCF file, initialized TCP/IP server, opened configured port and changed the current state to ''"Waiting for connection..."''.
 +
 
 +
If you click on the '''Locator Configurator desktop icon''', you will see the current Locator state as shown in the figure below:
 +
 
 +
 
 +
[[File: Locator initial run.png]]
 +
 
 +
 
 +
Press '''Stop Server''' to halt Locator runtime and adapt current configuration according to the application requirements.
 +
 
 +
'''Locator is configured to "remember" configuration from previous session''' so even after turning Vision Controller OFF and ON again, it will start with the last active configuration automatically.   
 +
 
 +
Following sections provide detailed information about PhoXi Scanner configuration, generation of PLCF and Locator setup.
  
 
== 1. PhoXi Control ==
 
== 1. PhoXi Control ==
  
'''Locator''' was designed to work with Photoneo PhoXi Scanners and '''requires PhoXi Control application''' to be running in parallel to the Locator application.  
+
'''Locator''' was designed to work with Photoneo PhoXi Scanners and '''requires the PhoXi Control application''' to be running in parallel to the Locator application.  
  
As a first step in the process, ensure that PhoXi Scanner is connected to the same subnet and appears in '''Network Discovery''' of PhoXi Control as shown in the figure below:
+
As a first step in the process, ensure that the PhoXi Scanner is connected to the same subnet and appears in the '''Network Discovery''' tab of PhoXi Control as is shown in the figure below:
  
  
Line 13: Line 31:
  
  
'''Connect to your PhoXi Scanner''' and fine tune scanning parameters in order to achieve best scanning performance. See our [http://wiki.photoneo.com/index.php/Main_Page knowledge base] to get more info on this topic.
+
'''Connect to your PhoXi Scanner''' and fine tune the scanning parameters in order to achieve the optimal scanning performance. See our [http://wiki.photoneo.com/index.php/Main_Page knowledge base] for more information on this topic.
  
  
Line 21: Line 39:
 
== 2. Localization Configurator ==
 
== 2. Localization Configurator ==
  
'''PLCF (Photoneo Localization Configuration File)''' is very important for overall Locator performance. PLCF holds information about object that is going to be localized within the scene, including CAD model, point of interest, stop criteria, localization settings and training data which speed up the localization process significantly. PLCF is generated by '''Photoneo Localization Configurator''', which is part of Locator image and can be launched by typing '''PhoLocConfig''' to the console or by searching for Photoneo Localization Configiurator directly in Ubuntu Applications menu.  
+
'''PLCF (Photoneo Localization Configuration File)''' is extremly important for the overall performance of Locator. PLCF holds information about the object that is going to be localized within the scene, including CAD model, point of interest, stop criteria, localization settings and training data. PLCF is generated by '''Photoneo Localization Configurator''', which is available of Vision Controller as a standalone tool and can be launched by typing '''PhoLocConfig''' into the console or by searching for Photoneo Localization Configiurator directly in the Ubuntu Applications menu.  
  
 
'''NOTE: HW license (USB Dongle) must be inserted into the system before launch!'''   
 
'''NOTE: HW license (USB Dongle) must be inserted into the system before launch!'''   
Line 29: Line 47:
  
  
Launch '''Photoneo Localization Configurator''' and upload model of your object in '''.ply''' or '''.stl''' format.  
+
Launch '''Photoneo Localization Configurator''' and upload the model of your object in '''.ply''' or '''.stl''' format.  
  
  
Line 35: Line 53:
  
  
'''Model Coordinates''' tab is intended for configuration of the point of the interest. Point of the interest is the point on the object, which coordinates will be returned by the Localization.  
+
The '''Model Coordinates''' tab is intended for the configuration of the point of the interest. The point of the interest is the point on the object, which coordinates will be returned by the Localization.  
  
 
If you plan to approach the object directly in the orientation returned by Localization, '''set the Z axis of interactive marker to point in the approaching direction of the robot''' (See the figure below).   
 
If you plan to approach the object directly in the orientation returned by Localization, '''set the Z axis of interactive marker to point in the approaching direction of the robot''' (See the figure below).   
Line 43: Line 61:
  
  
Always try to set point of the interest to be '''unique with respect to the object''', meaning that there is only one possible correct result of successful localization (this not always possible especially for rotation invariant objects). In case when several possible correct localization results might occur, you will need to apply additional logic on the robot controller to avoid situations when goal pose returned by Locator is '''not kinematicaly reachable by the robot'''.  
+
Always try to set the point of the interest to be '''unique with respect to the object''', meaning that there is only one possible correct result of successful localization (this not always possible, especially for rotation invariant objects). In cases in which several possible correct localization results might occur, you will need to apply additional logic to the robot controller to avoid situations when the goal pose returned by Locator is '''not kinematically reachable by the robot'''.  
  
Such a scenario is shown in the figure below. Even if you define point of the interest on the top surface of the object, you might get the result from the bottom side of the object pointing to the opposite direction. '''This result is correct from localization point of view, however it is not kinematicaly reachable by the robot.''' Therefore additional logic has to be applied directly on the robot controller to verify if Cartesian Goal pose is reachable by the robot.  
+
Such a scenario is shown in the figure below. Even if you define the point of the interest on the top surface of the object, you might obtain a result from the bottom side of the object pointing to the opposite direction. '''This result is correct from a localization point of view, however it is not kinematically reachable by the robot.''' In this situation additional logic would have to be applied directly on the robot controller to avoid this outcome.
  
  
Line 51: Line 69:
  
  
On the '''Set Parameters''' tab, ensure that you select reasonable '''Stop Criteria''' and trigger localization several times to verify that your current configuration provides reliable results. See figure below:
+
On the '''Set Parameters''' tab, ensure that you have selected suitable '''Stop Criteria''' and trigger localization several times to verify that your current configuration provides reliable results. See the figure below:
  
  
Line 57: Line 75:
  
  
In case when Localization does not work properly, adjustment of '''Advanced Settings''' might be neccesary. Contact [[http://www.photoneo.com/support/ Photoneo support]] if you need help with this step.
+
In cases in which Localization does not work properly, it might be necessary to make adjustments in the '''Advanced Settings''' dialog. Contact [[http://www.photoneo.com/support/ Photoneo support]] if you need help with this step.
  
  
Line 63: Line 81:
  
  
Click '''Generate''' to create PLCF file when Localization Configuration is finished. Use this file as an input for Locator in following steps.   
+
Click '''Generate''' to create a PLCF file once Localization Configuration has finished. Use this file as an input for Locator in the following steps.   
  
 
== 3. Locator Start [Ubuntu] ==
 
== 3. Locator Start [Ubuntu] ==
  
'''Locator Core works as a background service''' so it should be up and running from the boot. Type ''ps aux| grep pholocator'' to verify that '''pholocator''' service is running.  
+
'''Locator Core works as a background service''' so it should be up and running from the boot. Type ''ps aux | grep pholocator'' to verify that the '''pholocator''' service is running.  
  
  
[[File: Locator ps aux v1.png]]
+
[[File: Locator psaux.png]]
  
  
If you want to visualize Locator GUI, simply search for '''Locator Configurator icon ''' in the Applications menu in Ubuntu or type '''LocatorConfigurator''' command directly to the terminal.  
+
If you want to visualize the Locator GUI, simply search for the '''Locator Configurator icon ''' in the Applications menu in Ubuntu or type the '''LocatorConfigurator''' command directly into the terminal.  
  
  
Line 81: Line 99:
 
== 4. Locator Configuration ==
 
== 4. Locator Configuration ==
  
Figure below shows Locator GUI which is intended for configuration and validation of Locator functionality.  
+
The Locator GUI consists of a control panel on the left side and a 3D Visualizer on the right. As was mentioned above, the Locator GUI is primarily intended for the configuration and validation of Locator functionality.  
 
   
 
   
  
Line 87: Line 105:
  
  
Following is the list and description of Locator controls:
+
The Locator controls are as follows:
  
* - '''Scanner ID''' - List of all available PhoXi Scanners as shown by Network Discovery in PhoXi Control application. Use '''Refresh''' button to reload available devices.
+
* - '''Scanner ID''' - List of all available PhoXi Scanners as shown by Network Discovery in the PhoXi Control application. Use '''Refresh''' to reload available devices.
  
* - '''Port''' - Number of port which will be opened for socket communication. Locator always work in server mode.  
+
* - '''Port''' - Defines the port which will be opened for socket communication. Locator always works in server mode.  
  
* - '''PLCF''' - Photoneo Localization Configuration File generated from Localization Configurator in previous step. See [http://wiki.photoneo.com/index.php/3D_Localization_Configurator this link] for more info. Use '''Configure New'''  button to launch Photoneo Localization Configurator directly.
+
* - '''PLCF''' - Photoneo Localization Configuration File generated from Localization Configurator in the previous step. See [http://wiki.photoneo.com/index.php/3D_Localization_Configurator this link] for more information. Use the '''Configure New'''  button to launch the Photoneo Localization Configurator directly.
  
 
* - '''Best Result Selector''' - this option is used to filter results returned by Localization. Select from '''Min X''', '''Max X''', '''Min Y''', '''Max Y''', '''Min Z''', '''Max Z''', '''Max Overlap''' options.
 
* - '''Best Result Selector''' - this option is used to filter results returned by Localization. Select from '''Min X''', '''Max X''', '''Min Y''', '''Max Y''', '''Min Z''', '''Max Z''', '''Max Overlap''' options.
  
* - '''Store Log''' - If you want to store Locator logs to the text file, check this option and select/create a file using the '''Browse''' button.
+
* - '''Store Log''' - If you want to store Locator logs to the text file, check this option and select or create a file using the '''Browse''' button.
  
* - '''Load/Save Server Configuration''' - Locator stores last configuration by default, however these buttons can be used to save current configuration to specific file to be reloaded later.  
+
* - '''Load/Save Server Configuration''' - Locator stores the last configuration by default, however these buttons can be used to save the current configuration to a specific file to for future use.  
  
* - '''Start/Stop Server''' - This button is intended to start and stop Locator TCP/IP server.   
+
* - '''Start/Stop Server''' - This button is intended to start and stop the Locator TCP/IP server.   
  
 
== 5. Locator Runtime ==  
 
== 5. Locator Runtime ==  
  
When Locator is configured and ready for launch click '''Start Server''' to initialize TCP/IP communication. Locator is now initialized and waits for connection from client:
+
When Locator is configured and ready for launch, click '''Start Server''' to initialize TCP/IP communication. Locator is now initialized and waits for connection from the client:
  
  
Line 111: Line 129:
  
  
As soon as the connection from client is established and the first scan is triggered, the current point cloud should appear in the 3D visualizer screen on the right side. Use mouse to reorient 3D viewer properly.  
+
As soon as the connection from the client is established and the first scan is triggered, the current point cloud should appear in the 3D visualizer screen on the right side. You might need to use the mouse to reorient the 3D viewer correctly.
 +
 
 +
The final object whose coordinates are about to be sent to the client is '''highlighted in 3D visualizer in blue''' and its coordinates are output to the log screen. The figure below illustrates a situation in which only a single result was requested. 
 +
 
 +
 
 +
[[File: Locator single result mode.png]]
 +
 
  
The final object which coordinates are about to be sent to the client is '''highlighted in 3D visualizer by blue color'''. The actual object pose is also outputted to the '''log screen''' in the bottom left corner.  
+
If multiple results have been requested, all localized objects are highlighted blue and all coordinates are output to the log screen in the bottom left corner. See the figure below:
  
  
[[File: Locator runtime.jpg]]
+
[[File: Locator multiple result mode.png]]
  
  
Locator Core works as a background service so even if you close Locator GUI, the Locator will still be running.
+
'''Locator Core works as a background service so even if you close the Locator GUI, the Locator will remain running!'''

Latest revision as of 17:33, 26 February 2019

The main aim of this page is to provide a detailed overview of the prerequisites, configuration and runtime of the PhoXi Locator

Users are strongly recommended to read the Locator Tutorial: Introduction before starting this page!

Locator - First Launch

Locator Core is configured to start immediately after the boot. The original image comes with the example 3D Scan of several T-fitting objects placed in the bin and the basic T-fitting PLCF file.

When you launch Vision Controller with Locator for the first time, the default configuration of the Locator uses these two data sources for initial run. 3D scan of T-fitting objects in the PhoXi Control screen which you can see immediately after the boot, is a sign that Locator Core has connected to the example PhoXi device and triggered the first scan successfully. In addition to establishing a connection with PhoXi device, Locator Core has also loaded PLCF file, initialized TCP/IP server, opened configured port and changed the current state to "Waiting for connection...".

If you click on the Locator Configurator desktop icon, you will see the current Locator state as shown in the figure below:


Locator initial run.png


Press Stop Server to halt Locator runtime and adapt current configuration according to the application requirements.

Locator is configured to "remember" configuration from previous session so even after turning Vision Controller OFF and ON again, it will start with the last active configuration automatically.

Following sections provide detailed information about PhoXi Scanner configuration, generation of PLCF and Locator setup.

1. PhoXi Control

Locator was designed to work with Photoneo PhoXi Scanners and requires the PhoXi Control application to be running in parallel to the Locator application.

As a first step in the process, ensure that the PhoXi Scanner is connected to the same subnet and appears in the Network Discovery tab of PhoXi Control as is shown in the figure below:


Locator NetworkDiscovery.png


Connect to your PhoXi Scanner and fine tune the scanning parameters in order to achieve the optimal scanning performance. See our knowledge base for more information on this topic.


Locator-PhoXiControl.png


2. Localization Configurator

PLCF (Photoneo Localization Configuration File) is extremly important for the overall performance of Locator. PLCF holds information about the object that is going to be localized within the scene, including CAD model, point of interest, stop criteria, localization settings and training data. PLCF is generated by Photoneo Localization Configurator, which is available of Vision Controller as a standalone tool and can be launched by typing PhoLocConfig into the console or by searching for Photoneo Localization Configiurator directly in the Ubuntu Applications menu.

NOTE: HW license (USB Dongle) must be inserted into the system before launch!


Locator PLCF Configurator.png


Launch Photoneo Localization Configurator and upload the model of your object in .ply or .stl format.


Locator step 1 final.png


The Model Coordinates tab is intended for the configuration of the point of the interest. The point of the interest is the point on the object, which coordinates will be returned by the Localization.

If you plan to approach the object directly in the orientation returned by Localization, set the Z axis of interactive marker to point in the approaching direction of the robot (See the figure below).


Locator PLCF Config5.png


Always try to set the point of the interest to be unique with respect to the object, meaning that there is only one possible correct result of successful localization (this not always possible, especially for rotation invariant objects). In cases in which several possible correct localization results might occur, you will need to apply additional logic to the robot controller to avoid situations when the goal pose returned by Locator is not kinematically reachable by the robot.

Such a scenario is shown in the figure below. Even if you define the point of the interest on the top surface of the object, you might obtain a result from the bottom side of the object pointing to the opposite direction. This result is correct from a localization point of view, however it is not kinematically reachable by the robot. In this situation additional logic would have to be applied directly on the robot controller to avoid this outcome.


Locator possible results.png


On the Set Parameters tab, ensure that you have selected suitable Stop Criteria and trigger localization several times to verify that your current configuration provides reliable results. See the figure below:


Locator PLCF Config2.png


In cases in which Localization does not work properly, it might be necessary to make adjustments in the Advanced Settings dialog. Contact [Photoneo support] if you need help with this step.


Locator PLCF Advanced settings.png


Click Generate to create a PLCF file once Localization Configuration has finished. Use this file as an input for Locator in the following steps.

3. Locator Start [Ubuntu]

Locator Core works as a background service so it should be up and running from the boot. Type ps aux | grep pholocator to verify that the pholocator service is running.


Locator psaux.png


If you want to visualize the Locator GUI, simply search for the Locator Configurator icon in the Applications menu in Ubuntu or type the LocatorConfigurator command directly into the terminal.


Locator Ubuntu apps v2.png


4. Locator Configuration

The Locator GUI consists of a control panel on the left side and a 3D Visualizer on the right. As was mentioned above, the Locator GUI is primarily intended for the configuration and validation of Locator functionality.


Locator settings2.jpg


The Locator controls are as follows:

  • - Scanner ID - List of all available PhoXi Scanners as shown by Network Discovery in the PhoXi Control application. Use Refresh to reload available devices.
  • - Port - Defines the port which will be opened for socket communication. Locator always works in server mode.
  • - PLCF - Photoneo Localization Configuration File generated from Localization Configurator in the previous step. See this link for more information. Use the Configure New button to launch the Photoneo Localization Configurator directly.
  • - Best Result Selector - this option is used to filter results returned by Localization. Select from Min X, Max X, Min Y, Max Y, Min Z, Max Z, Max Overlap options.
  • - Store Log - If you want to store Locator logs to the text file, check this option and select or create a file using the Browse button.
  • - Load/Save Server Configuration - Locator stores the last configuration by default, however these buttons can be used to save the current configuration to a specific file to for future use.
  • - Start/Stop Server - This button is intended to start and stop the Locator TCP/IP server.

5. Locator Runtime

When Locator is configured and ready for launch, click Start Server to initialize TCP/IP communication. Locator is now initialized and waits for connection from the client:


Locator waiting for connection.jpg


As soon as the connection from the client is established and the first scan is triggered, the current point cloud should appear in the 3D visualizer screen on the right side. You might need to use the mouse to reorient the 3D viewer correctly.

The final object whose coordinates are about to be sent to the client is highlighted in 3D visualizer in blue and its coordinates are output to the log screen. The figure below illustrates a situation in which only a single result was requested.


Locator single result mode.png


If multiple results have been requested, all localized objects are highlighted blue and all coordinates are output to the log screen in the bottom left corner. See the figure below:


Locator multiple result mode.png


Locator Core works as a background service so even if you close the Locator GUI, the Locator will remain running!