0
# Machine Learning
1

2
OpenCV's Machine Learning module (`cv2.ml`) provides a comprehensive set of statistical machine learning algorithms for classification, regression, and clustering tasks. These tools enable pattern recognition, data analysis, and predictive modeling directly within the OpenCV framework.
3

4
The module includes both traditional machine learning algorithms (SVM, KNN, decision trees) and neural networks, all designed to work seamlessly with OpenCV's matrix data structures and image processing capabilities.
5

6
## Capabilities
7

8
### StatModel Base Class
9

10
The `StatModel` class serves as the base class for all statistical models in OpenCV's ML module, providing a unified interface for training, prediction, and model persistence.
11

12
```python { .api }
13
# Core methods available on all StatModel subclasses
14

15
# Train the model
16
StatModel.train(samples, layout, responses) -> retval
17

18
# Make predictions
19
StatModel.predict(samples[, results[, flags]]) -> retval, results
20

21
# Save trained model to file
22
StatModel.save(filename) -> None
23

24
# Load model from file (class method)
25
StatModel.load(filename) -> model
26

27
# Calculate prediction error
28
StatModel.calcError(data, test) -> retval, resp
29

30
# Check if model is trained
31
StatModel.isTrained() -> retval
32

33
# Check if model is a classifier
34
StatModel.isClassifier() -> retval
35

36
# Get number of variables
37
StatModel.getVarCount() -> retval
38
```
39

40
**Training Data Layouts:**
41
- `cv2.ml.ROW_SAMPLE` - Each row represents a training sample
42
- `cv2.ml.COL_SAMPLE` - Each column represents a training sample
43

44
### Support Vector Machines (SVM)
45

46
Support Vector Machines are powerful supervised learning algorithms used for classification and regression. They work by finding the optimal hyperplane that maximally separates different classes in high-dimensional space.
47

48
```python { .api }
49
# Create SVM instance
50
cv2.ml.SVM_create() -> svm
51

52
# Configure SVM
53
SVM.setType(val) -> None
54
SVM.getType() -> retval
55

56
SVM.setKernel(val) -> None
57
SVM.getKernel() -> retval
58

59
SVM.setDegree(val) -> None
60
SVM.getDegree() -> retval
61

62
SVM.setGamma(val) -> None
63
SVM.getGamma() -> retval
64

65
SVM.setCoef0(val) -> None
66
SVM.getCoef0() -> retval
67

68
SVM.setC(val) -> None
69
SVM.getC() -> retval
70

71
SVM.setNu(val) -> None
72
SVM.getNu() -> retval
73

74
SVM.setP(val) -> None
75
SVM.getP() -> retval
76

77
# Get support vectors
78
SVM.getSupportVectors() -> retval
79

80
# Get decision function
81
SVM.getDecisionFunction(i) -> retval, alpha, svidx
82

83
# Automatic parameter optimization
84
SVM.trainAuto(samples, layout, responses[, kFold[, ...]])
85
```
86

87
**SVM Types:**
88
```python { .api }
89
cv2.ml.SVM_C_SVC          # C-Support Vector Classification
90
cv2.ml.SVM_NU_SVC         # Nu-Support Vector Classification
91
cv2.ml.SVM_ONE_CLASS      # One-class SVM (anomaly detection)
92
cv2.ml.SVM_EPS_SVR        # Epsilon-Support Vector Regression
93
cv2.ml.SVM_NU_SVR         # Nu-Support Vector Regression
94
```
95

96
**Kernel Types:**
97
```python { .api }
98
cv2.ml.SVM_LINEAR         # Linear kernel: u'*v
99
cv2.ml.SVM_POLY           # Polynomial kernel: (gamma*u'*v + coef0)^degree
100
cv2.ml.SVM_RBF            # Radial Basis Function: exp(-gamma*|u-v|^2)
101
cv2.ml.SVM_SIGMOID        # Sigmoid kernel: tanh(gamma*u'*v + coef0)
102
cv2.ml.SVM_CHI2           # Chi-square kernel
103
cv2.ml.SVM_INTER          # Histogram intersection kernel
104
```
105

106
### K-Nearest Neighbors (KNearest)
107

108
K-Nearest Neighbors is a simple, instance-based learning algorithm that classifies samples based on the majority vote of their k nearest neighbors in the feature space.
109

110
```python { .api }
111
# Create KNN instance
112
cv2.ml.KNearest_create() -> knearest
113

114
# Set number of neighbors
115
KNearest.setDefaultK(val) -> None
116
KNearest.getDefaultK() -> retval
117

118
# Set algorithm type
119
KNearest.setAlgorithmType(val) -> None
120
KNearest.getAlgorithmType() -> retval
121

122
# Set E parameter for KDTREE
123
KNearest.setEmax(val) -> None
124
KNearest.getEmax() -> retval
125

126
# Set if classifier
127
KNearest.setIsClassifier(val) -> None
128
KNearest.getIsClassifier() -> retval
129

130
# Find nearest neighbors
131
KNearest.findNearest(samples, k[, results[, ...]]) -> retval, results, neighborResponses, dist
132
```
133

134
**Algorithm Types:**
135
```python { .api }
136
cv2.ml.KNearest_BRUTE_FORCE    # Brute force search
137
cv2.ml.KNearest_KDTREE          # KD-tree for efficient search
138
```
139

140
### Decision Trees (DTrees)
141

142
Decision Trees recursively split data based on feature values, creating a tree-like model of decisions. They are interpretable and can handle both numerical and categorical data.
143

144
```python { .api }
145
# Create decision tree instance
146
cv2.ml.DTrees_create() -> dtree
147

148
# Configure tree parameters
149
DTrees.setMaxDepth(val) -> None
150
DTrees.getMaxDepth() -> retval
151

152
DTrees.setMinSampleCount(val) -> None
153
DTrees.getMinSampleCount() -> retval
154

155
DTrees.setMaxCategories(val) -> None
156
DTrees.getMaxCategories() -> retval
157

158
DTrees.setCVFolds(val) -> None
159
DTrees.getCVFolds() -> retval
160

161
DTrees.setUseSurrogates(val) -> None
162
DTrees.getUseSurrogates() -> retval
163

164
DTrees.setUse1SERule(val) -> None
165
DTrees.getUse1SERule() -> retval
166

167
DTrees.setTruncatePrunedTree(val) -> None
168
DTrees.getTruncatePrunedTree() -> retval
169

170
# Set pruning parameters
171
DTrees.setPriors(val) -> None
172
DTrees.getPriors() -> retval
173

174
# Get the tree structure
175
DTrees.getRoots() -> retval
176
DTrees.getNodes() -> retval
177
DTrees.getSplits() -> retval
178
DTrees.getSubsets() -> retval
179
```
180

181
### Random Forest (RTrees)
182

183
Random Forest is an ensemble learning method that constructs multiple decision trees during training and outputs the mode of their predictions, providing better accuracy and robustness than single trees.
184

185
```python { .api }
186
# Create random trees instance
187
cv2.ml.RTrees_create() -> rtrees
188

189
# Configure forest parameters
190
RTrees.setMaxDepth(val) -> None
191
RTrees.getMaxDepth() -> retval
192

193
RTrees.setMinSampleCount(val) -> None
194
RTrees.getMinSampleCount() -> retval
195

196
RTrees.setMaxCategories(val) -> None
197
RTrees.getMaxCategories() -> retval
198

199
# Random forest specific parameters
200
RTrees.setActiveVarCount(val) -> None
201
RTrees.getActiveVarCount() -> retval
202

203
RTrees.setTermCriteria(val) -> None
204
RTrees.getTermCriteria() -> retval
205

206
RTrees.setCalculateVarImportance(val) -> None
207
RTrees.getCalculateVarImportance() -> retval
208

209
# Get variable importance
210
RTrees.getVarImportance() -> retval
211

212
# Get votes from individual trees
213
RTrees.getVotes(samples, flags) -> retval
214
```
215

216
### Boosting (Boost)
217

218
Boosting algorithms combine multiple weak learners (typically decision trees) into a strong classifier by iteratively training new models to correct errors made by previous ones.
219

220
```python { .api }
221
# Create boosting instance
222
cv2.ml.Boost_create() -> boost
223

224
# Configure boosting parameters
225
Boost.setBoostType(val) -> None
226
Boost.getBoostType() -> retval
227

228
Boost.setWeakCount(val) -> None
229
Boost.getWeakCount() -> retval
230

231
Boost.setWeightTrimRate(val) -> None
232
Boost.getWeightTrimRate() -> retval
233

234
# Inherits decision tree parameters
235
Boost.setMaxDepth(val) -> None
236
Boost.getMaxDepth() -> retval
237

238
Boost.setMinSampleCount(val) -> None
239
Boost.getMinSampleCount() -> retval
240

241
Boost.setMaxCategories(val) -> None
242
Boost.getMaxCategories() -> retval
243

244
Boost.setPriors(val) -> None
245
Boost.getPriors() -> retval
246
```
247

248
**Boosting Types:**
249
```python { .api }
250
cv2.ml.Boost_DISCRETE      # Discrete AdaBoost
251
cv2.ml.Boost_REAL          # Real AdaBoost
252
cv2.ml.Boost_LOGIT         # LogitBoost
253
cv2.ml.Boost_GENTLE        # Gentle AdaBoost
254
```
255

256
### Neural Networks (ANN_MLP)
257

258
Multi-Layer Perceptron (MLP) is a feedforward artificial neural network with one or more hidden layers. It can learn complex non-linear relationships through backpropagation training.
259

260
```python { .api }
261
# Create neural network instance
262
cv2.ml.ANN_MLP_create() -> ann
263

264
# Configure network architecture
265
ANN_MLP.setLayerSizes(layerSizes) -> None
266
ANN_MLP.getLayerSizes() -> retval
267

268
# Set activation function
269
ANN_MLP.setActivationFunction(type[, param1[, param2]]) -> None
270

271
# Configure training parameters
272
ANN_MLP.setTrainMethod(method[, param1[, param2]]) -> None
273
ANN_MLP.getTrainMethod() -> retval
274

275
ANN_MLP.setBackpropWeightScale(val) -> None
276
ANN_MLP.getBackpropWeightScale() -> retval
277

278
ANN_MLP.setBackpropMomentumScale(val) -> None
279
ANN_MLP.getBackpropMomentumScale() -> retval
280

281
ANN_MLP.setRpropDW0(val) -> None
282
ANN_MLP.getRpropDW0() -> retval
283

284
ANN_MLP.setRpropDWPlus(val) -> None
285
ANN_MLP.getRpropDWPlus() -> retval
286

287
ANN_MLP.setRpropDWMinus(val) -> None
288
ANN_MLP.getRpropDWMinus() -> retval
289

290
ANN_MLP.setRpropDWMin(val) -> None
291
ANN_MLP.getRpropDWMin() -> retval
292

293
ANN_MLP.setRpropDWMax(val) -> None
294
ANN_MLP.getRpropDWMax() -> retval
295

296
ANN_MLP.setAnnealInitialT(val) -> None
297
ANN_MLP.getAnnealInitialT() -> retval
298

299
ANN_MLP.setAnnealFinalT(val) -> None
300
ANN_MLP.getAnnealFinalT() -> retval
301

302
ANN_MLP.setAnnealCoolingRatio(val) -> None
303
ANN_MLP.getAnnealCoolingRatio() -> retval
304

305
ANN_MLP.setAnnealItePerStep(val) -> None
306
ANN_MLP.getAnnealItePerStep() -> retval
307

308
# Set termination criteria
309
ANN_MLP.setTermCriteria(val) -> None
310
ANN_MLP.getTermCriteria() -> retval
311

312
# Get network weights
313
ANN_MLP.getWeights(layerIdx) -> retval
314
```
315

316
**Activation Functions:**
317
```python { .api }
318
cv2.ml.ANN_MLP_IDENTITY        # Identity: f(x) = x
319
cv2.ml.ANN_MLP_SIGMOID_SYM     # Symmetric sigmoid: f(x) = beta*(1-exp(-alpha*x))/(1+exp(-alpha*x))
320
cv2.ml.ANN_MLP_GAUSSIAN        # Gaussian: f(x) = beta*exp(-alpha*x*x)
321
cv2.ml.ANN_MLP_RELU            # ReLU: f(x) = max(0, x)
322
cv2.ml.ANN_MLP_LEAKYRELU       # Leaky ReLU: f(x) = x if x >= 0 else alpha*x
323
```
324

325
**Training Methods:**
326
```python { .api }
327
cv2.ml.ANN_MLP_BACKPROP        # Backpropagation
328
cv2.ml.ANN_MLP_RPROP           # Resilient backpropagation (RProp)
329
cv2.ml.ANN_MLP_ANNEAL          # Simulated annealing
330
```
331

332
**Training Flags:**
333
```python { .api }
334
cv2.ml.ANN_MLP_UPDATE_WEIGHTS     # Update network weights
335
cv2.ml.ANN_MLP_NO_INPUT_SCALE     # Do not normalize input
336
cv2.ml.ANN_MLP_NO_OUTPUT_SCALE    # Do not normalize output
337
```
338

339
### Naive Bayes (NormalBayesClassifier)
340

341
Normal Bayes Classifier assumes that features follow a normal (Gaussian) distribution and applies Bayes' theorem for classification. It's simple, fast, and works well when the assumption holds.
342

343
```python { .api }
344
# Create Naive Bayes classifier instance
345
cv2.ml.NormalBayesClassifier_create() -> bayes
346

347
# Train and predict using StatModel interface
348
# NormalBayesClassifier.train(samples, layout, responses) -> retval
349
# NormalBayesClassifier.predict(samples) -> retval, results
350

351
# Predict with probabilities
352
NormalBayesClassifier.predictProb(inputs[, outputs[, ...]]) -> retval, outputs, outputProbs
353
```
354

355
### Logistic Regression (LogisticRegression)
356

357
Logistic Regression is a linear model for binary and multi-class classification that estimates the probability of class membership using a logistic function.
358

359
```python { .api }
360
# Create logistic regression instance
361
cv2.ml.LogisticRegression_create() -> lr
362

363
# Configure learning parameters
364
LogisticRegression.setLearningRate(val) -> None
365
LogisticRegression.getLearningRate() -> retval
366

367
LogisticRegression.setIterations(val) -> None
368
LogisticRegression.getIterations() -> retval
369

370
LogisticRegression.setRegularization(val) -> None
371
LogisticRegression.getRegularization() -> retval
372

373
LogisticRegression.setTrainMethod(val) -> None
374
LogisticRegression.getTrainMethod() -> retval
375

376
LogisticRegression.setMiniBatchSize(val) -> None
377
LogisticRegression.getMiniBatchSize() -> retval
378

379
# Get learned coefficients
380
LogisticRegression.get_learnt_thetas() -> retval
381
```
382

383
**Regularization Types:**
384
```python { .api }
385
cv2.ml.LogisticRegression_REG_DISABLE    # No regularization
386
cv2.ml.LogisticRegression_REG_L1         # L1 regularization (Lasso)
387
cv2.ml.LogisticRegression_REG_L2         # L2 regularization (Ridge)
388
```
389

390
**Training Methods:**
391
```python { .api }
392
cv2.ml.LogisticRegression_BATCH          # Batch gradient descent
393
cv2.ml.LogisticRegression_MINI_BATCH     # Mini-batch gradient descent
394
```
395

396
### Expectation Maximization (EM)
397

398
The EM algorithm is used for finding maximum likelihood estimates of parameters in probabilistic models with latent variables. It's commonly used for Gaussian Mixture Models and clustering.
399

400
```python { .api }
401
# Create EM instance
402
cv2.ml.EM_create() -> em
403

404
# Configure EM parameters
405
EM.setClustersNumber(val) -> None
406
EM.getClustersNumber() -> retval
407

408
EM.setCovarianceMatrixType(val) -> None
409
EM.getCovarianceMatrixType() -> retval
410

411
EM.setTermCriteria(val) -> None
412
EM.getTermCriteria() -> retval
413

414
# Train the model
415
EM.trainEM(samples[, logLikelihoods[, labels[, probs]]]) -> retval, logLikelihoods, labels, probs
416

417
EM.trainE(samples, means0[, covs0[, weights0[, ...]]]) -> retval, logLikelihoods, labels, probs
418

419
EM.trainM(samples, probs0[, logLikelihoods[, labels[, probs]]]) -> retval, logLikelihoods, labels, probs
420

421
# Get model parameters
422
EM.getWeights() -> retval
423
EM.getMeans() -> retval
424
EM.getCovs() -> retval
425

426
# Predict cluster and probability
427
EM.predict(samples[, results[, flags]]) -> retval, results
428
EM.predict2(sample) -> retval, probs
429
```
430

431
**Covariance Matrix Types:**
432
```python { .api }
433
cv2.ml.EM_COV_MAT_SPHERICAL    # Spherical covariance matrix (single variance)
434
cv2.ml.EM_COV_MAT_DIAGONAL     # Diagonal covariance matrix
435
cv2.ml.EM_COV_MAT_GENERIC      # Full covariance matrix
436
cv2.ml.EM_COV_MAT_DEFAULT      # Default covariance matrix type
437
```
438

439
**Start Step:**
440
```python { .api }
441
cv2.ml.EM_START_E_STEP         # Start with E-step
442
cv2.ml.EM_START_M_STEP         # Start with M-step
443
cv2.ml.EM_START_AUTO_STEP      # Automatically choose start step
444
```
445

446
### K-means Clustering
447

448
K-means is a clustering algorithm that partitions data into K clusters by iteratively assigning samples to the nearest cluster center and updating centers based on assigned samples.
449

450
```python { .api }
451
# Perform K-means clustering
452
cv2.kmeans(data, K, bestLabels, criteria, attempts, flags) -> retval, bestLabels, centers
453

454
# Parameters:
455
#   data - Input data (each row is a sample)
456
#   K - Number of clusters
457
#   bestLabels - Output labels (cluster assignments)
458
#   criteria - Termination criteria (type, max_iter, epsilon)
459
#   attempts - Number of times algorithm is run with different initial labelings
460
#   flags - Initialization method
461
```
462

463
**K-means Flags:**
464
```python { .api }
465
cv2.KMEANS_RANDOM_CENTERS      # Random initialization of cluster centers
466
cv2.KMEANS_PP_CENTERS          # K-means++ initialization (smart seeding)
467
cv2.KMEANS_USE_INITIAL_LABELS  # Use provided initial labels
468
```
469

470
**Termination Criteria:**
471
```python { .api }
472
# Create termination criteria
473
cv2.TermCriteria(type, maxCount, epsilon)
474

475
# Termination types (can be combined with bitwise OR):
476
cv2.TermCriteria_COUNT         # Stop after maxCount iterations
477
cv2.TermCriteria_EPS           # Stop when accuracy (epsilon) is reached
478
cv2.TermCriteria_MAX_ITER      # Alias for COUNT
479
```
480

481
### Training Data Preparation
482

483
```python { .api }
484
# Create training data container
485
cv2.ml.TrainData_create(samples, layout, responses[, ...]) -> trainData
486

487
# Access training data properties
488
TrainData.getLayout() -> retval
489
TrainData.getNTrainSamples() -> retval
490
TrainData.getNTestSamples() -> retval
491
TrainData.getNSamples() -> retval
492
TrainData.getNVars() -> retval
493
TrainData.getNAllVars() -> retval
494

495
# Get data splits
496
TrainData.getTrainSamples([, layout[, ...]]) -> retval
497
TrainData.getTestSamples() -> retval
498
TrainData.getTrainResponses() -> retval
499
TrainData.getTestResponses() -> retval
500

501
# Data sampling and splitting
502
TrainData.setTrainTestSplit(count[, shuffle]) -> None
503
TrainData.setTrainTestSplitRatio(ratio[, shuffle]) -> None
504
TrainData.shuffleTrainTest() -> None
505

506
# Variable types and missing data
507
TrainData.getVarType() -> retval
508
TrainData.setVarType(var_idx, type) -> None
509
TrainData.getMissing() -> retval
510
TrainData.getDefaultSubstValues() -> retval
511
```
512

513
**Variable Types:**
514
```python { .api }
515
cv2.ml.VAR_NUMERICAL          # Numerical (continuous) variable
516
cv2.ml.VAR_ORDERED            # Ordered categorical variable
517
cv2.ml.VAR_CATEGORICAL        # Unordered categorical variable
518
```
519

520
### Stochastic Gradient Descent SVM
521

522
```python { .api }
523
# Create SGD-based SVM instance
524
cv2.ml.SVMSGD_create() -> svmsgd
525

526
# Configure SGD parameters
527
SVMSGD.setOptimalParameters([, svmsgdType[, marginType]]) -> None
528

529
SVMSGD.setSvmsgdType(svmsgdType) -> None
530
SVMSGD.getSvmsgdType() -> retval
531

532
SVMSGD.setMarginType(marginType) -> None
533
SVMSGD.getMarginType() -> retval
534

535
SVMSGD.setMarginRegularization(marginRegularization) -> None
536
SVMSGD.getMarginRegularization() -> retval
537

538
SVMSGD.setInitialStepSize(InitialStepSize) -> None
539
SVMSGD.getInitialStepSize() -> retval
540

541
SVMSGD.setStepDecreasingPower(stepDecreasingPower) -> None
542
SVMSGD.getStepDecreasingPower() -> retval
543

544
SVMSGD.setTermCriteria(val) -> None
545
SVMSGD.getTermCriteria() -> retval
546

547
# Get decision function weights
548
SVMSGD.getWeights() -> retval
549
SVMSGD.getShift() -> retval
550
```
551

552
**SVMSGD Types:**
553
```python { .api }
554
cv2.ml.SVMSGD_SGD             # Stochastic Gradient Descent
555
cv2.ml.SVMSGD_ASGD            # Average Stochastic Gradient Descent
556
```
557

558
**Margin Types:**
559
```python { .api }
560
cv2.ml.SVMSGD_SOFT_MARGIN     # Soft margin (allows some misclassification)
561
cv2.ml.SVMSGD_HARD_MARGIN     # Hard margin (no misclassification allowed)
562
```
563

564
### Model Evaluation
565

566
```python { .api }
567
# Common evaluation patterns for all models
568

569
# Calculate prediction error on test set
570
error = model.calcError(test_data, test_flag)
571

572
# Get predictions with additional information
573
retval, results = model.predict(samples)
574

575
# For classifiers, check accuracy
576
correct_predictions = np.sum(predictions == ground_truth)
577
accuracy = correct_predictions / len(ground_truth)
578
```
579

580
**Prediction Flags:**
581
```python { .api }
582
cv2.ml.StatModel_RAW_OUTPUT        # Return raw output values
583
cv2.ml.StatModel_COMPRESSED_INPUT  # Input is compressed
584
cv2.ml.StatModel_PREPROCESSED_INPUT # Input is preprocessed
585
cv2.ml.StatModel_UPDATE_MODEL       # Update model during prediction
586
```
587