git.maemo.org Git - opencv/blob - docs/faq.htm

   1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0//EN">
   2 <html><head>
   3 <title>OpenCV Documentation (draft)</title>
   4 </head><body>
   5
   6 <center><table cellspacing=0 cellpadding=5 width="90%" bgcolor="#6a9bed" nosave >
   7 <tr nosave>
   8 <td nosave>
   9 <center><i><font color="#000000"><font size=+4>
  10 Frequently Asked Questions / Troubleshootings / HOWTOs
  11 </font></font></i></center>
  12 </td>
  13 </tr>
  14 </table></center>
  15
  16 <h1>General Questions</h1>
  17
  18 <hr><h3>How to install OpenCV properly?</h3>
  19 <p>Read <a href="../INSTALL">installation guide</a>
  20
  21 <hr><h3>How can I get acquainted with OpenCV fast?</h3>
  22 <p>
  23 <ol><li>Look at <a href="../samples/c/">samples</a>.
  24 <li>Within Visual Studio you may load <a href="../_make/">OpenCV workspace</a>:
  25 <ul>
  26 <li>opencv.dsw for Microsoft Visual Studio 6.0
  27 <li>opencv.sln for Microsoft Visual Studio .NET 2003
  28 <li>cbuilderx/opencv.bpgr for Borland C++ BuilderX
  29 </ul>
  30 select <code>cvsample</code> project, build it and run. Look into the code
  31 and modify it as you wish.
  32 <li>Also, scan through <a href="index.htm#ref">reference manuals</a> - they contain some example code as well.
  33 <li>Search OpenCV archives at <a href="http://groups.yahoo.com/group/OpenCV">http://groups.yahoo.com/group/OpenCV</a>
  34 for the topic you are interesting in.
  35 <li>Create a new project <a href="#devstudio_project">from scratch</a>
  36 or modify existing <code>cvsample</code>.
  37 There are application wizards for Microsoft Visual Studio that create OpenCV-aware projects;
  38 look for them at <a href="http://groups.yahoo.com/group/OpenCV">http://groups.yahoo.com/group/OpenCV</a>
  39 (Files section - you have to be registered OpenCV@yahoogroups.com user)
  40 </ol>
  41 </p>
  42
  43 <hr><h3>Where do I submit Bug reports for the computer vision library?</h3>
  44 <p>Send email to <a href="mailto:OpenCV@yahoogroups.com">OpenCV@yahoogroups.com</a>&nbsp;
  45 Subject: BUG &lt;....your title...&gt;</p>
  46
  47 <hr><h3>How do I send bug reports on the Intel® Integrated Performance Primitives</h3>
  48 <p>Send email to <a href="mailto:developer_support@intel.com">developer_support@intel.com</a></p>
  49
  50 <hr><h3>How do I join the OpenCV forum?</h3>
  51 <p>Send email to <a href="mailto:OpenCV-subscribe@yahoogroups.com">OpenCV-subscribe@yahoogroups.com</a>,
  52 after you are a member and select your login, you can read the web group at
  53 <a href="http://groups.yahoo.com/group/OpenCV">http://groups.yahoo.com/group/OpenCV</a></p>
  54
  55 <hr><h3>How do I modify the web group so that I don't receive tons of email's?</h3>
  56 <p>To get the messages real time, or once a day as a daily digest,
  57 you can go to <a href="http://groups.yahoo.com/mygroups" target="_top">http://groups.yahoo.com/mygroups</a>
  58 and choose your setting from the pull down list to the right of OpenCV.;</p>
  59
  60 <hr><h3>Ok, I found the group completely useless for me. How can I unsubscribe?</h3>
  61 <p>Mail to <a href="mailto:OpenCV-unsubscribe@yahoogroups.com">OpenCV-unsubscribe@yahoogroups.com</a>
  62 with subject <b>[OpenCV]</b> and arbitrary message contents.</p>
  63
  64 <hr><h3>When using OpenCV and IPL simultaneously, I get compiler errors. How to resolve this problem?</h3>
  65 <p>To be completely independent from IPL, OpenCV duplicates declarations of IplImage
  66 and few other structures and constants if it is not told explicitly that IPL is present.
  67 Defining HAVE_IPL before including OpenCV headers or putting "#include &lt;ipl.h&gt;"
  68 before OpenCV headers resolves the conflict.</p>
  69
  70 <hr><h3>Does OpenCV work on other processors?</h3>
  71 <p>Yes, OpenCV itself is open source and it is quite portable, especially across
  72 32-bit platforms. On the other hand, OpenCV can run much faster on Intel processors
  73 because of <a href="index.htm#ipp">IPP</a>.
  74
  75
  76 <hr><h1>Windows&reg; OS related Qs:</h1>
  77
  78 <hr><h3>When I try to build one of the
  79 apps, I get an error, streams.h not found.</h3>
  80 <p>You need install and setup DirectShow SDK that is now a part of Platform SDK
  81 (Windows Server 2003 SP1 SDK or later).
  82 Here is the procedure:
  83 <ol>
  84 <li>Download the Platform SDK from
  85    <a href="http://www.microsoft.com/msdownload/platformsdk/sdkupdate/">
  86     http://www.microsoft.com/msdownload/platformsdk/sdkupdate/</a><br>
  87    and DirectX SDK from <a href="http://msdn.microsoft.com/directx/">
  88    http://msdn.microsoft.com/directx/</a>
  89    (They are huge, but you can download and install them by parts).<br>
  90    If it doesn't work for you, consider HighGUI that can capture video via VFW or MIL
  91
  92 <li>Install Platform SDK <em>together</em> with DirectShow SDK.<br>
  93    Install DirectX SDK (with or without sample code).
  94
  95 <li>Build baseclasses.
  96    See &lt;PlatformSDKInstallFolder&gt;\samples\multimedia\directshow\readme.txt.
  97
  98 <li>Copy the built libraries (called strmbase.lib and strmbasd.lib
  99    in Release and Debug versions, respectively) to
 100    &lt;PlatformSDKInstallFolder&gt;\lib.
 101
 102 <li>In Developer Studio add the following paths:<br>
 103       &lt;DirectXSDKInstallFolder&gt;\include<br>
 104       &lt;PlatformSDKInstallFolder&gt;\include<br>
 105       &lt;PlatformSDKInstallFolder&gt;\samples\multimedia\directshow\baseclasses<br>
 106     to the includes' search path
 107     (at Tools->Options->Directories->Include files in case of Visual Studio 6.0,<br>
 108      at Tools->Options->Projects and Solutions->VC++ Directories->Include files in case
 109      of Visual Studio 2005)<br>
 110    Add<br>
 111       &lt;DirectXSDKInstallFolder&gt;\lib<br>
 112       &lt;PlatformSDKInstallFolder&gt;\lib<br>
 113    to the libraries' search path (in the same dialog, ...->"Library files" page)<p>
 114
 115    NOTE: PUT THE ADDED LINES ON THE VERY TOP OF THE LISTS, OTHERWISE YOU MAY STILL GET
 116    COMPILER OR LINKER ERRORS. This is necessary, because Visual Studio
 117    may include older versions of the same headers and libraries.</p>
 118
 119 <li>Now you can build OpenCV DirectShow filters.
 120 </ol>
 121
 122 <hr><h3>After installing DirectX SDK I'm still getting linker error about undefined
 123      or redefined "TransInPlace" filter class constructors etc.</h3>
 124 <p>Put the paths to the SDKs' include and lib folders on the top of the search lists.</p>
 125
 126 <hr><h3>When I use try to use cvcam, it just crashes</h3>
 127 <p>Make sure, you registered ProxyTrans.ax and SyncFilter.ax</p>
 128
 129 <!-- <hr><h3>CamShiftDemo can not be run</h3>
 130 <p>Make sure, you registered CamShift.ax and you have DirectShow-compatible camera</p> -->
 131
 132 <hr><h3>How to register *.ax (DirectShow filter)?</h3>
 133 <p>Open the file (within explorer) using regsvr32.exe (under Win2000 it is done by
 134 Open with->Choose Program...->Browse...->c:\windows\system32\regsvr32.exe (path may be different).
 135 You may remember association to save clicks later.</p>
 136
 137 <hr><h3>Filter couldn't be registered (regsvr32 reports an error)</h3>
 138 <p>The most probable reason is that the filter requires some DLLs that are not in the path.
 139 In case of OpenCV make sure &lt;OpenInstallFolder&gt;\bin is in the path</p>
 140
 141 <!-- <hr><h3>LKDemo / HMMDemo reports an error during startup and no the view is completely black</h3>
 142 <p>To run either of these apps you will need VFW-compatible camera.
 143 At startup the programs iterate through registered video capture devices.
 144 It might be that they could not find one. Try to select the camera manually
 145 by pressing "tune capture parameters" (camera) toolbar button. Then, try to
 146 setup video format (the button on the left from camera) to make the camera work.
 147 </p> -->
 148
 149
 150 <hr><h3>cxcore096d.dll or cxcored.lib seem to be missing</h3>
 151 <p>cxcore096d.dll means debug version of cxcore DLL and cxcored.lib is the import library for cxcore096d.dll.
 152 Open <a href="../_make/">OpenCV workspace</a>, select "cxcore" as active project and
 153 select "Win32 Debug" configuration. Build the library and you will get bin\cxcore096d.dll and
 154 lib\cxcored.lib files. The same should be repeat for <em>all</em> the other OpenCV components
 155 - name of binary, ending with <em>d</em> means Debug version that are not shipped.</p>
 156
 157 <hr><h3>When compiling HighGUI I get the error message "mil.h is not found"</h3>
 158 mil.h is a part of Matrox Imaging Library (MIL) that is usually supplied with
 159 Matrox (or compatible) framegrabbers, such as Meteor, Meteor II etc.
 160 <ul>
 161 <li>If you have such
 162 a framegrabber and MIL installed, add mil\include and mil\lib to the search paths
 163 within Developer Studio (submenu Tools-&gt;Options-&gt;Directories).
 164 <li>If you do not have MIL, just ignore the error. The file mil.h is only required
 165 to build MIL-aware version of Highgui "Win32 MIL Debug" or "Win32 MIL Release".
 166 Select "Win32 Debug" or "Win32 Release" configuration of highgui
 167 (submenu Build-&gt;Set Active Configuration...) instead - these versions of highgui
 168 can still be used to grab video via VFW interface, work with AVIs and still images.
 169 </ul>
 170
 171 <hr><h3>How can I debug DirectShow filter?</h3>
 172 <p><ul>
 173 <li>Open workspace with the filter (e.g. opencv.dsw),
 174 <li>select the filter as active project and build it in debug configuration,
 175 <li>switch to explorer for a minute to register debug version of the filter
 176 (e.g. regsvr32 camshiftd.ax) (it needs to be done only when debug/release version are switched - not
 177 every time when filter is recompiled, because registry stores only the filter name),
 178 <li>get back to Developer Studio and start debugging session (F5).
 179     It will ask, what application do you want to run to debug the module.
 180     You may choose camshiftdemo to debug camshift.ax and
 181     DirectX SDK tool graphedit to debug arbitrary DirectShow filter.
 182 <li>Within graphedit build filter graph (e.g. camera->camshift->renderer)
 183 <li>Save the graph (you may just load it next time)
 184 <li>Set the breakpoint inside ::Transform method of the filter or in other location.
 185 <li>Run the filter and ... have fun
 186 </ul>
 187
 188
 189 <hr><h3><a name="devstudio_project">How can I create Developer Studio project to start playing with OpenCV</a></h3>
 190 <p>(note: this is a lengthy answer)
 191 <p>
 192 To create your own OpenCV-based project in Developer Studio
 193 from scratch do the following:</p>
 194     <ol>
 195     <li>Within Developer Studio create new application:
 196     <ol>
 197       <li>select from menu "File"->"New..."->"Projects" tab.
 198         Choose "Win32 Application" or "Win32 console application" - the latter is
 199         the easier variant and the both sample projects have this type.
 200
 201       <li>type the project name and choose location
 202       <li>you may create own workspace for the project ("Create new workspace")
 203         or include the new project into the currently loaded workspace
 204         ("Add to current workspace").
 205       <li>click "next" button
 206       <li>choose "An empty project", click "Finish", "OK".
 207     </ol>
 208       After the above steps done Developer Studio will create the project
 209       folder (by default it has the same name as the project),
 210       &lt;project name&gt;.dsp file and, optionally, &lt;project name&gt;.dsw,.ncb ... files
 211       if you create own workspace.
 212
 213     <li>Add a file to the project:
 214       <ul>
 215       <li>select from menu "File"->"New..."->"Files" tab.
 216       <li>choose "C++ Source File", type file name and press "OK"
 217       <li>add OpenCV-related #include directives:
 218       <pre>
 219         #include "cv.h"
 220         /* #inlcude "cvaux.h" // experimental stuff (if need) */
 221         #include "highgui.h"
 222       </pre>
 223       Or, you may copy some existing file (say, opencv\samples\c\morphology.c) to the project folder,
 224       open it and add to the project
 225       (right click in editor view -&gt; "Insert File into Project" -&gt; &lt;your project name&gt; ).
 226       </ul>
 227     <li>Customize project settings:
 228       <ul>
 229       <li>Activate project setting dialog by choosing menu item
 230         "Project"-&gt;"Settings...".
 231       <li>Select your project in the right pane.
 232       <li>Tune settings, common to both Release and Debug configurations:
 233         <ul>
 234         <li>Select "Settings For:"-&gt;"All Configurations"
 235         <li>Choose "C/C++" tab -&gt; "Preprocessor" category -&gt; "Additional Include Directories:".
 236           Add comma-separated relative (to the .dsp file) or absolute paths
 237           to opencv\cxcore\include, opencv\cv\include, opencv\otherlibs\highgui and, optionally,
 238           opencv\cvaux\include.
 239         <li>Choose "Link" tab -&gt; "Input" category -&gt; "Additional library path:".
 240           Add the paths to all necessary import libraries (cxcore[d].lib cv[d].lib hihghui[d].lib cvaux[d].lib)
 241         </ul>
 242        <li>Tune settings for "Debug" configuration
 243        <ul>
 244         <li>Select "Settings For:"-&gt;"Win32 Debug".
 245         <li>Choose "Link" tab -&gt; "General" category -&gt; "Object/library modules".
 246           Add space-separated cvd.lib, highguid.lib, cvauxd.lib (optionally)
 247         <li>You may also want to change location and name of output file. For example,
 248           if you want the output .exe file to be put into the project folder, rather
 249           than Debug/ subfolder, you may type ./&lt;exe-name&gt;d.exe in
 250           "Link" tab -&gt; "General" category -&gt; "Output file name:".
 251         </ul>
 252        <li>Tune settings for "Release" configuration
 253        <ul>
 254         <li>Select "Settings For:"-&gt;"Win32 Release".
 255         <li>Choose "Link" tab -&gt; "General" category -&gt; "Object/library modules".
 256           Add space-separated cv.lib, highgui.lib, cvaux.lib (optionally)
 257         <li>Optionally, you may change name of the .exe file:
 258           type ./&lt;exe-name&gt;.exe in "Link" tab -&gt; "General" category -&gt; "Output file name:".
 259        </ul>
 260        </ul>
 261     <li>Add dependency projects into workspace:
 262        <ul>
 263        <li>Choose from menu: "Project" -&gt; "Insert project into workspace".
 264        <li>Select opencv\cv\make\cv.dsp.
 265        <li>Do the same for opencv\cvaux\make\cvaux.dsp, opencv\otherlibs\highgui\highgui.dsp.
 266        <li>Set dependencies:
 267        <ul>
 268         <li>Choose from menu: "Project" -&gt; "Dependencies..."
 269         <li>For "cv" choose "cxcore",
 270         <li>For "cvaux" choose "cv", "cxcore",
 271         <li>for "highgui" choose "cxcore",
 272         <li>for your project choose all: "cxcore", "cv", "cvaux", "highgui".
 273        </ul>
 274        The dependencies customization allows to automatically build debug versions
 275        of opencv libraries and rebuild the binaries if the sources are changed somehow.
 276     </ul>
 277     <li>That's it. Now compile and run everything.
 278     </ol>
 279
 280 <hr><h1>Linux Related Qs:</h1>
 281
 282 TODO
 283
 284
 285 <hr><h1>Technical Questions on Library use:</h1>
 286
 287 <hr><h3>How to access image pixels</h3>
 288 <p>
 289 (The coordinates are 0-based and counted from image origin, either top-left
 290 (img->origin=IPL_ORIGIN_TL) or bottom-left (img->origin=IPL_ORIGIN_BL)
 291 <ul>
 292 <li>Suppose, we have 8-bit 1-channel image I (IplImage* img):
 293 <pre>
 294 I(x,y) ~ ((uchar*)(img->imageData + img->widthStep*y))[x]
 295 </pre>
 296 <li>Suppose, we have 8-bit 3-channel image I (IplImage* img):
 297 <pre>
 298 I(x,y)<sub>blue</sub> ~ ((uchar*)(img->imageData + img->widthStep*y))[x*3]
 299 I(x,y)<sub>green</sub> ~ ((uchar*)(img->imageData + img->widthStep*y))[x*3+1]
 300 I(x,y)<sub>red</sub> ~ ((uchar*)(img->imageData + img->widthStep*y))[x*3+2]
 301 </pre>
 302 e.g. increasing brightness of point (100,100) by 30 can be done this way:
 303 <pre>
 304 CvPoint pt = {100,100};
 305 ((uchar*)(img->imageData + img->widthStep*pt.y))[pt.x*3] += 30;
 306 ((uchar*)(img->imageData + img->widthStep*pt.y))[pt.x*3+1] += 30;
 307 ((uchar*)(img->imageData + img->widthStep*pt.y))[pt.x*3+2] += 30;
 308 </pre>
 309 or more efficiently
 310 <pre>
 311 CvPoint pt = {100,100};
 312 uchar* temp_ptr = &((uchar*)(img->imageData + img->widthStep*pt.y))[x*3];
 313 temp_ptr[0] += 30;
 314 temp_ptr[1] += 30;
 315 temp_ptr[2] += 30;
 316 </pre>
 317 <li>Suppose, we have 32-bit floating point, 1-channel image I (IplImage* img):
 318 <pre>
 319 I(x,y) ~ ((float*)(img->imageData + img->widthStep*y))[x]
 320 </pre>
 321 <li>Now, the general case: suppose, we have N-channel image of type T:
 322 <pre>
 323 I(x,y)<sub>c</sub> ~ ((T*)(img->imageData + img->widthStep*y))[x*N + c]
 324 or you may use macro CV_IMAGE_ELEM( image_header, elemtype, y, x_Nc )
 325 I(x,y)<sub>c</sub> ~ CV_IMAGE_ELEM( img, T, y, x*N + c )
 326 </pre>
 327 </ul>
 328 There are functions that work with arbitrary (up to 4-channel) images and matrices
 329 (cvGet2D, cvSet2D), but they are pretty slow.
 330 </p>
 331
 332 <hr><h3>How to access matrix elements?</h3>
 333 <p>The technique is very similar.
 334 (In the samples below i - 0-based row index, j - 0-based column index)
 335 <ul>
 336 <li>Suppose, we have 32-bit floating point real matrix M (CvMat* mat):
 337 <pre>
 338 M(i,j) ~ ((float*)(mat->data.ptr + mat->step*i))[j]
 339 </pre>
 340 <li>Suppose, we have 64-bit floating point complex matrix M (CvMat* mat):
 341 <pre>
 342 Re M(i,j) ~ ((double*)(mat->data.ptr + mat->step*i))[j*2]
 343 Im M(i,j) ~ ((double*)(mat->data.ptr + mat->step*i))[j*2+1]
 344 </pre>
 345 <li>For single-channel matrices there is a macro CV_MAT_ELEM( matrix, elemtype, row, col ),
 346 i.e. for 32-bit floating point real matrix<pre>
 347 M(i,j) ~ CV_MAT_ELEM( mat, float, i, j ),</pre> e.g. here is
 348 initialization of 3x3 identity matrix:<pre>
 349 CV_MAT_ELEM( mat, float, 0, 0 ) = 1.f;
 350 CV_MAT_ELEM( mat, float, 0, 1 ) = 0.f;
 351 CV_MAT_ELEM( mat, float, 0, 2 ) = 0.f;
 352 CV_MAT_ELEM( mat, float, 1, 0 ) = 0.f;
 353 CV_MAT_ELEM( mat, float, 1, 1 ) = 1.f;
 354 CV_MAT_ELEM( mat, float, 1, 2 ) = 0.f;
 355 CV_MAT_ELEM( mat, float, 2, 0 ) = 0.f;
 356 CV_MAT_ELEM( mat, float, 2, 1 ) = 0.f;
 357 CV_MAT_ELEM( mat, float, 2, 2 ) = 1.f;
 358 </pre>
 359 </ul>
 360
 361 <hr><h3>How to process my data with OpenCV</h3>
 362 <p>
 363 Suppose, you have 300x200 32-bit floating point image/array, that
 364 resides in 60000-element array.
 365 <pre>
 366 int cols = 300, rows = 200;
 367 float* myarr = new float[rows*cols];
 368
 369 // step 1) initializing CvMat header
 370 CvMat mat = cvMat( rows, cols,
 371                    CV_32FC1, // 32-bit floating-point, single channel type
 372                    myarr // user data pointer (no data is copied)
 373                    );
 374 // step 2) using cv functions, e.g. calculating l2 (Frobenius) norm
 375 double norm = cvNorm( &mat, 0, CV_L2 );
 376
 377 ...
 378 delete myarr;
 379 </pre>
 380 Other scenaria are described in the reference manual.
 381 See cvCreateMatHeader, cvInitMatHeader, cvCreateImageHeader, cvSetData etc.
 382 </p>
 383
 384 <hr><h3>How to load and display image</h3>
 385 <pre>
 386 /* usage: prog &lt;image_name&gt; */
 387 #include "cv.h"
 388 #include "highgui.h"
 389
 390 int main( int argc, char** argv )
 391 {
 392     IplImage* img;
 393     if( argc == 2 && (img = cvLoadImage( argv[1], 1)) != 0 )
 394     {
 395         cvNamedWindow( "Image view", 1 );
 396         cvShowImage( "Image view", img );
 397         cvWaitKey(0); // very important, contains event processing loop inside
 398         cvDestroyWindow( "Image view" );
 399         cvReleaseImage( &img );
 400         return 0;
 401     }
 402     return -1;
 403 }
 404 </pre>
 405
 406 <hr><h3>How to find and process contours</h3>
 407 <p>Look at <a href="../samples/c/squares.c">squares</a> demo</p>
 408
 409 <hr><h3>How to calibrate camera using OpenCV</h3>
 410 <p>TODO</p>
 411
 412   </BODY>
 413 </HTML>