visionapi.cpp

good luck to everyone!

*  option defaults:
*       searchRect = IMAQ_NO_RECT
* 		minMatchScore = DEFAULT_MINMAX_SCORE (800)  
*/
int frcEqualize(Image* dest, const Image* source, float min, float max)
{	return frcEqualize(dest, source, min, max, NULL);  }

int frcEqualize(Image* dest, const Image* source, float min, float max, const Image* mask)
{
	return imaqEqualize(dest, source, min, max, mask);
}

/**
* @brief Improves contrast on a color image. 
* Supports IMAQ_IMAGE_RGB, IMAQ_IMAGE_HSL
* 
* option defaults: colorEqualization = TRUE to equalize all three planes of the image         
* @return On success: 1. On failure: 0. To get extended error information, call GetLastError().    
* @param dest The destination image.
* @param source The image to equalize 
* @param colorEqualization Set this parameter to TRUE to equalize all three planes of the image (the default). Set this parameter to FALSE to equalize only the luminance plane.
*/
int frcColorEqualize(Image* dest, const Image* source)
{
	return imaqColorEqualize(dest, source, TRUE);
}

int frcColorEqualize(Image* dest, const Image* source, int colorEqualization)
{
	return imaqColorEqualize(dest, source, TRUE);
}

/*   Image Conversion functions */

/**
* @brief Automatically thresholds a grayscale image into a binary image for Particle Analysis based on a smart threshold. 
* Supports IMAQ_IMAGE_RGB, IMAQ_IMAGE_I16
* @param dest The destination image.
* @param source The image to threshold 
* @param windowWidth The width of the rectangular window around the pixel on which the function
*  performs the local threshold. This number must be at least 3 and cannot be larger than the width of source
* @param windowHeight The height of the rectangular window around the pixel on which the function 
* performs the local threshold. This number must be at least 3 and cannot be larger than the height of source
* @param method Specifies the local thresholding method the function uses. Value can be IMAQ_NIBLACK 
* (which computes thresholds for each pixel based on its local statistics using the Niblack local thresholding
* algorithm.), or IMAQ_BACKGROUND_CORRECTION (which does background correction first to eliminate non-uniform 
* lighting effects, then performs thresholding using the Otsu thresholding algorithm)
* @param deviationWeight Specifies the k constant used in the Niblack local thresholding algorithm, which 
* determines the weight applied to the variance calculation. Valid k constants range from 0 to 1. Setting 
* this value to 0 will increase the performance of the function because the function will not calculate the 
* variance for any of the pixels. The function ignores this value if method is not set to IMAQ_NIBLACK
* @param type Specifies the type of objects for which you want to look. Values can be IMAQ_BRIGHT_OBJECTS 
* or IMAQ_DARK_OBJECTS.
* @param replaceValue Specifies the replacement value the function uses for the pixels of the kept objects 
* in the destination image.
* @return On success: 1. On failure: 0. To get extended error information, call GetLastError().
*/
int frcSmartThreshold(Image* dest, const Image* source, 
		unsigned int windowWidth, unsigned int windowHeight, LocalThresholdMethod method, 
		double deviationWeight, ObjectType type)
{
	float replaceValue = 1.0;
	return imaqLocalThreshold(dest, source, windowWidth, windowHeight, method, 
			deviationWeight, type, replaceValue);
}

int frcSmartThreshold(Image* dest, const Image* source, 
		unsigned int windowWidth, unsigned int windowHeight, LocalThresholdMethod method, 
		double deviationWeight, ObjectType type, float replaceValue)
{
	return imaqLocalThreshold(dest, source, windowWidth, windowHeight, method, 
			deviationWeight, type, replaceValue);
}

/**
* @brief Converts a grayscale image to a binary image for Particle Analysis based on a fixed threshold. 
* The function sets pixels values outside of the given range to 0. The function sets pixel values 
* within the range to a given value or leaves the values unchanged. 
* Use the simplified call to leave pixel values unchanged.
* Supports IMAQ_IMAGE_RGB, IMAQ_IMAGE_I16.
* 
* @param dest The destination image.
* @param source The image to threshold 
* @param rangeMin The lower boundary of the range of pixel values to keep
* @param rangeMax The upper boundary of the range of pixel values to keep.
* 
* @return int - error code: 0 = error. To get extended error information, call GetLastError().
*/
int frcSimpleThreshold(Image* dest, const Image* source, float rangeMin, float rangeMax)
{
	int newValue = 255;
	return frcSimpleThreshold(dest, source, rangeMin, rangeMax, newValue);
}

/**
* @brief Converts a grayscale image to a binary image for Particle Analysis based on a fixed threshold. 
* The function sets pixels values outside of the given range to 0. The function sets 
* pixel values within the range to the given value. 
* Supports IMAQ_IMAGE_RGB, IMAQ_IMAGE_I16.
* 
* @param dest The destination image.
* @param source The image to threshold 
* @param rangeMin The lower boundary of the range of pixel values to keep
* @param rangeMax The upper boundary of the range of pixel values to keep.
* @param newValue The replacement value for pixels within the range. Use the simplified call to leave the pixel values unchanged 
* 
* @return int - error code: 0 = error. To get extended error information, call GetLastError().
*/
int frcSimpleThreshold(Image* dest, const Image* source, float rangeMin, float rangeMax, float newValue)
{
	int useNewValue = TRUE;
	return imaqThreshold(dest, source, rangeMin, rangeMax, useNewValue, newValue);
}

/**
* @brief Applies a threshold to the Red, Green, and Blue values of a RGB image or the Hue, 
* Saturation, Luminance values for a HSL image. 
* Supports IMAQ_IMAGE_RGB, IMAQ_IMAGE_HSL.
* This simpler version filters based on a hue range in the HSL mode.
* 
* @param dest The destination image. This must be a IMAQ_IMAGE_U8 image.
* @param source The image to threshold 
* @param mode The color space to perform the threshold in. valid values are: IMAQ_RGB, IMAQ_HSL.
* @param plane1Range The selection range for the first plane of the image. Set this parameter to NULL to use a selection range from 0 to 255.
* @param plane2Range The selection range for the second plane of the image. Set this parameter to NULL to use a selection range from 0 to 255.
* @param plane3Range The selection range for the third plane of the image. Set this parameter to NULL to use a selection range from 0 to 255.
* 
* @return On success: 1. On failure: 0. To get extended error information, call GetLastError().
* */
int frcColorThreshold(Image* dest, const Image* source, ColorMode mode, 
		const Range* plane1Range, const Range* plane2Range, const Range* plane3Range)
{
	int replaceValue = 1;
	return imaqColorThreshold(dest, source, replaceValue, mode, plane1Range, plane2Range, plane3Range);
}

/**
* @brief Applies a threshold to the Red, Green, and Blue values of a RGB image or the Hue, 
* Saturation, Luminance values for a HSL image. 
* Supports IMAQ_IMAGE_RGB, IMAQ_IMAGE_HSL.
* The simpler version filters based on a hue range in the HSL mode.
* 
* @param dest The destination image. This must be a IMAQ_IMAGE_U8 image.
* @param source The image to threshold 
* @param replaceValue Value to assign to selected pixels. Defaults to 1 if simplified call is used.
* @param mode The color space to perform the threshold in. valid values are: IMAQ_RGB, IMAQ_HSL.
* @param plane1Range The selection range for the first plane of the image. Set this parameter to NULL to use a selection range from 0 to 255.
* @param plane2Range The selection range for the second plane of the image. Set this parameter to NULL to use a selection range from 0 to 255.
* @param plane3Range The selection range for the third plane of the image. Set this parameter to NULL to use a selection range from 0 to 255.
* 
* @return On success: 1. On failure: 0. To get extended error information, call GetLastError().
*/
int frcColorThreshold(Image* dest, const Image* source, int replaceValue, ColorMode mode, 
		const Range* plane1Range, const Range* plane2Range, const Range* plane3Range)
{	return imaqColorThreshold(dest, source, replaceValue, mode, plane1Range, plane2Range, plane3Range);}


/**
* @brief A simpler version of ColorThreshold that thresholds hue range in the HSL mode. Supports IMAQ_IMAGE_RGB, IMAQ_IMAGE_HSL.
* @param dest The destination image.
* @param source The image to threshold 
* @param hueRange The selection range for the hue (color). 
* @param minSaturation The minimum saturation value (1-255).  If not used, DEFAULT_SATURATION_THRESHOLD is the default.
* 
* @return On success: 1. On failure: 0. To get extended error information, call GetLastError().
*/
int frcHueThreshold(Image* dest, const Image* source, const Range* hueRange)
{ return frcHueThreshold(dest, source, hueRange, DEFAULT_SATURATION_THRESHOLD); }

int frcHueThreshold(Image* dest, const Image* source, const Range* hueRange, int minSaturation)
{
	// assume HSL mode
	ColorMode mode = IMAQ_HSL;  
	// Set saturation 100 - 255
	Range satRange;  satRange.minValue = minSaturation; satRange.maxValue = 255;
	// Set luminance 100 - 255
	Range lumRange;  lumRange.minValue = 100; lumRange.maxValue = 255;
	// Replace pixels with 1 if pass threshold filter
	int replaceValue = 1;
	return imaqColorThreshold(dest, source, replaceValue, mode, hueRange, &satRange, &lumRange);
}

/**
* @brief Extracts the Red, Green, Blue, or Hue, Saturation or Luminance information from a color image. 
* Supports IMAQ_IMAGE_RGB, IMAQ_IMAGE_HSL, IMAQ_IMAGE_RGB_U64.
* 
* @param image The source image that the function extracts the planes from.
* @param mode The color space that the function extracts the planes from. Valid values are IMAQ_RGB, IMAQ_HSL, IMAQ_HSV, IMAQ_HSI.
* @param plane1 On return, the first extracted plane. Set this parameter to NULL if you do not need this information. RGB-Red, HSL/HSV/HSI-Hue.
* @param plane2 On return, the second extracted plane. Set this parameter to NULL if you do not need this information. RGB-Green, HSL/HSV/HSI-Saturation.
* @param plane3 On return, the third extracted plane. Set this parameter to NULL if you do not need this information. RGB-Blue, HSL-Luminance, HSV-Value, HSI-Intensity.
*
* @return error code: 0 = error. To get extended error information, call GetLastError().
*/
int frcExtractColorPlanes(const Image* image, ColorMode mode, 
		Image* plane1, Image* plane2, Image* plane3)
{	return imaqExtractColorPlanes(image, mode, plane1, plane2, plane3); }

/**
* @brief Extracts the Hue information from a color image. Supports IMAQ_IMAGE_RGB, IMAQ_IMAGE_HSL, IMAQ_IMAGE_RGB_U64 
* 
* @param image The source image that the function extracts the plane from.
* @param huePlane On return, the extracted hue plane. 
* @param minSaturation the minimum saturation level required 0-255 (try 50)  
*          
* @return On success: 1. On failure: 0. To get extended error information, call GetLastError().     
*/
int frcExtractHuePlane(const Image* image, Image* huePlane)
{
	return frcExtractHuePlane(image, huePlane, DEFAULT_SATURATION_THRESHOLD);
}

int frcExtractHuePlane(const Image* image, Image* huePlane, int minSaturation)
{
	return frcExtractColorPlanes(image, IMAQ_HSL, huePlane, NULL, NULL);
}