Difference between revisions of "Tutorial"

From Emgu CV: OpenCV in .NET (C#, VB, C++ and more)
Jump to: navigation, search
(New page: ==Namespace== ===Emgu=== All libraries provided by Emgu(R) are provided under the namespace Emgu. ===Emgu.CV== The Emgu.CV namespace implement wrapper functions for OpenCV ==== Emgu.CV...)
 
(Image Processing Examples)
 
(185 intermediate revisions by 13 users not shown)
Line 1: Line 1:
==Namespace==
+
== Wrapping OpenCV ==
  
===Emgu===
+
===Function Mapping - Emgu.CV.CvInvoke ===
All libraries provided by Emgu(R) are provided under the namespace Emgu.  
+
The CvInvoke class provides a way to directly invoke [[OpenCV]] function within .NET languages. Each method in this class corresponds to a function in [[OpenCV]] of the same name. For example, a call to
 +
<source lang="csharp">
 +
IntPtr image = CvInvoke.cvCreateImage(new System.Drawing.Size(400, 300), CvEnum.IPL_DEPTH.IPL_DEPTH_8U, 1);
 +
</source> is equivalent to the following function call in C 
 +
<source lang="c">
 +
IplImage* image = cvCreateImage(cvSize(400, 300), IPL_DEPTH_8U, 1);
 +
</source>
 +
Both of which create a 400x300 of 8-bit unsigned grayscale image.
  
===Emgu.CV==
+
===Structure Mapping - Emgu.CV.Structure.M''xxx'' ===
The Emgu.CV namespace implement wrapper functions for OpenCV
+
This type of structure is a direct mapping to [[OpenCV]] structures.
 +
{| style="text-align:center" border="1px" cellspacing="0" cellpadding="5"
 +
![[Emgu CV]] Structure || [[OpenCV]] structure
 +
|-
 +
| Emgu.CV.Structure.MIplImage || IplImage
 +
|-
 +
| Emgu.CV.Structure.MCvMat || CvMat
 +
|-
 +
| ... || ...
 +
|-
 +
| Emgu.CV.Structure.M''xxxx'' || ''xxxx''
 +
|}
  
==== Emgu.CV.CvInvoke class ====
+
The prefix ''M'' here stands for Managed structure.
 +
 
 +
[[Emgu CV]] also borrows some existing structures in .Net to represent structures in [[OpenCV]]:
 +
 
 +
{| style="text-align:center" border="1px" cellspacing="0" cellpadding="5"
 +
!.Net Structure || [[OpenCV]] structure
 +
|-
 +
| System.Drawing.Point || CvPoint
 +
|-
 +
| System.Drawing.PointF || CvPoint2D32f
 +
|-
 +
| System.Drawing.Size || CvSize
 +
|-
 +
| System.Drawing.Rectangle || CvRect
 +
|}
 +
 
 +
===Enumeration Mapping - Emgu.CV.CvEnum ===
 +
The CvEnum namespace provides direct mapping to [[OpenCV]] enumerations. For example, <code> CvEnum.IPL_DEPTH.IPL_DEPTH_8U </code> has the same value as <code> IPL_DEPTH_8U </code> in [[OpenCV]]; both of which equals <code>8</code>.
 +
 
 +
==Managed classes==
 +
===[[Working with Images]]===
 +
===[[Working with Matrices]]===
 +
 
 +
==Error Handling==
 +
[[Emgu CV]] register a custom error handler in [[OpenCV]]. When error is encountered from [[OpenCV]], a <code>CvException</code> will be thrown.
 +
 
 +
==Code Documentation==
 +
===Xml Documentation===
 +
Documentation is embedded in the code using xml format, which can then be compiled as HTML documentation using [http://www.codeplex.com/Sandcastle Sandcastle]. You can browse our [[Documentation | Online Documentation]] for the latest stable and development code.
 +
 
 +
===Method Documentation===
 +
A library of coding examples according to the methods is being formed here: [http://www.emgu.com/wiki/index.php/Code_Reference Online Code Reference].
 +
 
 +
===Intellisense in Visual Studio===
 +
If you are using Visual Studio as your development tools, you will have intellisense support when developing [[Emgu CV]] applications. For example, if you want to create an image directly using cvCreateImage function, which is wrapped by the CvInvoke Class, just type <code>CvInvoke.</code>
 +
 
 +
[[image:EmguCvIntellisenseCreateImage1.GIF]]
 +
 
 +
and a list of functions belonging to <code>CvInvoke</code> class is displayed along with a description for each of the functions. Since you are creating an image, select the <code> cvCreateImage </code> function
 +
 
 +
[[image:EmguCvIntellisenseCreateImage2.GIF]]
 +
 
 +
The list of parameters for this function will be displayed as well as a description for each of the parameters.
 +
 
 +
==Examples==
 +
<b>[http://www.emgu.com/wiki/index.php/Code_Reference Online Code Reference]</b>
 +
 
 +
===C#===
 +
====Image Processing Examples ====
 +
<b>Introductions</b>
 +
* [[Hello World in CSharp|Hello World for Windows]]
 +
* [[Hello World for Ubuntu|Hello World for Ubuntu]]
 +
* [[Setting_up_EMGU_C_Sharp| User Guide to EMGU and Accessing Image Data]]
 +
* [[Camera Capture in 7 lines of code]]
 +
<b>Intermediate</b>
 +
* [[Shape (Triangle, Rectangle, Circle, Line) Detection in CSharp | Shape (Triangle, Rectangle, Circle, Line) Detection]]
 +
* [[SURF feature detector in CSharp|SURF Feature Detector]]
 +
* [[FAST feature detector in CSharp|FAST Feature Detector]]
 +
* [[WPF in CSharp|Windows Presentation Foundation (WPF)]]
 +
* [[Face detection| Face detection in Csharp]]
 +
* [[Pedestrian Detection in CSharp | Pedestrian Detection, Histogram of oriented gradients (HOG)]]
 +
* [[Traffic Sign Detection in CSharp|Traffic Sign Detection]]
 +
* [[License Plate Recognition in CSharp|License Plate Recognition (LPR), Optical Character Recognition (OCR)]]
 +
* [[Image Stitching in CSharp| Image Stitching]]
 +
* [[Kalman_Filter| Using the Kalman Filter]]
 +
* [[Asp.Net Core on Ubuntu| Asp.Net Core project on Ubuntu]]
 +
 
 +
====Computational Geometry Examples ====
 +
* [[Planar Subdivision in CSharp|Delaunay's Triangulation and Voronoi Diagram]]
 +
* [[Convex Hull in CSharp| Convex Hull]]
 +
* [[Ellipse Fitting in CSharp | Ellipse Fitting]]
 +
* [[Minimum Area Rectangle in CSharp | Minimum Area Rectangle]]
 +
* [[Minimum Enclosing Circle in CSharp | Minimum Enclosing Circle]]
 +
 
 +
====Machine Learning Examples ====
 +
* [[Normal Bayes Classifier in CSharp | Normal Bayes Classifier ]]
 +
* [[K Nearest Neighbors in CSharp | K Nearest Neighbors ]]
 +
* [[SVM (Support Vector Machine) in CSharp | Support Vector Machine (SVM) - thanks to Albert G.]]
 +
* [[Expectation-Maximization in CSharp | Expectation-Maximization (EM)]]
 +
* [[ANN MLP (Neural Network) in CSharp | Neural Network (ANN MLP) ]]
 +
* [[Mushroom Poisonous Prediction (Decision Tree) in CSharp | Mushroom Poisonous Prediction (Decision Tree) ]]
 +
 
 +
==== Video Codec ====
 +
* [[H264 Codec | VideoWriter with H264 codec]]
 +
 
 +
===C++===
 +
* [[Hello World in C++|Hello World]]
 +
===IronPython===
 +
* [[Setting up Emgu CV and IronPython]]
 +
* [[Face Detection from IronPython]]
 +
===VB.NET===
 +
* [[Face Detection in VB.NET]]
 +
* [[Hello World in VB.NET]]
 +
 
 +
===Unity===
 +
* [[Working with Vuforia]]
 +
 
 +
== Upgrading from Emgu CV 2.x to 3.x ==
 +
 
 +
===Function Mapping - Emgu.CV.CvInvoke ===
 +
 
 +
In Emgu CV v2.x, CvInvoke function calls use the C interface. In v3.x, we have migrate away from the opencv c interface to opencv C++ interface, so does the function names.
 +
 
 +
For example, in v2.x, the function <pre>CvInvoke.cvAnd(IntPtr src1, IntPtr src2, IntPtr dst, Intptr mask)</pre> has been replaced by <pre>CvInvoke.BitwiseAnd(IInputArray src1, IInputArray src2, IOutputArray dst, IInputArray mask)</pre>
 +
 
 +
The best way to find out the new function names if you are migrating from version 2.x is through the Open CV documentation:
 +
 
 +
http://docs.opencv.org/trunk/
 +
 
 +
You can search for the C function name and the search result should have the C++ function name right next to the C interface.
 +
 
 +
=== IInputArray, IOutputArray ===
 +
 
 +
<code>IInputArray</code> has been introduced in version 3.0. You can find that many of our new interfaces accepts <code>IInputArray</code> and <code>IOutputArray</code>. They can be any one of the following:
 +
*A CvArray, which is the base class of Matrix and Image<,>
 +
*A Mat, which is the Open CV equivalent of cv::Mat
 +
*A UMat, which is the Open CV equivalent of cv::UMat
 +
*A ScalarArray, which can be used to convert a scalar to an IInputArray
 +
*VectorOf{XXX}, this is the interface for the C++ standard vector
 +
 
 +
=== T-API ===
 +
'''T-API is THE MOST AWESOME FUTURE in 3.0 release !!!'''
 +
 
 +
Let me explain why:
 +
 
 +
For a simple image operation, suppose we have an image in memory and we wants to perform an invert operation. In Emgu CV 2.x, we can write the code as follows:
 +
<pre>
 +
Image<Gray, Byte> image = ... //load the image from some where
 +
Image<Gray, Byte> imageInvert = new Image<Gray, Byte>(image.Width, image.Height);
 +
CvInvoke.cvNot(image, imageInvert);
 +
</pre>
 +
In Emgu CV 3.x, we can still use the Image<Gray, Byte> class to perform the same operation, with a slight change in the CvInvoke function name
 +
<pre>
 +
Image<Gray, Byte> image = ... //load the image from some where
 +
Image<Gray, Byte> imageInvert = new Image<Gray, Byte>(image.Width, image.Height);
 +
CvInvoke.BitwiseNot(image, imageInvert);
 +
</pre>
 +
To realize the true potential with T-API, let's try to use UMat to perform the same operation
 +
<pre>
 +
UMat image = ... //load the image from some where
 +
UMat imageInvert = new UMat();
 +
CvInvoke.BitwiseNot(image, imageInvert);
 +
</pre>
 +
It all seems to be not much different from the code that use the Image<,> class in 3.0. However, the above code can automatically use OpenCL engine to perform the operation if a suitable OpenCL device is found. That means it will run many times faster on a system with a discrete GPU (Nvidia, AMD, Intel Iris Pro etc). On systems that do not have a OpenCL devices, the code will be run on CPU and have the same performance as if we are passing the Image<,> or Mat objects to the CvInvoke function.
 +
 
 +
In short, T-API enable developer to automatically use the OpenCL devices (GPU) for computing and automatically fall back to CPU in the absent of OpenCL devices. You can also turn the OpenCL engine off by simply setting
 +
<pre>
 +
CvInvoke.UseOpenCL = false
 +
</pre>
 +
In which case all the code will be run on CPU instead.
 +
 
 +
The T-API is the motivation for us to rewrite all our code using the OpenCV C++ interface to take advantage of this future. We believe it is well worth the effort once we see the results.

Latest revision as of 15:42, 30 November 2020

Wrapping OpenCV

Function Mapping - Emgu.CV.CvInvoke

The CvInvoke class provides a way to directly invoke OpenCV function within .NET languages. Each method in this class corresponds to a function in OpenCV of the same name. For example, a call to

 
 IntPtr image = CvInvoke.cvCreateImage(new System.Drawing.Size(400, 300), CvEnum.IPL_DEPTH.IPL_DEPTH_8U, 1);
is equivalent to the following function call in C
 
 IplImage* image = cvCreateImage(cvSize(400, 300), IPL_DEPTH_8U, 1);

Both of which create a 400x300 of 8-bit unsigned grayscale image.

Structure Mapping - Emgu.CV.Structure.Mxxx

This type of structure is a direct mapping to OpenCV structures.

Emgu CV Structure OpenCV structure
Emgu.CV.Structure.MIplImage IplImage
Emgu.CV.Structure.MCvMat CvMat
... ...
Emgu.CV.Structure.Mxxxx xxxx

The prefix M here stands for Managed structure.

Emgu CV also borrows some existing structures in .Net to represent structures in OpenCV:

.Net Structure OpenCV structure
System.Drawing.Point CvPoint
System.Drawing.PointF CvPoint2D32f
System.Drawing.Size CvSize
System.Drawing.Rectangle CvRect

Enumeration Mapping - Emgu.CV.CvEnum

The CvEnum namespace provides direct mapping to OpenCV enumerations. For example, CvEnum.IPL_DEPTH.IPL_DEPTH_8U has the same value as IPL_DEPTH_8U in OpenCV; both of which equals 8.

Managed classes

Working with Images

Working with Matrices

Error Handling

Emgu CV register a custom error handler in OpenCV. When error is encountered from OpenCV, a CvException will be thrown.

Code Documentation

Xml Documentation

Documentation is embedded in the code using xml format, which can then be compiled as HTML documentation using Sandcastle. You can browse our Online Documentation for the latest stable and development code.

Method Documentation

A library of coding examples according to the methods is being formed here: Online Code Reference.

Intellisense in Visual Studio

If you are using Visual Studio as your development tools, you will have intellisense support when developing Emgu CV applications. For example, if you want to create an image directly using cvCreateImage function, which is wrapped by the CvInvoke Class, just type CvInvoke.

EmguCvIntellisenseCreateImage1.GIF

and a list of functions belonging to CvInvoke class is displayed along with a description for each of the functions. Since you are creating an image, select the cvCreateImage function

EmguCvIntellisenseCreateImage2.GIF

The list of parameters for this function will be displayed as well as a description for each of the parameters.

Examples

Online Code Reference

C#

Image Processing Examples

Introductions

Intermediate

Computational Geometry Examples

Machine Learning Examples

Video Codec

C++

IronPython

VB.NET

Unity

Upgrading from Emgu CV 2.x to 3.x

Function Mapping - Emgu.CV.CvInvoke

In Emgu CV v2.x, CvInvoke function calls use the C interface. In v3.x, we have migrate away from the opencv c interface to opencv C++ interface, so does the function names.

For example, in v2.x, the function
CvInvoke.cvAnd(IntPtr src1, IntPtr src2, IntPtr dst, Intptr mask)
has been replaced by
CvInvoke.BitwiseAnd(IInputArray src1, IInputArray src2, IOutputArray dst, IInputArray mask)

The best way to find out the new function names if you are migrating from version 2.x is through the Open CV documentation:

http://docs.opencv.org/trunk/

You can search for the C function name and the search result should have the C++ function name right next to the C interface.

IInputArray, IOutputArray

IInputArray has been introduced in version 3.0. You can find that many of our new interfaces accepts IInputArray and IOutputArray. They can be any one of the following:

  • A CvArray, which is the base class of Matrix and Image<,>
  • A Mat, which is the Open CV equivalent of cv::Mat
  • A UMat, which is the Open CV equivalent of cv::UMat
  • A ScalarArray, which can be used to convert a scalar to an IInputArray
  • VectorOf{XXX}, this is the interface for the C++ standard vector

T-API

T-API is THE MOST AWESOME FUTURE in 3.0 release !!!

Let me explain why:

For a simple image operation, suppose we have an image in memory and we wants to perform an invert operation. In Emgu CV 2.x, we can write the code as follows:

Image<Gray, Byte> image = ... //load the image from some where
Image<Gray, Byte> imageInvert = new Image<Gray, Byte>(image.Width, image.Height);
CvInvoke.cvNot(image, imageInvert);

In Emgu CV 3.x, we can still use the Image<Gray, Byte> class to perform the same operation, with a slight change in the CvInvoke function name

Image<Gray, Byte> image = ... //load the image from some where
Image<Gray, Byte> imageInvert = new Image<Gray, Byte>(image.Width, image.Height);
CvInvoke.BitwiseNot(image, imageInvert);

To realize the true potential with T-API, let's try to use UMat to perform the same operation

UMat image = ... //load the image from some where
UMat imageInvert = new UMat();
CvInvoke.BitwiseNot(image, imageInvert);

It all seems to be not much different from the code that use the Image<,> class in 3.0. However, the above code can automatically use OpenCL engine to perform the operation if a suitable OpenCL device is found. That means it will run many times faster on a system with a discrete GPU (Nvidia, AMD, Intel Iris Pro etc). On systems that do not have a OpenCL devices, the code will be run on CPU and have the same performance as if we are passing the Image<,> or Mat objects to the CvInvoke function.

In short, T-API enable developer to automatically use the OpenCL devices (GPU) for computing and automatically fall back to CPU in the absent of OpenCL devices. You can also turn the OpenCL engine off by simply setting

CvInvoke.UseOpenCL = false

In which case all the code will be run on CPU instead.

The T-API is the motivation for us to rewrite all our code using the OpenCV C++ interface to take advantage of this future. We believe it is well worth the effort once we see the results.