Reference manual
CvCam
Contents
INTRODUCTION .........................................................................................................................3
COMMON USAGE.......................................................................................................................3
HOWTO:........................................................................................................................................5
B
EGIN WORK WITH CVCAM
...........................................................................................................5
S
ELECT A CAMERA
........................................................................................................................5
S
ET UP CAMERA
(
S
) .......................................................................................................................5
R
ENDER THE VIDEO STREAM
.........................................................................................................5
M
AKE THE SETTINGS ACTIVE
........................................................................................................6
C
ONTROL THE VIDEO
....................................................................................................................6
D
ISPLAY CAMERAS PROPERTY PAGES
...........................................................................................6
P
ROCESS VIDEO FRAMES
...............................................................................................................6
G
ET THE POINTER TO LAST FRAME
................................................................................................6
P
LAY AN AVI FILE AND PROCESS IT
’
S FRAMES IF NEEDED
..............................................................7
W
ORK WITH MULTIPLE CAMERAS UNDER LINUX
...........................................................................7
W
ORK WITH MULTIPLE CAMERAS UNDER
W
INDOWS
....................................................................7
F
INISH WORKING WITH CVCAM
.....................................................................................................8
CVCAM REFERENCE ................................................................................................................9
CVCAM
API ..................................................................................................................................9
cvcamExit ................................................................................................................................9
cvcamGetCamerasCount.........................................................................................................9
cvcamGetProperty...................................................................................................................9
cvcamInit ...............................................................................................................................10
cvcamPause ...........................................................................................................................10
cvcamPlayAVI .......................................................................................................................11
cvcamResume.........................................................................................................................12
cvcamSelectCamera...............................................................................................................12
cvcamSetProperty..................................................................................................................13
cvcamStart .............................................................................................................................13
cvcamStop..............................................................................................................................13
CVCAM
P
ROPERTIES
I
NTERFACE
.................................................................................................14
Introduction
CvCam is a universal cross-platform module for processing video stream from digital
video cameras. It is implemented as a dynamic link library (DLL) for Windows and as a shared
object library (so) for linux systems and provides a simple and convenient Application
Programming Interface (API) for reading and controlling video stream, processing its frames and
rendering the results. CvCam is distributed as a part of Intel’s OpenCV project under the same
license and uses some functionality of the Open Source Computer Vision Library.
Common Usage
The simplest way to use CvCam from a C++ program for a single video source is shown
at the following listing:
#include “cvcam.h”
void callback(IplImage* image);
int main()
{
int ncams = cvcamGetCamerascount( );//returns the number of available cameras in the
//system
cvcamSetProperty(0, CVCAM_PROP_ENABLE, &cvcamone); //Selects the 1-st found
//camera
cvcamSetProperty(0, CVCAM_PROP_RENDER, &cvcamone) //We’ll render stream
//from this source
//here I assume your create a window and store it’s id in MyWin variable.
//MyWin is of type HWND on Windows and Window on linux
cvcamSetProperty(0, CVCAM_PROP_WINDOW, &MyWin); // Selects a window for
//video rendering
cvcamSetProperty(0, CVCAM_PROP_CALLBACK, callback);//this callback will
//process every frame
cvcamInit( );
cvcamStart( );
//Your app is working
cvcamStop( );
cvcamExit( );
return 0;
}
void callback(IplImage* image)//Draws blue horizontal lines across the image
{
IplImage* image1 = image;
int i,j;
assert (image);
for(i=0; i<image1->height; i+=10)
{
for(j=(image1->widthStep)*i; j<(image1->widthStep)*(i+1);
j+=image1->nChannels)
{
image1->imageData[j] = (char)255;
image1->imageData[j+1] = 0;
image1->imageData[j+2] = 0;
}
}
}
The first function to be called is
cvcamGetCamerasCount( );
It prepares library and returns the
number of available cameras at the system. On Linux it’s also important to call it before your
initialize the X window system as it prepares X to work with linux threads. Your can also call
XInitThreads( )
at the beginning of your app instead.
The next step is to choose a camera and set it up.
cvcamSetProperty( int camera, char* property,
void* arg)
can do this for you. See CvCam Properties Interface for complete list of properties
and arguments. The first argument for this function is the number of the camera for which the
property is set, the second is a property’s name and the third is a pointer to some data, which
actual type depends on the property. In the example above we selected a camera and told CvCam
to render it into the window we specified.
The third optional step is frame processing with a callback. You can provide a function,
which will be called on every frame and can change it’s data. It should be of type void and takes
a pointer to a IplImage structure, declared in “ipl.h” header file. This is done by
CVCAM_PROP_CALLBACK
property and the third argument to
cvcamSetProperty
is a pointer to your
callback function;
Next step is calling
cvcamInit( ),
after which everything is ready for streaming;
cvcamStart( )
just starts the stream. It won’t block your app and returns immediately. The
stream continues until
cvcamStop( )
is called.
And the last is
cvcamExit( )
–Frees all resources used by CvCam.
Howto:
Begin work with cvcam
Call
cvcamGetCamerasCount()
. This not only returns the number of cameras in the system,
but also prepares cvcam. Under linux be sure to do this call before initializing X, or to call
XInitThreads()
before it.
Select a camera
You can select single or multiple cameras in 2 ways. The first is using a camera selection
dialog with
cvcamSelectCamera
. See an example below:
//Prototype
/*Pops up a camera(s) selection dialog
Return value - number of cameras selected (0,1 or 2);
Argument: an array of selected cameras numbers
NULL if none selected. Should be released with free() when not needed.
if NULL passed, not used.
*/
CVCAM_API int cvcamSelectCamera(int** out);
FunctionThatSelectsCamera()
{
int* out;
int nselected = cvcamSelectCamera(&out);
if(nselected>0)
printf(“the 1-st selected camera is camera number %d”, out[0]);
if(nselected == 2)
printf(“the 2-nd selected camera is camera number %d”, out[1]);
free(out);
return;
}
Note: if you don’t need selected cameras numbers, simply call
cvcamSelectCamera(NULL)
Note2: Linux version of cvcam currently has no implementation of
cvcamSelectCamera
.
The second, non-dialog way is to use CVCAM_PROP_ENABLE property like this:
int desiredcamera = 0;//for example
cvcamSetProperty(desiredcamera, CVCAM_PROP_ENABLE,CVCAMTRUE);
Set up camera(s)
See CvCam Properties Interface.
Render the video stream
1. Tell cvcam to render your camera:
cvcamSetProperty(YourCamera, CVCAM_PROP_RENDER, CVCAMTRUE)
2. Select the window
cvcamWindow mywin = …;//here I mean your initialize mywin with some
// existing window id/
cvcamSetProperty(YourCamera, CVCAM_PROP_WINDOW, &mywin);