epctofcam Library Documentation
===============================

The ``epctofcam`` library provides a high-level interface for capturing and processing data
from espros ToF sensors. It acquires raw ToF images from the sensor via the Linux V4L2
API and computes calibrated distance and amplitude images from the raw DCS frames. 

.. image:: _static/diagrams/epc_architecture.drawio.png
   :alt: epctofcam library overview
   :align: center

Target Platforms
----------------
This library is intended to run on all ARM based APU's but has mainly been tested on the Raspberry Pi 5. 

Requirements
------------
- Compatible espros ToF-Sensor (e.g. :external+epc670_tof_hat:doc:`epc670 ToF HAT+ <index>`) and :external+epc_device_drivers:doc:`device drivers <index>` must be installed and accessible on the system.
- The Python bindings expect a Python version >= 3.10

.. _installation:

Installation
------------
**Python bindings:**

.. code-block:: bash

   # Fresh installation
   pip install epc-tofcam-native

   # Update to the newest version
   pip install --upgrade epc-tofcam-native

   # Install a specific version
   pip install epc-tofcam-native=x.x.x

**C++ library:**

1. Download and add ESPROS GPG keyring to your keyrings

.. code-block:: bash

   sudo wget http://apt.espros.com/espros-archive-keyring.gpg -P /usr/share/keyrings/

2. Add the apt source to your system

.. code-block:: bash
   
   echo "Types: deb
   URIs: http://apt.espros.com
   Suites: trixie
   Components: main
   Signed-By: /usr/share/keyrings/espros-archive-keyring.gpg" | sudo tee /etc/apt/sources.list.d/espros.sources

3. Update and install the library

.. code-block:: bash

   # Fetch newest version informations
   sudo apt update

   # Fresh installation of libepctofcam
   sudo apt install libepctofcam

   # Update to the newest version
   sudo apt install --only-upgrade libepctofcam

   # Update to a specific version
   sudo apt install libepctofcam==x.x.x


Basic usage
------------

To get a quick overview of how to use the library, check out the :ref:`python_api` and :ref:`cpp_api` reference pages:

For a more complete example of capturing and visualizing ToF data, see the :ref:`python_example` and :ref:`cpp_example` pages in the :ref:`examples` section.


.. toctree::
   :maxdepth: 2
   :caption: epctofcam Library:
   :hidden:

   examples/examples.rst
   api/api.rst

.. toctree::
   :maxdepth: 2
   :caption: Related Products:
   :hidden:

   espros drivers <https://docs.espros.com/epc_device_drivers/>
   epc670 ToF HAT+ <https://docs.espros.com/epc670_tof_hat/>
   epc670 Starter Kit <https://docs.espros.com/epc670_starter_kit/>