/**
* @file color_pipe.h
* @brief Color Processing Pipeline Definitions
* @author Patrick Roth - roth@stettbacher.ch
* @copyright Stettbacher Signal Processing AG
*
* @remarks
*
*
* This library is free software; you can redistribute it and/or
* modify it under the terms of the GNU Lesser General Public
* License as published by the Free Software Foundation; either
* version 2.1 of the License, or (at your option) any later version.
*
* This library is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
* Lesser General Public License for more details.
*
* You should have received a copy of the GNU Lesser General Public
* License along with this library; if not, write to the Free Software
* Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
*
*
*/
#ifndef _COLOR_PIPE_H
#define _COLOR_PIPE_H
#include
#include
/**
* Coordinate definition.
*/
struct coord_t {
int x; ///< x-coordinate of calibrated pixel
int y; ///< y-coordinate of calibrated pixel
};
/**
* demosaicing algorithm definition
*/
enum bayer_alg_t {
BAYER_ALG_BILINEAR = 0, ///< bilinear interpolation
};
/**
* Demosaicing (debayer) data structure
* This algorithm is enabled always.
*/
struct debayer_data_t {
void *img_rgb; ///< RGB output image. This buffer must be allocated externly.
void *img_raw; ///< Pointer to input image containing raw bayer image.
int height; ///< image height in number of pixels
int width; ///< image width in number of pixels
enum enumDataFormat_t format; ///< data format of input image
enum enumBayerPattern_t start_pattern; ///< first pixel starts with this bayer pattern
enum bayer_alg_t alg; ///< debayer algorithm type
enum bayer_alg_t alg_new; ///< this debayer algorithm type is changed by API call (use double buffering)
};
/**
* automatic white balance (AWB) data structure
*/
struct awb_data_t {
int enable; ///< flag to enable this algorithm
void *img_rgb_balanced; ///< White balanced RGB output image. This buffer must be allocated externly.
void *img_in; ///< Unbalanced RGB input image.
int bit_channel; ///< Bits per color channel.
int height; ///< image height in number of pixels
int width; ///< image width in number of pixels
int16_t *img_yuv; ///< Image buffer holding YUV image. This buffer must be allocated externly.
float gray_threshold; ///< gray value threshold
float gray_threshold_new; ///< this gray value threshold is changed by API call (use double buffering)
float ctrl_k; ///< controller gain
float ctrl_k_new; ///< this controller gain is changed by API call (use double buffering)
float gain_red; ///< red color gain
float gain_blue; ///< blue color gain
};
/**
* camera distortion coefficient definition
*/
struct dist_coeff_t {
float k1; ///< radial distortion factor k1
float k2; ///< radial distortion factor k2
float p1; ///< tangential distortion factor p1
float p2; ///< tangential distortion factor p2
float k3; ///< radial distortion factor k3
};
/**
* camera matrix definition
*/
struct camera_matrix_t {
float a11; ///< fx: focal length in x-direction
float a12; ///< skew: axis skew
float a13; ///< cx: optical center in x-direction
float a21; ///< must be 0.0
float a22; ///< focal length in y-direction
float a23; ///< optical center in y-direction
float a31; ///< must be 0.0
float a32; ///< must be 0.0
float a33; ///< must be 1.0
};
/**
* O-3000 lense definitions supplied by Stettbacher Signal Processing.
* Lense definitions are used to load lens specific distortion coefficients.
*/
enum o3000_lenses_t {
// S-mount lenses
O3000_LS_F2_8 = 0, ///< S-mount, focal length 2.8mm, aperture 2.0
O3000_LS_F4_2, ///< S-mount, focal length 4.2mm, aperture 1.8
O3000_LS_F6_0, ///< S-mount, focal length 6.0mm, aperture 1.8
O3000_LS_F8_0, ///< S-mount, focal length 8.0mm, aperture 1.8
O3000_LS_F12_0, ///< S-mount, focal length 12.0mm, aperture 1.8
// CS-mount lenses
O3000_LCS_F2_8, ///< CS-mount, focal length 2.8mm, aperture 1.6
O3000_LCS_F4_2, ///< CS-mount, focal length 4.2mm, aperture 1.4
O3000_LCS_F6_0, ///< CS-mount, focal length 6.0mm, aperture 1.4
O3000_LCS_F8_0, ///< CS-mount, focal length 8.0mm, aperture 1.4
O3000_LCS_F12_0, ///< CS-mount, focal length 12.0mm, aperture 1.4
};
/**
* camera calibration structure
*
* The total width @ref tot_width and height @ref tot_height define the image size take during calibration processs.
* The field of view defines the current image windows. This window is less or equal to the total image size.
*/
struct cam_calib_data_t {
int enable; ///< flag to enable this algorithm
void *img_calib; ///< Undistorted (calibrated) output image. This buffer must be allocated externly.
void *img_in; ///< Uncalibrated distorted input image.
int is_color; ///< Not 0 if it's a color image.
int bit_channel; ///< Bits per color channel.
int tot_width; ///< total image width in pixels used during calibration process
int tot_height; ///< total image height in pixels used during calibration process
int fov_x_start; ///< field of view start pixel coordinate in x-direction
int fov_x_end; ///< field of view end pixel coordinate in x-direction
int fov_y_start; ///< field of view start pixel coordinate in y-direction
int fov_y_end; ///< field of view end pixel coordinate in y-direction
struct dist_coeff_t dist_coeff; ///< distortion coefficients
struct camera_matrix_t camera_matrix; ///< camera matrix
enum o3000_lenses_t lense; ///< lense type
enum o3000_lenses_t lense_new; ///< lense type is changed by API call (use double buffering)
int undistort_map_init; ///< flag indicating if lens undistortion map is initialized
/**
* Lense undistortion map.
* A coordinate pair defines the undistorted pixel location. It may be shifted (see @ref calib_map_scale_fact).
*
* This buffer must be allocated externly.
*/
struct coord_t *calib_map;
/**
* Bit shift applied on undistortion map @ref calib_map.
* The pixel location may lay between a pixel pair. Therefore the coordinates defined at the undistortion map
* @ref calib_map are (scaled) shifted by this factor.
*/
int calib_map_scale_fact;
};
/**
* Color Correction Matrix presets (CCM) for various camera types
*/
enum ccm_preset_t {
CCM_PRESET_O3020 = 0, ///< O-3020 camera from Stettbacher Signal Processing
};
/**
* color calibration structure definition
*
*
* The color correction matrix A maps the uncalibrated image (img_uncal) to the
* calibrated image (img_calib) according to the following transformation:
*
* img_calib = A * img_uncal
*
* where
*
* | a11 a12 a13 |
* A = | a21 a22 a23 |
* | a31 a32 a33 |
*
*
* | red_uncal |
* img_uncal = | green_uncal |
* | blue_uncal |
*
* | red_calib |
* img_calib = | green_calib |
* | blue_calib |
*
*
* red_calib = a11*red_uncal + a12*green_uncal + a12*blue_uncal
* green_calib = a21*red_uncal + a22*green_uncal + a22*blue_uncal
* blue_calib = a31*red_uncal + a32*green_uncal + a32*blue_uncal
*
*/
struct color_calib_data_t {
int enable; ///< flag to enable this algorithm
void *img_calib; ///< Color calibrated output image. This buffer must be allocated externly.
void *img_in; ///< Uncalibrated input image
int bit_channel; ///< bits per color channel
int width; ///< image width in number of pixels
int height; ///< image height in number of pixels
float a[3][3]; ///< 3x3 color correction matrix
enum ccm_preset_t ccm; ///< color correction matrix type loaded
enum ccm_preset_t ccm_new; ///< this color correction matrix type is changed by API call (use double buffering)
};
/**
* Sharpening algorithm definition
*/
enum sharp_alg_t {
SHARP_ALG_GLOBAL = 0, ///< global sharpening algorithm
SHARP_ALG_LOCAL, ///< local sharpening algorithm
};
/**
* Sharpening data definition
*/
struct sharp_data_t {
int enable; ///< flag to enable this algorithm
void *img_sharp; ///< Sharpened output RGB image. This buffer must be allocated externly.
void *img_in; ///< Unsharp RGB input image.
int is_color; ///< Not 0 if it's a color image
int bit_channel; ///< Bits per color channel.
int width; ///< image width in number of pixels
int height; ///< image height in number of pixels
int16_t *img_yuv; ///< YUV image buffer. This buffer must be allocated externly.
float sharp_factor; ///< Sharpening factor: As higher as stronger sharpening is done.
float sharp_factor_new; ///< this sharpening factor is changed by API call (use double buffering)
enum sharp_alg_t sharp_alg; ///< sharpening algorithm type
enum sharp_alg_t sharp_alg_new; ///< this algorithm type is changed by API call (use double buffering)
float local_sens; ///< Sensitivity setting of local sharpening algorithm in per cent. 100 % means everything is sharpened like the global algorithm does
float local_sens_new; ///< this sensitivity setting is changed by API call (use double buffering)
int16_t *img_yuv_sharp; ///< YUV image buffer holding sharpened Y-channel. This buffer must be allocated externly.
int16_t *img_sobel; ///< Sobel image in YUV color space used by local sharpening algorithm. This buffer must be allocated externly.
int16_t *img_gauss; ///< Gaussian low-pass filtered image in YUV color space used by local sharpening algorithm. This buffer must be allocated externly.
int8_t *sharp_mask; ///< Binary sharpening mask image used by local sharpening algorithm. This buffer must be allocated externly.
};
/**
* Gamma correction data definition
*/
struct gamma_data_t {
int enable; ///< flag to enable this algorithm
void *img_gamma; ///< Gamma corrected output image. This buffer must be allocated externly.
void *img_in; ///< Input image.
int is_color; ///< Not 0 if it's a color image
int bit_channel; ///< Bits per color channel.
int width; ///< image width in number of pixels
int height; ///< image height in number of pixels
float gamma; ///< gamma coefficient
float gamma_new; ///< this gamma coefficient is changed by API call (use double buffering)
int gamma_table_bitdepth; ///< gamma table is initialized with this bit-depth
float gamma_table_init; ///< gamma table is initialized with this coefficient
int *gamma_table; ///< Lookup table containg gamma corrected value. This buffer must be allocated externly.
};
/**
* Isosceles trapezoid correction definition
*/
struct trapcorr_data_t {
int enable; ///< flag to enable this algorithm
void *img_out; ///< Isosceles corrected output image. This buffer must be allocated externly.
void *img_in; ///< Input image.
int is_color; ///< Not 0 if it's a color image
int bit_channel; ///< Bits per color channel.
int width; ///< image width in number of pixels
int height; ///< image height in number of pixels
float wv; ///< vertical correction weight in per cent (range: -100.0 to +100.0) (NOTE not implemented yet!)
float wh; ///< horizontal correction weight in per cent (range: -100.0 to +100.0)
float wv_new; ///< double buffered vertical correction weight
float wh_new; ///< double buffered horizontal correction weight
int map_init; ///< flag indicating perspective correction map is initialized
/**
* perspective correction map
* A coordinate pair defines the pixel location to be corrected. It may be shifted (see @ref map_scale_fact).
*
* This buffer must be allocated externly.
*/
struct coord_t *map;
/**
* Bit shift applied on correction map @ref map.
* The pixel location may lay between a pixel pair. Therefore the coordinates defined at the correction map
* @ref map are (scaled) shifted by this factor.
*/
int map_scale_fact;
};
/**
* Projective transformation definition
*/
struct projection_data_t {
int enable; ///< flag to enable projective transformation
void *img_out; ///< projected image. This buffer must be allocated externly.
void *img_in; ///< Input image.
int is_color; ///< Not 0 if it's a color image
int bit_channel; ///< Bits per color channel.
int width; ///< image width in number of pixels
int height; ///< image height in number of pixels
float c_inv[3][3]; ///< inverse of 3x3 projection matrix C
float c_inv_new[3][3]; ///< double buffered matrix
int c_upd; ///< projection matrix update flag
int map_init; ///< flag indicating transformation map is initialized
/**
* projective transfomration map
* A coordinate pair defines the transformed pixel location. It may be shifted (see @ref map_scale_fact).
*
* This buffer must be allocated externly.
*/
struct coord_t *map;
/**
* Bit shift applied on correction map @ref map.
* The pixel location may lay between a pixel pair. Therefore the coordinates defined at the map
* @ref map are (scaled) shifted by this factor.
*/
int map_scale_fact;
};
/**
* Color pipe definition structure holding all memory data from different pipeline
* stages. This structure and image buffers are allocated dynamically.
*/
struct color_pipe_t {
void *img_out; ///< Points to processed output image in RGB format.
int is_color; ///< Not 0 if it's a color image
int bit_channel; ///< Bits per color channel.
int width; ///< image width in number of pixels
int height; ///< image height in number of pixels
struct debayer_data_t debayer_data; ///< demosaicing data
struct awb_data_t awb_data; ///< auto white balancing data
struct cam_calib_data_t cam_calib_data; ///< camera calibration data used for lens distortion correction
struct color_calib_data_t color_calib_data; ///< color calibration data used for color corretion
struct sharp_data_t sharp_data; ///< image sharpening data
struct gamma_data_t gamma_data; ///< gamma correction data
struct trapcorr_data_t trapcorr_data; ///< isosceles trapezoid correction data
struct projection_data_t proj_data; ///< projective transformation data
};
#if defined(__cplusplus) || defined(c_plusplus)
extern "C" {
#endif
void __stdcall color_pipe_process(struct color_pipe_t *color_pipe, void *img_buf, struct img_header_t *img_header);
int __stdcall color_pipe_open(struct color_pipe_t **color_pipe, const int max_img_height, const int max_img_width, const int bits_per_channel);
int __stdcall color_pipe_close(struct color_pipe_t *data);
void __stdcall color_pipe_get_version(int *major, int *minor, int *release);
void __stdcall color_pipe_stageconf_debayer(struct color_pipe_t *color_pipe, enum bayer_alg_t alg);
void __stdcall color_pipe_stageconf_awb(struct color_pipe_t *color_pipe, int enable, float gray_threshold, float ctrl_gain);
void __stdcall color_pipe_stageconf_cam_calib(struct color_pipe_t *color_pipe, int enable, enum o3000_lenses_t lense);
void __stdcall color_pipe_stageconf_color_calib(struct color_pipe_t *color_pipe, int enable, enum ccm_preset_t ccm_preset);
void __stdcall color_pipe_stageconf_sharp(struct color_pipe_t *color_pipe, int enable, float factor, enum sharp_alg_t alg, float sens);
void __stdcall color_pipe_stageconf_gamma(struct color_pipe_t *color_pipe, int enable, float gamma);
void __stdcall color_pipe_stageconf_trapcorr(struct color_pipe_t *color_pipe, int enable, float wv, float wh);
void __stdcall color_pipe_stageconf_projection(struct color_pipe_t *color_pipe, int enable, float c_inv[3][3]);
#if defined(__cplusplus) || defined(c_plusplus)
} // extern "C"
#endif
#endif // _COLOR_PIPE_H