Image Manager (CVCImg.dll) 15.0
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

Numeric data type of a single IImageVPA plane.

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

31-121110987-0
reservedCOFSbits per pixel

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

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:
(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;
}
long cvbdatatype_t
Numeric data type of a single IImageVPA plane.
Definition: CVTypes.h:24
cvbval_t BytesPerPixel(cvbdatatype_t Datatype)
Gets how many bytes per pixel (component) are occupied in memory based on the Datatype descriptor.
Definition: PseudoCOMExports.cpp:667
@ DT_Signed
Signed pixel component.
Definition: CVTypes.h:191
@ DT_Float
Floating point pixel component.
Definition: CVTypes.h:192
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"
);
}
void * IMG
CVB 2D image handle.
Definition: CVTypes.h:95
cvbbool_t WriteImageFile(IMG Image, const char *FileName)
Saves the Image to a file using the given FileName (ASCII strings).
Definition: StreamingExports.cpp:825
cvbbool_t LoadImageFile(const char *FileName, IMG &ImageOut)
Loads an image from a file (ASCII strings).
Definition: StreamingExports.cpp:675
cvbbool_t ReleaseObject(OBJ &Object)
Decrements the reference count of the given InterfaceContainer Object.
Definition: ImageHandlingExports.cpp:676

◆ 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]pBufferBaseBase pointer of the buffer provided to the function CreateImageFromPointer.
[in]pPrivatePrivate data pointer to given to the function CreateImageFromPointer.

Enumeration Type Documentation

◆ 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:
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

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

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

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

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;
}
cvbval_t BitsPerPixel(cvbdatatype_t Datatype)
Gets how many bits per pixel (component) are valid based on the Datatype descriptor.
Definition: PseudoCOMExports.cpp:649
Parameters
[in]DatatypeData 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]DatatypeData 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]ImageInImage handle to copy from.
[in]ImageOutImage handle to copy to.
[in]ImageInPlaneIndexPlane of ImageIn to copy from.
[in]ImageOutPlaneIndexPlane of the ImageOut to copy to.
[in]AreaArea of interest in pixel coordinates in the ImageIn.
[in]ShiftXX offset for pixel coordinates in ImageOut where to copy to.
[in]ShiftYY 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]ImageImage object handle of the image to be copied.
[in]hWndApplication 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]ImageInSource image to copy from.
[in]ImageOutDestination image to copy to.
[in]ImageInPlaneIndexPlane from ImageIn to copy from.
[in]ImageOutPlaneIndexPlane in the ImageOut to copy to.
[in]InLeftNon-negative left edge of the region of interest.
[in]InTopNon-negative top edge of the region of interest.
[in]InRightNon-negative right edge of the region of interest (inclusive).
[in]InBottomNon-negative bottom edge of the region of interest (inclusive).
[in]OutXNon-negative x component in pixel coordinates of point where to copy the data to.
[in]OutYNon-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]ImageInSource image to copy from.
[in]ImageOutDestination image to copy to.
[in]InLeftNon-negative left edge of the region of interest.
[in]InTopNon-negative top edge of the region of interest.
[in]InRightNon-negative right edge of the region of interest (inclusive).
[in]InBottomNon-negative bottom edge of the region of interest (inclusive).
[in]OutXNon-negative X offset in the target image to copy to.
[in]OutYNon-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]ImageInImage used for copying the overlay bits from.
[in]ImageOutImage 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]ImageInImage object handle of the source image.
[in]AreaArea of interest in image coordinates to be copied.
[out]ImageOutVariable 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:

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]ImageInInput image object handle.
[in]OutWidthPositive target width of the destination image; 0 if the width of ImageIn is to be used.
[in]OutHeightPositive target height of the destination image; 0 if the height of ImageIn is to be used.
[in]ForceOverlayBitSet to true to force the overlay capability; use false to use the overlay status of ImageIn.
[out]ImageOutVariable 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]ImageArrayNon-__NULL__ array containing the handles of at least one image to be concatenated.
[in]ArrayLengthNon-zero number of elements in the ImageArray.
[in]ShareMemorytrue only creates a new VPAT and reuses the source image's buffer without copy; false copies all the image data.
[out]ImageOutVariable 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)
// 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
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();
});
imageHandles.data(), // pointer to first element
imageHandles.size(), // number of elements
false, // copy the image data
ReversePlaneImage // result image
))
}
ObjPtr CreateSinglePlaneImage(IMG Image, cvbdim_t Plane)
{
IMG singlePlaneImage = nullptr;
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); });
}
#define CVC_ERROR(a)
Definition: CVCError.h:18
@ CVC_E_WRONGOBJECT
At least one of the input handles points to the wrong type of object.
Definition: CVCError.h:131
@ CVC_E_OK
No Error occurred.
Definition: CVCError.h:58
@ CVC_E_MEMORY
Definition: CVCError.h:73
cvbdim_t ImageDimension(IMG Image)
Gets the number of planes the Image contains.
Definition: PseudoCOMExports.cpp:361
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.
Definition: ImageHandlingExports.cpp:1750
cvbbool_t CreateConcatenatedImage(IMG *ImageArray, size_t ArrayLength, cvbbool_t ShareMemory, IMG &ImageOut)
Concatenates an array of images into a single new one.
Definition: ImageHandlingExports.cpp:867
void * OBJ
CVB reference counted object handle.
Definition: CVTypes.h:96

◆ 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]ImageInSource image.
[out]ImageOutVariable 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]ImageInSource image.
[out]ImageOutVariable 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:
R11G11B11R12G12B12
R9G9B9R10G10B10
R7G7B7R8G8B8
R5G5B5R6G6B6
R3G3B3R4G4B4
R1G1B1R2G2B2
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]NumPlanesNumber of planes to be created.
[in]WidthWidth of the output image to be created.
[in]HeightHeight of the output image to be created.
[in]HasOverlaytrue set the cvbdatatype_t being overlay capable (DT_Overlay); false otherwise.
[out]ImageOutVariable 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:
RRRRRR
RRRRRR
GGGGGG
GGGGGG
BBBBBB
BBBBBB
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]NumPlanesNumber of planes to be created.
[in]WidthPositive width of the output image to be created.
[in]HeightPositive height of the output image to be created.
[in]DataypeData type of the output image's planes.
[out]ImageOutVariable 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);
}
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.
Definition: ImageHandlingExports.cpp:1704
Parameters
[in]ImageInObject handle of the source image.
[in]PlaneIndexFirst plane to omit.
[in]NumPlanesNumber of planes to be omitted.
[in]MapImagetrue to MapImage the pixel buffer instead of copying it into a new buffer (false).
[out]ImageOutVariable 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]pImageMemoryNon-nullptr to the base of the image buffer.
[in]MemorySizeOptional size of the memory buffer in bytes; zero for no validation.
[in]WidthWidth of the image to be created in pixels.
[in]HeightHeight of the image to be created in pixels.
[in]NumPlanesPositive number of planes of the image to be created.
[in]DataTypecvbdatatype_t for all planes of the image to be created.
[in]PitchXDistance in memory in bytes between two horizontally neighboring pixels (position x and position x+1) in the same plane.
[in]PitchYDistance in the memory in bytes between two vertically neighboring pixels (position y and position y+1) in the same plane.
[in]PitchPlaneDistance in the memory in bytes between two equivalent pixels (same x- and y-coordinate) in two consecutive image planes.
[in]PlaneOrderOptional array of size NumPlanes to specify a nonstandard plane order; nullptr for default order.
[in]ReleaseCallbackMandatory callback function pointer that will be called when the reference count of ImageOut reaches zero.
[in]pPrivatePointer which is passed to the ReleaseCallback to store user state like an object pointer.
[out]ImageOutVariable that receives the handle to the newly created image.
Returns
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;
}
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.
Definition: ImageAccessExports.cpp:493
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]Image1Object handle of the first source image.
[in]Image2Object handle of the second source image.
[in]Image1InsertionIndexIndex at which to start inserting the planes from Image2 into the plane sequence of Image1.
[in]MapImagetrue to MapImage the pixel buffer instead of copying it into a new buffer (false).
[in]Intersecttrue to create ImageOut dimension and coordinate system by transforming both; false to simply use dimension and coordinate system of Image1.
[out]ImageOutVariable 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]ImageInHandle to the source image object.
[in]InLeftLeft edge of AOI in the ImageIn.
[in]InTopTop edge of AOI in the ImageIn.
[in]InRightRight edge of AOI in the ImageIn (inclusive).
[in]InBottomBottom edge of AOI in the ImageIn (inclusive).
[in]OutWidthPositive width of the output image to be created.
[in]OutHeightPositive height of the output image to be created.
[out]ImageOutVariable 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));
(
ImageIn,
0, 0, // (left, top) point
width - 1, height - 1, // (right, bottom) point
targetWidth, targetHeight,
ImageOut
);
}
cvbdim_t ImageWidth(IMG Image)
Gets the width of the Image.
Definition: PseudoCOMExports.cpp:387
cvbdim_t ImageHeight(IMG Image)
Gets the height of the Image.
Definition: PseudoCOMExports.cpp:413
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 destin...
Definition: ImageHandlingExports.cpp:2020
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]ImageInObject handle of the source image.
[in]PlaneIndexFirst plane to keep.
[in]NumPlanesNumber of planes to be kept.
[in]MapImagetrue to MapImage the pixel buffer instead of copying it into a new buffer (false).
[out]ImageOutVariable 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]ImageInSource image object handle.
[out]ImageOutVariable 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]ImageInSource image object handle.
[out]ImageOutVariable 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]ImageAFirst input image.
[in]ImageBSecond input image.
[in]PanoramaModeMode to be used when generating the output image.
[out]ImageOutVariable 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]ImageInImage to rotate in right angle (90°) steps.
[in]Rotation Either 90°, 180° or 270° rotation.
[out]ImageOutVariable 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]ImageInImage object handle of the source image.
[in]AreaArea of interest in image coordinates to be copied.
[out]ImageOutVariable 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]DatatypeData type descriptor for which to calculate the values.
[out]MinValMinimum value for pixels of the given Datatype.
[out]MaxValMaximum 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]ImageObject handle of the image to access.
[in]PlaneIndexIndex of plane to access pixel component.
[in]XX coordinate of the pixel.
[in]YY coordinate of the pixel.
[out]ValueVariable 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]ImageImage 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]ImageImage 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))
{
// Error case
break;
case CM_RGB:
// RGB case
break;
case CM_Mono:
// Mono case
break;
// ...
}
TColorModel ImageColorModel(IMG Image)
Returns the color model descriptor for the Image.
Definition: PseudoCOMExports.cpp:947
TColorModel
Color model descriptors.
Definition: CVTypes.h:222
@ CM_RGB
RGB color model.
Definition: CVTypes.h:227
@ CM_Mono
Only intensity information.
Definition: CVTypes.h:226
@ CM_Unknown
Image with no attached descriptor and not CM_Guess_RGB or CM_Guess_Mono.
Definition: CVTypes.h:225
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);
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 > ...
Definition: WindowsOnlyExports.cpp:119
@ DSM_WrapAround
Instead of scaling pixel values > 255 to the range [0 .. 255] simply use the lowest 8 bits of each pi...
Definition: CVTypes.h:277
Attention
This function is only available on Microsoft Windows operating systems.
Parameters
[in]ImageInImage object handle of the source image to be blitted.
[in]hDCWindows device context into which to blit.
[in]hDCLeftLeft edge in the device context where to start blit.
[in]hDCTopTop edge in the device context where to start blit.
[in]InLeftLeft edge of AOI in the ImageIn.
[in]InTopTop edge of AOI in the ImageIn.
[in]InRightRight edge of AOI in the ImageIn (inclusive).
[in]InBottomBottom edge of AOI in the ImageIn (inclusive).
[in]hDCWidthPositive width of the output image to be created.
[in]hDCHeightPositive height of the output image to be created.
[in]RedPlaneIndexPlane index to be used to display as red plane.
[in]GreenPlaneIndexPlane index to be used to display as green plane.
[in]BluePlaneIndexPlane index to be used to display as blue plane.
[in]GainGain to apply before blitting. Will be ignored if the Mode DSM_ViewPort is being used.
[in]OffsetOffset 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]ImageInImage object handle of the source image to be blitted.
[in]hDCWindows device context into which to blit.
[in]hDCLeftLeft edge in the device context where to start blit.
[in]hDCTopTop edge in the device context where to start blit.
[in]InLeftLeft edge of AOI in the ImageIn.
[in]InTopTop edge of AOI in the ImageIn.
[in]InRightRight edge of AOI in the ImageIn (inclusive).
[in]InBottomBottom edge of AOI in the ImageIn (inclusive).
[in]hDCWidthPositive width of the output image to be created.
[in]hDCHeightPositive height of the output image to be created.
[in]RedPlaneIndexPlane index to be used to display as red plane.
[in]GreenPlaneIndexPlane index to be used to display as green plane.
[in]BluePlaneIndexPlane index to be used to display as blue plane.
[in]GainGain to apply before blitting. Will be ignored if the Mode DSM_ViewPort is being used.
[in]OffsetOffset to apply before blitting. Will be ignored if the Mode DSM_ViewPort is being used.
[in]ModeSpecifies 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]ImageImage object handle of the image to be serialized.
[in]pMemPointer to the block of memory to which the image should be serialized.
[in]CapacitySize 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:

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]ImageImage to be copied.
[in]pMemPointer to the memory to copy the Image data to.
[in]CapacityNumber of bytes available at pMem.
[in]LayoutSpecifies 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]ImageImage 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]ImageImage 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]ImageImage object handle to be initialized.
[in]PlaneIndexIndex of plane to be initialized.
[in]AreaArea of interest to be initialized.
[in]ValueValue 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]ImageImage object handle to be initialized.
[in]PlaneIndexIndex of plane to be initialized.
[in]AreaArea of interest to be initialized.
[in]ValueValue 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]ImageImage 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]ImageImage 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;
}
cvbbool_t IsFloatDatatype(cvbdatatype_t Datatype)
Checks if the Datatype describes a floating point number.
Definition: PseudoCOMExports.cpp:853
Parameters
[in]DatatypeDescriptor 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]ImageImage 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;
}
cvbbool_t IsSignedDatatype(cvbdatatype_t Datatype)
Checks if the Datatype describes a signed data type.
Definition: PseudoCOMExports.cpp:829
Attention
The float data types have two possible representations, but are always signed:
In the variant without the DT_Signed flag set, this function returns false.
Parameters
[in]DatatypeDescriptor 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]FileNameNul-terminated string with the path to the file to be loaded.
[out]ImageOutVariable 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]FileNameNul-terminated string with the path to the file to be loaded.
[out]ImageOutVariable 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]ImageInObject handle of the source image.
[in]OverallNormalizationtrue if the gain factor is calculated over all planes; false if an individual gain factor is calculated for each plane.
[out]ImageOutVariable 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]ImageImage object handle for which the extent is written to Area.
[out]AreaVariable 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]pMemPointer to the buffer containing the serialized image.
[in]CapacitySize of the buffer at pMem in bytes.
[out]ImageOutVariable 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]ColorModelColor 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]hWndWindow handle through which to access the clipboard.
[out]ImageOutVariable 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]ImageObject handle of the image.
[in]PlaneIndexIndex of plane to access pixel component.
[in]XX coordinate of pixel to be accessed.
[in]YY coordinate of pixel to be accessed.
Returns
Positive value (including 0) of the pixel or a negative error code:

◆ 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]ImageObject handle of the image to access.
[in]PlaneIndexIndex of plane to access pixel component.
[in]XX coordinate of the pixel.
[in]YY coordinate of the pixel.
[out]ValuePixel 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]ImageImage object handle of the image to be saved.
[in]FileNameNul-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]ImageImage object handle of the image to be saved.
[in]FileNameNul-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]ImageObject handle of the image to be saved.
[in]QualityControls the balance between the quality and the compression ratio. Must be in the range [0...1].
[in]FileNameNull 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]ImageObject handle of the image to be saved.
[in]QualityControls the balance between the quality and the compression ratio. Must be in the range [0...1].
[in]FileNameNull 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)