Benchmark application

module demonstrating how to achieve a processing duration benchmark for an IPSDK library algorithm More...

module demonstrating how to achieve a processing duration benchmark for an IPSDK library algorithm

Overview

This application computes the local entropy image on a 2d input image loaded from a given input TIFF file, and saves the result in a given TIFF file.

See also

Local entropy 2d algorithm

Note

The used processing function (local entropy 2d in that case) can be replaced by any other IPSDK algorithm that the user would like to benchmark.

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>] [--inHalfKnlSizeX <input_half_kernel_x_size_value>] [--inHalfKnlSizeY <input_half_kernel_y_size_value>] [--inOptNbClasses <input_number_of_classes>]
     
   Arguments:
      --inputImgFilePath  optional; specifies the name of the TIFF file, from
                          which the 2d 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 2d output image resulting from entropy
                          computation will be saved; if not specified by the
                          user, the output image is saved in file
                          <TEMPORARY_IPSDK_DIR>/Sample/benchmark.tif
                          
      --inHalfKnlSizeX    optional; specifies the half size, along x axis, of
                          kernel used to compute the entropy image; default
                          value equals to 3
                          
      --inHalfKnlSizeY    optional; specifies the half size, along y axis, of
                          kernel used to compute the entropy image; default
                          value equals to 3

      --inOptNbClasses    optional; specifies the number of classes used to
                          compute the entropy image; default
                          value equals to 16

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 initialize output image
#include <IPSDKIPL/IPSDKIPLUtility/Processor/ConvertImg/ConvertImg.h>

// used to compute local entropy on input 2d image
#include <IPSDKIPL/IPSDKIPLStats/Processor/LocalEntropy2dImg/LocalEntropy2dImg.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>

// chronometer class used to retrieve processing duration
#include <IPSDKUtil/Tools/Chrono.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_Benchmark/Logger/Sample_BenchmarkLog.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 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_BENCHMARK_LOG_WARN(
            [eSample_BenchmarkMessage::eIPSDKLibInitWarn]
            % initRes.getMsg());
        break;
    case ipsdk::core::eLibInitStatus::eLIS_Failed:
        // IPSDK library initialization; notify the user and exit
        SAMPLE_BENCHMARK_LOG_ERROR(
            [eSample_BenchmarkMessage::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;

We also declare 2 variables, that will store the half dimensions, in X and Y, of the kernel used to compute the local entropy and a third one that will store the number of classes used during processing.

    // variable storing expected kernel 2d size
    ipsdk::ipUInt32 inHalfKnlSizeX, inHalfKnlSizeY;

    // variable storing expected number of classes
    ipsdk::ipUInt32 inOptNbClasses;

Paths, kernel dimensions values and number of classes value 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, 
                         inHalfKnlSizeX, inHalfKnlSizeY, inOptNbClasses))
        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_BENCHMARK_LOG_ERROR(
            [eSample_BenchmarkMessage::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;
    }

Once all input parameters are initialized, we compute the local entropy image by calling the function "ipsdk::imaproc::stats::localEntropy2dImg".

Note that this call is surrounded by a chronometer start and by the corresponding elapsed time retrieval.

    try {
        // chronometer used to measure processing duration
        ipsdk::Chrono clk;
        clk.start();

        // compute local entropy 2d on input image
        ipsdk::imaproc::stats::localEntropy2dImg(pInImg, inHalfKnlSizeX, inHalfKnlSizeY, inOptNbClasses, pOutImg);

        // retrieve processing duration in seconds
        const ipsdk::ipReal64 duration = clk.stop();

        SAMPLE_BENCHMARK_LOG_INFO(
            [eSample_BenchmarkMessage::eBenchmarkDuration]
            % static_cast<ipsdk::ipUInt32>(1000 * duration));

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

        // one of the 2 previous function calls
        SAMPLE_BENCHMARK_LOG_ERROR(
            [eSample_BenchmarkMessage::eErrorBenchmark]
            % 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 resulting 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_BENCHMARK_LOG_ERROR(
            [eSample_BenchmarkMessage::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:

    ipsdk::core::LibraryInitializer::getInstance().clear();
    return 0;
}

See the full source listing