PhoXi Python API

PhoXi Python API version aliases: 1.1.1

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.1.1.

phoxi_api: Python wrapper for PhoXi API

class phoxi_api_v1_1_1.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_v1_1_1.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

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 device settings to factory settings unselecting the active profile (NON_SELECTED) while also resetting the current startup profile to NON_SELECTED. The profile that was active before this call keeps its own stored settings unchanged.

startup_profile() → str

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 | None

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 | None

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_v1_1_1.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_v1_1_1.PhoXiFrame(info: dict, mats: dict, additional_components: dict)

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

Variables:

  • Successful (bool|None) – Whether grabbing was successful

  • 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

  • Messages (list|None) –

    List of diagnostic messages associated with the frame. Each message is a dictionary with the following fields:

    • code (int): Message code, one of:

      • -1 — Unknown

      • 0 — Legacy error

      • 10 — Marker recognition success

      • 11 — Marker recognition failure

      • 20 — Stereo maintenance success

      • 21 — Stereo maintenance failure

      • 30 — Marker dot correction success

      • 31 — Marker dot correction failure

      • 40 — Projector throttling active

      • 41 — Projector laser overcurrent detected

      • 42 — Projector command thrown away

      • 50 — Feature not supported by PhoXi Control

    • severity (int): Severity level, one of:

      • 0 — Info

      • 1 — Warning

      • 2 — Error

    • text (str): Human-readable description of the message

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

exception phoxi_api_v1_1_1.exceptions.PhoXiError

Bases: Exception

Generic error and base for other exceptions raised from phoxi_api module

exception phoxi_api_v1_1_1.exceptions.PhoXiCommandError

Bases: PhoXiError

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

exception phoxi_api_v1_1_1.exceptions.PhoXiTimeoutError

Bases: PhoXiError

Generic timeout error which occurred during command execution

exception phoxi_api_v1_1_1.exceptions.PhoXiUninitializedError

Bases: PhoXiError

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

exception phoxi_api_v1_1_1.exceptions.PhoXiDisconnectedError

Bases: PhoXiError

Error raised when device disconnects during command execution

exception phoxi_api_v1_1_1.exceptions.PhoXiInvalidResponseError

Bases: PhoXiCommandError

Error raised when PhoXi C API returned invalid response

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

Bases: PhoXiCommandError

Error raised when PhoXi C API returned valid error response

exception phoxi_api_v1_1_1.exceptions.PhoXiFrameError

Bases: PhoXiError

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

Maintenance Tool

New in version 1.1.1. Provides programmatic access to the PhoXi Control Maintenance Tool for calibration patch workflows.

class phoxi_api_v1_1_1.MaintenanceTool

Python wrapper for the MaintenanceTool C API.

Locates the native library inside the PhoXi Control installation directory specified by the PHOXI_CONTROL_PATH environment variable and exposes the calibration workflow as method calls.

get_maintenance_tool_api_version() → tuple[int, int, int]

Get the MaintenanceTool API version.

Returns:

A (major, minor, patch) version tuple.

Return type:

tuple[int, int, int]

check_phoxi_control_compatibility() → bool

Check PhoXiControl compatibility.

Returns:

True if compatible, False if not compatible or if compatibility could not be determined.

Return type:

bool

connect(serial_number: str, output_directory_path: str | None = None, validation_target_path: str | None = None, store_praw_files: bool = False) → MaintenanceToolDevice

Connect to a device and return a handle for operating it.

The returned MaintenanceToolDevice can be used as a context manager so the connection is closed automatically on exit:

with mt.connect("SN12345678", "/output") as device:
    device.trigger()
Parameters:

  • serial_number (str) – Serial number of the device to connect to.

  • output_directory_path (str or None) – Path where output files will be stored.

  • validation_target_path (str or None) – Path to the validation target file.

  • store_praw_files (bool) – Whether to store raw scan files.

Returns:

A handle for the active device connection.

Return type:

MaintenanceToolDevice

Raises:

phoxi_api_v1_1_1.exceptions.PhoXiError – If the device was already connected (requested parameters would be ignored), PhoXiControl is not running, the device is not found, another device is already connected, or the connection fails.

class phoxi_api_v1_1_1.MaintenanceToolDevice(lib)

Handle for an active device connection returned by MaintenanceTool.connect().

Supports the context manager protocol — the connection is closed automatically when the with block exits, even if an exception is raised.

Example usage:

mt = MaintenanceTool()
with mt.connect("SN12345678", "/output") as device:
    device.adjust_power()
    result = device.trigger()
    score = device.analyze()
    device.patch()
disconnect() → None

Disconnect from the device.

Raises:

phoxi_api_v1_1_1.exceptions.PhoXiError – If no device is connected.

adjust_power() → None

Adjust laser power and LED intensity.

Raises:

phoxi_api_v1_1_1.exceptions.PhoXiError – If no device is connected or the adjustment does not achieve a satisfactory outcome.

trigger() → TriggerResult

Trigger a scan.

Returns:

Scan counts from the trigger operation.

Return type:

TriggerResult

Raises:

phoxi_api_v1_1_1.exceptions.PhoXiError – If no device is connected, the validation target is not recognized, acquisition fails, or the pattern is unstable or tilted.

analyze() → float

Analyze acquired scans.

Returns:

Area occupancy score indicating how well the validation target occupies the scan area. Higher is better.

Return type:

float

Raises:

phoxi_api_v1_1_1.exceptions.PhoXiError – If no device is connected, the area occupancy criteria are not fulfilled, the device cannot be patched, or analysis fails.

patch() → None

Apply a correction patch to the device.

Raises:

phoxi_api_v1_1_1.exceptions.PhoXiError – If no device is connected, the patch was not prepared, or patch application fails.

restore() → None

Restore the device to factory calibration.

Raises:

phoxi_api_v1_1_1.exceptions.PhoXiError – If no device is connected or restoration fails.

class phoxi_api_v1_1_1.TriggerResult(count_of_recognized_marker_points: int, count_of_acquired_scans: int)

Result of a successful scan trigger.

Variables:

  • count_of_recognized_marker_points (int) – Number of marker points recognized in the acquired scans.

  • count_of_acquired_scans (int) – Total number of scans acquired.

count_of_recognized_marker_points: int

Alias for field number 0

count_of_acquired_scans: int

Alias for field number 1

PRAW Reader

New in version 1.1.1. Reads proprietary Photoneo RAW files (*.praw, *.pmraw) offline, without requiring an active instance of PhoXi Control or a connected device.

class phoxi_api_v1_1_1.PrawReader(path: str, frame_index: int = 0, lib_path: str | None = None)

Reader for PRAW and PMRAW files via the PrawExtractor C API.

Supports the context manager protocol so the file is closed automatically:

with PrawReader("/path/to/scan.pmraw", frame_index=2) as reader:
    info = reader.info()
    depth = reader.read_matrix("DepthMap")
Parameters:

  • path – Path to the PRAW or PMRAW file.

  • frame_index – For PMRAW files, the zero-based frame index to open. Ignored for PRAW files (which always contain a single frame).

  • lib_path – Explicit path to the native PrawExtractor shared library. When None, the library is located using the PHOXI_CONTROL_PATH environment variable.

Raises:

phoxi_api_v1_1_1.exceptions.PhoXiError – If the library cannot be loaded or the file cannot be opened.

close() → None

Close the file and release all resources held by the native library.

info() → PrawInfo

Return metadata for the opened file.

Return type:

PrawInfo

Raises:

phoxi_api_v1_1_1.exceptions.PhoXiError – On native-library error.

list_settings() → list[str]

Return all available setting paths for this frame.

Return type:

list[str]

Raises:

phoxi_api_v1_1_1.exceptions.PhoXiError – On native-library error.

list_matrices() → list[str]

Return all available matrix paths for this frame.

Return type:

list[str]

Raises:

phoxi_api_v1_1_1.exceptions.PhoXiError – On native-library error.

read_setting(path: str) → bool | int | float | str | None

Read a single setting value by path.

Parameters:

path – Setting path as returned by list_settings().

Returns:

The setting value, or None if the path does not exist in this frame.

Raises:

phoxi_api_v1_1_1.exceptions.PhoXiError – On native-library error other than path-not-found.

read_matrix(path: str) → object | None

Read a matrix as a numpy array.

Parameters:

path – Matrix path as returned by list_matrices().

Returns:

A 2-D (rows, cols) or 3-D (rows, cols, channels) numpy array, or None if the path does not exist in this frame.

Raises:

phoxi_api_v1_1_1.exceptions.PhoXiError – On native-library error other than path-not-found.

class phoxi_api_v1_1_1.PrawInfo(frames_count: int, name: str, variant: str, firmware_version: str, device_id: str, phoxi_control_version: str)

Metadata extracted from a PRAW or PMRAW file header.

Variables:

  • frames_count (int) – Total number of frames in the archive (always 1 for PRAW).

  • name (str) – Device product name (e.g. "MotionCam-3D").

  • variant (str) – Device variant (e.g. "M").

  • firmware_version (str) – Firmware version string (e.g. "1.17.1").

  • device_id (str) – Device serial number.

  • phoxi_control_version (str) – PhoXi Control version string (e.g. "1.16.2").

frames_count: int

Alias for field number 0

name: str

Alias for field number 1

variant: str

Alias for field number 2

firmware_version: str

Alias for field number 3

device_id: str

Alias for field number 4

phoxi_control_version: str

Alias for field number 5

phoxi_api_v1_1_1.normalize_texture(mat: object, percentile: float = 2.0) → object

Normalize a texture matrix to uint8 [0, 255] using percentile-clipped min/max.

Produces the same result as the Auto Intensity normalization applied by PhoXi Control when saving Texture images. The bottom and top percentile % of values are clipped before scaling, making the result robust to outlier pixels. For RGB textures all channels are flattened together for the percentile calculation and scaled uniformly, matching PhoXi Control behaviour.

Typical use — render a 12-bit grayscale or RGB Texture as a displayable image:

mat = reader.read_matrix("Texture")
img = normalize_texture(mat)  # uint8, same shape as mat
Parameters:

  • mat – Input numpy array (any dtype, 1-channel or 3-channel RGB).

  • percentile – Fraction (in percent) to clip from each tail. Default 2.0 matches the PhoXi Control default.

Returns:

uint8 numpy array with the same shape as mat, values in [0, 255].