Quantification on 2d images

tutorial for basic 2d quantification process More...

tutorial for basic 2d quantification process

Overview

This script introduce basics for 2d quantification problems resolution using IPSDK library. The following figure presents such problems :

It presents some classical processing steps used during 2d quantification :

• filtering
• segmentation
• shape analysis

Usage

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

   <application_exe_filename> [--inputImgFilePath <input_image_file_path>] [--outputReportPath <output_report_file_path>] [--inHalfKnlSize <half_kernel_size>] [--inSpaceSigma <space_sigma_value>] [--inDilateFactor <dilate_factor>]
     
   Arguments:
      --inputImgFilePath  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
                          
      --outputReportPath  optional; specifies the name of the CSV file, in
                          which the output quantification will be saved; if not 
                          specified by the user, the output results file is saved to
                          file <TEMPORARY_IPSDK_DIR>/Sample/quantification2d.csv

      --inHalfKnlSize     optional; specifies the value of half kernel size along each axis,
                          used while applying the mean smoothing filter; if not
                          specified by the user, equals to 3 by default

      --inSpaceSigma      optional; specifies the value of the spatial Gaussian standard deviation,
                          used while applying the 2d separated bilateral filter; if not
                          specified by the user, equals to 8 by default

      --inDilateFactor    optional; specifies the value of the dilation factor
                          used while applying the 2d watershed-based binary separation; if not
                          specified by the user, equals to 5 by default

Source code documentation

We start by importing all necessary libraries:

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

// used to initialize IPSDK environment
#include <IPSDKCore/Config/LibraryInitializer.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 compute the separated bilateral 2d smoothing
#include <IPSDKIPL/IPSDKIPLFiltering/Processor/SeparatedBilateral2dImg/SeparatedBilateral2dImg.h>

// used to compute the Otsu threshold
#include <IPSDKIPL/IPSDKIPLBinarization/Processor/OtsuThresholdImg/OtsuThresholdImg.h>

// used to compte the 2d binary watershed separation
#include <IPSDKIPL/IPSDKIPLAdvancedMorphology/Processor/WatershedBinarySeparation2dImg/WatershedBinarySeparation2dImg.h>

// used to compute the connected component analysis
#include <IPSDKIPL/IPSDKIPLAdvancedMorphology/Processor/ConnectedComponent2dImg/ConnectedComponent2dImg.h>

// used to compute the 2d label contour extraction
#include <IPSDKIPL/IPSDKIPLShapeSegmentation/Processor/LabelShapeExtraction2d/LabelShapeExtraction2d.h>

// used to compute measures on shapes
#include <IPSDKIPL/IPSDKIPLShapeAnalysis/Processor/ShapeAnalysis2d/ShapeAnalysis2d.h>

// used for saveCsvMeasureFile
#include <IPSDKBaseShapeAnalysis/Measure/Result/MeasureResultUtils.h>

// used for create2dInstance
#include <IPSDKBaseShapeAnalysis/Measure/Info/MeasureInfoSet.h>

// used for createMeasureInfo
#include <IPSDKBaseShapeAnalysis/Measure/Info/MeasureInfoUtils.h>

// used for the getMeasure() method
#include <IPSDKBaseShapeAnalysis/Measure/MeasureSet.h>

// used to specify the maxFeretDiameter measure parameters
#include <IPSDKIPL/IPSDKIPLShapeAnalysis/Measure/Geometry/FormFactor/MaxFeretDiameter/MaxFeretDiameterMsrParams.h>

// used to retrieve the results of the Area2d measure
#include <IPSDKIPL/IPSDKIPLShapeAnalysis/Measure/Geometry/Basic/Area2d/Area2dMsr.h>

// used to display log messages
#include <Sample/Sample_Quantification2d/Logger/Sample_Quantification2dLog.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_QUANTIFICATION2D_LOG_WARN(
            [eSample_Quantification2dMessage::eIPSDKLibInitWarn]
            % initRes.getMsg());
        break;
    case ipsdk::core::eLibInitStatus::eLIS_Failed:
        // IPSDK library initialization; notify the user and exit
        SAMPLE_QUANTIFICATION2D_LOG_ERROR(
            [eSample_Quantification2dMessage::eIPSDKLibInitFailed] % initRes.getMsg());
        return -1;
        break;
    default:
        break;
    }

Then, we define the input image file path, the output CSV file path and the other parameter values.

    // boost objects, used to store input and output files pathes
    boost::filesystem::path inputImgPath, outputReportPath;
    ipUInt32 inHalfKnlSize;
    ipReal32 inDilateFactor;
    ipReal64 inSpaceSigma;

We then read the arguments of the command line :

    // read program options from command line, and, if appropriate,
    // initialize input and output images files paths
    if(!readCmdArguments(argc, argv, inputImgPath, outputReportPath, inHalfKnlSize, inSpaceSigma, inDilateFactor)) {
        // clear IPSDK environment features; should be called before exiting
        // program
        ipsdk::core::LibraryInitializer::getInstance().clear();

        return -1;
    }

We load the input image from the associated TIFF file, by calling the function ipsdk::image::file::loadTiffImageFile.

    // declare the variable that will contain the input image, loaded from TIFF file
    ipsdk::image::ImagePtr pInGreyImg;
    try {
        // read input image from specified path
        pInGreyImg = ipsdk::image::file::loadTiffImageFile(inputImgPath);
    } catch(const image::file::IPSDKImageFileException& e) {

        // loadTiffImageFile function threw an exception; display error log
        // message
        SAMPLE_QUANTIFICATION2D_LOG_ERROR(
            [eSample_Quantification2dMessage::eErrorLoadingInputImgFromTiffFile]
            % inputImgPath.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;
    }

The first step consists in input image filtering to remove noise. In this tutorial we use Separated bilateral smoothing 2d filter. The good choice of used filter is a quite difficult task since it is dependent on input image type and on searched shapes.

At this step, the user will have to make a choice which is generally the result of successive try. See Filtering image operations for a list of available filters. There is no universal solution for that step, the user could nevertheless be interested in following questions :

• should the filter preserve, enhance or destroy edges ?
• should the filter behave as a low pass filter (smooth of homogeneous area ) ?

    // filtering of input image to smooth defaults
    ipsdk::image::ImagePtr pGreyFilteredImg = ipsdk::imaproc::filter::separatedBilateral2dImg(pInGreyImg, 3, 8);

Once the input image is filtered, we process to an automatic image binarization. In this tutorial we use Otsu Threshold binarization filter.

    // auto threshold on filtered image
    ipsdk::imaproc::bin::OtsuResult otsuResult = ipsdk::imaproc::bin::otsuThresholdImg(pGreyFilteredImg);
    ipsdk::image::file::saveTiffImageFile(binImgPath/"binImg.tif", otsuResult._pOutImg);

Please note in previous image connected area enhanced by red circles. During the next step, we will automatically separate these areae using a binary separation technic based on watershed algorithm (Watershed Binary Separation 2d).

    // automatic separation of binary shapes
    ipsdk::image::ImagePtr pBinSepImg =
        ipsdk::imaproc::advmorpho::watershedBinarySeparation2dImg(otsuResult._pOutImg, inDilateFactor,
                                                                  ipsdk::imaproc::attr::eWatershedSeparationMode::eWSM_Split);
    ipsdk::image::file::saveTiffImageFile(binImgPath/"binSepImg.tif", pBinSepImg);

Once all shape separated, we can proceed to a connected components analysis (Connected Component 2d) :

    // connected components analysis of separated binary image
    ipsdk::image::ImagePtr pLabelImg = ipsdk::imaproc::advmorpho::connectedComponent2dImg(pBinSepImg);
    ipsdk::image::file::saveTiffImageFile(binImgPath/"labelImg.tif", pLabelImg);

And then to the extraction of associated contours (LabelContourExtraction2d_Grp) :

    // extraction of contours from connected components image
    ipsdk::shape::segmentation::Shape2dCollPtr pShape2dColl = ipsdk::imaproc::shape::segmentation::labelShapeExtraction2d(pLabelImg);

We can now define a collection of measures that should be computed on extracted shapes (see Shape Analysis and Measurement for a complete list of available measures) :

    // definition of measure set on shapes
    ipsdk::shape::analysis::MeasureInfoSetPtr pMeasureInfoSet2d = ipsdk::shape::analysis::MeasureInfoSet::create2dInstance();
    createMeasureInfo(pMeasureInfoSet2d, "Area2dMsr");
    //createMeasureInfo(pMeasureInfoSet2d, "EquivalentRayMsr");
    //createMeasureInfo(pMeasureInfoSet2d, "AspectRatioMsr"/*, createAspectRatioMsrParams(180)*/);
    createMeasureInfo(pMeasureInfoSet2d, "Barycenter2dMsr");
    createMeasureInfo(pMeasureInfoSet2d, "HistogramMostPopulatedGLMsr");
    //createMeasureInfo(pMeasureInfoSet2d, "MaxFeretDiameterMsr", ipsdk::imaproc::shape::analysis::createMaxFeretDiameterMsrParams(180));
    //createMeasureInfo(pMeasureInfoSet2d, "MeanMsr");

And finally compute these measures :

    // shape analysis computation
    ipsdk::shape::analysis::MeasureSetPtr pMeasureSet = ipsdk::imaproc::shape::analysis::shapeAnalysis2d(pInGreyImg,  pShape2dColl,  pMeasureInfoSet2d);

At last, we save the measurement report into a csv format.

    // save report in csv format
    ipsdk::shape::analysis::saveCsvMeasureFile(outputReportPath, *pMeasureSet);

Data can also be directly accessed by using the following syntax :

    // retrieve area measure results
    const ipsdk::shape::analysis::MeasureConstPtr& pArea2dOutMsr = pMeasureSet->getMeasure("Area2dMsr");
    const ipsdk::shape::analysis::ValueMeasureResult<ipReal64>& outAreaMsrResults = 
        static_cast<const ipsdk::shape::analysis::ValueMeasureResult<ipReal64>&>(pArea2dOutMsr->getMeasureResult());

    // extract associated results collection
    const std::vector<ipReal64> areaValues = outAreaMsrResults.getColl();

    // access to the first label area
    const ipReal64 firstLabelArea = areaValues[1];

See the full source listing