PhoXi Python API

PhoXi Python API version aliases: 1.0.0

This page documents the public PhoXi Python API used in client applications. It focuses on user-facing classes, methods, and exceptions. The PhoXi Python API is versioned independently of the 3D Sensors software; this is version 1.0.0.

phoxi_api: Python wrapper for PhoXi API

class phoxi_api.PhoXiControl(api_lib_path: str | None = None)

Class providing methods for interacting with PhoXi Control application, e.g. connecting to a device, obtaining list of discovered devices, etc…

Parameters:

api_lib_path – Path to PhoXi API library (PhoXi_API.dll on Windows or libPhoXi_API.so on Linux). If None library will be searched in path specified by environment variable PHOXI_CONTROL_PATH

create(device_id: str) → PhoXiDevice

Create a new PhoXiDevice instance without connecting device to PhoXi Control. Useful for creating own context managers, e.g.:

from contextlib import contextmanager
from phoxi_api import PhoXiControl, PhoXiDevice


@contextmanager
def connect_device(device_id: str):
    phoxi_control = PhoXiControl()
    device = phoxi_control.create(device_id)
    try:
        while not api.can_connect(device_id):
            time.sleep(0.5)

        device.connect()

        # Setup device as needed, or do other common stuff...
        yield device
    finally:
        device.disconnect()
Parameters:

device_id – ID of a discovered device

Returns:

PhoXiDevice instance

connect(device_id: str, address: str | None = None, timeout_ms: int = 31536000000) → PhoXiDevice

Connect PhoXi Control application to a discovered device with the device_id. If an address is specified and a device with the device_id is not discovered, then creates a new direct connection with the device_id and connects to it using the address. If the direct connection with the device_id already exists, then this is treated as a discovered device.

from phoxi_api import PhoXiControl, PhoXiDevice

phoxi_control = PhoXiControl()
with phoxi_control.connect("AAA-123") as device:
    ...
Parameters:

  • device_id – ID of a discovered device or ID of a new direct connection

  • address – IP (v4 or v6) address or a hostname for the new direct connection

  • timeout_ms – Time in milliseconds to wait for a device with device_id to become connectible. Default is INFINITE_TIMEOUT (~1year)

Returns:

PhoXiDevice instance

can_connect(device_id) → bool

Checks if a device with device_id can be connected to PhoXi Control application, i.e. is discovered and has status “Ready”.

Parameters:

device_id – ID to check

Returns:

True if connectable, otherwise False

attach_file_camera(name: str, paths: str | list[str]) → str

Attach file camera to PhoXi Control application.

Parameters:

  • name – Name of the file camera

  • paths – Path or list of paths to file camera files (.praw, .pmraw)

Returns:

device_id of attached file camera for PhoXiControl.connect() method

detach_file_camera(name: str) → None

Detach file camera from PhoXi Control application.

Parameters:

name – device_id of the file camera to detach

Returns:

None

get_device_list(refresh: bool = False) → list[dict]

Get a list of devices discovered by PhoXi Control application.

Parameters:

refresh – Refresh the device discovery before returning the list of devices (may take few seconds)

Returns:

List of devices discovered by PhoXi Control application.

reboot(device_id: str) → None

Perform a device reboot.

Parameters:

device_id – ID of the device to reboot

Returns:

None

shutdown(device_id: str) → None

Perform a device shutdown.

Parameters:

device_id (str) – ID of the device to shut down

Returns:

None

factory_reset(device_id: str) → None

Perform a factory reset of the device.

Parameters:

device_id – ID of the device to factory reset

Returns:

None

log_download(device_id: str, logfile_path: str, overwrite: bool = False) → None

Download a logfile from the device.

Parameters:

  • device_id – ID of the device to download logfiles from

  • logfile_path – Path to store the logfile

  • overwrite – Allow to overwrite an existing logfile if it already exists at logfile_path

Returns:

None

is_phoxicontrol_running() → bool

Check if there is an instance of PhoXi Control application running.

Returns:

True if PhoXi Control application is running otherwise False

get_phoxicontrol_version() → str

Get version of PhoXi Control application running.

Returns:

Short version string e.g. 1.17.0

minimize_phoxicontrol() → None

Minimize PhoXi Control application.

Returns:

None

get_api_version() → str

Get version of the underlying PhoXi C API.

Returns:

Short version string e.g. 1.17.0

get_api_sem_version() → str

Get version of the underlying PhoXi C API in semver format.

Returns:

Version string e.g. 1.17.0+203.sha.8fe1e4067b

is_authenticated() → bool

Check if client application is authenticated to PhoXi Control application.

Returns:

True if authenticated otherwise False

authenticate(password: str) → bool

Perform authentication to PhoXi Control application.

Parameters:

password – Password to authenticate with

Returns:

True if authenticated otherwise False

class phoxi_api.PhoXiDevice(device_id: str, api: PhoXiWrapper)

Class to represent and manage a connection to a device. This class also provides methods to interact with the device and perform operations like getting and setting settings, triggering frames, …

Warning

Do not instantiate this class directly. Use PhoXiControl.connect() or PhoXiControl.create() instead.

If device connection is handled by context manager e.g. using with statement, the disconnect behaviour when __exit__() is called can be controlled using these variables:

Variables:

  • logout_on_exit (bool) – Disconnect / Log out device from PhoXi Control application on instance disconnect, default: False

  • stop_acquisition_on_exit (bool) – Stop device acquisition before disconnecting this instance, default True

Settings validation behaviour when setting values can be controlled using:

Variables:

strict_values (bool) – Reject values outside the min/max range or not present in the enum list when setting settings. When False, the device silently clamps or rounds the value to the nearest valid value instead. Default: True

class TriggerMode(*values)

Enum of available trigger modes. See PhoXiDevice.trigger_mode() and PhoXiDevice.set_trigger_mode().

SOFTWARE = 'Software'

Perform single acquisition of a frame when triggered via call PhoXiDevice.trigger_frame().

FREERUN = 'Freerun'

Perform continuous acquisition of frames when acquisition is started. See PhoXiDevice.start_acquisition() and PhoXiDevice.stop_acquisition().

info() → dict

Get the device info.

Returns:

Device information

device_schema() → dict

Get a schema of available device commands and operations accepted by PhoXi C API.

Returns:

Device schema

connect(address: str | None = None) → None

Connect this instance to a discovered device with the device_id. If an address is specified and a device with the device_id is not discovered, then creates a new direct connection with the device_id and connects to it using the address. If the direct connection with the device_id already exists, then this is treated as a discovered device.

Parameters:

address – IP (v4 or v6) address or hostname for direct connection

disconnect(logout: bool = False, stop_acquisition: bool = True) → None

Disconnect this instance from device. By default, this will also disconnect the device from PhoXi Control application and stop the acquisition if running.

Parameters:

  • logout – Logout/Disconnect the device from PhoXi Control

  • stop_acquisition – Stop the acquisition before disconnecting this instance

is_connected() → bool

Check if this instance is connected to device.

Returns:

True if connected, otherwise False

is_acquiring() → bool

Check the acquisition status of the device.

Returns:

True if acquisition is running, otherwise False

start_acquisition() → None

Start the acquisition.

stop_acquisition() → None

Stop the acquisition.

trigger_mode() → TriggerMode

Get the current trigger mode of the device.

Returns:

Current trigger mode

set_trigger_mode(trigger_mode: TriggerMode) → None

Set trigger mode of the device.

Parameters:

trigger_mode – Trigger mode to set

trigger_frame(wait_accept: bool = True, wait_grabbing_end: bool = False, custom_message: str | None = None) → int

Trigger a frame in the SOFTWARE trigger mode.

Parameters:

  • wait_accept – Wait until the device is ready to perform trigger

  • wait_grabbing_end – Wait for the image grabbing process to end

  • custom_message – A message to attach to the frame

Returns:

ID of the frame triggered

get_frame(frame_id: int | None = None, timeout_ms: int = 10000) → PhoXiFrame

Consume the latest or frame_id frame.

Parameters:

  • frame_id – ID of the frame to consume returned by PhoXiDevice.trigger_frame()

  • timeout_ms – Time to wait for the latest or frame_id frame to become available

Returns:

Requested frame

save_last_output(file_path: str, frame_id: int | None = None, options: dict | None = None) → None

Save the last frame or frame_id frame to file.

Parameters:

  • file_path – File path to save the frame. Must contain supported file extension

  • frame_id – ID of the frame to save returned by PhoXiDevice.trigger_frame()

  • options – Options described by the RecordingOptionsSchema.json schema located at $PHOXI_CONTROL_PATH/API. This function expects only options from json node properties/containers/properties/<TYPE>/properties, where <TYPE> is related to file extension provided in the file_path.

lock_gui() → None

Lock the GUI controls in PhoXi Control application for this device.

unlock_gui() → None

Unlock the GUI controls in PhoXi Control application for this device.

start_recording(options: dict, persist_options: bool = False) → None

Start the recording of frames to location and formats specified in the options.

Parameters:

  • options – Options described by the RecordingOptionsSchema.json schema located at $PHOXI_CONTROL_PATH/API.

  • persist_options – Persist the options for this device, the options will be applied again when the device is connected

stop_recording() → None

Stop the recording of frames.

is_recording() → bool

Get the recording status for this device.

Returns:

True if recording is started, otherwise False

recording_options() → dict

Get the current recording options for this device.

Returns:

Options described by the RecordingOptionsSchema.json schema located at $PHOXI_CONTROL_PATH/API.

last_recorded_frame_index() → int | None

Get last recorded frame index for this device.

Returns:

Index

profiles() → list[dict]

Get the list of profiles for this device.

Returns:

List of profiles available on the device

active_profile() → str | None

Get the active profile for this device.

Returns:

Active profile name

set_active_profile(profile: str) → None

Set active profile for this device.

Parameters:

profile – Profile name from list of available profiles, see PhoXiDevice.profiles()

reset_active_profile() → None

Reset the active profile to DEFAULT profile settings.

startup_profile() → str | None

Get the startup profile for this device.

Returns:

Startup profile name

set_startup_profile(profile: str) → None

Set startup profile for this device.

Parameters:

profile – Profile name from list of available profiles, see PhoXiDevice.profiles()

create_profile(profile: str) → None

Create a profile from current settings applied to this device.

Parameters:

profile – Name of the new profile to create

delete_profile(profile: str) → None

Delete a profile from this device. Note: Factory profiles can not be deleted.

Parameters:

profile – Profile name from list of available profiles, see PhoXiDevice.profiles()

update_profile(profile: str) → None

Apply current device settings to an existing profile from this device. Note: Factory profiles can not be updated.

Parameters:

profile – Profile name from list of available profiles, see PhoXiDevice.profiles()

import_profile(profile: str, profile_data: bytes) → None

Import a profile to this device from a profile data (e.g. read from file,…).

Parameters:

  • profile – Profile name of new profile created by importing

  • profile_data – Binary profile data

export_profile(profile: str) → bytes

Export a profile from this device to binary profile data.

Parameters:

profile – Profile name from list of available profiles, see PhoXiDevice.profiles()

Returns:

Binary profile data

settings(access_type: str = 'stable') → PhoXiSettings | None

Get settings handle of this device. Handle can be used to get or set settings of this device.

Parameters:

access_type –

  • “stable” - stable settings defined by PhoXi C API (see PhoXiDevice.device_schema())

    handle = device.settings()
handle.CapturingSettings.LaserPower.value = 1024
laser_power = handle.CapturingSettings.LaserPower.value

  • ”direct” - settings in structure of PhoXi Control GUI. Spaces in setting names must be replaced with double underscores

    handle = device.settings(access_type="direct")
handle.General__Settings.Laser__Power.value = 1024
laser_power = handle.General__Settings.Laser__Power.value

Returns:

Settings handle

get_settings(settings: list[str], access_type: str = 'stable')

Get requested settings from this device.

Parameters:

  • settings – List of the settings to obtain from this device

  • access_type –

    • “stable” - stable settings defined by PhoXi C API (see PhoXiDevice.device_schema())

      settings = ["CapturingSettings/LaserPower", ...]

    • ”direct” - settings in structure of PhoXi Control GUI

      settings = ["General Settings/Laser Power", ...]

Returns:

Tuple of settings values and settings errors, where:

  • first - dictionary of settings and values

  • second - dictionary of settings and error messages

set_settings(settings: dict, access_type: str = 'stable') → dict

Set settings to this device.

Parameters:

  • settings – Dictionary of settings and values

  • access_type –

    • “stable” - stable settings defined by PhoXi C API (see PhoXiDevice.device_schema())

      settings = {"CapturingSettings/LaserPower" : 1024, ...}

    • ”direct” - settings in structure of PhoXi Control GUI

      settings = {"General Settings/Laser Power" : 1024, ...}

Returns:

Dictionary of settings and error messages

save_settings() → None

Save current settings to the active user profile. Note: Factory profiles can not be modified.

frame_settings() → PhoXiSettings | None

Get frame settings handle of this device. Handle can be used to enable or disable frame components.

frame_settings = device.frame_settings()
frame_settings.PointCloud.value = True
frame_settings.DepthMap.value = False
Returns:

Frame settings handle

get_frame_settings(components: list[str])

Get requested frame settings from this device.

Parameters:

components –

List of components to obtain from device

components = ["PointCloud", "DepthMap", ...]

Returns:

Tuple of components values and components errors

  • first - dictionary of components and values

  • second - dictionary of components and error messages

set_frame_settings(components: dict) → dict

Set frame settings to this device.

Parameters:

components –

Dictionary of components and values

components = {"PointCloud" : True, "DepthMap" : False, ...}

Returns:

Dictionary of components and error messages

class phoxi_api.PhoXiSettings(settings_schema: dict, path: list[str] | None = None, getter=None, setter=None)

Class providing access and means to get and set the device settings.

Warning

Do not instantiate this class directly. Use PhoXiDevice.settings() or PhoXiDevice.frame_settings() to obtain settings handles for a device.

Variables:

  • <setting_path_part> (PhoXiSettings) –

    Attribute representing one part of a device setting path. In general if the setting path is e.g. CapturingSettings/LaserPower it will translate to attributes .CapturingSettings.LaserPower. This attribute is also of the PhoXiSettings type, thus methods below can be used to access the value, test the setting availability or to obtain minimum and maximum values, etc…

    E.g. to check if the setting CapturingSettings/LaserPower is settable or gettable:

    settings = device.settings()
if settings.CapturingSettings.LaserPower.can_get():
    ...
if settings.CapturingSettings.LaserPower.can_set():
    ...

  • value –

    Special attribute used to access the value of a setting. E.g. accessing the setting CapturingSettings/LaserPower value:

    settings = device.settings()
laser_power = settings.CapturingSettings.LaserPower.value  # Get value
settings.CapturingSettings.LaserPower.value = 1024  # Set value

    This attribute can be also used to access a group of settings and modify them at once. The expected type of this attribute in this case is dict.

    settings = device.settings()
# Get group of settings
capturing_settings = settings.CapturingSettings.value
laser_power = capturing_settings["LaserPower"]
led_power = capturing_settings["LEDPower"]

# Set group of settings
capturing_settings["LaserPower"] = 1024
capturing_settings["LEDPower"] = 2048
settings.CapturingSettings.value = capturing_settings

    If the setting accessed via attributes is not available, or if PhoXiDevice.strict_values is True and the value is outside the allowed min/max range or not in the enum list, an exception will be raised. To access the setting in a more relaxed way see methods PhoXiSettings.get() and PhoXiSettings.set().

get(default=None)

Get the setting value.

Parameters:

default – Default value

Returns:

Value of the setting if available and gettable, otherwise default on error.

set(value) → bool

Set the setting value.

Values outside the min/max range or not present in the enum list are rejected when PhoXiDevice.strict_values is True (default).

Parameters:

value – Value to set

Returns:

True if setting was set successfully, otherwise False on error

can_get()

Check if the setting is gettable.

Returns:

True if setting is gettable otherwise False

can_set()

Check if the setting is settable.

Returns:

True if setting is settable otherwise False

type() → str | None

Get string representation of the setting type.

Returns:

Type or None otherwise

enum() → list | None

Get list of available values.

Returns:

List of values or None if setting does not accept enum

min()

Get the minimum value.

Returns:

Minimum value or None if the minimum value is not specified

max()

Get the maximum value.

Returns:

Maximum value or None if the maximum value is not specified

class phoxi_api.PhoXiFrame(info: dict, mats: dict, additional_components: dict)

Class representing one frame obtained from the device via PhoXiDevice.get_frame()

Variables:

  • Info (dict) – Dictionary of information about the frame

  • PointCloud (np.ndarray|None) – Array with the PointCloud data

  • NormalMap (np.ndarray|None) – Array with the NormalMap data

  • DepthMap (np.ndarray|None) – Array with the DepthMap data

  • ConfidenceMap (np.ndarray|None) – Array with the ConfidenceMap data

  • EventMap (np.ndarray|None) – Array with the EventMap data

  • Texture (np.ndarray|None) – Array with the Texture data

  • ColorCameraImage (np.ndarray|None) – Array with the ColorCameraImage data

  • CustomMessage (str|None) – Custom message attached to the frame by PhoXiDevice.trigger_frame()

exception phoxi_api.exceptions.PhoXiError

Bases: Exception

Generic error and base for other exceptions raised from phoxi_api module

exception phoxi_api.exceptions.PhoXiCommandError

Bases: PhoXiError

Error raised when PhoXi C API failed command execution or unspecified error happened

exception phoxi_api.exceptions.PhoXiTimeoutError

Bases: PhoXiError

Generic timeout error which occurred during command execution

exception phoxi_api.exceptions.PhoXiUninitializedError

Bases: PhoXiError

Error raised when PhoXi C API is uninitialized and command execution is performed

exception phoxi_api.exceptions.PhoXiDisconnectedError

Bases: PhoXiError

Error raised when device disconnects during command execution

exception phoxi_api.exceptions.PhoXiInvalidResponseError

Bases: PhoXiCommandError

Error raised when PhoXi C API returned invalid response

exception phoxi_api.exceptions.PhoXiErrorResponse(status, message, error_code=None)

Bases: PhoXiCommandError

Error raised when PhoXi C API returned valid error response

exception phoxi_api.exceptions.PhoXiFrameError

Bases: PhoXiError

Error raised when PhoXi C API failed to obtain a frame or unspecified frame related error happened