Variance 2d

module demonstrating the computation of local variance on a 2d image More...

module demonstrating the computation of local variance on a 2d image

Overview

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

See also

variance 2d 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>] [--inHalfKnlSizeX <input_half_kernel_x_size_value>] [--inHalfKnlSizeY <input_half_kernel_y_size_value>]
     
   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 variance
                          computation will be saved; if not specified by the
                          user, the output image is saved in file
                          <TEMPORARY_IPSDK_DIR>/Sample/variance.tif
                          
      --inHalfKnlSizeX    optional; specifies the half size, along x axis, of
                          kernel used to compute the variance image; default
                          value equals to 1
                          
      --inHalfKnlSizeY    optional; specifies the half size, along y axis, of
                          kernel used to compute the variance image; default
                          value equals to 1

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 compute the variance image
#include <IPSDKIPL/IPSDKIPLStats/Processor/Variance2dImg/Variance2dImg.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_Variance2d/Logger/Sample_Variance2dLog.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:
        SAMPLE_VARIANCE2D_LOG_WARN(
            [eSample_Variance2dMessage::eIPSDKLibInitWarn] % initRes.getMsg());
        break;
    case ipsdk::core::eLibInitStatus::eLIS_Failed:
        SAMPLE_VARIANCE2D_LOG_ERROR(
            [eSample_Variance2dMessage::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 variance

    // variables storing half dimensions of kernel, used to compute the variance
    ipsdk::ipUInt32 inHalfKnlSizeX, inHalfKnlSizeY;

Paths and kernel dimensions 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,
                        inHalfKnlSizeX, inHalfKnlSizeY))
        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_VARIANCE2D_LOG_ERROR(
            [eSample_Variance2dMessage::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 variance image by calling the function "ipsdk::imaproc::stats::variance2dImg".

    // declare the variable that will contain the output image, resulting from
    // variance computation
    ImagePtr pOutImg;
    try {
        // compute image of variance
        pOutImg = ipsdk::imaproc::stats::variance2dImg(pInImg,
            inHalfKnlSizeX, inHalfKnlSizeY);

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

        // one of the 2 previous function calls
        SAMPLE_VARIANCE2D_LOG_ERROR(
            [eSample_Variance2dMessage::eErrorComputingVariance]
            % 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_VARIANCE2D_LOG_ERROR(
            [eSample_Variance2dMessage::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