=======
Sensing
=======

The radar module provides all functionalities to implement sensing operations on
devices.

It currently implements a single signal processing chain :doc:`Radar</api/radar.radar.Radar>` configured
by realizations of abstract :doc:`RadarWaveform</api/radar.radar.RadarWaveform>` and :doc:`RadarDetector</api/radar.detection.RadarDetector>` classes:

.. mermaid::

    classDiagram
 
       class Radar {
 
          +RadarWaveform waveform
          +TransmitBeamformer transmit_beamformer
          +ReceiveBeamformer receive_beamformer
          +RadarTransmission transmission
          +RadarReception reception
          +RadarDetector detector
          
          +transmit() : RadarTransmission
          +receive() : RadarReception
       }

      class RadarWaveform {

         <<Abstract>>
         +ping() : Signal
         +estimate(Signal) : ndarray
      }

      class RadarTransmission {

         +Signal signal
      }

      class RadarReception {

         +Signal signal
         +RadarCube cube
         +RadarPointCloud cloud
      }

      class RadarDetector {
         <<Abstract>>
         +detect(RadarCube) : RadarPointCloud
      }

      class PointDetection {

         +ndarray position
         +ndarray velocity
         +float power
      }

      class RadarCube {
         +plot_range()
         +plot_range_velocity()
      }

      class RadarPointCloud {
         +plot()
      }

      Radar *-- RadarWaveform
      Radar --> RadarTransmission : transmit()
      Radar *-- RadarTransmission
      Radar --> RadarReception : receive()
      Radar *-- RadarReception
      Radar *-- RadarDetector
      Radar --> RadarCube
      RadarCube --* RadarReception
      RadarCube --> RadarDetector
      RadarDetector --> RadarPointCloud : detect()
      RadarReception *-- RadarPointCloud
      PointDetection "*" --* RadarPointCloud
                     
      link RadarCube "radar.cube.RadarCube.html"     
      link Radar "radar.radar.Radar.html"
      link RadarReception "radar.radar.RadarReception.html"
      link RadarTransmission "radar.radar.RadarTransmission.html"
      link RadarWaveform "radar.radar.RadarWaveform.html"
      link RadarDetector "radar.detection.RadarDetector.html"
      link PointDetection "radar.detection.PointDetection.html"
      link RadarPointCloud "radar.detection.RadarPointCloud.html"

Within the context of a simulation,
we can use the :doc:`Radar<radar.radar.Radar>` class to configure a device
sensing a single target within its field of view:

.. literalinclude:: ../scripts/radar_simulation.py
   :language: python
   :linenos:
   :lines: 15-28

This snippet initially imports required modules from Hermes' radar, simulation and channel modules
and configures a simulation scenario with a single :doc:`FMCW<radar.fmcw>` :doc:`Radar<radar.radar.Radar>` :doc:`Device<core.device.Device>`
transmitting at :math:`60~\mathrm{GHz}`.
The transmitted signals are reflected by a single :doc:`Target<channel.radar.SingleTargetRadarChannel>` with a cross section of :math:`1~\mathrm{m}^2` at a distance of half the maximum detectable range.
A single simulation drop, consisting of the radar emitting a frame, the frame being propagated over the channel model,
the radar receiving the frame and processing it given the configured waveform and detector can be generated by executing the following statement:

.. literalinclude:: ../scripts/radar_simulation.py
   :language: python
   :linenos:
   :lines: 30-31

Afterwards, the generated information is cached at the radar and can be visualized by calling plotting routines:

.. literalinclude:: ../scripts/radar_simulation.py
   :language: python
   :linenos:
   :lines: 33-38

For more detailed examples, please refer to the :doc:`/tutorials` section.
For a detailed description of the individual classes and their methods,
refer to the API documentation:

.. toctree::

   radar.radar.Radar
   radar.radar.RadarReception
   radar.radar.RadarTransmission
   radar.radar.RadarWaveform
   radar.cube.RadarCube
   radar.detection.RadarDetector
   radar.detection.PointDetection
   radar.detection.RadarPointCloud
   radar.evaluators.RadarEvaluator

.. footbibliography::