Shape Analysis 2d

module demonstrating shape analysis and measurement in 2d case More...

module demonstrating shape analysis and measurement in 2d case

Overview

This application computes measurements on 2d shapes from an input image TIFF files cupple (a grey level and a binary image).

See also

Shape Analysis 2d algorithm

Usage

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

   <application_exe_filename> [--inputGreyImgPath <input_grey_image_file_path>] [--inputBinImgPath <input_binary_image_file_path>] [--outputXmlResultPath <output xml result 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, the input image is loaded from
                              file 
                              <DEV_ROOT>/data/Sample/images/blobs_483x348_UInt8.tif
                          
      --inputBinImgPath       optional; specifies the name of the TIFF file, from
                              which the input binary 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

       --outputXmlResultPath  optional; specifies the name of the XML file, in
                              which the output analysis results will be saved; if not 
                              specified by the user, the output results file is saved to
                              file 
                              <TEMPORARY_IPSDK_DIR>/Sample/shapeAnalysis2d.xml

Here is a snapshot of default input images used by the application and of corresponding output results when application is launched without any argument:

Note

Connected components (labels) are indexed from left to right and top to bottom.

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 analysis
#include <IPSDKIPL/IPSDKIPLShapeAnalysis/Measure/Geometry/Basic/HolesBasicPolicyMsrParams.h>
#include <IPSDKIPL/IPSDKIPLShapeSegmentation/Processor/LabelShapeExtraction2d/LabelShapeExtraction2d.h>
#include <IPSDKIPL/IPSDKIPLAdvancedMorphology/Processor/ConnectedComponent2dImg/ConnectedComponent2dImg.h>
#include <IPSDKIPL/IPSDKIPLShapeAnalysis/Processor/ShapeAnalysis2d/ShapeAnalysis2d.h>
#include <IPSDKBaseShapeAnalysis/Measure/BaseMeasure.h>
#include <IPSDKBaseShapeAnalysis/Measure/Result/ValueMeasureResult.h>
#include <IPSDKBaseShapeAnalysis/Measure/Result/MeasureResultUtils.h>
#include <IPSDKBaseShapeAnalysis/Measure/Info/MeasureInfoSet.h>
#include <IPSDKBaseShapeAnalysis/Measure/Info/MeasureInfoUtils.h>
#include <IPSDKBaseShapeAnalysis/Measure/MeasureSet.h>
#include <IPSDKBaseShapeSegmentation/Entity/2d/Shape2dColl.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 write a xml shape analysis result file:
#include <IPSDKSerialization/Archive/FileSerializationUtils.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_ShapeAnalysis2d/Logger/Sample_ShapeAnalysis2dLog.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_SHAPEANALYSIS2D_LOG_WARN(
            [eSample_ShapeAnalysis2dMessage::eIPSDKLibInitWarn]
            % initRes.getMsg());
        break;
    case ipsdk::core::eLibInitStatus::eLIS_Failed:
        // IPSDK library initialization; notify the user and exit
        SAMPLE_SHAPEANALYSIS2D_LOG_ERROR(
            [eSample_ShapeAnalysis2dMessage::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 images files and output xml results paths
    boost::filesystem::path inputGreyImgPath, inputBinImgPath, outputXmlResultPath;
    if(!readCmdArguments(argc, argv, inputGreyImgPath, inputBinImgPath, outputXmlResultPath))
        return -1;

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

We then apply a connected components algorithm on input binary image (see Connected Component 2d).

A contour based version of this 'labeled' image is then processed. The user should note that a polygonal approximation of contours is processed during previous step (see Label shape extraction 2d).

At last we define a collection of measures to be processed and we launch the shape analysis (see Shape Analysis 2d).

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

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

    // display a log message in "INFO" level, to notify the user of the current
    // step
    SAMPLE_SHAPEANALYSIS2D_LOG_INFO(
        [eSample_ShapeAnalysis2dMessage::eLoadingInputBinImgFromTiffFile]
        % inputBinImgPath.string());

    // opening binary input image
    ImagePtr pInBinImg2d = loadTiffImageFile(inputBinImgPath);

    // connected components analysis
    ImagePtr pInLabelImg2d = connectedComponent2dImg(pInBinImg2d);

    // extract contours from connected component (label) image
    Shape2dCollPtr pShape2dColl = labelShapeExtraction2d(pInLabelImg2d);

    // define a measure info set
    MeasureInfoSetPtr pMeasureInfoSet = MeasureInfoSet::create2dInstance();
    createMeasureInfo(pMeasureInfoSet, "AreaMinusHoles", "Area2dMsr", createHolesBasicPolicyMsrParams(true));
    createMeasureInfo(pMeasureInfoSet, "AreaWithHoles", "Area2dMsr", createHolesBasicPolicyMsrParams(false));
    createMeasureInfo(pMeasureInfoSet, "EquivalentRay", "EquivalentRayMsr");
    createMeasureInfo(pMeasureInfoSet, "SumMsr");
    
    // compute measure on extracted data
    MeasureSetPtr pOutMeasureSet = shapeAnalysis2d(pInGreyImg2d, pShape2dColl, pMeasureInfoSet);

Measure results can then be individually extracted from returned object MeasureSetPtr pOutMeasureSet as demonstrated by following code (extracted type must match measure results type, see measure result type associated to Area2d for example) :

    // retrieve area 2d results for 'minus holes' parametrization for example
    const MeasureConstPtr& pAreaMinusHolesOutMsr = pOutMeasureSet->getMeasure("AreaMinusHoles");
    const std::vector<ipReal64>& pAreaMinusHolesRes = extractValueResults<ipReal64>(pAreaMinusHolesOutMsr);

Measure results can also be saved to file using XML file format (for example) using following code :

    // display a log message in "INFO" level, to notify the user of the current
    // step
    SAMPLE_SHAPEANALYSIS2D_LOG_INFO(
        [eSample_ShapeAnalysis2dMessage::eSavingOutputXmlResultsFile]
        % outputXmlResultPath.string());

    // save all analysis results to output xml file
    BoolResult bWritten = writeToXmlFile(outputXmlResultPath, *pOutMeasureSet);
    if (bWritten == false) {

        SAMPLE_SHAPEANALYSIS2D_LOG_ERROR(
            [eSample_ShapeAnalysis2dMessage::eFailedToSaveXmlResultsFile]
            % outputXmlResultPath.string() % bWritten.getMsg());

        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