Processing

Functions and types used to work with pixel data. More...

Typedefs
typedef cvbbool_t(*	TFLine) (void *pPrivate, cvbval_t LinesToDo)
	Start of or end of scan line callback function. More...
typedef void(*	TFNonlinear) (void *pPrivate, double &X, double &Y)
	Callback function that defines the transformation used in the CreateTransformedImage function. More...
typedef cvbbool_t(*	TFPixelBinary) (void *pPrivate, void *pPixel1, void *pPixel2, cvbdim_t X, cvbdim_t Y)
	Pixel callback for binary scanning functions. More...
typedef cvbbool_t(*	TFPixelUnary) (void *pPrivate, void *pPixel, cvbdim_t X, cvbdim_t Y)
	Pixel callback for unary scanning functions. More...
typedef cvbbool_t(*	TFProgress) (void *pPrivate, cvbval_t StepsTotal, cvbval_t StepsDone)
	Callback for providing progress feedback. More...
typedef cvbval_t	THistogram[256]
	Value histogram for one 8 BitsPerPixel IImageVPA plane. More...

Enumerations
enum	TNormalizeMode { Normalize_MeanVariance = 0 , Normalize_MinMax = 1 }
	Normalization mode used by CreateNormalizedImage. More...
enum	TSubPixelMode { SP_None = 0 , SP_Parabolic_Fast = 1 , SP_Parabolic_Accurate = 2 , SP_Gauss = 3 }
	Modes for calculating results at sub pixel accuracy. More...

Functions
cvbbool_t	ApplyWhiteBalance (IMG Image, double GainRed, double GainGreen, double GainBlue)
	Performs an in-place white balance on the given Image, applying the three gain factors. More...
cvbbool_t	CalculateWhiteBalance (IMG Image, TArea Area, double &GainRed, double &GainGreen, double &GainBlue)
	Calculate the white balance factors. More...
cvbbool_t	CreateColorFeatureImage (IMG ImageIn, IMG &ImageOut)
	Creates a 9-planar output image from an RGB ImageIn. More...
cvbbool_t	CreateColorTransform (IMG ImageIn, cvbval_t OutNumPlanes, cvbbool_t WrapAroundOverflow, void *Coefficients, IMG &ImageOut)
	Creates an n-planar output image using a linear combination of the planes of ImageIn. More...
cvbres_t	CreateFlatfieldCorrectedImage (IMG ImageIn, IMG ImageFlat, IMG ImageDark, double Gain, IMG &ImageOut)
	Performs a flat field correction on the given ImageIn with optional correction of the fix pattern noise. More...
cvbbool_t	CreateInversePolarImage (IMG ImageIn, double Alpha0, double InnerRadius, IMG &ImageOut)
	Creates an image with the inverse of the transformation performed by CreatePolarImage or CreatePolarImageEx. More...
cvbbool_t	CreateLinearCombinationImage (IMG ImageIn, cvbbool_t WrapAroundOverflow, void *Coefficients, IMG &ImageOut)
	Creates a monochrome output image using a linear combination of the planes of ImageIn. More...
cvbbool_t	CreateMeanVarianceImage (IMG ImageIn, IMG &ImageMean, IMG &ImageStandardDeviation)
	Creates a mean and a standard deviation image over all planes of ImageIn. More...
cvbbool_t	CreateMinMaxImage (IMG ImageIn, IMG &ImageMin, IMG &ImageMax)
	Creates a minimum and a maximum image over all planes of ImageIn. More...
cvbbool_t	CreateNormalizedImage (IMG ImageIn, TNormalizeMode Mode, double TargetMeanMin, double TargetStandardDeviationMax, IMG &ImageOut)
	Creates a normalized image of ImageIn. More...
cvbbool_t	CreateOverlayFromPixelList (PIXELLIST PixelList, IMG ImageIn, IMG &ImageOut)
	Creates a new image that has overlay bits set according to the coordinates in PixelList. More...
cvbbool_t	CreatePixelListFromOverlay (IMG ImageIn, cvbval_t PixelListDimension, cvbval_t Left, cvbval_t Top, cvbval_t Right, cvbval_t Bottom, PIXELLIST &PixelList)
	Creates an IPixelList from the coordinates of ImageIn pixels with set overlay bits. More...
cvbbool_t	CreatePolarImage (IMG ImageIn, double CenterX, double CenterY, double Alpha0, double InnerRadius, double OuterRadius, IMG &ImageOut)
	Creates a polar transformed image using linear interpolation from a full ring (360°). . More...
cvbbool_t	CreatePolarImageEx (IMG ImageIn, double CenterX, double CenterY, double Alpha0, double AlphaTotal, double InnerRadius, double OuterRadius, IMG &ImageOut)
	Creates a polar transformed image using linear interpolation where the ring segment can be fully specified. More...
cvbbool_t	CreateTransformedImage (IMG ImageIn, cvbval_t Width, cvbval_t Height, TFNonlinear Transformation, void *pPrivate, IMG &ImageOut)
	Creates an arbitrarily transformed, linear interpolated image from the given ImageIn. More...
cvbval_t	FindMaxima (IMG Image, cvbval_t PlaneIndex, cvbval_t Left, cvbval_t Top, cvbval_t Right, cvbval_t Bottom, cvbval_t Locality, cvbval_t Threshold, PIXELLIST &MaximaList)
	Search an image for maxima of gray values. More...
cvbbool_t	FindMaximaEx (IMG Image, cvbval_t PlaneIndex, cvbval_t Left, cvbval_t Top, cvbval_t Right, cvbval_t Bottom, cvbval_t Locality, double Threshold, PIXELLIST &MaximaList)
	Search an Image for local maxima of gray values without sub-pixel accuracy. More...
cvbbool_t	FindSubPixelMaxima (IMG Image, cvbdim_t PlaneIndex, cvbdim_t Left, cvbdim_t Top, cvbdim_t Right, cvbdim_t Bottom, cvbdim_t Locality, double Threshold, TSubPixelMode SubPixelMode, cvbdim_t Radius, PIXELLIST &MaximaList)
	Search an Image for local maxima of gray values with optional sub-pixel accuracy. More...
cvbbool_t	ImageHistogram (IMG Image, cvbval_t PlaneIndex, cvbdensity_t Density, TArea Area, THistogram &Histogram)
	Calculates the histogram of the 8 bit per plane Image plane at PlaneIndex. More...
cvbbool_t	InversePolarTransform (IMG ImageIn, double CenterX, double CenterY, double Alpha0, double InnerRadius, IMG ImageOut)
	Calculates the inverse of the transformation performed by CreatePolarImage or CreatePolarImageEx. More...
cvbval_t	ScanImageBinary (IMG Image1, IMG Image2, TArea Area, cvbdensity_t Density, cvbval_t ShiftX, cvbval_t ShiftY, cvbbool_t UseCS, TFPixelBinary FPixel, TFLine FStartLine, TFLine FEndLine, void *pPrivate)
	Scans the Area in all planes of the given Image1 and Image2. More...
cvbval_t	ScanImageUnary (IMG Image, TArea Area, cvbdensity_t Density, cvbbool_t UseCS, TFPixelUnary FPixel, TFLine FStartLine, TFLine FEndLine, void *pPrivate)
	Scans the Area in all planes of the Image. More...
cvbval_t	ScanPlaneBinary (IMG Image1, IMG Image2, cvbval_t PlaneIndex1, cvbval_t PlaneIndex2, TArea Area, cvbdensity_t Density, cvbval_t ShiftX, cvbval_t ShiftY, cvbbool_t UseCS, TFPixelBinary FPixel, TFLine FStartLine, TFLine FEndLine, void *pPrivate)
	Scans the Area in single planes of the given Image1 and Image2. More...
cvbval_t	ScanPlaneUnary (IMG Image, cvbval_t PlaneIndex, TArea Area, cvbdensity_t Density, cvbbool_t UseCS, TFPixelUnary FPixel, TFLine FStartLine, TFLine FEndLine, void *pPrivate)
	Scans the Area in a single plane with PlaneIndex of the Image. More...

Detailed Description

Functions and types used to work with pixel data.

Typedef Documentation

TFLine

cvbbool_t(* TFLine)(void *pPrivate, cvbval_t LinesToDo)

Start of or end of scan line callback function.

This callback function type is used to indicate a new line or the end of a line depending on its registration in the calling function.

Parameters

[in]	pPrivate	Pointer to user data given in via the calling function; e.g. pointer to object.
[in]	LinesToDo	Number of lines left to scan.

Returns

false if scanning should be aborted; true otherwise.

See also

ScanPlaneUnary, ScanImageUnary, ScanPlaneBinary, ScanImageBinary

TFNonlinear

void(* TFNonlinear)(void *pPrivate, double &X, double &Y)

Callback function that defines the transformation used in the CreateTransformedImage function.

Parameters

[in]	pPrivate	Private data pointer that was given to the calling function (e.g. CreateTransformedImage).
[in,out]	X	Input is the X component of the pixel coordinate to be transformed; write the transformed value back on this one (overwrite).
[in,out]	Y	Input is the Y component of the pixel coordinate to be transformed; write the transformed value back on this one (overwrite).

TFPixelBinary

cvbbool_t(* TFPixelBinary)(void *pPrivate, void *pPixel1, void *pPixel2, cvbdim_t X, cvbdim_t Y)

Pixel callback for binary scanning functions.

This callback function type is used by the scan functions ScanImageBinary and ScanPlaneBinary. This function pointer is called for each pixel in the selected TArea.

Parameters

[in]	pPrivate	Pointer to user data given in via ScanPlaneUnary or ScanImageUnary; e.g. pointer to object.
[in]	pPixel1	Pointer to the current pixel at (X, Y) in Image1. The actual layout of the data depends on the calling function.
[in]	pPixel2	Pointer to the current pixel at (X, Y) in Image2. The actual layout of the data depends on the calling function.
[in]	X	Current x coordinate in pixel coordinates.
[in]	Y	Current y coordinate in pixel coordinates.

Returns

false if scanning should be aborted; true otherwise.

See also

ScanPlaneBinary, ScanImageBinary

TFPixelUnary

cvbbool_t(* TFPixelUnary)(void *pPrivate, void *pPixel, cvbdim_t X, cvbdim_t Y)

Pixel callback for unary scanning functions.

This callback function type is used by the scan functions ScanPlaneUnary and ScanImageUnary. This function pointer is called for each pixel in the selected TArea.

Parameters

[in]	pPrivate	Pointer to user data given in via ScanPlaneUnary or ScanImageUnary; e.g. pointer to object.
[in]	pPixel	Pointer to the current pixel at (X, Y). The actual layout of the data depends on the calling function.
[in]	X	Current x coordinate in pixel coordinates.
[in]	Y	Current y coordinate in pixel coordinates.

Returns

false if scanning should be aborted; true otherwise.

See also

ScanPlaneUnary, ScanImageUnary

TFProgress

cvbbool_t(* TFProgress)(void *pPrivate, cvbval_t StepsTotal, cvbval_t StepsDone)

Callback for providing progress feedback.

The feedback provided by this function can e.g. be used to display a progress indicator during a lengthy operation.

Parameters

[in]	pPrivate	Private data pointer given to the calling function.
[in]	StepsTotal	Total number of steps that are going to be performed in the lengthy operation.
[in]	StepsDone	Number of steps that have already been performed.

Returns

false if the operation that invoked the callback is to be aborted; true to continue.

THistogram

THistogram

Value histogram for one 8 BitsPerPixel IImageVPA plane.

This array stores 256 values in the range [0 .. 255]. Every index in this array refers to a gray value. The value in the histogram at that location (index) is the count of that gray value in the inspected AOI.

See also

ImageHistogram

Enumeration Type Documentation

TNormalizeMode

enum TNormalizeMode

Normalization mode used by CreateNormalizedImage.

Enumerator
Normalize_MeanVariance	Image normalization with a target mean value and standard deviation. Attention Despite its name, the standard deviation is used instead of the variance.
Normalize_MinMax	Image normalization with target min and max value.

TSubPixelMode

enum TSubPixelMode

Modes for calculating results at sub pixel accuracy.

Enumerator
SP_None	No sub pixel calculation.
SP_Parabolic_Fast	Approximates a paraboloid. Fastest, but least accurate sub pixel mode. The shape of the extremum is assumed to be parabolic. The fit in this case is a linear fit, providing a slightly lower accuracy than a full-fledged least-squares fit. For most applications this mode is a reasonable trade-off, because typically the deviation of the local maxima from the actual parabolic shape causes more significant errors in the measurement than the difference between the linear fit and the least squares fit.
SP_Parabolic_Accurate	Best fit paraboloid approximation. Reasonably fast and accurate sub pixel mode. Performs a full least-squares fit of the extremum to a parabolic shape (in contrast to the linear fit in SP_Parabolic_Fast). This is an approximation of a Gaussian distribution SP_Gauss.
SP_Gauss	Gaussian distribution fit. Slowest, but most accurate sub pixel mode. Performs a least-squares fit of the extremum to a Gaussian intensity distribution.

Function Documentation

ApplyWhiteBalance()

cvbbool_t ApplyWhiteBalance	(	IMG	Image,
		double	GainRed,
		double	GainGreen,
		double	GainBlue
	)

Performs an in-place white balance on the given Image, applying the three gain factors.

Gray values exceeding the cvbdatatype_t dynamic range will be truncated.

The following BytesPerPixel for signed and unsigned integer cvbdatatype_t values are supported: 1, 2, 4, and 8. For floating point cvbdatatype_t values only 4 and 8 BytesPerPixel are supported.

Note

All planes in the Image must have the same cvbdatatype_t.

Parameters

[in]	Image	Image object handle on which to perform the white balance operation.
[in]	GainRed	Gain for the red channel.
[in]	GainGreen	Gain for the green channel.
[in]	GainBlue	Gain for the blue channel.

Returns

true if successful; false otherwise.

See also

CalculateWhiteBalance for calculating the three factors.

CalculateWhiteBalance()

cvbbool_t CalculateWhiteBalance	(	IMG	Image,
		TArea	Area,
		double &	GainRed,
		double &	GainGreen,
		double &	GainBlue
	)

Calculate the white balance factors.

The following BytesPerPixel for signed and unsigned integer cvbdatatype_t values are supported: 1, 2, 4, and 8. For floating point cvbdatatype_t values only 4 and 8 BytesPerPixel are supported.

Note

All planes in the Image must have the same cvbdatatype_t. Also a DT_Float or DT_Signed Image must not have negative pixel values for this operation to yield useful output!

Parameters

[in]	Image	Image object handle from which to calculate the gain factors.
[in]	Area	aoi in which to calculate the gain factors; the aoi is assumed to contain a portion of the image, that should be of neutral color, not saturated to white or black
[out]	GainRed	gain factor for the red channel
[out]	GainGreen	gain factor for the green channel
[out]	GainBlue	gain factor for the blue channel

Returns

true if successful; false otherwise.

CreateColorFeatureImage()

cvbbool_t CreateColorFeatureImage	(	IMG	ImageIn,
		IMG &	ImageOut
	)

Creates a 9-planar output image from an RGB ImageIn.

This function does the same as MantoColourTransform, a function that was originally published in the Manto.dll. It requires an image with 3 planes (R, G, B) as input and produces a result image with 9 planes (R, G, B, RG, RB, GB, R², G², B²).

The following BytesPerPixel for signed and unsigned integer cvbdatatype_t values are supported: 1, 2, 4, and 8. For floating point cvbdatatype_t values only 4 and 8 BytesPerPixel are supported.

Note

All ImageIn planes must have the same cvbdatatype_t. The target image is created via CreateGenericImageDT and uses the cvbdatatype_t of ImageIn.

The created ImageOut always has the default coordinate system (see TCoordinateMap).

Call ReleaseObject on ImageOut, when it is no longer needed.

Parameters

[in]	ImageIn	Image object handle of the source image.
[in]	ImageOut	Variable to receive the handle of the output image.

Returns

true if successfuk; false otherwise.

See also

CreateColorTransform

CreateColorTransform()

cvbbool_t CreateColorTransform	(	IMG	ImageIn,
		cvbval_t	OutNumPlanes,
		cvbbool_t	WrapAroundOverflow,
		void *	Coefficients,
		IMG &	ImageOut
	)

Creates an n-planar output image using a linear combination of the planes of ImageIn.

The arrangement of the Coefficients array is complex:
Therefore, assume that the ImageIn has m planes and the ImageOut n planes. The coefficient array needs (m + 1) * n elements. These elements are:

• (0,... , m- 1) being the weights for the output plane 1
• (m) being the offset for the output plane 1
• (m + 1,... , 2 * m) being the weights for output plane 2
• (2 * m + 1) being the offset for the output plane 2 and so on.

For each pixel the following calculation is done using the coefficients for the output planes as described above:

*pPixelOut = pPlanePixelsIn[0] * coefficient[0] + ... + pPlanePixelsIn[dim-1] * coefficient[dim-1] + coefficient[dim];

The following BytesPerPixel for signed and unsigned integer cvbdatatype_t values are supported: 1, 2, 4, and 8. For floating point cvbdatatype_t values only 4 and 8 BytesPerPixel are supported.

Note

All ImageIn planes must have the same cvbdatatype_t. The target image is created via CreateGenericImageDT and uses the cvbdatatype_t of ImageIn.

The created ImageOut always has the default coordinate system (see TCoordinateMap).

Call ReleaseObject on ImageOut, when it is no longer needed.

Parameters

[in]	ImageIn	Image object handle of the source image.
[in]	OutNumPlanes	Number of planes in the output image.
[in]	WrapAroundOverflow	true for wrap around at the upper/lower limit of the cvbdatatype_t range; false for truncation.
[in]	Coefficients	double array as described above.
[out]	ImageOut	Variable to receive the output image handle.

Returns

true if successful; false otherwise.

See also

CreateLinearCombinationImage

CreateFlatfieldCorrectedImage()

cvbres_t CreateFlatfieldCorrectedImage	(	IMG	ImageIn,
		IMG	ImageFlat,
		IMG	ImageDark,
		double	Gain,
		IMG &	ImageOut
	)

Performs a flat field correction on the given ImageIn with optional correction of the fix pattern noise.

To use this function, create a background image where the pixels' gray values span a range of roughly 50% to 75% of available dynamic range (fox example 128 to 192 in the case of 8Bit images). Optionally also take a dark image (e.g. by putting a lens cap on).

The flat field correction is being calculated using the formula:

‍ImageOut = (ImageIn - ImageDark) / (ImageFlat - ImageDark) * Gain

If no ImageDark was specified (nullptr) the calculation shortens to:

‍ImageOut = ImageIn / ImageFlat * Gain

The following BytesPerPixel for signed and unsigned integer cvbdatatype_t values are supported: 1, 2, 4, and 8. For floating point cvbdatatype_t values only 4 and 8 BytesPerPixel are supported.

Note

Call ReleaseObject on ImageOut, when it is no longer needed.

Parameters

[in]	ImageIn	The input image handle.
[in]	ImageFlat	The flat image showing the background.
[in]	ImageDark	Optional dark image; nullptr for none.
	Gain	A gain value that may be used to adjust the brightness of ImageOut. Usually roughly the average gray value of ImageIn is used.
[out]	ImageOut	Variable to receive the handle of the resulting image.

Returns

Smaller than zero on error. See Error Handling on how to work with error codes. Specifically the following codes are returned:

• CVC_ERROR (CVC_E_NOIMAGE) if either ImageIn or ImageFlat contains no valid image handle.
• CVC_ERROR (CVC_E_INVALIDDIMENSION) if ImageIn and ImageFlat or, if ImageDark was specified, ImageIn and ImageDark have different size and/or number of planes.
• CVC_ERROR (CVC_E_INVALIDDATATYPE) if the pixel data type of ImageIn and ImageFlat differs or, if ImageDark was specified, the pixel data type of ImageIn and ImageDark differs.
• CVC_ERROR (CVC_E_MEMORY) if the output image could not be created (the most likely reason for this is a lack of sufficiently large blocks of free memory).
• CVC_ERROR( CVC_E_ERROR) if an error occurred for which the reason could not be determined.

Since

CVB 2017 (13.00.000)

CreateInversePolarImage()

cvbbool_t CreateInversePolarImage	(	IMG	ImageIn,
		double	Alpha0,
		double	InnerRadius,
		IMG &	ImageOut
	)

Creates an image with the inverse of the transformation performed by CreatePolarImage or CreatePolarImageEx.

This function transforms the content of a rectangular image into a ring or ring segment. For a detailed explanation on Alpha0 and InnerRadius see the documentation of CreatePolarImageEx.

The ring (segment) will be centered in the resulting ImageOut, which is created via CreateCompatibleImage. The resulting width and height are twice the OuterRadius that is calculated as follows:

‍OuterRadius = ImageHeight (ImageIn) - 1 + InnerRadius

The background of the image's planes are initialized with the cvbdatatype_t dependent default value:

‍GetDatatypeMinMaxVal (ImageDatatype (ImageIn, plane), max, min): (max - min) / 2

Angles are measured clockwise and an angle of 0° describes a line segment in direction of the positive x-axis.

The following BytesPerPixel for signed and unsigned integer cvbdatatype_t values are supported: 1, 2, 4, and 8. For floating point cvbdatatype_t values only 4 and 8 BytesPerPixel are supported.

Note

Call ReleaseObject on ImageOut, when it is no longer needed.

Parameters

[in]	ImageIn	Image object handle containing the data to be transformed.
[in]	Alpha0	Start angle in degrees for ImageOut.
[in]	InnerRadius	Inner radius in pixels for ImageOut.
[out]	ImageOut	Variable to receive the handle of the result image.

Returns

true if successful; false otherwise.

See also

CreatePolarImageEx, InversePolarTransform

CreateLinearCombinationImage()

cvbbool_t CreateLinearCombinationImage	(	IMG	ImageIn,
		cvbbool_t	WrapAroundOverflow,
		void *	Coefficients,
		IMG &	ImageOut
	)

Creates a monochrome output image using a linear combination of the planes of ImageIn.

The number of elements in Coefficients must be ImageDimension (ImageIn) + 1, where the last element is an offset and the elements before it are the factors for the planes. For each pixel the following calculation is done:

*pPixelOut = pPlanePixelsIn[0] * coefficient[0] + ... + pPlanePixelsIn[dim-1] * coefficient[dim-1] + coefficient[dim];

The method is a shorthand for:

CreateColorTransform(ImageIn, 1, WrapAroundOverflow, Coefficients, ImageOut);

The following BytesPerPixel for signed and unsigned integer cvbdatatype_t values are supported: 1, 2, 4, and 8. For floating point cvbdatatype_t values only 4 and 8 BytesPerPixel are supported.

Note

All ImageIn planes must have the same cvbdatatype_t. The target image is created via CreateGenericImageDT and uses the cvbdatatype_t of ImageIn.

The created ImageOut always has the default coordinate system (see TCoordinateMap).

Call ReleaseObject on ImageOut, when it is no longer needed.

Parameters

[in]	ImageIn	Image object handle of the source image.
[in]	WrapAroundOverflow	true for wrap around at the upper/lower limit of the cvbdatatype_t range; false for truncation.
[in]	Coefficients	double array with weight coefficients and an offset as the last element.
[out]	ImageOut	Variable to receive the output image handle.

Returns

true if successful; false otherwise.

Example

cvbbool_t RGBToMono(IMG ImageIn, IMG &ImageOut)
{
  static const bool TRUNCATE = false;
 
  if(ImageDimension(ImageIn) != 3)
    return false;
  
  // R, G, B coefficients and no offset
  double coefficients[] = { 0.299, 0.587, 0.114, 0.0 };
  return CreateLinearCombinationImage(ImageIn, TRUNCATE, coefficients, ImageOut);
}

See also

CreateColorTransform

CreateMeanVarianceImage()

cvbbool_t CreateMeanVarianceImage	(	IMG	ImageIn,
		IMG &	ImageMean,
		IMG &	ImageStandardDeviation
	)

Creates a mean and a standard deviation image over all planes of ImageIn.

ImageMean is a single-plane image that will contain the mean value over all planes in ImageIn at their respective coordinate. The same is true for ImageStandardDeviation which contains the standard deviation respectively.

The following BytesPerPixel for signed and unsigned integer cvbdatatype_t values are supported: 1, 2, 4, and 8. For floating point cvbdatatype_t values only 4 and 8 BytesPerPixel are supported.

Note

All ImageIn planes must have the same cvbdatatype_t. ImageMean and ImageStandardDeviation are created with CreateGenericImageDT and the cvbdatatype_t of ImageIn. Also they have the same coordinate system (see TCoordinateMap) as ImageIn.

Call ReleaseObject on ImageMean and/or ImageStandardDeviation, when they are no longer needed.

Attention

Despite this function's name the standard deviation is calculated instead of the variance. Square the result if you need the variance.

Parameters

[in]	ImageIn	Image object handle of the source image.
[out]	ImageMean	Variable to receive the handle of the mean image object.
[out]	ImageStandardDeviation	Variable to receive the handle of the standard deviation image object.

Returns

true if successful; false otherwise.

CreateMinMaxImage()

cvbbool_t CreateMinMaxImage	(	IMG	ImageIn,
		IMG &	ImageMin,
		IMG &	ImageMax
	)

Creates a minimum and a maximum image over all planes of ImageIn.

ImageMin is a single-plane image that will contain the minimum value over all planes in ImageIn at their respective coordinate. The same is true for ImageMax which contains the maximum value respectively.

The following BytesPerPixel for signed and unsigned integer cvbdatatype_t values are supported: 1, 2, 4, and 8. For floating point cvbdatatype_t values only 4 and 8 BytesPerPixel are supported.

Note

All ImageIn planes must have the same cvbdatatype_t. ImageMin and ImageMax are created with CreateGenericImageDT and the cvbdatatype_t of ImageIn. Also they have the same coordinate system (see TCoordinateMap) as ImageIn.

Call ReleaseObject on ImageMin and/or ImageMax, when they are no longer needed.

Parameters

[in]	ImageIn	Image object handle of the source image.
[out]	ImageMin	Variable to receive the handle of the minimum image object.
[out]	ImageMax	Variable to receive the handle of the maximum image object.

Returns

true if successful; false otherwise.

CreateNormalizedImage()

cvbbool_t CreateNormalizedImage	(	IMG	ImageIn,
		TNormalizeMode	Mode,
		double	TargetMeanMin,
		double	TargetStandardDeviationMax,
		IMG &	ImageOut
	)

Creates a normalized image of ImageIn.

With the Mode parameter two possible procedures can be selected:

• Target min/max (Normalize_MinMax):
  The source image color range is stretched so that the target image shows a minimal value of TargetMeanMin and a maximal value of TargetStandardDeviationMax.
• Target standard deviation (Normalize_MeanVariance):
  The source image color range is stretched so that the target image has a mean value of TargetMeanMin and a standard deviation of TargetStandardDeviationMax.

The following BytesPerPixel for signed and unsigned integer cvbdatatype_t values are supported: 1, 2, 4, and 8. For floating point cvbdatatype_t values only 4 and 8 BytesPerPixel are supported.

Note

The target image is created via CreateCompatibleImage and has the same coordinate system (see TCoordinateMap) as ImageIn.

Call ReleaseObject on ImageOut, when it is no longer needed.

Attention

Despite the Mode name of Normalize_MeanVariance not the variance is used, but the standard deviation!

Parameters

[in]	ImageIn	Image object handle of the source image.
[in]	Mode	Normalize_MinMax or Normalize_MeanVariance (standard deviation).
[in]	TargetMeanMin	Either target mean or min depending on Mode.
[in]	TargetStandardDeviationMax	Either target standard deviation or max depending on Mode.
[out]	ImageOut	Variable to receive the output image handle.

Returns

true if successful; false otherwise.

CreateOverlayFromPixelList()

cvbbool_t CreateOverlayFromPixelList	(	PIXELLIST	PixelList,
		IMG	ImageIn,
		IMG &	ImageOut
	)

Creates a new image that has overlay bits set according to the coordinates in PixelList.

First ImageOut is created via CreateCompatibleImage with forced overlay bit (DT_Overlay). If ImageIn is overlay capable the overlays bits are copied with the pixel data to ImageOut; if not the overlay bits are reset to 0 while copying.

Then for each Pixel coordinate (x and y) in the PixelList, the overlay bit of the corresponding image pixel will be set. If a Pixel from the PixelList lies outside the ImageIn boundaries, it will be ignored.

The following BytesPerPixel for signed and unsigned integer cvbdatatype_t values are supported: 1, 2, 4, and 8.

Note

Call ReleaseObject on ImageOut, when it is no longer needed.

Parameters

[in]	PixelList	Pixel list handle of object that contains the overlay coordinate information. F
[in]	ImageIn	Input image handle of object providing the source pixel data.
[out]	ImageOut	Variable to receive the image handle that is the resulting IImageVPA with DT_Overlay

Returns

true if successful; false otherwise.

See also

CreatePixelListFromOverlay, IPixelList

CreatePixelListFromOverlay()

cvbbool_t CreatePixelListFromOverlay	(	IMG	ImageIn,
		cvbval_t	PixelListDimension,
		cvbval_t	Left,
		cvbval_t	Top,
		cvbval_t	Right,
		cvbval_t	Bottom,
		PIXELLIST &	PixelList
	)

Creates an IPixelList from the coordinates of ImageIn pixels with set overlay bits.

For each pixel in the given region (Left, Top, Right, Bottom) in ImageIn with the overlay bit being set (DT_Overlay), a Pixel is added to the newly created PixelList. Each new Pixel has the x and y Component set accordingly. Any additional PixelList __Component__s are set to 0.

The following BytesPerPixel for signed and unsigned integer cvbdatatype_t values are supported: 1, 2, 4, and 8.

Note

ImageIn must be overlay-capable (DT_Overlay set in cvbdatatype_t).

Release PixelList via ReleaseObject if not needed anymore.

Parameters

[in]	ImageIn	Image handle of overlay capable image object to analyze.
[in]	PixelListDimension	Number of __Component__s for the PixelList to be created. Range is [2 .. 256].
[in]	Left	Left edge of the AOI in pixel coordinates.
[in]	Top	Top edge of the AOI in pixel coordinates.
[in]	Right	Right edge of the AOI in pixel coordinates (inclusive).
[in]	Bottom	Bottom edge of the AOI in pixel coordinates (inclusive).
[out]	PixelList	Variable to receive the resulting IPixelList handle.

Returns

true if successful; false otherwise.

See also

CreateOverlayFromPixelList, IPixelList

CreatePolarImage()

cvbbool_t CreatePolarImage	(	IMG	ImageIn,
		double	CenterX,
		double	CenterY,
		double	Alpha0,
		double	InnerRadius,
		double	OuterRadius,
		IMG &	ImageOut
	)

Creates a polar transformed image using linear interpolation from a full ring (360°). .

This is a shorthand for CreatePolarImageEx with AlphaTotal = 360°:

CreatePolarImageEx(ImageIn, CenterX, CenterY, Alpha0, 360, InnerRadius, OuterRadius, ImageOut);

Note

Call ReleaseObject on ImageOut, when it is no longer needed.

Parameters

[in]	ImageIn	Image object handle of the image to be transformed.
[in]	CenterX	Positive X coordinate of transformation center.
[in]	CenterY	Positive Y coordinate of transformation center.
[in]	Alpha0	Angle in degrees where to start the polar transformation.
[in]	InnerRadius	Inner radius in pixels for transformation.
[in]	OuterRadius	Outer radius in pixels for transformation.
[out]	ImageOut	Variable to receive the handle to the transformed image object.

Returns

true if successful; false otherwise.

See also

CreatePolarImageEx

CreatePolarImageEx()

cvbbool_t CreatePolarImageEx	(	IMG	ImageIn,
		double	CenterX,
		double	CenterY,
		double	Alpha0,
		double	AlphaTotal,
		double	InnerRadius,
		double	OuterRadius,
		IMG &	ImageOut
	)

Creates a polar transformed image using linear interpolation where the ring segment can be fully specified.

In the image above (300×300) the parameters are roughly as follows:

CenterX, CenterY		150,150		(yellow point)
Alpha0		100°		(line that ends with green point)
AlphaTotal		185°		(line that ends with red point)
InnerRadius		80		(line segment from yellow to white point)
OuterRadius		120		(line segment from yellow to green or red point)

Angles are measured clockwise and an angle of 0° describes a line segment in direction of the positive x-axis. The AlphaTotal defines the length of the ring segment. Thus the line segment that ends with the red point has the absolute angle of Alpha0 + AlphaTotal.

The resulting dimensions of ImageOut, which is created via CreateCompatibleImage, are calculated as follows:

‍

(OuterRadius and InnerRadius are inclusive)

The following BytesPerPixel for signed and unsigned integer cvbdatatype_t values are supported: 1, 2, 4, and 8. For floating point cvbdatatype_t values only 4 and 8 BytesPerPixel are supported.

Note

This function supports values of AlphaTotal being less than and being greater than 360°. Values being greater than 360° create an overscan image where the image data from the start is repeated.

Call ReleaseObject on ImageOut, when it is no longer needed.

Parameters

[in]	ImageIn	Image object handle of the image to be transformed.
[in]	CenterX	Positive X component of pixel coordinate of transformation center.
[in]	CenterY	Positive Y component of pixel coordinate of transformation center.
[in]	Alpha0	Angle in degrees where to start the polar transformation.
[in]	AlphaTotal	Positive, non-0 total radial angle in degrees.
[in]	InnerRadius	Inner radius in pixels for transformation.
[in]	OuterRadius	Outer radius in pixels for transformation.
[out]	ImageOut	Variable to receive the handle to the transformed image object.

Returns

true if successful; false otherwise.

See also

CreatePolarImage, CreateInversePolarImage

CreateTransformedImage()

cvbbool_t CreateTransformedImage	(	IMG	ImageIn,
		cvbval_t	Width,
		cvbval_t	Height,
		TFNonlinear	Transformation,
		void *	pPrivate,
		IMG &	ImageOut
	)

Creates an arbitrarily transformed, linear interpolated image from the given ImageIn.

This function creates a new image via CreateCompatibleImage with the given Width and Height. The Transformation callback function is used for transforming each pixel coordinate.

The following BytesPerPixel for signed and unsigned integer cvbdatatype_t values are supported: 1, 2, 4, and 8. For floating point cvbdatatype_t values only 4 and 8 BytesPerPixel are supported.

Note

Call ReleaseObject on ImageOut, when it is no longer needed.

Parameters

[in]	ImageIn	Image object handle of the source image.
[in]	Width	Width of the target image to be created.
[in]	Height	Height of the target image to be created.
[in]	Transformation	Callback for coordinate transformation.
[in]	pPrivate	Pointer to user data, e.g. object pointer, passed in each call to Transformation.
[out]	ImageOut	Variable to receive the handle to the result image.

Returns

true if successful, false otherwise.

Example

struct ImageSize
{
  cvbdim_t Width;
  cvbdim_t Height;
};
 
// forward declaration
void __stdcall PointReflectTransformer(void *pPrivate, double &x, double &y);
 
cvbbool_t CreatePointReflectionImage(IMG ImageIn, IMG &ImageOut)
{
  ImageSize size = { ImageWidth(ImageIn), ImageHeight(ImageIn) };
  return CreateTransformedImage(ImageIn, size.Width, size.Height, &PointReflectTransformer, &size, ImageOut);
}
 
void __stdcall PointReflectTransformer(void *pPrivate, double &x, double &y)
{
  ImageSize size = *reinterpret_cast<ImageSize*>(pPrivate);
  x = size.Width - 1 - x;
  y = size.Height - 1 - y;
}

FindMaxima()

cvbval_t FindMaxima	(	IMG	Image,
		cvbval_t	PlaneIndex,
		cvbval_t	Left,
		cvbval_t	Top,
		cvbval_t	Right,
		cvbval_t	Bottom,
		cvbval_t	Locality,
		cvbval_t	Threshold,
		PIXELLIST &	MaximaList
	)

Search an image for maxima of gray values.

A local maximum is defined as the brightest pixels above a Threshold and surrounded by pixels of lower intensity. No two local maxima are allowed to be closer to each other than defined by the parameter Locality.

The following BytesPerPixel for signed and unsigned integer cvbdatatype_t values are supported: 1, 2. Additionally signed 4 BytesPerPixel is supported.

Deprecated:

This function will crash if you use Image objects one MPixel and up due to the recursive algorithm it uses. Please either use the FindMaximaEx or FindSubPixelMaxima directly.

Parameters

[in]	Image	Handle of the image object to be searched in for local maxima.
[in]	PlaneIndex	Plane of source Image to search in.
[in]	Left	Left edge of the AOI in pixel coordinates.
[in]	Top	Top edge of the AOI in pixel coordinates.
[in]	Right	Right edge (inclusive) of the AOI in pixel coordinates.
[in]	Bottom	Bottom edge (inclusive) of the AOI in pixel coordinates.
[in]	Locality	Positive minimum L1 distance in pixels between two neighboring maxima.
[in]	Threshold	Minimum gray value for a local maximum to be considered.
[out]	MaximaList	Variable to receive the IPixelList containing all maxima points (x, y, gray value).

Returns

true if successful; false otherwise.

See also

IPixelList, FindMaximaEx, FindSubPixelMaxima

FindMaximaEx()

cvbbool_t FindMaximaEx	(	IMG	Image,
		cvbval_t	PlaneIndex,
		cvbval_t	Left,
		cvbval_t	Top,
		cvbval_t	Right,
		cvbval_t	Bottom,
		cvbval_t	Locality,
		double	Threshold,
		PIXELLIST &	MaximaList
	)

Search an Image for local maxima of gray values without sub-pixel accuracy.

This is an alias for FindSubPixelMaxima with:

FindSubPixelMaxima(Image, PlaneIndex, Left, Top, Right, Bottom, Locality, Threshold, SP_None, 0, MaximaList);

Parameters

[in]	Image	Handle of the image object to be searched in for local maxima.
[in]	PlaneIndex	Plane of source Image to search in.
[in]	Left	Left edge of the AOI in pixel coordinates.
[in]	Top	Top edge of the AOI in pixel coordinates.
[in]	Right	Right edge (inclusive) of the AOI in pixel coordinates.
[in]	Bottom	Bottom edge (inclusive) of the AOI in pixel coordinates.
[in]	Locality	Positive minimum L1 distance in pixels between two neighboring maxima.
[in]	Threshold	Minimum gray value for a local maximum to be considered. Note that the minimal possible value for the image's pixel type is never eligible to be a local maximum (e.g. if the image uses 8 bits per pixel unsigned, pixels with value 0 will never be a local maximum even if the threshold has been set to 0.
[out]	MaximaList	Variable to receive the IPixelList containing all maxima points (x, y, gray value).

Returns

true if successful; false otherwise.

See also

IPixelList, FindSubPixelMaxima

FindSubPixelMaxima()

cvbbool_t FindSubPixelMaxima	(	IMG	Image,
		cvbdim_t	PlaneIndex,
		cvbdim_t	Left,
		cvbdim_t	Top,
		cvbdim_t	Right,
		cvbdim_t	Bottom,
		cvbdim_t	Locality,
		double	Threshold,
		TSubPixelMode	SubPixelMode,
		cvbdim_t	Radius,
		PIXELLIST &	MaximaList
	)

Search an Image for local maxima of gray values with optional sub-pixel accuracy.

A local maximum is defined as the brightest pixels above a Threshold and surrounded by pixels of lower intensity. No two local maxima are allowed to be closer to each other than defined by the parameter Locality.

The local maxima are being searched for at pixel accuracy. Then an optional step can be applied, that generates sub-pixel accurate results by fitting a selectable model to the gray values within the specified Radius (see TSubPixelMode). The Radius is only used with SP_Parabolic_Accurate and SP_Gauss. For SP_Parabolic_Fast the Radius is always 1 (8-connected).

The following BytesPerPixel for signed and unsigned integer cvbdatatype_t values are supported: 1, 2, 4, and 8. For floating point cvbdatatype_t values only 4 and 8 BytesPerPixel are supported.

Limits of Sub-Pixel Accuracy

Maximum lies within \a Radius pixels of the \a Image border

The result reported by this function will have a bias of the order of 0.5 to 1.0 pixels towards the border of the Image and away from the real location of the maximum.

This is an artifact that stems from the fact that the images in Common Vision Blox are internally extended beyond their border by up to four pixels in order to accommodate filter operations with larger filter masks. This extension is implemented by repeating the outermost pixel rows and columns, leading to a notable deviation of a maximum that lies right on the border from its assumed parabolic or Gaussian shape.

Real-world data deviates from parabolic/Gaussian distribution

In a real-world application, the accuracy that can be reached by using a parabolic or Gaussian fit will be limited to no less than roughly 0.005 pixels.

This is not an artifact of the calculation that is being carried out, but rather the result of a difference between the model applied and the reality - if the sub pixel calculations are being carried out on an artificial image where the gray value distribution perfectly matches the assumed model (Gaussian or parabolic) then the sub pixel measurement results will - within the limits of numerical accuracy - perfectly fit the parameters used during generation of the gray value distribution.

Note

Free the returned MaximaList via ReleaseObject if not needed anymore.

The distance for the Locality is calculated in L1 norm which is not the Euclidean distance. Here the distance of the x- and y-distances are checked individually for performance reasons. Thus the Locality is a square and not a circle.

The Radius, if used, has a significant impact on processing time as the amount of pixels to be investigated increases with the square of the Radius. Increasing the Radius will not necessarily yield better results as in a typical application the deviation of the intensity distribution around a local maximum will increase as you go further away from the maximum. Good values for the Radius are one or two.

Parameters

[in]	Image	Handle of the image object to be searched in for local maxima.
[in]	PlaneIndex	Plane of source Image to search in.
[in]	Left	Left edge of the AOI in pixel coordinates.
[in]	Top	Top edge of the AOI in pixel coordinates.
[in]	Right	Right edge (inclusive) of the AOI in pixel coordinates.
[in]	Bottom	Bottom edge (inclusive) of the AOI in pixel coordinates.
[in]	Locality	Positive minimum L1 distance in pixels between two neighboring maxima.
[in]	Threshold	Minimum gray value for a local maximum to be considered. Note that the minimal possible value for the image's pixel type is never eligible to be a local maximum (e.g. if the image uses 8 bits per pixel unsigned, pixels with value 0 will never be a local maximum even if the threshold has been set to 0.
[in]	SubPixelMode	Model/mode with which to determine the sub pixel accurate position of the local maxima.
[in]	Radius	Defines the L1 norm radius over which the sub pixel fit of the local maxima should be performed (used only for SP_Parabolic_Accurate and SP_Gauss). Valid values are in the range [0 .. 4] (0 forces SubPixelMode SP_None).
[out]	MaximaList	Variable to receive the IPixelList containing all maxima points (x, y, gray value).

Returns

true if successful; false otherwise.

See also

IPixelList, SortPixelsByPosition, SortPixelsByValue, TruncatePixelList

ImageHistogram()

cvbbool_t ImageHistogram	(	IMG	Image,
		cvbval_t	PlaneIndex,
		cvbdensity_t	Density,
		TArea	Area,
		THistogram &	Histogram
	)

Calculates the histogram of the 8 bit per plane Image plane at PlaneIndex.

The histogram is the representation of the distribution of the pixel values in the given Area of the plane identified by PlaneIndex in the given Image. For 8 bit per plane there a 256 possible bins (one for each possible pixel value [0 .. 255]). Each bin contains the count of the respective pixel value in the whole Area. Thus the index 0 in Histogram will contain the number of all pure black pixels in the Area.

Note

Only 8-bit images are supported (cvbdatatype_t of 8). As with most TArea functions, this function uses the image's coordinate system (see TCoordinateMap).

Parameters

[in]	Image	Image object handle of the source image.
[in]	PlaneIndex	Image plane index for which the histogram is to be calculated.
[in]	Density	Processing density from 1 to 1000, where 1000 means all pixels (100%).
[in]	Area	Area of interest in image coordinates for which the histogram is calculated.
[out]	Histogram	Array to be filled with the histogram data.

Returns

true if successful; false otherwise.

See also

THistogram

InversePolarTransform()

cvbbool_t InversePolarTransform	(	IMG	ImageIn,
		double	CenterX,
		double	CenterY,
		double	Alpha0,
		double	InnerRadius,
		IMG	ImageOut
	)

Calculates the inverse of the transformation performed by CreatePolarImage or CreatePolarImageEx.

This function transforms the content of a rectangular image into a ring or ring segment. For a detailed explanation on Alpha0 and InnerRadius see the documentation of CreatePolarImageEx.

The ring (segment) will be centered around (CenterX, CenterY) in the ImageOut, which has to have the same cvbdatatype_t as ImageIn. The resulting width and height of the ring are twice the OuterRadius that is calculated as follows:

‍OuterRadius = ImageHeight (ImageIn) - 1 + InnerRadius

Regions outside the ring (segment) are not affected.

Angles are measured clockwise and an angle of 0° describes a line segment in direction of the positive x-axis.

The following BytesPerPixel for signed and unsigned integer cvbdatatype_t values are supported: 1, 2, 4, and 8. For floating point cvbdatatype_t values only 4 and 8 BytesPerPixel are supported.

Note

If the resulting coordinates are outside the boundaries of ImageOut, no error will be returned and the invalid pixels will simply not be written. Thus even if no resulting pixel will lay inside the boundaries of ImageOut, no error will be returned.

Parameters

[in]	ImageIn	Image object handle containing the data to be transformed.
[in]	Alpha0	Start angle in degrees for ImageOut.
[in]	CenterX	Positive X component of pixel coordinate of transformation center.
[in]	CenterY	Positive Y component of pixel coordinate of transformation center.
[in]	InnerRadius	Inner radius in pixels for ImageOut.
[in]	ImageOut	Image object to which the transformation is written.

Returns

true if successful; false otherwise.

See also

CreateInversePolarImage, CreatePolarImageEx

ScanImageBinary()

cvbval_t ScanImageBinary	(	IMG	Image1,
		IMG	Image2,
		TArea	Area,
		cvbdensity_t	Density,
		cvbval_t	ShiftX,
		cvbval_t	ShiftY,
		cvbbool_t	UseCS,
		TFPixelBinary	FPixel,
		TFLine	FStartLine,
		TFLine	FEndLine,
		void *	pPrivate
	)

Scans the Area in all planes of the given Image1 and Image2.

For each pixel (FPixel), each beginning of a line (FStartLine) and each end of a line (FEndLine), the respective callback function is called. The scanning is limited to the Area and Density. If any callback function returns false, the processing is aborted. The function then reports the number of processed pixels until the abort.

This function supports any cvbdatatype_t as only the pointers to the pixels are given in the FPixel callback. As this function works on all planes, the pPixel1 and pPixel2 parameters of the FPixel callback function will point to the first element in a pointer array with the length of ImageDimension (Image) + 1. The first element is the pointer to the pixelin plane 0, the second is the pointer to the pixel in plane 1, and so on. The last entry is a nullptr to terminate the array.

Note

Usage of the Image object's coordinate system (see TCoordinateMap) is configurable via UseCS. Usage of the coordinate system only refers to the Area interpretation which will be transformed via Image1 object's coordinate system. Coordinates in the callback functions are always given in pixel coordinates.

If a location (x, y) is not present in either Image1 or Image2, the FPixel callback is not called for that location. The returned number of pixels is negative then and does not incorporate this pixel.

Attention

If Image1 and Image2 have differing number of planes, the pixel pointers will have different number of elements respectively.

Parameters

[in]	Image1	Image object handle of the first image.
[in]	Image2	Image object handle of the second image.
[in]	Area	Area of interest to be scanned.
[in]	Density	Processing density from 1 to 1000, where 1000 means all pixels (100%).
[in]	ShiftX	Horizontal shift in pixels between the two source images.
[in]	ShiftY	Vertical shift in pixels between the two source images
[in]	UseCS	true, if the coordinate system is used and the Area should be transformed; false otherwise.
[in]	FPixel	Optional callback to process each pixel that lies within the Area and matches the selected Density.
[in]	FStartLine	Optional callback to signal each beginning of a new line.
[in]	FEndLine	Optional callback to signal each end of a line.
[in]	pPrivate	Pointer to user data like an object pointer. This pointer is passed to all callbacks.

Returns

Number of pixels traversed (all planes are considered to be one pixel):

• positive number if all pixels were inside the Image
• negative number if some pixels were outside the Image
• -1 on error

See also

TFPixelBinary, TFLine, ScanPlaneUnary, ScanImageUnary, ScanPlaneBinary

ScanImageUnary()

cvbval_t ScanImageUnary	(	IMG	Image,
		TArea	Area,
		cvbdensity_t	Density,
		cvbbool_t	UseCS,
		TFPixelUnary	FPixel,
		TFLine	FStartLine,
		TFLine	FEndLine,
		void *	pPrivate
	)

Scans the Area in all planes of the Image.

For each pixel (FPixel), each beginning of a line (FStartLine) and each end of a line (FEndLine), the respective callback function is called. The scanning is limited to the Area and Density. If any callback function returns false, the processing is aborted. The function then reports the number of processed pixels until the abort.

This function supports any cvbdatatype_t as only the pointers to the pixels are given in the FPixel callback. As this function works on all planes, the pPixel parameter of the FPixel callback function will point to the first element in a pointer array with the length of ImageDimension (Image) + 1. The first element is the pointer to the pixel in plane 0, the second is the pointer to the pixel in plane 1, and so on. The last entry is a nullptr to terminate the array.

Note

Usage of the Image object's coordinate system (see TCoordinateMap) is configurable via UseCS. Usage of the coordinate system only refers to the Area interpretation. Coordinates in the callback functions are always given in pixel coordinates.

If a location (x, y) is not present in Image, the FPixel callback is not called for that location. The returned number of pixels is negative then and does not incorporate this pixel.

Parameters

[in]	Image	Image object handle of the source image.
[in]	Area	Area of interest to be scanned.
[in]	Density	Processing density from 1 to 1000, where 1000 means all pixels (100%).
[in]	UseCS	true, if the coordinate system is used and the Area should be transformed; false otherwise.
[in]	FPixel	Optional callback to process each pixel that lies within the Area and matches the selected Density.
[in]	FStartLine	Optional callback to signal each beginning of a new line.
[in]	FEndLine	Optional callback to signal each end of a line.
[in]	pPrivate	Pointer to user data like an object pointer. This pointer is passed to all callbacks.

Returns

Number of pixels traversed (all planes are considered to be one pixel):

• positive number if all pixels were inside the Image
• negative number if some pixels were outside the Image
• -1 on error

Example:

#include <cstdlib>
#include <iostream>
#include <iCVCImg.h>
 
// forward declaration
cvbbool_t __stdcall GetMax(void *pPrivate, void *pPixel, cvbdim_t x, cvbdim_t y);
 
static const cvbdim_t WIDTH = 640;
static const cvbdim_t HEIGHT = 480;
 
int main()
{
  IMG hImg = nullptr;
  if(!CreateGenericImageDT(1, WIDTH, HEIGHT, 16, hImg)) // Mono16
    return EXIT_FAILURE;
    
  TArea fullImage = { 0 };
  MaxImageArea(hImg, fullImage);
  InitializeImageAreaEx(hImg, /* plane */ 0, fullImage, /* value */ 0.0);
  cvbval_t maxValue = 4711;
  CVB::SetPixVal(hImg, /* plane */ 0, /* x */ 42, /* y */ 434, maxValue);
  
  cvbuint16_t max = 0;
  ScanImageUnary(hImg, fullImage, /* density */ 1000, /* use cs */ false, &GetMax, nullptr, nullptr, &max);
  if(max == maxValue)
    std::cout << "Max is " << maxValue << " as it should be :)\n";
  else
    std::cerr << "Max is not " << maxValue << " as expected, but " << max << "\n";
  
  ReleaseObject(hImg);
  
  return EXIT_SUCCESS;
}
 
cvbbool_t __stdcall GetMax(void *pPrivate, void *pPixel, cvbdim_t x, cvbdim_t y)
{
  cvbuint16_t &max = *reinterpret_cast<cvbuint16_t*>(pPrivate);
  cvbuint16_t pixVal = *reinterpret_cast<cvbuint16_t**>(pPixel)[0]; // array of values
  
  if(pixVal > max)
    max = pixVal;
    
  return true;
}

See also

TFPixelUnary, TFLine, ScanPlaneUnary, ScanPlaneBinary, ScanImageBinary

ScanPlaneBinary()

cvbval_t ScanPlaneBinary	(	IMG	Image1,
		IMG	Image2,
		cvbval_t	PlaneIndex1,
		cvbval_t	PlaneIndex2,
		TArea	Area,
		cvbdensity_t	Density,
		cvbval_t	ShiftX,
		cvbval_t	ShiftY,
		cvbbool_t	UseCS,
		TFPixelBinary	FPixel,
		TFLine	FStartLine,
		TFLine	FEndLine,
		void *	pPrivate
	)

Scans the Area in single planes of the given Image1 and Image2.

For each pixel (FPixel), each beginning of a line (FStartLine) and each end of a line (FEndLine), the respective callback function is called. The scanning is limited to the Area and Density. If any callback function returns false, the processing is aborted. The function then reports the number of processed pixels until the abort.

This function supports any cvbdatatype_t as only the pointers to the pixels are given in the FPixel callback. As this function only works on one plane respectively, the pPixel1 and pPixel2 parameters of the FPixel callback function will only point to one element.

Note

Usage of the Image object's coordinate system (see TCoordinateMap) is configurable via UseCS. Usage of the coordinate system only refers to the Area interpretation which will be transformed via Image1 object's coordinate system. Coordinates in the callback functions are always given in pixel coordinates.

If a location (x, y) is not present in either Image1 or Image2, the FPixel callback is not called for that location. The returned number of pixels is negative then and does not incorporate this pixel.

Attention

If Image1 and Image2 have differing number of planes, the pixel pointers will have different number of elements respectively.

Parameters

[in]	Image1	Image object handle of the first image.
[in]	Image2	Image object handle of the second image.
[in]	PlaneIndex1	Index of Image1 object's plane.
[in]	PlaneIndex2	Index of Image2 object's plane.
[in]	Area	Area of interest to be scanned.
[in]	Density	Processing density from 1 to 1000, where 1000 means all pixels (100%).
[in]	ShiftX	Horizontal shift in pixels between the two source images.
[in]	ShiftY	Vertical shift in pixels between the two source images
[in]	UseCS	true, if the coordinate system is used and the Area should be transformed; false otherwise.
[in]	FPixel	Optional callback to process each pixel that lies within the Area and matches the selected Density.
[in]	FStartLine	Optional callback to signal each beginning of a new line.
[in]	FEndLine	Optional callback to signal each end of a line.
[in]	pPrivate	Pointer to user data like an object pointer. This pointer is passed to all callbacks.

Returns

Number of pixels traversed (all planes are considered to be one pixel):

• positive number if all pixels were inside the Image
• negative number if some pixels were outside the Image
• -1 on error

See also

TFPixelBinary, TFLine, ScanPlaneUnary, ScanImageUnary, ScanImageBinary

ScanPlaneUnary()

cvbval_t ScanPlaneUnary	(	IMG	Image,
		cvbval_t	PlaneIndex,
		TArea	Area,
		cvbdensity_t	Density,
		cvbbool_t	UseCS,
		TFPixelUnary	FPixel,
		TFLine	FStartLine,
		TFLine	FEndLine,
		void *	pPrivate
	)

Scans the Area in a single plane with PlaneIndex of the Image.

For each pixel (FPixel), each beginning of a line (FStartLine) and each end of a line (FEndLine), the respective callback function is called. The scanning is limited to the Area and Density. If any callback function returns false, the processing is aborted. The function then reports the number of processed pixels until the abort.

This function supports any cvbdatatype_t as only the pointer to the pixel is given in the FPixel callback. As this function only works on one plane, the pPixel parameter of the FPixel callback function will only point to this one element.

Note

Usage of the Image object's coordinate system (see TCoordinateMap) is configurable via UseCS. Usage of the coordinate system only refers to the Area interpretation. Coordinates in the callback functions are always given in pixel coordinates.

If a location (x, y) is not present in Image, the FPixel callback is not called for that location. The returned number of pixels is negative then and does not incorporate this pixel.

Parameters

[in]	Image	Image object handle of the source image.
[in]	PlaneIndex	Index of plane to be scanned.
[in]	Area	Area of interest to be scanned.
[in]	Density	Processing density from 1 to 1000, where 1000 means all pixels (100%).
[in]	UseCS	true, if the coordinate system is used and the Area should be transformed; false otherwise.
[in]	FPixel	Optional callback to process each pixel that lies within the Area and matches the selected Density.
[in]	FStartLine	Optional callback to signal each beginning of a new line.
[in]	FEndLine	Optional callback to signal each end of a line.
[in]	pPrivate	Pointer to user data like an object pointer. This pointer is passed to all callbacks.

Returns

Number of pixels traversed:

• positive number if all pixels were inside the Image
• negative number if some pixels were outside the Image
• -1 on error

See also

TFPixelUnary, TFLine, ScanImageUnary, ScanPlaneBinary, ScanImageBinary