:py:mod:`tonic.functional.event_downsampling`
=============================================

.. py:module:: tonic.functional.event_downsampling


Module Contents
---------------


Functions
~~~~~~~~~

.. autoapisummary::

   tonic.functional.event_downsampling.differentiator_downsample
   tonic.functional.event_downsampling.integrator_downsample



.. py:function:: differentiator_downsample(events: numpy.ndarray, sensor_size: tuple, target_size: tuple, dt: float, differentiator_time_bins: int = 2, noise_threshold: int = 0)

   Spatio-temporally downsample using the integrator method coupled with a differentiator to effectively
   downsample large object sizes relative to downsampled pixel resolution in the DVS camera's visual field.

   Incorporates the paper Ghosh et al. 2023, Insect-inspired Spatio-temporal Downsampling of Event-based Input,
   https://doi.org/10.1145/3589737.3605994

   :param events: ndarray of shape [num_events, num_event_channels].
   :type events: ndarray
   :param sensor_size: a 3-tuple of x,y,p for sensor_size.
   :type sensor_size: tuple
   :param target_size: a 2-tuple of x,y denoting new down-sampled size for events to be
                       re-scaled to (new_width, new_height).
   :type target_size: tuple
   :param dt: step size for simulation, in ms.
   :type dt: float
   :param differentiator_time_bins: number of equally spaced time bins with respect to the dt
                                    to be used for the differentiator.
   :type differentiator_time_bins: int
   :param noise_threshold: number of events before a spike representing a new event is emitted.
   :type noise_threshold: int

   :returns: the spatio-temporally downsampled input events using the differentiator method.


.. py:function:: integrator_downsample(events: numpy.ndarray, sensor_size: tuple, target_size: tuple, dt: float, noise_threshold: int = 0, differentiator_call: bool = False)

   Spatio-temporally downsample using with the following steps:

   1. Differencing of ON and OFF events to counter camera shake or jerk.
   2. Use an integrate-and-fire (I-F) neuron model with a noise threshold similar to
   the membrane potential threshold in the I-F model to eliminate high-frequency noise.

   Multiply x/y values by a spatial_factor obtained by dividing sensor size by the target size.

   :param events: ndarray of shape [num_events, num_event_channels].
   :type events: ndarray
   :param sensor_size: a 3-tuple of x,y,p for sensor_size.
   :type sensor_size: tuple
   :param target_size: a 2-tuple of x,y denoting new down-sampled size for events to be
                       re-scaled to (new_width, new_height).
   :type target_size: tuple
   :param dt: temporal resolution of events in milliseconds.
   :type dt: float
   :param noise_threshold: number of events before a spike representing a new event is emitted.
   :type noise_threshold: int
   :param differentiator_call: Preserve frame spikes for differentiator method in order to optimise
                               differentiator method.
   :type differentiator_call: bool

   :returns: the spatio-temporally downsampled input events using the integrator method.