path: root/color_pipe.h

/**
* @file			color_pipe.h
* @brief		Color Processing Pipeline Definitions
* @author		Patrick Roth - roth@stettbacher.ch
* @copyright	Stettbacher Signal Processing AG
* 
* @remarks
*
* <PRE>
* 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
* </PRE>
*
*/


#ifndef _COLOR_PIPE_H
#define _COLOR_PIPE_H


#include <o3000/o3000_portable.h>
#include <o3000/image_header.h>


/**
 * 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