K-Means

module demonstrating the usage of k-means algorithm on a 2d image More...

module demonstrating the usage of k-means algorithm on a 2d image

Overview

This application classifies the pixels of a given 2d image using K-means algorithm. It also involves, among others, median2dImg, standardizeImg and lawTexture2dImg algorithms

Usage

This is a standalone script file which takes no input argument.

Here is a snapshot of input image used for the following example :

Problem statement

Having a quick look at the input image, the human eye clearly distinguishes 4 distinct types of regions (or classes):

• class #1: the background, dark and textured
• class #2: two bright and textured regions
• class #3: 2 dark and homogeneous regions
• class #4: 1 bright and homogeneous region

However, distinguishing these 4 classes using the k-means algorithm is more complicated than expected: if we simply provide as input of the k-means algorithm the original image, we obtain an image of classes that if far from the expected result (see image below).

image of classes resulting from k-means application using only the image of intensities as input

There are 2 problems with the current input image that prevent us from relying only on the information of intensity:

• means of intensities are equal between class #1 and class #3, and between class #2 and class #4
• standard deviations of intensities in classes #1 and #2 (resp. in classes #3 and #4) are so great that some pixels in class #1 (resp. class #3] have the same intensity that some pixels and class #2 (resp. class #4].

In fact, to do the classification, the human eye implicitly tries to agglomerate neighbouring pixels that share the same properties. In this case, common properties are:

• intensities
• local texture

Using k-means, we can at least rely on the the cunjunction of these 2 properties, provided we feed the algorithm with the appropriate images:

• first, extract local texture information using lawTexture2dImg. In our case, the image seems to give the bests results (see image below, we clearly distinguish the 2 types of textures - classes #1 and #2 on one hand, classes #3 and #4 on the other hand)

  

  R5R5 Law's texture energy map associated to input image
• then, unnoise the input image using the median2dImg filter, to slightly decrease the standard deviation of intensities of each class
• concatenate the unnoised image of intensities with the image resulting from the lawTexture2dImg filter application in a temporal sequence image
• standardize the sequence image, so that the intensity information and the local texture information have the same weight
• pass the standardize sequence image as input of k-means algorithm.

The result is closer from what we can expect, even if it's still not perfect (pixels on the boundary of regiton associated to class #4 are not correctly classified), but some filters applied as post-process (morphologic opening, for instance) can improve the result.

image of classes resulting from sample application execution

Source code documentation

Start by including all the necessary header files:

// --- IPSDK includes
// ------------------

// used to initialize IPSDK environment
#include <IPSDKCore/Config/LibraryInitializer.h>

// used to classify the input image using k-means algorithm
#include <IPSDKIPL/IPSDKIPLClassification/Processor/KMeansImg/KMeansImg.h>

// used to unnoise the input image using the median filter
#include <IPSDKIPL/IPSDKIPLFiltering/Processor/Median2dImg/Median2dImg.h>

// used to standardize the temporal sequence image
#include <IPSDKIPL/IPSDKIPLIntensityTransform/Processor/StandardizeImg/StandardizeImg.h>

// used to extract Law's texture energy map
#include <IPSDKIPL/IPSDKIPLStats/Processor/LawTexture2dImg/LawTexture2dImg.h>

// used to concatenate image of intensities and image of local textures into a temporal sequence of images (format accepted by k-means algorithm)
#include <IPSDKIPL/IPSDKIPLUtility/Processor/AppendSeqImg/AppendSeqImg.h>

// used to convert input image buffer type into real32, to make sequence image homogeneous
#include <IPSDKIPL/IPSDKIPLUtility/Processor/ConvertImg/ConvertImg.h>

// used to manage exceptions possibly thrown by algoritms functions
#include <IPSDKBaseProcessing/Logger/IPSDKBaseProcessingException.h>

// for BaseImageGeometry
#include <IPSDKImage/Geometry/BaseImageGeometry.h>

// for function "geometry2d"
#include <IPSDKImage/Geometry/ImageGeometryInstances.h>

// for ImageGeometryPtr typedef
#include <IPSDKImage/Geometry/ImageGeometryTypes.h>

// for MemoryImage class
#include <IPSDKImage/Image/Memory/MemoryImage.h>

// used to catch exceptions potentially thrown  by functions loadRawImageFile and saveRawImageFile
#include <IPSDKImageFile/Logger/IPSDKImageFileException.h>

// used to read/write an image from/to a RAW file:
#include <IPSDKImageFile/Tiff/TiffImageFileUtils.h>

// used to retrieve usual folders (IPSDK temporary folder, root development folder, etc.)
#include <IPSDKUtil/Tools/LibraryPath.h>

// used to display log messages
#include <Sample/Sample_KMeans/Logger/Sample_KMeansLog.h>

// --- third-party boost includes
// ------------------------------

// boost/filesystem/*: contains functions and classes providing facilities to
// manipulate files and directories, and associated paths
#include <boost/filesystem/path.hpp>
#include <boost/filesystem/convenience.hpp>

// --- third-party log4cplus include
// ---------------------------------

// used to add console as output support of logs
#include <log4cplus/consoleappender.h>

// --- STL include
// ---------------

// for std::cout
#include <iostream>

In the main function body, we start by asking to display all the log messages generated by IPSDK libraries and by our application itself to the application console:

int
main(int argc, char* argv[])
{
    // add console appender for application logs
    log4cplus::SharedAppenderPtr pConsole(new log4cplus::ConsoleAppender);
    log4cplus::Logger::getRoot().addAppender(pConsole);
    log4cplus::Logger::getRoot().setLogLevel(log4cplus::INFO_LOG_LEVEL);

Next, we initialize the IPSDK environment:

    // initialize IPSDK environment (first call to be done before calling any
    // function or using any entity of IPSDK environment)
    const ipsdk::core::LibInitResult initRes =
        ipsdk::core::LibraryInitializer::getInstance().init();

    switch(initRes.getResult().value()) {
    case ipsdk::core::eLibInitStatus::eLIS_Warn:
        // IPSDK library is initialized but there were warnings;
        // notify the user by displaying a message
        SAMPLE_KMEANS_LOG_WARN(
            [eSample_KMeansMessage::eIPSDKLibInitWarn] % initRes.getMsg());
        break;
    case ipsdk::core::eLibInitStatus::eLIS_Failed:
        // IPSDK library initialization; notify the user and exit
        SAMPLE_KMEANS_LOG_ERROR(
            [eSample_KMeansMessage::eIPSDKLibInitFailed] % initRes.getMsg());
        return -1;
        break;
    default:
        break;
    }

Then we declare objects 'inImgFilePath' and 'outImgFilePath':

    // boost objects, used to store input and output images files paths
    boost::filesystem::path inImgFilePath = 
        getIPSDKDirectory(eInternalDirectory::eID_Images) / "sampleKMeansInputImage.tif";
        "Unequalized_Hawkes_Bay_NZ.tif";
    boost::filesystem::path outImgFilePath =
        getIPSDKDefaultDirectory(eDefaultExternalDirectory::eDED_Tmp) / "outClassImg.tif";
    

And we load our input image from the associated TIFF file, by calling the function ipsdk::image::file::loadTiffImageFile.

    // declare the variable that will contain the input image, loaded from
    // TIFF file
    ipsdk::image::ImagePtr pInImg;

    try {
        // read input image from specified path
        pInImg = 
            image::file::loadTiffImageFile(inImgFilePath);
    } catch(const image::file::IPSDKImageFileException& e) {

        // loadTiffImageFile function threw an exception; display error log
        // message
        SAMPLE_KMEANS_LOG_ERROR(
            [eSample_KMeansMessage::eErrorLoadingInputImgFromTiffFile]
            % inImgFilePath.string() % e.getMsg());

        // clear IPSDK environment features; should be called before exiting
        // program
        ipsdk::core::LibraryInitializer::getInstance().clear();

        // quit the application with an exit code indicating an error
        return -1;
    }

We then call the median 2d filter, to unnoise the input image.

    // declare the variable that will contain the output image, resulting from
    // boundary extraction
    ImagePtr pUnnoisedImg;
    try {
        // compute boundary image
        pUnnoisedImg = ipsdk::imaproc::filter::median2dImg(pInImg, 1, 1);

    } catch(const processor::IPSDKBaseProcessingException& e) {

        // median2dImg function threw an exception; display error log
        // message
        SAMPLE_KMEANS_LOG_ERROR(
            [eSample_KMeansMessage::eErrorUnnoisingImg]
            % e.getMsg());

        // clear IPSDK environment features; should be called before exiting
        // program
        ipsdk::core::LibraryInitializer::getInstance().clear();

        // quit the application with an exit code indicating an error
        return -1;
    }

To extract local texture information, we apply Law's texture 2D filter to the input image

    ImagePtr pLawTexImg;

    // initialize Law Texture filter input parameters

    // initialize Law Texture filter input pre-process parameters (use default parameters for this one)
    ipsdk::imaproc::attr::LawTexPreProcParamsPtr pPreProcParams =
        ipsdk::imaproc::attr::createMeanLawTexPreProcParams(7);

    // initialize Law Texture filter input post-process parameters (use default parameters for this one)
    ipsdk::imaproc::attr::LawTexPostProcParamsPtr pPostProcParams =
        ipsdk::imaproc::attr::createMeanAbsLawTexPostProcParams(7);

    // initialize Law Texture filter input kernel types
    // here, only R5R5 Law's texture energy map interests us, so we reset all flags but R5R5 one (remember, all flags are set to True by default)
    ipsdk::imaproc::attr::LawTextureKernel2dTypesPtr pKernelTypes =
        ipsdk::imaproc::attr::createLawTextureKernel2dTypes();
    pKernelTypes->setValue<attr::LawTextureKernel2dTypes::FlagL5E5_E5L5>(false);
    pKernelTypes->setValue<attr::LawTextureKernel2dTypes::FlagL5S5_S5L5>(false);
    pKernelTypes->setValue<attr::LawTextureKernel2dTypes::FlagL5R5_R5L5>(false);
    pKernelTypes->setValue<attr::LawTextureKernel2dTypes::FlagE5E5>(false);
    pKernelTypes->setValue<attr::LawTextureKernel2dTypes::FlagE5S5_S5E5>(false);
    pKernelTypes->setValue<attr::LawTextureKernel2dTypes::FlagE5R5_R5E5>(false);
    pKernelTypes->setValue<attr::LawTextureKernel2dTypes::FlagS5S5>(false);
    pKernelTypes->setValue<attr::LawTextureKernel2dTypes::FlagS5R5_R5S5>(false);

    try {
        // apply Law's texture filter
        pLawTexImg = ipsdk::imaproc::stats::lawTexture2dImg(pInImg, pKernelTypes, pPreProcParams, pPostProcParams);
    }
    catch (const image::file::IPSDKImageFileException& e) {

        SAMPLE_KMEANS_LOG_ERROR(
            [eSample_KMeansMessage::eErrorComputingLawTextureImg]
            % e.getMsg());

        // clear IPSDK environment features; should be called before exiting
        // program
        ipsdk::core::LibraryInitializer::getInstance().clear();

        // quit the application with an exit code indicating an error
        return -1;
    }

Next, we concatenate intensities and local texture images into a temporal sequence image

    ImagePtr pSeqImg;

    try {
        // apply Law's texture filter
        pSeqImg = ipsdk::imaproc::util::appendSeqImg(pLawTexImg, util::convertImg(pUnnoisedImg, eImageBufferType::eIBT_Real32));
    }
    catch (const image::file::IPSDKImageFileException& e) {

        SAMPLE_KMEANS_LOG_ERROR(
            [eSample_KMeansMessage::eErrorAppendingSeqImg]
        % e.getMsg());

        // clear IPSDK environment features; should be called before exiting
        // program
        ipsdk::core::LibraryInitializer::getInstance().clear();

        // quit the application with an exit code indicating an error
        return -1;
    }

The sequence is then standardized, to give the same weight to intensities and to local texture information

    try {
        // standardize the sequence image, to give same weight to intensity information and local texture information
        pSeqImg = ipsdk::imaproc::itrans::standardizeImg(pSeqImg);
    }
    catch (const image::file::IPSDKImageFileException& e) {

        SAMPLE_KMEANS_LOG_ERROR(
            [eSample_KMeansMessage::eErrorStandardizingImg]
        % e.getMsg());

        // clear IPSDK environment features; should be called before exiting
        // program
        ipsdk::core::LibraryInitializer::getInstance().clear();

        // quit the application with an exit code indicating an error
        return -1;
    }

We are now able to launch k-means classifier on the standardized sequence, to classify our image into 4 classes

    boost::shared_ptr<MemoryImage> pOutImg = boost::make_shared<MemoryImage>();
    pOutImg->init(pInImg->getGeometry());

    try {
        // launch classification using k-means algorithm
        const ipUInt32 K = 4;
        ipsdk::imaproc::classif::kMeansImg(pSeqImg, K, 20, 1000, 0.001, pOutImg);
    }
    catch (const image::file::IPSDKImageFileException& e) {

        SAMPLE_KMEANS_LOG_ERROR(
            [eSample_KMeansMessage::eErrorComputingKMeans]
            % e.getMsg());

        // clear IPSDK environment features; should be called before exiting
        // program
        ipsdk::core::LibraryInitializer::getInstance().clear();

        // quit the application with an exit code indicating an error
        return -1;
    }

The output image is then saved to the TIFF file specified in object "outImgFilePath":

    try {
        // save the resulting image in specified path
        ipsdk::image::file::saveTiffImageFile(outImgFilePath, pOutImg);
    } catch(const image::file::IPSDKImageFileException& e) {

        SAMPLE_KMEANS_LOG_ERROR(
            [eSample_KMeansMessage::eErrorSavingImgTiffFile]
            % outImgFilePath % e.getMsg());

        // clear IPSDK environment features; should be called before exiting
        // program
        ipsdk::core::LibraryInitializer::getInstance().clear();

        // quit the application with an exit code indicating an error
        return -1;
    }

Finally, we clean IPSDK environment and exit:

    // clearing IPSDK environment features; should be called before exiting
    // program
    ipsdk::core::LibraryInitializer::getInstance().clear();
    return 0;
}

See the full source listing