Metadata-Version: 2.4
Name: phoxi-api
Version: 1.1.0
Summary: Python wrapper for PhoXi API
Keywords: 3D Camera,3D Scanner,Computer Vision,Image Processing,PhoXi Control,PhoXi
Author: Ján Packo, Ivan Varga, Peter Kováč
License-Expression: MIT
License-File: LICENSE.txt
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Topic :: Scientific/Engineering :: Image Processing
Classifier: Topic :: Software Development
Requires-Dist: numpy>=2.2.6
Requires-Dist: semver>=3.0.4
Requires-Dist: sphinx>=8.1.3 ; extra == 'docs'
Requires-Dist: sphinx-copybutton>=0.5.2 ; extra == 'docs'
Requires-Dist: sphinx-multiversion>=0.2.4 ; extra == 'docs'
Requires-Dist: sphinx-rtd-theme>=3.1.0 ; extra == 'docs'
Requires-Dist: sphinx-tabs>=3.5.0 ; extra == 'docs'
Requires-Dist: sphinx-reredirects>=0.1.6 ; extra == 'docs'
Maintainer: Ján Packo, Ivan Varga, Peter Kováč
Requires-Python: >=3.10
Project-URL: documentation, https://docs.photoneo.com/docs/api/python/phoxi_api.html
Project-URL: examples, https://github.com/photoneo-3d/photoneo-python-examples/tree/main/PhoXi-API
Project-URL: homepage, https://www.photoneo.com
Project-URL: issues, https://www.photoneo.com/support
Provides-Extra: docs
Description-Content-Type: text/markdown

# PhoXi Python API
![image](https://photoneo.com/files/dw/dw/github/Personal_Linkedin_banner_v4.png)

A Python wrapper for the [Photoneo](https://www.photoneo.com) 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](https://www.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](https://docs.photoneo.com/docs/PXC/PXC_manual.html#installation).

## Installation

```bash
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.

```python
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.

```python
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.

```python
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.

```python
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](https://github.com/photoneo-3d/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](https://docs.photoneo.com/docs/api/python/phoxi_api.html).

## License

[MIT](LICENSE.txt) — Copyright 2020 Zebra Technologies Ltd, Inc.

## Support

 - Contact us at the [Help Center](https://www.photoneo.com/Help-Center)
 - Visit Photoneo support pages at [photoneo.com/support](https://www.photoneo.com/support).