Otsu binarization

module demonstrating the automatic binarization on a grey-level image using Otsu's method More...

module demonstrating the automatic binarization on a grey-level image using Otsu's method

Overview

This application applies Otsu's binarization on a grey-level input image loaded from a given input TIFF file, and saves the result in a given TIFF file.

See also

Otsu binarization algorithm

Usage

The application can be called through a command line as follows:

   <application_exe_filename> [--inputImgFilePath <input_image_file_path>] [--outputImgFilePath <output_image_file_path>]
     
   Arguments:
      --inputImgFilePath  optional; specifies the name of the TIFF file, from
                          which the input image will be loaded; if not 
                          specified by the user, the input image is loaded from
                          file 
                          <DEV_ROOT>/data/Sample/images/Lena_510x509_UInt8.tif
                          
      --outputImgFilePath optional; specifies the name of the TIFF file, in
                          which the output image resulting from the 
                          Otsu's binarization will be saved;
                          if not specified by the user, the output image is 
                          saved in file
                          <TEMPORARY_IPSDK_DIR>/Sample/otsu.tif

Here is a snapshot of default input image used by the application and of corresponding output image when application is launched without any argument:

Source code documentation

The sequence of operations executed in this application is very similar to what is done in Lightness sample application:

Start by including all the necessary header files:

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

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

// used to binarize an image using Otsu's method
#include <IPSDKIPL/IPSDKIPLBinarization/Processor/OtsuThresholdImg/OtsuThresholdImg.h>

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

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

// used to read/write an image from/to a TIFF 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_Otsu/Logger/Sample_OtsuLog.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>

// boost/program_options/*: contains functions and classes used to manage and
// interpret arguments of command line
#include <boost/program_options/cmdline.hpp>
#include <boost/program_options/options_description.hpp>
#include <boost/program_options/parsers.hpp>
#include <boost/program_options/variables_map.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_OTSU_LOG_WARN(
            [eSample_OtsuMessage::eIPSDKLibInitWarn] % initRes.getMsg());
        break;
    case ipsdk::core::eLibInitStatus::eLIS_Failed:
        // IPSDK library initialization; notify the user and exit
        SAMPLE_OTSU_LOG_ERROR(
            [eSample_OtsuMessage::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, outImgFilePath;

Paths and standard deviation values are updated from the command line, by calling function "readCmdArguments":

    // read program options from command line, and, if appropriate,
    // initialize input and output images files paths
    if(!readCmdArguments(argc, argv, inImgFilePath, outImgFilePath))
        return -1;

And we load our input image from the associated TIFF file:

    // 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 = ipsdk::image::file::loadTiffImageFile(inImgFilePath);
    } catch(const image::file::IPSDKImageFileException& e) {

        // loadTiffImageFile function threw an exception; display error log
        // message
        SAMPLE_OTSU_LOG_ERROR(
            [eSample_OtsuMessage::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;
    }

After that, we binarize the input image by calling the function "ipsdk::imaproc::bin::otsuThresholdImg". This function returns an object of type OtsuResult. We store its attribute _pOutImg, of type ImagePtr, in our variable pOutImg.

    // declare the variable that will contain the output image, resulting from
    // otsu binarization
    ImagePtr pOutImg;
    try {
        // binarize input image using Otsu's method
        pOutImg = ipsdk::imaproc::bin::otsuThresholdImg(pInImg)._pOutImg;

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

        // one of the 2 previous function calls
        SAMPLE_OTSU_LOG_ERROR(
            [eSample_OtsuMessage::eErrorComputingOtsu]
            % 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_OTSU_LOG_ERROR(
            [eSample_OtsuMessage::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:

    // display a log message in "INFO" level, to notify the user that the job
    // is successfully done
    SAMPLE_OTSU_LOG_INFO(
        [eSample_OtsuMessage::eSuccessfullyDone]);

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

See the full source listing