Clusters pixels of an input image based on minimum distance, given a set of clusters centroids. More...

IPSDKIPLCLASSIFICATION_API image::ImagePtr	ipsdk::imaproc::classif::kMeansAssignImg (const ipsdk::image::ImageConstPtr &pInImg, const ipsdk::imaproc::attr::ClustersCentersConstPtr &pInClustersCenters)
	wrapper function for Assigns pixels of an input image to clusters given clusters centroids More...

IPSDKIPLCLASSIFICATION_API image::ImagePtr	ipsdk::imaproc::classif::kMeansAssignImg (const ipsdk::image::ImageConstPtr &pInImg, const ipsdk::image::ImageConstPtr &pMaskImg, const ipsdk::imaproc::attr::ClustersCentersConstPtr &pInClustersCenters)
	wrapper function for Assigns pixels of an input image to clusters given clusters centroids More...

IPSDKIPLCLASSIFICATION_API void	ipsdk::imaproc::classif::kMeansAssignImg (const ipsdk::image::ImageConstPtr &pInImg, const ipsdk::imaproc::attr::ClustersCentersConstPtr &pInClustersCenters, const ipsdk::image::ImagePtr &pOutClassImg)
	wrapper function for Assigns pixels of an input image to clusters given clusters centroids More...

IPSDKIPLCLASSIFICATION_API void	ipsdk::imaproc::classif::kMeansAssignImg (const ipsdk::image::ImageConstPtr &pInImg, const ipsdk::image::ImageConstPtr &pMaskImg, const ipsdk::imaproc::attr::ClustersCentersConstPtr &pInClustersCenters, const ipsdk::image::ImagePtr &pOutClassImg)
	wrapper function for Assigns pixels of an input image to clusters given clusters centroids More...

Detailed Description

Clusters pixels of an input image based on minimum distance, given a set of clusters centroids.

This algorithm clusters pixels of an input image to clusters given clusters centroids.

Considering an image of size (x, y, z, c, t) (with x, y and z the sizes respectively along x, y and z-axis, c the number of color channels and t the number of elements in temporal sequence) as a set of x*y*z data vector of c*t dimension, and a set of n clusters of dimensions c*t (n > 1); for each data vector of the image, the algorithm assigns the cluster, the closest centroid to the data vector currently considered, based on the euclidean distance computed between data vectors and centroid vectors, both of dimensions c*t.

Note: This algorithm is also used during the "assignment" step of the K-means algorithm.

Input and output attributes of the algorithm are:

: the input image we want to classify,
: collection of centroids of clusters. Dimensions of clusters centers must equal to $InImg.getSizeC() \times InImg.getSizeT()$ ,
: optional; information stored during the assignment process, such as the sums of data vectors for each cluster, the number of elements of each cluster and the compactness of each cluster. Used by k-means algorithm,
: image of identifiers of clusters for each pixel/voxel (identifiers in range [0..nbClusters-1]; must be a single grey levels image. Its size along x, y and z-axis must equal to InImg sizes along these same axis.

Here is an example of clusters assignment algorithm applied to Lena RGB image, with 4 clusters centers: (223, 136, 126), (61, 3, 28) , (237, 230, 224) and (109, 69, 131):

In this figure, the first label (in black) has a value of 1. The label 0 corresponds to the case where a pixel/voxel has a value of False in the optional input mask image, is provided.

Here is an example of cluster assignment, by taking into account a mask with the centers (223, 136, 126), (61, 3, 28) , (237, 230, 224) and (109, 69, 131). In this case, black pixels in the label image correspond to black pixels in the mask image:

Attributes description

Attribute description for algorithm :

Name	ToolTip	Default Initializer
ipsdk::imaproc::attr::InHomogeneousImg	[Input] Homogeneous image	X
ipsdk::imaproc::attr::InClustersCenters	[Input] centers of clusters	X
ipsdk::imaproc::attr::InOptSingleGreyMaskImg	[Input Optional] Binary image for masking operation for each (x, y, z) coordinate regardless to (c, t) coordinates	X
ipsdk::imaproc::attr::OutOptKMeansAssignmentInfo	[Output Optional] information resulting from assignment step in k-means algorithm	X
ipsdk::imaproc::attr::OutClassImg	[Output] Image of classes	customOutput (_pOutClassImg, outputKMeans(_pInHomogeneousImg,_pInClustersCenters))

Global Rule description

Global rule description for algorithm :
ipsdk::imaproc::matchSize (eMatchImageSizeType::eMIST_3d,_pInHomogeneousImg,_pOutClassImg) &&
ipsdk::imaproc::classif::clustersCentersCollMatchImgSize (_pInClustersCenters,_pInHomogeneousImg) &&
ipsdk::imaproc::customImageProperty (_pOutClassImg,
allowedClassImgBuffersFromNbClusters (_pInClustersCenters)) &&
ipsdk::processor::If (
ipsdk::processor::isSet (_pInOptSingleGreyMaskImg),
ipsdk::imaproc::matchSize (eMatchImageSizeType::eMIST_3d,_pInHomogeneousImg,_pInOptSingleGreyMaskImg),
ipsdk::processor::none ())

Example of Python code :

Example imports

import PyIPSDK

import PyIPSDK.IPSDKIPLClassification as classif

Code Example

    # opening of input image
    inImg = PyIPSDK.loadTiffImageFile(inputImgPath)
    
    # initialize input clusters centers (4 centers of dimension 3)
    inClustersCenters = PyIPSDK.createClustersCenters([223.0, 136.0, 126.0, 61.0, 3.0, 28.0, 237.0, 230.0, 224.0, 109.0, 69.0, 131.0], 3)
    
    # apply assignment algorithm
    outClassImg = classif.kMeansAssignImg(inImg, inClustersCenters)

Example of C++ code :

Example informations

Associated library

IPSDKIPLClassification

Header file

#include <IPSDKIPL/IPSDKIPLClassification/Processor/KMeansAssignImg/KMeansAssignImg.h>

Code Example

    // load input image from file
    ImagePtr pInImg = loadTiffImageFile(inputImgPath);
    
    // load input clusters centers from file
    ClustersCentersPtr pInClustersCenters = boost::make_shared<ClustersCenters>();
    readFromXmlFile(inputClustersCentersPath, *pInClustersCenters);
    // apply clusters assignment algorithm
    const ImagePtr pOutClassImg = classif::kMeansAssignImg(pInImg, pInClustersCenters);

See also: KMeansAssignImgLvl1; KMeansAssignImgLvl2; KMeansAssignImgLvl3

Function Documentation

◆ kMeansAssignImg() [1/4]

IPSDKIPLCLASSIFICATION_API image::ImagePtr ipsdk::imaproc::classif::kMeansAssignImg	(	const ipsdk::image::ImageConstPtr &	pInImg,
		const ipsdk::imaproc::attr::ClustersCentersConstPtr &	pInClustersCenters
	)

wrapper function for Assigns pixels of an input image to clusters given clusters centroids

Exceptions

ipsdk::processor::IPSDKBaseProcessingException on failure

◆ kMeansAssignImg() [2/4]

IPSDKIPLCLASSIFICATION_API image::ImagePtr ipsdk::imaproc::classif::kMeansAssignImg	(	const ipsdk::image::ImageConstPtr &	pInImg,
		const ipsdk::image::ImageConstPtr &	pMaskImg,
		const ipsdk::imaproc::attr::ClustersCentersConstPtr &	pInClustersCenters
	)

wrapper function for Assigns pixels of an input image to clusters given clusters centroids

Exceptions

ipsdk::processor::IPSDKBaseProcessingException on failure

◆ kMeansAssignImg() [3/4]

IPSDKIPLCLASSIFICATION_API void ipsdk::imaproc::classif::kMeansAssignImg	(	const ipsdk::image::ImageConstPtr &	pInImg,
		const ipsdk::imaproc::attr::ClustersCentersConstPtr &	pInClustersCenters,
		const ipsdk::image::ImagePtr &	pOutClassImg
	)

wrapper function for Assigns pixels of an input image to clusters given clusters centroids

Exceptions

ipsdk::processor::IPSDKBaseProcessingException on failure

◆ kMeansAssignImg() [4/4]

IPSDKIPLCLASSIFICATION_API void ipsdk::imaproc::classif::kMeansAssignImg	(	const ipsdk::image::ImageConstPtr &	pInImg,
		const ipsdk::image::ImageConstPtr &	pMaskImg,
		const ipsdk::imaproc::attr::ClustersCentersConstPtr &	pInClustersCenters,
		const ipsdk::image::ImagePtr &	pOutClassImg
	)

wrapper function for Assigns pixels of an input image to clusters given clusters centroids

Exceptions

ipsdk::processor::IPSDKBaseProcessingException on failure