Clustering

Overview

This API defines clustering is the automatic and unsupervised combination of unlabelled templates into groups of like templates. What constitutes likeness is heavily dependent on the use case and context in question. One example when dealing with faces is grouping based on identity, where all faces belonging to a single individual are placed in a cluster.

Structs

JaniceClusterId

A unique identifier for a cluster

Signature

typedef size_t JaniceClusterId;

JaniceClusterIds

A structure to represent a list of JaniceClusterId objects.

Fields

Name Type Description
ids JaniceClusterId* An array of cluster id objects.
length size_t The number of elements in ids

JaniceClusterIdsGroup

A structure to represent a list of JaniceClusterIds objects.

Fields

Name Type Description
group JaniceClusterIds* An array of cluster ids objects.
length size_t The number of elements in group

JaniceClusterConfidence

A value representing the confidence that an item belongs to a cluster.

Signature

typedef double JaniceClusterConfidence;

JaniceClusterConfidences

A structure to represent a list of JaniceClusterConfidence objects.

Fields

Name Type Description
confidences JaniceClusterConfidence* An array of cluster confidence objects.
length size_t The number of elements in confidences

JaniceClusterConfidencesGroup

A structure to represent a list of JaniceClusterConfidences objects.

Fields

Name Type Description
group JaniceClusterConfidences* An array of cluster confidences objects.
length size_t The number of elements in group

Function

janice_cluster_media

Cluster a collection of media objects into groups. Each media object may contain 0 or more objects of interest. The output is arranged so that each output structure has N sublists where N is the number of input media and the ith sublist contains information for objects found in the ith media.

Cluster Confidence

Along with a cluster assignment, this API supports the concept of a cluster confidence. A cluster confidence is a value indicating a liklihood that the object of interest actually belongs to a cluster. For example, one possible implementation of a cluster confidence is the negative distance of an object from the cluster centroid. One use case for this value, is for end users to manually scrub cluster results by dynamically orphaning elements with lower confidence values. The cluster confidence is subject to the following contraints:

  1. A higher value indicates greater confidence of cluster membership
  2. No meaning can be assigned to an individual confidence, it is only relevant when being compared with other confidences generated by the same algorithm.

Signature

JANICE_EXPORT JaniceError janice_cluster_media(JaniceMediaIterators media,
                                               JaniceContext context,
                                               JaniceClusterIdsGroup* cluster_ids,
                                               JaniceClusterConfidencesGroup* cluster_confidences,
                                               JaniceTracksGroup* tracks);

Thread Safety

This function is Reentrant.

Parameters

Name Type Description
media JaniceMediaIterators An array of media to cluster.
context JaniceContext A context object with relevant hyperparameters set.
cluster_ids JaniceClusterIdsGroup* An output structure to hold cluster ids. Objects with the same cluster id are members of the same cluster. This structure must have N sublists, where N is the number of elements in media. The ith sublist contains cluster ids for all objects of interest found in the ith media. If no objects of interest are found in a media then the corresponding sublist should have length 0. Internal struct members should be initialized by the implementor as part of the call. The user is required to clear the struct by calling janice_clear_cluster_ids_group.
cluster_confidences JaniceClusterConfidencesGroup* An output structure to hold Cluster Confidence. This structure must have N sublists, where N is the number of elements in media. The ith sublist contains cluster confidences for all objects of interest found in the ith media. The jth confidence in the ith sublist refers to the same object as the jth id in the ith sublist of ids. Internal struct members should be initialized by the implementor as part of the call. The user is required to clear the struct by calling janice_clear_cluster_confidences_group.
tracks JaniceTracksGroup* Location information for each clustered object. This structure must have N sublists, where N is the number of elements in media. The ith sublist contains tracks for all objects of interest found in the ith media. The jth track in the ith sublist refers to the same object as the jth id in the ith sublist of ids and the jth confidence in the ith sublist of confidences. Internal struct members should be initialized by the implementor as part of the call. The user is required to clear the struct by calling janice_clear_tracks_group.

janice_cluster_templates

Cluster a collection of template objects into groups.

Signature

JANICE_EXPORT JaniceError janice_cluster_templates(JaniceTemplates tmpls,
                                                   JaniceContext context,
                                                   JaniceClusterIds* cluster_ids,
                                                   JaniceClusterConfidences* cluster_confidences);

Thread Safety

This function is Reentrant.

Parameters

Name Type Description
tmpls JaniceTemplates An array of templates to cluster. Each template was created with the JaniceCluster role.
context JaniceContext A context object with relevant hyperparameters set.
cluster_ids JaniceClusterIds* An output structure to hold cluster ids. Templates assigned the same cluster id are members of the same cluster. This structure must have the same number of elements as tmpls. The ith cluster id corresponds to the ith template object. Objects that can’t be clustered should be assigned a unique cluster id. Internal struct members should be initialized by the implementor as part of the call. The user is required to clear the struct by calling janice_clear_cluster_ids.
cluster_confidences JaniceClusterConfidences* An output structure to hold Cluster Confidence. This structure must have the same number of elements as tmpls. The ith cluster confidence corresponds to the ith template object. Internal struct members should be initialized by the implementor as part of the call. The user is required to clear the struct by calling janice_clear_cluster_confidences.

janice_clear_cluster_ids

Free any memory associated with a of JaniceClusterIds object.

Signature

JANICE_EXPORT JaniceError janice_clear_cluster_ids(JaniceClusterIds* ids);

Thread Safety

This function is Reentrant.

Parameters

Name Type Description
ids JaniceClusterIds* A cluster ids object to clear.

janice_clear_cluster_ids_group

Free any memory associated with a JaniceClusterIdsGroup object.

Signature

JANICE_EXPORT JaniceError janice_clear_cluster_ids_group(JaniceClusterIdsGroup* group);

Parameters

Name Type Description
group JaniceClusterIdsGroup* A cluster ids group to clear.

janice_clear_cluster_confidences

Free any memory associated with a of JaniceClusterConfidences object.

Signature

JANICE_EXPORT JaniceError janice_clear_cluster_confidences(JaniceClusterConfidences* confidences);

Thread Safety

This function is Reentrant.

Parameters

Name Type Description
confidences JaniceClusterConfidences* A cluster confidences object to clear.

janice_clear_cluster_confidences_group

Free any memory associated with a JaniceClusterConfidencesGroup object.

Signature

JANICE_EXPORT JaniceError janice_clear_cluster_confidences_group(JaniceClusterConfidencesGroup* group);

Parameters

Name Type Description
group JaniceClusterConfidencesGroup* A cluster confidences group to clear.