327 lines
10 KiB
C
327 lines
10 KiB
C
/**
|
|
******************************************************************************
|
|
* @file evision-api-utils.h
|
|
* @author LACROIX - Impulse
|
|
* @brief eVision utilitary public header.
|
|
******************************************************************************
|
|
* @attention
|
|
*
|
|
* Copyright (c) 2023 LACROIX - Impulse.
|
|
* Copyright (c) 2025 STMicroelectronics.
|
|
* 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.
|
|
*
|
|
******************************************************************************
|
|
*/
|
|
|
|
#ifndef EVISION_API_UTILS_H_
|
|
#define EVISION_API_UTILS_H_
|
|
|
|
#ifdef __cplusplus
|
|
extern "C" {
|
|
#endif
|
|
|
|
/************************************************************************
|
|
* Includes
|
|
************************************************************************/
|
|
|
|
#include <stdint.h>
|
|
|
|
/************************************************************************
|
|
* Public Defines
|
|
************************************************************************/
|
|
|
|
/**
|
|
* @def EVISION_MIN
|
|
* @brief Determine the lowest value between a and b
|
|
*/
|
|
#define EVISION_MIN(a, b) ((a) < (b) ? (a) : (b))
|
|
|
|
/**
|
|
* @def EVISION_MAX
|
|
* @brief Determine the greatest value between a and b
|
|
*/
|
|
#define EVISION_MAX(a, b) ((a) > (b) ? (a) : (b))
|
|
|
|
/**
|
|
* @def EVISION_SIGN
|
|
* @brief Determine the sign of a number.
|
|
*/
|
|
#define EVISION_SIGN(x) ((x) > 0.0f ? 1.0f : -1.0f)
|
|
|
|
#ifdef ALGO_SW_STATISTICS
|
|
/* YUV parameters */
|
|
/*! @brief Minimum of Y value due to ISP RGB 2 YUV conversion formula */
|
|
#define EVISION_YUV_MIN_Y_VAL (16.0)
|
|
/*! @brief Maximum of Y value due to ISP RGB 2 YUV conversion formula */
|
|
#define EVISION_YUV_MAX_Y_VAL (235.140625)
|
|
/*! @brief YUV factor value due to ISP RGB 2 YUV conversion formula */
|
|
#define EVISION_YUV_FACTOR (256)
|
|
/*! @brief YUV maximum value due to ISP RGB 2 YUV conversion formula */
|
|
#define EVISION_YUV_MAX_VAL (255)
|
|
/*! @brief range of Y value due to ISP RGB 2 YUV conversion formula */
|
|
#define EVISION_YUV_RANGE_Y_VAL (EVISION_YUV_MAX_Y_VAL - EVISION_YUV_MIN_Y_VAL)
|
|
#endif
|
|
|
|
/**
|
|
* @typedef evision_return_t
|
|
* @brief Return type for functions.
|
|
*
|
|
* @enum evision_return
|
|
* @brief Return type for functions.
|
|
*
|
|
* Return code that must be checked to be sure the output of the function is valid.
|
|
*/
|
|
typedef enum evision_return {
|
|
EVISION_RET_INVALID_VALUE = 2, /*!< The process succeeded but the output value is invalid and should not be used.*/
|
|
EVISION_RET_SUCCESS = 1, /*!< the process succeeded. */
|
|
EVISION_RET_FAILURE = 0, /*!< Error: There was a failure. */
|
|
EVISION_RET_PARAM_ERR = -1, /*!< Error: A parameter is invalid. */
|
|
EVISION_RET_DIMENSION_ERR = -2, /*!< Error: A dimension is incompatible with the process. */
|
|
EVISION_RET_MEMORY_ERR = -3, /*!< Error: Could not allocate memory. */
|
|
EVISION_RET_FILE_ERR = -4, /*!< Error: A file could not be opened */
|
|
EVISION_RET_FORMAT_ERR = -5, /*!< Error: the specified format is invalid. */
|
|
} evision_return_t;
|
|
|
|
/**
|
|
* @typedef evision_state_t
|
|
* @brief Describes the state of the estimator.
|
|
*
|
|
* @enum evision_state
|
|
* @brief Describes the state of the estimator.
|
|
*/
|
|
typedef enum evision_state {
|
|
/*! @brief
|
|
* The estimator exists.
|
|
*/
|
|
EVISION_STATE_NONE = 0u,
|
|
/*! @brief
|
|
* The estimator was initialized and is ready to run.
|
|
*/
|
|
EVISION_STATE_INIT = 1u,
|
|
/*! @brief
|
|
* The estimator is running.
|
|
*/
|
|
EVISION_STATE_RUN = 2u,
|
|
} evision_state_t;
|
|
|
|
/**
|
|
* @typedef evision_image_format_t
|
|
* @brief Specify the format under which the image is stored.
|
|
*
|
|
* @enum evision_image_format
|
|
* @brief Specify the format under which the image is stored.
|
|
*
|
|
* Those formats are as the ones defined by V4L2.
|
|
*/
|
|
typedef enum evision_image_format {
|
|
/*! @brief
|
|
* 8 bit gray-level.
|
|
*/
|
|
EVISION_IMAGE_FORMAT_GRAY8 = 0u,
|
|
/*! @brief
|
|
* 8 bit gray-level.
|
|
*/
|
|
EVISION_IMAGE_FORMAT_GREY8 = 1u,
|
|
/*! @brief
|
|
* RGB interleaved, 8 bit per channel, 24 bit per pixel..
|
|
*/
|
|
EVISION_IMAGE_FORMAT_RGB8 = 2u,
|
|
/*! @brief
|
|
* BGR interleaved, 8 bit per channel, 24 bit per pixel..
|
|
*/
|
|
EVISION_IMAGE_FORMAT_BGR8 = 3u,
|
|
/*! @brief
|
|
* 8 bit YUV 422 SP format.
|
|
*/
|
|
EVISION_IMAGE_FORMAT_YUV422SP = 4u,
|
|
/*! @brief
|
|
* RGGB Bayer format, 8 bit per channel, Red compound first.
|
|
*/
|
|
EVISION_IMAGE_FORMAT_RGGB8 = 5u,
|
|
/*! @brief
|
|
* BGGR Bayer format, 8 bit per channel, Blue compound first.
|
|
*/
|
|
EVISION_IMAGE_FORMAT_BGGR8 = 6u,
|
|
/*! @brief
|
|
* GRBG Bayer format, 16 bit per channel, each coded on 16 bits inverted (0xFF, 0x0F).
|
|
*/
|
|
EVISION_IMAGE_FORMAT_GRBG12 = 7u,
|
|
/*! @brief
|
|
* RGGB Bayer format, 16 bit per channel, each coded on 16 bits inverted (0xFF, 0x0F).
|
|
*/
|
|
EVISION_IMAGE_FORMAT_RGGB12 = 8u
|
|
} evision_image_format_t;
|
|
|
|
/************************************************************************
|
|
* Public Functions Signatures
|
|
************************************************************************/
|
|
|
|
/**
|
|
* @brief Callback function to output logs.
|
|
*
|
|
* @param[in] msg Received message.
|
|
*
|
|
* If the user wants to handle the log and messages yielded by the estimator,
|
|
* a function with this signature must be specified.
|
|
*
|
|
*/
|
|
typedef void (*evision_api_log_callback)(const char* const msg);
|
|
|
|
/************************************************************************
|
|
* Public Structures
|
|
************************************************************************/
|
|
|
|
/**
|
|
* @typedef evision_image_t
|
|
* @brief Structure to hold frame data and metadata for eVision AE and AWB algorithms.
|
|
*
|
|
* @struct evision_image
|
|
* @brief Structure to hold frame data and metadata for eVision AE and AWB algorithms.
|
|
*
|
|
*/
|
|
typedef struct evision_image {
|
|
/*! @brief
|
|
* Frame data.
|
|
*/
|
|
uint8_t* pdata;
|
|
/*! @brief
|
|
* Number of pixels columns in the image.
|
|
*/
|
|
uint16_t width;
|
|
/*! @brief
|
|
* Number of pixels rows in the image.
|
|
*/
|
|
uint16_t height;
|
|
/*! @brief
|
|
* The format of the image.
|
|
*/
|
|
evision_image_format_t format;
|
|
} evision_image_t;
|
|
|
|
#ifdef ALGO_SW_STATISTICS
|
|
/**
|
|
* @typedef evision_roi_t
|
|
* @brief Represents a Region Of Interest (aka a rectangle of pixels in an image).
|
|
*
|
|
* @struct evision_roi
|
|
* @brief Represents a Region Of Interest (aka a rectangle of pixels in an image).
|
|
*
|
|
* A ROI serves to limit the statistics extraction to a specific zone inside the frame.
|
|
* Several ROIs can be defined and for each ROI a weight must be defined.
|
|
* The aggregated statistic is the weighted average of individual ROI statistics.
|
|
* Setting all weights equal results in the aggregated statistic to be the arithmetic average of the individual statistics.
|
|
*
|
|
*/
|
|
typedef struct evision_roi {
|
|
/*! @brief
|
|
* Horizontal pixel coordinate of the Top-Left corner of the ROI.
|
|
*/
|
|
uint16_t x0;
|
|
/*! @brief
|
|
* Vertical pixel coordinate of the Top-Left corner of the ROI.
|
|
*/
|
|
uint16_t y0;
|
|
/*! @brief
|
|
* Horizontal pixel coordinate of the Bottom-Right corner of the ROI.
|
|
*/
|
|
uint16_t x1;
|
|
/*! @brief
|
|
* Vertical pixel coordinate of the Bottom-Right corner of the ROI.
|
|
*/
|
|
uint16_t y1;
|
|
/*! @brief
|
|
* Weight associated to the ROI.
|
|
*/
|
|
double weight;
|
|
} evision_roi_t;
|
|
|
|
/**
|
|
* @typedef evision_roi_array_t
|
|
* @brief Represents an array of evision_roi.
|
|
*
|
|
* @struct evision_roi_array
|
|
* @brief Represents an array of evision_roi.
|
|
*
|
|
* Represents the collection of all the defined ROIs for the estimator. Must contain at least one ROI.
|
|
*
|
|
*/
|
|
typedef struct evision_roi_array {
|
|
/*! @brief
|
|
* Pointer to the beginning of the array.
|
|
*/
|
|
evision_roi_t* parray;
|
|
/*! @brief
|
|
* Number of elements in the array.
|
|
*/
|
|
uint16_t len;
|
|
} evision_roi_array_t;
|
|
#endif
|
|
|
|
|
|
/************************************************************************
|
|
* Private Structure Declaration
|
|
************************************************************************/
|
|
|
|
/************************************************************************
|
|
* Public Variables
|
|
************************************************************************/
|
|
|
|
/************************************************************************
|
|
* Public Function Prototypes
|
|
************************************************************************/
|
|
|
|
/* Library management functions */
|
|
#ifdef ALGO_SW_STATISTICS
|
|
/* ROI array management */
|
|
|
|
/**
|
|
* @fn evision_roi_array_t* evision_api_roi_array_new(const uint16_t length)
|
|
* @brief Create and allocate the memory for a new array of #evision_roi_array_t elements.
|
|
*
|
|
* @param[in] length Size of the array to create
|
|
* @return Address of the created #evision_roi_array_t. NULL if something went wrong.
|
|
*/
|
|
evision_roi_array_t* evision_api_roi_array_new(const uint16_t length);
|
|
|
|
/**
|
|
* @fn evision_roi_array_t* evision_api_roi_array_new_grid(const uint16_t frame_width, const uint16_t frame_height, const uint16_t roi_width, const uint16_t roi_height, const uint16_t nb_roi_col, const uint16_t nb_roi_row)
|
|
* @brief Create and allocate the memory for a new array of #evision_roi_array_t with pre filled ROIs positioned as a grid.
|
|
*
|
|
* In the end, the number of ROIs will be nb_roi_col * nb_roi_row
|
|
*
|
|
* @param[in] frame_width Number of pixels column in the frame where the ROIs will be placed.
|
|
* @param[in] frame_height Number of pixels rows in the frame where the ROIs will be placed.
|
|
* @param[in] roi_width Size (columns) of each ROI.
|
|
* @param[in] roi_height Size (rows) of each ROI.
|
|
* @param[in] nb_roi_col Number of ROIs to be placed in the horizontal dimension.
|
|
* @param[in] nb_roi_row Number of ROIs to be placed in the vertical dimension.
|
|
* @return Address of the created #evision_roi_array_t. NULL if something went wrong.
|
|
*/
|
|
evision_roi_array_t* evision_api_roi_array_new_grid(const uint16_t frame_width, const uint16_t frame_height, const uint16_t roi_width, const uint16_t roi_height, const uint16_t nb_roi_col, const uint16_t nb_roi_row);
|
|
|
|
/**
|
|
* @fn evision_return_t evision_api_roi_array_delete(evision_roi_array_t* self)
|
|
* @brief Free the memory allocated to an #evision_roi_array_t.
|
|
*
|
|
* @param[in, out] self Address of the concerned ROI array instance to be deleted, cannot be used after.
|
|
* @return
|
|
* - EVISION_RET_SUCCESS
|
|
* - EVISION_RET_PARAM_ERR
|
|
*/
|
|
evision_return_t evision_api_roi_array_delete(evision_roi_array_t* self);
|
|
#endif
|
|
|
|
/************************************************************************
|
|
* Public Function Definitions
|
|
************************************************************************/
|
|
|
|
#ifdef __cplusplus
|
|
}
|
|
#endif
|
|
|
|
#endif /* EVISION_API_UTILS_H_ */
|