Image Manager (CVCImg.dll) 14.0
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 }
 
enum  TSubPixelMode { SP_None = 0 , SP_Parabolic_Fast = 1 , SP_Parabolic_Accurate = 2 , SP_Gauss = 3 }
 

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]pPrivatePointer to user data given in via the calling function; e.g. pointer to object.
[in]LinesToDoNumber 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]pPrivatePrivate data pointer that was given to the calling function (e.g. CreateTransformedImage).
[in,out]XInput is the X component of the pixel coordinate to be transformed; write the transformed value back on this one (overwrite).
[in,out]YInput 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]pPrivatePointer to user data given in via ScanPlaneUnary or ScanImageUnary; e.g. pointer to object.
[in]pPixel1Pointer to the current pixel at (X, Y) in Image1. The actual layout of the data depends on the calling function.
[in]pPixel2Pointer to the current pixel at (X, Y) in Image2. The actual layout of the data depends on the calling function.
[in]XCurrent x coordinate in pixel coordinates.
[in]YCurrent 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]pPrivatePointer to user data given in via ScanPlaneUnary or ScanImageUnary; e.g. pointer to object.
[in]pPixelPointer to the current pixel at (X, Y). The actual layout of the data depends on the calling function.
[in]XCurrent x coordinate in pixel coordinates.
[in]YCurrent 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]pPrivatePrivate data pointer given to the calling function.
[in]StepsTotalTotal number of steps that are going to be performed in the lengthy operation.
[in]StepsDoneNumber 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

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

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]ImageImage object handle on which to perform the white balance operation.
[in]GainRedGain for the red channel.
[in]GainGreenGain for the green channel.
[in]GainBlueGain 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]ImageImage object handle from which to calculate the gain factors.
[in]Areaaoi 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]GainRedgain factor for the red channel
[out]GainGreengain factor for the green channel
[out]GainBluegain 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]ImageInImage object handle of the source image.
[in]ImageOutVariable 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]ImageInImage object handle of the source image.
[in]OutNumPlanesNumber of planes in the output image.
[in]WrapAroundOverflowtrue for wrap around at the upper/lower limit of the cvbdatatype_t range; false for truncation.
[in]Coefficientsdouble array as described above.
[out]ImageOutVariable 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]ImageInThe input image handle.
[in]ImageFlatThe flat image showing the background.
[in]ImageDarkOptional dark image; nullptr for none.
GainA gain value that may be used to adjust the brightness of ImageOut. Usually roughly the average gray value of ImageIn is used.
[out]ImageOutVariable to receive the handle of the resulting image.
Returns
Smaller than zero on error. See ErrorHandling 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]ImageInImage object handle containing the data to be transformed.
[in]Alpha0Start angle in degrees for ImageOut.
[in]InnerRadiusInner radius in pixels for ImageOut.
[out]ImageOutVariable 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);
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.
Definition: ScanExports.cpp:1081

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]ImageInImage object handle of the source image.
[in]WrapAroundOverflowtrue for wrap around at the upper/lower limit of the cvbdatatype_t range; false for truncation.
[in]Coefficientsdouble array with weight coefficients and an offset as the last element.
[out]ImageOutVariable 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);
}
cvbdim_t ImageDimension(IMG Image)
Gets the number of planes the Image contains.
Definition: PseudoCOMExports.cpp:363
void * IMG
CVB 2D image handle.
Definition: CVTypes.h:95
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.
Definition: ScanExports.cpp:1028
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]ImageInImage object handle of the source image.
[out]ImageMeanVariable to receive the handle of the mean image object.
[out]ImageStandardDeviationVariable 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]ImageInImage object handle of the source image.
[out]ImageMinVariable to receive the handle of the minimum image object.
[out]ImageMaxVariable 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]ImageInImage object handle of the source image.
[in]ModeNormalize_MinMax or Normalize_MeanVariance (standard deviation).
[in]TargetMeanMinEither target mean or min depending on Mode.
[in]TargetStandardDeviationMaxEither target standard deviation or max depending on Mode.
[out]ImageOutVariable 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]PixelListPixel list handle of object that contains the overlay coordinate information. F
[in]ImageInInput image handle of object providing the source pixel data.
[out]ImageOutVariable 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]ImageInImage handle of overlay capable image object to analyze.
[in]PixelListDimensionNumber of __Component__s for the PixelList to be created. Range is [2 .. 256].
[in]LeftLeft edge of the AOI in pixel coordinates.
[in]TopTop edge of the AOI in pixel coordinates.
[in]RightRight edge of the AOI in pixel coordinates (inclusive).
[in]BottomBottom edge of the AOI in pixel coordinates (inclusive).
[out]PixelListVariable 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);
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 spec...
Definition: TransformationExports.cpp:892
Note
Call ReleaseObject on ImageOut, when it is no longer needed.
Parameters
[in]ImageInImage object handle of the image to be transformed.
[in]CenterXPositive X coordinate of transformation center.
[in]CenterYPositive Y coordinate of transformation center.
[in]Alpha0Angle in degrees where to start the polar transformation.
[in]InnerRadiusInner radius in pixels for transformation.
[in]OuterRadiusOuter radius in pixels for transformation.
[out]ImageOutVariable 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]ImageInImage object handle of the image to be transformed.
[in]CenterXPositive X component of pixel coordinate of transformation center.
[in]CenterYPositive Y component of pixel coordinate of transformation center.
[in]Alpha0Angle in degrees where to start the polar transformation.
[in]AlphaTotalPositive, non-0 total radial angle in degrees.
[in]InnerRadiusInner radius in pixels for transformation.
[in]OuterRadiusOuter radius in pixels for transformation.
[out]ImageOutVariable 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]ImageInImage object handle of the source image.
[in]WidthWidth of the target image to be created.
[in]HeightHeight of the target image to be created.
[in]TransformationCallback for coordinate transformation.
[in]pPrivatePointer to user data, e.g. object pointer, passed in each call to Transformation.
[out]ImageOutVariable 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;
}
cvbdim_t ImageWidth(IMG Image)
Gets the width of the Image.
Definition: PseudoCOMExports.cpp:389
cvbdim_t ImageHeight(IMG Image)
Gets the height of the Image.
Definition: PseudoCOMExports.cpp:415
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.
Definition: TransformationExports.cpp:1057

◆ 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]ImageHandle of the image object to be searched in for local maxima.
[in]PlaneIndexPlane of source Image to search in.
[in]LeftLeft edge of the AOI in pixel coordinates.
[in]TopTop edge of the AOI in pixel coordinates.
[in]RightRight edge (inclusive) of the AOI in pixel coordinates.
[in]BottomBottom edge (inclusive) of the AOI in pixel coordinates.
[in]LocalityPositive minimum L1 distance in pixels between two neighboring maxima.
[in]ThresholdMinimum gray value for a local maximum to be considered.
[out]MaximaListVariable 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);
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.
Definition: PixelListExports.cpp:218
@ SP_None
No sub pixel calculation.
Definition: CVTypes.h:224
Parameters
[in]ImageHandle of the image object to be searched in for local maxima.
[in]PlaneIndexPlane of source Image to search in.
[in]LeftLeft edge of the AOI in pixel coordinates.
[in]TopTop edge of the AOI in pixel coordinates.
[in]RightRight edge (inclusive) of the AOI in pixel coordinates.
[in]BottomBottom edge (inclusive) of the AOI in pixel coordinates.
[in]LocalityPositive minimum L1 distance in pixels between two neighboring maxima.
[in]ThresholdMinimum 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]MaximaListVariable 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]ImageHandle of the image object to be searched in for local maxima.
[in]PlaneIndexPlane of source Image to search in.
[in]LeftLeft edge of the AOI in pixel coordinates.
[in]TopTop edge of the AOI in pixel coordinates.
[in]RightRight edge (inclusive) of the AOI in pixel coordinates.
[in]BottomBottom edge (inclusive) of the AOI in pixel coordinates.
[in]LocalityPositive minimum L1 distance in pixels between two neighboring maxima.
[in]ThresholdMinimum 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]SubPixelModeModel/mode with which to determine the sub pixel accurate position of the local maxima.
[in]RadiusDefines 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]MaximaListVariable 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]ImageImage object handle of the source image.
[in]PlaneIndexImage plane index for which the histogram is to be calculated.
[in]DensityProcessing density from 1 to 1000, where 1000 means all pixels (100%).
[in]AreaArea of interest in image coordinates for which the histogram is calculated.
[out]HistogramArray 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]ImageInImage object handle containing the data to be transformed.
[in]Alpha0Start angle in degrees for ImageOut.
[in]CenterXPositive X component of pixel coordinate of transformation center.
[in]CenterYPositive Y component of pixel coordinate of transformation center.
[in]InnerRadiusInner radius in pixels for ImageOut.
[in]ImageOutImage 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]Image1Image object handle of the first image.
[in]Image2Image object handle of the second image.
[in]AreaArea of interest to be scanned.
[in]DensityProcessing density from 1 to 1000, where 1000 means all pixels (100%).
[in]ShiftXHorizontal shift in pixels between the two source images.
[in]ShiftYVertical shift in pixels between the two source images
[in]UseCStrue, if the coordinate system is used and the Area should be transformed; false otherwise.
[in]FPixelOptional callback to process each pixel that lies within the Area and matches the selected Density.
[in]FStartLineOptional callback to signal each beginning of a new line.
[in]FEndLineOptional callback to signal each end of a line.
[in]pPrivatePointer 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]ImageImage object handle of the source image.
[in]AreaArea of interest to be scanned.
[in]DensityProcessing density from 1 to 1000, where 1000 means all pixels (100%).
[in]UseCStrue, if the coordinate system is used and the Area should be transformed; false otherwise.
[in]FPixelOptional callback to process each pixel that lies within the Area and matches the selected Density.
[in]FStartLineOptional callback to signal each beginning of a new line.
[in]FEndLineOptional callback to signal each end of a line.
[in]pPrivatePointer 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";
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;
}
cvbbool_t SetPixVal(IMG Image, cvbval_t PlaneIndex, cvbval_t X, cvbval_t Y, cvbval_t &Value)
Sets the Value of a pixel of the given Image in the plane specified by PlaneIndex at a specified posi...
Definition: ImageAccessExports.cpp:211
cvbbool_t CreateGenericImageDT(cvbval_t NumPlanes, cvbval_t Width, cvbval_t Height, cvbdatatype_t Dataype, IMG &ImageOut)
Creates a new and uninitialized planar image with selectable Datatype.
Definition: ImageHandlingExports.cpp:2102
cvbbool_t InitializeImageAreaEx(IMG Image, cvbval_t PlaneIndex, TArea Area, double Value)
Initialize the pixels in the given Area to a given Value.
Definition: ScanExports.cpp:672
cvbbool_t MaxImageArea(IMG Image, TArea &Area)
Sets the Area to the full extent of the Image.
Definition: PseudoCOMExports.cpp:249
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.
Definition: ScanExports.cpp:2000
cvbbool_t ReleaseObject(OBJ &Object)
Decrements the reference count of the given InterfaceContainer Object.
Definition: ImageHandlingExports.cpp:675
Describes an area of interest that is using three points (P0, P1 and P2).
Definition: CVTypes.h:170
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]Image1Image object handle of the first image.
[in]Image2Image object handle of the second image.
[in]PlaneIndex1Index of Image1 object's plane.
[in]PlaneIndex2Index of Image2 object's plane.
[in]AreaArea of interest to be scanned.
[in]DensityProcessing density from 1 to 1000, where 1000 means all pixels (100%).
[in]ShiftXHorizontal shift in pixels between the two source images.
[in]ShiftYVertical shift in pixels between the two source images
[in]UseCStrue, if the coordinate system is used and the Area should be transformed; false otherwise.
[in]FPixelOptional callback to process each pixel that lies within the Area and matches the selected Density.
[in]FStartLineOptional callback to signal each beginning of a new line.
[in]FEndLineOptional callback to signal each end of a line.
[in]pPrivatePointer 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]ImageImage object handle of the source image.
[in]PlaneIndexIndex of plane to be scanned.
[in]AreaArea of interest to be scanned.
[in]DensityProcessing density from 1 to 1000, where 1000 means all pixels (100%).
[in]UseCStrue, if the coordinate system is used and the Area should be transformed; false otherwise.
[in]FPixelOptional callback to process each pixel that lies within the Area and matches the selected Density.
[in]FStartLineOptional callback to signal each beginning of a new line.
[in]FEndLineOptional callback to signal each end of a line.
[in]pPrivatePointer 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