PhoXi ® Control · Understanding the output format - topology of 3D scan 15 List of supported...

PhoXi® Control User Manual

Version: 1.2

v 19.01.28

User Manual for PhoXi Control version 1.2 Document version: 19.01.28 All rights reserved. No part of this publication may be reproduced, stored in a retrieval system, or transmitted in any form or by any means, electronic, mechanical, photocopying, recording, or otherwise, without prior written permission of the publisher. Copyright © 2014-2018 by Photoneo s.r.o., Bratislava, Slovakia Photoneo®, PhoXi® Control, PhoXi® 3D Scanner, MotionCam-3D, MotionCam 3D are registered trademarks of Photoneo s.r.o. Microsoft, Windows, Windows 7/8/8.1/10, Visual Studio C++ are either trademarks or registered trademarks of Microsoft Corporation. Linux is a trademark of Linus Torvalds. NVIDIA, CUDA, cuBLAS, and cuDNN are either trademarks or registered trademarks of NVIDIA Corporation. OpenGL is a trademark of Silicon Graphics, Inc. All other nationally and internationally recognized trademarks and tradenames are hereby recognized.

www.photoneo.com PhoXi Control 1.2 - User Manual 1/38

http://www.photoneo.com/

v 19.01.28

About This User Manual

This manual is intended for users who want to familiarize themselves with the PhoXi Control software suite for PhoXi 3D Scanners. PhoXi Control provides both a graphical user interface (GUI) and an application programming interface (API).

PhoXi 3D Scanner is a compact yet powerful 3D scanner with unbeatable performance in the terms of precision, noise and overall efficiency. It can be used for scanning a wide variety of subjects in various configurations, making it a universal tool which is ideal for all kinds of industrial applications.

The content in this manual is based on PhoXi Control version 1.2. and firmware version > 1.2. of the PhoXi 3D Scanner. Visit the Photoneo website for the most up-to-date information and documents. Please read this PhoXi Control User Manual before using PhoXi Control. Please read the PhoXi 3D Scanner User Manual for your PhoXi 3D Scanner to get familiar with safety and assembly instruction before using the device.

Contact

Photoneo s.r.o. Jamnického 3 841 05 Bratislava Slovakia Orders and inquiries: [email protected]

Technical support

Contact us at [email protected] See the Troubleshooting section at the end of this manual. Consult the Photoneo Wiki at http://wiki.photoneo.com



mailto:[email protected]


http://wiki.photoneo.com/


v 19.01.28

Table of Contents

Introduction 6 Vocabulary 6

Getting started 7 HW Requirements 7

Installation 8

Windows 8

Linux 8

Graphical User Interface 9 Overview 9

Menu 9

Main menu items 9

Network Discovery 9

Open file camera 9

Lock GUI 9

Turn Off PhoXi Control 9

Other menu items 9

3D Cameras 9

Languages 9

Tools / Options 10

Help / Send Logs 10

Help / Send Admin Request 10

Help / About 10

Network Discovery 11

Connecting to the Scanner 12

Device states overview 12

Relationship between GUI and API 12

File Cameras 12

Configuring the Scanner network settings 13

Device window 14

Main Controls 14

Acquisition modes - triggering the scan 14

Saving the 3D scans 15

Understanding the output format - topology of 3D scan 15

List of supported formats 15

Saving single scan manually 16

Saving scans automatically - Recording 16

Saving options 16

Specifics of file formats 16

Tools 16

Test Speed 16

Firmware Upgrade 17



v 19.01.28

View 17

Settings pane 17

Scanning profiles 17

Using own profile 18

Scanning parameters 18

Controls 18

Output 19

Viewer pane 20

3D Viewer 20

Changing the visualisation 20

3D Viewer Controls 21

Image tabs 22

Confidence Map 22

Depth Map 22

Texture 22

Image tabs visualisation controls 23

Image information 23

Intensity 23

Controls 23

API 25 Introduction 25

Prerequisites 25

Getting started example - “Connect and Grab” 25

Instructions to run the example 25

Full API example 26

Using PhoXi API with 3rd party libraries 27

OpenCV 27

Point Cloud Library (PCL) 27

Scanning guide 29 How to scan 29

Factors affecting the scan 29

Assessing the quality of the scan 30

Scanning parameters 30

Capturing Settings 30

Basic 30

Advanced 31

Processing Settings 32

Data Cutting 32

Point Cloud Generation 33

Experimental Settings 34

Coordinates Settings 34

Troubleshooting 35 The PhoXi 3D Scanner does not appear in the PhoXi Control application 36



v 19.01.28

Cannot connect to the Scanner or the scanning time is too long 36

Bonjour Service cannot be started on Windows 36

How can I update firmware on the device? 36

I can’t see some settings and/or controls in the Settings pane 36

PhoXi Control window freezes or is very slow 37

In case of other problems 37



v 19.01.28

Introduction The PhoXi Control application enables users to control the PhoXi 3D Scanner manually through the GUI or programmatically through the provided API. The GUI is primarily used to set up the scanning environment, to configure Scanner parameters and to test the output. In addition, the GUI can also be used as a powerful debugging tool for development with the API because calls to the API trigger the same response in the GUI as user inputs. After triggering the scan by calling the API method, the application will execute the scan, send it as an output of the call and display it simultaneously on the GUI. The API has been designed to serve as a central platform for building custom industry applications for PhoXi 3D Scanners. In order to facilitate the development process and reduce computing demands, all computations are performed on the device itself. This user manual will first guide you through using the PhoXi Control GUI and the API and then provide a quick scanning guide with references to further resources.

Vocabulary It is useful to clarify few terms used throughout this document.

scanner, device Short term for the PhoXi 3D Scanner

Image sensor PhoXi 3D Scanner is composed of three main units: projection unit, 2D camera unit and computing unit. Image sensor refers to the CMOS sensor inside 2D camera unit.

2D camera Refers to the 2D camera unit inside the PhoXi 3D Scanner.



v 19.01.28

Getting started

HW Requirements

Please ensure that your computer meets at least following requirements in order to run smoothly.

Processor: Intel i5 or higher, x64 architecture (Processor performance affects the responsiveness of the application.)

Operating system: Only 64 bit platform Windows 7, 10 Ubuntu 14 (will be deprecated, only bug fixes) Ubuntu 16

RAM: Recommended > 8 GB (min 2 GB for the application connected to 1 device)

HD: 4 GB disc space

GPU: Recommended external graphics card with OpenGL v 2.0 support. PhoXi 3D Scanner has a very high resolution with more than 3 million of 3D points, therefore the requirements on graphical performance of your graphics card are higher. Old or slow graphics card can cause low performance of 3D viewer.

For using the API, following compilers are supported:

● Windows OS: ○ Visual Studio 12 2013 Win64 ○ Visual Studio 14 2015 Win64

● Ubuntu 14: g++ 4.9.4

● Ubuntu 16: g++ 5.4.0



v 19.01.28

Installation

Download the latest version of PhoXi Control: http://photoneo.com/3d-scanning-software/ Installer will prompt you to uninstall previous version of PhoXi Control. Only one version of PhoXi Control at the time is supported.

Windows To install PhoXi Control on Windows, proceed as follows:

1. Double-click the downloaded .exe file. 2. Follow the setup wizard and restart the computer if prompted to do so. 3. Run PhoXi Control as a standard Windows application.

Default installation paths:

- Shortcut folder: C:\ProgramData\Microsoft\Windows\Start Menu\Programs\Photoneo's PhoXi Control

- Installation folder: C:\Program Files\PhotoneoPhoXiControl

- Application data folder: %AppData%/roaming/PhotoneoPhoXiControl/

Linux To install PhoXi Control on Linux, proceed as follows:

1. Unpack the downloaded .tar file $ tar -xvf PhotoneoPhoXiControlInstaller-Ubuntu[16 14]-<version>-STABLE.run.tar

2. Execute with sudo $ sudo ./PhotoneoPhoXiControlInstaller-Ubuntu[16 14]-<version>-STABLE.run.tar

3. Successful installation output will show you the installation path and asks you for reboot.

4. Restart your computer $ sudo reboot

5. Run PhoXi Control from command line or from launcher $ PhoXiControl

Default installation paths:

- Installation folder: /opt/PhotoneoPhoXiControl

- Application data folder: /home/<username>/.PhotoneoPhoXiControl


http://photoneo.com/3d-scanning-software/


v 19.01.28

Graphical User Interface

Overview The introduction window of the application is called Network Discovery and displays a list of all devices available on the network. Connection to the device opens a new Device window. Device windows can be organised by dragging the title of the window. The application minimizes to the system tray. To close the application, use the Menu or right-click on the system tray icon and select the option to Turn off PhoXi Control.

Menu This chapter explains the use of menu items.

Main menu items

Network Discovery

● Opens the Network Discovery window. Used when the window is hidden after connecting to the device.

Open file camera

● Loads 3D scans in *.praw format into the new File Camera, which remains available until the application is shut down.

Lock GUI

● Option to protect the use of GUI with a password.

Turn Off PhoXi Control

● Shuts down the application (using the standard close button will only hide the application in the system tray).

Other menu items

3D Cameras

● Switching window to one of the connected device or file camera.

Languages

● Switch between supported languages.



v 19.01.28

Tools / Options

● Switching color themes. ● Disabling default warning behaviour. ● Reset application look

- The application remembers your preference of showing UI components. Use this function to reset to the default layout.

Help / Send Logs

● This option allows you to send logs to Photoneo support for further investigation.

● Make sure your network settings do not block access to the server photoneo.com and its subdomains.

Help / Send Admin Request

● By sending an admin request, you can allow a Photoneo employee to set admin privileges for this PhoXi Control application. This is used to change advanced scanner parameters. Please fill out the fields and ensure that your device is connected to the Internet and that your network settings do not block access to the server photoneo.com

Help / About

● Displays the current PhoXi Control application version and links to the Photoneo web page.



v 19.01.28

Network Discovery

The Network Discovery window lists all available Scanners on the network. After the application starts, please wait a moment until all Scanners are found. If your Scanner is not listed, please make sure that your Scanner is turned on and connected to the network. After a short time the Scanner will appear on the list. The time to discover newly powered device should be under 3 minutes. The time to discover the device after it was disconnected or the connection was lost should be under 45 seconds. If no device is shown in your list, please check your network configuration. See the chapter Configuring the Scanner network settings for more information.



v 19.01.28

Connecting to the Scanner To start controlling the Scanner, double-click on the Scanner in the list or select the Scanner in Ready state and click Connect. The application will connect to the Scanner and open the Device window. For other users on the network, the status of the Scanner will change from Ready to Occupied. Therefore if you share a Scanner with other users, make sure you disconnect from the Scanner after you finished using it. The following list represents all possible device statuses.

Device states overview

Not started Device was just plugged in or restarted. After a few seconds, the status will change to Starting.

Starting Device is starting its operating application. After a few moments, the status will change to Ready.

Ready Device is ready for new connection.

Terminating Device is terminating after user disconnects from the device. After a few moments the status will change to Starting and Ready.

Occupied Device appears as occupied after the connection was established. Only one connection at the time is allowed. It is not possible to connect to an occupied device.

Relationship between GUI and API

Connection to the Scanner through the API causes GUI to open the Device window the same way as when connecting through GUI. When you connect to the device through GUI, it is perfectly possible to work with the device through API.

File Cameras Every 3D scan taken by PhoXi 3D Scanner can be saved into the native *.praw file. The main advantage of using the native format is that it contains all information about the scanning configuration and additional information about the device. Single or multiple *.praw files can be loaded into the PhoXi Control either using the menu or by drag & drop functionality. Opening a praw file(s) will create a new virtual device called File Camera. This virtual



v 19.01.28

device behaves very similar to a regular Scanner. Triggering new scan on the File Camera will open next praw file in the directory. Note: The scanning parameters for File Camera are read only, as these scans were already taken and processed. Network Discovery window offers specific options for File Cameras upon right click or by a keyboard shortcut:

● Add as internal File Camera ○ Internal File Camera remains in Network Discovery even after you restart the PhoXi Control

application.

● Remove from list (Delete key) ○ This option will remove the File Camera from the list of devices but keep underlying files

on disk

● Delete from filesystem (Shift + Delete keys) ○ This option will remove the File Camera from the list of devices and also delete underlying

files from disk.

Configuring the Scanner network settings To be able to discover the device on the network, It is necessary that both your computer and the device is set to DHCP (this is default for the device) or that you are on the same subnet as the device when using static IP configuration. The default device IPv4 is 169.254.0.X, so the subnet on your computer should be 255.255.0.0 (this is sometimes necessary especially for Ubuntu). To switch between static and dynamic IP of the Scanner in the network, select the Scanner in the list and click Configure. By default, the device uses DHCP. The device will restart after changing its network settings. Make sure to set a compatible IPv4 address on the host computer in case you are using static IP configuration. Please note that setting an invalid static IP can result in unrecoverable connection loss. The ideal communication method for the Scanner is IPv6. Always consider enabling IPv6 in your network. If no device is visible on the network, turn of the firewall.



v 19.01.28

Device window The Scanner window consists of 3 parts:

● Main Controls (red) ● Settings pane (green) ● Viewer pane (blue)

TIP: Once the window is open, hit F5 or the Trigger scan button to trigger a scan.

Main Controls Main Controls provide basic functions for triggering and saving scans and for safe disconnection from the device. They also contain set of advanced tools.

Acquisition modes - triggering the scan

PhoXi 3D Scanner can run in two acquisition modes: ● Single scan mode (default)

○ Device waits for trigger command to perform 3D scan. ○ Use button Trigger scan.

● Free run mode ○ Device performs consecutive scans at maximum speed (if not slowed down by Maximum

FPS setting) ○ To toggle free run mode on or off, use button Free run.



v 19.01.28

○ When the device is in Free run mode, you can pause and restart the acquisition by button Pause / Start.

At any time you can prevent the device from taking scan by using the Pause button. The use of this function is more intuitive in the API, where secondary application may prevent other application from triggering the scan.

Saving the 3D scans

Application allows manually save single scan or automatically save every acquired scan. Automatic saving mode is called recording. The output of the PhoXi 3D Scanner may contain lot of information:

- Information about the device, e.g. ID number, calibration data of the image sensor... - Information about the 3D scan, e.g. duration, scanning parameters, coordinate system… - Point cloud: organized set of 3D points - Normals: for each captured 3D point, the normal vector expressing the orientation of the captured

surface - Texture: color values for each 3D point - Depth map: the depth data for each pixel from which the point cloud is reconstructed - Confidence data: the data expressing the estimated noise of acquired point

All these data are stored only in a native PhoXi Control format with file extension *.praw. Therefore it is recommended to always store all scans in praw format. See also benefits of File Camera. Scans in praw format can be later converted into any other supported formats. Other than praw formats are capable to store only partial information, usually only point cloud, normals and texture. The data that should be stored for each format can be selected in Saving options dialog.

Understanding the output format - topology of 3D scan

The point cloud acquired by PhoXi 3D Scanner is topographically organized according to the image sensor. The photo from the image sensor is called texture. For each pixel in the image sensor there is one computed 3D point. For the pixel that has "no 3D point" (because the area seen by this pixel was not illuminated by the projection, usually due to the shadows) there is actually a "zero 3D point" = point with coordinates (0,0,0). For example, the pixel at position [x= 2010, y =350] in the texture is the (2064*349 + 2010) = 722346-th point in the point cloud. PhoXi Control allows also saving of unorganized point clouds. In unorganized point clouds the "zero points" are omitted and not saved. Therefore the topology is lost. If you have an unorganized point cloud and would like to restore its organization, you’ll need to iterate over the point cloud and find corresponding pixel in the depth map by comparing the Z value.

List of supported formats

- Photoneo RAW data format (*.praw) - Stanford’s PLY (*.ply)

- http://graphics.stanford.edu/data/3Dscanrep/ - Leica’s PTX (*.ptx)


http://graphics.stanford.edu/data/3Dscanrep/


v 19.01.28

- http://w3.leica-geosystems.com/kb/?guid=5532D590-114C-43CD-A55F-FE79E5937CB2 - Text file (*.txt) - Raw images in tif (*.tif)

For each format you might choose which data to store (point cloud, normals, texture…), see the Saving options below.

Saving single scan manually

After triggering the scan, use button Save to open saving dialog. Choose one of the supported formats and confirm. The data stored within the file are defined in Saving options dialog. TIP: you can convert scan in praw format to any other format by loading it into PhoXi Control and choosing different file format in saving dialog.

Saving scans automatically - Recording

Toggle button Record to start or stop automatic recording. Before using this functionality, use Saving options dialog to define destination and file formats in which the scan should be stored.

Saving options

Use button Saving options to configure your preference for storing the 3D scans and corresponding data. Fields Folder path and File pattern are used by automatic recording. Folder path defines the destination where the scans will be saved. File pattern defines the name of the files, hash signs will be replaced by counter starting at the defined value. The image on the right depicts the settings that will save the scan in file scan_0011.praw. Use the checkboxes on the left (next to name of the file format) to select all formats in which the scan should be saved during automatic recording. Use the Options button on the right (next to the name of the file format) to define which data should be saved when using this file format.

Specifics of file formats

● What is confidence map? See: http://wiki.photoneo.com/index.php/Confidence_Map ● Using text file as a file format may result in longer saving time, depending on the speed of your

hard drive. The same holds for not using binary format in PLY format. ● TIF file is one dimensional, therefore this file format actually creates multiple files for each stored

component.

Tools

Test Speed

Tests the speed of the connection to the device. The device acquisition mode


http://w3.leica-geosystems.com/kb/?guid=5532D590-114C-43CD-A55F-FE79E5937CB2

http://wiki.photoneo.com/index.php/Confidence_Map


v 19.01.28

must be stopped for the duration of the speed test.

Firmware Upgrade

Opens a new dialog window which searches for a *.deb package. After selecting the correct *.deb package, the firmware on the device will be updated. Do not disconnect the device during the firmware update. Contact [email protected] for the options to upgrade your FW.

View

● Device settings pane: ○ the pane on the left side which contains device settings.

● Visualisation settings pane: ○ pane on the right-hand side which contains options to

change the visualisation of the point cloud.

Settings pane Settings pane:

● Provides scanning profiles and parameters (tab Properties) ● Allows to control the output data sent from the Scanner (tab Output structure)

The set of scanning parameters and presets depends on the firmware version of your device. This User Manual is based on FW version 1.2.6.

Scanning profiles

Scanning profiles allow changing multiple scanning parameters at once. You can define as many own profiles as necessary. PhoXi 3D Scanners come with predefined profiles that should help you to fine tune the scanning parameters for various use cases.

Use the cog button to enter advanced configuration.

● Select - switch to the chosen profile. ● Create new from existing - creates a new profile as

a duplicate of the selected profile. The newly created profile can be amended in the Properties window and stored to device.

● Delete - deletes the selected profile. ● Rename - renames the selected profile. ● Mark as startup profile - The device will be started

with this user profile. ● Reset to factory settings - resets settings to factory

default. ● Import - imports a user profile from file. ● Export - saves a user profile to file.




v 19.01.28

Using own profile

● Use button and create new profile from the existing profile which is closest to your use case. You might want to mark it as a startup profile as well.

● Amend desired parameters to your needs ● Use Set and Store button to permanently store the settings

Scanning parameters

The scanning process consists of three phases: capturing (or acquisition), processing (computation) and transfer. Scanning parameters are divided into four logical groups:

● Capturing settings - these options change exposure times and methods of projecting structured light patterns.

● Processing settings - these options affect the computation of the point cloud and allows setting the region of interest.

● Experimental settings - advanced settings which are used in special use cases.

● Coordinate settings - defines the coordinate space for the point cloud.

The total scanning time is the sum of the times required for acquisition (defined by capturing settings), computation (defined by processing settings) and transfer (defined by Output structure). The use of scanning parameters is described in Scanning Guide - Parameters at the end of this User Manual.

Controls

● Search box (Ctrl+F) ○ Search setting by name

● Set button (Ctrl+S)

○ Sets scanning parameters for the current session only. Settings are discarded after the scanner is disconnected.

● Set and store button (Ctrl+Shift+S) ○ Store scanning parameters permanently to the Scanner memory (and current profile).

● Refresh button (Ctrl+R)

○ Retrieve current settings for selected profile from the Scanner memory.



v 19.01.28

Output

Output structure lets you choose which kind of data will be retrieved from the scanner. Any changes to the output structure will affect the transfer stage. The retrieval time can be sped up by selecting only the data which you need for your application.

PointCloud The point cloud is a set of measured 3D points. Each 3D point has coordinates X, Y, Z in the point cloud coordinate space (see Coordinate settings). The point cloud has a topology which corresponds to the image sensor. Unmeasured points (pixels) caused by shadows are given the default coordinates (0,0,0). Based on the saving options these unmeasured points might or might not be saved. The point cloud can be examined in the 3D Viewer tab.

NormalMap The normal vector for each 3D point can also be calculated. The normal vector is perpendicular to the area surrounding the point (see Normal estimation radius). Normals can be inspected in the 3D Viewer tab after selecting the display parameter in the right pane.

DepthMap The “depth” of a point is the absolute 3D distance from the image sensor to the measured point (the ray of the light that hits the surface of the object). The DepthMap is therefore always in the camera coordinate system and corresponds to Z coordinate value in the point cloud. NOTE: even when you change the point cloud coordinate space, the DepthMap always shows the distance (depth) in the camera coordinate system.

Texture Texture is the 2D photo of the scene. The source of the illumination is either a LED diode or a laser projection. Texture is in a gray scale (in the red spectrum). Texture is used to colour the 3D point cloud..

ConfidenceMap For each measured 3D point, the “confidence” value expresses the certainty about the accuracy of the point measurement. For example, a confidence value of 0.12 means that the estimated error for point measurement is 0.12 mm. This value is based on a heuristic method that considers the light conditions for each pixel.



v 19.01.28

Viewer pane This pane displays the output from the Scanner in various views. After the device window was opened, hit F5 or press the Trigger scan button in the main controls to trigger the scan. The output is provided as a 3D point cloud (3D Viewer tab) and a set of corresponding data as 2D images (all other tabs). View can be switched using the tabs at the bottom. Each view has its own display settings on the right. These settings does not change the data themselves, just their visualisation. It is recommended to understand the relationship between 3D point cloud and 2D images as described in Point cloud topology.

3D Viewer

Use this tab to inspect the point cloud and obtain a general overview of the scanned scene.

Changing the visualisation

Set default view Resets the camera to the default position.

Restore default settings Restores the default settings for Texture, Normals and Coordinates.

Color Select the data source for coloring the point cloud: ● Plain White - all points are white, no shader is applied ● Texture - points have colour from the photo of the scene



v 19.01.28

● Normals - color is based on point orientation (direction of the normal vector)

● Depth - Grayscale - color of the point is based on its distance from the device. Furthest points are white, closest points are black.

● Depth - Hue - color of the point is based on its distance from the device. Furthest points are red, closest points are blue.

Texture - Intensity multiplier Makes the visualization brighter or darker.

Normals checkbox Renders normal vectors for selected 3D points. Control the selection of 3D points by the Normals distribution setting and the length of the vectors by Normals - Length setting.

Coordinates - Axis Renders the axis of the coordinate system.

Coordinates - Laser and Camera checkbox

Renders the position and field of view of the camera and laser unit of Scanner.

Frame information section Shows information about the current frame such as: ● Index - serial number of scanned frame in current session ● Acquisition - duration of acquisition phase (projection of patterns). ● Computation - duration of the computation on the device ● Transfer - duration of the data transfer from the device to the

computer. ● Timestamp - timestamp of the scanned frame in current session

3D Viewer Controls

Left mouse button drag Rotates the point cloud around the selected point of focus. By default, the selected point of focus is the camera position.

Mouse wheel or Vertical right mouse button drag or Keys: [ ]

Zooms in/out.

Mouse wheel drag or Hold SHIFT + left mouse drag

Moves the point cloud.

Hold CTRL + left mouse drag Tilts the point cloud.

F Sets the point of focus to the point under the mouse cursor. This is the point around which the scene is rotated.

R Resets the view to the default. Use to center the view on the point cloud.

Key: + Increases the size of point.

Key: - Decreases the size of point.



v 19.01.28

Image tabs

Confidence Map

This tab displays the predicted error of measurement for each pixel (corresponding 3D point). Darker areas in this map show areas which have been scanned with lower error rates, while lighter areas indicate areas where errors may have occurred, suggesting that these sections of the scene may be problematic. See http://wiki.photoneo.com/index.php/Confidence_Map for further information. To see the confidence map, it is necessary to turn it on in the output structure and then trigger new scan. Set Maximal value threshold in the right pane to the reasonably small number, e.g. 0.5. Then hover the mouse cursor over the image to see the value of specific pixel (its corresponding 3D point).

Depth Map

This view shows the scene as a gray-scaled image in which the intensity of every pixel represents the distance of the measured point from the camera. The depth value of the pixel under the cursor is shown in the right side pane as the current pixel value. The image can be made more readable by adjusting the settings on the right side of the window as explained below. This view can also be used for measuring the distance between 3D points by dragging a line between corresponding pixels with the right mouse button.

Texture

The texture is the 2D photo of the scene. Colours from the texture are used to colour the point cloud.


http://wiki.photoneo.com/index.php/Confidence_Map


v 19.01.28

Image tabs visualisation controls

Image information

Zoom level Current zoom level of the image.

Cursor position Position of the pixel under the cursor.

Current pixel value Value of the pixel under the cursor.

Pixel datatype Represents the data type of the image.

Distance Distance between two points. You can measure distance of two points by dragging a line between them with the right mouse button.

Intensity

Use Intensity settings to make the image look brighter or darker.

Minimal value Pixels with lower value than the minimal value are depicted in black.

Maximal value Pixels with higher value than the maximal value are depicted in white.

Auto Min Max Computes values of Minimal and Maximal intensity for current viewport to maximize the visualisation benefit.

Highlight Camera View

Highlights pixels which corresponding 3D points are currently in the viewport of the 3D Viewer.

Value multiplier Makes image look brighter or darker.

Controls

Button: Set default view

Resets image position and zoom to default values.

Button: Restore default settings

Restores the default settings for Intensity settings.

Left mouse button drag Moves the scene.

Mouse wheel Zooms in/out.

Right mouse button drag Draws a line between two pixels and computes the 3D distance between the two corresponding 3D points.



v 19.01.28



v 19.01.28

API

Introduction The PhoXi API provides all the building blocks necessary for developing your custom application for the PhoXi 3D Scanner. The API is provided directly by the PhoXi Control application, so make sure the application is running before using the API. This manual will demonstrate how to use the API in two examples. You can start your development based on one of the examples and modify it to suit your specific needs. Microsoft Visual Studio 2015 and CMake will be used to depict how to run the examples. The technical documentation is located in the file API/API_Manual.html inside the application installation directory. On Windows OS, the path to the API directory is usually: “Program Files/PhotoneoPhoXiControl/API ” On Linux OS, the path to API directory is usually: “/opt/PhotoneoPhoXiControl/API ”.

Prerequisites CMake version 3.10 or above. You can download CMake from the following link: https://cmake.org/download/

Getting started example - “Connect and Grab” This example will test that everything is working correctly and that you are able to use the API. It will also demonstrate that the GUI is a powerful debugging tool as it displays the responses of API calls in real time. The flow of the program is as follows:

- Firstly, it tests whether the PhoXi Control application is running - It then obtains the list of all devices available on the network - If a device is already active in the PhoXi Control application, it will connect to that device.

Otherwise it will connect to the last scanner in the list. - It will execute 5 scans via a manual trigger and 5 scans in the free run mode.

For full details, please see the source code and consult the technical documentation. Also note that this example only illustrates standard usage without any extensive checks for unexpected conditions.

Instructions to run the example - Copy the content of the directory API/examples/cpp/ConnectAndGrab_CPP to your custom

directory (This is only necessary when you want to edit the source code. Originally, the source code is located inside the Program Files directory, so you will need admin rights to change the file).

- Launch CMake


https://cmake.org/

https://cmake.org/download/


v 19.01.28

- Choose the source and destination directory - Click the Configure button, specify Visual Studio 14 2015 Win64 as the generator for the

project and confirm with the Finish button

- Wait until the configuration is completed, then click Generate button - In the destination directory, open the file ConnectAndGrab.sln - Set the project ConnectAndGrab as a StartUp Project in the right context menu. - Rebuild the solution in Visual Studio (Menu → Build → Rebuild Solution). - Make sure that the PhoXi Control application is running - In Visual Studio, hit F5 to run the example (menu → Debug → Start Debugging) - While the example is running, switch back to the PhoXi Control application - every frame that the

camera captures is displayed in the Viewer pane.

Full API example This example illustrates the use of the API in a production environment where every possible error condition should be handled carefully. To run the example, please follow the instructions from the previous example. The source code is located in API/examples/cpp/FullAPIExample_CPP. This example shows how to:

- find available scanners on the network - connect to the scanner using various methods based on the hardware identification number, index

in the list or to the first active device - get details about the current device status and capabilities - capture the scene in freerun or manual mode and get the output in all provided formats - change the scanning settings and specify the desired output formats - handle and store the received data - correctly disconnect the device



v 19.01.28

Using PhoXi API with 3rd party libraries

OpenCV To enable PHOXI_OPENCV_SUPPORT In your code you should enable OpenCV support by adding these lines (before PhoXi.h): #include "opencv2/opencv.hpp"

#define PHOXI_OPENCV_SUPPORT

#include "PhoXi.h"

The project must then be correctly set up. In VisualStudio 2015: Right click on your project → Properties C/C++ → General → Additional Include Directories:

● C:\Program Files\PhotoneoPhoXiControl\API\include

○ where our API headers are ● <install-dir>\opencv-<ver>\include

○ you should find the opencv and opencv2 folders there Linker → General → Additional Library Directories:

● C:\Program Files\PhotoneoPhoXiControl\API\lib

● <install-dir>\opencv-<ver>\x64\vc14\lib

Linker → Input → Additional Dependencies: ● PhoXi_API_msvc14_Release_1.2.6.lib

● opencv_core<ver>.lib

Point Cloud Library (PCL) To enable PHOXI_PCL_SUPPORT In your code you should enable PCL support by adding these lines (before PhoXi.h): #include "pcl/point_cloud.h"

#include "pcl/point_types.h"

#define PHOXI_PCL_SUPPORT

#include "PhoXi.h"

The project must then be correctly set up. In VisualStudio 2015: Right click on your project → Properties C/C++ → General → Additional Include Directories:

● C:\Program Files\PhotoneoPhoXiControl\API\include ○ where our API headers are

● <install-dir>\pcl-<ver>\include\pcl-<ver> ○ you should find another pcl folder there which contains folders (2d, common,..) and header

files (cloud_iterator.h, conversions.h,...) ● <install-dir>\eigen-<ver>

○ it should contain the Eigen folder which has a src folder and files without extensions



v 19.01.28

● <install-dir>\boost-<ver> ○ it should contain a boost folder which contains all the headers

Linker → General → Additional Library Directories:

● C:\Program Files\PhotoneoPhoXiControl\API\lib ● <install-dir>\pcl-<ver>\lib ● <install-dir>\boost-<ver>\lib64-msvc-14.0

Linker → Input → Additional Dependencies:

● PhoXi_API_msvc14_Release_1.2.6.lib ● pcl_common_release.lib

Please consult the source code and technical documentation for more details.



v 19.01.28

Scanning guide

How to scan 1) Arrange the scene for optimal scanning quality. See Factors affecting the scan. 2) Put the Scanner into optimal scanning distance. Consult datasheet in PhoXi 3D Scanner User

Manual or on the Photoneo website. 3) Adjust scanning parameters for optimal results. See Scanning parameters.

Factors affecting the scan The quality of the scan depends on a number of different factors. The Scanner provides a variety of settings to enable an optimal scan, but even by rearranging the positions of the scene and Scanner you can obtain better results. Always arrange the scene to ensure the best conditions for the scan as a first step and only then manipulate the settings of the Scanner. Distance: Closer objects have a better spatial resolution and generally less noise. Material albedo (reflectivity): Material with higher albedo provides a better signal-to-noise ratio. Strong ambient light: Indoor ambient light does not generally influence the scan. However, very strong light such as direct sunlight might be a problem, especially when scanning outdoors. Try to remove all direct sunlight, for example by closing window blinds or by moving the installation to a different place. Reflections: Non-glossy, matte materials are typically scanned at high quality, and even soft-gloss objects have a nearly optimal scan. However, specular reflections can influence the scan quality since the projected light is reflected out of the sight of the camera (in which case that part has a poor quality). Similarly, reflected light can interfere with scanning when reflected onto other parts of the scene (in which case the part illuminated by reflection can show artifacts). Metal parts with a high-gloss (or mirror-like) finishes are particularly difficult to scan. As a rule of thumb: Take a flat piece of the material you wish to scan and try to look into it as you would with a mirror. If you are able to make out the shape of your head as reflected by the material, the material is glossy. Depending on the scene, some parts might be not scanned optimally. When scanning glossy objects, find a position where the light from the projection unit does not illuminate other objects on the scene. In order to increase the likelihood of an optimal scan while scanning glossy materials, use the “AmbienLightSuppresion” setting, although be aware that using this setting will increase the scanning time. Transparent objects: Transparent materials such as glass, ice or water cannot be scanned. Remove such materials from the scene in order to avoid artifacts. A thin layer of plastic wrap would still allow the wrapped object to be scanned but there is a risk of greater noise in the final scan and the wrap may also increase the glossiness of the object (see previous paragraph). Scanning through a window is possible as long as the window does not cause reflection -- the angle between the projector unit and the window should be close to a right angle.



v 19.01.28

Translucent objects: It is possible to scan translucent objects to a certain extent, however, the scattering of the light inside the material may cause reduce the accuracy of the scan of the object surface. As with transparent objects, materials with a high degree of translucency cannot be scanned.

Assessing the quality of the scan Firstly, do a quick visual check of the scan in the PhoXi Control application. Switch to the Point Cloud tab. Do you see all parts of the object? Use the mouse to rotate the scene or the mouse wheel to zoom in or out. For a more advanced assessment, switch to the ConfidenceMap. This tab displays the expected deviation of the measured distance. Darker areas in the map have been scanned with lower error rates, while lighter areas indicate parts of the scene in which the error rate might be higher, suggesting that these sections may be problematic.

Scanning parameters Before using the PhoXi 3D Scanner, it is useful to get familiar with basics of structured light projection https://en.wikipedia.org/wiki/Structured_light. Please ask your sales representative for more detailed material and webinars on this topic. The scanning process consists of three phases:

● Capturing (or acquisition) ● Processing (computation) ● Transfer

Scanning parameters covers first two phases: capturing and processing. The transfer is affected by the amount of selected data as defined in the Output structure. In addition, scanning parameters also contain experimental settings and settings for changing the coordinate system of the point cloud.

Capturing Settings

Basic

Shutter Multiplier Values: 1 (default) - 20

Increasing scanning time by multiplying projection time of patterns. Shutter Multiplier helps when scanning:

- dark objects - sharp scanning angle - or in any other condition when the pattern is reflected back only

partially Too long exposure can lead to oversaturation and thus missing points.

Scan Multiplier 1 (default) - 20

Increasing scanning time by repetition and averaging of patterns. Scan Multiplier helps to increase the signal to noise ratio and brings higher contrast in situations where high dynamic range is required and shutter


https://en.wikipedia.org/wiki/Structured_light


v 19.01.28

multiplier leads to oversaturation.

Resolution 2064 x 1544 1032 x 772

Benefits of low resolution: - Significantly shorter acquisition time is needed to achieve the same

scan quality as on full resolution - Faster transfer time due to less data

Camera Only Mode

Specifies a mode in which only the internal camera unit captures the frame. With Camera Only Mode, you can use the Scanner’s internal camera to capture 2D images of the scene. These images can then be read as Texture. This setting is useful when it is necessary to navigate the Scanner around the scene or to take a quick snapshot which can look for changes. The setting does not perform any computations necessary for 3D Scanning and therefore has low latency. Default value: false

Advanced

Ambient Light Suppression - off / on

Special acquisition method limiting the effect of ambient light. Use in the situations where increasing Shutter Multiplier does not bring desired performance. This setting locks the Shutter Multiplier to value 2. Therefore to prolong the exposure, use Single Pattern Exposure instead. This setting has no additional value when the Single Pattern Exposure is below 40 ms. Default value: false

Coding Strategy - Interreflections - Normal

Coding strategy optimized for Interreflections uses advanced digital coding to permit the repression of some diffuse interreflection. For most scenes, choosing the interreflection strategy will provide better output, but in some specific situations the Normal strategy might be useful. Default value: Interreflections

Coding Quality - Fast - High - Ultra

Settings connected with subpixel accuracy: - Fast - no sub-pixel accuracy - High - sub-pixel accuracy (default) - Ultra - enhanced sub-pixel accuracy

This parameter influences the processing time. Selection between Ultra and High should be made based on specific scene. Ultra is usually useful for long range scans with XL model. Default value: High

Texture Source

Defines the way how the Texture is acquired.



v 19.01.28

- LED - Computed - Laser - Focus

LED will capture an additional image illuminated with the LED flash that offers a speckle-free 2D image. Computed is a texture computed from the structured patterns - no additional image is required. Images have speckles (laser noise). Laser will trigger an additional image using a Laser flash. Use this setting to investigate light conditions in the scene. Focus will set a structured pattern as a texture. This setting is useful for analyzing problems with signal contrast and the optimal scanning time. Explore the dark and white areas and compare their values. Higher the contrast, higher the scanning quality. But avoid overexposure (value above 4095). Default value: LED

Single Pattern Exposure 10 - 100

Increasing scanning time by longer projection time of patterns. Has the same effects as Shutter Multiplier, but brings more variability in choosing the right value. In combination with Ambient Light Suppression, use values above 40 ms. Default value: scanner specific

Maximum FPS Useful for limiting the fps in freerun mode. If you want to allow a scan every 10 seconds, you can set Maximum FPS to 0.1. Default value: 0 (unlimited)

Laser Power 2000 - 4095

This option is useful only when you are experiencing issues with overexposure. In this case, this setting allows to decrease the power of the laser. Default value: 4095

Processing Settings Processing settings influence the computational part of the scanning after the data were acquired.

Data Cutting

Data cutting is beneficial for noise filtering or background removal. Often, the noise 3D points have normals which are almost in the right angle with the viewing direction. Use max normal angles settings to filter these points out (set max angles to e.g. 70).

Group Name Type Description

3D ROI Camera Space X Double Defines data cutting volumes in either the Camera or the Point Cloud coordinate space. Camera Space Y Double



v 19.01.28

Camera Space Z Double The cutting is applied after the point cloud is computed, therefore this setting can’t speed up the transfer time. The cutting will be applied only when minimal component is smaller than maximal component, e.g. MinX must be less than MaxX. This holds for all components X, Y, Z. Tip: use this setting in combination with Marker Space to remove the background and make scan alignment easy.

Point Cloud Space X Double

Point Cloud Space Y Double

Point Cloud Space Z Double

Normal Angle Max Camera Angle Double 0 - 90

Maximal angle between the normal vector of the 3D point and the direction towards the camera. Default value: 90 degrees

Max Projection Angle Double 0 - 90

Maximal angle between the normal vector of the 3D point and the direction towards the projector. Default value: 90 degrees

Min Halfway Angle Double 0 - 90

Minimal angle between the normal vector of the 3D point and the halfway vector. Halfway vector is the vector between the point-to-camera and point-to-projection vectors. Default value: 0 degrees

Max Halfway Angle Double 0 - 90

Maximal angle between the normal vector of the 3D point and the halfway vector. Default value: 0 degrees

Max Inaccuracy (mm) Double 0 - 5

Controls the number of output points based on point reliability. This enables the user to set preferences based on the application. Some applications require a more complete output at the expense of lower precision. Other applications are intended to work with precise data only and need to filter out regions where the precision does not meet a specific threshold. Default value: 2.0

Point Cloud Generation

Name Type Description

Surface Smoothness Sharp Normal Smooth

Defines the setting of the smoothness of the point cloud generation algorithm.

- Sharp - optimized for small feature retrieval. Higher noise on surfaces.

- Normal - standard sensor setting suitable for most scans.



v 19.01.28

- Smooth - edge preserving algorithm that smooths the surface, lowering noise at the expense of small features.

Default value: Normal

Normals Estimation Radius

Integer 1 - 4

Defines the size of the area (in pixels) around a point which serves for the computation of the normal vector of each 3D point. Higher radius leads to smooth normal vectors, small radius to noisy normals. Default value: 2

Experimental Settings In normal use, there is no need for users to change these settings. We recommend contacting Photoneo support before changing any of the experimental settings.


Use Extended Logging Boolean Determines whether extended logging is enabled in PhoXi Control. Please use this option only when instructed to do so by a Photoneo employee. When enabled, much more data is logged on the Scanner and this can lead to the Scanner memory becoming full. The Scanner must be restarted after changing this setting. Default value: false

Coordinates Settings Coordinates settings are used to change the coordinate space of the returned point cloud. By default the Scanner coordinate system has its origin in the 2D camera, the Z coordinate aims at the scene, the X coordinate aims beyond the Scanner (to the right) and the Y coordinate to the rear (the bottom of the Scanner). The usage of coordinates spaces is covered in more depth at: http://wiki.photoneo.com/index.php/Scan_coordinate_space You can define any arbitrary coordinate space by defining the transformation matrix from the default Camera coordinate space to your coordinate space. The transformation matrix can be stored in “CustomSpace” or “RobotSpace”. TIP: use the 3D visualizer to display the coordinate system of the point cloud.


Coordinate Space CameraSpace MarkerSpace RobotSpace CustomSpace

CameraSpace: Coordinate space with origin in the camera of the Scanner.


http://wiki.photoneo.com/index.php/Scan_coordinate_space


v 19.01.28

MarkerSpace: To align multiple scans in PhoXi Control, it is useful to use marker patterns. You can download marker patterns from the Photoneo website. If you place a marker pattern below an object and set the marker space as your coordinate space, you can now move the Scanner to different locations with the point cloud automatically returning to the same coordinate system defined by the marker plate. RobotSpace: Coordinate space with origin in the robot. Automatically set by Robot-Camera Calibration Tool. See Photoneo website for more information. CustomSpace: Your custom defined coordinate space. Default value: CameraSpace

Recognize Markers Boolean When true, markers will be recognized in the scan. If Recognize Markers is set, you need to present marker pattern to the scanner, otherwise the resulting frame will be corrupted. Default value: false



v 19.01.28

Troubleshooting

The PhoXi 3D Scanner does not appear in the PhoXi Control application

● Double check all cable connections ● Investigate whether your Firewall blocks Bonjour Discovery Service (process

mDNSResponder.exe) ○ https://www.digitalcitizen.life/how-change-windows-firewalls-list-allowed-blocked-apps

Cannot connect to the Scanner or the scanning time is too long

The PhoXi 3D Scanner is listed in PhoXi Control application, but after clicking to connect to it the Scanner disconnects

● Check your ethernet connection speed; the minimum speed should be 1 Gbps

● If your connection is very slow (10 Mbps), the connection will most likely time-out ● If your connection is slow (100 Mbps), data transfer will take more time

Bonjour Service cannot be started on Windows

If you try to start ‘Bonjour Service’ and it fails due to exception 1067, download the 32-bit version of ‘Bonjour Service’ from Apple. The name of the 32-bit version is ‘Bonjour Print Services for Windows v2.0.2’ and it can be found in the following link: https://support.apple.com/kb/dl999?locale=en_US. Bonjour Service has been replaced in PhoXi Control versions 1.2. and is needed only for older firmwares.

How can I update firmware on the device? Please contact [email protected].

I can’t see some settings and/or controls in the Settings pane

Check the firmware version of the device in the Network Discovery window. If the firmware version is lower than 1.2., please ask Photoneo Support for help you with the firmware update.


https://www.digitalcitizen.life/how-change-windows-firewalls-list-allowed-blocked-apps

https://support.apple.com/kb/dl999?locale=en_US



v 19.01.28

PhoXi Control window freezes or is very slow

This issue is related to Qt and Nvidia graphic cards (QTBUG-68883) and has only been experienced on Windows so far. To resolve this, set PhoXi Control to be launched with the integrated GPU. Open NVIDIA Control Panel → Manage 3D Settings → Program Settings → add installed

PhoXiControl → select Integrated graphics → press Apply.

In case of other problems

Please report the problem to [email protected]. Please describe what have you been trying to do, what was the result, and what you expected. Depending on the character of the problem, please also report the Windows version used, PC configuration, and other additional information which would be helpful in replicating the problem and identifying the root cause.


https://bugreports.qt.io/browse/QTBUG-68883



PhoXi ® Control · Understanding the output format - topology of 3D scan 15 List of supported...

Documents

Transcript of PhoXi ® Control · Understanding the output format - topology of 3D scan 15 List of supported...