/** ****************************************************************************** * @file evision-api-st-ae.h * @author STMicroelectronics / LACROIX - Impulse * @brief ST eVision Auto Exposure algorithm public header. ****************************************************************************** * @attention * * Copyright (c) 2025 STMicroelectronics. * Copyright (c) 2023 LACROIX - Impulse. * All rights reserved. * * This software is licensed under terms that can be found in the LICENSE file * in the root directory of this software component. * If no LICENSE file comes with this software, it is provided AS-IS. * ****************************************************************************** */ /* Define to prevent recursive inclusion -------------------------------------*/ #ifndef EVISION_API_ST_AE_H_ #define EVISION_API_ST_AE_H_ /* Includes ------------------------------------------------------------------*/ #include #include #include "evision-api-utils.h" /* Exported types ------------------------------------------------------------*/ typedef struct evision_st_ae_hyper_param { /*! @brief * Target exposure to reach.
* Restrictions: >= 0 AND < 256.
* Default value: 56 */ uint32_t target; /*! @brief * Max delta between lum stat and target in convergence region
* Restrictions: >= 0 AND < 256.
* Default value: 10 */ uint32_t tolerance; /*! @brief * Factor applied to increment gain update
* Restrictions: >= 0 AND < 1000.
* Default value: 100 */ uint32_t gain_increment_coeff; /*! @brief * Max delta value between lum stat and target in low delta region
* Restrictions: >= 0 AND < 256.
* Default value: 45 */ uint32_t gain_low_delta; /*! @brief * Min delta value between lum stat and target in high delta region
* Restrictions: >= 0 AND < 256.
* Default value: 120 */ uint32_t gain_high_delta; /*! @brief * Maximum gain update value in luminance low delta region
* Restrictions: >= #gain_min AND < #gain_max.
* Default value: 1500 */ uint32_t gain_low_increment_max; /*! @brief * Maximum gain update value in luminance medium delta region
* Restrictions: >= #gain_min AND < #gain_max.
* Default value: 6000 */ uint32_t gain_medium_increment_max; /*! @brief * Maximum gain update value in luminance high delta region
* Restrictions: >= #gain_min AND < #gain_max.
* Default value: 12000 */ uint32_t gain_high_increment_max; /*! @brief * Factor applied to increment exposure
* Restrictions: >= 0.0 AND < 1.
* Default value: 0.020*/ double exposure_up_ratio; /*! @brief * Minimum value accepted for exposure time.
* Restrictions: >= 0.0 AND < 1.
* Default value: 0.004*/ double exposure_down_ratio; /*! @brief * Minimum value accepted for exposure time.
* Restrictions: >= 0.0 AND < #exposure_max.
* Default value: 0.0*/ uint32_t exposure_min; /*! @brief * Maximum value accepted for exposure time.
* Restrictions: > 0.0 AND >= #exposure_min.
* Default value: 1.0 */ uint32_t exposure_max; /*! @brief * Minimum possible gain value.
* Restrictions: > 1 AND < #gain_max.
* Default value: 1 */ uint32_t gain_min; /*! @brief * Maximum possible gain value.
* Restrictions: >= 1 AND > #gain_min.
* Default value: 1 */ uint32_t gain_max; /*! @brief * Luminance limit where we consider the frame as dark.
* Restrictions: >= 0 AND < 256.
* Default value: 5 */ uint32_t dark_zone_lum_limit; /*! @brief * Compatible light frequency in Hz to avoid flickering effect.
* Restrictions: >= 0 (None) AND < 256.
* Default value: 0 (None) */ uint32_t compat_freq; } evision_st_ae_hyper_param_t; /** * @typedef evision_ae_estimator_t * @brief AE estimator structure. * * @struct evision_ae_estimator * @brief AE estimator structure. * * Set of all data structures required for the functioning of the AE algorithm. */ typedef struct evision_st_ae_process_t { /*! @brief * Indicates the state of the AE algorithm.
* Restrictions: Internal algorithm parameter. Must not be changed!
* Possible values: see #evision_state_t */ evision_state_t state; /*! @brief * Computed exposure time to apply to sensor.
* Restrictions: Internal algorithm parameter. Must not be changed! */ uint32_t new_exposure; /*! @brief * Computed gain value to apply to sensor.
* Restrictions: Internal algorithm parameter. Must not be changed! */ uint32_t new_gain; /*! @brief * The set of AE algorithm hyper-parameters. Set to default values at creation!
* #evision_ae_hyper_param_t.exposure_min, #evision_ae_hyper_param_t.exposure_max, * #evision_ae_hyper_param_t.gain_min and #evision_ae_hyper_param_t.gain_max hyper-parameters * must be updated before running the ae process with respect to the sensor in use.
* As a general note, the hyper-parameters can be updated from their default values. * Care must be taken as in such a case there is no guarantee of proper functioning of the process!
* Restrictions: Must not be updated during runtime! */ evision_st_ae_hyper_param_t hyper_params; /*! @brief * Handler to output logs.
*/ evision_api_log_callback log_cb; } evision_st_ae_process_t; /* Exported constants --------------------------------------------------------*/ #define EVISION_ST_AEC_LUM_TARGET 56 /* Default luminance value targeted by the AE algorithm */ #define EVISION_ST_AEC_TOLERANCE 10 /* Max delta between lum stat and target in convergence region */ #define EVISION_ST_AEC_GAIN_INCREMENT_COEFF 100 /* Factor applied to increment gain update */ #define EVISION_ST_AEC_GAIN_LOW_DELTA 45 /* Max delta value between lum stat and target in low delta region */ #define EVISION_ST_AEC_GAIN_HIGH_DELTA 120 /* Min delta value between lum stat and target in high delta region */ #define EVISION_ST_AEC_GAIN_LOW_INC_MAX 1500 /* Maximum gain update value in luminance low delta region */ #define EVISION_ST_AEC_GAIN_MEDIUM_INC_MAX 6000 /* Maximum gain update value in luminance medium delta region */ #define EVISION_ST_AEC_GAIN_HIGH_INC_MAX 12000 /* Maximum gain update value in luminance high delta region */ #define EVISION_ST_AEC_EXPOSURE_UP_RATIO 0.020F /* Factor applied to increment exposure */ #define EVISION_ST_AEC_EXPOSURE_DOWN_RATIO 0.004F /* Factor applied to decrement exposure */ #define EVISION_ST_AEC_DARKZONE_LUM_LIMIT 5 /* Default value for dark zone luminance limit */ #define EVISION_ST_DEFAULT_EXPOSURE_MIN 0 /* Default value for exposure min */ #define EVISION_ST_DEFAULT_EXPOSURE_MAX 33000 /* Default value for expsoure max */ #define EVISION_ST_DEFAULT_GAIN_MIN 1 /* Default value for gain min */ #define EVISION_ST_DEFAULT_GAIN_MAX 100 /* Default value for gain max */ #define EVISION_ST_DEFAULT_COMPAT_FREQ 0 /* Default value for compatible frequency */ /* Exported macro ------------------------------------------------------------*/ /* Exported functions ------------------------------------------------------- */ /** * @fn evision_st_ae_process_t* evision_api_st_ae_new(void); * @brief Create a new #evision_st_ae_process_t instance. * * @param[in] log_cb Callback to output logs. * @return The address of the created instance. NULL if it failed. */ evision_st_ae_process_t* evision_api_st_ae_new(evision_api_log_callback log_cb); /** * @fn evision_return_t evision_api_st_ae_delete(evision_st_ae_process_t* self); * @brief Releases the memory allocated for the #evision_st_ae_process_t ae process instance. * * @param[in, out] ae process instance address. * @return * - EVISION_RET_SUCCESS * - EVISION_RET_PARAM_ERR */ evision_return_t evision_api_st_ae_delete(evision_st_ae_process_t* self); /** * @fn evision_return_t evision_api_st_ae_init(evision_st_ae_process_t* const self) * @brief Initialize the AE process structure. * * @param[in, out] self AE process to be initialized. * @return * - EVISION_RET_SUCCESS * - EVISION_RET_PARAM_ERROR * * Initializes the AE process structure. Hyper params can later be modified. */ evision_return_t evision_api_st_ae_init(evision_st_ae_process_t* const self); /** * @fn evision_return_t evision_api_st_ae_process(evision_st_ae_process_t* const self, uint32t_t current_gain, uint32_t current_exposure, uint8_t average_lum) * @brief Run the ae process to calculate new gain and expsoure * * @param[in, out] self Concerned process instance address. * @param[in] current_gain Current sensor gain in mdB. * @param[in] current_exposure Current sensor exposure microsecond. * @param[in] average_lum Average luminance measurement value. Range should normally be between 0 (completely dark image) and 255 (completely white image). * * @return * - EVISION_RET_SUCCESS * - EVISION_RET_FAILURE */ evision_return_t evision_api_st_ae_process(evision_st_ae_process_t* const self, uint32_t current_gain, uint32_t current_exposure, uint8_t average_lum); /* Exported variables --------------------------------------------------------*/ #endif /* EVISION_API_ST_AE_H_ */