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

From 3D scanning Knowledge base - Photoneo wiki
Jump to: navigation, search
 
(26 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 how to configure and use 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''' 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:
  
  
[[File: Locator NetworkDiscovery.png]]
+
[[File:Locator NetworkDiscovery.png]]
  
  
'''Connect to the specific PhoXi Scanner''' and fine scanning parameters in order to provide best achievable results. 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 ==
  
The Configuration of PLCF (Photoneo Localization Configuration File) is very important for overall Locator performance.  
+
'''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!''' 
 +
 
 +
 
 +
[[File: Locator PLCF Configurator.png]]
 +
 
 +
 
 +
Launch '''Photoneo Localization Configurator''' and upload the model of your object in '''.ply''' or '''.stl''' format.  
  
Launch Photoneo Localization Configurator and on the '''1. Step - Model''' tab upload the model of your object in '''.ply''' or '''.stl''' format.
 
  
 +
[[File: Locator step 1 final.png]]
  
[[File: Locator PLCF Config3.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.
  
On the '''2. Step - Model Coordinates''' tab, select the point of interest - the point on the object, which should be returned by the Localization. Try to set this point to be unique (not always possible especially for rotation invariant objects).
+
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). Otherwise it might not be kinematicaly reachable. 
 
  
 +
[[File: Locator PLCF Config5.png]]
  
[[File: 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'''.
  
On the '''3. Step - Set Parameters''' tab, ensure that you select reasonable Stop Criteria and trigger localization several times to see your current configuration provides reliable results. See figure below:
+
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. 
 +
 
 +
 
 +
[[File: 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:
  
  
Line 43: Line 75:
  
  
In case that Localization does not provide reliable results, use '''Advanced Settings''' to adjust additional localization settings.  
+
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.
 +
 
 +
 
 +
[[File: Locator PLCF Advanced settings.png]]
 +
 
  
Click '''Generate''' to create PLCF file when Localization Configuration is finished.   
+
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 running in the background since first reboot after its installation.  
+
'''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.  
 +
 
  
If you want to visualize Locator GUI, simply search for '''Locator Configurator icon ''' in the Applications menu in Ubuntu or type '''Locator''' command directly to the terminal.  
+
[[File: 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.  
 +
 
 +
 
 +
[[File:Locator Ubuntu apps v2.png]]
  
  
 
== 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 62: Line 105:
  
  
Following is the list and description of Locator controls:
+
The Locator controls are as follows:
  
* - '''Scanner ID''' - Locator detects and list 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.
  
* - '''Main Port''' - Set a number of port which will be opened for TCP/IP communication by Locator for communication with client.  
+
* - '''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. 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. For example if PLCF configuration is set to return 50 results but Locator client request only single one, this option affects which of Localization results will be finally transmitted to the client. If client requires more results, Best Result Selector is used as sorting criterion. 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 by default stores the last configuration used, 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.   
  
== 3. Locator Runtime ==  
+
== 5. Locator Runtime ==  
  
When Locator is configured and ready for launch use '''Start Server''' button to initialize TCP/IP communication. Locator initialized and waiting for connection from client as shown in the figure below:
+
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 86: Line 129:
  
  
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. Use mouse to reorient 3D viewer to show scene and goal object/s 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!