phoxi-api 1.1.0

Python wrapper for PhoXi API

PhoXi Python API

A Python wrapper for the Photoneo PhoXi API, providing a Pythonic interface to Photoneo 3D sensors via the PhoXi Control application. Supports device discovery, frame acquisition, settings management, profile control, and recording.

Requirements

• Python >= 3.10
• PhoXi Control >= 1.16.0 installed and running
  • Reading PRAW/PMRAW files with PrawReader requires PhoXi Control >= 1.17.2 installed, but not running

PhoXi Control Installation

1. Download the installer from photoneo.com/downloads/phoxi-control
2. Run the installer and follow the on-screen instructions
3. Launch PhoXi Control before using this library

For full setup instructions see the PhoXi Control - Installation.

Installation

pip install phoxi-api

Dependencies

Package	Version
numpy	>= 2.2.6
semver	>= 3.0.4

Quick Start

List available devices

Discovers all devices currently visible on the network.

import sys
from phoxi_api import PhoXiControl

phoxi_control = PhoXiControl()
if not phoxi_control.is_phoxicontrol_running():
    print("PhoXi Control is not running.")
    sys.exit(1)

device_list = phoxi_control.get_device_list(refresh=True)
print(device_list)

Acquire frames (software trigger)

Connects to a device, configures the output frame, and captures a single frame using a software trigger.

import sys
from phoxi_api import PhoXiControl, PhoXiDevice

phoxi_control = PhoXiControl()
if not phoxi_control.is_phoxicontrol_running():
    print("PhoXi Control is not running.")
    sys.exit(1)

with phoxi_control.connect("AAA-123") as device:
    device.logout_on_exit = True
    device.stop_acquisition_on_exit = True

    # Enable only the outputs you need
    frame_settings = device.frame_settings()
    all_outputs = frame_settings.value
    for key in all_outputs:
        all_outputs[key] = False
    frame_settings.value = all_outputs
    frame_settings.PointCloud.value = True
    frame_settings.DepthMap.value = True
    frame_settings.Texture.value = True

    device.set_trigger_mode(PhoXiDevice.TriggerMode.SOFTWARE)
    device.start_acquisition()

    frame_id = device.trigger_frame(True, True)
    frame = device.get_frame(frame_id)

    print(frame.PointCloud.shape)  # numpy array (H, W, 3)
    print(frame.DepthMap.shape)    # numpy array (H, W)
    print(frame.Texture.shape)     # numpy array (H, W)

Adjust settings

Reads and modifies device settings, either through attribute-style access on the settings handle or by passing a dictionary of setting keys and their new values.

import sys
from phoxi_api import PhoXiControl

phoxi_control = PhoXiControl()
if not phoxi_control.is_phoxicontrol_running():
    print("PhoXi Control is not running.")
    sys.exit(1)

with phoxi_control.connect("AAA-123") as device:
    s = device.settings()

    print(s.CapturingSettings.LaserPower.value)
    s.CapturingSettings.LaserPower.value = 1024

    # Set multiple settings at once
    device.set_settings({
        "CapturingSettings/ISO": "100",
        "CapturingSettings/LaserPower": 1024,
    })

Read a PRAW/PMRAW file

Reads metadata and frame data from a recorded .praw/.pmraw file without connecting to a device. Requires PhoXi Control >= 1.17.2 to be installed, but it does not need to be running.

from phoxi_api import PrawReader, normalize_texture

with PrawReader("/path/to/scan.pmraw", frame_index=0) as reader:
    info = reader.info()
    print(info.name, info.firmware_version)

    print(reader.list_matrices())  # e.g. ["PointCloud", "DepthMap", "Texture", ...]
    point_cloud = reader.read_matrix("PointCloud")  # numpy array (H, W, 3)

    texture = reader.read_matrix("Texture")
    img = normalize_texture(texture)  # uint8, ready for display

    print(reader.list_settings())
    # The path to the settings reflects the path from the PhoXi Control GUI.
    laser_power = reader.read_setting("Capturing Settings/Advanced/Laser Power")

Examples

Examples are available in the PhoXi Control installation directory under API/Examples/Python/, or from the photoneo-python-examples repository:

Example	Description
get_device_list.py	Discover and list connected devices
get_frame_freerun.py	Continuous frame acquisition (freerun mode)
get_frame_sw_trigger.py	Frame acquisition via software trigger
get_frame_sw_trigger_visual.py	Software trigger with Open3D point cloud visualization
get_and_set_settings.py	Read and write device settings
maintenance_tool_api_example.py	MaintenanceTool workflow: connect, adjust power, trigger, analyze, patch
read_praw_file.py	Read metadata, settings, and matrices from a PRAW/PMRAW file
read_praw_texture.py	Read a PRAW/PMRAW Texture matrix and normalize it to a displayable PNG
read_praw_two_files.py	Open two PRAW/PMRAW files at once and compare their common matrices

API Overview

Class	Purpose
PhoXiControl	Manage PhoXi Control — discover and connect devices, attach file cameras
PhoXiDevice	Control device settings, trigger frames, control acquisition and recording
PhoXiSettings	Settings handle with attribute-based access to settings and other auxiliary functions like get/set/min/max/enum
PhoXiFrame	Frame container with frame info Info and arrays like PointCloud, DepthMap, NormalMap, Texture, ...
PrawReader	Read metadata, settings, and matrices from recorded PRAW/PMRAW files, without a device connection

Exceptions: PhoXiError, PhoXiTimeoutError, PhoXiDisconnectedError, PhoXiErrorResponse, and others — all inheriting from PhoXiError.

Documentation

Full API reference and guides are available at docs.photoneo.com.

License

MIT — Copyright 2020 Zebra Technologies Ltd, Inc.

Support

• Contact us at the Help Center
• Visit Photoneo support pages at photoneo.com/support.