User Manual for PhoXi Control version 1.17 based on PhoXi Control version 1.17.0.
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.
This manual is intended for users who want to familiarize themselves with PhoXi Control software for MotionCam-3D, MotionCam-3D Color, PhoXi 3D Scanners, and Alpha 3D Scanners. PhoXi Control provides both a graphical user interface (GUI) and an application programming interface (API).
The MotionCam-3D (Color) is a high-resolution and high-accuracy 3D camera that uses a patented CMOS sensor and Parallel Structured Light technology developed by Photoneo. It provides the scanning quality of structured light devices with the ability to scan static and dynamic scenes at the speed of Time of Flight devices. Additionally, output from the RGB camera unit on the color models is mapped on the point cloud, adding an important layer of information for further processing.
PhoXi 3D Scanner is a compact yet powerful 3D scanner with state-of-the-art performance in terms of precision, noise, and overall efficiency. It can be used for scanning a wide variety of objects, making it a universal tool for all kinds of industrial applications, mainly automated object manipulation and inspection.
Alpha 3D Scanner takes advantage of the structured light technology, providing high-quality 3D point clouds for a great variety of machine vision tasks, making it a perfect choice for scanning large objects with a simple shape, such as boxes or containers in measurement, inspection, and similar applications.
This manual is based on the Photoneo 3D Sensors on firmware version 1.17. Using a Photoneo 3D Sensor on a different version may result in slight differences. It is recommended to use the newest firmware version available at Firmware Updater. Consult the Versioning Guide to see the newest firmware version for your device.
Visit www.photoneo.com for the most up-to-date information and documents.
Please read the PhoXi Control User Manual before using the software, and the Photoneo 3D Sensor User Manual to become familiar with the safety and assembly instructions before using the devices.
This user manual will first guide you through the use of PhoXi Control Graphical user interface (GUI) and the API, and then provide a quick scanning guide with references to further resources. Additionally, alternative ways of operating Photoneo 3D Sensors are referenced or described.
Photoneo sensors can be operated via:
PhoXi Control
GUI
API
GenICam (discontinued)
GigE Vision protocol
PhoXi Control application enables users to control Photoneo 3D Sensors manually via the GUI or by a computer program using the provided API or GenICam interface. Alternatively, Photoneo sensors can run in GigE Vision compatible mode in which PhoXi Control cannot be used.
The GUI is primarily used to set up the scanning environment, configure the device parameters, and test the output. In addition, the GUI can also be used as a powerful debugging tool for development with the API, since the calls to the API trigger the same response in the GUI as the 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 the development of custom applications. To facilitate the development process as well as to reduce computing demands, all 3D data computations are performed on the device itself. The postprocessing of the data (e.g. Localization of object) happens on the user’s computer.
GenICam interface was discontinued and removed from PhoXi Control 1.16.4 and onward.
The Generic Interface for Cameras standard is the base for plug-and-play handling of cameras and devices. It was developed by the European Machine Vision Association (EMVA)
GenICam support is provided via the GenTL library that works as a wrapper around the PhoXi Control C++ API. PhoXi Control has to be running in order to use the GenICam interface.
The available examples for Python and Halcon support can be found in the installation directory:
On Windows OS, the path to the GenTL directory is usually:
Program Files/Photoneo/PhoXiControl-1.16.x/API/Examples/GenTL
On Linux OS, the path to the GenTL directory is usually:
/opt/Photoneo/PhoXiControl-1.16.x/API/GenTL
User guides for GenICam integrations contain more detailed information and requirements for running the examples.
GigE Vision is a high-speed communication protocol and interface standard that is designed for transmitting data over Ethernet networks. Third-party software with GigE support can be used to operate Photoneo 3D Sensors without a running instance of PhoXi Control.
User guides for GigE integrations contain more detailed information and requirements for running the examples.
GigE Vision functionalities can be turned on and off. For that please download and install the necessary utilities, that you can find on the corresponding links:
Clarification of several terms used in this document.
Photoneo 3D Sensor
General term for PhoXi 3D Scanner or MotionCam-3D (Color).
device
General term for PhoXi 3D Scanner or MotionCam-3D (Color).
MotionCam-3D
General term for MotionCam-3D devices including the MotionCam-3D Color if not stated otherwise
2D camera
Refers to the 2D camera unit inside PhoXi 3D Scanners.
image sensor
‘Image sensor’ refers to the CMOS sensor inside the 2D camera unit. More information about camera components can be found in Photoneo 3D Sensors User Manual
RGB camera
Refers to the 2D RGB camera unit inside the MotionCam-3D Color and Phoxi 3D Scanner Gen3.
Please ensure that your computer meets the minimum recommended requirements in order to run PhoXi Control smoothly.
Processor
Any x64 architecture, Intel or AMD but Intel Core i7 or Ryzen 7 for best performance.
(Processor performance affects the responsiveness of the application)
Operating system:
Only 64-bit platform
Windows 10 / 11
Ubuntu 18 / 20 / 22 / 24
RAM:
Recommended 16 GB (minimum 2 GB for the application connected to 1 device)
SSD:
128 GB (Minimum 4 GB free disk space)
GPU:
GeForce GTX 1060 3 GB or similar external graphics card with OpenGL v 3.0 support.
Note
Photoneo 3D Sensors have a very high resolution mode producing up to 3 million 3D points, therefore the requirements made on the graphical performance of your graphics cards are higher. Old or slow graphics cards can reduce the performance of the 3D viewer.*
By installing and using PhoXi Control, you agree to the End User License Agreement (EULA), which can be found in the installation directory.
While the installer will prompt you to uninstall any existing version of PhoXi Control, this step can be ignored as Multiple versions of PhoXi Control can be installed on one computer. However, only one instance can run at a time.
To install PhoXi Control on Windows, proceed as follows:
Double-click the downloaded *.exe installation file.
Follow the setup wizard and restart the computer if this is your first installation of PhoXi Control.
Run PhoXi Control as a standard Windows application. The application automatically starts after the computer starts.
Note
The user is able to install PhoXi Control with or without the included file camera examples or the API. This can be changed during the Choose Components part of the installation process.
Make the file executable and then execute with sudo. The installation requires the user to accept EULA, to do this automatically, pass the –accept flag to the installer script.
Multiple versions of PhoXi Control can be installed on one computer. This is achieved by choosing different installation directories during the installation. The process is as follows:
PhoXi Control path environment variable is set to the latest installed version of PhoXi Control, not the most recent PhoXi Control version (Example: User installs PhoXi Control 1.16 and then installs PhoXi Control 1.12). This may affect access to certain features only available in the newest release and are dependent on the path defined in the environment variable.
By default, PhoXi Control starts automatically after the operating system is started. Users can change the default application behavior by setting up specific environment variables or by command line parameters.
PhoXi Control can be started with the following command line parameters:
-minimised
PhoXi Control will be started minimized.
-lock
Used to lock the application against unauthorized use. The application will ask you to set up a password and then to restart. Users are prompted to enter a password every time they start the application. The API can connect to the device only after the password is entered.
-unlock
Removing the authorization request after the application startup. The application prompts you to enter the password and then restarts. This means PhoXi Control can be used without authorization.
-kill
Any instance of PhoXi Control will be switched off.
-forceRun
Used together with -kill. While -kill alone stops all running instances of PhoXi Control, additional argument -forceRun ensures that a new instance of PhoXi Control will be started as next.
The initial window of the application is called Network Discovery. It displays a list of all the devices available on the network. A new connection to the device opens a new Device window. Device windows can be organized by dragging the window title. The application minimizes itself into 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.
The version of the PhoXi Control is displayed in the title bar of the GUI window.
This option opens a directory containing folders with marker patterns and their metadata.
Marker patterns are used for changing the coordinate space and device calibration (multiple devices together, hand-eye calibration, calibration with an external 2D camera)
Marker patterns come in 5 sizes that are intended for different scanning distances. The applicable scanning distances for each pattern are stated in the name of the corresponding pdf file.
This option opens a directory containing folders with marker patterns and their metadata.
Marker patterns are used for changing the coordinate space and device calibration (multiple devices together, hand-eye calibration, calibration with an external 2D camera)
Marker patterns come in 5 sizes that are intended for different scanning distances. The applicable scanning distances for each pattern are stated in the name of the corresponding pdf file.
The application remembers your preferences for showing UI components. Use this function to reset PhoXi Control to the default layout. Useful mainly when switching between monitors with different DPI and resolutions.
The Network Discovery window lists all available devices on the network. After the application starts, please wait a moment until all devices are found, or click on the refresh button in the upper left corner above the displayed devices.
If your device is not listed, please make sure that it is turned on and connected to the network. After a short time, the device will appear on the list. The time required to discover a newly powered device should be under 3 minutes. The time required to discover the device after it was disconnected or the connection was lost should be under 45 seconds.
If no device is shown on your list, please check your network configuration. See the chapter Configuring Device Network Settings for more information.
Selecting a device will display its details such as Name, Description, Configuration, Status, and ID, as well as its network settings, firmware version and model.
Configuration shows the hardware specifications of the given device. Possible tags you can see in the Configuration field are:
Alpha - represents the Photoneo Alpha 3D Scanner
Color - represents the devices with built in RGB camera
Red - represents the color of the laser
Blue - represents the color of the laser
LC2 - represents the Laser Class 2 (used with Photoneo Scanner Gen 2 and MotionCam-3D)
LC3 - represents the Laser Class 3 (used with Photoneo Scanner Gen 2 and MotionCam-3D)
GigE-V - represents the possibility to connect to the device through GigE-V
Interlock - represents the activation of the interlock feature
#MP - represents the maximal supported resolution of the device
Through API, this information can be found under the name “features”. Configuration and features are only available for PhoXi Control version 1.16.2 and higher, as well as firmware version 1.16.2 and higher.
It is possible to “Pin Device” by right-clicking a device in the list. Pinned device will always show on the top of the list. It is also possible to pin a File Camera.
Not all information is available for File Cameras or for devices with an older firmware version. For example, a comment field in the network discovery allows the user to describe the device with a custom message (up to 1024 characters). This is possible only for devices with firmware versions higher than 1.9.0. A comment can be added by right-clicking the Comment and selecting Edit comment.
The status field has three different “Occupied” states :
Occupied by me (via PhoXi Control): Indicated simply as “Occupied” (means the user is already connected)
Occupied by someone else (via PhoXi Control): Displayed as “Occupied” with a red box showing the IP address
Occupied via GigE Vision interface: Displayed as “Occupied” with a red box labeled “GigE Vision” (and the IP address if provided by the device).
IPv4 and IPv6 address rows contain dynamic interface labels. The labels dynamically change color: red for non-routable addresses, orange for sub-1Gbps interface speed, and blue for normal operation (1Gbps).
The following list represents all the possible device states. It is only possible to connect to a device in Ready state.
Not started
The device has just been plugged in or was restarted. After a few seconds, the status will change to Starting.
Starting
The device is starting its operating application. After a few moments, the status will change to Ready.
Ready
The device is ready for a new connection.
Occupied
The device appears as occupied after the connection is established. Only one connection at a time is permitted. It is not possible to connect to an occupied device.
Terminating
The device is being terminated after the user disconnects from the device. After a few moments, the status will change to Starting and Ready.
This list can also be found in the lower left corner of the Network Discovery window.
To connect to a device, simply double-click on the device name or select it and click Connect. It usually takes about 2-5 seconds for the device to connect; however, based on the internal state of the device, it can take up to 1 minute. Once the device is connected, a new Device window will open and its status in Network Discovery will change from Ready to Occupied. Therefore, if you share a device with other users, make sure you disconnect from it after you finish using it.
Please ensure that you are using a wired network connection to the device. WIFI connections are not recommended due to lower speed and reliability.
Connection to the device via API causes the GUI to open the Device window similar to when connecting via the GUI. When you connect to the device through the GUI, it is possible to work with the device through API.
Every 3D scan captured by PhoXi 3D Scanner or MotionCam-3D can be saved into a Photoneo RAW ( *.praw) file. The main advantage of this native format is that it contains all the information about the scanning configuration and additional information about the device. All other formats can be exported from *.praw files.
Additionally, dynamic scans taken by MotionCam-3D can be saved into a Photoneo MotionCam-3D RAW (*.pmraw) file. This format is capable of creating a file camera consisting of a single file but containing many scans.
Single or multiple *.praw files can be loaded into PhoXi Control either by using the menu or by dragging & dropping the files anywhere on the GUI. Opening N *.praw files will create a new virtual device called File Camera. This virtual device behaves in a very similar way to a regular device. In case of drag-and-dropping multiple *.praw files or opening a *.pmraw file, you can use “Previous frame” and “Next frame” buttons, which replace the “Trigger” button, to cycle through the frames.
While looking at the last scan, you can press Right Arrow to seamlessly move to the first scan. Respectively, you can move to the last scan by pressing Left Arrow, while looking at the first scan.
PhoXi Control already contains 2 example file cameras, which contain 1 or more captured frames and can be used for testing purposes.
Note
The scanning parameters for File Camera are read-only, as these scans have already been taken and processed.
Network Discovery window offers specific options for File Cameras when right-click is used or by using a keyboard shortcut:
Add as internal file camera
Internal File Camera remains in Network Discovery even after you restart the PhoXi Control application. Otherwise, the File Camera is present only until the end of the 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 the filesystem (Shift + Delete keys)
This option will remove the File Camera from the list of devices and also delete underlying files from the disk.
Setting the order of scans in an internal file camera
After creating an internal file camera using a group of scans, it is possible to define the order of the loaded scans using an order.cache file in the directory of the internal file camera which can be found at:
Create a file order.cache and open it in a text editor. The order of the scans being loaded in the internal file camera can be defined as follows:
Defining the order by name (alphabetical order)
Line 1: order_by_name
Defining the order by the last modified date/time
Line 1: order_by_modified_time custom
Defining a custom order (files not mentioned will be skipped)
Line 1: scan_1.praw
Line 2: scan_14.praw
Note
The file camera needs to be set to an Internal File Camera in order to order.cache config file to affect the order. Scans loaded to PhoXi Control by Menu → Open File Camera or by dragging the scans will be normally loaded in the order they were selected in their original directory.
The scanning settings are applicable to the device depending on its FW version. A *.praw file contains complete data about the scan, including scanning settings. It needs to be noted that older versions of PhoXi Control might not display all parameters of devices with newer FW.
To ensure the smooth operation of the device with your computer, make sure you follow the guidelines for hardware setup and network connection described in the next sections. Before you connect your device to any network, make sure you know how the network is set up or have the administrator of your network do it for you.
Connect the network cable to the device first, then connect the power cable.
Always use cables of a Cat5e category or higher that support Gigabit Ethernet or 10 Gigabit Ethernet standards. Do not use cables of the Cat5 category as their speed is usually 10 - 100 Mbps, which is too low to obtain a good scanning performance. To distinguish these two types of cables you can try
We recommend connecting Photoneo devices directly to a computer or a local network, ideally keeping them air-gapped.
Photoneo devices use Zeroconf technology for service discovery. However, this technology is generally not routable outside of local sub-networks. Therefore, the supported network topologies are
Direct connection between the user’s PC and Photoneo 3D Sensor.
Star topology with one or more user PCs and one or more Photoneo 3D Sensors connected to a switch, all on a single local subnet. The switch has to be able to run at 1 Gbps or more.
If you connect your device to your network via a router, it will not be accessible since routers usually connect two different subnets. Zeroconf technology is routable only in the same subnet.
If you are not sure how your network works or how to set up an IP address assignment, contact your network administrator.
Photoneo 3D sensors are network devices, therefore, they need a unique IP address so that any other computer on the same network can identify them, and communicate with them. IPv4 addresses usually serve this purpose.
There are three ways the device can obtain an IPv4, and how it can be discovered in the network:
Dynamic IP assignment via DHCP (Dynamic Host Configuration Protocol). Ask your network administrator if you have a DHCP server available on your network.
Dynamic IP assignment via Zeroconf technology (for networks without DHCP). Thanks to Zeroconf technology the device is assigned an IPv4 address automatically and can be discovered on the network with no further input from the user. IPv4 addresses assigned by Zeroconf come from the 169.254.0.0/16 network as described in RFC 3927.
Some Ubuntu systems require a Link-local connection for the correct Zeroconf IP address assignment.
Static IP address assignment. A static IP address has to be set up manually. Ask your network administrator for a valid and available IPv4 address before configuring it. Be careful not to set an IP address outside of the network you are currently in, as this would make the device in the network undiscoverable. Once you set a static IP address for your device, write it down and store it in case you need to use the device in a different network or want to change your network parameters in the future.
Note
Zeroconf network discovery works with Link-local connections on Ubuntu OS. Using Zeroconf without a Link-local connection may result in IPv4 addresses not being assigned correctly. Symptoms include missing IPv4 address in the corresponding field in PhoXi Control and command ipaddrshow<INTERFACE-NAME> not showing 169.254.x.x IPv4 address. Read instructions on how to create a Link-local connection in the section Troubleshooting.
Note
A fixed IPv6 Link-local address is assigned to each device. The address starts with fe80:: and can also be used to connect to the device. IPv6 connection is preferred over IPv4.
The three different IP assignment types are reflected in the PhoXi Control setup. The configuration can be done by clicking the Configure button in the lower part of the Network Discovery window. You can select between DHCP and Static IP. The device restarts after every change in network configuration.
Choosing Static IP changes the window where, IP address, Gateway, Subnet mask, and DNS can be set up. Please note that setting an invalid IP address will make the device undiscoverable on the network, so make sure the IP address is valid and not outside the subnet you are on.
By default, the devices use DHCP for IP assignment. On networks with no DHCP, the IP will be assigned by Zeroconf.
Using Zeroconf technology for service discovery does not rely on any specific PhoXi Control configuration - the IP assignment type can be left blank or set to DHCP. After the device is connected to a network without a DHCP server, it should already be available in PhoXi Control. The only requirement for Zeroconf to work correctly is to have Avahi installed on Linux systems and Bonjour service on Windows systems.
If a device is moved from a network with a static IP address assignment to a network with a dynamic IP address assignment, before the device is disconnected, its IP assignment type should be changed to DHCP.
If it is possible, the device always establishes a connection via IPv6. To prefer an IPv4 connection before an IPv6 connection, set the environment variable:
A device can be added using its IP address in the Menu -> Add device via Address which displays the following dialog. A device added in such a way will carry a different icon and user-defined name DirectConnection-<User-defined>
The Utils button (previously Maintain) is located at the very right-bottom corner of the Network Discovery tab and offers a list of functions to control the device. A device must be selected to use this option.
Warning
Rebooting device disconnects anyone currently using the device.
Maintenance tool is a Photoneo software for validation of Photoneo 3D Sensors based on the acquisition of a marker pattern. It is used to verify device calibration and adjust it if necessary. Find out more in the Maintenance Tool section.
This tool is a command-line application designed for the spatial alignment of multiple Photoneo 3D Sensors. It calculates and applies the spatial transformations to align two or more scanners into a single, shared coordinate system.
For more detailed information, see Appendix 2 - Sensor Alignment Tool.
The device waits for the trigger command to capture a 3D scan.
Use the Trigger / Set and Trigger / Trigger Diagnostics button
The Set and Trigger button automatically temporarily saves changes made in the Device Settings or Structure tabs and triggers a scan.
Trigger Diagnostics takes a special scan that contains the most information, and can take longer to compute. See Diagnostic scan chapter for more information.
Trigger, Set and Trigger and Trigger Diagnostics are 3 settings for the same button. Settings are changed through the dropdown menu accessible through the small arrow next to the button.
Trigger Auto-Maintain is a dedicated button for Autonomous Maintenance. This feature is available only on MotionCam-3D devices shipped after the 26th of May 2025 and on PhoXi 3D Scanner Gen3.
Free run mode
The device performs consecutive scans at maximum speed (if not slowed down by the Maximum FPS setting).
To turn the free run mode on or off, use the button Free run.
When the device is in Free-run mode, you can pause and restart the acquisition with the Pause / Start button.
Photoneo 3D Sensors can also use a hardware trigger to acquire scans. In hardware trigger mode, the scan is triggered by a signal change on a specific GPIO pin. More information can be found in the section Hardware trigger.
You may prevent the device from taking a scan by using the Pause button at any time. Using this function is more intuitive in the API, where a secondary application may prevent the first application from triggering the scan.
Tip
Once the window is open, hit F5 or the Trigger button to trigger a scan.
The Settings Assistant guides you through a step-by-step process to find the ideal settings for the specific scene.
Tip
For a step-by-step visual demonstration, you can watch our video tutorial on how to use this feature here.
You can pick one or multiple dimensions:
1 - Exposure - Adapts to the light conditions, environment, and scanning distance
2 - Material & Object Type - Adapts to object material by adjusting core scanning methods
3 - Exposure Fine Tuning - Refines the light settings around the best option from previous step
4 - Enhance & Clean up - Perfects the scan by increasing the level of detail and decreasing noise
Once you select each of these dimensions, the Settings Assistant initiates an automated process to explore the best parameters within each chosen category.
For each dimension you pick, the Assistant performs the following actions:
Step
Action
Outcome
Automatic Capture
The Assistant automatically captures several frames, each using a different scanning profile relevant to the selected dimension (e.g., 9 different exposure settings).
A gallery of several distinct scans is generated for your review.
Data Reporting
It analyzes each of the frames, reporting the scanning time and the number of points in the resulting point cloud.
You receive comparable data to help you evaluate the trade-offs between speed and number of points for each profile.
Profile Recommendation
Based on its analysis, the Assistant highlights one of the profiles as the recommended best choice.
You get a suggestion, but the final decision remains in your hands.
Custom Profile Creation
Based on your final selection, a new, optimized custom profile can be created and saved.
This delivers a “plug-and-play” experience, providing you with the best possible scanning parameters in just a few minutes.
This systematic process ensures you can quickly fine-tune your scanning setup for optimal quality and performance, tailored precisely to your object and environment.
Use the Assistant button to initialize the Settings Assistant tool.
Settings Assistant for <DeviceSN> will open. The following windows contains two tabs Scan generation and Best scan selection which are switched automatically throughout the process.
Choose one of 4 dimensions (1 - Exposure, 2 - Material & Object Type, 3 - Exposure Fine Tuning, 4 - Enhance & Clean up) or use the default order as represented by the numbers enumerating each of the dimensions starting with the 1 - Exposure (recommended).
Hit the Generate scans button. The tool will automatically capture several scans with different parameters according to the chosen dimension.
Afterwards, a new file camera named <DeviceSN>-<dimension> (in our case PHA-125-Exposure) will be connected.
The Settings Assistant automatically switches to the Best scan selection tab, where you can compare individual scans. Each scan is represented by a button that displays its scanning time and the number of points in the point cloud (taking the selected resolution into account). Scans are sorted based on the total scanning time from shortest to longest. One scan is always designated as the reference scan, and another is marked as Suggested based on a combined rank of the scanning time and the amount of point cloud data it contains. You can cycle through the scans by using the buttons, the blue arrows, or the ← and → arrow keys on your keyboard.
Tip
Hovering over each scan’s button will display its Acquisition, Computation, and Transfer times, as well as any adjusted parameters.
Select the best scan. In the image below, for example, the first scan was suggested but the user chooses the 6th scan.
Provided you have the best scan selected, you can use the Save into profile button to save the current parameters (optional at this point). If you are satisfied with the result, you can opt to exit the Settings Assistant by selecting the Exit button. To continue optimizing the scanning parameters, use the Optimize further button which takes you back to the Scan generation tab.
Once you are back in the Scan generation tab, you can repeat the same process by selecting another dimension.
You can exit the Settings Assistant using the Exit button which closes all the related windows and file cameras. You will be prompted to either save all the generated scans or exit without saving the scans.
Make sure you saved your profile before exiting the Settings Assistant or otherwise the parameters will be lost.
PhoXi Control allows you to save scans both manually and automatically. The automatic saving mode is called recording.
The output can contain:
Point cloud: an organized set of 3D points.
Normals: for each captured 3D point, the normal vector expresses the orientation of the captured surface.
Depth map: the depth data for each pixel.
Texture: grayscale intensity or RGB values for each 3D point.
ColorCameraImage: 2D RGB texture captured by the color camera unit in MotionCam-3D Color and PhoXi 3D Scanner Gen3
Confidence data: the data expressing the estimated noise of the acquired point.
Split RGB Channels: control over production of channel files for Texture and ColorCameraImage.
Information about the device, such as the ID number or calibration data of the image sensor
Information about the 3D scan, e.g. duration, scanning parameters, coordinate system
All these data can be stored only in the native Photoneo RAW formats ( *.praw or *.pmraw). They can be opened later in PhoXi Control as a File Camera and converted to any other supported file format.
Other scan formats (PLY, PTX, TIF) are capable of storing only partial information, usually only point cloud, normals, and texture. The saving options dialog enables the user to choose from output structures saved in each file format.
Firstly, use the saving options dialog to define the destination and file formats in which the acquired scan should be stored. Using *.txt format to save data during recording is not recommended. Afterwards click the Record button to start or stop automatic recording.
When recording is used in free run mode, the disk writing speed may limit the number of stored frames and some frames might be skipped and not stored. This usually happens when multiple file formats are being saved at once or when compression is used to save *.praw files. If this occurs, the status bar in PhoXi Control displays the message “Scans cannot be saved, they are generated faster than the computer can process them. Consider changing saving options.”.
Use the button Recording Options to configure how the 3D scans and corresponding data are saved.
The Folder path and File pattern fields are used by automatic recording. The folder path defines the destination where the scans will be saved. The file pattern defines the name of the files, hash signs will be replaced by a counter starting at the defined value. The image on the right depicts the settings that will save the scan with the name scan_0000. Other possible tags in the File patterns include {file_index}, {device_id}, {frame_id}, {timestamp}, {date_time}, {frame_start_timestamp}, and {frame_start_date_time}. These tags enable dynamic insertion of session-specific variables into filenames. Users can also define the frequency of saved scans by changing the N parameter. Additionally, the number of scans can be limited by the Maximum number of scans parameter. Use the checkboxes on the left to select all the formats in which the scan should be saved during automatic recording. Use the Options buttons on the right to define which data should be saved when using the selected file format.
Tip
Any scan in a *.praw / *.pmraw format can be converted into any other format by loading it into PhoXi Control and choosing a different file format in the saving dialog.
An Explanation of the Confidence map can be found in the 2D Image Tabs section
Using a text file to save data may result in longer saving time, depending on the speed of your SSD or HDD. The same is true when the binary format is not used in the PLY format.
TIF file is one-dimensional, therefore it creates multiple files for each stored component.
Understanding Scanner Outputs - Topology of the 3D Scan
The point cloud acquired by PhoXi 3D Scanners is topologically organized according to the image sensor. An image from the image sensor is called texture. There is one computed 3D point for each pixel in the texture. If any point from the scene is not illuminated by projection (usually because of shadows) the corresponding pixel has no 3D value (its coordinates are [0, 0, 0]) and is called a “zero 3D point”.
For example, the pixel at position [x= 2010, y =350] in the texture is the (2064*350 + 2010) = 724410-th point in the point cloud.
PhoXi Control also allows unorganized point clouds to be saved. In unorganized point clouds, the “zero 3D 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 will need to iterate over the point cloud and find a corresponding pixel in the depth map by comparing the Z value.
Understanding MotionCam-3D Output - Topology of the 3D Scan
On MotionCam-3D the relationship between the number of pixels on the image sensor and the number of points in the point cloud is not 1:1. The ratio depends on the Sampling and Output Topologies.
This tool serves to save scans for diagnostic purposes independently from the client application. The setup allows choosing how often and where the scans are saved, and what information is contained within them. Open the Recording Options and select PRAW format. Then scroll down and you can see the possibility of recording Diagnostic Data.
When the maximum log file size is surpassed, deletion of *.praw files will commence, beginning with the oldest *.praw file. This tool can save:
3D scans
3D scans with diagnostic data
3D scans with full diagnostic data (default, recommended)
2D outputs
2D outputs with diagnostic data
Note
Different diagnostic profiles have different performance impact, resulting in higher processing or transfer time.
This tool can be used to measure the transfer speed between the device and the computer running PhoXi Control. Use the default settings for Size [MB] and Number of attempts in case you don’t suspect any connection issue.
If you suspect there is a slow connection speed, change the parameters Size [MB] and Number of attempts to lower values.
The result of the test is shown as Speed and Latency with their minimal, maximal, and median values. On 1 Gbps networks, the expected speed should be around 100 MB/s with a latency below 6 ms.
Low speeds significantly prolong the overall scanning time. Check if the network cables are of a Cat5e category or higher. Lower-category cables have a speed of around 10 MB/s.
Tip
Besides the ability to use the Test Speed, IPv4, and IPv6 address rows in the Network Discovery tab contain dynamic interface labels. The labels dynamically change color: red for non-routable addresses, orange for sub-1Gbps interface speed, and blue for normal operation (1Gbps and higher).
Clicking the Logout button disconnects PhoXi Control from the currently selected device. Closing PhoXi Control without disconnecting from the device may produce a warning when the next connection is established
This setting is only available for viewing File Cameras. It opens a new window where you can select the index of the *.praw or a specific scan in a *.pmraw file that will be displayed after the next scan is triggered. The file is selected based on the order of the files in the directory (index starts with 0).
Scanning profiles allow users to easily change multiple scanning parameters at once. There are several profiles pre-configured with different scanning parameters for different uses. Factory profiles are not editable, and cannot be deleted or renamed, however, it is possible to clone them and edit the cloned profile. A different set of factory profiles is available for MotionCam-3D and PhoXi 3D Scanner. It is also possible to define custom profiles.
Use the cog button to enter the advanced configuration.
Select - switch to the chosen profile.
Save current settings - save your current settings in a new profile.
Duplicate - create a new duplicate profile from your selected profile.
Delete - delete user-created profile.
Rename - rename the user-created profile.
Mark as startup profile - the device will be started with this user profile.
Reset to factory settings - resets settings to factory default.
Export to GigEV UserSet - Export a selected user profile as a GigEV UserSet
Export - save a user profile into the *.phop file.
Export all - saves all user profiles into a *.phop file.
Import - imports a user profile from a *.phop file.
Use the button and create a new profile from the existing one, which is closest to your use case. You might want to mark it as a startup profile as well.
Modify the desired parameters to your needs.
Use the Set and Store button below to store the settings in your custom-made profile permanently.
The set of scanning parameters available depends on the version of the firmware installed on the device. This manual is based on firmware version 1.16.5.
The scanning process consists of three phases: capturing (or acquisition), processing (computation), and transfer.
Scanning parameters are divided into several groups. These groups differ depending on the device as shown below.
General Settings - settings that control the operating mode of PhoXi 3D Scanner
Capturing Settings - these options change exposure times and methods of projecting light patterns.
Color Settings* - settings for 2D RGB camera unit.
Processing Settings - these options affect the computation of the point cloud and allow the setting of filtering criteria such as the region of interest.
Coordinate Settings - defines the coordinate space for the point cloud.
General Settings - settings that control the operating mode of MotionCam-3D (camera or scanner mode)
Color Settings* - settings for 2D RGB camera unit
Camera Mode - settings for acquisition in camera mode
Scanner Mode - settings for acquisition in scanner mode
Processing Settings - point cloud computation and filtering (ROI)
Coordinate Settings - define the coordinate space for the point cloud
*only with the MotionCam-3D Color
The total scanning time is the sum of the time 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 the Scanning Guide - Parameters at the end of this User Manual.
Output structure lets you choose what kind of data will be retrieved from the device. Any changes to the output structure will affect the transfer stage. The read-out 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 the coordinates X, Y, and Z in the point cloud coordinate space (see Coordinate settings). The point cloud has a topology that depends on the device in use. On PhoXi 3D Scanners each point in the point cloud corresponds to the pixel on the image sensor.
On MotionCam-3D the points are organized in superpixel topology - 2 or 4 3D points per one superpixel in irregular patterns or can be interpolated into a grid topology that resembles that of the scanner. 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 light that hits the surface of the object). The DepthMap is, therefore, always in the camera coordinate system and corresponds to the 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 texture is either in grayscale (in the red spectrum - the source of the illumination is either LED diode or laser projection) or Color captured by the RGB camera unit on MotionCam-3D Color and PhoXi 3D Scanner Gen3 (source of the illumination is either ambient light or internal white LED). The texture is also used to color the 3D point cloud.
ConfidenceMap
For each measured 3D point, the “confidence” value expresses certainty about the accuracy of the point measurements. For example, a confidence value of 0.12 means that the estimated error for a point measurement is 0.12 mm. This value is based on a heuristic method that considers the light conditions for each pixel.
EventMap
EventMap is a 2D output available only on MotionCam-3D. For each measured point, it shows the time when it was captured. The time is in milliseconds and is measured from the beginning of exposure - each point can have a value from 0 up to the total duration of exposure - i.e. 10 ms.
ColorCameraImage
This output is only accessible on the MotionCam-3D Color and PhoXi 3D Scanner Gen3. When set to true, it outputs an image from the RGB camera unit in the resolution specified in the Color Settings in the settings tab.
Note
Adjusting the resolution of the ColorCameraImage can affect the performance of the MotionCam-3D Color and PhoXi 3D Sensor Gen3.
icon situated next to the search bar at the bottom of the Device Settings Pane allows the user to open the Search history window. This window contains the recent search inputs and can be very helpful when reusing a specific parameter repeatedly.
In the bottom right corner of the window, 3 buttons are available:
- Dock the Search history window
- Delete selected history (DEL key)
- Clear search history
Docking the Search history window will result in the search history being available under the search bar.
This pane displays the output from the device in various views. After the Device window is 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). The view can be switched using the tabs at the bottom. Each view has its own display settings on the right. These settings do not change the data themselves, just their visualization.
In case that OpenGL does not have the required version necessary to visualize 3D point cloud, the following error message will appear. It provides additional information about the current setup for your computer and notifies you that the given version of OpenGL does not meet the requirements to showcase 3D point cloud.
Allows the user to save a *.png screenshot of the 3D Viewer window.
Intensity
Select the data source for coloring the point cloud:
Plain White - all points are white, no shader is applied
Texture - points have color from the photo (Texture) of the scene
Normals - the color is based on point orientation (direction of the normal vector)
Depth - Grayscale - the color of the point is based on its distance from the device. The furthest points are white, the closest points are black. If the coordinate space is set to Marker space and objects are below the marker pattern, negative depth may occur.
Depth - Hue - the color of the point is based on its distance from the device. The farthest points are red, green, and the nearest points are blue. If the coordinate space is set to Marker space and objects are below the marker pattern, negative depth may occur.
Visualization settings
Adjusting the brightness and contrast of the scene.
Contrast - Manually set Min and Max values or use Smart or Full presets to adjust the contrast of the scene. This setting can be used only for the current frame or all frames by checking the box **Apply to every frame.
**Additionally, when using the Depth - Hue intensity visualization, a trio of icons can be used for flexible range display options, enabling clamping, graying out, or hiding values beyond the selected range. :mark:`
The brightness of the scene can be adjusted by applying gamma correction. This is useful for viewing dark objects. It can be adjusted using a slider or setting the value manually. Clicking on Reset resets the value of Gamma to 1.
Show normals as ticks
This checkbox allows the rendering of normal vectors for selected 3D points. The selection of 3D points can be adjusted using the Stride setting and the length of the vectors by the Length setting.
Coordinates
Displaying the coordinate system:
Axis - Renders the axis of the coordinate system.*
Scanning volume - Renders the scanning volume of the respective device
Primary Camera and Projection - Renders the position and field of view of the Primary camera.
Color Camera - Renders the position and field of view of the Color Camera
Current Camera - Renders the position and field of view of the Current Camera
*If after checking the Axis you do not see anything different, try zooming out in your 3D point cloud. Because the coordinate system origin is at the camera, you may not see the arrows representing axes if your current camera position aligns.
Show the transformation matrix from “Point Cloud Space” to the currently chosen “Camera space” (or vice versa). Point Cloud Space is a general term used for the currently chosen Coordinate Space (CameraSpace, MarkerSpace, RobotSpace, CustomSpace or PrimaryCameraSpace).
Shows information about the current frame, such as
Index - serial number of scanned frames in a current session.
Total scans - number of scans made by the device or number of .praw / *.pmraw files in the file camera.
Valid 3D points count - number of the valid 3D points.
Acquisition - duration of the 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.
Host latency - duration of frame post-processing, starting after data are completely received and ends when frame is provided for the API client (GUI related processing and API client side frame consumption not included)
Timestamp - timestamp of the scanned frame in the current session
Received timestamp - timestamp when the frame was received by PhoXi Control
Acquisition Start - Frame Acquisition Start Time, PTP clock synchronized
PTP state - current PTP state
Product name - Photoneo 3D Sensor type.
Product variant - a model of the device.
Serial number - serial number of the device.
Firmware - firmware version of the device.
Device temp - current device temperature.
Marker Dot Status - Marker Dot correction status
Diagnostic frame - information if the frame is diagnostic (true/false)
*File name - File name in case of a file camera
Note
The displayed frame information also depends on the FW version of the device. Above presented frame information is present in FW 1.16.
Given information can also be edited by the user. Right-click on any of the information and click on the Content editor. This then opens a new window called Frame info editor.
In this window the user can choose which information is seen as necessary and which is redundant. The checkmark next to the information represents, whether the information is shown or hidden.
It is also possible to change the order of the information, by holding the order number and moving it elsewhere.
After hitting Apply the information is updated in the Visualization pane.
This tab displays the predicted error of depth measurement for each pixel (corresponding 3D point). Darker areas on this map show parts of the scene that have been scanned with lower error rates, while brighter areas show parts of the scene where errors may have occurred, suggesting that these sections of the scene may be problematic. The Confidence Map serves as a tool for estimating inaccuracy in millimeters. It can be used to find places where the inaccuracy is high and then trim them away using the Max Inaccuracy (mm) setting.
To see the confidence map, it is necessary to turn on the Confidence Map checkbox in the output structure and then trigger a new scan. Set the Maximum value threshold in the right pane to a reasonably small number, e.g. 0.5. Then hover the mouse cursor over the image to see the value of the specific pixel (its corresponding 3D point).
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 on 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 to measure the distance between 3D points by dragging a line between corresponding pixels with the right mouse button.
Event Map displays time information about when each 3D point was acquired. The measurement starts and ends together with the acquisition of 3D data which is achieved by sweeping a laser line over the object and modulating pixels in the camera sensor. Each point in EventMap can only have values ranging from 0 to Exposure time ( ie 0 - 10 ms).
The time information is useful for applications where movement plays a role. MotionCam-3D can scan objects moving at high speeds, however, depending on the speed and direction of the movement, the resulting point cloud can be distorted. Combining the information from the EventMap with information about the speed and direction of the object is necessary to reconstruct the point cloud.
ColorCameraImage
After setting ColorCameraImage to true, a Color 2D image tab will appear at the bottom of the Visualisation pane. It is the native RGB image from the RGB camera unit in the MotionCam-3D Color and PhoXi 3D Scanner Gen3. Its resolution can be altered in Color Settings.
The top part of the 2D image tabs visualization controls and the Frame Information are the same as in the 3D viewer visualization controls.
Overlays
Visible 3D points
Creates an overlay of visible 3D points on the currently opened 2D image tab
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
The distance between two points. You can measure the distance between two points by dragging a line between them with the right mouse button. The computation takes into consideration the position of the points in 3D space.
Image size
Image size in pixels
Debug Information
When hovering over a specific pixel with a mouse cursor, the debug information pane displays values of all of the available output maps for the current pixel.
Controls
Button:Set default view
Resets the image position and zoom to default values.
Button:Restore default settings
Restores the default settings for Intensity settings.
Left mouse button drag
Tilts the scene.
Mouse wheel
Zooms in/out.
Right mouse button drag
Draws a line between two pixels and computes the distance between the two corresponding 3D points.
The Measuring tool allows you to quickly measure the distance between two selected points. Using Right mouse button drag, you can draw a line between two pixels, and the tool will compute the distance between the corresponding 3D points. Once placed, the points can be repositioned by clicking and dragging them with the left mouse button to a desired location, as long as it corresponds to a valid 3D point.
After selecting the two points for distance calculation, you can move them around in all 2D Image Tabs, except the 3D Viewer tab. The 3D Viewer tab allows you to visualize the placement of the points in XYZ, but adjustments must be made in one of the 2D Image Tabs.
This feature allows the user to observe more device windows while working with multiple devices and/or file cameras by opening more undocked tabs side by side.
The Undock Device Tabs feature can be activated after clicking the Undock Device Tabs icon at the right top corner of the PhoXi Control GUI.
This feature allows the user to undock a device tab from the main PhoXi Control base tab and position it anywhere on the screen. In the case shown below, all 4 tabs can be moved separately and the user can adjust both the width and height of the window.
Example of 4 simultaneously observed undocked tabs.
Additionally, the user can also dock the individual tabs in the PhoXi Control base tab and use it in a split-screen view. In another case shown below, all 3 tabs are docked and the user can adjust the width of the individual windows.
In the lower part of the Device Window, you can find the Status bar. Status bar is the communication tool of PhoXi Control, where all the info messages, warning messages and error messages will be shown.
Messages have a pre-determined structure:
Type of message
Info - no special color change, no need to change any settings or anything in the scene you are scanning.
Warning - yellow status bar. This might be the warning that you have diagnostic data turned on, which may not be desirable, or that the device is paused while you are trying to trigger a scan. Therefore you may have to change settings.
Error - red status bar. You need to change settings or something in the scene to continue scanning correctly.
(code of message) - code of the message. It is written in brackets.
Message text - Description of the problem.
Here are the most important or most common messages you can see on your Status bar:
Info
Scan triggered for frame [frame number]
Info
Frame [frame number] arrived
Info
Scan saved successfully
Info
Settings set successfully
Warning
Unpause the device before triggering a scan.
Warning
Unpause the device to record.
Warning
Frame [frame number] arrived with the diagnostic data
Warning
Saving - with the diagnostic data…
Warning
Scan saved successfully - with the diagnostic data
Warning
Scans cannot be saved, they are generated faster than the computer can process them. Consider changing recording options.
Error
Failed to set settings!
Error
Error while saving scan for frame: [frame number]!
Supported on MotionCam-3D Color (shipped after 05-26-2025) and PhoXi 3D Scanner Gen3
No markers or marker board required
GUI, API, GigE
Using one or combination of the tools is recommended:
During system setup, before starting operations
If the device experienced extensive vibration or physical shock (transport, robot collision)
After major environmental changes, like a relocation or temperature/humidity fluctuation
As a part of a precision-focused workflow, where you might want to run a quick check regularly (recommended once or twice a year, or during general system maintenance sessions)
Maintenance tool is a Photoneo software for validation of Photoneo 3D Sensors based on the acquisition of a marker pattern. It is used to verify device calibration and adjust it if necessary.
Maintenance tool requires a marker pattern (A2, A3, A4, A5, S30) printed on a flat, high-quality surface (e.g. float, tempered and heat strengthened glass, PCB board, Komatex, Metal board - Aluminium/steel, etc.). The default scaling (100%) of the marker pattern is recommended. Using incorrectly scaled marker patterns may lead to inconclusive or incorrect calibration patches.
The device should be running for at least 45 minutes before maintenance.
In the Network Discovery window, select the desired camera (do not connect) and click Utils (previously Maintain) in the lower right corner. Then, choose Maintenance Tool to automatically connect and open the Device Window and Maintenance tool console.
The Autonomous Maintenance Reset restores the device’s calibration to its factory state without impacting the user profiles or other settings.
The marker pattern should be statically placed in front of the device (for example not held in hand). Place the pattern in optimal focus distance (See Marker Pattern chapter to see which marker pattern size is recommended for your camera, as well as ideal distance for the given marker pattern).
Note
It is recommended to change the user profile to DEFAULT and use command adjustPower, to automatically set the optimal scanning parameters.
To trigger a scan, either use the command trigger, or press t, and then ENTER key on your keyboard in the console after connecting to the camera. Do not trigger a scan in Device Window - information from that scan will not be sent to the Maintenance tool.
It is necessary to cover as much of Field of View (FOV) as possible. Otherwise it will not be possible to continue maintenance of the device.
The image above shows the most optimal placement of the marker pattern for the scans. However, the exact placement or the number of layers depends on the size of the marker pattern chosen by the user, as it is necessary to cover as much of the Field of View (FOV) as possible. If the marker pattern is larger, fewer scans are necessary to cover the FOV.
Starting with PhoXi Control 1.17.0, the Maintenance Tool supports multiple identical validation targets present in the scene at the same time. You can place several copies of the same marker pattern into the scanner’s field of view. The tool will automatically recognize and use all the recognized patterns. This helps to reduce the number of frames needed. Support for multiple identical patterns is enabled by default.
After the acquisition is done, enter the command analyze. The analysis results in one of the following options:
Calibration patch is available. Please continue with uploading the patch (via command patch)
Calibration patch is available. It is strongly recommended to continue with uploading the patch (via command patch)
The MaintenanceTool is unable to fix the calibration, please contact the support.
Scans of pattern are not well distributed and do not cover scanning area homogeneously. Please, add scan(s) of the validation target to improve the scanning volume coverage.
Scans of the pattern do not sufficiently cover the projection range. Please, add scan(s) of the validation target to improve the projection range coverage.
If the marker pattern is too small for the size of the device, during the command analyze it will show a histogram of coverage.
After patching the calibration, exit the Maintenance tool using the command exit. If you also wish to disconnect from the camera, use the command exitdisconnect.
If it is necessary, it is possible to revert any calibration of the camera back to its original factory settings using the command restore.
Maintenance tool is also available to use through API.
Marker Dot Correction is a Photoneo feature used to maintain a point cloud from a 3D Sensor at a “fixed position”, with respect to marker dots permanently installed in the scene.
Marker Dot Correction can be controlled in the GUI (Processing Settings → Marker Dot Correction) or using the PhoXi API as demonstrated in the MarkerDotCorrectionExample.cpp
The Reference Recording mode saves the position of the marker dots. Reference Recording is stored even after disconnecting from the device or turning the device off. Only factory reset or failed attempt to record a new Reference Recording erases the reference.
After the device contains the reference recording, automatic mode can be used which automatically recognizes the marker dots in every scan and performs an adjustment so the point cloud remains fixed at the learned position. This operation is performed by the FW of the device. (Computation time: <150ms)
If the Marker Dots are not visible the last calculated correction is applied.
If the correction application was a success, the result is stored in the scan’s metadata. If the correction exceeds acceptable configurable thresholds, the device will send out an alert. Use the Maintenance Tool to verify the performance of the device. The Maintenance Tool patch invalidates the last Reference Recording.
For diagnostic purposes, a small log is generated and stored on the device. The logs are being overwritten and can be retrieved via the LogDownloader utility and sent to Photoneo for analysis.
For time-sensitive applications, switching between active and passive mode is recommended (for example, switching to Active mode for one scan in every 1000 scans in Passive mode). The passive mode does not check the positions of the marker dots in the scene. It only applies the last known correction.
The change between the initially recorded and recognized position of the marker dots is defined in millimeters and exceeding a definable threshold triggers a warning. See more in the Marker Dot Shift Threshold.
Marker Dot Correction has Max Marker Shift (<double>) - maximal permitted pixel shift of the markers (with regards to Reference Recording). This prevents the correction application in case of dots being moved by accident. It is not recommended to raise this value above 25 pixels.
Correct Marker Dot Placement and Conditions for Recognition
The Marker Dots can be shown in the scene by placing them in the scene or mounting them. Each Dot has 4 mounting holes in each of the corners.
The Minimum number of dots in the scene is 4.
The minimal distance between the leftmost and rightmost Dot should be at least half of the calibration volume (half of the angular range covered by the projection)
The Marker Dots should not be clustered in one place. PhoXi Control will warn the user about the incorrect placement of the Marker Dots.
Marker Dots help the device to calibrate its position during the process of recording scans. The marker dots should not be placed in a collinear position - in a single line in space (the distance from the device [depth] is not considered when checking the collinearity of the Marker Dots). The collinearity of the dots is checked during Active mode, not during Reference Recording.
A new Reference Recording has to be acquired in case of a change (e.g. position of the device, dots have been repositioned)
Marker Dots Correction can be used via PhoXi API using the MarkerDotCorrectionExample.cpp. (See the API Examples section).
Autonomous Maintenance is a feature tailored for the MotionCam-3D Color (shipped after 26th of May 2025) and for PhoXi 3D Scanner Gen3. It maintains long-term measurement accuracy without manual intervention, external markers, or production stops. This feature leverages the hardware enhancements to monitor the calibration condition, identifying and correcting alignment issues over time.
MotionCam-3D Color or PhoXi 3D Scanner Gen3 with firmware version 1.16 or higher (shipped after 26th of May 2025).
Static scene (only during calibration checks).
The device should be running for at least 45 minutes before maintenance.
For firmware versions prior to 1.17, the device temperature must be within ±10 degrees Celsius of its internal calibration temperature, which is approximately 35°C. You can verify the device’s temperature in the Frame Information. If this condition is not met, an error message will be displayed. As of firmware version 1.17, this temperature constraint has been removed.
Maintenance mode can be used to check and improve consistency of the device calibration.
Off: Maintenance is inactive.
Auto: Autonomous maintenance mode acquires additional patterns to check calibration consistency, thus it takes longer time. If possible, it adjusts certain calibration parameters to improve the consistency of the device calibration. The procedure requires a static and well scannable scene. This mode is available only on devices with Color camera manufactured or serviced with firmware version 1.15.0 or higher and shipped after May 2025. If your device was produced earlier, it does not support this feature.
Using Auto-Maintenance via PhoXi Control GUI
Use parameters to enable the Auto-Maintenance mode
Use the predefined Trigger Auto-Maintain trigger option
The status messages are displayed in the very bottom part of the PhoXi Control.
Autonomous Maintenance was successfully performed
Autonomous Maintenance failed (for example, the scene moved)
Usually, this is caused because the device or the scene has moved during the acquisition, the scene does not contain enough 3D data or the 3D parameters are set incorrectly (e.g. under/over exposure. If changing parameters or changing setting does not help, it is recommended to perform a factory reset. If the issue persists, contact our Help Center.
Autonomous Maintenance can be used also via PhoXi API as demonstrated in the AutonomousMaintenanceExample.cpp. (See the API Examples section).
PhoXi API provides the building blocks necessary for developing your custom C++ or C# application for working with Photoneo devices. All API functionalities are provided directly by the PhoXi Control application, therefore, PhoXi Control has to be always running for your custom application to work with the device.
Starting with PhoXi Control version 1.17.0, we also offer the PhoXi Python API. Documentation for the Python API is maintained separately in the PhoXi Python API section of this Knowledge Base.
The following guide focuses on C++ and C# integrations. It shows how to use the API in several examples. You may start your development based on one of the examples and modify it to suit your specific needs. Microsoft Visual Studio 2015 and CMake are used to demonstrate how to run the API 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:
ProgramFiles/Photoneo/PhoXiControl-1.16.x/API
On Linux OS, the path to the API directory is usually:
API examples contain source codes together with build instructions (CMake) to bootstrap the development of your custom application based on the PhoXi API.
The most extensive source code is the FullAPIexample, which contains all functionalities provided by the API for the PhoXi 3D Scanner. Settings that are specific for MotionCam-3D are showcased in the MotionCamChangeSettings. For better readability, specific functionalities are provided in the form of additional examples. All examples are located in corresponding folders in the application installation directory in API/examples/CPP or API/examples/C_Sharp.
The overview of all examples is laid out in the following table.
Example name
C++
C#
You will learn how to
ApplyCustomProjection
✓
Apply transformation from camera space to custom space of the device.
Reproject the depth map into this custom space.
Save the reprojected depth map.
AutonomousMaintenance
✓
✓
Check and improve consistency of the device calibration..
Calibrate the device to work with an external 2D camera.
Obtain a depth map aligned from the point of view of the external camera.
Align a color texture from an external camera with the point cloud.
GetISCalibParams
✓
Obtain image sensor calibration parameters.
GetProfiles
✓
Use profiles.
Get the profile that is currently used.
Set the profile that is to be used.
Import and export profiles.
GetTemperatures
✓
Get temperatures of the projection unit control board and of the laser diode.
JointMarkerSpace
✓
Prerequisites: 2 Photoneo devices, marker pattern
Align point cloud of two sensors in the same coordinate space
MarkerDotCorrection
✓
Make a marker dot reference scan.
Apply the marker dot correction onto a test scan.
Monitor displacements of the recognized marker dots.
MaintenanceCommands
✓
✓
Find devices available on the network.
Use maintenance functionality of the PhoXiFactory such as reboot, shutdown, and factory reset of the device.
MinimalOpenCV
✓
Use the OpenCV library in your project.
Convert the scan into OpenCV format.
MinimalPcl
✓
Use PointCloud Library in your project.
Convert the scan into PCL format.
MotionCamChangeSettings
✓
✓
Retrieve and set settings for MotionCam-3D.
Best practice to disconnect from the device.
MovementCompensation
✓
How to compensate for the motion distortion of the point cloud if the frame was acquired by a MotionCam-3D in the Camera mode, and the velocity vector of the object is known.
PointCloudCalculation
✓
✓
Calculate the point cloud using a Reprojection map.
PTPTime
✓
✓
Get the start acquisition time from the received frame
Get the start acquisition time from the received frame
Check if time is valid
Print time in desired format
Calculate duration between two time points with usage of standard std::chrono function
ReadPointCloud
✓
Connect to a device from a list of devices connected to the network by requesting its ID.
Work with the acquired data and save it to a specific data structure.
Save scans into different file formats.
Recording
✓
✓
Start and stop recording
Check if recording is running
Setup recording container for recording into desired (supported) format
Setup and enable diagnostic recording
ReprojectionToExternalCamera
✓
Calculate external camera parameters to reproject depth map
Set up an on-device reprojection feature on the main device.
RotatedCalibration
✓
Obtain transformation from marker space to camera space.
Apply a custom transformation matrix before triggering a scan.
TwoScanners
✓
Connect to multiple devices and trigger scans.
TwoScannersMultithread
✓
✓
Connect to multiple devices and trigger scans using multiple threads.
WinForms
✓
Set up your C# project independent from CMake,
use WinForms in your project.
Full API Example
✓
✓
Find devices available on the network.
Various methods to connect to the device.
Obtain details about the current state of the device and its capabilities.
Capture the scene using free run and manual mode, and obtain all available output formats.
Change the scanning settings and specify desired output formats.
To run the examples on the Windows operating system you will need CMake and Microsoft Visual Studio:
Copy the content of any of the directories, e.g. 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:
Choose the source and destination directory.
Click the Configure button, specify VisualStudio142015Win64 or newer as the generator for the project, and confirm with the Finish button. Supported toolsets are v120 and v140 ( also compatible with v141 and v142).
Wait until the configuration is completed, then click the :guilabel:`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→StartDebugging)
While the example is running, switch back to the PhoXi Control application - every frame captured by the camera is displayed in the Viewer pane.
When multiple versions of PhoXi Control are installed on one computer, the exact path to the PhoXi Control installation directory has to be specified in the find_package(PhoXi) command in the project’s CMakeList.txt file, e.g.:
PhoXi API creates a PhotoneoLogFiles folder in the current project directory. To change the directory where this folder should be created please use the environment variable PHO_LOG_FILES_DIR.
Examples:
Absolute path:
PHO_LOG_FILES_DIR=C:\\my_logs
All logs from the client application will be saved in C:\my_logs\PhotoneoLogFiles
Relative path:
PHO_LOG_FILES_DIR=my_app_logs
Client application that runs from folder C:\\my_appwillcreatelogsinC:\\my_app\\my_app_logs\\PhotoneoLogFiles
The quality of the scan depends on a number of different factors. The devices provide a variety of settings that help to perform an optimal scan. Before you decide to change the scanning settings, try to rearrange the scene to ensure the best conditions for scanning. Changing the position of the device with regard to the scene can also make the results of the scan better.
Distance: Closer objects have a better spatial resolution and generally have less noise.
Material albedo (reflectivity): Material with a higher albedo provides a better signal-to-noise ratio. Albedo is defined as a measure of the material’s reflectivity or the degree to which the material will reflect the incoming radiation. The higher the albedo, the more radiation the material reflects from its surface. Generally, brightly colored materials have a higher albedo than darker colored ones, but color alone is not the most reliable indicator of albedo, because radiation has many components outside the visible spectrum.
Strong ambient light: Indoor ambient light generally does not influence the scan very much. However, very strong light such as direct sunlight might be a problem, especially when scanning outdoors. Try to remove all direct sunlight, e.g. by closing window blinds or by moving the installation to a different place. Additionally, Ambient Light Suppression can be used with specific Photoneo 3D Sensors.
Reflections: Non-glossy, matte materials are typically scanned with high-quality results. Even semi-glossy objects are scanned with almost optimal quality. However, glossy, shiny, smooth-sanded, or polished objects often produce specular (mirror-like) reflections - the projected light is reflected out of the sight of the camera. These reflections can significantly lower the scan quality in the corresponding parts of the scan. Additionally, this reflected light can also be reflected onto other parts of the scene. In such cases when the parts are illuminated by reflections from other parts, these secondary “interreflections” can interfere with regular reflections and produce “ghost artifacts”. Metal parts with a high-gloss (or mirror-like) finish are particularly difficult to scan.
Note
A rule of thumb - Take a flat piece of the material you wish to scan and try to look into it as you would into a mirror. If you are able to recognize the shape of your head in the reflection, the material is glossy. In scenes containing such objects, some of them may not be scanned optimally.
When scanning glossy objects, find a position where the light from the projection unit does not illuminate other objects in the scene as this causes interreflections.
Transparent objects: Transparent materials such as glass, ice, or water can be scanned using MotionCam-3D with Firmware version 1.14 or higher using the pre-defined profiles for transparent objects..Otherwise, remove such materials from the scene to avoid artifacts. It is possible to scan objects wrapped in a thin layer of plastic, however, there is a risk they will increase the glossiness of the object and generate more noise in the scan.
Scanning through a flat glass is possible as long as the glass does not cause reflection - the angle between the projection unit and the glass plate should be close to a right angle.
Translucent objects: It is possible to scan semi-translucent objects to a certain extent, however, the scattering of light inside the material may reduce the accuracy of the scan of the object’s surface. Materials with a high degree of translucency (near transparent) cannot be scanned.
First, do a quick visual check of the scan in the PhoXi Control application. Switch to the 3D Viewer 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 Confidence Map. This tab displays the estimated deviation of the measured distance. Darker map areas have been scanned with lower error rates, while brighter areas show parts of the scene in which the error rate might be higher, indicating that these sections may be problematic.
Before using any of the devices, it is useful to become familiar with the basics of structured light projection. Please ask your sales representative for more detailed materials and webinars on this topic.
The scanning process consists of three phases:
Capturing (or acquisition)
Processing (computation)
Transfer
Scanning parameters cover the 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 settings for changing the coordinate system of the point cloud.
MotionCam-3D can operate in 3 modes controlled by this setting.
Camera mode - intended for dynamic scenes and moving objects.
Scanner mode - intended to capture static scenes at high quality.
2D - intended to capture textures only.
Laser Power
0 - 4095
Controls the intensity of the projected light. By default, it is set to the highest possible value. Decrease the value in case of overexposure.
Note: The ‘Laser Power’ setting, adjustable from 0 to 4095, controls the relative output of the laser. Note that the actual power output can vary between individual devices, even when set to the same ‘Laser Power’ value.
LED Power
0 - 4095
Enables to decrease the LED light intensity used to capture texture. Useful for cases when the texture is used for extracting additional information and is experiencing overexposure.
Maximum FPS
0 - unlimited
Useful for limiting FPS in freerun mode. If you want to allow scan every 10 seconds, set Maximum FPS to 0.1.
Hardware Trigger
true/false
Usually used when two or more devices need to be synchronized.
When MotionCam-3D is in hardware trigger mode and a scan is triggered, the acquisition will start after a specified edge of the signal is detected on the trigger input pin. MotionCam-3D can also signalize to other devices that it is acquiring by keeping the trigger output signal in the high state.
Hardware Trigger Signal
Falling
Rising
Both
Specifies what type of signal is used to trigger MotionCam-3D.
Maintenance Mode
Off
Auto
Off - maintenance mode is turned off
Auto - used to check and improve consistency of the device calibration by capturing a static scene. Available only on MotionCam-3D Color (shipped after the 26th of May 2025). To find out more, see the Autonomous Maintenance section.
Projection Offset
(Left/Right)
0 - 512
This parameter narrows the area covered by the projection, shortens the shutter window, and thus limits the ROI of the device.
It determines the number of projection columns that are cut off from the left/right side of the projection. The total width of the projection is 512 columns.
It is useful for cases where the surroundings of the scanned object interfere with the scan or are unnecessary for further use of the point cloud.
Additionally, the sensor’s shutter window length is adjusted to match the narrowed projection, allowing less ambient light to enter the sensor. This parameter can help in scenes with extreme ambient light levels.
ISO
100-360
This value can be adjusted to modify the primary sensor’s sensitivity to light. Higher ISO means the image will be brighter, however, high ISO values introduce noise which can affect the quality of the texture and also of the point cloud. Adjusting this parameter can improve performance on scenes with high levels of ambient light.
Early Transfer
(MotionCam-3D Color only)
Off
ColorCameraImage
Early Transfer is a latency-optimization feature designed for high-performance processing pipelines.
When enabled, the device transmits the selected texture/image data as a separate frame as soon as it becomes available, before the rest of the 3D data is ready.
Off - Disables Early Transfer feature. All acquired data is sent together in a single frame per scan.
ColorCameraImage - Two frames per scan are sent from the device:
First frame: ColorCameraImage (an image from the RGB camera unit in the resolution specified in the Color Settings)
Second frame: Complete 3D data (PointCloud, NormalMap, DepthMap, Texture, ConfidenceMap, ColorCameraImage according to the current selection in Output Structure).
When this option is selected, ColorCameraImage must be enabled in Output Structure. We recommend setting Camera Space = ColorCamera to achieve 1:1 alignment between 3D data and the ColorCameraImage/Texture without additional processing.
Log Level
Trace
Debug
Info (default value)
Warning
Error
Critical
No Logs
Different levels of logging. High logging level may subtly affect runtime.
Color Settings (MotionCam-3D Color, PhoXi 3D Scanner Gen3)
White Balance
(Color Settings)
Allows users to adjust individual red, green, and blue channels’ presence in the RGB texture and ColorCameraImage. It also contains different custom presets to choose from and can be turned off completely.
ROI
(region-of-interest)
(Color Settings)
ROI settings allow the user to specify a region, an area, of the scan to focus on. This allows the user to disregard anything outside the given specified region, which in turn decreases the size of the scan and makes it possible to transfer, while also keeping higher resolution of the scan.
The settings consist of four numbers:
X min
X max
Y min
Y max
These numbers represent the X and Y coordinates of the start and the end of the ROI.
Note: To take this setting into consideration, you need to turn theROI Modeto “Custom”. Otherwise the coordinates in this setting will not be taken into account.
Note: ROI is also available through API
Exposure
(Color Settings)
0.32 - 100 ms
This setting allows the user to adjust the exposure of the RGB camera unit in the MotionCam-3D Color and PhoXi 3D Scanner Gen3 independently from the 3D data acquisition.
ISO
(Color Settings)
50 - 12800
This value can be adjusted to increase the RGB sensor’s sensitivity to light. Higher ISO means the image will be brighter, however, high ISO values introduce noise which can affect the quality of the RGB data.
Gamma
(Color Settings)
0 - 1000
The brightness of the RGB data can be adjusted by applying gamma correction. It will be applied after hitting Set or Set and Store By altering these settings, data are changed also in the API, while the gamma correction in the Visualisation setting pane only affects the way the data is displayed in the GUI.
Resolution
(Color Settings)
1288 x 730
1932 x 1096
2576 x 1460
3864 x 2192
This setting will not affect the resolution of the 3D data. It only changes the resolution of the ColorCameraImage (Color in the 2D image tab).
If the Camera Space is set to ColorCamera, the depth map resolution is determined by the ColorCameraImage resolution and it is used as Texture.
Remove False Colors
true/false
Solution to address falsely colored points caused by occlusions in the perspective of the color camera unit
ROI Mode
Standard
Extended
Custom
Standard (4:3) [default mode] - Resolution of the primary camera (centered in the middle, same height as the Extended mode)
Extended (16:9) - Resolution of the color camera, full view of the color camera
Custom (ROI) - the region is chosen based on the coordinates set in ROI, in context of the Extended mode (full color image resolution).
Note: ROI Mode is available also through API
Camera Mode (MotionCam-3D, MotionCam-3D Color)
Exposure
10 - 100 ms
Data acquisition time: In the camera mode, the duration of the laser line sweeps across the scanned area.
Resolution
(Read-only)
1120 x 800
1288 x 730
1932 x 1096
2576 x 1460
3864 x 2192
Resolution of the depth map. It is a read-only parameter:
In Camera Mode, determined by the selected Output Topology
Raw: 560 x 800
Irregular: 1120 x 800
Regular: 1120 x 800
Full Grid: 1680 x 1200
Or if the Camera Space is set to ColorCamera, the depth map resolution is determined by the ColorCameraImage (Settings → Color Settings → Resolution) resolution.
Sampling Topology
(Read-only)
Standard
Defines the topology of sensor pixel modulations used for 3D data computation.
Currently, only “Standard” sampling topology is supported.
Output Topology
Raw
Irregular grid
Regular grid
Full grid
Defines the structure of the point cloud.
Raw - points are organized into a checkerboard grid.
Irregular Grid - complements the missing checkerboard grid through interpolation in PhoXi Control.
Regular Grid - shares the same sampling locations as Irregular grid, however, all 3D points of this topology are properly estimated (i.e. no interpolation is involved). This option requires longer transfer time.
Full grid - Computes 3D points on the native sensor resolution (2 Mpix), as in the Scanner mode. Transfer and computation time are impacted. Acquisition is identical to using other Output Topologies in the Camera mode - therefore suitable for scenes in motion. (To find out about a possibility to upgrade devices without this option - manufactured before Nov 2023 - contact our Help Center)
Coding Strategy
Normal
Interreflections
High-frequency
Sparse
Coding strategy changes the shape of the patterns modulated by the camera sensor (MotionCam 3D) with the aim of lowering interreflections in the scene. The coding strategy optimized for Interreflections uses advanced digital coding that enables the repression of some diffuse interreflections.
Interreflections Coding strategy makes the projected light stripes very similar in width, while Normal makes the stripes go from very thick to very thin across the projected patterns.
High-frequency is used to suppress interreflections on shiny objects. Additionally, it is useful for scanning of semi-transparent surfaces.
Sparse Coding strategy uses Photoneo’s unique COMPIS (Computational Image Sensor) and the Parallel Structured Light technology to enhance signal readouts on transparent, translucent, and glossy surfaces. Suitable for static scenes only and is available only on MotionCam-3D (Color) product line, using the Camera mode.
MotionCam-3D - uses a Normal strategy by default. Interreflections Coding Strategy has a lower effect than the Phoxi 3D Scanner.
Texture Source
Laser
Laser (Enhanced)
LED
Color
Determines the way the Texture is acquired.
Laser - is a texture computed from the structured patterns - no additional image is required. Images have speckles (laser noise).
Laser (Enhanced) - the scene is illuminated by the Laser diode flash. No additional image is required. Images might have speckles (laser noise). The projection stripes are suppressed. This option is not available on devices with Powell lens based projector.
LED - will capture an additional image illuminated with the LED flash that offers a speckle-free 2D image.
Color - will capture an additional image illuminated with the white LED flash that offers a speckle-free 2D RGB image
Scanner Mode (MotionCam-3D, MotionCam-3D Color)
Resolution
(Read-only)
1680 x 800
Resolution of the depth map. It is a read-only parameter:
In Scanner Mode: 1680 x 1200
Or if the Camera Space is set to ColorCamera, the depth map resolution is determined by the ColorCameraImage (Settings → Color Settings → Resolution) resolution.
Shutter Multiplier
1 - 50
Increases scanning time and amount of used light by repeating the projection of each pattern.
Shutter Multiplier helps with
Scanning dark objects.
Sharp scanning angle.
Any other condition when the pattern is reflected back only partially.
Setting high values of the Shutter Multiplier can lead to overexposure and cause missing points in the point cloud.
Scan Multiplier
1 - 10
Increases scanning time by repetition and averaging the scanning sequence. Scan Multiplier helps to increase the signal-to-noise ratio and brings higher contrast in situations where a high dynamic range is required and a shutter multiplier leads to overexposure.
Coding Strategy
Normal
Interreflections
High-frequency
Coding strategy changes the shape of the projected light patterns with the aim of lowering interreflections in the scene. The coding strategy optimized for Interreflections uses advanced digital coding that enables the repression of some diffuse interreflections.
Interreflections Coding strategy makes the projected light stripes very similar in width, while Normal makes the stripes go from very thick to very thin across the projected patterns.
High-frequency Coding strategy is suitable for scenes containing reflective surfaces.
MotionCam-3D - uses a Normal strategy by default. Interreflections Coding Strategy has a smaller effect than the Phoxi 3D Scanner.
Coding Quality
Fast
High
Ultra
Determines the number of used patterns and the subpixel accuracy:
Fast - no sub-pixel accuracy.
High - sub-pixel accuracy (default).
Ultra - enhanced sub-pixel accuracy.
This parameter also influences both scanning and processing time. Selection between Ultra and High should be made based on specific scenes. Ultra is usually useful for long-distance scanning with the L or L+ models.
Texture Source
LED
Computed
Computed (Enhanced)
Laser
Laser (Enhanced)
Focus
Color
Determines the way the Texture is acquired.
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).
Computed (Enhanced) - operates like standard Computed option, but applies additional processing to suppress projection stripes. It does not work in 2D Mode and devices with Powell lens based projection unit.
Laser - will trigger an additional image using a laser flash. Use this setting to investigate light conditions in the scene. Images have speckles.
Laser (Enhanced) - operates like standard Laser option, but applies additional processing to suppress projection stripes. It does not work in 2D Mode and devices with Powell lens based projection unit.
Focus - will set the scanned structured light pattern as a texture. This setting is useful for analyzing problems with signal contrast and for finding optimal scanning time. Explore the dark and white areas and compare their values. The higher the contrast value, the higher the scanning quality. But avoid overexposure (value above 4095).
Color - will capture an additional image illuminated with the white LED flash that offers a speckle-free 2D RGB image
Exposure
10 - 40 ms
In scanner mode, the length of exposure of one pattern. (16 patterns + texture by default).
Capturing parameters (PhoXi 3D Scanner, Alpha 3D Scanner)
General Settings (PhoXi 3D Scanner, Alpha 3D Scanner)
Log Level
Trace
Debug
Info (default value)
Warning
Error
Critical
No Logs
Different levels of logging. High logging level may subtly affect runtime.
Capturing Settings (PhoXi 3D Scanner, Alpha 3D Scanner)
Basic / Shutter Multiplier
1 - 50
Increases scanning time and amount of used light by repeating the projection of each pattern.
Shutter Multiplier helps with
Scanning dark objects.
Sharp scanning angle.
Any other condition when the pattern is reflected back only partially.
Setting high values of the Shutter Multiplier can lead to overexposure and cause missing points in the point cloud.
Basic / Scan Multiplier
1 - 50
Increases scanning time by repetition and averaging the scanning sequence.
Scan Multiplier helps to increase the signal-to-noise ratio and brings higher contrast in situations where a high dynamic range is required and a shutter multiplier leads to overexposure.
Basic / Resolution
PhoXi 3D Scanner Gen2
2064 x 1544
1032 x 772
PhoXi 3D Scanner Gen3
2064 x 1544
1854 x 1548
1236 x 1032
1032 x 772
924 x 774
Alpha 3D Scanner
1440 x 1080
This parameter adjusts the resolution of the depth map.
PhoXi 3D Scanner supports high (2064 x 1544) and half (1032 x 772) resolution. Half resolution is achieved by binning pixels.
Benefits of lower resolution:
Significantly shorter acquisition time is needed (with the same scan accuracy as at full resolution.
Faster transfer time due to fewer data.
Basic / Camera Only Mode
true/false
In this mode, the internal camera is used to capture 2D images of the scene. This setting is useful when it is necessary to navigate the Scanner around the scene or to take a quick snapshot to look for changes in the scene.
The captured images can be read as Texture.
The setting does not perform any computations necessary for 3D scanning and therefore has low latency.
Advanced /
Ambient Light Suppression
true/false
Special acquisition method which limits the effect of ambient light. When Ambient Light Suppression is set to True, increase Shutter Multiplier and Single Pattern Exposure. It is recommended to set LED Shutter Multiplier to non-zero value
PhoXi 3D Scanner Gen 1 - ALS Gen 1
Alpha 3D Scanner - ALS Gen 2
PhoXi 3D Scanner Gen 2 (FW 1.2.37 and lower) - ALS Gen 2
PhoXi 3D Scanner Gen 2 (FW 1.10.0 and higher) - ALS Gen 3
Advanced / Coding Strategy
Normal
Interreflections
High-frequency
Coding strategy changes the shape of the projected light patterns (Phoxi 3D Scanner). The coding strategy optimized for Interreflections uses advanced digital coding that enables the repression of some diffuse interreflections.
Interreflections Coding strategy makes the projected light stripes very similar in width, while Normal makes the stripes go from very thick to very thin across the projected patterns.
High-frequency Coding strategy is suitable for scenes containing reflective surfaces.
Phoxi 3D Scanner - for most scenes, choosing the interreflections strategy will provide better output, but in some specific situations, the Normal strategy might be useful.
Advanced / Coding Quality
Fast
High
Ultra
Determines the number of used patterns and the subpixel accuracy:
Fast - no sub-pixel accuracy.
High - sub-pixel accuracy (default).
Ultra - enhanced sub-pixel accuracy.
This parameter also influences both scanning and processing time. Selection between Ultra and High should be made based on specific scenes. Ultra is usually useful for long-distance scanning with the XL model.
Advanced / Texture Source
PhoXi 3D Scanner Gen2
LED
Computed
Laser
Focus
PhoXi 3D Scanner Gen3
LED
Computed
Computed (Enhanced)
Laser
Laser (Enhanced)
Focus
Color
Alpha 3D Scanner
LED
Computed
Computed (Enhanced)
Laser
Laser (Enhanced)
Focus
Determines the way the Texture is acquired.
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).
Computed (Enhanced) - operates like standard Computed option, but applies additional processing to suppress projection stripes. It does not work in Camera Only Mode and devices with Powell lens based projection unit.
Laser - will trigger an additional image using a laser flash. Use this setting to investigate light conditions in the scene. Images have speckles.
Laser (Enhanced) - operates like standard Laser option, but applies additional processing to suppress projection stripes. It does not work in Camera Only mode and devices with Powell lens based projection unit.
Focus - will set the scanned structured light pattern as a texture. This setting is useful for analyzing problems with signal contrast and for finding optimal scanning time. Explore the dark and white areas and compare their values. The higher the contrast value, the higher the scanning quality. But avoid overexposure (value above 1023).
Color - will capture an additional image illuminated with the white LED flash that offers a speckle-free 2D RGB image.
Advanced /
Single Pattern Exposure
10 - 100 ms
Increases acquisition time by prolonging the projection of each pattern. The longer the time the more light is projected on the scene.
Has the same effect as Shutter Multiplier, but offers more variability in choosing the right value. In combination with Ambient Light Suppression, use values above 40 ms.
Advanced / Maximum FPS
0 - inf
Useful for limiting FPS in freerun mode. If you want to allow a scan every 10 seconds, set Maximum FPS to 0.1.
Advanced / Laser Power
0 - 4095
Controls the intensity of the projected light. By default, it is set to the highest possible value. Decrease the value in case of overexposure.
Note: The ‘Laser Power’ setting, adjustable from 0 to 4095, controls the relative output of the laser. Note that the actual power output can vary between individual devices, even when set to the same ‘Laser Power’ value.
Advanced /
Projection Offset (Left/Right)
0 - 512
This parameter narrows the area covered by the projection, shortens the shutter window, and thus limits the ROI of the device.
It determines the number of projection columns that are cut off from the left/right side of the projection. The total width of the projection is 512 columns.
It is useful for cases where the surroundings of the scanned object interfere with the scan or are unnecessary for further use of the point cloud.
Additionally, the sensor’s shutter window length is adjusted to match the narrowed projection, allowing less ambient light to enter the sensor. This parameter can help in scenes with extreme ambient light levels.
Advanced / LED Power
0 - 4095
Enables to decrease the LED light intensity used to capture texture. Useful for cases when the texture is used for extracting additional information and is experiencing overexposure.
Advanced /
LED Shutter Multiplier
0 - 20
Increases scanning time and amount of used light to capture texture.
Advanced / Hardware Trigger
true/false
Usually used when two or more devices need to be synchronized.
When the device is in hardware trigger mode and a scan is triggered, the acquisition will start after a specified edge of the signal is detected on the trigger input pin. The device can also signalize to other devices that it is acquiring by keeping the trigger output signal in the high state.
Advanced /
Hardware Trigger Signal
Falling
Rising
Both
Specifies what type of edge of the signal on the trigger input pin is used to hardware trigger the device.
Advanced / Maintenance Mode
(PhoXi 3D Scanner Gen3 only)
Off
Auto
Maintenance mode can be used to check and improve consistency of the device calibration.
Off - maintenance is inactive.
Auto - autonomous maintenance mode acquires additional patterns to check calibration consistency, thus it takes longer time. If possible, it adjusts certain calibration parameters to improve the consistency of the device calibration. The procedure requires a static and well scannable scene. This mode is available only on devices with Color camera manufactured or serviced with firmware version 1.15.0 or higher and shipped after May 2025. If your device was produced earlier, it does not support this feature.
Advanced / ISO
(PhoXi 3D Scanner Gen3
and Alpha 3D Scanner only)
100
140
200
280
400
560
800
1120
1600
This value adjusts the primary sensor’s sensitivity to light. Higher ISO brightens the image and reveals more detail in dark regions, but also increases noise and the risk of oversaturation in bright areas, which can degrade the quality of the texture and the point cloud. Base value: 100.
Interaction with HDR (available for PhoXi 3D Scanner Gen3) - use HDR to counteract oversaturation when ISO is set high.
Advanced / HDR
(PhoXi 3D Scanner Gen3 only)
Off
Medium
Strong
Controls how well bright regions are preserved (by reducing oversaturation) while keeping dark‑region detail constant. The higher the HDR setting, the better the bright region preservation.
HDR helps preserve highlights at medium and high ISO values. At the lowest ISO, HDR has no effect.
Early Transfer
(PhoXi 3D Scanner Gen3 only)
Off
ColorCameraImage
Early Transfer is a latency-optimization feature designed for high-performance processing pipelines.
When enabled, the device transmits the selected texture/image data as a separate frame as soon as it becomes available, before the rest of the 3D data is ready.
Off - Disables Early Transfer feature. All acquired data is sent together in a single frame per scan.
ColorCameraImage - Two frames per scan are sent from the device:
First frame: ColorCameraImage (an image from the RGB camera unit in the resolution specified in the Color Settings)
Second frame: Complete 3D data (PointCloud, NormalMap, DepthMap, Texture, ConfidenceMap, ColorCameraImage according to the current selection in Output Structure).
When this option is selected, ColorCameraImage must be enabled in Output Structure. We recommend setting Camera Space = ColorCamera to achieve 1:1 alignment between 3D data and the ColorCameraImage/Texture without additional processing.
Defines data cutting volumes in Camera or Point Cloud space. This setting can be configured manually via numerical input or via the Interactive Mode in the 3D Viewer. For detailed instructions and Interactive Mode usage, see chapter 3D ROI Configuration
Data Cutting / Normal Angle
Max Camera Angle
0 - 90°
Maximal angle accepted between the camera-to-3Dpoint straight line and the measured normal vector at this point. (can be understood as “how much the scanned surface is rotated away from the camera”).
Max Projection Angle
0 - 90°
Maximal angle accepted between the projector-to-3D-point straight line and the measured normal vector at this point. (=“how much the scanned surface is rotated away from the laser projector”)
3D points with normals rotated away above these thresholds will be filtered out. Useful for scanning objects where edges are causing problems.
Min Halfway Angle
0 - 90°
Minimal angle accepted between the “halfway line” to a 3D point and the normal vector in this point. The halfway line is the center line between the camera-to-3D point line and the projector-to-3D point line.
Max Halfway Angle
0 - 90°
Maximal angle accepted between the “halfway line” to a 3D point and the normal vector from this point.
Data Cutting / Max Inaccuracy
0 - 100 (mm)
Threshold for filtering the 3D points based on the point measurement reliability. Enables prefiltering of the output data according to the specific needs of your application. Some applications require a more complete device 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 criterion.
Max Inaccuracy can be set based on data from the Confidence Map. The corresponding parameter in the API is named Confidence.
Data Cutting /
Calibration Volume Only
true / false
By default, only the points scanned in the recommended scanning volume are displayed. It is possible to see all the data acquired in the scene by setting the Calibration Volume Only to false.
Data outside of the recommended scanning range are not guaranteed to be measured with the same accuracy.
Recommended scanning volume is defined by the minimal and maximal scanning distance, which differs between the device models and can be found in the device datasheet.
Point Cloud Generation /
Surface Smoothness
Sharp
Normal
Smooth
Determines 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.
Smooth - an edge-preserving algorithm that smooths the surface, lowering noise at the expense of small features.
Point Cloud Generation /
Normals Estimation Radius
0 - 4
Determines the size of the area (in sensor pixels) around the point that serves for the computation of the normal vector of each 3D point.
A higher radius leads to smooth normal vectors and a small radius to noisy normals. With the radius set to 0 normals are not calculated.
Marker Dot Correction /
Operation Mode
Off
Passive
Active
Reference Recording
All the operation modes are explained in section Operation Modes
Marker Dot Correction /
Max Marker Shift (pixel)
0-25
Maximal permitted pixel shift of the markers It is not recommended to raise this value above 25 pixels
Interreflections Filter
(PhoXi 3D Scanner,
Alpha 3D Scanner only)
true/false
Special filter used to remove incorrectly calculated points due to the presence of interreflections. Switching the filter on changes the Coding Strategy to Interreflections.
Interreflections occur when the laser light pattern is reflected from a diffuse surface and illuminates nearby objects. If the reflection interferes with the primary light pattern reflected from the scene, the depth calculation is affected causing the existence of discrete patches of points isolated from the rest of the point cloud, and they do not represent reality.
Interreflection Filter Strength
(PhoXi 3D Scanner,
Alpha 3D Scanner only)
0.01 -0.99
Allows the user to adjust the strength of the Interreflection Filter.
Pattern Code Correction
Off
Medium
Strong
Defines strength of the smoothing filter applied onto the decoded projection patterns.
Pattern Decomposition Reach
Local
Small
Medium
Large
This parameter is mostly used to scan objects that are harder to scan due to challenging scanning angles, dark color, or higher shine. It helps to correct or eliminate points that have higher computation errors.
To correctly decode the series of light patterns for each pixel, the values of surrounding pixels are taken into account. If the difference between them is larger than expected, the value of the candidate pixel is adjusted. This way some errors that are identified during computation are corrected. If the difference between neighboring pixels is too large, the candidate pixel is filtered out.
Signal Contrast Threshold
(PhoXi 3D Scanner,
Alpha 3D Scanner only)
0 - 4095
Serves as a filter that helps to eliminate parts of the scan with low contrast and low quality. Lowering the value of the Signal contrast threshold can help in situations where strong ambient light or worse scanning properties produce insufficient contrast between the light and dark stripes of the pattern. Higher values can serve to eliminate some noise from the scan.
Each pattern is composed of light and dark stripes. The difference in intensity between them is called contrast. Two neighboring pixels belong to differently illuminated stripes (one is light and one is dark) if the contrast between them is higher than the threshold set by this parameter.
To assess the contrast between light and dark stripes, set the “Focus” texture option within the Texture source setting and examine the resulting contrast in the Texture image.
Glare Compensation
true/false
Filter to suppress 3D reconstruction deficiencies caused by glare from a strong reflection of the scanned subject.
Hole Filling
Off
Medium
Hole filling feature, if enabled, supplements 3D points to gaps surrounded by points in reasonably small depth range. Gaps surrounded with largely varying depths will not be filled.
Defines the rotation matrix to transform from the camera space to the robot or custom space. Clicking the Edit button opens a new window with a 3x3 editable matrix.
Translation Vector
Defines the translation vector from the camera space to the robot or custom space. Clicking the Edit button opens a new window where the X, Y, and Z coordinates of the vector can be set.
Marker Scale
X 0 - inf
Y 0 - inf
Enables the setting of the X and Y scale of the marker pattern. Use X or Y larger than 1 for upscaled marker patterns and smaller than 1 for downscaled marker patterns. The correct scale is when the origin of the coordinate system is placed in the center of the white circle in one of the corners of the marker pattern.
Marker Ortho
Default Sampling Distance
Sampling distance 0 - inf
Origin Distance 0 - inf
Default Origin Distance
Default Sampling Distance: Distance between points from neighboring pixels in the sweet spot of the original projection.
Sampling Distance: Distance between points from neighboring pixels at the same depth, measured in millimeters.
If equals 0, the distance between points from neighboring pixels in the sweet spot of the original projection will be used instead.
Default value: 0.0
Origin Distance: Distance between virtual camera and marker board.
Default value: 0.0
Default Origin Distance: Distance between sensor position and marker origin.
Camera Space
PrimaryCamera
ColorCamera
CustomCamera
MarkerOrthoCamera
Defines the origin of the depth map. If the “Coordinate Space” is set to “CameraSpace” it also changes the point cloud space.
PrimaryCamera: The origin of the depthmap is in the primary camera of the device - the 3D sensor.
ColorCamera: The origin of the depth map is in the color camera of the device.
Note: The resolution of the depth map is determined by the resolution of the ColorCameraImage (Color Settings -> Resolution) at either resolution of 1288x730 or 1932x1096 (interpolated). To correctly get the depth map in the selected Color Resolution, ROI mode cannot be Standard.ColorCamera option is available only for PhoXi 3D Scanner and MotionCam-3D Color.
CustomCamera: The origin of the depth map is in the custom camera (which can be for example external infrared camera). This cannot be set up through GUI. Please check the ReprojectionToExternalCameraexample in the API Example section of this manual.
MarkerOrthoCamera:
Prerequisite: marker pattern in the scene
The depth map is organized as it was capturedby orthogonal (telecentric) camera pointed perpendicular on a marker board.
Coordinate Space
CameraSpace
MarkerSpace
RobotSpace
CustomSpace
PrimaryCameraSpace
CameraSpace: Coordinate space with the origin in the CurrentCamera’s position
The X-Y plane is defined by the camera sensor or a virtual camera defined by Camera Space in a case of depth map reprojection and Z is the perpendicular distance from the sensor to the scene/object.
MarkerSpace: To align multiple scans in PhoXi Control, it is useful to use marker patterns. Marker patterns are available in Tools/Marker patterns. If you place a marker pattern below an object and set the marker space as your coordinate space, you can now move the sensor to different locations with the point cloud automatically returning to the same coordinate system defined by the marker plate.
RobotSpace: Coordinate space with the origin of the robot. Automatically set by Robot-Camera Calibration Tool. See the Photoneo website for more information.
CustomSpace: Your custom-defined coordinate space.
PrimaryCameraSpace: Coordinate space with the origin in the primary camera of the device.
Recognize Markers
true/false
When true, the algorithm will look for markers in the scene. Then you need to place a marker pattern in the scanning scene, otherwise, the resulting frame will be corrupted.
Save Transformations
true/false
When true, the new transformation from CameraSpace to any other Coordinate Space will be automatically saved to the device. The same can be done manually with the Set and Store function.
Primary Camera to Point Cloud Space transformations
Transformation between the primary camera and the marker space
MarkerSpace
ColorCamera
Transformation between the color camera and the marker space
PrimaryCameraSpace
PrimaryCamera
Match (identity matrix)
PrimaryCameraSpace
ColorCamera
Transformation between primary camera and the color camera
Robot/CustomSpace
PrimaryCamera
Transformation between the primary camera and the robot/custom space
Robot/CustomSpace
ColorCamera
Transformation between the color camera and the robot/custom space
The above-mentioned matrices for the Primary Camera to Point Cloud Space transformations and the Current Camera to Point Cloud Space transformations are also available via API.
Processing Order: Cutting is processed after the point cloud is computed; therefore, enabling this setting cannot speed up the transfer time.
Coordinate Spaces: ROI cutting applied in the camera space is always based on the original coordinate system. ROI cutting in the point cloud space is applied only when the coordinate system of the point cloud differs from the camera space.
Tip
Use this setting in combination with Marker Space to remove the background, which will make scan alignment easier.
The Interactive Mode allows you to visually define and modify the cutting volume directly within the 3D Viewer.
Activation
To activate the Interactive Mode for 3D ROI, click the box icon located in the settings pane under: Processing Settings > Data Cutting > 3D ROI > Camera Space (or Point Cloud Space).
Once activated, a bounding box will appear over your point cloud in the 3D Viewer, along with a dedicated ROI toolbar at the top of the viewer.
Manipulating the Bounding Box
You can modify the size and position of the bounding box using the interactive 3D widgets attached to it. The axes are color-coded: X (Red), Y (Green), and Z (Blue).
Note
The bounding box is always aligned to the coordinate axes and cannot be rotated.
Colored Handles (Resize) - Click and drag the red, green, or blue handles located on the faces of the bounding box to stretch or shrink the volume along that specific axis.
Grey Central Cube (Free Movement) - Click and drag the solid grey cube in the very center to move the entire bounding box freely in 3D space.
Grey Planar Squares (Planar Movement) - Click and drag one of the grey square markers (located near the center) to move the entire bounding box strictly along its corresponding 2D plane (X-Y, X-Z, or Y-Z).
ROI Toolbar Controls
While in Interactive Mode, a new toolbar appears at the top of the 3D Viewer. Use these buttons to manage your ROI session.
Apply - Confirms your adjustments. The Min and Max coordinate values in the settings panel will update automatically to match the visual box.
Note
To see the actual cut applied to a new scan, you must hit the main Set and Trigger button.
Erase - Clears the current bounding box and sets all boundary values to 0 (which disables data cutting).
Auto - Automatically sizes and positions the bounding box to encapsulate all valid points in the point cloud.
Reset - Reverts the bounding box back to the exact dimensions it had before you started the current interactive session.
You can manually define the cutting volume by inputting exact boundary values. You have two options for entering these parameters:
Start filling out the Min and Max values for all three coordinates directly in the settings pane.
Click the pencil icon to open the dedicated coordinate table and fill in the values.
Configuration Rules & Constraints
When manually defining the ROI, the system applies the following rules to your inputted values:
The cutting will be applied only if the minimum value is strictly smaller than the maximum value for a given axis (e.g., min. X is smaller than max. X).
Setting any boundary value to 0 disables data cutting in that specific direction.
If cutting close to 0 is necessary, use a small decimal value instead.
The hardware trigger provides the user with means of triggering devices by external means - outside of the software environment. To get further hardware specifications about the hardware trigger, see the Photoneo 3D Sensor User Manual. This functionality is mostly used for synchronization purposes:
With external events, such as an object arriving inside the field of view of Photoneo 3D Sensor (i.e. triggered by an optical gate)
With other devices, such as 2D cameras, PLCs, etc.
Example: A MotionCam-3D Color triggered by an optical sensor to capture a moving object on a conveyor belt
A device sending an output signal to a PLC
Example: A MotionCam-3D sends an output signal to a robotic controller after the acquisition to start a solution. Locator Studio picking from a moving conveyor belt.
Multiple devices triggered by HW trigger independently from each other
2 Photoneo 3D Sensors triggered by a PLC with a specific delay
Two or more devices triggered sequentially in a chain → Daisy chain
PhoXi Instant Meshing model creation
Two or more devices triggered sequentially in a loop → daisy chain in a loop
The device can be triggered with a software (default) or a hardware trigger. There is a dedicated parameter in PhoXi Control / PhoXi API to control device trigger mode. To trigger the device via hardware trigger:
Set Hardware Trigger = TRUE
Put the device into freerun
Send the signal to trigger input
With hardware trigger mode enabled, the device will capture a new scan each time an input signal is detected. If the trigger input signal arrives during an active device acquisition, it will be ignored. To stop the device from listening to the hardware trigger signal, turn the freerun OFF. To disable hardware trigger mode, set the HardwareTrigger=FALSE. The response to the trigger signal is around 3 ± 2 milliseconds.
Photoneo 3D Sensor output signal to PLC or other device (OUT)
Photoneo 3D Sensor sends a signal to trigger a secondary device, which can be a PLC or other signal acceptor.
Multiple devices triggered by HW trigger independently from each other (MEXT)
In this case, an external trigger would be triggering 2 or more devices independently. The devices need to be set up the same way as in the previous use case with a single device. If the devices’ FOVs (fields of view) overlap, make sure the input signals are timed adequately in order to acquire 3D data without any distortions caused by the projection interference.
Daisy chain and daisy chain in a loop are special setups in which two or more Photoneo 3D Sensors are interconnected and are triggered consecutively by each other. They are mostly used to prevent interference between two projections if the devices have overlapping fields of view. In a daisy chain, the trigger sequence is always triggered by external means. In a daisy chain in a loop, once the acquisition has started it will continue until the loop is broken.
Two or more devices triggered sequentially in a daisy chain (EXTSEQ, INTSEQ)
In a daisy chain consisting of, for example, 4 devices, the output pin of the first device is connected to the trigger input of the second device. The output of the second device is connected to the input on the third device and so on. The output on the last (fourth device) is not connected to any Photoneo 3D Sensor (but can be connected to a different device).
There are two options on how to set up the chain:
Sequential triggering with external signal source - EXTSEQ
Set HardwareTrigger=TRUE on all devices.
Start freerun on all devices. In this scenario nothing will happen unless
Hardware trigger from an external source is sent to the trigger input of the first device in the chain
Sequential internal triggering - INTSEQ
Set HardwareTrigger = TRUE on the last three devices and put them into freerun.
Trigger the first device by software trigger/ freerun. This will start the chain and trigger all consecutive devices.
In case the freerun is used, to stop the acquisition of all devices, it is necessary to disable freerun on the first device
Limiting the FPS in some applications might be necessary to achieve stable results. For example, we can have 4 MotionCam-3Ds with overlapping FoVs of which one is primary and it is running on freerun (via PhoXi Control or API) which triggers the other 3 secondary devices via the hardware trigger (connected in series). If, theoretically, the acquisition takes 15 ms for each MotionCam-3D and the Maximum FPS is set to 20 (frame every 50 ms), there is enough time to trigger only 2 secondary devices and part of the acquisition of the last device would be overlapping with the following frame on the primary device. If we limit the FPS of the primary device to 15 (frame every 66 ms), there is enough time to trigger all secondary devices to avoid overlapping. The acquisition windows of the secondary device and tertiary device need to fit in the window between the frames of the first device.
Two or more devices triggered sequentially in a loop - daisy chain in a loop (EXTDCL)
This case is very similar to the basic daisy chain explained above. We can have 4 devices, where the output pin of the first device is connected to the trigger input of the second device. The output of the second device is connected to the input on the third device and so on. However, in this case, the output signal from the last device is connected to the input of the first device, creating a loop.
The picture below illustrates the daisy chain loop with three devices. The red rectangle represents the time period in which the device is in acquisition (the laser is sweeping the scene). During this time period the signal, which is represented by the black line, is opposite to what it was before the acquisition. Once the acquisition on the first device is finished, the signal changes back and thus produces a trigger signal (blue arrow) for the second device that is connected to the first one. A few milliseconds later the acquisition on the second device is started. The yellow rectangle represents the delay between when the trigger signal is received and when the acquisition starts. This delay is typically around 3 milliseconds.
Simplified signal representation for 3 devices in a daisy chain in a loop
In these setups, the end of acquisition on MotionCam-3D #1 produces a falling edge on its output pin which triggers acquisition on MotionCam-3D #2. This is followed by the acquisition on the MotionCam-3D #3.
To set up Photoneo 3D Sensors in a daisy chain in a loop configuration:
Set Hardware Trigger = TRUE on all devices.
Enable free run on all devices
Send a signal from an external signal source to initialize the acquisition
To stop the acquisition, disable freerun on one of the devices.
See our API example for the daisy chain to learn how to control the devices via hardware trigger.
If the following section does not help in solving the difficulty you are experiencing, contact our support team at the Help Center.
The more information that you provide, the faster and more accurate the answer can be. The following section explains how to collect the log files that you are kindly asked to attach to your support requests.
Additionally, please describe what you have been trying to do, what the result was, and what you expected. Depending on the nature of the problem, please also report the version of the operating system being used, your PC configuration, and other additional information that would be helpful in replicating the problem and identifying its root cause.
By default, the logging level on the device is optimized for performance. To extend the logging level to contain extensive information on PhoXi 3D Scanners, turn on Extended logging in PhoXi Control and reconnect to the device (the logging level is determined at the time of connection to the device.) Extended log level on MotionCam-3D needs to be enabled by our support during the remote sessions.
PhoXi Control always creates basic log files. If you experience any problem with Phoxi Control please collect the logs from the folders mentioned above. If you are able to recreate the problem, please set up Extended Logs:
Open LogConfig.txt in the PhotoneoLogFiles folder
On the first line, change 0 to 10 to enable extended logs
Restart PhoXi Control
Once you have replicated the issue and collected logs, change the first number in LogConfig.txt back to 0.
If you have experienced a crash of PhoXi Control, please collect the core dump located in the ProgramData folder on Windows and in the /tmp folder on Ubuntu. The core dumps are available for all PhoXi Controls with version above 1.2.22:
Windows 10
The core dump generation is enabled automatically during the installation
Client API application does not create logs by default.
To set up API logging (generating a lot of data):
Navigate to your application folder and open PhotoneoLogFiles folder
Open LogConfig.txt and change the value on the first row to 10
Restart your application
Once you have replicated the issue, you can turn off the logs by changing the first-row value back to 0
The API log files directory can be changed by setting up the environment variable PHO_API_LOG_FILES_DIR or PHO_LOG_FILES_DIR. If PHO_API_LOG_FILES_DIR environment variable is defined, logs will be saved in the direction it points to. If it is not defined, logs are saved in the directory pointed by the PHO_LOG_FILES_DIR. If none of these is defined, the logs will be saved directly on the desktop. In case both of the variables are defined, PHO_API_LOG_FILES_DIR is prioritized.
Cannot connect to the device or scanning time is too long
The device is listed in the PhoXi Control application, but after trying to connect to it, it 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.
Use the Speed test to verify the right connection speed
The device is not visible in PhoXi Control on a network with a dynamic IP assignment
Make sure your device is connected correctly - you are using network media supporting Gigabit Ethernet or higher and your network topology is either star or direct (see sections Network media and Network topology).
Reboot the device.
Check the LED lights on the backside of the device. The last two indicate the status of the Ethernet connection. Please note that the PoE devices have a different set of LEDs than the 12 V devices.
12 V devices
The left diode indicates speed:
ON - 100 Mbps
OFF - other than 100 Mbps, usually 1 Gbps
The right diode indicates Ethernet activity:
OFF - link is down
Flashing - link is up with activity
Steady - link is up without activity
PoE devices:
3rd LED from top:
OFF - link is down
Flashing - link is up with activity
Steady - link is up without activity
4th LED from top:
ON - Gigabit connection
OFF - slower than gigabit connection
Check the network configuration of your computer:
Your firewall is blocking communication with the device.
Zeroconf implementations (Avahi or Bonjour service) are not running or are running incorrectly.
To resolve the problems listed above:
Check your Network Connection status in system settings. If networking is disabled, enable it.
Check the settings of your firewall. The device communicates with the computer on ports - 5353 and 5354 on the computer side and ports - 65499 and 65534 on the device side.
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 BonjourPrintServicesforWindowsv2.0.2 and can be found in the following link: support.apple.com/kb/dl999?locale=en_US.
Ubuntu does not show IPv4 address - creating a Link-local connection
When the PhoXi 3D Scanner or MotionCam-3D is connected to Ubuntu and you want to use dynamic IP address assignment relying on Zeroconf, the network discovery usually requires a Link-local connection. It is necessary to create Link-local connection when:
PhoXi Control does not display IPv4 address in the corresponding field
Running the following command does not show 169.254.x.x IPv4 address
$ipaddrshow<INTERFACE-NAME>
To create Link-local connection:
Connect the device to your computer.
Find out the system name of the network interface you have used. It is usually ethN or enpNs0 where N is some small number, e.g. eth0 or enp2s0. You can find out the list of network interfaces by typing ip-br-clinkshown into a terminal window. Your device will be shown as UP. Note that if you use more than one Ethernet interface you’ll see more than one device UP. In that case, disconnect the network cable from the Photoneo device, run the ip-br-clinkshow command again to see which one went DOWN, and plug the network cable back again. Note the hardware (MAC) address of the device. In our example, the device is enp2s0 and its hardware address is 7c:67:a2:9e:57:c3.
Create a new network connection using NetworkManager. In the Ethernet tab, choose the right device (the field is under the Identity tab and called MAC address on some versions of Ubuntu). In the IPv4 Settings choose Link-localOnly as the connection method.
Name the connection for example as Link-localOnlyConnection and save its configuration.
Activate the connection by clicking on its name in the network connections list in the top right corner of your screen.
Please describe what you have been trying to do, what the result was, and what you expected. Depending on the nature of the problem, please also report the version of the operating system being used, your PC configuration, and other additional information that would be helpful in replicating the problem and identifying its root cause. Thank you!
Every point in a point cloud is identified by three numbers - its XYZ coordinates. Coordinates give the precise position of each 3D point relative to the point of origin of the specific coordinate system.
By default, all Photoneo 3D Sensors are set to generate point clouds in the camera coordinate space (the point of origin is located in the center of the camera sensor). Additionally, they provide the internal capability to real-time transform the point cloud to any arbitrary coordinate space. Once the transformation parameters are known the device generates the point cloud (using 3D rotation and translation) in the selected coordinate system.
In PhoXi Control there are five coordinate spaces to choose from
Camera space
Marker space
Robot space
Custom space
PrimaryCameraSpace
The default setting for all Photoneo 3D Sensors is to use CameraSpace. This coordinate system has a point of origin in the center of the camera sensor.
In PhoXi Control, use the checkbox Axis under the Coordinates box in the right pane to visualize the axis defining the default coordinate system. (XYZ axes follow the RGB color convention).
Camera space in PhoXi Control. Z-axis (blue) lines up perfectly with the direction of the view, so it is not visible.
In the camera space, X-axis aims to the right side of the device, and Y-axis aims downwards. The sensor is mounted at a specific angle relative to the sensor body. This angle varies for different device models, so the XY-plane is not parallel with the outer casing of the device (see Table 1 for details).
Z-axis aims at the scene and defines the “depth” at which the object is observed by the device. It’s the perpendicular distance of every single point on the scene to the XY-plane defined by the camera sensor.
Orientation of camera space coordinate system in relation to the device. The X-axis is red, the Y-axis is green and the Z-axis is blue.
Table 1: Angles at which the camera sensor is mounted in different models of PhoXi 3D Scanner.
Device
XS
S
M
L
XL
Angle
0°
15.45°
11.75°
9.45°
7.50°
Table 2: Angles at which the camera sensor is mounted in different models of Alpha 3D Scanner.
Device
L
XL
Angle
7.50°
7.50 °
Table 3: Angles at which the camera sensor is mounted in different models of MotionCam-3D (Color).
Device
S
S+
M
M+
L
*L+
Angle
0°
0°
0°
0°
0°
0°
* Only available as MotionCam-3D Color
Camera space (left - the origin is in the camera unit of the device) and marker space (right - the origin is in the origin of the marker pattern) in PhoXi Control.
Marker space provides you with a practical tool for many different real-world applications. Marker space transformation is useful in situations like: calibration of a coordinate system with a specific plane, multiple scan alignment (one moving device), multiple device calibration (scanning scene from different directions), or calibration of a device mounted on a moving robot arm.
Marker space has the point of origin and its axes defined by marker pattern:
The origin point lies at the origin point of axes printed on the pattern.
The XY-plane is aligned with the XY-plane visible on the marker pattern. The X-axis and Y-axis match the X-axis and Y-axis printed on the pattern.
The Z-axis points upwards from the marker pattern perpendicular to the XY plane.
Marker pattern is a specially developed printed pattern recognized by Photoneo 3D sensors used to transform the coordinate system from default camera space to marker space. It contains N uniquely recognizable white circles on black background with encoded coordinates. Marker patterns are available in different sizes - in the PhoXi Control installation folder or for downloading from our website www.photoneo.com/downloads/device-resources/.
Use PhoXi Control Menu → Tools → Marker Patterns to open a folder containing two subfolders. In the subfolder Patterns, you can find PDF versions of all available marker pattern sizes. Since different device models are able to scan different volumes from different distances, they also need different sizes of marker pattern.
Table 3: Recommended sizes of marker patterns for PhoXi 3D Scanner models.
XS
S
M
L
XL
Scanning distance [mm]:
<1900
>1900
A5
✔
A4
✔
✔
A3
✔
✔
✔
A2
✔
✔
S30
✔
✔
✔
✔
✔
Table 4: Recommended sizes of marker patterns for MotionCam-3D models.
S
S+
M
M+
L
L+
<1900
>1900
A5
✔
✔
A4
✔
✔
✔
✔
✔
A3
✔
✔
✔
✔
✔
✔
✔
A2
✔
✔
✔
S30
✔
✔
✔
✔
✔
✔
✔
Table 5: Recommended sizes of marker patterns for Alpha 3D Scanner models.
L
XL
A5
A4
✔
A3
✔
✔
A2
✔
✔
S30
✔
✔
For complete information about minimal/maximal distances and maximal angles from which marker pattern is recognizable by Photoneo 3D Sensors please refer to Table 6, 7, and 8.
Table 6: Sizes, distances, and angles at which the marker pattern is still recognizable by PhoXi 3D Scanner devices
XS
A5
A4
A3
A2
S30
Minimal distance
150
230
230
Maximal distance
250
250
250
Maximal angle (~180 mm)
30
S
Minimal distance
380
380
380
380
Maximal distance
580
580
580
580
Maximal angle (~440mm)
60
60
60
60
M
Minimal distance
460
460
460
460
Maximal distance
620
1160
1160
1160
Maximal angle (~650mm)
15
60
60
60
L
Minimal distance
870
870
1300
870
Maximal distance
1950
1950
2200
2200
Maximal angle (~1240mm)
15
15
60
15
XL
Minimal distance
1680
1680
1680
1680
Maximal distance
1950
1950
3950
3950
Maximal angle (~2300mm)
15
15
15
15
Table 7: Sizes, distances, and angles at which the marker pattern is still recognizable by different models of MotionCam-3D.
S
A5
A4
A3
A2
S30
Minimal distance
380
380
380
Maximal distance
580
580
580
Maximal angle
60
60
60
S+
Minimal distance
630
635
635
Maximal distance
1570
1540
1540
Maximal angle
15
60
15
M
Minimal distance
500
500
500
Maximal distance
935
935
935
Maximal angle
60
60
60
M+
Minimal distance
630
635
635
Maximal distance
1570
1540
1540
Maximal angle
15
60
15
L
Minimal distance
780
780
780
780
Maximal distance
1400
2350
3030
3030
Maximal angle
15
15
15
15
L+
Minimal distance
1300
1300
1300
Maximal distance
2950
3780
3780
Maximal angle
15
15
15
Table 8: Sizes, distances, and angles at which the marker pattern is still recognizable by different models of Alpha 3D Scanner.
L
A5
A4
A3
A2
S30
Minimal distance
870
870
870
870
Maximal distance
1630
2150
2150
2150
Maximal angle
15
15
15
15
XL
Minimal distance
1680
1680
1680
Maximal distance
2840
3780
3780
Maximal angle
15
15
15
Table 6, 7, 8 explanations:
Minimal distance - minimal distance at which the device can still recognize the marker pattern.
Maximal distance - the maximal distance at which the device can still recognize the marker pattern.
Maximal angle - maximal angle to which the marker device can be rotated away from the position parallel with the device as can be seen in the following figure.
Maximal angle to which the marker pattern can be rotated away from position parallel with the device for the pattern to be still recognizable. For maximal angles for different sizes of devices and marker patterns refer to Table 3 and 4.
Note
When using a marker pattern, whose maximal center-to-center distance is 4-times smaller than the calibration range of the device, the maximal angle is 15°. Refer to Tables 6, 7 and 8 for more information.**
Marker pattern with the point of origin and X (red), Y (green), and Z (blue) axes depicted.
The origin of marker space always lies in one specific circle (see Figure 5). Even if this circle is not visible in the initial scan, the design of the pattern ensures that the point of origin can be calculated based on which circles are visible in the scan. If the marker pattern is printed scaled and the corresponding scale is not set in PhoXi Control, the marker pattern will not be recognized correctly (i.e. the point of origin will be on the edge of the circle instead of in the middle.
For applications where the highest accuracy is necessary, the marker pattern can also be ordered as a metal plate. Paper marker patterns usually are not perfectly flat, which can cause small deviations in the setting of the XY plane. Even though this error is small, for objects that are larger or further away this initial error multiplies and can cause millimeter deviations in measurements far from the pattern. Marker patterns on metal plates have better flatness and eliminate these types of errors.
For applications where scaled versions of the above-mentioned marker patterns are used, the scale of the pattern has to be reflected by setting up the Marker Scale in PhoXi Control. The marker Scale is part of the Coordinate Settings menu. For lower versions of PhoXi Control, this utility is used to change the scale of the marker pattern.
In most cases at least an area of 2 columns* x* 3 rows of the marker pattern has to be visible to the device. The circles on the marker pattern visible to the device cannot be collinear or the device will not be able to recognize them.
Figure 5: Minimal part of the marker pattern that has to be visible for the device to correctly recognize it and set marker space. It does not matter which part of the marker pattern is visible to the device.
“Calibration” is the process of recognizing the position of the marker pattern and setting up the marker space coordinate system. It can be done one time, e.g. to calibrate the coordinate system with the table or the floor, or every time the scan is taken, e.g. to be used on rotary tables.metadata
If using a MotionCam-3D, for the Cameramode, markers should be 1.5x larger than in the Scannermode to accommodate the reduced resolution (if not using the FullGrid Output Topology).
In the Coordinates Settings menu set Coordinate Space to MarkerSpace.
Check Recognize Markers.
Check Save Transformations.
Hit the Set button.
You can also save this marker space transformation into your current profile, and hit the Set and Store button.
Place the marker pattern in the scene, and trigger the scan.
If any object is in the scene, make sure the minimal part of the marker pattern is visible (Figure 5).
Once the calibration is completed, the marker coordinate system is stored in the device, so the marker pattern can be removed from the scene.
For the following scans:
Set Coordinate Space to Marker Space.
Set Recognize Markers to off.
Set Save Transformations to off.
If using a MotionCam-3D, after the calibration is complete, Operation Mode can be either set to Camera or Scanner while preserving the Marker Space
Usage of marker space.
Recognize Markers parameter is used to tell the device to look for the marker pattern in the scene:
When this option is checked and the marker pattern is in the scene, transformation to marker space occurs.
When this option is checked and the marker pattern is not in the scene, PhoXi Control shows the status Error: Marker pattern was not recognized (3D-Based)!, but still displays the texture of the last frame.
It is only necessary for Recognize Markers to be checked during marker space calibration. Once the transformation is known it is saved on the device by the Save Transformations parameter.
Moving the device between sessions or making other adjustments to the scene in terms of distances and/or angles between the device and plane defined by the marker pattern makes the transformation incorrect.
Save Transformations parameter is used to permanently save transformations from camera space to other coordinate spaces (marker space, custom, or robot space) to the device. This means that even when marker space is selected in the following session (after the device restart) and the pattern is not set to be recognized again, the transformation is applied to the point cloud.
There are several uses of Photoneo 3D Sensors where the Marker Space presents an advantage:
Calibration with a plane: for applications that need to have a specific plane as their base, marker space provides an easy way to achieve this. The marker pattern can be removed after the initial calibration.
Multiple scan alignment: for applications where multiple scans from different points of view are used to create a model of the scanned object. Point clouds that have coordinates in camera space can be aligned by complex algorithms or manually. However, when the point clouds are generated in marker space the scans can be automatically pre-aligned with each other.
Multiple devices calibration: for applications where multiple devices are used to scan the scene from different points of view. If all the devices in the scene have coordinates set to marker space they generate point clouds with the same coordinates. This is very similar to scanning objects with one device from different points of view.
Figure 10: Multiple devices in one scene using marker space generated point clouds with the same coordinates.
Calibration of the device on a moving robot arm allows determining the exact position of the device mounted on the moving robot arm with regards to the tool center point (TCP) of the robot. The calculation is done based on several scans of the marker pattern in different positions of the robot (its TCP). Knowledge of the exact position of the device on the robot is necessary to transform the position of the scanned object into the coordinate space of the robot.
Marker space allows finding the transformation between the tool center point of the robot and the fixed position of the device on the robot arm.
How do I find out if my point cloud is in the Marker space?
On the right side of the Viewer Pane in the Coordinates menu check the Axis box. This displays the axes of the point cloud coordinate system. Marker space axes can be easily visually checked in a 3D viewer to see if they are set correctly.
Scan in Marker space with displayed axes. Note: On newer marker patterns the axes origin will be in the origin of the axes printed on the marker patten in the corner.
Point cloud is not generated, and the status bar shows Error: Marker pattern was not recognized (3D-Based)!.
The marker pattern is not detected correctly. Either:
The visible portion of the marker pattern is too small
There are only collinear circles in the visible portion of the marker pattern
The angle between the marker pattern and the device is too big (please refer to Table 3, Table 4 and Figure 13),
The point cloud is in half resolution.
If using MotionCam-3D, the Operation mode is set to Camera
The point of origin of Marker Space is not in the center of the circle.
Check if the marker pattern is printed correctly without scaling or fitting it to paper. When the pattern is scaled the size of the circles is different, and the position of the point of origin is not calculated correctly.
Always use marker patterns available in PhoXi Control or downloaded from our website.
Does the origin point of Marker Space have to be visible to the device?
No. All the circles are unique so the origin point is calculated based on the circles that are visible.
This tool is a command-line application designed for the spatial alignment of multiple Photoneo 3D Sensors. It calculates and applies the spatial transformations to align two or more scanners into a single, shared coordinate system.
The alignment tool also supports chaining transformations through intermediate devices. This enables alignment even when not all devices have direct overlap with the master device, as long as there is a chain of overlapping observations. In all methods, one scanner is designated as the master device (the first in the device list).
Texture-Based: Relies on identifying and matching common 2D features in the textures of the scans.
Sphere-Based: Uses at least three spheres of a known diameter placed in the scene. The application automatically detects these spheres and uses their 3D positions to compute the transformation.
Multi-Marker: An interactive method that uses a marker board to collect multiple marker positions across different placements. The user moves/rotates the marker board to multiple positions, capturing marker detections from all devices at each capture. The alignment is computed from the captured marker poses.
Marker-Dot: Uses the device’s built-in marker dot recognition to detect marker dots placed in the scene. The 3D positions of the detected dots are used to compute the alignment transformation. Requires at least three marker dots visible to all devices.
This workflow applies to all alignment methods. The specific actions required for your chosen method are detailed in the console and in the “Method-Specific Preparations” section below.
Launch the Tool: In the Network Discovery window, select the primary (master) device and navigate to Utils > Sensor Alignment Tool.
Select Devices: A command-line application will open. Follow the prompts to select one or more secondary devices.
Choose Alignment Mode: Select the alignment method you wish to use (e.g., Texture-Based, Sphere-Based, etc.).
Set Coordinate Space: Decide if you want the tool to automatically set the coordinate space to CustomSpace after a successful alignment.
Configure Profile Settings: Choose whether to save the resulting alignment to a specific scanning profile.
Follow On-Screen Instructions: The console will now provide specific instructions based on the chosen alignment method. This may involve moving objects, capturing scans, or entering data.
Review Results: Once the process is complete, the application closes. If you choose to do so in Step 4, the transformation is automatically applied to the secondary devices. All scanners will now operate in the master device’s coordinate space.
Before starting the general workflow, prepare your physical setup according to the method you plan to use. During the workflow (Step 6), the console will guide you through the unique actions required for each method.
Setup: Ensure the scanners have an overlapping field of view. Place at least one flat, texture-rich object (like an open magazine or a detailed poster) within the shared area to ensure a high-contrast, non-repetitive texture. This significantly improves the likelihood of a successful alignment.
Setup: Place at least three alignment spheres of the same, known diameter into the scene so they are visible to all scanners. The spheres should not form an equilateral or isosceles triangle; ensure that each pair of spheres in the triplet has a different distance between them.
In-Tool Action: When prompted by the console, you will need to enter the diameter of the spheres in millimeters.
Setup: Place at least three marker dots in the scene so that they are visible to all scanners you wish to align. The dots should be well-distributed in 3D space (not collinear).
The paths below assume the default installation directory and version 1.17.0. If you installed PhoXi Control in a different location or are using a different version, please adjust the paths accordingly.
Image sensors inside PhoXi 3D Scanners and MotionCam-3D (non-color) are capable of providing grayscale images only. Applications that require color information along with the 3D data can be performed using the MotionCam-3D Color or by a calibration (also referred to as alignment) of an additional color camera with the PhoXi 3D Scanners and MotionCam-3D (non-color).
The calibration is achieved via PhoXi C++ API by capturing multiple images of marker pattern both from the device and the external camera. The output of this calculation is a transformation from the default device coordinate space to the coordinate space of the external camera. As a result, the API can provide a depth map from the perspective of the external camera as well as a 3D point cloud with a mapped color texture.
This manual will guide you through the use of the API example ExternalCamera in the following steps:
Calibration of sample external camera with PhoXi 3D Scanner or MotionCam-3D.
Calculation of the depth map from the point of view of the external camera.
Application of color information on the 3D point cloud.
Provided example application has two modes of operation:
Batch mode controlled by command line arguments capable of calibration of the device with an external camera, depth map calculation, and color point cloud processing using saved files.
Interactive mode where each step is based on user input. This mode is capable of calibrating the external camera with the device, calculating the depth map, and processing the color point cloud while connected to the device.
Provided API application runs with sample data to demonstrate the process of calibration with an external camera, producing a depth map and colored point cloud. Implementation and use of your own external camera is described in later parts of this document.
The process of calibration serves to compute the transformation between the default coordinate space of the device and the coordinate space of the external camera which has origin in the external camera. The computation is achieved by processing:
Ten pairs of images of marker pattern taken by the device and the external camera, each taken from a different point of view. For calibration purposes, the images from the external camera have to be in greyscale. The images are located in <path>/Datadirectory with the following naming convention:
Prefix frame for images captured by the internal camera of the device.
Prefix image for images captured by the external camera.
Input parameters from files located in the <path>/Settingsdirectory:
FocalLength → focal length of the external camera.
PixelSize → pixel size of the external camera.
MarkerPositions → positions of centers of circles on the marker pattern. Different sizes of marker patterns have different positions of the circles.
The calibration is handled by connecting to file camera 1.praw located in the <path>/Datafolder.
The result of calibration is file calibration.txt containing a set of estimates of intrinsic and extrinsic parameters of the external camera and transformation from the native Photoneo 3D Sensor coordinate space to the external camera coordinate space.
To calibrate the application with sample data, use the following command line argument:
During this step, the depth map aligned from the point of view of the external camera is calculated.
The aligned depth map is calculated based on the data loaded from calibration.txt. The application connects to a file camera <folder>/Data/1.praw and then computes the aligned depth map, which is saved as an image in <folder>/fileCamera_1.jpg. The following command line argument is used to calculate the depth map:
This step serves to apply the color texture captured by the external camera to the point cloud.
The colored point cloud is calculated based on the data loaded from calibration.txt. The application connects to a file camera <path>/Data/1.praw, loads a color texture from <path>/Data/1.bmp, and applies it to the point cloud. The result is saved as <path>/1.ply. The following command line argument is used to calculate the colored point cloud:
For successful integration of the external camera with Photoneo 3D Sensor the following requirements have to be met:
The external camera is C++ compatible and the user is able to trigger images via API calls.
Its pixel size and focal length (both in millimeters) are known.
The position of the external camera with regards to the device is fixed.
The field of view of the external camera overlaps the field of view of the device camera as much as possible. It is recommended to mount the external camera very close to the camera unit of the device.
The following files have to be modified with the information about intrinsic parameters of the external camera:
<path>/Data/FocalLength.txt - contains the focal length in millimeters.
<path>/Data/PixelSize.txt - contains pixel size in millimeters.
The calibration of Photoneo 3D Sensor with an external camera requires a marker pattern and text file detailing the positions of circles on the pattern. A standard marker pattern bundled within PhoXi Control is used for this purpose. The folder containing marker patterns (Menu → Tools → Marker Patterns) also contains the subfolder Patterns_with_Metadata with text files where the position of each circle on the marker pattern is written. Each size of the pattern has different positions of the circles.
Frames and images of the marker pattern from which the transformation to the coordinate space of the external camera is calculated, are acquired during the calibration. The application prompts the user to trigger the frame, after which the method ExternalCamera:getCalibrationImage is called to capture the image from the external camera. At least fivepairs of frames and images from different points of view have to be processed for the calibration to be successful. When the point of view is changed, the relative position of the external camera and the native camera of Photoneo 3D Sensor has to remain the same. The output of the calibration is saved into <path>/calibration.txt. The calibration is valid for all consecutive scans.
The application loads calibration.txt. The aligned depth map is calculated right after a new pair of frames and images is triggered and saved into <folder>/device_1.jpg. The number in the file name is increased every time a new scan is triggered and a new depth map is saved.
The calculation of the aligned depth map from previously captured data can be achieved with the following command line arguments:
--depthmap[fullpathtoprawfile][outputfile]
The calibration.txt has to be present for this command to work, otherwise the application will exit with an error. The output file is where the resulting depth map is saved. The full command would look like this:
The application loads calibration.txt. After the new scan is triggered the application calls ExternalCamera:getColorImage method to capture color texture by the external camera. This texture is then applied to the native point cloud and saved into <path>/device_1.ply. The number in the file name is increased each time a new point cloud is saved.
The calibration.txt has to be present for this command to work, otherwise, the application will exit with an error. The color image is the texture from the external camera that is going to be aligned with the point cloud and the output file is where the resulting point cloud is saved. The full command looks like this:
Depth map is a basic output calculated by Photoneo devices, transferred to PhoXi Control, and used for point cloud calculation. In some applications, the users might calculate the point cloud from the depth map by themselves and not rely on the calculation done by PhoXi Control. Some information about how the 2D camera “sees” the world is necessary for this procedure. This information is carried either by intrinsic camera matrix or by reprojection map.
In Photoneo scanning devices the texture and depth map have a direct relationship → each pixel in the texture has corresponding depth information in the depth map. Therefore operations like segmenting out the only object of interest in the texture and then calculating only the 3D points that were segmented are possible.
The point cloud can be calculated from depth map using these approaches:
Using intrinsic camera matrix and triangle similarity described in pinhole camera model together with distortion coefficients to calculate point cloud for each pixel
Using reprojection map to multiply the depth of given pixel by a reprojection vector corresponding to that pixel
Texture, ColorCameraImage and a DepthMap from Photoneo devices are distorted. This means that straight lines at some parts of the picture appear bent or round-shaped objects appear to be oval-shaped in the texture. Therefore image processing for such geometric shapes is not possible on distorted data and we have to undistort them first.
To undistort, we first apply the inverse of distortion function to each pixel, for example by using the OpenCV method. Once we have the undistorted texture, we can identify the feature points of our object. Then there are two possibilities:
To undistort the depth map as well and use the intrinsic parameters to calculate a new, undistorted point cloud
Distort the feature points back to see to which camera pixels they belong and then use this information to identify them in the point cloud
Intrinsic Parameters Provided by Photoneo Devices
All provided intrinsic parameters can be retrieved by PhoXi API or via Chunk Data Control in GigEV protocol on devices with FW 1.14.0 or higher. There are two different types of intrinsic parameters:
Intrinsic camera matrix and distortion coefficients
Reprojection map
All available intrinsic parameters can be now retrieved via PhoXi API through corresponding pho::api::PhoXiCoordinatesSettings class members:
CurrentCamera: Current (effective) camera settings; depends on CameraSpace setting selector.
CurrentPrimaryCamera: Parameters of the camera which the original depth map (before reprojection) was created with.
CurrentColorCamera: Parameters of the color camera with which the color texture was created.
Intrinsic Camera Matrix and Distortion Coefficients
Intrinsic camera matrix describes the transformation from 3D coordinates to 2D coordinates on an image plane using the pinhole camera model. It is a 3x3 matrix containing focal length - the distance between the pinhole and the image plane and principal point offset - the pixel offset from the principal point.
Distortion coefficients describe the properties of the camera lens and how it distorts the real shape of an object to the shape on the image. OpenCV compatible coefficients (k1, k2, p1, p2, k3) are used to describe the distortion introduced by the camera lens in Photoneo devices.
Intrinsic camera matrix and distortion coefficient can be retrieved using PhoXi API by two different approaches:
Global method: PhoXiDevice``→``CalibrationSettings:
provides the Camera Matrix and Distortion Coefficients at maximum device resolution:
PhoXi 3D Scanner → 2064x1544
MotionCam-3D → Scanner mode 1680x1200
PerFrame method: FrameInfo``→``Camera
provides the Camera Matrix and Distortion Coefficients for current device resolution
PhoXi 3D Scanner → 2064x1544 or 1032x772
MotionCam-3D → respects current Operation mode and Output topology. Empty for Raw and Irregular grid topologies
Reprojection map is a field of vectors that describes the direction from which each pixel gathers data. Each pixel has its own vector, therefore when we multiply the depth information by the vector from the reprojection map we get a point cloud.
Reprojection map can only be retrieved by one method:
Global method: PhoXiDevice``→``ReprojectionMap
Provides current reprojection map that respect current device settings
PhoXi 3D Scanner → both resolutions
MotionCam-3D both operations modes and all output topologies
boolcalculatePointCloud(pho::api::PointCloud32f&pointCloud,pho::api::DepthMap32fdepth,pho::api::PhoXiReprojectionMapreprojection){if(pointCloud.Size!=reprojection.Map.Size){returnfalse;}for(introw=0;row<pointCloud.Size.Height;++row){for(intcol=0;col<pointCloud.Size.Width;++col){if(depth.At(row,col)>0.0f){pointCloud.At(row,col).x=depth.At(row,col)*reprojection.Map.At(row,col).x;pointCloud.At(row,col).y=depth.At(row,col)*reprojection.Map.At(row,col).y;pointCloud.At(row,col).z=depth.At(row,col)*reprojection.Map.At(row,col).z;}else{pointCloud.At(row,col).x=0.0f;pointCloud.At(row,col).y=0.0f;pointCloud.At(row,col).z=0.0f;}}}returntrue;}pho::api::PhoXiReprojectionMapmap=PhoXiDevice->ReprojectionMap;PhoXiDevice->StartAcquisition();if(!PhoXiDevice->isAcquiring()){std::cout<<"Your device could not start acquisition!"<<std::endl;return0;}intid=PhoXiDevice->TriggerFrame();if(id<0){std::cout<<"Trigger frame unsuccessful"<<std::endl;}autoframe=PhoXiDevice->GetSpecificFrame(id);if(frame){autodepth=frame->DepthMap;pho::api::PointCloud32fpointCloud;pointCloud.Resize(depth.Size);calculatePointCloud(pointCloud,depth,map);//pointCloud now contains your point cloud data}return0;
Settings Assistant for
button to enter the advanced configuration.
icon situated next to the search bar at the bottom of the Device Settings Pane allows the user to open the Search history window. This window contains the recent search inputs and can be very helpful when reusing a specific parameter repeatedly.
- Dock the Search history window
- Delete selected history (DEL key)
- Clear search history
Usually, this is caused because the device or the scene has moved during the acquisition, the scene does not contain enough 3D data or the 3D parameters are set incorrectly (e.g. under/over exposure. If changing parameters or changing setting does not help, it is recommended to perform a factory reset. If the issue persists, contact our Help Center.
