Contents

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 s ared ob!ect library (so) for linu" systems and provides a simple and convenient #pplication $rogramming Interface (#$I) for reading and controlling video stream% processing its frames and rendering t e results. CvCam is distributed as a part of Intel&s 'penC( pro!ect under t e same license and uses some functionality of t e 'pen )ource Computer (ision Library.

Common Usage
* e simplest way to use CvCam from a C++ program for a single video source is s own at t e following listing,
-include .cvcam. / void callback(IplImage0 image)1 int main() 2 int ncams 3 cvcam4etCamerascount( )155returns t e number of available cameras in t e 55system cvcam)et$roperty(6% C(C#78$9'$8:;#<L:% =cvcamone)1 55)elects t e >-st found 55camera cvcam)et$roperty(6% C(C#78$9'$89:;D:9% =cvcamone) 55We&ll render stream 55from t is source 55 ere I assume your create a window and store it&s id in 7yWin variable. 557yWin is of type ?W;D on Windows and Window on linu" cvcam)et$roperty(6% C(C#78$9'$8WI;D'W% =7yWin)1 55 )elects a window for 55video rendering cvcam)et$roperty(6% C(C#78$9'$8C#LL<#C@% callback)155t is callback will 55process every frame cvcamInit( )1 cvcam)tart( )1 55Aour app is working cvcam)top( )1 cvcam:"it( )1 return 61 B void callback(IplImage0 image)55Draws blue oriContal lines across t e image 2 IplImage0 image> 3 image1 int i%!1 assert (image)1 for(i361 iDimage>-E eig t1 i+3>6) 2 for(!3(image>-Ewidt )tep)0i1 !D(image>-Ewidt )tep)0(i+>)1 !+3image>-EnC annels) 2 image>-EimageDataF!G 3 (c ar)HII1 image>-EimageDataF!+>G 3 61 image>-EimageDataF!+HG 3 61

B B B

* e first function to be called is cvcam4etCamerasCount( )1 It prepares library and returns t e number of available cameras at t e system. 'n Linu" it&s also important to call it before your initialiCe t e J window system as it prepares J to work wit linu" t reads. Aour can also call JInit* reads( ) at t e beginning of your app instead.

* e ne"t step is to c oose a camera and set it up. cvcam)et$roperty( int camera% c ar0 property% can do t is for you. )ee CvCam Properties Interface for complete list of properties and arguments. * e first argument for t is function is t e number of t e camera for w ic t e property is set% t e second is a property&s name and t e t ird is a pointer to some data% w ic actual type depends on t e property. In t e e"ample above we selected a camera and told CvCam to render it into t e window we specified.
void0 arg)

* e t ird optional step is frame processing wit a callback. Aou can provide a function% w ic will be called on every frame and can c ange it&s data. It s ould be of type void and takes a pointer to a IplImage structure% declared in .ipl. / eader file. * is is done by C(C#78$9'$8C#LL<#C@ property and t e t ird argument to cvcam)et$roperty is a pointer to your callback function1 ;e"t step is calling cvcamInit( )% after w ic everyt ing is ready for streaming1
cvcam)tart( ) !ust starts t e stream. It won&t block your app and returns immediately. * e stream continues until cvcam)top( ) is called.

#nd t e last is cvcam:"it( ) KLrees all resources used by CvCam.

Howto:
Begin work with cvcam
Call cvcam4etCamerasCount(). * is not only returns t e number of cameras in t e system% but also prepares cvcam. Mnder linu" be sure to do t is call before initialiCing J% or to call JInit* reads() before it.

Select a camera
Aou can select single or multiple cameras in H ways. * e first is using a camera selection dialog wit cvcam)electCamera. )ee an e"ample below, 55$rototype
50$ops up a camera(s) selection dialog 9eturn value - number of cameras selected (6%> or H)1 #rgument, an array of selected cameras numbers ;MLL if none selected. ) ould be released wit free() w en not needed. if ;MLL passed% not used. 05 C(C#78#$I int cvcam)electCamera(int00 out)1 Lunction* at)electsCamera() 2 int0 out1 int nselected 3 cvcam)electCamera(=out)1 if(nselectedE6) printf(.t e >-st selected camera is camera number Nd/% outF6G)1 if(nselected 33 H) printf(.t e H-nd selected camera is camera number Nd/% outF>G)1 free(out)1 return1

;ote, if you don&t need selected cameras numbers% simply call cvcam)electCamera(;MLL) ;oteH, Linu" version of cvcam currently as no implementation of cvcam)electCamera. * e second% non-dialog way is to use C(C#78$9'$8:;#<L: property like t is,
int desiredcamera 3 6155for e"ample cvcam)et$roperty(desiredcamera% C(C#78$9'$8:;#<L:%C(C#7*9M:)1

Set up camera(s)
)ee CvCam Properties Interface.

Render the video stream

>. *ell cvcam to render your camera,
cvcam)et$roperty(AourCamera% C(C#78$9'$89:;D:9% C(C#7*9M:)

H. )elect t e window
cvcamWindow mywin 3 O155 ere I mean your initialiCe mywin wit some 55 e"isting window id5 cvcam)et$roperty(AourCamera% C(C#78$9'$8WI;D'W% =mywin)1

P.)et output widt and eig t of t e video.

int widt 3 PH61 int eig t 3 HQ61 cvcam)et$roperty(AourCamera% C(C#78$9'$89;DWID*?% =widt )1 cvcam)et$roperty(AourCamera% C(C#78$9'$89;D?:I4?*% = eig t)1

;ote, if your pass ;MLL as a window% or don&t set it% it&ll be created under Windows systems ;ote H, If you don&t set widt and eig t t ose of t e source are used. ;ote P , cvcamWindow as type ?W;D under Windows and type Window under linu".

Make the settings active

Call cvcamInit()1

Control the video

Call cvcam)tart()1
cvcam)top()1 cvcam$ause()1 cvcam9esume()1

* ey take no arguments and return 6 on success.

ispla! cameras propert! pages

*o display t e property page for camera AourCamera call
cvcam4et$roperty(AourCamera% C(C#78C#7:9#$9'$)% ;MLL)1

*o display t e video format property page for t e same camera call

cvcam4et$roperty(AourCamera% C(C#78(ID:'L'97#*% ;MLL)1

;ote, a camera may ave no one or bot property pages under Windows and t e content of t e pages depends on t e particular driver. ;oteH, $roperty pages are displayed only for enabled camera(s) and after a call to cvcamInit() under Windows.

"rocess video #rames

Aou can set your own callback function% w ic will process every captured frame and c ange it&s data. It can be done wit C(C#78$9'$8C#LL<#C@ property.
void callback(IplImage0 image) 2 55Do everyt ing you want wit t e image B cvcam)et$roperty(6% C(C#78$9'$8C#LL<#C@% callback)

;ote,under linu" callback currently is called on every frame being rendered or got wit .raw8image/ property. Mnder windows Kon every frame captured.

$et the pointer to last #rame

55:"ample for camera 6
IplImage0 image1 Cvcam$ause()1 cvcam4et$roperty(6%/raw8image/%=image) 55Do w at you want wit t e image cvcam9esume()1

;ote, you don&t need to free t e data pointed to by image. ;oteH, Aou s ould use cvcam$ause and cvcam9esume to prevent c anges of t e data. ;oteP. * is isn&t currently implemented under Windows

"la! an avi #ile and process it%s #rames i# needed

Mse cvcam$lay#(I( const c ar0 file%
void0 window% int widt % int eig t% void0 callback)

* e default call cvcam$lay#(I(6%6%6%6%6) opens an .open file/ dialog and if a file was c osen creates a video window and plays t e file into it wit out any procession. If an e"isting file name is passed as a first argument t is file is played. * e second argument is a window id to play video into it (?W;D or Window depending on platform) Widt and ?eig t specify t e siCe of t e output video window. If 6 passed% t ose t at are set in t e file are used. Callback is Ruiet as for processing video from camera K void callback(IplImage0 image). Example(C++ for Windows ):
e"tern SCS 2 -include S ig gui. S B int main() 2 c ar0 filename 3 .C,Tcartoon.avi/1 named8window(Scvcam windowS% 6)1 ?W;D mywin 3 get8 wnd8byname(Scvcam windowS)1 cvcam$lay#(I( filename% mywin% PH6% HQ6% mycallback)1 return 61 B void mycallback(IplImage0 img) 55$aints top alf of image black 2 memset(img-EimageData% 6% img-Eimage)iCe5H)1 B

;ote, * is function blocks t e calling t read until t e file finis es playing. ;ote, t is function isn&t implemented under Linu" yet.

&ork with multiple cameras under linu'

)electing multiple cameras under linu" wit setting C(C#78$9'$8:;#<L: property will make t em all to work independently

&ork with multiple cameras under &indows

:nabling two cameras under Windows results in activating cv)yncLilter% w ic sync roniCes t e streams and enables setting stereo callback for H sync ronous frames. )et it as below,
void stereocallback(IplImage0 image>% IplImage0 imageH)1 cvcam)et$roperty(6% C(C#78)*:9:'8C#LL<#C@ % stereocallback)1 ;ote, single callbacks for eac camera are not active in t is mode currently1

(inish working with cvcam

Call cvcam:"it()1

Cvcam Re#erence
cvcam )"I
cvcamExit
Declaration,
int cvcam:"it()1

$arameters, ;one. 9eturn (alue, #lways 6. 9emarks, Lrees all resources% used by cvcam.

cvcamGetCamerasCount
Declaration,
int cvcam4etCamerasCount()1

$arameters, ;one. 9eturn (alue, ;umber of found cameras. 9emarks, * e first procedure to call in most every cvcam based program. InitialiCes t e cvcam library. Mnder linu" initialiCes J window system to work wit multiple t reads also.

cvcamGetProperty
Declaration,
cvcam4et$roperty(int camera% const c ar0 property% void0 value)1

$arameters,

int camera (in) K a number of t e camera in 6-based inde" of cameras found in t e system. const c ar0 property (in) K a name of t e property ()ee cvcam $roperties Interface for details). void0 value (out) K depends on t e property&s name. ()ee cvcam $roperties Interface for details).

9eturn (alue, 6 on success% negative error code for error. 9emarks, If successful% value will contain t e value of t e specified property for t e specified camera. ()ee cvcam $roperties Interface for details).

cvcamInit
Declaration,
int cvcamInit()1

$arameters, ;one. 9eturn (alue, > on success% 6 on error. 9emarks, * is function makes t e settings% set by cvcam)et$roperty active and does t e final step of cvcam initialiCation. Don&t be confused K it&s not t e first function% you call. It assumes t at cvcam4etCamerasCount as already been called and usually t at some properties ave been set.

cvcamPause
Declaration,
int cvcam$ause()1

$arameters, ;one. 9eturn (alue, #lways 6. 9emarks, Uust pauses t e video stream if it is running.

cvcamPlayAVI
Declaration,
int cvcam$lay#(I(const c ar0 file% void0 window% int widt % int eig t% void0 callback)

$arameters, const c ar0 file (in) K t e name of an e"isting file on disk or ;MLL . void0 window (in) K an e"isting ?W;D (Windows systems) or Window(Linu" systems) or ;MLL. int width (in) K widt of t e displayed video1 int height (in) K eig t of t e displayed video1 void0 callbac (in) K a pointer to a callback function void callback(IplImage0 img)% w ic will process every frame before displaying it. 9eturn (alue, 6 on success% -> on eror. 9emarks, $lays t e file of type .avi into a specified window. * e output video siCe is set to width " height. :very frame is processed wit a callbac before displaying. If t e file parameter is ;MLL% t e .file open/ dialog is displayed. If t e window is ;MLL it&ll be created. If width or height is 6% it is set to t e siCe specified inside t e avi file being played. If callbac is ;MLL t e frames won&t be processed% !ust displayed as is. Aou can also define your callback function void callback(IplImage0 img) and pass a pointer to it as a callbac parameter. It will be called before displaying eac frame wit t e img parameter containing t e data of frame going to be displayed. IplImage structure is declared in .ipl. /% w ic is included from .cv. / as follows,

typedef struct 8IplImage 2 int n)iCe1 50 siCe of iplImage struct 05 int ID1 50 version 05 int nC annels1 int alp aC annel1 int dept 1 50 pi"el dept in bits 05 c ar color7odelFQG1 c ar c annel)eRFQG1 int data'rder1 int origin1 int align1 50 Q or V byte align 05 int widt 1 int eig t1 struct 8Ipl9'I 0roi1 struct 8IplImage 0mask9'I1 50 poiner to mask9'I if any 05 void 0imageId1 50 use of t e application 05 struct 8Ipl*ileInfo 0tileInfo1 50 contains information on tiling 05 int image)iCe1 50 useful siCe in bytes 05 c ar 0imageData1 50 pointer to aligned image 05 int widt )tep1 50 siCe of aligned line in bytes 05 int <order7odeFQG1 50 05 int <orderConstFQG1 50 05 c ar 0imageData'rigin1 50 ptr to full% nonaligned image 05 B IplImage1

* is function blocks t e calling t read until t e file finis es or error occurs and t en returns.

cvcam!esume
Declaration,
int cvcam9esume()1

$arameters, ;one. 9eturn (alue, #lways 6. 9emarks, 9esumes t e video if it is paused.

cvcam"electCamera
Declaration,
int cvcam)electCamera(int00 out)1

$arameters, int00 out (out) K an address of a pointer to int or ;MLL If not ;MLL will contain an array of selected cameras inde"es. 9eturn (alue, * e number of selected cameras K 6% > or H. 9emarks, * is function pops up a dialog bo"% w ic suggests to select one or H cameras to work wit . If out is not ;MLL% and user as selected some camera(s)% t e array of t eir inde"es is placed into 0out. Mse free() to release t is array after you don&t need it more.

cvcam"etProperty
Declaration,
int cvcam)et$roperty(int camera% const c ar0 property% void0 value)1

$arameters, int camera (in) K a number of t e camera in 6-based inde" of cameras found in t e system. const c ar0 property (in) K a name of t e property ()ee cvcam $roperties Interface for details). void0 value (in) K depends on t e property&s name. ()ee cvcam $roperties Interface for details). 9eturn (alue, 6 on success% negative error code for error. 9emarks, )ets t e value of t e specified property of t e specified camera to value. ()ee $roperties Interface for details). cvcam

cvcam"tart
Declaration,
int cvcam)tart()1

$arameters, ;one.

9eturn (alue, 6 on success% -> on failure. 9emarks, )tarts t e video stream for all enabled cameras.

cvcam"top
Declaration,
int cvcam)top()1

$arameters, ;one. 9eturn (alue, #lways 6. 9emarks, )tops t e video stream.

cvcam "roperties Inter#ace

* ere is a list of properties w ic can be set for eac camera. * ere are H functions to work wit t em,
cvcam4et$roperty(int camerainde"% const c ar0 property% void0 value)1 cvcam)et$roperty(int camerainde"% const c ar0 property% void0 value)1

* e first argument is t e number t at identifies t e camera% t e second is t e name of t e property. * e actual type of t e P-rd argument depends on t e property. )ome of t e properties can be set and got% some only set or only got. )ee t e table below for detailes $roperty name
C(C#78$9'$8:;#<L:

#ction )elects5deselects t e camera 9enders t e cam

argument C(C#7*9M:5 C(C#7L#L): Lor )et% pointer to int for 4et C(C#7*9M:5 C(C#7L#L): Lor )et% pointer to int for 4et $ointer to ?W;D(Win)

Can be get5set )4

$latform Win5Lin WL

C(C#78$9'$89:;D:9

)4

WL

C(C#78$9'$8WI;D'W

)elects a window

)4

WL

C(C#78$9'$8C#LL<#C@

C(C#78D:)C9I$*I';

for rendering camera&s stream )ets a callback function w ic processes every frame 4ets string name and some ot er info about t e camera Displays videoformat dialog bo" for t e camera Displays camera properties dialog bo" for t e camera )ets t e widt of t e output video )ets t e eig t of t e output video )ets t e callback w ic will be called on every two sync ronous frames from H cameras 4ets t e last frame )ets video format in non-dialog way

or pointer to Window(Lin) void (0callback) (IplImage0 image) # pointer to struct

CameraDescription Mnder windows only DeviceDescription field is active

WL

WL

C(C#78(ID:'L'97#*

;MLL ;MLL $ointer to int containing widt $ointer to int containing eig t (oid (0callback) (IplImage0 Image>% IplImage0 imageH)

4 4 )4 )4 )

WL WL WL WL W

C(C#78C#7:9#$9'$)

C(C#789;DWID*? C(C#789;D?:I4?* C(C#78)*:9:'8C#LL<#C @

C(C#78$9'$89#W C(C#78$9'$8):*L'97#*

IplImage00 # pointer to struct videoformat.Lor )et s ould be initialiCed wit desired values

4 )4

L L