Norm of a gaussian gradient

module demonstrating the computation of the norm of a gaussian gradient on a 2d image More...

module demonstrating the computation of the norm of a gaussian gradient on a 2d image

Overview

This application computes the norm of a gaussian gradient on a 2d input image loaded from a given input TIFF file, and saves the result in a given TIFF file.

See also

euclidian norm algorithm

gaussian 2d gradient 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>] [--stdDev <std_dev_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 the 
                          computation of the norm of the gradient will be saved;
                          if not specified by the user, the output image is 
                          saved in file
                          <TEMPORARY_IPSDK_DIR>/Sample/gradientNorm.tif
      
      
      --stdDev            optional; specifies the value of standard deviation,
                          used to compute the gaussian gradient kernel; if not
                          specified by the user, equals to 3.0 by default

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 norm on 2 images
#include <IPSDKIPL/IPSDKIPLArithmetic/Processor/L2Norm2Img/L2Norm2Img.h>

// used to apply gaussian gradient filter on 2d images
#include <IPSDKIPL/IPSDKIPLFiltering/Processor/GaussianGradient2dImg/GaussianGradient2dImg.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_GradientNorm/Logger/Sample_GradientNormLog.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_GRADIENTNORM_LOG_WARN(
            [eSample_GradientNormMessage::eIPSDKLibInitWarn]
            % initRes.getMsg());
        break;
    case ipsdk::core::eLibInitStatus::eLIS_Failed:
        // IPSDK library initialization; notify the user and exit
        SAMPLE_GRADIENTNORM_LOG_ERROR(
            [eSample_GradientNormMessage::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 a variable that will store the standard deviation used to compute the gaussian kernel (used by the gradient operation) and specified by the user (or its default value if the user did not specify its value).

    // variable storing standard deviation value, used to compute the gaussian
    // gradient kernel
    ipReal32 inStdDev;

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, inStdDev))
        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_GRADIENTNORM_LOG_ERROR(
            [eSample_GradientNormMessage::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 first compute the gaussian gradient of the loaded image by calling the function ipsdk::imaproc::filter::gaussianGradient2dImg. The 2 resulting images (gradient respectively along x and y axis) are stored in variable "gradientXYImg". Then we compute the norm of these 2 images by calling the function "l2Norm2Img". The resulting output image is stored in variable pOutImg.

The call of these 2 functions is enclosed in a try/catch block, to handle the case where an exception is thrown. If an error occurs, a message is displayed to the user, IPSDK environment is cleaned by calling "ipsdk::core::LibraryInitializer::getInstance().clear()" and the application terminates.

    // declare the variable that will contain the output image, resulting from
    // the computation of the norm of the gradient
    ImagePtr pOutImg;
    try {
        // compute the gradient, along the 2 axis, of input image
        filter::GradientXYImg gradientXYImg =
            filter::gaussianGradient2dImg(pInImg, inStdDev);

        // compute the norm of the gradient
        pOutImg = arithm::l2Norm2Img(gradientXYImg._pXGradImg,
                                     gradientXYImg._pYGradImg);

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

        // one of the 2 previous function calls 
        SAMPLE_GRADIENTNORM_LOG_ERROR(
            [eSample_GradientNormMessage::eErrorComputingGradient]
            % 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_GRADIENTNORM_LOG_ERROR(
            [eSample_GradientNormMessage::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