Skip to content
opencv-wasm

gapi_kmeans

gapifunctionOpenCV 5.0.0
import { gapi_kmeans } from '@banou/opencv-wasm'

Use after await initOpenCV(). See the initialization and named imports guide.

ARGUMENTSdata, K, bestLabels, criteria
FUNCTIONgapi_kmeans
RETURN TYPEtuple_GOpaque_double_and_GMat_and_GMat
Call structure. A void return can still write to destination arguments. The parameter descriptions define inputs, outputs and ownership.

Finds centers of clusters and groups input samples around the clusters.

The function kmeans implements a k-means algorithm that finds the centers of K clusters and groups the input samples around the clusters. As an output, \texttt{bestLabels}_i contains a 0-based cluster index for the i^{th} sample.

Note: - Function textual ID is "org.opencv.core.kmeansND"

  • In case of an N-dimensional points' set given, input GMat can have the following traits: 2 dimensions, a single row or column if there are N channels, or N columns if there is a single channel. Mat should have CV_32F depth.
  • Although, if GMat with height != 1, width != 1, channels != 1 given as data, n-dimensional samples are considered given in amount of A, where A = height, n = width * channels.
  • In case of GMat given as data:
    • the output labels are returned as 1-channel GMat with sizes width = 1, height = A, where A is samples amount, or width = bestLabels.width, height = bestLabels.height if bestLabels given;
    • the cluster centers are returned as 1-channel GMat with sizes width = n, height = K, where n is samples' dimensionality and K is clusters' amount.
  • As one of possible usages, if you want to control the initial labels for each attempt by yourself, you can utilize just the core of the function. To do that, set the number of attempts to 1, initialize labels each time using a custom algorithm, pass them with the ( flags = #KMEANS_USE_INITIAL_LABELS ) flag, and then choose the best (most-compact) clustering.
gapi_kmeans(data: GMat, K: number, bestLabels: GMat, criteria: TermCriteria, attempts: number, flags: number): tuple_GOpaque_double_and_GMat_and_GMat;
data

Data for clustering. An array of N-Dimensional points with float coordinates is needed. Function can take GArray<Point2f>, GArray<Point3f> for 2D and 3D cases or GMat for any dimensionality and channels.

K

Number of clusters to split the set by.

bestLabels

Optional input integer array that can store the supposed initial cluster indices for every sample. Used when ( flags = #KMEANS_USE_INITIAL_LABELS ) flag is set.

criteria

The algorithm termination criteria, that is, the maximum number of iterations and/or the desired accuracy. The accuracy is specified as criteria.epsilon. As soon as each of the cluster centers moves by less than criteria.epsilon on some iteration, the algorithm stops.

attempts

Flag to specify the number of times the algorithm is executed using different initial labellings. The algorithm returns the labels that yield the best compactness (see the first function return value).

flags

Flag that can take values of cv::KmeansFlags .

Returns
  • Compactness measure that is computed as
\sum _i  \| \texttt{samples} _i -  \texttt{centers} _{ \texttt{labels} _i} \| ^2

after every attempt. The best (minimum) value is chosen and the corresponding labels and the compactness value are returned by the function.

  • Integer array that stores the cluster indices for every sample.
  • Array of the cluster centers.

Upstream declaration ↗

These signatures describe this package. Upstream documentation can mention optional backends that are absent from this build. Check runtime compatibility before choosing a backend or file format.