Clusterer Workflow

This code snippet demonstrates how the Clusterer module is typically used. Note that error handling is left out for clarity.

Initialization

Initialize Clusterer parameters with default values.

dwClustererParams clusteringParams{};
dwClusterer_initParams(&clusteringParams);

The initialization of Clustering module requires the following clustering parameters to be defined.

// Set DBSCAN clustering parameters
clusteringParams.maxSampleCount = 1000;

This parameter defines the maximum number of samples the Clustering module should expect as input at once. This allows the module to pre-allocate resources at initialization time.

clusteringParams.epsilon = 0.2;

In Clustering module, there are bounding boxes which are defined to be “core” which represent the cluster. Epsilon is the maximum distance for a box to be considered an element of a cluster to the core of that cluster.

clusteringParams.minSamples = 0;

Defines the minimum number of boxes required to form a dense region. minSamples and minSumOfWeights are checked conjunctively.

clusteringParams.minSumOfWeights = 0.5;

Defines the minimum sum of weights required to form a dense region. minSamples and minSumOfWeights are checked conjunctively.

Initialize Clusterer module.

dwClustererHandle_t clustererHandle = DW_NULL_HANDLE;
dwClusterer_initialize(&clustererHandle, &clusteringParams, contextHandle);

Allocate a list of bounding boxes to store the inputs of clustering.

dwRect *inputBoxes = new dwRect[clusteringParams.maxSampleCount];
float32_t *inputWeights = new float32_t[clusteringParams.maxSampleCount];
uint32_t numInputBoxes = 0U;

Allocate a list of bounding boxes to store the outputs of clustering.

int32_t *clusterLabels = new int32_t[clusteringParams.maxSampleCount];
uint32_t numClusterLabels = 0U;
uint32_t numClusters = 0U;

Bind input & output to the clusterer module.

dwClusterer_bindInput(&inputBoxes, &inputWeights, &numInputBoxes, clustererHandle);

This function enables binding input to the Clusterer module by providing the pointers to an array of bounding boxes, to an array of weights and to number of bounding boxes to be clustered. Once the input is bound via this function, the changes to the input will be reflected in the Clustering module.

dwClusterer_bindOutput(&clusterLabels, &numClusterLabels, &numClusters, clustererHandle);

This function enables binding output to the Clusterer module by providing the pointers to an array of cluster labels, to number of cluster labels and to number of clusters. Once the output is bound via this function, the content of the output will be updated by the Clusterer module every time dwClusterer_process() is called.

clusterLabels parameter contains the label index for each input sample in inputBoxes parameter in dwClusterer_bindInput() in the same order. If a bounding box does not belong to a cluster, its clusterLabel is set to -1. Otherwise, clusters are labeled as [0, clusterCount).

clusterLabelCount is the number of labels in the array, and it is expected to be the same as boxesCount in bindInput.

numClusters is the number of clusters, i.e. number of unique labels except -1.

Run clustering algorithm.

while isRun()
{
    // Run a process to update inputBoxes
    fillInputBoxes(inputBoxes, inputWeights, numInputBoxes);

    // Run clustering.
    // This call reads the input from the variables bound via 
    // dwClusterer_bindInput() and updates the variables bound via dwClusterer_bindOutput().
    dwClusterer_process(clustererHandle);

    // Read clustering labels
    for (uint32_t boxIdx = 0U; boxIdx < numInputBoxes; ++boxIdx)
    {
        int32_t label = clusterLabels[boxIdx];
        if (label < 0)
        {
            std::cout << "Sample at " << boxIdx << " does not belong to any cluster." << std::endl;
        }
        else 
        {
            std::cout << "Sample at " << boxIdx << " belongs to cluster with id " << label;
        }
    }   
}

Note

Clustering is performed on CPU.

Free previously allocated memory.

// Free resources
delete[] inputBoxes;
delete[] inputWeights;
delete[] clusterLabels;
dwClusterer_release(&clustererHandle);