Image Manager (CVCImg.dll) 15.0
IImageVPA Interface

CVB 2D image using the VPAT. More...

Functions

cvbbool_t GetImageCoordinates (IMG Image, TCoordinateMap &CS)
 Gets the coordinate system of an Image. More...
 
cvbbool_t GetImageVPA (IMG Image, cvbval_t PlaneIndex, void **ppBase, PVPAT *ppVPAT)
 Gets the PVPAT and its base pointer to access the image data. More...
 
cvbdatatype_t ImageDatatype (IMG Image, cvbval_t PlaneIndex)
 Gets the cvbdatatype_t of the given Image PlaneIndex. More...
 
cvbdim_t ImageDimension (IMG Image)
 Gets the number of planes the Image contains. More...
 
cvbdim_t ImageHeight (IMG Image)
 Gets the height of the Image. More...
 
cvbdim_t ImageWidth (IMG Image)
 Gets the width of the Image. More...
 
cvbbool_t SetImageCoordinates (IMG Image, TCoordinateMap CS)
 Sets the given coordinate system CS to the given Image. More...
 

Detailed Description

CVB 2D image using the VPAT.

A CVB image can either be a

The presence of this interface is mostly signaled via the IMG handle type (see OBJ on how IDisposableType relates to the handles).

Each image has a Width and Height (in pixels), a CoordinateSystem (as TCoordinateMap) and a number of planes (at least one). The number of planes can be read out by calling the ImageDimension function.

A CVB plane is, in short, one component of pixel. E.g. for a monochrome image, there is just one dimension: the intensity or gray value. If you have an RGB image, the dimension is three: red, green, and blue.

Every plane has its own VPAT to locate the pixels in memory and cvbdatatype_t describing the data type of the pixel component.

Note
The plane order is logical and not related to the pixel buffer layout! Thus a BGR memory layout still has its first plane being red, the second green and the third blue.
As described in the class diagram above, any single image has one Width, Height and CoordinateSystem. Each plane, though, can have its own cvbdatatype_t and VPAT. Thus you can combine even different memory buffers into a single image (see CreateConcatenatedImage) to package related information. This can e.g. be 2½D, 16 bits per pixel data and its byte confidence map.
The IImageVPA itself does not define the component's role and most algorithms working on a plane treat it as monochrome intensity data. Thus you could still do OCR on a 2½D image of embossed letters. You can use the ImageColorModel function to determine how CVB interprets the planes.

Function Documentation

◆ GetImageCoordinates()

cvbbool_t GetImageCoordinates ( IMG  Image,
TCoordinateMap CS 
)
related

Gets the coordinate system of an Image.

Parameters
[in]ImageImage object handle to get the coordinate system from.
[out]CSVariable to which the coordinate system is set.
Returns
true if successful; false if e.g. Image is not valid.

◆ GetImageVPA()

cvbbool_t GetImageVPA ( IMG  Image,
cvbval_t  PlaneIndex,
void **  ppBase,
PVPAT ppVPAT 
)

Gets the PVPAT and its base pointer to access the image data.

For more information on how to handle image pixel data access see the VPAT documentation.

Note
If possible prefer the GetLinearAccess function from the CVCUtilities.dll. See the UtilitiesLibraryReference for additional information.
Attention

The returned PVPAT is the VPAT stored in the Image handle's IImageVPA object. Thus changes to the VPAEntry elements should only be made with the greatest caution as this is the central access point for functions using IMG handles.
Parameters
[in]ImageImage object handle to get plane of.
[in]PlaneIndexPlane index for which to get the pixel access data.
[out]ppBaseAddress of the variable to receive the base pointer for the PVPAT offset table.
[out]ppVPATAddress of the variable to receive the VPAT.
Returns
true if successful; false otherwise.
Examples
A static 8bpp image access based on the description in VPAT :
cvbbool_t InvertImage(IMG Image)
{
assert(IsAllSameDatatype(Image) == 8); // all planes must be bytes
cvbdim_t numPlanes = ImageDimension(Image); // 0 on error
cvbdim_t width = ImageWidth(Image), height = ImageHeight(Image);
for(cvbdim_t plane = 0; plane < numPlanes; ++plane)
{
intptr_t baseAddress = 0;
PVPAT vpat = nullptr;
if(!GetImageVPA(Image, plane, reinterpret_cast<void**>(&baseAddress), &vpat))
return false; // just precaution: this always works on valid images
for(cvbdim_t y = 0; y < height; ++y)
{
intptr_t lineAddress = baseAddress + vpat[y].YEntry;
for(cvbdim_t x = 0; x < width; ++x)
{
cvbuint8_t *pPixel = reinterpret_cast<cvbuint8_t *>(lineAddress + vpat[x].XEntry);
*pPixel = 255 - *pPixel;
}
}
}
return numPlanes > 0;
}
cvbdim_t ImageDimension(IMG Image)
Gets the number of planes the Image contains.
Definition: PseudoCOMExports.cpp:361
cvbbool_t GetImageVPA(IMG Image, cvbval_t PlaneIndex, void **ppBase, PVPAT *ppVPAT)
Gets the PVPAT and its base pointer to access the image data.
Definition: PseudoCOMExports.cpp:787
cvbdim_t ImageWidth(IMG Image)
Gets the width of the Image.
Definition: PseudoCOMExports.cpp:387
cvbdim_t ImageHeight(IMG Image)
Gets the height of the Image.
Definition: PseudoCOMExports.cpp:413
void * IMG
CVB 2D image handle.
Definition: CVTypes.h:95
cvbdatatype_t IsAllSameDatatype(IMG Image)
Checks if all the planes in the Image have identical data types and returns the cvbdatatype_t if it i...
Definition: PseudoCOMExports.cpp:554
Individual entry in the IImageVPA object's PVPAT.
Definition: CVTypes.h:119
intptr_t YEntry
Memory y-offset in bytes (lines).
Definition: CVTypes.h:121
intptr_t XEntry
Memory x-offset in bytes (columns).
Definition: CVTypes.h:120
Generic implementation using templates to apply inversion for different pixel component types (we use the DatatypeMatches<ConcreteType> function from the example in cvbdatatype_t):
// if Windef.h is included (e.g. via Windows.h) you should define NOMINMAX
// either before the include or in your project settings (except you need the
// min or max macros...
// Alternatively use:
// #ifdef max
// # undef max
// #endif // max
template <typename ConcreteType>
cvbbool_t InvertImage(IMG Image)
{
if(!DatatypeMatches<ConcreteType>(dt))
return false; // tparam and image data type mismatch or error
cvbdim_t numPlanes = ImageDimension(Image);
cvbdim_t width = ImageWidth(Image), height = ImageHeight(Image);
for(cvbdim_t plane = 0; plane < numPlanes; ++plane)
{
intptr_t baseAddress = 0;
PVPAT vpat = nullptr;
if(!GetImageVPA(Image, plane, reinterpret_cast<void**>(&baseAddress), &vpat))
return false; // just precaution: this always works on valid images
for(cvbdim_t y = 0; y < height; ++y)
{
intptr_t lineAddress = baseAddress + vpat[y].YEntry;
for(cvbdim_t x = 0; x < width; ++x)
{
ConcreteType *pPixel = reinterpret_cast<ConcreteType *>(lineAddress + vpat[x].XEntry);
*pPixel = std::numeric_limits<ConcreteType>::max()
- (*pPixel - std::numeric_limits<ConcreteType>::lowest());
}
}
}
return true;
}
long cvbdatatype_t
Numeric data type of a single IImageVPA plane.
Definition: CVTypes.h:24
You can call it like this
// Mono8 image
InvertImage<cvbuint8_t>(mono8Image);
// Float image
InvertImage<float>(floatImage);

◆ ImageDatatype()

cvbdatatype_t ImageDatatype ( IMG  Image,
cvbval_t  PlaneIndex 
)

Gets the cvbdatatype_t of the given Image PlaneIndex.

Parameters
[in]ImageImage object handle to get plane of.
[in]PlaneIndexIdentifies the plane to get the data type of.
Valid range is [0..ImageDimension(IMG Image)[ (exclusive).
Returns
Data type of the given Image PlaneIndex; -1 or 0 on error.

◆ ImageDimension()

cvbdim_t ImageDimension ( IMG  Image)

Gets the number of planes the Image contains.

Parameters
[in]ImageImage object handle to get the number of planes of.
Returns
Number of planes in Image; 0 on error.

◆ ImageHeight()

cvbdim_t ImageHeight ( IMG  Image)

Gets the height of the Image.

Parameters
[in]ImageImage object handle to get the height for.
Returns
Height of the Image; 0 on error.

◆ ImageWidth()

cvbdim_t ImageWidth ( IMG  Image)

Gets the width of the Image.

Parameters
[in]ImageImage object handle to get the width of.
Returns
Width in pixels of the Image; 0 on error.

◆ SetImageCoordinates()

cvbbool_t SetImageCoordinates ( IMG  Image,
TCoordinateMap  CS 
)
related

Sets the given coordinate system CS to the given Image.

Parameters
[in]ImageImage object handle to set the CS to.
[in]CSNew coordinate system to be set.
Returns
true if successful; false if e.g. Image is not valid.