.. _python_api:

Python API Reference
====================

The ``epc_tofcam_native`` module provides Python bindings for the ``libepctofcam`` library,
built with pybind11. All frame data is returned as 2D ``numpy`` arrays.

Overview
--------
The API consists of the following main classes:

- :py:class:`epc_tofcam_native.TOFCam` — camera control: open/close, stream management, control parameters
- :py:class:`epc_tofcam_native.TOFFrame` — frame data access: DCS, amplitude, distance, phase and metadata

Frame data is provided as numpy arrays and its memory is owned and managed by the underlying C++ frame object.

Quick Start
-----------

.. literalinclude:: ../../../samples/python_examples/src/python_api_example.py
   :language: python
   :linenos:

Frame Types
-----------

Use the following frame types with ``TOFFrame.get()`` to access typed frame data:

+------------------------------------+------------+----------+---------------------------+
| Frame type                         | Data type  | Unit     | Description               |
+====================================+============+==========+===========================+
| ``FrameType.DCS``                  | uint16     | LSB      | Raw DCS images            |
+------------------------------------+------------+----------+---------------------------+
| ``FrameType.AMPLITUDE``            | uint16     | LSB      | Amplitude image           |
+------------------------------------+------------+----------+---------------------------+
| ``FrameType.DISTANCE``             | uint16     | mm       | Computed distance image   |
+------------------------------------+------------+----------+---------------------------+
| ``FrameType.PHASE``                | float      | radian   | Phase image               |
+------------------------------------+------------+----------+---------------------------+

Logging
-------

The module uses Python's standard ``logging`` module under the logger name
``epc_tofcam_native``. All internal C++ log messages are routed through this logger.
Configure it as usual:

.. code-block:: python

   import logging
   logging.getLogger("epc_tofcam_native").setLevel(logging.DEBUG)


API reference:
--------------

.. py:module:: epc_tofcam_native

.. autoclass:: TOFCam
   :members:

.. autoclass:: TOFFrame
   :members:

.. autoclass:: TOFSensor

.. autoclass:: FrameType

.. autoclass:: TOFControl

.. autoclass:: AcquisitionMode

.. autoclass:: TOFMetadata
   :members:
