Shape Analysis 3d

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

module demonstrating shape analysis and measurement in 3d case

Overview

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

See also

Shape Analysis 3d 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>] [--outputCsvResultPath <output csv result path>]
     
   Arguments:
      --inputGreyImgPath      optional; specifies the name of the TIFF file, from
                              which the input 3d grey level image will be loaded; if not 
                              specified by the user, the input image is loaded from
                              file 
                              <DEV_ROOT>/data/Sample/images/blobs3d_483x348x31_UInt8.tif
                          
      --inputBinImgPath       optional; specifies the name of the TIFF file, from
                              which the input 3d binary image will be loaded; if not 
                              specified by the user, the input image is loaded from
                              file 
                              <DEV_ROOT>/data/Sample/images/blobs3d_483x348x31_Binary.tif

       --outputCsvResultPath  optional; specifies the name of the CSV 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/shapeAnalysis3d.csv

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 3d analysis
#include <IPSDKIPL/IPSDKIPLShapeAnalysis/Measure/Geometry/Basic/HolesBasicPolicyMsrParams.h>
#include <IPSDKIPL/IPSDKIPLShapeAnalysis/Measure/Geometry/FormFactor/MaxFeretDiameter/MaxFeretDiameterMsrParams.h>
#include <IPSDKIPL/IPSDKIPLShapeAnalysis/Measure/Geometry/FormFactor/MinFeretDiameter/MinFeretDiameterMsrParams.h>
#include <IPSDKIPL/IPSDKIPLShapeSegmentation/Processor/LabelShapeExtraction3d/LabelShapeExtraction3d.h>
#include <IPSDKIPL/IPSDKIPLAdvancedMorphology/Processor/ConnectedComponent3dImg/ConnectedComponent3dImg.h>
#include <IPSDKIPL/IPSDKIPLShapeAnalysis/Processor/ShapeAnalysis3d/ShapeAnalysis3d.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/3d/Shape3dColl.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_ShapeAnalysis3d/Logger/Sample_ShapeAnalysis3dLog.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_SHAPEANALYSIS3D_LOG_WARN(
            [eSample_ShapeAnalysis3dMessage::eIPSDKLibInitWarn]
            % initRes.getMsg());
        break;
    case ipsdk::core::eLibInitStatus::eLIS_Failed:
        // IPSDK library initialization; notify the user and exit
        SAMPLE_SHAPEANALYSIS3D_LOG_ERROR(
            [eSample_ShapeAnalysis3dMessage::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 csv results paths
    boost::filesystem::path inputGreyImgPath, inputBinImgPath, outputCsvResultPath;
    if(!readCmdArguments(argc, argv, inputGreyImgPath, inputBinImgPath, outputCsvResultPath))
        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 3d).

A contour based version of this 'labeled' image is then processed. User should note that a polyhedral approximation of surfaces is processed during previous step (see Label shape extraction 3d).

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

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

    // opening grey level input image
    ImagePtr pInGreyImg3d = loadTiffImageFile(inputGreyImgPath, eTiffDirectoryMode::eTDM_Volume);

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

    // opening binary input image
    ImagePtr pInBinImg3d = loadTiffImageFile(inputBinImgPath, eTiffDirectoryMode::eTDM_Volume);

    // connected components analysis
    ImagePtr pInLabelImg3d = connectedComponent3dImg(pInBinImg3d);

    // extract contours from connected component (label) image
    Shape3dCollPtr pShape3dColl = labelShapeExtraction3d(pInLabelImg3d);
    
    // define a measure info set
    MeasureInfoSetPtr pMeasureInfoSet = MeasureInfoSet::create3dInstance();
    createMeasureInfo(pMeasureInfoSet, "AreaMinusHoles", "Area3dMsr", createHolesBasicPolicyMsrParams(true));
    createMeasureInfo(pMeasureInfoSet, "AreaWithHoles", "Area3dMsr", createHolesBasicPolicyMsrParams(false));
    createMeasureInfo(pMeasureInfoSet, "VolumeMinusHoles", "Volume3dMsr", createHolesBasicPolicyMsrParams(true));
    createMeasureInfo(pMeasureInfoSet, "VolumeWithHoles", "Volume3dMsr", createHolesBasicPolicyMsrParams(false));
    createMeasureInfo(pMeasureInfoSet, "EquivalentRay", "EquivalentRayMsr");
    createMeasureInfo(pMeasureInfoSet, "SumMsr");
    createMeasureInfo(pMeasureInfoSet, "Convexity", "ConvexityMsr", createHolesBasicPolicyMsrParams(true));
    
    // compute measure on extracted data
    MeasureSetPtr pOutMeasureSet = shapeAnalysis3d(pInGreyImg3d, pShape3dColl, 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 Area3d for example) :

    // retrieve area 3d 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 CSV file format (for example) using following code :

    // display a log message in "INFO" level, to notify the user of the current
    // step
    SAMPLE_SHAPEANALYSIS3D_LOG_INFO(
        [eSample_ShapeAnalysis3dMessage::eSavingOutputCsvResultsFile]
        % outputCsvResultPath.string());

    // save all analysis results to output csv file
    BoolResult bWritten = saveCsvMeasureFile(outputCsvResultPath, *pOutMeasureSet);

    
    if (bWritten == false) {

        SAMPLE_SHAPEANALYSIS3D_LOG_ERROR(
            [eSample_ShapeAnalysis3dMessage::eFailedToSaveCsvResultsFile]
            % outputCsvResultPath.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