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

• normal image, owning its image data
• mapped image, being only a view on another image or memory buffer
• driver image, viewing the latest acquired buffer (e.g. via Driver Library's G2Wait)

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]	Image	Image object handle to get the coordinate system from.
[out]	CS	Variable 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]	Image	Image object handle to get plane of.
[in]	PlaneIndex	Plane index for which to get the pixel access data.
[out]	ppBase	Address of the variable to receive the base pointer for the PVPAT offset table.
[out]	ppVPAT	Address 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;
}

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)
{
  cvbdatatype_t dt = IsAllSameDatatype(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;
}

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]	Image	Image object handle to get plane of.
[in]	PlaneIndex	Identifies 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]

Image

Image 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]

Image

Image 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]

Image

Image 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]	Image	Image object handle to set the CS to.
[in]	CS	New coordinate system to be set.

Returns

true if successful; false if e.g. Image is not valid.