Shape Filtering 2d

module demonstrating shape filtering on 2d images More...

module demonstrating shape filtering on 2d images

Overview

This application proceeds to a shape filtering operation from an input image TIFF files cupple (a binary or label image and an optional grey level image) and a filtering formula.

See also

Shape Filtering 2d algorithm

Usage

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

   <application_exe_filename> [--inputGreyImgPath <input_grey_image_file_path>] [--inputBinLabImgPath <input_binary_image_file_path>] [--inputFilterFormula <input_filter_formula>] [--outputImgFilePath <output_image_file_path>]
     
   Arguments:
      --inputGreyImgPath      optional; specifies the name of the TIFF file, from
                              which the input grey level image will be loaded; if not 
                              specified by the user, used input image is loaded from
                              file 
                              <DEV_ROOT>/data/Sample/images/blobs_483x348_UInt8.tif
                          
      --inputBinLabImgPath    optional; specifies the name of the TIFF file, from
                              which the input binary or label image will be loaded; 
                              if not specified by the user, the input image is
                              loaded from file 
                              <DEV_ROOT>/data/Sample/images/blobs_483x348_Binary.tif

       --inputFilterFormula   optional; specifies the formula string used to filter
                              shapes from input binary/label image.
                              if not specified by the user, the input filter formula
                              will be set to
                              Area2dMsr > 800

       --outputImgFilePath    optional; specifies the name of the TIFF file, in
                              which the output filtered image will be saved; if not 
                              specified by the user, the output image file is saved
                              to file
                              <TEMPORARY_IPSDK_DIR>/Sample/shapeFiltering2dImg.tif

Here is a snapshot of default input images used by the application and of corresponding output results with the following filtering criteria Circularity<0.9 and Mean<170:

Central displayed table correspond to the working data used during filtering operation.

Source code documentation

We start by including all the necessary header files:

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

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

// used to process shape 2d filtering
#include <IPSDKIPL/IPSDKIPLShapeAnalysis/Processor/ShapeFiltering2dImg/ShapeFiltering2dImg.h>

// used to manage exceptions possibly thrown by algorithms 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_ShapeFiltering2dImg/Logger/Sample_ShapeFiltering2dImgLog.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 by invoking "ipsdk::core::LibraryInitializer::getInstance().init()". This method must be called before using any entity or function of IPSDK libraries. It returns an object of type ipsdk::core::LibInitResult, that tells us whether the initialization was OK or not. If the initialization failed (because the IPSDK license file was not found, for instance), we notify the user with an appropriate log message, and we close the application.

    // 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_SHAPEFILTERING2DIMG_LOG_WARN(
            [eSample_ShapeFiltering2dImgMessage::eIPSDKLibInitWarn]
            % initRes.getMsg());
        break;
    case ipsdk::core::eLibInitStatus::eLIS_Failed:
        // IPSDK library initialization; notify the user and exit
        SAMPLE_SHAPEFILTERING2DIMG_LOG_ERROR(
            [eSample_ShapeFiltering2dImgMessage::eIPSDKLibInitFailed] % initRes.getMsg());
        return -1;
        break;
    default:
        break;
    }

We then initialize input paths through the call of the "readCmdArguments" function. As its name suggests, it parses the command line to initialize the input and output images files paths, depending on the options specified by the user. The definition of this function is not explained here, because it mainly uses boost functions, and no IPSDK code.

    // read program options from command line, and, if appropriate,
    // initialize input and output images files and used filtering formula
    boost::filesystem::path inputGreyImgPath, inputBinLabImgPath, outputImgPath;
    std::string inputFilterFormula;
    if(!readCmdArguments(argc, argv, inputGreyImgPath, inputBinLabImgPath, inputFilterFormula, outputImgPath))
        return -1;

Once the IPSDK environment correctly initialized, we load our input images from the associated TIFF file.

We then apply the main shape filtering algorithm on input image using input formula string.

    // display a log message in "INFO" level, to notify the user of the current
    // step
    SAMPLE_SHAPEFILTERING2DIMG_LOG_INFO(
        [eSample_ShapeFiltering2dImgMessage::eLoadingInputGreyImgFromTiffFile]
        % inputGreyImgPath.string());

    // opening grey level input image
    ImagePtr pInGreyImg = loadTiffImageFile(inputGreyImgPath);

    // display a log message in "INFO" level, to notify the user of the current
    // step
    SAMPLE_SHAPEFILTERING2DIMG_LOG_INFO(
        [eSample_ShapeFiltering2dImgMessage::eLoadingInputBinLabImgFromTiffFile]
        % inputBinLabImgPath.string());

    // opening binary/label input image
    ImagePtr pInBinLabImg = loadTiffImageFile(inputBinLabImgPath);

    // shape 2d filtering operation
    ImagePtr pOutImg;
    try {

        pOutImg = shapeFiltering2dImg(pInBinLabImg, pInGreyImg, inputFilterFormula);
    } catch(const BaseException& e) {

        SAMPLE_SHAPEFILTERING2DIMG_LOG_ERROR(
            [eSample_ShapeFiltering2dImgMessage::eErrorProcessingFiltering]
            % 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 "outputImgFilePath":

    try {
        // save the resulting image in specified path
        ipsdk::image::file::saveTiffImageFile(outputImgPath, pOutImg);
    } catch(const image::file::IPSDKImageFileException& e) {

        SAMPLE_SHAPEFILTERING2DIMG_LOG_ERROR(
            [eSample_ShapeFiltering2dImgMessage::eErrorSavingImgTiffFile]
            % outputImgPath % 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 final action consists in cleaning the IPSDK environment before exiting. This cleaning operation (call to "ipsdk::core::LibraryInitializer::getInstance().clear()") must be the last call to IPSDK environment. It guarantees in particular that all threads created by IPSDK libraries are complete.

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

See the full source listing