Methods

Functions
void	AboutBox ()
	Displays the About box of the Common Vision Image Control.
boolean	Clear (long Plane, double Value)
	Sets the specified image plane to the required initial gray scale value. More...
boolean	CopyImageToClipboard ()
	Copies any image that is present to the Windows clipboard. More...
boolean	CreateEmptyImage (long Dimension, long Width, long Height, boolean ForceOverlay)
	Creates a new, empty image. More...
long	DataType (long Plane)
	Returns the data type of a specified plane of the image. More...
boolean	GetGrab2Status (Grab2InfoType Grab2InfoType, double *Grab2Info)
	Returns status information of the IGrab2 inteface of the underlying driver image. More...
boolean	LoadImage (BSTR Filename)
	Loads an image from a file using the given name. More...
boolean	LoadImageByDialog ()
	Loads an image from a file using the given file name. More...
boolean	LoadImageByUserDialog (BSTR DefaultPath, BSTR Titel, BSTR Filter)
	Loads an image from a file using the Windows common dialog box to open files. More...
boolean	PasteImageFromClipboard ()
	If the Windows clipboard contains an image it will be pasted. More...
boolean	SaveImage (BSTR Filename)
	Saves an image to a file using the given file name. This method has the same effect as a change to the Filename property. The CVCError event is triggered if an error occurs. More...
boolean	SaveImageByDialog ()
	Saves an image to a file using the options of a dialog box. More...
boolean	SaveImageByUserDialog (BSTR DefaultPath, BSTR Titel, BSTR Filter)
	Saves an image to a file using the options of a dialog box. More...
boolean	SaveLossyImage (BSTR Filename, double Quality)
	Saves an image to a file using the given file name, applying a lossy compression codec. More...
boolean	ScanImage (long Density, boolean UseCS)
	Scans the image in a defined area. More...
boolean	ScanPlane (long Plane, long Density, boolean UseCS)
	Scans the image in a defined area in a specified plane. More...
boolean	Snap ()
	Acquires an individual image from the camera. More...

Detailed Description

Function Documentation

Clear()

boolean Clear	(	long	Plane,
		double	Value
	)

Sets the specified image plane to the required initial gray scale value.

The gray scale value is passed as Double to ensure that different data types of the image can be supported.

Attention

8-bit and 16-bit images are supported at present.

Parameters

[in]	Plane	Index of the plane to be initialized. Index ranges between zero and image dimension.
[in]	Value	Gray scale value for image data (e.g. 0..255 for an 8-bit image).

Returns

TRUE if successful, FALSE otherwise.

Examples:

Visual Basic - VB Fileformats Example

CopyImageToClipboard()

boolean CopyImageToClipboard

(

)

Copies any image that is present to the Windows clipboard.

Returns

TRUE if copying was successful, FALSE otherwise.

CreateEmptyImage()

boolean CreateEmptyImage	(	long	Dimension,
		long	Width,
		long	Height,
		boolean	ForceOverlay
	)

Creates a new, empty image.

Parameters

[in]	Dimension	Dimension of the image to be created.
[in]	Width	Widht of the image to be created.
[in]	Height	Height of the image to be created.
[in]	ForceOverlay	TRUE specifies that a overlay-capable image is created, FALSE otherwise.

Returns

TRUE if creation was successful, otherwise FALSE.

DataType()

long DataType

(

long

Plane

)

Returns the data type of a specified plane of the image.

The data type has following individual bits:

31	...	10	9	8	7	6	5	4	3	2	1	0
Reserved		O	F	S	Bits/pixel

Where S = Signed, F = Float (only for 32 or 64 bits/pixel) and O = Overlay bit

Examples for data types:

• An 8-bit unsigned image has a data type of 8.
• A signed 32-bit image has 32 + 256.
• A double image has 64 + 512.
• The data type for a 24-bit RGB image is 8 and NOT 24, because the number of bits/pixel relates only to a plane of the image.

Parameters

[in]

Plane

Index of the plane of the source image. Index ranges between zero and image dimension.

Returns

Datatyp of plane, -1 otherwise.

GetGrab2Status()

boolean GetGrab2Status	(	Grab2InfoType	Grab2InfoType,
		double *	Grab2Info
	)

Returns status information of the IGrab2 inteface of the underlying driver image.

Attention

This function works correct if the driver image supports the IGrab2 interface and if this interface is used for acquisition.

Parameters

[in]	Grab2InfoType	Information you want querry. For information you might request see Grab2InfoType.
[out]	Grab2Info	Requested information as return value.

Returns

TRUE if successful, otherwise FALSE.

Examples:

Delphi - Delphi RingBuffer Example
Visual Basic - VB RingBuffer Examples
Visual C++ - VC RingBuffer Example

LoadImage()

boolean LoadImage

(

BSTR

Filename

)

Loads an image from a file using the given name.

It is possible to load CVB VIN-drivers for the supported image acquisition devices like framegrabbers, cameras or other devices. This method has the same effect as a change to the Filename property. The CVCError event is triggered if an error occurs.

Attention

Check first the supported image formats.
Since CVB version 9.0 it is possible to include enviroment variables in the path. Use the environment variables enclosed in % signs as they are used in the command prompt (e.g. cvb%\Tutorial\Clara.bmp).

Parameters

[in]

Filename

Entire path of the file.

Returns

TRUE if loading was successful, otherwise FALSE.

Examples:

Visual Basic - VB Fileformats Example

LoadImageByDialog()

boolean LoadImageByDialog

(

)

Loads an image from a file using the given file name.

This includes also loading CVB vin-drivers for the supported image acquistion devices like frame grabbers, cameras or other devices.

Returns

TRUE if loading was successful, FALSE otherwise.

Examples:

Delphi - Delphi Display Example
Visual Basic - VB Fileformats Example
Visual C++ - VC Sizeable Display Example

LoadImageByUserDialog()

boolean LoadImageByUserDialog	(	BSTR	DefaultPath,
		BSTR	Titel,
		BSTR	Filter
	)

Loads an image from a file using the Windows common dialog box to open files.

The user can change the appearance of the dialog box.
It is possible to load CVB VIN-drivers for the supported image acquisition devices like framegrabbers, cameras or other devices.
This method has the same effect as a change to the Filename property. The CVCError event is triggered if an error occurs.

Attention

Check first the supported image formats.

Parameters

[in]	DefaultPath	The default path of the dialog box. In case of NULL the current path will be taken.
[in]	Titel	Title of the dialog box.
[in]	Filter	A valid filter string (refer to Windows documentation on FileDialog), e.g. "CVC Drivers (*.vin)|*.vin".

Returns

TRUE if image was loaded successfully, otherwise FALSE (e.g. if the dialog box was closed with cancel).

Visual Basic Test Code:

The following example shows a user-defined File Open dialog.

 Private Sub bOpen_Click()
Dim Dummy As Integer
' load image via dialog
Dummy = Img.LoadImageByUserDialog("", "Load CVC Driver", "CVC Drivers (*.vin)|*.vin")
End Sub

Examples:

Visual Basic - VB Fileformats Example

PasteImageFromClipboard()

boolean PasteImageFromClipboard

(

)

If the Windows clipboard contains an image it will be pasted.

Returns

TRUE if pasting was successful, FALSE otherwise.

SaveImage()

boolean SaveImage

(

BSTR

Filename

)

Saves an image to a file using the given file name. This method has the same effect as a change to the Filename property. The CVCError event is triggered if an error occurs.

Parameters

[in]

Filename

Entire path of the file.

Returns

TRUE if saving was successful, FALSE otherwise.

SaveImageByDialog()

boolean SaveImageByDialog

(

)

Saves an image to a file using the options of a dialog box.

This method has the same effect as a change to the Filename property. The CVCError event is triggered if an error occurs.

Attention

It is not necessary to explicity enter the file name in this function like in SaveImage. Check first the supported image formats.

Returns

TRUE if saving was successful, FALSE otherwise.

SaveImageByUserDialog()

boolean SaveImageByUserDialog	(	BSTR	DefaultPath,
		BSTR	Titel,
		BSTR	Filter
	)

Saves an image to a file using the options of a dialog box.

It is possible to change the appearance of teh dialog box.

Parameters

[in]	DefaultPath	The default path of the dialog box. In case of NULL the current path will be taken.
[in]	Titel	Title of the dialog box.
[in]	Filter	A valid filter string (refer to Windows documentation on FileDialog), e.g. "CVC Drivers (*.vin)|*.vin".

Returns

TRUE if saving was successful, otherwise FALSE.

Visual Basic Test Code:

The following example shows a user-defined File Save dialog.

 Private Sub bSave_Click() 
Dim Dummy As Integer ' save image via dialog
Dummy = Img.SaveImageByUserDialog("", "Save Image ", "CVC Image Format (*.mio)|*.mio")
End Sub

SaveLossyImage()

boolean SaveLossyImage	(	BSTR	Filename,
		double	Quality
	)

Saves an image to a file using the given file name, applying a lossy compression codec.

Lossy codecs drop image information for the sake of a higher compression ratio. This generally introduces artifacts into the image. The WriteLossyImageFile gives control over the tradeoff between compression ratio and image quality by means of the Quality parameter.

Attention

The codec for saving an image file is selected based on the extension of the filename. When calling this function you should supply a filename with an extension that corresponds to a lossy image codec.
If you specify a lossless codec, the Quality paramter is ignored and the function call will be re-routed to WriteImageFile.

Parameters

[in]	Filename	Entire path of the file to save.
[in]	Quality	Controls the balance between the quality and the compression ratio. The value ranges from a codec-specific minimum and 1.0. Higher values leading to image files that are bigger and contain less artifacts.

Returns

TRUE if saving was successful, otherwise FALSE.

ScanImage()

boolean ScanImage	(	long	Density,
		boolean	UseCS
	)

Scans the image in a defined area.

The image data can be accessed easily with this function (especially using Visual Basic). An event is gernerated for each pixel. This event returns the reference of the pixel and allows the user to modify the pixel value (refer to StartOfLine, EndOfLine and NextPixel events).

Attention

This method works on 8 Bit images.

Parameters

[in]	Density	Defines the scan density. The density is between zero and 1000.
[in]	UseCS	The defined coordinate system will be used if UseCs is TRUE. Otherwise the area of interest relates to the left, upper corner of the image.

Returns

TRUE if succeeded, otherwise FALSE.

Visual Basic Test Code:

 Private Sub Scan_Click()
bCancel = False CVImage1.ScanImage 1000, True
CVDisplay1.Refresh
End Sub
 
Sub Private Sub CVImage1_EndOfLine(ByVal LinesToDo As Long, Cancel As Boolean) 
LinesLeft = LinesToDo
End Sub Private
 
Private Sub CVImage1_NextPixel(ByVal Plane As Long, ByVal x As Long, ByVal y As Long, Value As Long, Cancel As Boolean) 
Value = Value And 129 
DoEvents
Cancel = bCancel
End Sub

ScanPlane()

boolean ScanPlane	(	long	Plane,
		long	Density,
		boolean	UseCS
	)

Scans the image in a defined area in a specified plane.

The image data can be accessed easily with this function (especially using Visual Basic). An event is gernerated for each pixel. This event returns the reference of the pixel and allows the user to modify the pixel value (refer to StartOfLine, EndOfLine and NextPixel events).

Attention

This method works on 8 Bit images.

Parameters

[in]	Plane	Defines the disired plane. The index of the plane have to be between zero and the image dimension.
[in]	Density	Defines the scan density. The density is between zero and 1000.
[in]	UseCS	The defined coordinate system will be used if UseCs is TRUE. Otherwise the area of interest relates to the left, upper corner of the image.

Returns

TRUE if succeeded, otherwise FALSE.

Visual Basic Test Code:

 Private Sub Scan_Click()
bCancel = False CVImage1.ScanPlane 0, 1000, True
CVDisplay1.Refresh
End Sub
 
Sub Private Sub CVImage1_EndOfLine(ByVal LinesToDo As Long, Cancel As Boolean) 
LinesLeft = LinesToDo
End Sub Private
 
Private Sub CVImage1_NextPixel(ByVal Plane As Long, ByVal x As Long, ByVal y As Long, Value As Long, Cancel As Boolean) 
Value = Value And 129 
DoEvents
Cancel = bCancel
End Sub

Snap()

boolean Snap

(

)

Acquires an individual image from the camera.

Attention

If the Grab property is TRUE, the value is reset to FALSE. The function returns after acquiring the image. A sequence of Snapcalls cannot generally replace live image acquisition. For live image acquisition please use the Grab property.

Returns

TRUE if acquisition was successful, otherwise FALSE or when an error occured during acquisition.

Related Topics:

Grab

Examples:

Delphi - Delphi Image Access Example
Visual Basic - VB Fileformats Example
Visual C++ - VC Sizeable Display Example