argus_pba.h

Go to the documentation of this file.

/*************************************************************************/
#ifndef ARGUS_PBA_H
#define ARGUS_PBA_H
#ifdef __cplusplus
extern "C" {
#endif
 
/*!***************************************************************************
 * @defgroup    argus_pba Pixel Binning Algorithm
 * @ingroup     argus_api
 *
 * @brief       Pixel Binning Algorithm (PBA) parameter definitions and API functions.
 *
 * @details     Defines the generic Pixel Binning Algorithm (PBA) setup parameters
 *              and data structure.
 *
 *              The PBA module contains filter algorithms that determine the
 *              pixels with the best signal quality and extract an 1D distance
 *              information from the filtered pixels by averaging them in a
 *              specified way.
 *
 *              Basically, the Pixel Binning Algorithm is a multi-stage filter:
 *
 *              -# A fixed pre-filter mask is applied to statically disable
 *                  specified pixels.
 *
 *              -# A relative and absolute amplitude filter is applied in the
 *                  second stage. The relative filter is determined by a ratio
 *                  of the maximum amplitude off all available (i.e. not filtered
 *                  in stage 1) pixels. Pixels that have an amplitude below the
 *                  relative threshold are dismissed. The same holds true for
 *                  the absolute amplitude threshold. All pixel with smaller
 *                  amplitude are dismissed.\n
 *                  Note that the absolute amplitude threshold is disabled if
 *                  the Golden Pixel (see below) is also disabled in order to
 *                  prevent invalid filtering for multi-pixel devices.\n
 *                  The relative threshold is useful to setup a distance
 *                  measurement scenario. All well illuminated pixels are
 *                  selected and considered for the final 1D distance. The
 *                  absolute threshold is used to dismiss pixels that are below
 *                  the noise level. The latter would be considered for the 1D
 *                  result if the maximum amplitude is already very low.\n
 *                  Those threshold are implemented using a hysteresis behavior.
 *                  For its configuration, see the following parameters:
 *                  - #argus_cfg_pba_t::RelativeAmplitudeInclusion
 *                  - #argus_cfg_pba_t::RelativeAmplitudeExclusion
 *                  - #argus_cfg_pba_t::AbsoluteAmplitudeInclusion
 *                  - #argus_cfg_pba_t::AbsoluteAmplitudeExclusion
 *                  .
 *
 *              -# An absolute minimum distance filter is applied in addition
 *                  to the amplitude filter. This removes all pixel that have
 *                  a lower distance than the specified threshold. This is used
 *                  to remove invalid pixels that can be detected by a physically
 *                  not correct negative distance.\n
 *                  For its configuration, see the following parameters:
 *                  - #PBA_ENABLE_MIN_DIST_SCOPE
 *                  - #argus_cfg_pba_t::AbsoluteDistanceScopeInclusion
 *                  - #argus_cfg_pba_t::AbsoluteDistanceScopeExclusion
 *                  - #argus_cfg_pba_t::RelativeDistanceScopeInclusion
 *                  - #argus_cfg_pba_t::RelativeDistanceScopeExclusion
 *                  .
 *
 *              -# A distance filter is used to distinguish pixels that target
 *                  the actual object from pixels that see the brighter background,
 *                  e.g. white walls. Thus, the pixel with the minimum distance
 *                  is referenced and all pixel that have a distance between
 *                  the minimum and the given minimum distance scope are selected
 *                  for the 1D distance result. The minimum distance scope is
 *                  determined by an relative (to the current minimum distance)
 *                  and an absolute value. The larger scope value is the
 *                  relevant one, i.e. the relative distance scope can be used
 *                  to heed the increasing noise at larger distances.\n
 *                  For its configuration, see the following parameters:
 *                  - #argus_cfg_pba_t::AbsoluteMinimumDistanceThreshold
 *                  .
 *
 *              -# If all of the above filters fail to determine a single valid
 *                  pixel, the Golden Pixel is used as a fallback value. The
 *                  Golden Pixel is the pixel that sits right at the focus point
 *                  of the optics at large distances. Thus, it is expected to
 *                  have the best signal at large distances.\n
 *                  For its configuration, see the following parameters:
 *                  - #PBA_ENABLE_GOLDPX_FALLBACK_MODE
 *                  .
 *
 *              -# In order to avoid unwanted effects from "out-of-focus" pixels
 *                  in application that require a smaller focus, the Golden Pixel
 *                  Priority Mode prioritizes a valid signal on the central
 *                  Golden Pixel over other pixels. That is, while the Golden
 *                  Pixel has a reasonable signal strength, it is the only pixel
 *                  considered for the 1D result.\n
 *                  For its configuration, see the following parameters:
 *                  - #PBA_ENABLE_GOLDPX_FALLBACK_MODE
 *                  - #argus_cfg_pba_t::GoldenPixelPriorityAmplitudeInclusion
 *                  - #argus_cfg_pba_t::GoldenPixelPriorityAmplitudeExclusion
 *                  .
 *              .
 *
 *              After filtering is done, there may be more than a single pixel
 *              left to determine the 1D signal. Therefore several averaging
 *              methods are implemented to obtain the best 1D result from many
 *              pixels. See #argus_pba_averaging_mode_t for details.
 *
 *
 * @addtogroup  argus_pba
 * @{
 *****************************************************************************/
 
#include "argus_def.h"
 
/*!***************************************************************************
 * @brief   Enable flags for the pixel binning algorithm.
 *
 * @details Determines the pixel binning algorithm feature enable status.
 *
 *          - [0]: #PBA_ENABLE: Enables the pixel binning feature.
 *          - [1]: reserved
 *          - [2]: reserved
 *          - [3]: reserved
 *          - [4]: #PBA_ENABLE_GOLDPX_PRIORITY_MODE: Enables the Golden Pixel
 *                                                   priority mode feature.
 *          - [5]: #PBA_ENABLE_GOLDPX_FALLBACK_MODE: Enables the Golden Pixel
 *                                                   fallback mode feature.
 *          - [6]: #PBA_ENABLE_MIN_DIST_SCOPE: Enables the minimum distance
 *                                             scope feature.
 *          - [7]: reserved
 *          .
 *****************************************************************************/
typedef enum argus_pba_flags_t
{
    PBA_ENABLE = 1U << 0U,
 
    PBA_ENABLE_GOLDPX_PRIORITY_MODE = 1U << 4U,
 
    PBA_ENABLE_GOLDPX_FALLBACK_MODE = 1U << 5U,
 
    PBA_ENABLE_MIN_DIST_SCOPE = 1U << 6U,
 
} argus_pba_flags_t;
 
/*!***************************************************************************
 * @brief   The averaging modes for the pixel binning algorithm.
 *****************************************************************************/
typedef enum argus_pba_averaging_mode_t
{
    PBA_SIMPLE_AVG = 1U,
 
    PBA_LINEAR_AMPLITUDE_WEIGHTED_AVG = 2U,
 
} argus_pba_averaging_mode_t;
 
/*!***************************************************************************
 * @brief   The pixel binning algorithm settings data structure.
 * @details Describes the pixel binning algorithm settings.
 *****************************************************************************/
typedef struct
{
    argus_pba_flags_t Enabled;
 
    argus_pba_averaging_mode_t AveragingMode;
 
    uq0_8_t RelativeAmplitudeInclusion;
 
    uq0_8_t RelativeAmplitudeExclusion;
 
    uq12_4_t AbsoluteAmplitudeInclusion;
 
    uq12_4_t AbsoluteAmplitudeExclusion;
 
    uq12_4_t GoldenPixelPriorityAmplitudeInclusion;
 
    uq12_4_t GoldenPixelPriorityAmplitudeExclusion;
 
    uq0_8_t RelativeDistanceScopeInclusion;
 
    uq0_8_t RelativeDistanceScopeExclusion;
 
    uq1_15_t AbsoluteDistanceScopeInclusion;
 
    uq1_15_t AbsoluteDistanceScopeExclusion;
 
    uint8_t GoldenPixelSaturationFilterPixelThreshold;
 
    uint8_t GoldenPixelOutOfSyncAgeThreshold;
 
    q9_22_t AbsoluteMinimumDistanceThreshold;
 
    uint32_t PrefilterMask;
 
} argus_cfg_pba_t;
 
#ifdef __cplusplus
} // extern "C"
#endif
#endif /* ARGUS_PBA_H */