.. _cpp_example:

C++ Example
===========

This example demonstrates how to use the ``epc::TOFCam`` API to capture distance and amplitude frames
from the EPC670 ToF camera module and display them in real time using OpenCV.


.. image:: ../_static/images/cpp_example_screenshot.png
   :alt: C++ example result
   :align: center
   :width: 60%

Prerequisites
-------------

- A connected EPC670 ToF camera module
- OpenCV 4.10 or later installed on the system (e.g. ``sudo apt install libopencv-dev``)
- libepctofcam installed, see :ref:`Installation <installation>` for details.

Build
-----

Compile and link the :ref:`example code <cpp_example_source>` against the preinstalled ``libepctofcam`` library:

.. code-block:: bash

   g++ cpp_example.cpp -o cpp_example \
       -std=c++17 \
       -lepctofcam \
       $(pkg-config --cflags --libs opencv4)

If ``pkg-config`` is not available for OpenCV, specify the flags manually:

.. code-block:: bash

   g++ cpp_example.cpp -o cpp_example \
       -std=c++17 \
       -lepctofcam \
       -I/usr/include/opencv4 \
       -lopencv_core -lopencv_highgui -lopencv_imgproc

Run
---

.. code-block:: bash

   ./cpp_example

Press any key in the OpenCV window to stop the stream and exit.

Parameters
----------

+-------------------------------------+---------------------+--------------------------------------------+
| Parameter                           | Value               | Description                                |
+=====================================+=====================+============================================+
| ``ACQUISITION_MODE``                | ``DIST_AMP_HDR``    | Acquisition mode                           |
+-------------------------------------+---------------------+--------------------------------------------+
| ``HDR_INTEGRATION_TIME1_US``        | 40 µs               | HDR integration time (short)               |
+-------------------------------------+---------------------+--------------------------------------------+
| ``HDR_INTEGRATION_TIME2_US``        | 400 µs              | HDR integration time (medium)              |
+-------------------------------------+---------------------+--------------------------------------------+
| ``HDR_INTEGRATION_TIME3_US``        | 4000 µs             | HDR integration time (long)                |
+-------------------------------------+---------------------+--------------------------------------------+
| ``MODULATION_FREQ_HZ``              | 10 MHz              | Modulation frequency                       |
+-------------------------------------+---------------------+--------------------------------------------+

How It Works
------------

1. **Open** the camera with ``cam.open()``.
2. **Configure** the acquisition mode, exposure time and modulation frequency via ``cam.setControl()``.
3. **Start the stream** with ``cam.startStream()``.
4. In a loop, **capture frames** with ``cam.captureFrame()`` and copy the distance and amplitude data
   into OpenCV matrices using ``std::memcpy``.
5. The distance image is **scaled** to the unambiguity range of the sensor and **colorized** with the
   JET colormap. The amplitude image is colorized with the VIRIDIS colormap.
6. Both images are **upscaled 2x** using nearest-neighbor interpolation for better visibility on screen.
7. When a key is pressed, the stream is **stopped** with ``cam.stopStream()`` and the camera is
   **closed** with ``cam.close()``.


.. _cpp_example_source:

Full Source Code
----------------

.. literalinclude:: ../../../samples/cpp_examples/src/cpp_example.cpp
   :language: cpp
   :linenos:
   :tab-width: 4

