Image Handling

Functions to create, copy and access basic properties of IImageVPA IMG handles. More...

Modules
	IImageVPA Interface
	CVB 2D image using the VPAT.
	VPAT
	Virtual Pixel Access Table.

Typedefs
typedef long	cvbdatatype_t
	Numeric data type of a single IImageVPA plane. More...
typedef void *	IMG
	CVB 2D image handle. More...
typedef void(*	PFFINALRELEASE) (void *pBufferBase, void *pPrivate)
	Release callback for images created with CreateImageFromPointer. More...

Enumerations
enum	TColorModel {   CM_Guess_RGB = -2 , CM_Guess_Mono = -1 , CM_Unknown = 0 , CM_Mono = 1 ,   CM_RGB = 2 , CM_YUV = 3 , CM_HSI = 4 , CM_YCbCr = 5 ,   CM_LUV = 6 , CM_Lab = 7 , CM_HLS = 8 , CM_YCC = 9 ,   CM_HSV = 10 , CM_XYZ = 11 }
	Color model descriptors. More...
enum	TDatatype { DT_Signed = 0x100 , DT_Float = 0x200 , DT_Overlay = 0x400 , DT_ComplexPacked = 0x800 }
	cvbdatatype_t flags. More...
enum	TDisplayScaleMode { DSM_Global = 0 , DSM_ViewPort = 1 , DSM_WrapAround = 2 }
	Defines modes for treating high bit images (> 8bpp) when displaying them on an 8 bit display. More...
enum	TPanoramaMode { PM_Horizontal = 0 , PM_Vertical = 1 }
	Defines how input images are stitched together. More...
enum	TRawFileLayout { RFL_Interleaved = 1 , RFL_Planar = 2 }
	Pixel layout for images serialized with ImageToMemoryRaw. More...
enum	TVPATRotation {   VPATROT_Unknown = -1 , VPATROT_0 = 0 , VPATROT_90 = 1 , VPATROT_180 = 2 ,   VPATROT_270 = 3 }
	Defines possible right angle VPAT rotations. VPATROT_90 or higher can be used in the CreateRotatedImageMap function. More...

Functions
cvbval_t	BitsPerPixel (cvbdatatype_t Datatype)
	Gets how many bits per pixel (component) are valid based on the Datatype descriptor. More...
cvbval_t	BytesPerPixel (cvbdatatype_t Datatype)
	Gets how many bytes per pixel (component) are occupied in memory based on the Datatype descriptor. More...
cvbbool_t	CopyImageArea (IMG ImageIn, IMG ImageOut, cvbval_t ImageInPlaneIndex, cvbval_t ImageOutPlaneIndex, TArea Area, cvbval_t ShiftX, cvbval_t ShiftY)
	Copy function for TArea regions of interest. More...
cvbbool_t	CopyImageClipboard (IMG Image, HWND hWnd)
	Copies an image to the system clipboard. More...
cvbbool_t	CopyImageRect (IMG ImageIn, IMG ImageOut, cvbdim_t ImageInPlaneIndex, cvbdim_t ImageOutPlaneIndex, cvbdim_t InLeft, cvbdim_t InTop, cvbdim_t InRight, cvbdim_t InBottom, cvbdim_t OutX, cvbdim_t OutY)
	Quick copy function for rectangular regions of interest. More...
cvbbool_t	CopyImageRectPlanes (IMG ImageIn, IMG ImageOut, cvbdim_t InLeft, cvbdim_t InTop, cvbdim_t InRight, cvbdim_t InBottom, cvbdim_t OutX, cvbdim_t OutY)
	Quick copy function for a rectangular region of interest, operating on several planes simultaneously. Therefore suited for e.g. RGB images. More...
cvbbool_t	CopyOverlay (IMG ImageIn, IMG ImageOut)
	Copies the overlay bits from the ImageIn to the ImageOut. More...
cvbbool_t	CreateAreaSubImage (IMG ImageIn, TArea Area, IMG &ImageOut)
	Creates a linear interpolated copy of the Area of the given ImageIn. More...
cvbbool_t	CreateCompatibleImage (IMG ImageIn, cvbval_t OutWidth, cvbval_t OutHeight, cvbbool_t ForceOverlayBit, IMG &ImageOut)
	Creates a new image of the same data type and number of planes, but with the given OutWidth and OutHeight. More...
cvbbool_t	CreateConcatenatedImage (IMG *ImageArray, size_t ArrayLength, cvbbool_t ShareMemory, IMG &ImageOut)
	Concatenates an array of images into a single new one. More...
cvbbool_t	CreateDuplicateImage (IMG ImageIn, IMG &ImageOut)
	Creates a new image which is a copy from ImageIn. More...
cvbbool_t	CreateDuplicateImageEx (IMG ImageIn, IMG &ImageOut)
	Creates a new quick copied image from the given ImageIn. More...
cvbbool_t	CreateGenericImage (cvbval_t NumPlanes, cvbval_t Width, cvbval_t Height, cvbbool_t HasOverlay, IMG &ImageOut)
	Creates a new and uninitialized interleaved image with 8 bits per plane. More...
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. More...
cvbbool_t	CreateImageDeleteList (IMG ImageIn, cvbval_t PlaneIndex, cvbval_t NumPlanes, cvbbool_t MapImage, IMG &ImageOut)
	Creates a new image that contains a plane-subset of the ImageIn by omitting planes. More...
cvbres_t	CreateImageFromPointer (void *pImageMemory, size_t MemorySize, cvbdim_t Width, cvbdim_t Height, cvbdim_t NumPlanes, cvbdatatype_t DataType, intptr_t PitchX, intptr_t PitchY, intptr_t PitchPlane, const cvbval_t PlaneOrder[], PFFINALRELEASE ReleaseCallback, void *pPrivate, IMG &ImageOut)
	Creates an image object around a block of memory without copying the data. More...
cvbbool_t	CreateImageInsertList (IMG Image1, IMG Image2, cvbval_t Image1InsertionIndex, cvbbool_t MapImage, cvbbool_t Intersect, IMG &ImageOut)
	Creates a new image where the planes of Image2 are inserted into Image1 starting at Image1InsertionIndex. More...
cvbbool_t	CreateImageMap (IMG ImageIn, cvbval_t InLeft, cvbval_t InTop, cvbval_t InRight, cvbval_t InBottom, cvbval_t OutWidth, cvbval_t OutHeight, IMG &ImageOut)
	Creates a new mapped image object based on the rectangular area of interest and scales it to a destination size. More...
cvbbool_t	CreateImageSubList (IMG ImageIn, cvbval_t PlaneIndex, cvbval_t NumPlanes, cvbbool_t MapImage, IMG &ImageOut)
	Creates a new image that contains a plane-subset of the ImageIn by including only selected planes. More...
cvbbool_t	CreateNonOverlayImage (IMG ImageIn, IMG &ImageOut)
	Creates a new non-overlay image which is copy of the overlay capable ImageIn. More...
cvbbool_t	CreateOverlayImage (IMG ImageIn, IMG &ImageOut)
	Creates a new overlay image which is a copy of an ImageIn. More...
cvbbool_t	CreatePanoramicImageMap (IMG ImageA, IMG ImageB, TPanoramaMode PanoramaMode, IMG &ImageOut)
	Merges the two input images ImageA, ImageB into one ImageOut without copying the pixel data. More...
cvbbool_t	CreateRotatedImageMap (IMG ImageIn, TVPATRotation Rotation, IMG &ImageOut)
	Rotates the ImageIn in right angle (90°) steps via VPAT. More...
cvbbool_t	CreateSubImage (IMG ImageIn, TArea Area, IMG &ImageOut)
	Creates a linear interpolated copy of the Area of the given ImageIn. More...
cvbbool_t	GetDatatypeMinMaxVal (cvbdatatype_t Datatype, cvbval_t &MinVal, cvbval_t &MaxVal)
	Returns the minimum and maximum value for a pixel component based on its Datatype. More...
cvbbool_t	CVB::GetPixel (IMG Image, cvbval_t PlaneIndex, cvbval_t X, cvbval_t Y, cvbval_t &Value)
	Alias for CVB::GetPixVal. More...
cvbbool_t	CVB::GetPixVal (IMG Image, cvbval_t PlaneIndex, cvbval_t X, cvbval_t Y, cvbval_t &Value)
	Gets the Value of a pixel of the given Image in the plane specified by PlaneIndex at the location X, Y. More...
cvbbool_t	HasOverlay (IMG Image)
	Checks if any plane of the given Image has DT_Overlay set in its datatype. More...
TColorModel	ImageColorModel (IMG Image)
	Returns the color model descriptor for the Image. More...
void	ImageToDC (IMG ImageIn, HDC hDC, cvbval_t hDCLeft, cvbval_t hDCTop, cvbval_t InLeft, cvbval_t InTop, cvbval_t InRight, cvbval_t InBottom, cvbval_t hDCWidth, cvbval_t hDCHeight, cvbval_t RedPlaneIndex, cvbval_t GreenPlaneIndex, cvbval_t BluePlaneIndex, double Gain, cvbval_t Offset)
	Blits the ImageIn into a standard Windows DeviceContext with DSM_WrapAround mode. More...
void	ImageToDCEx (IMG ImageIn, HDC hDC, cvbval_t hDCLeft, cvbval_t hDCTop, cvbval_t InLeft, cvbval_t InTop, cvbval_t InRight, cvbval_t InBottom, cvbval_t hDCWidth, cvbval_t hDCHeight, cvbval_t RedPlaneIndex, cvbval_t GreenPlaneIndex, cvbval_t BluePlaneIndex, double Gain, cvbval_t Offset, TDisplayScaleMode Mode)
	Blits the ImageIn into a standard Windows DeviceContext with user-definable handling of bit depths > 8. More...
cvbbool_t	ImageToMemory (IMG Image, void *pMem, intptr_t Capacity)
	Serializes the Image object into a buffer. More...
cvbbool_t	ImageToMemoryRaw (IMG Image, void *pMem, intptr_t Capacity, TRawFileLayout Layout)
	Write the raw pixel data of an image into a buffer. More...
intptr_t	ImageToMemoryRawSize (IMG Image)
	Determine the amount of memory needed for ImageToMemoryRaw. More...
intptr_t	ImageToMemorySize (IMG Image)
	Determine the amount of memory needed for ImageToMemory. More...
cvbbool_t	InitializeImageArea (IMG Image, cvbval_t PlaneIndex, TArea Area, cvbval_t Value)
	Initialize the pixels in the given Area to a given Value. More...
cvbbool_t	InitializeImageAreaEx (IMG Image, cvbval_t PlaneIndex, TArea Area, double Value)
	Initialize the pixels in the given Area to a given Value. More...
cvbbool_t	IsAll8Bit (IMG Image)
	Checks if all the planes in the Image have 8 bits per pixel. More...
cvbdatatype_t	IsAllSameDatatype (IMG Image)
	Checks if all the planes in the Image have identical data types and returns the cvbdatatype_t if it is so. More...
cvbbool_t	IsFloatDatatype (cvbdatatype_t Datatype)
	Checks if the Datatype describes a floating point number. More...
cvbbool_t	IsOverlayImage (IMG Image)
cvbbool_t	IsSignedDatatype (cvbdatatype_t Datatype)
	Checks if the Datatype describes a signed data type. More...
cvbbool_t	LoadImageFile (const char *FileName, IMG &ImageOut)
	Loads an image from a file (ASCII strings). More...
cvbbool_t	LoadImageFileW (const wchar_t *FileName, IMG &ImageOut)
	Loads an image from a file (Unicode strings). More...
cvbbool_t	MapTo8Bit (IMG ImageIn, cvbbool_t OverallNormalization, IMG &ImageOut)
	Creates a new 8-bit per plane image from ImageIn. More...
cvbbool_t	MaxImageArea (IMG Image, TArea &Area)
	Sets the Area to the full extent of the Image. More...
cvbbool_t	MemoryToImage (void *pMem, intptr_t Capacity, IMG &ImageOut)
	Restores an image object from memory that has been serialized using the function ImageToMemory. More...
cvbval_t	NumPlanesNeededPerImage (TColorModel ColorModel)
	Returns the number of planes which an image should have with the given ColorModel. More...
cvbbool_t	PasteClipboardImage (HWND hWnd, IMG &ImageOut)
	Creates an image object from a compatible image stored in the system clipboard. More...
cvbval_t	PixVal (IMG Image, cvbdim_t PlaneIndex, cvbdim_t X, cvbdim_t Y)
	Gets the pixel value of the given Image in the plane specified by PlaneIndex at the location X, Y. More...
cvbbool_t	CVB::SetPixel (IMG img, cvbval_t index, cvbval_t x, cvbval_t y, cvbval_t &value)
	Alias for CVB::SetPixVal. More...
cvbbool_t	CVB::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 position X, Y. More...
cvbbool_t	WriteImageFile (IMG Image, const char *FileName)
	Saves the Image to a file using the given FileName (ASCII strings). More...
cvbbool_t	WriteImageFileW (IMG Image, const wchar_t *FileName)
	Saves the Image to a file using the given FileName (Unicode strings). More...
cvbbool_t	WriteLossyImageFile (IMG Image, double Quality, const char *FileName)
	Saves an image under the given FileName using a lossy compression codec (ASCII strings). More...
cvbbool_t	WriteLossyImageFileW (IMG Image, double Quality, const wchar_t *FileName)
	Saves an image under the given FileName using a lossy compression codec (Unicode strings). More...

Detailed Description

Functions to create, copy and access basic properties of IImageVPA IMG handles.

Typedef Documentation

cvbdatatype_t

cvbdatatype_t

Numeric data type of a single IImageVPA plane.

The datatype, which is returned by ImageDatatype, is a bit field:

31-12	11	10	9	8	7-0
reserved	C	O	F	S	bits per pixel

The bits 8 to 11 are declared as readable enum values in TDatatype:

• DT_Signed (bit 8): signed number
• DT_Float (bit 9): floating point number
• DT_Overlay (bit 10): overlay bit used
• DT_ComplexPacked (bit 11): complex number used by Foundation package FFT functions

The Reserved field is always 0 and bits per pixel is interpreted as a byte encoding the data type's bit depth.

Examples

• byte: dt = 8
• uint16_t: dt = 16
• int16_t: dt = #DT_Signed | 16 // = 272
• float32_t: dt = #DT_Float | #DT_Signed | 32 // = 800

Attention

It is easy to create invalid datatypes like DT_Signed | 1. Also for floating point numbers two representations exist:

• float: DT_Float | DT_Signed | 32
• float: DT_Float | 32
• double: DT_Float | DT_Signed | 64
• double: DT_Float | 64

(both DT_Float | DT_Signed and DT_Float denote the same datatype which is always signed – the fully qualified variant is safer)

Functions on cvbdatatype_t

(Note that these are not member functions.)

---

cvbval_t BitsPerPixel(cvbdatatype_t Datatype)

---

cvbval_t BytesPerPixel(cvbdatatype_t Datatype)

---

cvbbool_t GetDatatypeMinMaxVal(cvbdatatype_t Datatype, cvbval_t &MinVal, cvbval_t &MaxVal)

---

cvbbool_t IsFloatDatatype(cvbdatatype_t Datatype)

---

cvbbool_t IsSignedDatatype(cvbdatatype_t Datatype)

---

Related Functions

(Note that these are not member functions.)

---

cvbbool_t CreateGenericImageDT(cvbval_t NumPlanes, cvbdim_t Width, cvbdim_t Height, cvbdatatype_t Datatype, IMG &Image)

---

cvbres_t CreateImageFromPointer(void *pImageMem, size_t MemSize, cvbdim_t Width, cvbdim_t Height, cvbdim_t NumPlanes, cvbdatatype_t DataType, intptr_t PitchX, intptr_t PitchY, intptr_t PitchPlane, cvbval_t PlaneOrder[], PFFINALRELEASE ReleaseCallback, void *pUserData, IMG &ImageOut)

---

cvbbool_t HasOverlay(IMG Image)

---

cvbdatatype_t ImageDatatype(IMG Image, cvbdim_t PlaneIndex)

---

cvbbool_t IsAll8Bit(IMG Image)

---

cvbdatatype_t IsAllSameDatatype(IMG Image)

---

cvbbool_t MapTo8Bit(IMG ImageIn, cvbbool_t UseSingleGain, IMG &ImageOut)

---

Example

Check if CVB's cvbdatatype_t matches a plain old datatype:

// needs #include <limits>
 
template <typename ConcreteType>
cvbbool_t DatatypeMatches(cvbdatatype_t dt)
{
  typedef std::numeric_limits<ConcreteType> DTLimits;
 
  if(dt <= 0 || (dt & 0xFFFFF800))
    return false; // invalid, complex packed or unknown flag set
 
  if(BytesPerPixel(dt) != sizeof(ConcreteType))
    return false;
 
  if(typename DTLimits::is_integer)
  {
    if(dt & DT_Float)
      return false;
    if(typename DTLimits::is_signed && !(dt & DT_Signed))
      return false;
  }
  else if(typename DTLimits::is_iec559)
  {
    if(!(dt & DT_Float))
      return false;
    // signed flag is optional as this is implied by IEC 559/IEEE 754 floats
  }
 
  return true;
}

You can call it like this:

DatatypeMatches<cvbuint8_t>( 8 ); // => true
DatatypeMatches<float>( 32 | DT_Float ); // => true
DatatypeMatches<float>( 32 | DT_Float | DT_Signed ); // => true
DatatypeMatches<cvbuint16_t>( 10 ); // => true
 
DatatypeMatches<cvbuint8_t>( 10 ); // => false
DatatypeMatches<cvbuint32_t>( 32 | DT_Float ); // => false

IMG

IMG

CVB 2D image handle.

The IMG is a reference counted OBJ handle. IMG objects provide at least the IImageVPA interface.

Basic Factory Functions

---

cvbbool_t CreateGenericImage(cvbdim_t Dimension, cvbdim_t Width, cvbdim_t Height, cvbbool_t HasOverlayBit, IMG &Image)

---

cvbbool_t CreateGenericImageDT(cvbdim_t Dimension, cvbdim_t Width, cvbdim_t Height, cvbdatatype_t Datatype, IMG &Image)

---

cvbbool_t LoadImageFile(const char *FileName, IMG &Image)

---

cvbbool_t LoadImageFileW(const wchar_t *FileName, IMG &Image)

---

This handle type is ubiquitous throughout Common Vision Blox. Both pure images and fully fledged camera devices (loaded Vin-Driver via LoadImageFile) are an IMG. Many other functions work on images or create new ones. But to put it more in perspective: most OBJ objects you use, have an IImageVPA interface and thus can be used as an image.

Note

For driver IMG objects and, new in CVB 2017 (13.00.000), non-streaming devices (devices which do not provide an image or other buffer), see the DriverDLLReference.

Example

A simple C command line application you can use to convert between different image formats. File format is detected by the file's extension.

#include <stdio.h>
#include <iCVCImg.h>
 
void PrintUsage();
 
enum
{
  ok,
  invalid_param,
  io_error
};
 
int main(int argc, char *args[])
{
  if(argc == 2 && strcmp(args[1], "--help") == 0)
  {
    PrintUsage();
    return ok;
  }
  if(argc != 3)
  {
    printf("Invalid number of arguments!\n\n");
 
    PrintUsage();
    return invalid_param;
  }
 
  IMG hInputImage = nullptr;
  if(!LoadImageFile(args[1], hInputImage))
  {
    printf("Error loading '%s'!\n\n", args[1]);
    return io_error;
  }
 
  cvbbool_t writeSuccessful = WriteImageFile(hInputImage, args[2]);
  ReleaseObject(hInputImage);
 
  if(writeSuccessful)
  {
    printf("Successfully converted\n'%s'\n->\n'%s'\n\n", args[1], args[2]);
    return ok;
  }
  else
  {
    printf("Error converting\n'%s'\n->\n'%s'\n\n", args[1], args[2]);
    return io_error;
  }
}
 
static void PrintUsage()
{
  printf(
    "converter <src> <tgt>\n\n"
    "Converts the given <src> file into the given <tgt> file. Target format is\n"
    "deduced by <tgt>'s extension\n\n"
    "<src>   Full or relative path to image file to read\n"
    "<tgt>   Full or relative path to image file to write\n\n"
    "Use --help to show this page\n\n"
  );
}

PFFINALRELEASE

void(* PFFINALRELEASE)(void *pBufferBase, void *pPrivate)

Release callback for images created with CreateImageFromPointer.

In this callback, the implementer can take the necessary steps to e.g. clean up memory or other resources allocated for a CreateImageFromPointer call.

Parameters

[in]	pBufferBase	Base pointer of the buffer provided to the function CreateImageFromPointer.
[in]	pPrivate	Private data pointer to given to the function CreateImageFromPointer.

Enumeration Type Documentation

TColorModel

enum TColorModel

Color model descriptors.

These descriptors are returned by the ImageColorModel function.

Note

Not all images carry a color model descriptor. E.g. images loaded via LoadImageFile come without a descriptor. For these CVB's default interpretation is returned:

• CM_Guess_Mono
• CM_Guess_RGB
• CM_Unknown

See also

ImageColorModel

Enumerator
CM_Guess_RGB	3-plane image with no attached descriptor.
CM_Guess_Mono	1-plane image with no attached descriptor.
CM_Unknown	Image with no attached descriptor and not CM_Guess_RGB or CM_Guess_Mono.
CM_Mono	Only intensity information.
CM_RGB	RGB color model.
CM_YUV	YUV color model.
CM_HSI	HSI color model.
CM_YCbCr	YCbCr color model.
CM_LUV	CIE LUV color model.
CM_Lab	CIE Lab color model.
CM_HLS	HLS color model.
CM_YCC	YCC color model.
CM_HSV	HSV color model.
CM_XYZ	CIE XYZ color model.

TDatatype

enum TDatatype

cvbdatatype_t flags.

Enumerator
DT_Signed	Signed pixel component. Only relevant for integer types. DT_Float is always considered a signed data type (although often both flags are set for floating point numbers).
DT_Float	Floating point pixel component. This data type only applies to pixel components with 32 or 64 bits per pixel. Also often DT_Signed is set on these data types (although floating point numbers are implicitly signed).
DT_Overlay	Pixel component uses lowest bit as mask marker. If the lowest bit is set, the pixel is considered being masked. Masked pixels are displayed in a special color in the CVB displays. Many tools, like Minos for example, consider this bit to be a don't care mask. Note As this is a bit mask, this flag is only valid on integer images (DT_Float must not be set).
DT_ComplexPacked	Packed complex number pixel component. Makes use of the symmetries in the complex valued image that is the result of a real valued image's fourier transformation. Images with this data type can only be used with the FFT functions from the Foundation Package.

TDisplayScaleMode

enum TDisplayScaleMode

Defines modes for treating high bit images (> 8bpp) when displaying them on an 8 bit display.

Enumerator
DSM_Global	Scale the image globally to fit into the gray scale range [0 .. 255]. This can result in a darker overall impression of your images if your images do not make full use of the dynamic range available to the cvbdatatype_t they are using.
DSM_ViewPort	Scale only the currently visible gray values of the image to the range [0 .. 255]. This mode will make fine gray value differences in your images more obvious when you zoom in.
DSM_WrapAround	Instead of scaling pixel values > 255 to the range [0 .. 255] simply use the lowest 8 bits of each pixel for display. This mode was until CVB 11.01.000 the only available display mode for images with more than 8 bits per pixel (and for DirectDraw display this currently continues to be the only option). It is therefore also the default mode (for backward compatibility) that is assumed if nothing else is specified (e.g. when using the Display OCX or calling ImageToDC).

TPanoramaMode

enum TPanoramaMode

Defines how input images are stitched together.

See also

CreatePanoramicImageMap

Enumerator
PM_Horizontal	Stitches the input images in left to right order.
PM_Vertical	Stitches the input images in top to bottom order.

TRawFileLayout

enum TRawFileLayout

Pixel layout for images serialized with ImageToMemoryRaw.

Enumerator
RFL_Interleaved	The pixels in the raw file are interleaved. I.e. for a pixel with n planes, the n component values of coordinate (0,0) are saved, then the n component values of coordinate (1,0) and so on.
RFL_Planar	The pixels in the raw file are planar. The pixels in the raw file are saved plane by plane, starting with plane 0.

TVPATRotation

enum TVPATRotation

Defines possible right angle VPAT rotations. VPATROT_90 or higher can be used in the CreateRotatedImageMap function.

Enumerator
VPATROT_Unknown	Undefined or unknown rotation.
VPATROT_0	No rotation.
VPATROT_90	90° rotation.
VPATROT_180	180° rotation.
VPATROT_270	270° rotation.

Function Documentation

BitsPerPixel()

cvbval_t BitsPerPixel

(

cvbdatatype_t

Datatype

)

Gets how many bits per pixel (component) are valid based on the Datatype descriptor.

This simply executes the following:

cvbval_t BitsPerPixel(cvbdatatype_t Datatype)
{
  return Datatype & 0xFF;
}

Parameters

[in]

Datatype

Data type descriptor to extract the bits per pixel component from.

Returns

Number of bits valid in the pixel component.

See also

See BytesPerPixel to get the actual number of bytes occupied by the pixel component; ImageDatatype

BytesPerPixel()

cvbval_t BytesPerPixel

(

cvbdatatype_t

Datatype

)

Gets how many bytes per pixel (component) are occupied in memory based on the Datatype descriptor.

Parameters

[in]

Datatype

Data type descriptor to calculate the bytes per pixel component from.

Returns

Number of bytes that are occupied in memory by the Datatype.

See also

BitsPerPixel, ImageDatatype

CopyImageArea()

cvbbool_t CopyImageArea	(	IMG	ImageIn,
		IMG	ImageOut,
		cvbval_t	ImageInPlaneIndex,
		cvbval_t	ImageOutPlaneIndex,
		TArea	Area,
		cvbval_t	ShiftX,
		cvbval_t	ShiftY
	)

Copy function for TArea regions of interest.

Copies the pixels inside the TArea region of interest from the ImageIn ImageInPlaneIndex to the ImageOut ImageOutPlaneIndex offset by the point (ShiftX, ShiftY). If ShiftX and ShiftY are 0, the ImageOut pixel coordinates are the same as in ImageIn. Copy is done via the ScanPlaneBinary function.

If the input region of interest or the output region (partially) lies outside the boundaries of the respective images, the region will be silently cropped. Even if no image data could be copied due to this setup this function will return true.

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

Although this function uses a TArea it does not take the coordinate system of the ImageIn into account (see TCoordinateMap on coordinate systems). You can use ImageAreaToPixel to transform the image coordinates into pixel coordinates if necessary.

The cvbdatatype_t must be identical for accessed planes in ImageIn and ImageOut for this function to succeed.

Keep in mind, that areas of interest are inclusive (see TArea for more information).

Parameters

[in]	ImageIn	Image handle to copy from.
[in]	ImageOut	Image handle to copy to.
[in]	ImageInPlaneIndex	Plane of ImageIn to copy from.
[in]	ImageOutPlaneIndex	Plane of the ImageOut to copy to.
[in]	Area	Area of interest in pixel coordinates in the ImageIn.
[in]	ShiftX	X offset for pixel coordinates in ImageOut where to copy to.
[in]	ShiftY	Y offset for pixel coordinates in ImageOut where to copy to.

Returns

true if successful; false otherwise.

See also

CopyImageRect

CopyImageClipboard()

cvbbool_t CopyImageClipboard	(	IMG	Image,
		HWND	hWnd
	)

Copies an image to the system clipboard.

The input image will be placed into the clipboard as either a device independent bitmap (clipboard format "CF_DIB") or as a serialized MIO stream (custom clipboard format "cf_MIO"). Note that the latter is usually not readable/usable by any application except Common Vision Blox.

Whether DIB or MIO will be serialized depends on the image content:

• Images with more than 8 bits per pixel will always be placed into the clipboard as MIO streams (if you need to pass images with more than 8 bits per pixel through the clipboard in DIB format, please pass them through the function MapTo8Bit first).
• Images with a plane count other than 1 or 3 will always be placed into the clipboard as MIO streams.
• Images that make use of the Common Vision Blox overlay bit DT_Overlay will always be placed into the clipboard as MIO streams. Images with overlay bits can be recognized by the output of the function HasOverlay on the image's cvbdatatype_t.

All other images will be places into the clipboard as DIBs.

Attention

This function is only available on the Windows platform.

Parameters

[in]	Image	Image object handle of the image to be copied.
[in]	hWnd	Application window handle.

Returns

true if successful; false otherwise.

See also

PasteClipboardImage

CopyImageRect()

cvbbool_t CopyImageRect	(	IMG	ImageIn,
		IMG	ImageOut,
		cvbdim_t	ImageInPlaneIndex,
		cvbdim_t	ImageOutPlaneIndex,
		cvbdim_t	InLeft,
		cvbdim_t	InTop,
		cvbdim_t	InRight,
		cvbdim_t	InBottom,
		cvbdim_t	OutX,
		cvbdim_t	OutY
	)

Quick copy function for rectangular regions of interest.

Copies the pixels inside the rectangular region of interest (InLeft, InTop, InRight, InBottom) from the ImageIn ImageInPlaneIndex to the ImageOut ImageOutPlaneIndex starting at the point (OutX, OutY). Copying is optimized for various VPAT layouts, i.e. this function will choose the fastest available approach that suits the layout of the input and the output image. The following BytesPerPixel are supported: 1, 2, 4, and 8.

Therefore this function will often be faster than the similar CopyImageArea which always runs through the VPAT in the source and destination image even if a quicker memcopy would be possible. For this function to be able to copy faster only the pixel coordinate system and a rectangular region of interest is supported (image coordinate system is not being taken into account).

If the input region of interest or the output region (partially) lies outside the boundaries of the respective images, the region will be silently cropped. Even if no image data could be copied due to this setup this function will return true.

Note

The cvbdatatype_t must be identical for accessed planes in ImageIn and ImageOut for this function to succeed.

Keep in mind, that areas of interest are inclusive (see TDRect for more information).

The cvbdatatype_t must be identical for accessed planes in ImageIn and ImageOut for this function to succeed.

The speed advantage over CopyImageArea may be outweighed by the time consumed for the VPAT analysis of the input images if the region to be copied is very small or the image is not linear.

Attention

If ImageIn and ImageOut point to the same IImageVPA object, make sure that the source and destination areas respective planes do not overlap! The result is going to be undefined in this case and this function does not guard against this!

Parameters

[in]	ImageIn	Source image to copy from.
[in]	ImageOut	Destination image to copy to.
[in]	ImageInPlaneIndex	Plane from ImageIn to copy from.
[in]	ImageOutPlaneIndex	Plane in the ImageOut to copy to.
[in]	InLeft	Non-negative left edge of the region of interest.
[in]	InTop	Non-negative top edge of the region of interest.
[in]	InRight	Non-negative right edge of the region of interest (inclusive).
[in]	InBottom	Non-negative bottom edge of the region of interest (inclusive).
[in]	OutX	Non-negative x component in pixel coordinates of point where to copy the data to.
[in]	OutY	Non-negative y component in pixel coordinates of point where to copy the data to.

Returns

true on success; false otherwise.

See also

CopyImageRectPlanes, CopyImageArea, CreateDuplicateImageEx

CopyImageRectPlanes()

cvbbool_t CopyImageRectPlanes	(	IMG	ImageIn,
		IMG	ImageOut,
		cvbdim_t	InLeft,
		cvbdim_t	InTop,
		cvbdim_t	InRight,
		cvbdim_t	InBottom,
		cvbdim_t	OutX,
		cvbdim_t	OutY
	)

Quick copy function for a rectangular region of interest, operating on several planes simultaneously. Therefore suited for e.g. RGB images.

Copies the pixels inside the rectangular region of interest (InLeft, InTop, InRight, InBottom) from the ImageIn to the ImageOut starting at the point (OutX, OutY). All planes are taken into account.

Copying is optimized for various VPAT layouts, i.e. this function will choose the fastest available approach that suits the layout of the input and the output image. The following BytesPerPixel are supported: 1, 2, 4, and 8.

Therefore this function will often be faster than the similar CopyImageArea which always runs through the VPAT in the source and destination image even if a quicker memcopy would be possible. For this function to be able to copy faster only the pixel coordinate system and a rectangular region of interest is supported (image coordinate system is not being taken into account).

If the input region of interest or the output region (partially) lies outside the boundaries of the respective images, the region will be silently cropped. Even if no image data could be copied due to this setup this function will return true.

Note

The cvbdatatype_t must be identical for accessed planes in ImageIn and ImageOut for this function to succeed.

Keep in mind, that areas of interest are inclusive (see TDRect for more information).

The speed advantage over CopyImageArea may be outweighed by the time consumed for the VPAT analysis of the input images if the region to be copied is very small or the image is not linear.

Attention

If ImageIn and ImageOut point to the same IImageVPA object, make sure that the source and destination areas respective planes do not overlap! The result is going to be undefined in this case and this function does not guard against this!

Parameters

[in]	ImageIn	Source image to copy from.
[in]	ImageOut	Destination image to copy to.
[in]	InLeft	Non-negative left edge of the region of interest.
[in]	InTop	Non-negative top edge of the region of interest.
[in]	InRight	Non-negative right edge of the region of interest (inclusive).
[in]	InBottom	Non-negative bottom edge of the region of interest (inclusive).
[in]	OutX	Non-negative X offset in the target image to copy to.
[in]	OutY	Non-negative Y offset in the target image to copy to.

Returns

true on success; false otherwise.

See also

CopyImageRect, CopyImageArea, CreateDuplicateImageEx

CopyOverlay()

cvbbool_t CopyOverlay	(	IMG	ImageIn,
		IMG	ImageOut
	)

Copies the overlay bits from the ImageIn to the ImageOut.

Note

Both images must be overlay capable (DT_Overlay set on cvbdatatype_t) and must have the same dimension. If at least one plane is overlay capable in both images, this function succeeds. Non-overlay-capable planes are ignored.

Parameters

[in]	ImageIn	Image used for copying the overlay bits from.
[in]	ImageOut	Image to copy the overlay bits to.

Returns

true if copy succeeded, false otherwise.

See also

CreateOverlayImage

CreateAreaSubImage()

cvbbool_t CreateAreaSubImage	(	IMG	ImageIn,
		TArea	Area,
		IMG &	ImageOut
	)

Creates a linear interpolated copy of the Area of the given ImageIn.

The resulting ImageOut, which is created via CreateCompatibleImage, has the default coordinate system. In contrast to CopyImageArea this function copies the given Area exactly as specified (even if the angle between the P0P1, P0P2 line segments is not perpendicular).

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.

Attention

This function uses P0P2 for its scan line instead of P0P1 (see TArea for additional information)!

Parameters

[in]	ImageIn	Image object handle of the source image.
[in]	Area	Area of interest in image coordinates to be copied.
[out]	ImageOut	Variable to receive the handle of the output image.

Returns

true if successful; false otherwise.

See also

CreateSubImage, CreateMatrixTransformedImage, CreateMatrixTransformedImageEx

CreateCompatibleImage()

cvbbool_t CreateCompatibleImage	(	IMG	ImageIn,
		cvbval_t	OutWidth,
		cvbval_t	OutHeight,
		cvbbool_t	ForceOverlayBit,
		IMG &	ImageOut
	)

Creates a new image of the same data type and number of planes, but with the given OutWidth and OutHeight.

The overlay capability may either be transferred from the input image or overridden by means of the ForceOverlayBit flag.

Image buffer layout depends on the cvbdatatype_t of ImageIn:

• CreateGenericImage is used for 8bpp plane images (IsAll8Bit).
• CreateGenericImageDT is used if all planes have the same cvbdatatype_t (IsAllSameDatatype), but not 8bpp.
• Multiple buffers created via CreateGenericImageDT and concatenated by CreateConcatenatedImage if the planes have different cvbdatatype_t.

Note

The coordinate system of ImageOut is the default coordinate system (see InitCoordinateMap).

This function does not copy image data, but uses the ImageIn to create a new, compatible image. The pixel content is not initialized.

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

Attention

ForceOverlayBit flag is ignored if the pixel datatype of ImageIn is not unsigned 8 bits per pixel.

If either OutWidth or OutHeight is 0, both values will be set to the ImageWidth and ImageHeight of ImageIn respectively.

The created ImageOut has the same datatype and dimension, but that does not mean, that the pixel buffer layout is exactly the same. Thus you cannot simply memcpy the image data. Still better use CopyImageRectPlanes or even CreateDuplicateImageEx if you want to clone an image with pixel content.

Parameters

[in]	ImageIn	Input image object handle.
[in]	OutWidth	Positive target width of the destination image; 0 if the width of ImageIn is to be used.
[in]	OutHeight	Positive target height of the destination image; 0 if the height of ImageIn is to be used.
[in]	ForceOverlayBit	Set to true to force the overlay capability; use false to use the overlay status of ImageIn.
[out]	ImageOut	Variable to receive the resulting image handle.

Returns

true on success; false otherwise.

CreateConcatenatedImage()

cvbbool_t CreateConcatenatedImage	(	IMG *	ImageArray,
		size_t	ArrayLength,
		cvbbool_t	ShareMemory,
		IMG &	ImageOut
	)

Concatenates an array of images into a single new one.

The planes in ImageOut will be ordered as given in the ImageArray. Its coordinate system is taken from the first valid image in ImageArray.

Note

Each input image in ImageArray must have the same width and height. If an input image handle is not valid, it will be silently discarded and treated as if there is no such element.

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

Attention

If ArrayLength is 1 and ShareMemory is true, no new IMG object is created, but the first handle in ImageArray is shared and set into ImageOut.

Parameters

[in]	ImageArray	Non-__NULL__ array containing the handles of at least one image to be concatenated.
[in]	ArrayLength	Non-zero number of elements in the ImageArray.
[in]	ShareMemory	true only creates a new VPAT and reuses the source image's buffer without copy; false copies all the image data.
[out]	ImageOut	Variable to receive the resulting image handle.

Returns

true on success; false otherwise.

Example

This is a C++11 example to swap image planes using CreateImageSubList and CreateConcatenatedImage.

#include <algorithm>
#include <memory>
#include <utility>
#include <vector>
#include <CVCError.h>
#include <iCVCImg.h>
 
// Helper to let the compiler take care of object life-time via custom deleter
using ObjPtr = std::unique_ptr<void, void(*)(OBJ)>;
 
// forward declaration
ObjPtr CreateSinglePlaneImage(IMG Image, cvbdim_t Plane);
 
// Swaps image planes, to e.g. have BGR instead of RGB
cvbres_t CreateReversePlanesImage(IMG Image, IMG &ReversePlaneImage)
{
  cvbdim_t numPlanes = ImageDimension(Image);
  if(numPlanes == 0)
    return CVC_ERROR(CVC_E_WRONGOBJECT);
 
  // own the newly created single plane images
  std::vector<ObjPtr> singlePlaneImages;
  for(cvbdim_t planeIndex = numPlanes - 1; planeIndex >= 0; --planeIndex)
  {
    ObjPtr pSinglePlaneImage = CreateSinglePlaneImage(Image, planeIndex);
    if(!pSinglePlaneImage) // check if added pointer is invalid
      return CVC_ERROR(CVC_E_MEMORY);
    singlePlaneImages.push_back(std::move(pSinglePlaneImage));
  }
 
  // non-owning handles "array" for CreateConcatenatedImage
  std::vector<IMG> imageHandles(singlePlaneImages.size());
  std::transform(std::begin(singlePlaneImages), std::end(singlePlaneImages), std::begin(imageHandles), [](const ObjPtr &pImage)
  {
    return pImage.get();
  });
 
  if(!CreateConcatenatedImage(
    imageHandles.data(),  // pointer to first element
    imageHandles.size(),  // number of elements
    false,                // copy the image data
    ReversePlaneImage     // result image
  ))
    return CVC_ERROR(CVC_E_MEMORY);
 
  return CVC_ERROR(CVC_E_OK);
}
 
ObjPtr CreateSinglePlaneImage(IMG Image, cvbdim_t Plane)
{
  IMG singlePlaneImage = nullptr;
  CreateImageSubList(
    Image,            // input image
    Plane,            // plane index
    1,                // only use 1 plane from input
    true,             // do not copy
    singlePlaneImage  // result image
  );
  // no error handling: on failure singlePlaneImage is still nullptr
  return ObjPtr(singlePlaneImage, [](OBJ pObj) { ReleaseObject(pObj); });
}

CreateDuplicateImage()

cvbbool_t CreateDuplicateImage	(	IMG	ImageIn,
		IMG &	ImageOut
	)

Creates a new image which is a copy from ImageIn.

Creates an output image which ImageWidth, ImageHeight and data type(s) match those of the ImageIn. Then copies the pixel data and the coordinate system from ImageIn to the newly created 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.

Always runs through the VPAT for copying the image data. For a possibly faster copy use CreateDuplicateImageEx.

Note

Note that the output image buffer layout depends on the ImageIn planes and their cvbdatatype_t: ImageOut is created via CreateCompatibleImage.

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

Parameters

[in]	ImageIn	Source image.
[out]	ImageOut	Variable to receive the resulting image handle.

Returns

true on success; false otherwise.

See also

CreateDuplicateImageEx

CreateDuplicateImageEx()

cvbbool_t CreateDuplicateImageEx	(	IMG	ImageIn,
		IMG &	ImageOut
	)

Creates a new quick copied image from the given ImageIn.

Creates an output image which ImageWidth, ImageHeight and data type(s) match those of the ImageIn. Then copies the pixel data and the coordinate system from ImageIn to the newly created ImageOut.

Unlike CreateDuplicateImage, CreateDuplicateImageEx will not necessarily run through the VPAT for copying the image data. Instead it will - very much like CopyImageRectPlanes - analyze the VPA layout of the ImageIn and choose the most suitable copy mode automatically. The following BytesPerPixel are supported: 1, 2, 4, and 8.

Note

Note that the output image will - unlike the output generated by CreateDuplicateImage - always have a positive y-increment. CreateDuplicateImageEx can therefore be used to efficiently generate a linearized version of the ImageIn.

If all planes have the same cvbdatatype_t, the newly created image will be in a contiguous block with interleaved planes. If there are different cvbdatatype_t for the planes, each plane will be stored in its own block of memory.

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

Parameters

[in]	ImageIn	Source image.
[out]	ImageOut	Variable to receive the resulting image handle.

Returns

true on success; false otherwise.

See also

CreateDuplicateImage, CopyImageRectPlanes

CreateGenericImage()

cvbbool_t CreateGenericImage	(	cvbval_t	NumPlanes,
		cvbval_t	Width,
		cvbval_t	Height,
		cvbbool_t	HasOverlay,
		IMG &	ImageOut
	)

Creates a new and uninitialized interleaved image with 8 bits per plane.

The image will be created in DIB-compatible style, which means that it is flipped in memory: last line comes first in memory. This means that GetLinearAccess from the CVCUtilities library will return a negative y-increment.

Note

The coordinate system of ImageOut is the default coordinate system (see InitCoordinateMap).

The pixel buffer created by this function is not initialized. Use e.g. InitializeImageAreaEx if a defined content is needed.

Release the image with ReleaseObject if it is no longer needed.

Attention

When creating images with NumPlanes greater than 1 (e.g. RGB images), the memory layout will be interleaved. I.e. the memory layout is as indicated below:

R11	G11	B11	R12	G12	B12
R9	G9	B9	R10	G10	B10
R7	G7	B7	R8	G8	B8
R5	G5	B5	R6	G6	B6
R3	G3	B3	R4	G4	B4
R1	G1	B1	R2	G2	B2

As described in IImageVPA the pixel buffer layout has no impact on the logical plane indices: 0 will always be red ignoring the physical memory layout.

Parameters

[in]	NumPlanes	Number of planes to be created.
[in]	Width	Width of the output image to be created.
[in]	Height	Height of the output image to be created.
[in]	HasOverlay	true set the cvbdatatype_t being overlay capable (DT_Overlay); false otherwise.
[out]	ImageOut	Variable to receive the resulting image handle.

Returns

true if successful; false otherwise.

See also

CreateGenericImageDT

CreateGenericImageDT()

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.

This function is similar to CreateGenericImage, but it differs from it in the following ways:

• It is possible to specify the data type of the image planes (one cvbdatatype_t for all planes)
• If the overlay bit is to be used, this will have to be set via the Datatype parameter (e.g. #DT_Overlay | 16)
• The output image will always be created as a planar image (CreateGenericImage will create interleaved memory layout when called upon to generate an RGB image)

Note

The coordinate system of ImageOut is the default coordinate system (see InitCoordinateMap).

The pixel buffer created by this function is not initialized. Use e.g. InitializeImageAreaEx if a defined content is needed.

Release the image with ReleaseObject if it is no longer needed.

Attention

As a planar memory layout is created, the pixel buffer looks like this for a three plane image:

R	R	R	R	R	R
R	R	R	R	R	R
G	G	G	G	G	G
G	G	G	G	G	G
B	B	B	B	B	B
B	B	B	B	B	B

As described in IImageVPA the pixel buffer layout has no impact on the logical plane indices: 0 will always be red ignoring the physical memory layout.

Parameters

[in]	NumPlanes	Number of planes to be created.
[in]	Width	Positive width of the output image to be created.
[in]	Height	Positive height of the output image to be created.
[in]	Dataype	Data type of the output image's planes.
[out]	ImageOut	Variable to receive the newly created image handle.

Returns

true if successful; false otherwise.

See also

CreateGenericImage

CreateImageDeleteList()

cvbbool_t CreateImageDeleteList	(	IMG	ImageIn,
		cvbval_t	PlaneIndex,
		cvbval_t	NumPlanes,
		cvbbool_t	MapImage,
		IMG &	ImageOut
	)

Creates a new image that contains a plane-subset of the ImageIn by omitting planes.

Note

The coordinate system of ImageOut is copied from ImageIn.

This function can create either a copy of the selected planes (MapImage is false) or just create a mapped image (reuses the pixel buffer and only creates a new VPAT per plane): MapImage is true.

If this function is successful and MapImage is true, then the ImageIn is shared by the ImageOut to ensure the pixel buffer's life-time. When not needed anymore the ImageOut must be released via ReleaseObject. In that case also the ImageIn is released.

Example

If you have an RGB image and you start deleting at PlaneIndex 0 and delete NumPlanes = 2, then you receive a single plane image in ImageOut containing the blue plane only:

IMG blueImage = nullptr;
if(CreateImageDeleteList(rgbImage, 0, 2, false, blueImage))
{
  // process it
 
  // when done with it
  ReleaseObject(blueImage);
}

Parameters

[in]	ImageIn	Object handle of the source image.
[in]	PlaneIndex	First plane to omit.
[in]	NumPlanes	Number of planes to be omitted.
[in]	MapImage	true to MapImage the pixel buffer instead of copying it into a new buffer (false).
[out]	ImageOut	Variable to receive the resulting image handle.

Returns

true if successful; false otherwise.

See also

CreateImageSubList, CreateConcatenatedImage, CreateImageInsertList

CreateImageFromPointer()

cvbres_t CreateImageFromPointer	(	void *	pImageMemory,
		size_t	MemorySize,
		cvbdim_t	Width,
		cvbdim_t	Height,
		cvbdim_t	NumPlanes,
		cvbdatatype_t	DataType,
		intptr_t	PitchX,
		intptr_t	PitchY,
		intptr_t	PitchPlane,
		const cvbval_t	PlaneOrder[],
		PFFINALRELEASE	ReleaseCallback,
		void *	pPrivate,
		IMG &	ImageOut
	)

Creates an image object around a block of memory without copying the data.

This function creates an IImageVPA view on the given pImageMemory buffer. It does not own the memory given. If you need to get notified on the disposal of the created ImageOut, you can pass a ReleaseCallback with its pPrivate. The base pointer passed to the ReleaseCallback will be pImageMemory. If you don't need notification set pPrivate and ReleaseCallback to nullptr.

PlaneOrder can be optionally defined if the memory order is not the logical order (e.g. 0 for red, 1 for green and 2 for blue). If single plane images are created or the memory order is equal to the logical order, nullptr can be given as argument.

If not nullptr, the PlaneOrder array must have a size of NumPlanes with unique entries ranging from [0 .. NumPlanes[ (excluding NumPlanes).

Pitch Examples

Layout	PitchX	PitchY	PitchPlane
Contiguous Mono8	1	Width	0
Contiguous Mono10	2	Width * 2	0
Contiguous RGB8	3	Width * 3	1
Contiguous RGB8 Planar	1	Width	PitchY * Height

Mono10 is stored in two bytes (not packed) in IImageVPA images.

Plane Order Examples

Layout	PlaneOrder
Mono	nullptr or [0]
RGB	nullptr or [0, 1, 2]
BGR	[2, 1, 0]

Note

When not needed anymore, ImageOut must be released via ReleaseObject.

MemorySize is only used for consistency checking: e.g. if Width and Height is 16 each, but the caller claims to pass only 3 bytes, then the buffer is invalid. The DataType value is always validated against PitchX and PitchY: e.g. if the absolute value of the PitchX or PitchY is less than the number of bytes required for one pixel, then the layout is invalid.

All NumPlanes image planes have the same DataType. If you need images with differing cvbdatatype_t, you can call this function multiple times and combine these images via CreateConcatenatedImage.

Attention

Take care to specify the correct memory layout as access violations/segmentation faults or worse may occur! These effects will first be visible when actually accessing the buffer, not when creating the image view.

Also take care that the referenced memory stays valid for as long as the returned ImageOut is alive.

Parameters

[in]	pImageMemory	Non-nullptr to the base of the image buffer.
[in]	MemorySize	Optional size of the memory buffer in bytes; zero for no validation.
[in]	Width	Width of the image to be created in pixels.
[in]	Height	Height of the image to be created in pixels.
[in]	NumPlanes	Positive number of planes of the image to be created.
[in]	DataType	cvbdatatype_t for all planes of the image to be created.
[in]	PitchX	Distance in memory in bytes between two horizontally neighboring pixels (position x and position x+1) in the same plane.
[in]	PitchY	Distance in the memory in bytes between two vertically neighboring pixels (position y and position y+1) in the same plane.
[in]	PitchPlane	Distance in the memory in bytes between two equivalent pixels (same x- and y-coordinate) in two consecutive image planes.
[in]	PlaneOrder	Optional array of size NumPlanes to specify a nonstandard plane order; nullptr for default order.
[in]	ReleaseCallback	Mandatory callback function pointer that will be called when the reference count of ImageOut reaches zero.
[in]	pPrivate	Pointer which is passed to the ReleaseCallback to store user state like an object pointer.
[out]	ImageOut	Variable that receives the handle to the newly created image.

Returns

• CVC_ERROR (CVC_E_OK) on success.
• CVC_ERROR (CVC_E_PARAMETER) if input data is invalid/inconsistent.
• CVC_ERROR (CVC_E_MEMORY) if not enough memory was available to create ImageOut.

Mono8 Example

// Create an image from a contiguous byte-array.
cvbres_t CreateImageFromMono8(cvbuint8_t *pMemory, cvbdim_t Width, cvbdim_t Height, IMG &ImageOut)
{
  return CreateImageFromPointer(pMemory, Width * Height, Width, Height,
                                1 /* NumPlanes */,
                                8 /* DataType */,
                                1 /* PitchX */,
                                Width /* PitchY */,
                                0 /* PitchPlane */,
                                nullptr /* PlaneOrder */,
                                nullptr /* from above */,
                                nullptr /* pPrivate */,
                                ImageOut);
}
 
int main()
{
  cvbuint8_t buffer[640 * 480] = { 0 }; // black image
  IMG image = nullptr;
  cvbres_t result = CreateImageFromMono8(buffer, 640, 480, image);
  if(result < 0)
    return EXIT_FAILURE;
  
  // do something with the image
  
  // when done with it
  ReleaseObject(image);
  return EXIT_SUCCESS;
}

BGR8 Example

#pragma pack ( push, 1 )
struct BGRColor
{
  cvbuint8_t B;
  cvbuint8_t G;
  cvbuint8_t R;
};
#pragma pack ( pop )
 
// Create an image from a contiguous BGR8 (24bit per pixel) array.
cvbres_t CreateImageFromBGR8(BGRColor *pMemory, cvbdim_t Width, cvbdim_t Height, IMG &ImageOut)
{
  static const cvbval_t PLANEORDER[] = { 2, 1, 0 };
  return CreateImageFromPointer(pMemory, Width * Height * 3, Width, Height
                                3 /* NumPlanes */,
                                8 /* DataType */,
                                3 /* PitchX */,
                                Width * 3 /* PitchY */,
                                1 /* PitchPlane */,
                                PLANEORDER,
                                nullptr /* from above */,
                                nullptr /* pPrivate */,
                                ImageOut);
}
 
int main()
{
  BGRColor buffer[640 * 480] = { 0 }; // black image
  IMG image = nullptr;
  cvbres_t result = CreateImageFromBGR8(buffer, 640, 480, image);
  if(result < 0)
    return EXIT_FAILURE;
  
  // do something with the image
  
  // when done with it
  ReleaseObject(image);
  return EXIT_SUCCESS;
}

CreateImageInsertList()

cvbbool_t CreateImageInsertList	(	IMG	Image1,
		IMG	Image2,
		cvbval_t	Image1InsertionIndex,
		cvbbool_t	MapImage,
		cvbbool_t	Intersect,
		IMG &	ImageOut
	)

Creates a new image where the planes of Image2 are inserted into Image1 starting at Image1InsertionIndex.

If Intersect is false, then simply the ImageWidth and ImageHeight are taken from Image1 as well as its TCoordinateMap. If Image2 has different width or height, then its resolution is adjusted via CreateImageMap.

If Intersect is true, though, then a new width and height and TCoordinateMap are calculated as follows:

• The bounding rects of Image1 and Image2 are translated according to their coordinate system TCoordinateMap::OrgX and TCoordinateMap::OrgY (the TCoordinateMap::Matrix is ignored).
• The intersection between the now transformed rectangles defines the new image region.
• The coordinate system origin of ImageOut is set to the left-/top-most origin component of both input coordinate systems. The matrix is taken from Image1.

Note

This function can create either a copy of the selected planes (MapImage is false) or just create a mapped image (reuses the pixel buffer and only creates a new VPAT per plane): MapImage is true.

If this function is successful and MapImage is true, then Image1 and Image2 are shared by the ImageOut to ensure the pixel buffers' life-time. When not needed anymore the ImageOut must be released via ReleaseObject. In that case also the Image1 and Image2 are released.

When setting Intersect to true and giving images that due to their coordinate systems do not overlap, this function fails.

Parameters

[in]	Image1	Object handle of the first source image.
[in]	Image2	Object handle of the second source image.
[in]	Image1InsertionIndex	Index at which to start inserting the planes from Image2 into the plane sequence of Image1.
[in]	MapImage	true to MapImage the pixel buffer instead of copying it into a new buffer (false).
[in]	Intersect	true to create ImageOut dimension and coordinate system by transforming both; false to simply use dimension and coordinate system of Image1.
[out]	ImageOut	Variable to receive the resulting image handle.

Returns

true if successful; false otherwise.

See also

CreateImageDeleteList, CreateImageSubList, CreateConcatenatedImage

CreateImageMap()

cvbbool_t CreateImageMap	(	IMG	ImageIn,
		cvbval_t	InLeft,
		cvbval_t	InTop,
		cvbval_t	InRight,
		cvbval_t	InBottom,
		cvbval_t	OutWidth,
		cvbval_t	OutHeight,
		IMG &	ImageOut
	)

Creates a new mapped image object based on the rectangular area of interest and scales it to a destination size.

The rectangular AOI (InLeft, InTop, InRight, InBottom) will be scaled to the given OutWidth and OutHeight.

This function does not copy data and therefore will be extremely fast. It only creates a view of the original ImageIn using its pixel buffer. Newly created are only one VPAT per plane and a TCoordinateMap.

Note

The scaling only uses a sub-/super-sampling approach without any interpolation. Thus this will likely produce notable artifacts.

The coordinate system of the ImageOut will be moved such that the top left pixel of the output image will - in image coordinates - have the same position as in the original image. The TCoordinateMap::Matrix is copied from ImageIn.

This function can safely be used with driver images as ImageOut stores a reference to the ImageIn and queries the base pointer from it. So with that you can have a mapped image created once for a driver image and keep on working on your defined AOI.

If this function is successful the ImageIn is shared by the ImageOut to ensure its life-time. When not needed anymore the ImageOut must be released via ReleaseObject. In that case also the ImageIn is released.

Specifying an AOI outside the ImageIn will fail.

Attention

Remember that CVB AOIs are inclusive (see TDRect for more information).

Writing to a mapped image will write to the original ImageIn pixel buffer. As sub- or super-sampling is used, algorithms might have surprising results as different logical pixels might point to the same memory location!

Parameters

[in]	ImageIn	Handle to the source image object.
[in]	InLeft	Left edge of AOI in the ImageIn.
[in]	InTop	Top edge of AOI in the ImageIn.
[in]	InRight	Right edge of AOI in the ImageIn (inclusive).
[in]	InBottom	Bottom edge of AOI in the ImageIn (inclusive).
[in]	OutWidth	Positive width of the output image to be created.
[in]	OutHeight	Positive height of the output image to be created.
[out]	ImageOut	Variable to receive the resulting image handle.

Returns

true if successful; false otherwise.

Example

cvbbool_t ScaleImageMap(IMG ImageIn, double Factor, IMG &ImageOut)
{
  cvbdim_t width = ImageWidth(ImageIn);
  cvbdim_t height = ImageHeight(ImageIn);
  if(width < 1 || height < 1)
    return false;
 
  cvbdim_t targetWidth = static_cast<cvbdim_t>(round(width * Factor));
  cvbdim_t targetHeight = static_cast<cvbdim_t>(round(height * Factor));
 
  return CreateImageMap
  (
    ImageIn,
    0, 0,                   //  (left, top) point
    width - 1, height - 1,  //  (right, bottom) point
    targetWidth, targetHeight,
    ImageOut
  );
}

See also

CreateMatrixTransformedImage

CreateImageSubList()

cvbbool_t CreateImageSubList	(	IMG	ImageIn,
		cvbval_t	PlaneIndex,
		cvbval_t	NumPlanes,
		cvbbool_t	MapImage,
		IMG &	ImageOut
	)

Creates a new image that contains a plane-subset of the ImageIn by including only selected planes.

Note

The coordinate system of ImageOut is copied from ImageIn.

This function can create either a copy of the selected planes (MapImage is false) or just create a mapped image (reuses the pixel buffer and only creates a new VPAT per plane): MapImage is true.

If this function is successful and MapImage is true, then the ImageIn is shared by the ImageOut to ensure the pixel buffer's life-time. When not needed anymore the ImageOut must be released via ReleaseObject. In that case also the ImageIn is released.

See CreateConcatenatedImage for an example.

Parameters

[in]	ImageIn	Object handle of the source image.
[in]	PlaneIndex	First plane to keep.
[in]	NumPlanes	Number of planes to be kept.
[in]	MapImage	true to MapImage the pixel buffer instead of copying it into a new buffer (false).
[out]	ImageOut	Variable to receive the resulting image handle.

Returns

true if creation succeeded, false otherwise.

See also

CreateImageDeleteList, CreateConcatenatedImage, CreateImageInsertList

CreateNonOverlayImage()

cvbbool_t CreateNonOverlayImage	(	IMG	ImageIn,
		IMG &	ImageOut
	)

Creates a new non-overlay image which is copy of the overlay capable ImageIn.

The overlay bits (lowest bit) of ImageOut will be set to zero. The resulting ImageOut will have an interleaved layout with positive pixel and line increments.

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

Note

Release the ImageOut with ReleaseObject when it is no longer needed.

Parameters

[in]	ImageIn	Source image object handle.
[out]	ImageOut	Variable to receive the resulting image handle.

Returns

true if successful; false otherwise.

See also

CreateOverlayImage, CreateGenericImageDT, CopyOverlay, ReleaseObject

CreateOverlayImage()

cvbbool_t CreateOverlayImage	(	IMG	ImageIn,
		IMG &	ImageOut
	)

Creates a new overlay image which is a copy of an ImageIn.

The ImageOut is created by CreateCompatibleImage with forced overlay bit. The copied pixel data has its overlay bit set to 0.

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

Note

Release the ImageOut with ReleaseObject when it is no longer needed.

Parameters

[in]	ImageIn	Source image object handle.
[out]	ImageOut	Variable to receive the resulting image handle.

Returns

true if successful; false otherwise.

See also

CreateNonOverlayImage, CreateGenericImageDT, CopyOverlay, ReleaseObject

CreatePanoramicImageMap()

cvbbool_t CreatePanoramicImageMap	(	IMG	ImageA,
		IMG	ImageB,
		TPanoramaMode	PanoramaMode,
		IMG &	ImageOut
	)

Merges the two input images ImageA, ImageB into one ImageOut without copying the pixel data.

The effect is achieved by creating an output image that does not have memory of its own (similar to what CreateImageMap does) and then modifying the VPAT of the ImageOut to reference the memory of the two input images ImageA and ImageB.

Note

The coordinate system of ImageOut is the default coordinate system (see InitCoordinateMap).

The input images need to be compatible, which means that depending on the TPanoramaMode either width or height need to be identical, the dimension (number of planes) needs to be identical and the data types of the planes need to be identical.

If width, height or dimension do not match, you may use the functions CreateImageMap (for width/height) or CreateImageSubList / CreateImageInsertList to fix this. If the data types do not match, you will need to create a converted image first.

Lastly, the VPATs of the images must be compatible for generating the panoramic map. If, for example, ImageA has a VPAT with a y-increment of 1024 and ImageB has a VPAT with a y-increment of 2048, generating a horizontally merged panoramic map will fail, because in the output image the section for ImageA and ImageB will need to share the y-VPAT entries which is not possible if the y-VPAT of both images has a different increment.

If this function is successful the ImageA and ImageB are shared by the ImageOut to ensure their life-time. When not needed anymore the ImageOut must be released via ReleaseObject. In that case also the ImageA and ImageB are released.

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

Attention

There is one fundamental difference between CreatePanoramicImageMap and CreateImageMap: The image created by CreateImageMap will always refer to the most up-to-date frame when generated from a driver IMG, because CreateImageMap will keep querying the base pointer from the original image.

This kind of behavior, however, is not possible for CreatePanoramicImageMap, because this would require the difference between the base pointer of ImageA and ImageB to remain the same - a condition that is in practice almost never met. Therefore, CreatePanoramicImageMap will store the base pointer of the input images (that of ImageA directly, that of ImageB implicitly through the shape of the VPAT).

That means if you use a panoramic image on one or more driver IMG objects, the pixel buffer content is undefined after unlocking the buffer! This happens on the next call to G2Wait in RINGBUFFER_LOCKMODE_AUTO or when calling RBUnlock with RINGBUFFER_LOCKMODE_ON.

Please note that the result image created by this function will usually not have a linear memory layout. Therefore, code that relies on a linear memory layout will fail when working on the result images from this function. If a linear memory layout is required, the image data will need to be copied - for example using CreateDuplicateImageEx.

Parameters

[in]	ImageA	First input image.
[in]	ImageB	Second input image.
[in]	PanoramaMode	Mode to be used when generating the output image.
[out]	ImageOut	Variable to receive the generated image handle.

Returns

true on success; false otherwise.

CreateRotatedImageMap()

cvbbool_t CreateRotatedImageMap	(	IMG	ImageIn,
		TVPATRotation	Rotation,
		IMG &	ImageOut
	)

Rotates the ImageIn in right angle (90°) steps via VPAT.

Creates an image map from the given ImageIn that is rotated counter clockwise. Only new VPA table(s) are created, but no image data is copied.

The mapped image has its own coordinate system (copied from ImageIn) and VPA tables.

Note

If this function is successful the ImageIn is shared by the ImageOut to ensure its life-time. When not needed anymore the ImageOut must be released via ReleaseObject. In that case also the ImageIn is released.

Parameters

[in]	ImageIn	Image to rotate in right angle (90°) steps.
[in]	Rotation	Either 90°, 180° or 270° rotation.
[out]	ImageOut	Variable to receive resulting mapped image handle.

Returns

true on success; false otherwise.

CreateSubImage()

cvbbool_t CreateSubImage	(	IMG	ImageIn,
		TArea	Area,
		IMG &	ImageOut
	)

Creates a linear interpolated copy of the Area of the given ImageIn.

The copy will have the dimensions of the smallest possible axis parallel bounding rectangle which encloses the given Area. This bounding rectangle is calculated in the Image's currently set coordinate system (i. e. "axis parallel" refers to the potentially rotated coordinate axes).

The resulting ImageOut, which is created via CreateCompatibleImage, has the default coordinate system.

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

In most cases you want to use CreateAreaSubImage.

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

Parameters

[in]	ImageIn	Image object handle of the source image.
[in]	Area	Area of interest in image coordinates to be copied.
[out]	ImageOut	Variable to receive the handle of the output image.

Returns

true if successful; false otherwise.

See also

CreateAreaSubImage for a function that treats the Area as it is defined.

GetDatatypeMinMaxVal()

cvbbool_t GetDatatypeMinMaxVal	(	cvbdatatype_t	Datatype,
		cvbval_t &	MinVal,
		cvbval_t &	MaxVal
	)

Returns the minimum and maximum value for a pixel component based on its Datatype.

Attention

This function only works with Datatype descriptors for integer planes with no more than 32 bits per pixel.

Parameters

[in]	Datatype	Data type descriptor for which to calculate the values.
[out]	MinVal	Minimum value for pixels of the given Datatype.
[out]	MaxVal	Maximum value for pixels of the given Datatype.

Returns

true if successful; false for invalid or non-integer data types.

See also

ImageDatatype

GetPixel()

cvbbool_t CVB::GetPixel	(	IMG	Image,
		cvbval_t	PlaneIndex,
		cvbval_t	X,
		cvbval_t	Y,
		cvbval_t &	Value
	)

Alias for CVB::GetPixVal.

Deprecated:

This function is deprecated since Common Vision Blox 13.04.000 and has in fact been removed from the C header. Please use CVB::GetPixVal instead.

See also

CVB::GetPixVal

GetPixVal()

cvbbool_t CVB::GetPixVal	(	IMG	Image,
		cvbval_t	PlaneIndex,
		cvbval_t	X,
		cvbval_t	Y,
		cvbval_t &	Value
	)

Gets the Value of a pixel of the given Image in the plane specified by PlaneIndex at the location X, Y.

This gets the pixel Value at location X, Y independent of the cvbdatatype_t of the Image.

Note

This is the slowest way of accessing image data and has been implemented for the sake of completeness. Using CVCUtility library's GetLinearAccess or GetImageVPA is preferable.

Attention

This function does not work on images having a DT_Float cvbdatatype_t.

Parameters

[in]	Image	Object handle of the image to access.
[in]	PlaneIndex	Index of plane to access pixel component.
[in]	X	X coordinate of the pixel.
[in]	Y	Y coordinate of the pixel.
[out]	Value	Variable to receive the pixel value.

Returns

true if successful; false otherwise.

See also

GetImageVPA, CVB::SetPixVal

HasOverlay()

cvbbool_t HasOverlay

(

IMG

Image

)

Checks if any plane of the given Image has DT_Overlay set in its datatype.

Parameters

[in]

Image

Image object handle of the image to inspect.

Returns

true if at least on plane in the Image has the overlay bit set; false otherwise or if the Image is invalid.

See also

CreateOverlayImage, CreateGenericImage, CreateGenericImageDT, ImageDatatype

ImageColorModel()

TColorModel ImageColorModel

(

IMG

Image

)

Returns the color model descriptor for the Image.

Note

The return value of CM_Unknown is ambiguous as it may be returned if the given Image is invalid or if the given Image has no IColorModel interface and has a ImageDimension unequal to 1 and unequal to 3.

Parameters

[in]

Image

Image object handle of the image for which to retrieve the color model.

Returns

Color model descriptor; CM_Unknown on error.

Example

This example shows how to ignore the Guess part for monochrome and RGB models:

TColorModel colorModel = ImageColorModel(Image);
switch(abs(colorModel))
{
case CM_Unknown:
  // Error case
  break;
case CM_RGB:
  // RGB case
  break;
case CM_Mono:
  // Mono case
  break;
// ...  
}

See also

NumPlanesNeededPerImage

ImageToDC()

void ImageToDC	(	IMG	ImageIn,
		HDC	hDC,
		cvbval_t	hDCLeft,
		cvbval_t	hDCTop,
		cvbval_t	InLeft,
		cvbval_t	InTop,
		cvbval_t	InRight,
		cvbval_t	InBottom,
		cvbval_t	hDCWidth,
		cvbval_t	hDCHeight,
		cvbval_t	RedPlaneIndex,
		cvbval_t	GreenPlaneIndex,
		cvbval_t	BluePlaneIndex,
		double	Gain,
		cvbval_t	Offset
	)

Blits the ImageIn into a standard Windows DeviceContext with DSM_WrapAround mode.

See ImageToDCEx for additional information as this function forwards its parameters to it:

ImageToDCEx(ImageIn, hDC, hDCLeft, hDCTop, InLeft, InTop, InRight, InBottom, hDCWidth, hDCHeight, RedPlaneIndex, GreenPlaneIndex, BluePlaneIndex, Gain, Offset, DSM_WrapAround);

Attention

This function is only available on Microsoft Windows operating systems.

Parameters

[in]	ImageIn	Image object handle of the source image to be blitted.
[in]	hDC	Windows device context into which to blit.
[in]	hDCLeft	Left edge in the device context where to start blit.
[in]	hDCTop	Top edge in the device context where to start blit.
[in]	InLeft	Left edge of AOI in the ImageIn.
[in]	InTop	Top edge of AOI in the ImageIn.
[in]	InRight	Right edge of AOI in the ImageIn (inclusive).
[in]	InBottom	Bottom edge of AOI in the ImageIn (inclusive).
[in]	hDCWidth	Positive width of the output image to be created.
[in]	hDCHeight	Positive height of the output image to be created.
[in]	RedPlaneIndex	Plane index to be used to display as red plane.
[in]	GreenPlaneIndex	Plane index to be used to display as green plane.
[in]	BluePlaneIndex	Plane index to be used to display as blue plane.
[in]	Gain	Gain to apply before blitting. Will be ignored if the Mode DSM_ViewPort is being used.
[in]	Offset	Offset to apply before blitting. Will be ignored if the Mode DSM_ViewPort is being used.

ImageToDCEx()

void ImageToDCEx	(	IMG	ImageIn,
		HDC	hDC,
		cvbval_t	hDCLeft,
		cvbval_t	hDCTop,
		cvbval_t	InLeft,
		cvbval_t	InTop,
		cvbval_t	InRight,
		cvbval_t	InBottom,
		cvbval_t	hDCWidth,
		cvbval_t	hDCHeight,
		cvbval_t	RedPlaneIndex,
		cvbval_t	GreenPlaneIndex,
		cvbval_t	BluePlaneIndex,
		double	Gain,
		cvbval_t	Offset,
		TDisplayScaleMode	Mode
	)

Blits the ImageIn into a standard Windows DeviceContext with user-definable handling of bit depths > 8.

CreateImageMap is used to scale the ImageIn according to the AOI and target size.

The contrast and brightness of the ImageIn is controlled by Gain and Offset.

This function highlights the overlay pixels if an ImageIn having a cvbdatatype_t with set DT_Overlay is given.

Note

For showing a gray scale image use the same index for the RedPlaneIndex, GreenPlaneIndex and BluePlaneIndex.

For a floating point ImageIn always DSM_ViewPort will be used. Use of DSM_ViewPort here causes the function to ignore the settings for Gain and Offset.

Attention

This function is only available on Microsoft Windows operating systems.

Parameters

[in]	ImageIn	Image object handle of the source image to be blitted.
[in]	hDC	Windows device context into which to blit.
[in]	hDCLeft	Left edge in the device context where to start blit.
[in]	hDCTop	Top edge in the device context where to start blit.
[in]	InLeft	Left edge of AOI in the ImageIn.
[in]	InTop	Top edge of AOI in the ImageIn.
[in]	InRight	Right edge of AOI in the ImageIn (inclusive).
[in]	InBottom	Bottom edge of AOI in the ImageIn (inclusive).
[in]	hDCWidth	Positive width of the output image to be created.
[in]	hDCHeight	Positive height of the output image to be created.
[in]	RedPlaneIndex	Plane index to be used to display as red plane.
[in]	GreenPlaneIndex	Plane index to be used to display as green plane.
[in]	BluePlaneIndex	Plane index to be used to display as blue plane.
[in]	Gain	Gain to apply before blitting. Will be ignored if the Mode DSM_ViewPort is being used.
[in]	Offset	Offset to apply before blitting. Will be ignored if the Mode DSM_ViewPort is being used.
[in]	Mode	Specifies how to treat high bit images when blitting (see TDisplayScaleMode).

ImageToMemory()

cvbbool_t ImageToMemory	(	IMG	Image,
		void *	pMem,
		intptr_t	Capacity
	)

Serializes the Image object into a buffer.

The data of the Image (including coordinate system and object data) will be serialized to the destination buffer at pMem, provided the buffer is sufficiently big (use ImageToMemorySize to determine the buffer size required to serialize a given image).

Upon completion, the buffer provided by the caller will effectively contain a MIO image (i.e. saving the buffer's content to a file with the extension ".mio" will make it possible to open this file e.g. in a Common Vision Blox example!).

If Capacity is less than the output of ImageToMemorySize, then only the number of bytes specified by Capacity will be copied and no error will be returned. Also at most ImageToMemorySize bytes are copied.

Attention

The buffer will not just contain a copy of the pixel data (use ImageToMemoryRaw to export only pixel data). It is not in a directly interpretable format.

Parameters

[in]	Image	Image object handle of the image to be serialized.
[in]	pMem	Pointer to the block of memory to which the image should be serialized.
[in]	Capacity	Size of the block of memory pointed to by pMem in bytes.

Returns

true if successful; false otherwise.

See also

ImageToMemorySize, MemoryToImage

ImageToMemoryRaw()

cvbbool_t ImageToMemoryRaw	(	IMG	Image,
		void *	pMem,
		intptr_t	Capacity,
		TRawFileLayout	Layout
	)

Write the raw pixel data of an image into a buffer.

Writes the raw pixel data of an image into the target buffer. The buffer starts at pixel coordinate (0,0) and goes through the image line by line. With Layout the way the target buffer is filled can be set:

• RFL_Interleaved
• RFL_Planar

Unlike the related function ImageToMemory this function will not dump a (deserializable) object structure into the designated block of memory; it will instead only dump the actual pixel data currently inside the Image which may then be used for any purpose outside Common Vision Blox.

This function only copies images where all planes have the same data type, the data type itself however may be anything supported by CVB except DT_ComplexPacked.

If Capacity is less than the output of ImageToMemoryRawSize, then only the number of bytes specified by Capacity will be copied and no error will be returned. Also at most ImageToMemoryRawSize bytes are copied.

Note

You can use this function if you need to copy the Image data to the specific Layout e.g. to another library's buffer.

Parameters

[in]	Image	Image to be copied.
[in]	pMem	Pointer to the memory to copy the Image data to.
[in]	Capacity	Number of bytes available at pMem.
[in]	Layout	Specifies how multi planar images are treated.

Returns

true if successful; false otherwise.

See also

ImageToMemoryRawSize

ImageToMemoryRawSize()

intptr_t ImageToMemoryRawSize

(

IMG

Image

)

Determine the amount of memory needed for ImageToMemoryRaw.

See ImageToMemoryRaw for detailed documentation.

Parameters

[in]

Image

Image to get the buffer size for.

Returns

Size of the buffer needed for all the pixels in Image in bytes; 0 on error.

See also

ImageToMemory

ImageToMemorySize()

intptr_t ImageToMemorySize

(

IMG

Image

)

Determine the amount of memory needed for ImageToMemory.

See ImageToMemory for detailed documentation.

Parameters

[in]

Image

Image to get the buffer size for.

Returns

Size of the buffer needed for all the pixels in Image in bytes; 0 on error.

See also

ImageToMemory, MemoryToImage

InitializeImageArea()

cvbbool_t InitializeImageArea	(	IMG	Image,
		cvbval_t	PlaneIndex,
		TArea	Area,
		cvbval_t	Value
	)

Initialize the pixels in the given Area to a given Value.

Deprecated:

There are a newer version of the method. See InitializeImageAreaEx for additional information.

Parameters

[in]	Image	Image object handle to be initialized.
[in]	PlaneIndex	Index of plane to be initialized.
[in]	Area	Area of interest to be initialized.
[in]	Value	Value for initializing the pixels to.

Returns

true if successful; false otherwise.

InitializeImageAreaEx()

cvbbool_t InitializeImageAreaEx	(	IMG	Image,
		cvbval_t	PlaneIndex,
		TArea	Area,
		double	Value
	)

Initialize the pixels in the given Area to a given Value.

It uses ScanPlaneUnary to initialize the Area of the Image plane at PlaneIndex to Value.

This is a newer version of InitializeImageArea. It is also capable of treating images with floating point and 64 bit values.

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

Although this function uses a TArea it does not take the coordinate system of the ImageIn into account (see TCoordinateMap on coordinate systems). You can use ImageAreaToPixel to transform the image coordinates into pixel coordinates if necessary.

Parameters

[in]	Image	Image object handle to be initialized.
[in]	PlaneIndex	Index of plane to be initialized.
[in]	Area	Area of interest to be initialized.
[in]	Value	Value for initializing the pixels to.

Returns

true if successful; false otherwise.

IsAll8Bit()

cvbbool_t IsAll8Bit

(

IMG

Image

)

Checks if all the planes in the Image have 8 bits per pixel.

Parameters

[in]

Image

Image object handle of the image to inspect.

Returns

true if all planes have 8 bits per pixel; false otherwise or if the Image is invalid.

See also

CreateGenericImage, CreateGenericImageDT, ImageDatatype

IsAllSameDatatype()

cvbdatatype_t IsAllSameDatatype

(

IMG

Image

)

Checks if all the planes in the Image have identical data types and returns the cvbdatatype_t if it is so.

Parameters

[in]

Image

Image object handle of the image to inspect.

Returns

• if all planes have the same data type, the cvbdatatype_t is returned
• if the planes have different data types, 0 is returned
• if an error occured while reading the image properties a negative value is returned

See also

ImageDatatype

IsFloatDatatype()

cvbbool_t IsFloatDatatype

(

cvbdatatype_t

Datatype

)

Checks if the Datatype describes a floating point number.

The implementation looks like this:

cvbbool_t IsFloatDatatype(cvbdatatype_t Datatype)
{
  return (Datatype & DT_Float) != 0;
}

Parameters

[in]

Datatype

Descriptor to be checked.

Returns

true if DT_Float flag is set; false otherwise.

See also

ImageDatatype

IsOverlayImage()

cvbbool_t IsOverlayImage

(

IMG

Image

)

Checks if any plane of the given Image has DT_Overlay set in its datatype.

Parameters

[in]

Image

Image object handle of the image to inspect.

Returns

true if at least on plane in the Image has the overlay bit set; false otherwise or if the Image is invalid.

See also

CreateOverlayImage, CreateGenericImage, CreateGenericImageDT, ImageDatatype

Deprecated:

Use HasOverlay instead.

IsSignedDatatype()

cvbbool_t IsSignedDatatype

(

cvbdatatype_t

Datatype

)

Checks if the Datatype describes a signed data type.

The implementation looks like this:

cvbbool_t IsSignedDatatype(cvbdatatype_t Datatype)
{
  return (Datatype & DT_Signed) != 0;
}

Attention

The float data types have two possible representations, but are always signed:

• float: DT_Float | DT_Signed | 32
• float: DT_Float | 32
• double: DT_Float | DT_Signed | 64
• double: DT_Float | 64

In the variant without the DT_Signed flag set, this function returns false.

Parameters

[in]

Datatype

Descriptor to be checked.

Returns

true if DT_Signed flag is set; false otherwise.

See also

ImageDatatype

LoadImageFile()

cvbbool_t LoadImageFile	(	const char *	FileName,
		IMG &	ImageOut
	)

Loads an image from a file (ASCII strings).

The type of the file being loaded is determined by the extension of the FileName. But this function will not only load image files like *.bmp, *.mio etc., it can also be used for loading acquisition drivers (file extension .vin), video files (.avi or .mpg) or emulator files (.emu).

This function will not resolve any environment variables contained in the file name (like "%CVB%\Drivers\GenICam.vin"); this can be achieved by using the TranslateFileName function from the CVCUtilities.dll.

Note

The extension must match the actual file contents, otherwise the load fails: this function will not parse the content of the file to be loaded!

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

Parameters

[in]	FileName	Nul-terminated string with the path to the file to be loaded.
[out]	ImageOut	Variable to receive the image handle.

Returns

true if successful; false otherwise.

See also

WriteImageFile, CVCDriver.dll for additional information on driver images.

LoadImageFileW()

cvbbool_t LoadImageFileW	(	const wchar_t *	FileName,
		IMG &	ImageOut
	)

Loads an image from a file (Unicode strings).

The type of the file being loaded is determined by the extension of the FileName. But this function will not only load image files like *.bmp, *.mio etc., it can also be used for loading acquisition drivers (file extension .vin), video files (.avi or .mpg) or emulator files (.emu).

This function will not resolve any environment variables contained in the file name (like "%CVB%\Drivers\GenICam.vin"); this can be achieved by using the TranslateFileName function from the CVCUtilities.dll.

Note

The extension must match the actual file contents, otherwise the load fails: this function will not parse the content of the file to be loaded!

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

Parameters

[in]	FileName	Nul-terminated string with the path to the file to be loaded.
[out]	ImageOut	Variable to receive the image handle.

Returns

true if successful; false otherwise.

See also

WriteImageFile, CVCDriver.dll for additional information on driver images.

Since

CVB 2017 (13.00.000)

MapTo8Bit()

cvbbool_t MapTo8Bit	(	IMG	ImageIn,
		cvbbool_t	OverallNormalization,
		IMG &	ImageOut
	)

Creates a new 8-bit per plane image from ImageIn.

Images with up to 2 BytesPerPixel are supported. 8 bit per plane are simply duplicated via CreateDuplicateImage. On higher bit ImageIn the ImageOut is created via CreateGenericImage.

This function generates a gain factor ranging from zero to the maximum gray value in the image. Each pixel is multiplied by this factor.

Note

As described above the scaling is dynamic and depends on the pixel values if the image has a cvbdatatype_t with more than 8 bits per plane. It does no fixed scaling dependent on the bits per plane!

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

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

Parameters

[in]	ImageIn	Object handle of the source image.
[in]	OverallNormalization	true if the gain factor is calculated over all planes; false if an individual gain factor is calculated for each plane.
[out]	ImageOut	Variable to receive the output image handle.

Returns

true if successful; false otherwise.

MaxImageArea()

cvbbool_t MaxImageArea	(	IMG	Image,
		TArea &	Area
	)

Sets the Area to the full extent of the Image.

Parameters

[in]	Image	Image object handle for which the extent is written to Area.
[out]	Area	Variable to receive the Image extent.

Returns

true if successful; false otherwise.

MemoryToImage()

cvbbool_t MemoryToImage	(	void *	pMem,
		intptr_t	Capacity,
		IMG &	ImageOut
	)

Restores an image object from memory that has been serialized using the function ImageToMemory.

Deserializes the buffer at pMem that has been serialized with ImageToMemory (see ImageToMemory for detailed documentation).

Parameters

[in]	pMem	Pointer to the buffer containing the serialized image.
[in]	Capacity	Size of the buffer at pMem in bytes.
[out]	ImageOut	Variable to receive the handle to the deserialized image object.

Returns

true if successful; false otherwise.

See also

ImageToMemory, ImageToMemorySize

NumPlanesNeededPerImage()

cvbval_t NumPlanesNeededPerImage

(

TColorModel

ColorModel

)

Returns the number of planes which an image should have with the given ColorModel.

Parameters

[in]

ColorModel

Color model for which to find out the number of planes.

Returns

Number of planes an image should have; -1 if an invalid color model identifier was given.

See also

ImageColorModel

PasteClipboardImage()

cvbbool_t PasteClipboardImage	(	HWND	hWnd,
		IMG &	ImageOut
	)

Creates an image object from a compatible image stored in the system clipboard.

If the system clipboard contains an image in a format recognized by Common Vision Blox, the image will be deserialized from the clipboard and put into a new image object. The clipboard formats recognized by Common Vision Blox are "CF_DIB" (device independent bitmap) and "cf_MIO" (custom format used by Common Vision Blox for images with higher bit depths and plane counts. Any other formats will not be recognized by Common Vision Blox.

Attention

This function is only available on the Windows platform.

Parameters

[in]	hWnd	Window handle through which to access the clipboard.
[out]	ImageOut	Variable that receives the handle to the deserialized image.

Returns

true if successful; false otherwise.

See also

CopyImageClipboard

PixVal()

cvbval_t PixVal	(	IMG	Image,
		cvbdim_t	PlaneIndex,
		cvbdim_t	X,
		cvbdim_t	Y
	)

Gets the pixel value of the given Image in the plane specified by PlaneIndex at the location X, Y.

Note

This function only works on Image planes with up to 16 BitsPerPixel and a cvbdatatype_t that is not DT_Signed.

Deprecated:

If really needed use CVB::GetPixVal instead.

Parameters

[in]	Image	Object handle of the image.
[in]	PlaneIndex	Index of plane to access pixel component.
[in]	X	X coordinate of pixel to be accessed.
[in]	Y	Y coordinate of pixel to be accessed.

Returns

Positive value (including 0) of the pixel or a negative error code:

• CVC_ERROR (CVC_E_NOIMAGE): Image was not a valid IImageVPA object.
• CVC_ERROR (CVC_E_PARAMETER): PlaneIndex, X or Y are out of range.
• CVC_ERROR (CVC_E_INVALIDDATATYPE): Image plane at PlaneIndex was not unsigned and/or up to 16 BitsPerPixel.

SetPixel()

cvbbool_t CVB::SetPixel	(	IMG	img,
		cvbval_t	index,
		cvbval_t	x,
		cvbval_t	y,
		cvbval_t &	value
	)

Alias for CVB::SetPixVal.

Deprecated:

This function is deprecated since Common Vision Blox 13.04.000 and has in fact been removed from the C header. Please use CVB::GetPixVal instead.

See also

CVB::SetPixVal.

SetPixVal()

cvbbool_t CVB::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 position X, Y.

Sets the pixel Value at location X, Y independent of the cvbdatatype_t of the Image.

Note

This is the slowest way of accessing image data and has been implemented for the sake of completeness. Using CVCUtility library's GetLinearAccess or GetImageVPA is preferable.

Attention

This function does not work on images having a DT_Float cvbdatatype_t; behavior is undefined!

Parameters

[in]	Image	Object handle of the image to access.
[in]	PlaneIndex	Index of plane to access pixel component.
[in]	X	X coordinate of the pixel.
[in]	Y	Y coordinate of the pixel.
[out]	Value	Pixel value to set.

Returns

true if successful; false otherwise.

See also

GetImageVPA, CVB::GetPixVal.

WriteImageFile()

cvbbool_t WriteImageFile	(	IMG	Image,
		const char *	FileName
	)

Saves the Image to a file using the given FileName (ASCII strings).

The actual format to save the file in is determined by the extension of the FileName. Currently the following formats are supported:

• .bmp - regular Windows Bitmap files
• .mio - Minos Image Objects; CVB's proprietary format
• .jpg - JPEG files (through CVCFile.dll)
• .tif - TIFF files (through CVCFile.dll)
• .png - Portable network graphics (though CVCFile.dll)
• .j2k - JPEG 2000 (through CVCFile.dll)

Attention

Please note that format-specific limitations apply:

Format	Restrictions
bmp	Only images with 1 or 3 planes with 8 bits per pixel (unsigned) may be saved as *.bmp files
mio	The overall file size of a MIO file must not exceed 2 GB. Note that this limit may be hit with much less than 2 GPixels: With 16 bit per pixels and three planes for example, roughly 341 MPixels (roundabout 16k x 20k) are sufficient to generate more than 2 GB of data.
jpg	Image width and height are both restricted to 64k Pixels; currently only images with 1 or 3 planes with 8 bits per pixel (unsigned) may be saved as *.jpg files.
png	The alpha channel of *.png files will be ignored. Loading a *.png file and saving it again will erase the alpha channel data. Only images with 1 or 3 planes with 8 or 16 bits per pixel (unsigned) may be saved as *.png files
j2k	Only images with 1 or 3 planes with 8 to 16 bits per pixel (unsigned) may be saved as *.j2k files

Violation of these restrictions will result in the function return FALSE.

Parameters

[in]	Image	Image object handle of the image to be saved.
[in]	FileName	Nul-terminated string containing file path to save to.

Returns

true if successful; false otherwise.

See also

LoadImageFile, WriteLossyImageFile

WriteImageFileW()

cvbbool_t WriteImageFileW	(	IMG	Image,
		const wchar_t *	FileName
	)

Saves the Image to a file using the given FileName (Unicode strings).

The actual format to save the file in is determined by the extension of the FileName. Currently the following formats are supported:

• .bmp - regular Windows Bitmap files
• .mio - Minos Image Objects; CVB's proprietary format
• .jpg - JPEG files (through CVCFile.dll)
• .tif - TIFF files (through CVCFile.dll)
• .png - Portable network graphics (though CVCFile.dll)
• .j2k - JPEG 2000 (through CVCFile.dll)

Attention

Please note that format-specific limitations apply:

Format	Restrictions
bmp	Only images with 1 or 3 planes with 8 bits per pixel (unsigned) may be saved as *.bmp files
mio	The overall file size of a MIO file must not exceed 2 GB. Note that this limit may be hit with much less than 2 GPixels: With 16 bit per pixels and three planes for example, roughly 341 MPixels (roundabout 16k x 20k) are sufficient to generate more than 2 GB of data.
jpg	Image width and height are both restricted to 64k Pixels; currently only images with 1 or 3 planes with 8 bits per pixel (unsigned) may be saved as *.jpg files.
png	The alpha channel of *.png files will be ignored. Loading a *.png file and saving it again will erase the alpha channel data. Only images with 1 or 3 planes with 8 or 16 bits per pixel (unsigned) may be saved as *.png files
j2k	Only images with 1 or 3 planes with 8 to 16 bits per pixel (unsigned) may be saved as *.j2k files

Violation of these restrictions will result in the function return FALSE.

Parameters

[in]	Image	Image object handle of the image to be saved.
[in]	FileName	Nul-terminated string containing file path to save to.

Returns

true if successful; false otherwise.

See also

LoadImageFile, WriteLossyImageFile

Since

CVB 2017 (13.00.000)

WriteLossyImageFile()

cvbbool_t WriteLossyImageFile	(	IMG	Image,
		double	Quality,
		const char *	FileName
	)

Saves an image under the given FileName using a lossy compression codec (ASCII strings).

Lossy codecs can discard image information for the sake of a higher compression ratio. This usually introduces artifacts into the image.

This function gives control over the trade off between compression ration and image quality specified via the Quality parameter. The value of this parameter ranges between a codec-specific minimum and 1.0. Higher values lead to larger image files containing less artifacts.

Attention

The actual codec for saving an image file is selected based on the extension of the FileName. Therefore the extension should correspond to a lossy image codec, otherwise this function ignores the Quality parameter and the function call will be re-routed to WriteImageFile.

Parameters

[in]	Image	Object handle of the image to be saved.
[in]	Quality	Controls the balance between the quality and the compression ratio. Must be in the range [0...1].
[in]	FileName	Null terminate string containing file path to save save to.

Returns

true if saving was successful, false otherwise.

See also

WriteImageFile, LoadImageFile

WriteLossyImageFileW()

cvbbool_t WriteLossyImageFileW	(	IMG	Image,
		double	Quality,
		const wchar_t *	FileName
	)

Saves an image under the given FileName using a lossy compression codec (Unicode strings).

Lossy codecs can discard image information for the sake of a higher compression ratio. This usually introduces artifacts into the image.

This function gives control over the trade off between compression ration and image quality specified via the Quality parameter. The value of this parameter ranges between a codec-specific minimum and 1.0. Higher values lead to larger image files containing less artifacts.

Attention

The actual codec for saving an image file is selected based on the extension of the FileName. Therefore the extension should correspond to a lossy image codec, otherwise this function ignores the Quality parameter and the function call will be re-routed to WriteImageFile.

Parameters

[in]	Image	Object handle of the image to be saved.
[in]	Quality	Controls the balance between the quality and the compression ratio. Must be in the range [0...1].
[in]	FileName	Null terminate string containing file path to save save to.

Returns

true if saving was successful, false otherwise.

See also

WriteImageFile, LoadImageFile

Since

CVB 2017 (13.00.000)