Masking

module demonstrating the image masking operation More...

module demonstrating the image masking operation

Overview

This application applies a binary mask on an input image and saves the result in a given TIFF file. Input image and binary mask are loaded from given TIFF files.

See also

masking algorithm

Usage

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

   <application_exe_filename> [--inputImgFilePath <input_image_file_path>] [--maskImgFilePath <mask_image_file_path] [--outputImgFilePath <output_image_file_path>]
     
   Arguments:
      --inputImgFilePath  optional; specifies the path 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
                          
      --maskImgFilePath    optional; specifies the path of the TIFF file, from
                           which the binary image of mask will be loaded; if not
                           specified by the user, the input image is loaded from
                           file
                           <DEV_ROOT>/data/Sample/iamges/binary_mask.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/mask.tif

Here is a snapshot of default input and mask images 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 mask input image
#include <IPSDKIPL/IPSDKIPLLogical/Processor/MaskImg/MaskImg.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_Mask/Logger/Sample_MaskLog.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_MASK_LOG_WARN(
            [eSample_MaskMessage::eIPSDKLibInitWarn]
            % initRes.getMsg());
        break;
    case ipsdk::core::eLibInitStatus::eLIS_Failed:
        // IPSDK library initialization; notify the user and exit
        SAMPLE_MASK_LOG_ERROR(
            [eSample_MaskMessage::eIPSDKLibInitFailed] % initRes.getMsg());
        return -1;
        break;
    default:
        break;
    }

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

    // boost objects, used to store input and output images files paths
    boost::filesystem::path inImgFilePath, maskImgFilePath, outImgFilePath;

Paths 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, maskImgFilePath,
                         outImgFilePath))
        return -1;

And we load input image and binary mask image from the associated TIFF files:

    // 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_MASK_LOG_ERROR(
            [eSample_MaskMessage::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;
    }

    // display a log message in "INFO" level, to notify the user of the current
    // step
    SAMPLE_MASK_LOG_INFO(
        [eSample_MaskMessage::eLoadingMaskImgFromTiffFile]
        % maskImgFilePath.string());

    // declare the variable storing the image of mask
    ipsdk::image::ImagePtr pMaskImg;
    try {
        pMaskImg = ipsdk::image::file::loadTiffImageFile(maskImgFilePath);
    } catch(const image::file::IPSDKImageFileException& e) {

        // loadTiffImageFile function threw an exception; display error log
        // message
        SAMPLE_MASK_LOG_ERROR(
            [eSample_MaskMessage::eErrorLoadingMaskImgFromTiffFile]
            % maskImgFilePath.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 input and mask images are loaded, we apply the masking operation, by calling "ipsdk::imaproc::logic::maskImg" function. The resulting output image is stored in variable pOutImg.

The call of this function 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 mask application
    ImagePtr pOutImg;
    try {
        // apply mask to input image
        pOutImg = ipsdk::imaproc::logic::maskImg(pInImg, pMaskImg);

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

        // one of the 2 previous function calls
        SAMPLE_MASK_LOG_ERROR(
            [eSample_MaskMessage::eErrorApplyingMask]
            % 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_MASK_LOG_ERROR(
            [eSample_MaskMessage::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