vendor: OpenCV 5.0.0 snapshot at 755e50675d97db9b7d449d8bd6b09888646f6c6e

modules/ml/tutorials/cpp_ml/introduction_to_svm/introduction_to_svm.markdown

@@ -0,0 +1,272 @@
+Introduction to Support Vector Machines {#tutorial_introduction_to_svm}
+=======================================
+
+@tableofcontents
+
+@next_tutorial{tutorial_non_linear_svms}
+
+|    |    |
+| -: | :- |
+| Original author | Fernando Iglesias García |
+| Compatibility | OpenCV >= 3.0 |
+
+Goal
+----
+
+In this tutorial you will learn how to:
+
+-   Use the OpenCV functions @ref cv::ml::SVM::train to build a classifier based on SVMs and @ref
+    cv::ml::SVM::predict to test its performance.
+
+What is a SVM?
+--------------
+
+A Support Vector Machine (SVM) is a discriminative classifier formally defined by a separating
+hyperplane. In other words, given labeled training data (*supervised learning*), the algorithm
+outputs an optimal hyperplane which categorizes new examples.
+
+In which sense is the hyperplane obtained optimal? Let's consider the following simple problem:
+
+For a linearly separable set of 2D-points which belong to one of two classes, find a separating
+straight line.
+
+![](images/separating-lines.png)
+
+@note In this example we deal with lines and points in the Cartesian plane instead of hyperplanes
+and vectors in a high dimensional space. This is a simplification of the problem.It is important to
+understand that this is done only because our intuition is better built from examples that are easy
+to imagine. However, the same concepts apply to tasks where the examples to classify lie in a space
+whose dimension is higher than two.
+
+In the above picture you can see that there exists multiple lines that offer a solution to the
+problem. Is any of them better than the others? We can intuitively define a criterion to estimate
+the worth of the lines: <em> A line is bad if it passes too close to the points because it will be
+noise sensitive and it will not generalize correctly. </em> Therefore, our goal should be to find
+the line passing as far as possible from all points.
+
+Then, the operation of the SVM algorithm is based on finding the hyperplane that gives the largest
+minimum distance to the training examples. Twice, this distance receives the important name of
+**margin** within SVM's theory. Therefore, the optimal separating hyperplane *maximizes* the margin
+of the training data.
+
+![](images/optimal-hyperplane.png)
+
+How is the optimal hyperplane computed?
+---------------------------------------
+
+Let's introduce the notation used to define formally a hyperplane:
+
+\f[f(x) = \beta_{0} + \beta^{T} x,\f]
+
+where \f$\beta\f$ is known as the *weight vector* and \f$\beta_{0}\f$ as the *bias*.
+
+@note A more in depth description of this and hyperplanes you can find in the section 4.5 (*Separating
+Hyperplanes*) of the book: *Elements of Statistical Learning* by T. Hastie, R. Tibshirani and J. H.
+Friedman (@cite HTF01).
+
+The optimal hyperplane can be represented in an infinite number of different ways by
+scaling of \f$\beta\f$ and \f$\beta_{0}\f$. As a matter of convention, among all the possible
+representations of the hyperplane, the one chosen is
+
+\f[|\beta_{0} + \beta^{T} x| = 1\f]
+
+where \f$x\f$ symbolizes the training examples closest to the hyperplane. In general, the training
+examples that are closest to the hyperplane are called **support vectors**. This representation is
+known as the **canonical hyperplane**.
+
+Now, we use the result of geometry that gives the distance between a point \f$x\f$ and a hyperplane
+\f$(\beta, \beta_{0})\f$:
+
+\f[\mathrm{distance} = \frac{|\beta_{0} + \beta^{T} x|}{||\beta||}.\f]
+
+In particular, for the canonical hyperplane, the numerator is equal to one and the distance to the
+support vectors is
+
+\f[\mathrm{distance}_{\text{ support vectors}} = \frac{|\beta_{0} + \beta^{T} x|}{||\beta||} = \frac{1}{||\beta||}.\f]
+
+Recall that the margin introduced in the previous section, here denoted as \f$M\f$, is twice the
+distance to the closest examples:
+
+\f[M = \frac{2}{||\beta||}\f]
+
+Finally, the problem of maximizing \f$M\f$ is equivalent to the problem of minimizing a function
+\f$L(\beta)\f$ subject to some constraints. The constraints model the requirement for the hyperplane to
+classify correctly all the training examples \f$x_{i}\f$. Formally,
+
+\f[\min_{\beta, \beta_{0}} L(\beta) = \frac{1}{2}||\beta||^{2} \text{ subject to } y_{i}(\beta^{T} x_{i} + \beta_{0}) \geq 1 \text{ } \forall i,\f]
+
+where \f$y_{i}\f$ represents each of the labels of the training examples.
+
+This is a problem of Lagrangian optimization that can be solved using Lagrange multipliers to obtain
+the weight vector \f$\beta\f$ and the bias \f$\beta_{0}\f$ of the optimal hyperplane.
+
+Source Code
+-----------
+
+@add_toggle_cpp
+-   **Downloadable code**: Click
+    [here](https://github.com/opencv/opencv_contrib/tree/5.x/modules/ml/samples/introduction_to_svm.cpp)
+
+-   **Code at glance:**
+    @include samples/introduction_to_svm.cpp
+@end_toggle
+
+@add_toggle_java
+-   **Downloadable code**: Click
+    [here](https://github.com/opencv/opencv_contrib/tree/5.x/modules/ml/samples/java/tutorial_code/ml/introduction_to_svm/IntroductionToSVMDemo.java)
+
+-   **Code at glance:**
+    @include samples/java/tutorial_code/ml/introduction_to_svm/IntroductionToSVMDemo.java
+@end_toggle
+
+@add_toggle_python
+-   **Downloadable code**: Click
+    [here](https://github.com/opencv/opencv_contrib/tree/5.x/modules/ml/samples/python/tutorial_code/ml/introduction_to_svm/introduction_to_svm.py)
+
+-   **Code at glance:**
+    @include samples/python/tutorial_code/ml/introduction_to_svm/introduction_to_svm.py
+@end_toggle
+
+Explanation
+-----------
+
+-   **Set up the training data**
+
+The training data of this exercise is formed by a set of labeled 2D-points that belong to one of
+two different classes; one of the classes consists of one point and the other of three points.
+
+@add_toggle_cpp
+@snippet samples/introduction_to_svm.cpp setup1
+@end_toggle
+
+@add_toggle_java
+@snippet samples/java/tutorial_code/ml/introduction_to_svm/IntroductionToSVMDemo.java setup1
+@end_toggle
+
+@add_toggle_python
+@snippet samples/python/tutorial_code/ml/introduction_to_svm/introduction_to_svm.py setup1
+@end_toggle
+
+The function @ref cv::ml::SVM::train that will be used afterwards requires the training data to be
+stored as @ref cv::Mat objects of floats. Therefore, we create these objects from the arrays
+defined above:
+
+@add_toggle_cpp
+@snippet samples/introduction_to_svm.cpp setup2
+@end_toggle
+
+@add_toggle_java
+@snippet samples/java/tutorial_code/ml/introduction_to_svm/IntroductionToSVMDemo.java setup2
+@end_toggle
+
+@add_toggle_python
+@snippet samples/python/tutorial_code/ml/introduction_to_svm/introduction_to_svm.py setup1
+@end_toggle
+
+-   **Set up SVM's parameters**
+
+    In this tutorial we have introduced the theory of SVMs in the most simple case, when the
+    training examples are spread into two classes that are linearly separable. However, SVMs can be
+    used in a wide variety of problems (e.g. problems with non-linearly separable data, a SVM using
+    a kernel function to raise the dimensionality of the examples, etc). As a consequence of this,
+    we have to define some parameters before training the SVM. These parameters are stored in an
+    object of the class @ref cv::ml::SVM.
+
+@add_toggle_cpp
+@snippet samples/introduction_to_svm.cpp init
+@end_toggle
+
+@add_toggle_java
+@snippet samples/java/tutorial_code/ml/introduction_to_svm/IntroductionToSVMDemo.java init
+@end_toggle
+
+@add_toggle_python
+@snippet samples/python/tutorial_code/ml/introduction_to_svm/introduction_to_svm.py init
+@end_toggle
+
+Here:
+-   *Type of SVM*. We choose here the type @ref cv::ml::SVM::C_SVC "C_SVC" that can be used for
+    n-class classification (n \f$\geq\f$ 2). The important feature of this type is that it deals
+    with imperfect separation of classes (i.e. when the training data is non-linearly separable).
+    This feature is not important here since the data is linearly separable and we chose this SVM
+    type only for being the most commonly used.
+
+-   *Type of SVM kernel*. We have not talked about kernel functions since they are not
+    interesting for the training data we are dealing with. Nevertheless, let's explain briefly now
+    the main idea behind a kernel function. It is a mapping done to the training data to improve
+    its resemblance to a linearly separable set of data. This mapping consists of increasing the
+    dimensionality of the data and is done efficiently using a kernel function. We choose here the
+    type @ref cv::ml::SVM::LINEAR "LINEAR" which means that no mapping is done. This parameter is
+    defined using cv::ml::SVM::setKernel.
+
+-   *Termination criteria of the algorithm*. The SVM training procedure is implemented solving a
+    constrained quadratic optimization problem in an **iterative** fashion. Here we specify a
+    maximum number of iterations and a tolerance error so we allow the algorithm to finish in
+    less number of steps even if the optimal hyperplane has not been computed yet. This
+    parameter is defined in a structure @ref cv::TermCriteria .
+
+-   **Train the SVM**
+    We call the method @ref cv::ml::SVM::train to build the SVM model.
+
+@add_toggle_cpp
+@snippet samples/introduction_to_svm.cpp train
+@end_toggle
+
+@add_toggle_java
+@snippet samples/java/tutorial_code/ml/introduction_to_svm/IntroductionToSVMDemo.java train
+@end_toggle
+
+@add_toggle_python
+@snippet samples/python/tutorial_code/ml/introduction_to_svm/introduction_to_svm.py train
+@end_toggle
+
+-   **Regions classified by the SVM**
+
+    The method @ref cv::ml::SVM::predict is used to classify an input sample using a trained SVM. In
+    this example we have used this method in order to color the space depending on the prediction done
+    by the SVM. In other words, an image is traversed interpreting its pixels as points of the
+    Cartesian plane. Each of the points is colored depending on the class predicted by the SVM; in
+    green if it is the class with label 1 and in blue if it is the class with label -1.
+
+@add_toggle_cpp
+@snippet samples/introduction_to_svm.cpp show
+@end_toggle
+
+@add_toggle_java
+@snippet samples/java/tutorial_code/ml/introduction_to_svm/IntroductionToSVMDemo.java show
+@end_toggle
+
+@add_toggle_python
+@snippet samples/python/tutorial_code/ml/introduction_to_svm/introduction_to_svm.py show
+@end_toggle
+
+-   **Support vectors**
+
+    We use here a couple of methods to obtain information about the support vectors.
+    The method @ref cv::ml::SVM::getSupportVectors obtain all of the support
+    vectors. We have used this methods here to find the training examples that are
+    support vectors and highlight them.
+
+@add_toggle_cpp
+@snippet samples/introduction_to_svm.cpp show_vectors
+@end_toggle
+
+@add_toggle_java
+@snippet samples/java/tutorial_code/ml/introduction_to_svm/IntroductionToSVMDemo.java show_vectors
+@end_toggle
+
+@add_toggle_python
+@snippet samples/python/tutorial_code/ml/introduction_to_svm/introduction_to_svm.py show_vectors
+@end_toggle
+
+Results
+-------
+
+-   The code opens an image and shows the training examples of both classes. The points of one class
+    are represented with white circles and black ones are used for the other class.
+-   The SVM is trained and used to classify all the pixels of the image. This results in a division
+    of the image in a blue region and a green region. The boundary between both regions is the
+    optimal separating hyperplane.
+-   Finally the support vectors are shown using gray rings around the training examples.
+
+![](images/svm_intro_result.png)

modules/ml/tutorials/cpp_ml/non_linear_svms/non_linear_svms.markdown

@@ -0,0 +1,287 @@
+Support Vector Machines for Non-Linearly Separable Data {#tutorial_non_linear_svms}
+=======================================================
+
+@tableofcontents
+
+@prev_tutorial{tutorial_introduction_to_svm}
+
+|    |    |
+| -: | :- |
+| Original author | Fernando Iglesias García |
+| Compatibility | OpenCV >= 3.0 |
+
+Goal
+----
+
+In this tutorial you will learn how to:
+
+-   Define the optimization problem for SVMs when it is not possible to separate linearly the
+    training data.
+-   How to configure the parameters to adapt your SVM for this class of problems.
+
+Motivation
+----------
+
+Why is it interesting to extend the SVM optimization problem in order to handle non-linearly separable
+training data? Most of the applications in which SVMs are used in computer vision require a more
+powerful tool than a simple linear classifier. This stems from the fact that in these tasks __the
+training data can be rarely separated using an hyperplane__.
+
+Consider one of these tasks, for example, face detection. The training data in this case is composed
+by a set of images that are faces and another set of images that are non-faces (_every other thing
+in the world except from faces_). This training data is too complex so as to find a representation
+of each sample (_feature vector_) that could make the whole set of faces linearly separable from the
+whole set of non-faces.
+
+Extension of the Optimization Problem
+-------------------------------------
+
+Remember that using SVMs we obtain a separating hyperplane. Therefore, since the training data is
+now non-linearly separable, we must admit that the hyperplane found will misclassify some of the
+samples. This _misclassification_ is a new variable in the optimization that must be taken into
+account. The new model has to include both the old requirement of finding the hyperplane that gives
+the biggest margin and the new one of generalizing the training data correctly by not allowing too
+many classification errors.
+
+We start here from the formulation of the optimization problem of finding the hyperplane which
+maximizes the __margin__ (this is explained in the previous tutorial (@ref tutorial_introduction_to_svm):
+
+\f[\min_{\beta, \beta_{0}} L(\beta) = \frac{1}{2}||\beta||^{2} \text{ subject to } y_{i}(\beta^{T} x_{i} + \beta_{0}) \geq 1 \text{ } \forall i\f]
+
+There are multiple ways in which this model can be modified so it takes into account the
+misclassification errors. For example, one could think of minimizing the same quantity plus a
+constant times the number of misclassification errors in the training data, i.e.:
+
+\f[\min ||\beta||^{2} + C \text{(misclassification errors)}\f]
+
+However, this one is not a very good solution since, among some other reasons, we do not distinguish
+between samples that are misclassified with a small distance to their appropriate decision region or
+samples that are not. Therefore, a better solution will take into account the _distance of the
+misclassified samples to their correct decision regions_, i.e.:
+
+\f[\min ||\beta||^{2} + C \text{(distance of misclassified samples to their correct regions)}\f]
+
+For each sample of the training data a new parameter \f$\xi_{i}\f$ is defined. Each one of these
+parameters contains the distance from its corresponding training sample to their correct decision
+region. The following picture shows non-linearly separable training data from two classes, a
+separating hyperplane and the distances to their correct regions of the samples that are
+misclassified.
+
+![](images/sample-errors-dist.png)
+
+@note Only the distances of the samples that are misclassified are shown in the picture. The
+distances of the rest of the samples are zero since they lay already in their correct decision
+region.
+
+The red and blue lines that appear on the picture are the margins to each one of the
+decision regions. It is very __important__ to realize that each of the \f$\xi_{i}\f$ goes from a
+misclassified training sample to the margin of its appropriate region.
+
+Finally, the new formulation for the optimization problem is:
+
+\f[\min_{\beta, \beta_{0}} L(\beta) = ||\beta||^{2} + C \sum_{i} {\xi_{i}} \text{ subject to } y_{i}(\beta^{T} x_{i} + \beta_{0}) \geq 1 - \xi_{i} \text{ and } \xi_{i} \geq 0 \text{ } \forall i\f]
+
+How should the parameter C be chosen? It is obvious that the answer to this question depends on how
+the training data is distributed. Although there is no general answer, it is useful to take into
+account these rules:
+
+-   Large values of C give solutions with _less misclassification errors_ but a _smaller margin_.
+    Consider that in this case it is expensive to make misclassification errors. Since the aim of
+    the optimization is to minimize the argument, few misclassifications errors are allowed.
+-   Small values of C give solutions with _bigger margin_ and _more classification errors_. In this
+    case the minimization does not consider that much the term of the sum so it focuses more on
+    finding a hyperplane with big margin.
+
+Source Code
+-----------
+
+You may also find the source code in `ml/samples` folder of the OpenCV source library or
+[download it from here](https://github.com/opencv/opencv_contrib/tree/5.x/modules/ml/samples).
+
+@add_toggle_cpp
+-   **Downloadable code**: Click
+    [here](https://github.com/opencv/opencv/tree/5.x/samples/cpp/tutorial_code/ml/non_linear_svms/non_linear_svms.cpp)
+
+-   **Code at glance:**
+    @include samples/non_linear_svms.cpp
+@end_toggle
+
+@add_toggle_java
+-   **Downloadable code**: Click
+    [here](https://github.com/opencv/opencv_contrib/tree/5.x/modules/ml/samples/java/tutorial_code/ml/non_linear_svms/NonLinearSVMsDemo.java)
+
+-   **Code at glance:**
+    @include samples/java/tutorial_code/ml/non_linear_svms/NonLinearSVMsDemo.java
+@end_toggle
+
+@add_toggle_python
+-   **Downloadable code**: Click
+    [here](https://github.com/opencv/opencv_contrib/tree/5.x/modules/ml/samples/python/tutorial_code/ml/non_linear_svms/non_linear_svms.py)
+
+-   **Code at glance:**
+    @include samples/python/tutorial_code/ml/non_linear_svms/non_linear_svms.py
+@end_toggle
+
+Explanation
+-----------
+
+-   __Set up the training data__
+
+The training data of this exercise is formed by a set of labeled 2D-points that belong to one of
+two different classes. To make the exercise more appealing, the training data is generated
+randomly using a uniform probability density functions (PDFs).
+
+We have divided the generation of the training data into two main parts.
+
+In the first part we generate data for both classes that is linearly separable.
+
+@add_toggle_cpp
+@snippet samples/non_linear_svms.cpp setup1
+@end_toggle
+
+@add_toggle_java
+@snippet samples/java/tutorial_code/ml/non_linear_svms/NonLinearSVMsDemo.java setup1
+@end_toggle
+
+@add_toggle_python
+@snippet samples/python/tutorial_code/ml/non_linear_svms/non_linear_svms.py setup1
+@end_toggle
+
+In the second part we create data for both classes that is non-linearly separable, data that
+overlaps.
+
+@add_toggle_cpp
+@snippet samples/non_linear_svms.cpp setup2
+@end_toggle
+
+@add_toggle_java
+@snippet samples/java/tutorial_code/ml/non_linear_svms/NonLinearSVMsDemo.java setup2
+@end_toggle
+
+@add_toggle_python
+@snippet samples/python/tutorial_code/ml/non_linear_svms/non_linear_svms.py setup2
+@end_toggle
+
+-   __Set up SVM's parameters__
+
+@note In the previous tutorial @ref tutorial_introduction_to_svm there is an explanation of the
+attributes of the class @ref cv::ml::SVM that we configure here before training the SVM.
+
+@add_toggle_cpp
+@snippet samples/non_linear_svms.cpp init
+@end_toggle
+
+@add_toggle_java
+@snippet samples/java/tutorial_code/ml/non_linear_svms/NonLinearSVMsDemo.java init
+@end_toggle
+
+@add_toggle_python
+@snippet samples/python/tutorial_code/ml/non_linear_svms/non_linear_svms.py init
+@end_toggle
+
+There are just two differences between the configuration we do here and the one that was done in
+the previous tutorial (@ref tutorial_introduction_to_svm) that we use as reference.
+
+-   _C_. We chose here a small value of this parameter in order not to punish too much the
+    misclassification errors in the optimization. The idea of doing this stems from the will of
+    obtaining a solution close to the one intuitively expected. However, we recommend to get a
+    better insight of the problem by making adjustments to this parameter.
+
+    @note In this case there are just very few points in the overlapping region between classes.
+    By giving a smaller value to __FRAC_LINEAR_SEP__ the density of points can be incremented and the
+    impact of the parameter _C_ explored deeply.
+
+-   _Termination Criteria of the algorithm_. The maximum number of iterations has to be
+    increased considerably in order to solve correctly a problem with non-linearly separable
+    training data. In particular, we have increased in five orders of magnitude this value.
+
+-   __Train the SVM__
+
+We call the method @ref cv::ml::SVM::train to build the SVM model. Watch out that the training
+process may take a quite long time. Have patiance when your run the program.
+
+@add_toggle_cpp
+@snippet samples/non_linear_svms.cpp train
+@end_toggle
+
+@add_toggle_java
+@snippet samples/java/tutorial_code/ml/non_linear_svms/NonLinearSVMsDemo.java train
+@end_toggle
+
+@add_toggle_python
+@snippet samples/python/tutorial_code/ml/non_linear_svms/non_linear_svms.py train
+@end_toggle
+
+-   __Show the Decision Regions__
+
+The method @ref cv::ml::SVM::predict is used to classify an input sample using a trained SVM. In
+this example we have used this method in order to color the space depending on the prediction done
+by the SVM. In other words, an image is traversed interpreting its pixels as points of the
+Cartesian plane. Each of the points is colored depending on the class predicted by the SVM; in
+dark green if it is the class with label 1 and in dark blue if it is the class with label 2.
+
+@add_toggle_cpp
+@snippet samples/non_linear_svms.cpp show
+@end_toggle
+
+@add_toggle_java
+@snippet samples/java/tutorial_code/ml/non_linear_svms/NonLinearSVMsDemo.java show
+@end_toggle
+
+@add_toggle_python
+@snippet samples/python/tutorial_code/ml/non_linear_svms/non_linear_svms.py show
+@end_toggle
+
+-   __Show the training data__
+
+The method @ref cv::circle is used to show the samples that compose the training data. The samples
+of the class labeled with 1 are shown in light green and in light blue the samples of the class
+labeled with 2.
+
+@add_toggle_cpp
+@snippet samples/non_linear_svms.cpp show_data
+@end_toggle
+
+@add_toggle_java
+@snippet samples/java/tutorial_code/ml/non_linear_svms/NonLinearSVMsDemo.java show_data
+@end_toggle
+
+@add_toggle_python
+@snippet samples/python/tutorial_code/ml/non_linear_svms/non_linear_svms.py show_data
+@end_toggle
+
+-   __Support vectors__
+
+We use here a couple of methods to obtain information about the support vectors. The method
+@ref cv::ml::SVM::getSupportVectors obtain all support vectors. We have used this methods here
+to find the training examples that are support vectors and highlight them.
+
+@add_toggle_cpp
+@snippet samples/non_linear_svms.cpp show_vectors
+@end_toggle
+
+@add_toggle_java
+@snippet samples/java/tutorial_code/ml/non_linear_svms/NonLinearSVMsDemo.java show_vectors
+@end_toggle
+
+@add_toggle_python
+@snippet samples/python/tutorial_code/ml/non_linear_svms/non_linear_svms.py show_vectors
+@end_toggle
+
+Results
+-------
+
+-   The code opens an image and shows the training examples of both classes. The points of one class
+    are represented with light green and light blue ones are used for the other class.
+-   The SVM is trained and used to classify all the pixels of the image. This results in a division
+    of the image in a blue region and a green region. The boundary between both regions is the
+    separating hyperplane. Since the training data is non-linearly separable, it can be seen that
+    some of the examples of both classes are misclassified; some green points lay on the blue region
+    and some blue points lay on the green one.
+-   Finally the support vectors are shown using gray rings around the training examples.
+
+![](images/svm_non_linear_result.png)
+
+You may observe a runtime instance of this on the [YouTube here](https://www.youtube.com/watch?v=vFv2yPcSo-Q).
+
+@youtube{vFv2yPcSo-Q}

modules/ml/tutorials/py_ml/py_knn/py_knn_index.markdown

@@ -0,0 +1,10 @@
+K-Nearest Neighbour {#tutorial_py_knn_index}
+===================
+
+-   @subpage tutorial_py_knn_understanding
+
+    Get a basic understanding of what kNN is
+
+-   @subpage tutorial_py_knn_opencv
+
+    Now let's use kNN in OpenCV for digit recognition OCR

modules/ml/tutorials/py_ml/py_knn/py_knn_opencv/py_knn_opencv.markdown

@@ -0,0 +1,123 @@
+OCR of Hand-written Data using kNN {#tutorial_py_knn_opencv}
+==================================
+
+Goal
+----
+
+In this chapter:
+    -   We will use our knowledge on kNN to build a basic OCR (Optical Character Recognition) application.
+    -   We will try our application on Digits and Alphabets data that comes with OpenCV.
+
+OCR of Hand-written Digits
+--------------------------
+
+Our goal is to build an application which can read handwritten digits. For this we need some
+training data and some test data. OpenCV comes with an image digits.png (in the folder
+opencv/samples/data/) which has 5000 handwritten digits (500 for each digit). Each digit is
+a 20x20 image. So our first step is to split this image into 5000 different digit images. Then for each digit (20x20 image),
+we flatten it into a single row with 400 pixels. That is our feature set, i.e. intensity values of all
+pixels. It is the simplest feature set we can create. We use the first 250 samples of each digit as
+training data, and the other 250 samples as test data. So let's prepare them first.
+@code{.py}
+import numpy as np
+import cv2 as cv
+
+img = cv.imread('digits.png')
+gray = cv.cvtColor(img,cv.COLOR_BGR2GRAY)
+
+# Now we split the image to 5000 cells, each 20x20 size
+cells = [np.hsplit(row,100) for row in np.vsplit(gray,50)]
+
+# Make it into a Numpy array: its size will be (50,100,20,20)
+x = np.array(cells)
+
+# Now we prepare the training data and test data
+train = x[:,:50].reshape(-1,400).astype(np.float32) # Size = (2500,400)
+test = x[:,50:100].reshape(-1,400).astype(np.float32) # Size = (2500,400)
+
+# Create labels for train and test data
+k = np.arange(10)
+train_labels = np.repeat(k,250)[:,np.newaxis]
+test_labels = train_labels.copy()
+
+# Initiate kNN, train it on the training data, then test it with the test data with k=1
+knn = cv.ml.KNearest_create()
+knn.train(train, cv.ml.ROW_SAMPLE, train_labels)
+ret,result,neighbours,dist = knn.findNearest(test,k=5)
+
+# Now we check the accuracy of classification
+# For that, compare the result with test_labels and check which are wrong
+matches = result==test_labels
+correct = np.count_nonzero(matches)
+accuracy = correct*100.0/result.size
+print( accuracy )
+@endcode
+So our basic OCR app is ready. This particular example gave me an accuracy of 91%. One option to
+improve accuracy is to add more data for training, especially for the digits where we had more errors.
+
+Instead of finding
+this training data every time I start the application, I better save it, so that the next time, I can directly
+read this data from a file and start classification. This can be done with the help of some Numpy
+functions like np.savetxt, np.savez, np.load, etc. Please check the NumPy docs for more details.
+@code{.py}
+# Save the data
+np.savez('knn_data.npz',train=train, train_labels=train_labels)
+
+# Now load the data
+with np.load('knn_data.npz') as data:
+    print( data.files )
+    train = data['train']
+    train_labels = data['train_labels']
+@endcode
+In my system, it takes around 4.4 MB of memory. Since we are using intensity values (uint8 data) as
+features, it would be better to convert the data to np.uint8 first and then save it. It takes only
+1.1 MB in this case. Then while loading, you can convert back into float32.
+
+OCR of the English Alphabet
+------------------------
+
+Next we will do the same for the English alphabet, but there is a slight change in data and feature
+set. Here, instead of images, OpenCV comes with a data file, letter-recognition.data in
+opencv/samples/cpp/ folder. If you open it, you will see 20000 lines which may, on first sight, look
+like garbage. Actually, in each row, the first column is a letter which is our label. The next 16 numbers
+following it are the different features. These features are obtained from the [UCI Machine Learning
+Repository](http://archive.ics.uci.edu/ml/). You can find the details of these features in [this
+page](http://archive.ics.uci.edu/ml/datasets/Letter+Recognition).
+
+There are 20000 samples available, so we take the first 10000 as training samples and the remaining
+10000 as test samples. We should change the letters to ascii characters because we can't work with
+letters directly.
+@code{.py}
+import cv2 as cv
+import numpy as np
+
+# Load the data and convert the letters to numbers
+data= np.loadtxt('letter-recognition.data', dtype= 'float32', delimiter = ',',
+                    converters= {0: lambda ch: ord(ch)-ord('A')})
+
+# Split the dataset in two, with 10000 samples each for training and test sets
+train, test = np.vsplit(data,2)
+
+# Split trainData and testData into features and responses
+responses, trainData = np.hsplit(train,[1])
+labels, testData = np.hsplit(test,[1])
+
+# Initiate the kNN, classify, measure accuracy
+knn = cv.ml.KNearest_create()
+knn.train(trainData, cv.ml.ROW_SAMPLE, responses)
+ret, result, neighbours, dist = knn.findNearest(testData, k=5)
+
+correct = np.count_nonzero(result == labels)
+accuracy = correct*100.0/10000
+print( accuracy )
+@endcode
+It gives me an accuracy of 93.22%. Again, if you want to increase accuracy, you can iteratively add
+more data.
+
+Additional Resources
+--------------------
+1. [Wikipedia article on Optical character recognition](https://en.wikipedia.org/wiki/Optical_character_recognition)
+
+Exercises
+---------
+1. Here we used k=5. What happens if you try other values of k? Can you find a value that maximizes accuracy (minimizes the number of errors)?

modules/ml/tutorials/py_ml/py_knn/py_knn_understanding/py_knn_understanding.markdown

@@ -0,0 +1,150 @@
+Understanding k-Nearest Neighbour {#tutorial_py_knn_understanding}
+=================================
+
+Goal
+----
+
+In this chapter, we will understand the concepts of the k-Nearest Neighbour (kNN) algorithm.
+
+Theory
+------
+
+kNN is one of the simplest classification algorithms available for supervised learning. The idea
+is to search for the closest match(es) of the test data in the feature space. We will look into it with the below
+image.
+
+![image](images/knn_theory.png)
+
+In the image, there are two families: Blue Squares and Red Triangles. We refer to each family as
+a **Class**. Their houses are shown in their town map which we call the **Feature Space**. You can consider
+a feature space as a space where all data are projected. For example, consider a 2D coordinate
+space. Each datum has two features, a x coordinate and a y coordinate. You can represent this datum in your 2D
+coordinate space, right? Now imagine that there are three features, you will need 3D space. Now consider N
+features: you need N-dimensional space, right? This N-dimensional space is its feature space.
+In our image, you can consider it as a 2D case with two features.
+
+Now consider what happens if a new member comes into the town and creates a new home, which is shown as the green circle. He
+should be added to one of these Blue or Red families (or *classes*). We call that process, **Classification**. How exactly should this new member be classified? Since we are dealing with kNN, let us apply the algorithm.
+
+One simple method is to check who is his nearest neighbour. From the image, it is clear that it is a member of the Red
+Triangle family. So he is classified as a Red Triangle. This method is called simply **Nearest Neighbour** classification, because classification depends only on the *nearest neighbour*.
+
+But there is a problem with this approach! Red Triangle may be the nearest neighbour, but what if there are also a lot of Blue
+Squares nearby? Then Blue Squares have more strength in that locality than Red Triangles, so
+just checking the nearest one is not sufficient. Instead we may want to check some **k** nearest families. Then whichever family is the majority amongst them, the new guy should belong to that family. In our image, let's take k=3, i.e. consider the 3 nearest
+neighbours. The new member has two Red neighbours and one Blue neighbour (there are two Blues equidistant, but since k=3, we can take only
+one of them), so again he should be added to Red family. But what if we take k=7? Then he has 5 Blue
+neighbours and 2 Red neighbours and should be added to the Blue family. The result will vary with the selected
+value of k. Note that if k is not an odd number, we can get a tie, as would happen in the above case with k=4. We would see that our new member has 2 Red and 2 Blue neighbours as his four nearest neighbours and we would need to choose a method for breaking the tie to perform classification. So to reiterate, this method is called **k-Nearest Neighbour** since
+classification depends on the *k nearest neighbours*.
+
+Again, in kNN, it is true we are considering k neighbours, but we are giving equal importance to
+all, right? Is this justified? For example, take the tied case of k=4. As we can see, the 2
+Red neighbours are actually closer to the new member than the other 2 Blue neighbours, so he is more eligible to be
+added to the Red family. How do we mathematically explain that? We give some weights to each neighbour
+depending on their distance to the new-comer: those who are nearer to him get higher weights, while
+those that are farther away get lower weights. Then we add the total weights of each family separately and classify the new-comer as part of whichever family
+received higher total weights. This is called **modified kNN** or **weighted kNN**.
+
+So what are some important things you see here?
+
+-   Because we have to check
+    the distance from the new-comer to all the existing houses to find the nearest neighbour(s), you need to have information about all of the houses in town, right?  If there are plenty of houses and families, it takes a lot of memory, and also more time for calculation.
+-   There is almost zero time for any kind of "training" or preparation. Our "learning" involves only memorizing (storing) the data, before testing and classifying.
+
+Now let's see this algorithm at work in OpenCV.
+
+kNN in OpenCV
+-------------
+
+We will do a simple example here, with two families (classes), just like above. Then in the next
+chapter, we will do an even better example.
+
+So here, we label the Red family as **Class-0** (so denoted by 0) and Blue family as **Class-1**
+(denoted by 1). We create 25 neighbours or 25 training data, and label each of them as either part of Class-0 or Class-1.
+We can do this with the help of a Random Number Generator from NumPy.
+
+Then we can plot it with the help of Matplotlib. Red neighbours are shown as Red Triangles and Blue
+neighbours are shown as Blue Squares.
+@code{.py}
+import cv2 as cv
+import numpy as np
+import matplotlib.pyplot as plt
+
+# Feature set containing (x,y) values of 25 known/training data
+trainData = np.random.randint(0,100,(25,2)).astype(np.float32)
+
+# Label each one either Red or Blue with numbers 0 and 1
+responses = np.random.randint(0,2,(25,1)).astype(np.float32)
+
+# Take Red neighbours and plot them
+red = trainData[responses.ravel()==0]
+plt.scatter(red[:,0],red[:,1],80,'r','^')
+
+# Take Blue neighbours and plot them
+blue = trainData[responses.ravel()==1]
+plt.scatter(blue[:,0],blue[:,1],80,'b','s')
+
+plt.show()
+@endcode
+You will get something similar to our first image. Since you are using a random number generator, you
+will get different data each time you run the code.
+
+Next initiate the kNN algorithm and pass the trainData and responses to train the kNN. (Underneath the hood, it constructs
+a search tree: see the Additional Resources section below for more information on this.)
+
+Then we will bring one new-comer and classify him as belonging to a family with the help of kNN in OpenCV. Before
+running kNN, we need to know something about our test data (data of new comers). Our data should be a
+floating point array with size \f$number \; of \; testdata \times number \; of \; features\f$. Then we
+find the nearest neighbours of the new-comer. We can specify *k*: how many neighbours we want. (Here we used 3.) It returns:
+
+1.  The label given to the new-comer depending upon the kNN theory we saw earlier. If you want the *Nearest
+    Neighbour* algorithm, just specify k=1.
+2.  The labels of the k-Nearest Neighbours.
+3.  The corresponding distances from the new-comer to each nearest neighbour.
+
+So let's see how it works. The new-comer is marked in green.
+@code{.py}
+newcomer = np.random.randint(0,100,(1,2)).astype(np.float32)
+plt.scatter(newcomer[:,0],newcomer[:,1],80,'g','o')
+
+knn = cv.ml.KNearest_create()
+knn.train(trainData, cv.ml.ROW_SAMPLE, responses)
+ret, results, neighbours ,dist = knn.findNearest(newcomer, 3)
+
+print( "result:  {}\n".format(results) )
+print( "neighbours:  {}\n".format(neighbours) )
+print( "distance:  {}\n".format(dist) )
+
+plt.show()
+@endcode
+I got the following results:
+@code{.py}
+result:  [[ 1.]]
+neighbours:  [[ 1.  1.  1.]]
+distance:  [[ 53.  58.  61.]]
+@endcode
+It says that our new-comer's 3 nearest neighbours are all from the Blue family. Therefore, he is labelled as part of the Blue
+family. It is obvious from the plot below:
+
+![image](images/knn_simple.png)
+
+If you have multiple new-comers (test data), you can just pass them as an array. Corresponding results are also
+obtained as arrays.
+@code{.py}
+# 10 new-comers
+newcomers = np.random.randint(0,100,(10,2)).astype(np.float32)
+ret, results,neighbours,dist = knn.findNearest(newcomer, 3)
+# The results also will contain 10 labels.
+@endcode
+Additional Resources
+--------------------
+
+1.  [NPTEL notes on Pattern Recognition, Chapter
+    11](https://nptel.ac.in/courses/106108057)
+2.  [Wikipedia article on Nearest neighbor search](https://en.wikipedia.org/wiki/Nearest_neighbor_search)
+3.  [Wikipedia article on k-d tree](https://en.wikipedia.org/wiki/K-d_tree)
+
+Exercises
+---------
+1. Try repeating the above with more classes and different choices of k. Does choosing k become harder with more classes in the same 2D feature space?

modules/ml/tutorials/py_ml/py_svm/py_svm_basics/py_svm_basics.markdown

@@ -0,0 +1,134 @@
+Understanding SVM {#tutorial_py_svm_basics}
+=================
+
+Goal
+----
+
+In this chapter
+    -   We will see an intuitive understanding of SVM
+
+Theory
+------
+
+### Linearly Separable Data
+
+Consider the image below which has two types of data, red and blue. In kNN, for a test data, we used
+to measure its distance to all the training samples and take the one with minimum distance. It takes
+plenty of time to measure all the distances and plenty of memory to store all the training-samples.
+But considering the data given in image, should we need that much?
+
+![image](images/svm_basics1.png)
+
+Consider another idea. We find a line, \f$f(x)=ax_1+bx_2+c\f$ which divides both the data to two
+regions. When we get a new test_data \f$X\f$, just substitute it in \f$f(x)\f$. If \f$f(X) > 0\f$, it belongs
+to blue group, else it belongs to red group. We can call this line as **Decision Boundary**. It is
+very simple and memory-efficient. Such data which can be divided into two with a straight line (or
+hyperplanes in higher dimensions) is called **Linear Separable**.
+
+So in above image, you can see plenty of such lines are possible. Which one we will take? Very
+intuitively we can say that the line should be passing as far as possible from all the points. Why?
+Because there can be noise in the incoming data. This data should not affect the classification
+accuracy. So taking a farthest line will provide more immunity against noise. So what SVM does is to
+find a straight line (or hyperplane) with largest minimum distance to the training samples. See the
+bold line in below image passing through the center.
+
+![image](images/svm_basics2.png)
+
+So to find this Decision Boundary, you need training data. Do you need all? NO. Just the ones which
+are close to the opposite group are sufficient. In our image, they are the one blue filled circle
+and two red filled squares. We can call them **Support Vectors** and the lines passing through them
+are called **Support Planes**. They are adequate for finding our decision boundary. We need not
+worry about all the data. It helps in data reduction.
+
+What happened is, first two hyperplanes are found which best represents the data. For eg, blue data
+is represented by \f$w^Tx+b_0 > 1\f$ while red data is represented by \f$w^Tx+b_0 < -1\f$ where \f$w\f$ is
+**weight vector** ( \f$w=[w_1, w_2,..., w_n]\f$) and \f$x\f$ is the feature vector
+(\f$x = [x_1,x_2,..., x_n]\f$). \f$b_0\f$ is the **bias**. Weight vector decides the orientation of decision
+boundary while bias point decides its location. Now decision boundary is defined to be midway
+between these hyperplanes, so expressed as \f$w^Tx+b_0 = 0\f$. The minimum distance from support vector
+to the decision boundary is given by, \f$distance_{support \, vectors}=\frac{1}{||w||}\f$. Margin is
+twice this distance, and we need to maximize this margin. i.e. we need to minimize a new function
+\f$L(w, b_0)\f$ with some constraints which can expressed below:
+
+\f[\min_{w, b_0} L(w, b_0) = \frac{1}{2}||w||^2 \; \text{subject to} \; t_i(w^Tx+b_0) \geq 1 \; \forall i\f]
+
+where \f$t_i\f$ is the label of each class, \f$t_i \in [-1,1]\f$.
+
+### Non-Linearly Separable Data
+
+Consider some data which can't be divided into two with a straight line. For example, consider an
+one-dimensional data where 'X' is at -3 & +3 and 'O' is at -1 & +1. Clearly it is not linearly
+separable. But there are methods to solve these kinds of problems. If we can map this data set with
+a function, \f$f(x) = x^2\f$, we get 'X' at 9 and 'O' at 1 which are linear separable.
+
+Otherwise we can convert this one-dimensional to two-dimensional data. We can use \f$f(x)=(x,x^2)\f$
+function to map this data. Then 'X' becomes (-3,9) and (3,9) while 'O' becomes (-1,1) and (1,1).
+This is also linear separable. In short, chance is more for a non-linear separable data in
+lower-dimensional space to become linear separable in higher-dimensional space.
+
+In general, it is possible to map points in a d-dimensional space to some D-dimensional space
+\f$(D>d)\f$ to check the possibility of linear separability. There is an idea which helps to compute the
+dot product in the high-dimensional (kernel) space by performing computations in the low-dimensional
+input (feature) space. We can illustrate with following example.
+
+Consider two points in two-dimensional space, \f$p=(p_1,p_2)\f$ and \f$q=(q_1,q_2)\f$. Let \f$\phi\f$ be a
+mapping function which maps a two-dimensional point to three-dimensional space as follows:
+
+\f[\phi (p) = (p_{1}^2,p_{2}^2,\sqrt{2} p_1 p_2)
+\phi (q) = (q_{1}^2,q_{2}^2,\sqrt{2} q_1 q_2)\f]
+
+Let us define a kernel function \f$K(p,q)\f$ which does a dot product between two points, shown below:
+
+\f[
+\begin{aligned}
+K(p,q)  = \phi(p).\phi(q) &= \phi(p)^T \phi(q) \\
+                          &= (p_{1}^2,p_{2}^2,\sqrt{2} p_1 p_2).(q_{1}^2,q_{2}^2,\sqrt{2} q_1 q_2) \\
+                          &= p_{1}^2 q_{1}^2 + p_{2}^2 q_{2}^2 + 2 p_1 q_1 p_2 q_2 \\
+                          &= (p_1 q_1 + p_2 q_2)^2 \\
+          \phi(p).\phi(q) &= (p.q)^2
+\end{aligned}
+\f]
+
+It means, a dot product in three-dimensional space can be achieved using squared dot product in
+two-dimensional space. This can be applied to higher dimensional space. So we can calculate higher
+dimensional features from lower dimensions itself. Once we map them, we get a higher dimensional
+space.
+
+In addition to all these concepts, there comes the problem of misclassification. So just finding
+decision boundary with maximum margin is not sufficient. We need to consider the problem of
+misclassification errors also. Sometimes, it may be possible to find a decision boundary with less
+margin, but with reduced misclassification. Anyway we need to modify our model such that it should
+find decision boundary with maximum margin, but with less misclassification. The minimization
+criteria is modified as:
+
+\f[min \; ||w||^2 + C(distance \; of \; misclassified \; samples \; to \; their \; correct \; regions)\f]
+
+Below image shows this concept. For each sample of the training data a new parameter \f$\xi_i\f$ is
+defined. It is the distance from its corresponding training sample to their correct decision region.
+For those who are not misclassified, they fall on their corresponding support planes, so their
+distance is zero.
+
+![image](images/svm_basics3.png)
+
+So the new optimization problem is :
+
+\f[\min_{w, b_{0}} L(w,b_0) = ||w||^{2} + C \sum_{i} {\xi_{i}} \text{ subject to } y_{i}(w^{T} x_{i} + b_{0}) \geq 1 - \xi_{i} \text{ and } \xi_{i} \geq 0 \text{ } \forall i\f]
+
+How should the parameter C be chosen? It is obvious that the answer to this question depends on how
+the training data is distributed. Although there is no general answer, it is useful to take into
+account these rules:
+
+-   Large values of C give solutions with less misclassification errors but a smaller margin.
+    Consider that in this case it is expensive to make misclassification errors. Since the aim of
+    the optimization is to minimize the argument, few misclassifications errors are allowed.
+-   Small values of C give solutions with bigger margin and more classification errors. In this
+    case the minimization does not consider that much the term of the sum so it focuses more on
+    finding a hyperplane with big margin.
+
+Additional Resources
+--------------------
+
+-#  [NPTEL notes on Statistical Pattern Recognition, Chapters
+    25-29](https://nptel.ac.in/courses/117108048)
+Exercises
+---------

modules/ml/tutorials/py_ml/py_svm/py_svm_index.markdown

@@ -0,0 +1,10 @@
+Support Vector Machines (SVM) {#tutorial_py_svm_index}
+=============================
+
+-   @subpage tutorial_py_svm_basics
+
+    Get a basic understanding of what SVM is
+
+-   @subpage tutorial_py_svm_opencv
+
+    Let's use SVM functionalities in OpenCV

modules/ml/tutorials/py_ml/py_svm/py_svm_opencv/py_svm_opencv.markdown

@@ -0,0 +1,56 @@
+OCR of Hand-written Data using SVM {#tutorial_py_svm_opencv}
+==================================
+
+Goal
+----
+
+In this chapter
+
+-   We will revisit the hand-written data OCR, but, with SVM instead of kNN.
+
+OCR of Hand-written Digits
+--------------------------
+
+In kNN, we directly used pixel intensity as the feature vector. This time we will use [Histogram of
+Oriented Gradients](http://en.wikipedia.org/wiki/Histogram_of_oriented_gradients) (HOG) as feature
+vectors.
+
+Here, before finding the HOG, we deskew the image using its second order moments. So we first define
+a function **deskew()** which takes a digit image and deskew it. Below is the deskew() function:
+
+@snippet samples/python/tutorial_code/ml/py_svm_opencv/hogsvm.py deskew
+
+Below image shows above deskew function applied to an image of zero. Left image is the original
+image and right image is the deskewed image.
+
+![image](images/deskew.jpg)
+
+Next we have to find the HOG Descriptor of each cell. For that, we find Sobel derivatives of each
+cell in X and Y direction. Then find their magnitude and direction of gradient at each pixel. This
+gradient is quantized to 16 integer values. Divide this image to four sub-squares. For each
+sub-square, calculate the histogram of direction (16 bins) weighted with their magnitude. So each
+sub-square gives you a vector containing 16 values. Four such vectors (of four sub-squares) together
+gives us a feature vector containing 64 values. This is the feature vector we use to train our data.
+
+@snippet samples/python/tutorial_code/ml/py_svm_opencv/hogsvm.py hog
+
+Finally, as in the previous case, we start by splitting our big dataset into individual cells. For
+every digit, 250 cells are reserved for training data and remaining 250 data is reserved for
+testing. Full code is given below, you also can download it from [here](https://github.com/opencv/opencv/tree/5.x/samples/python/tutorial_code/ml/py_svm_opencv/hogsvm.py):
+
+@include samples/python/tutorial_code/ml/py_svm_opencv/hogsvm.py
+
+This particular technique gave me nearly 94% accuracy. You can try different values for various
+parameters of SVM to check if higher accuracy is possible. Or you can read technical papers on this
+area and try to implement them.
+
+Additional Resources
+--------------------
+
+-#  [Histograms of Oriented Gradients Video](https://www.youtube.com/watch?v=0Zib1YEE4LU)
+
+Exercises
+---------
+
+-#  OpenCV samples contain digits.py which applies a slight improvement of the above method to get
+    improved result. It also contains the reference. Check it and understand it.

modules/ml/tutorials/py_table_of_contents_ml_.markdown

@@ -0,0 +1,11 @@
+Machine Learning (Python) {#tutorial_py_table_of_contents_ml_}
+================
+
+-   @subpage tutorial_py_knn_index
+
+    Learn to use kNN for classification
+    Plus learn about handwritten digit recognition using kNN
+
+-   @subpage tutorial_py_svm_index
+
+    Understand concepts of SVM

modules/ml/tutorials/table_of_content_ml.markdown

@@ -0,0 +1,5 @@
+Machine Learning (C++) {#tutorial_table_of_content_ml}
+========================================================
+
+-   @subpage tutorial_introduction_to_svm
+-   @subpage tutorial_non_linear_svms