Quantification on 3d volumes

tutorial for basic 3d quantification process More...

tutorial for basic 3d quantification process

Overview

This script introduces basics for 3d quantification problems resolution using the IPSDK library.

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

• filtering
• segmentation
• shape analysis

Note

Illustrations are presented in a 2d case in the 2d quantification sample tutorial.

Usage

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

   <application_exe_filename> [--inputImg3dFilePath <input_3d_image_file_path>] [--outputReportPath <output_report_file_path>] [--inHalfKnlSize <half_kernel_size>] [--inSpaceSigma <space_sigma_value>] [--inDilateFactor <dilate_factor>]
     
   Arguments:
      --inputImg3dFilePath  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/blobs3d_483x348x31_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/quantification3d.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 3d 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 3d 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 3d smoothing
#include <IPSDKIPL/IPSDKIPLFiltering/Processor/SeparatedBilateral3dImg/SeparatedBilateral3dImg.h>

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

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

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

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

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

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

// used for create3dInstance
#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 Area3d measure
#include <IPSDKIPL/IPSDKIPLShapeAnalysis/Measure/Geometry/Basic/Area3d/Area3dMsr.h>

// used to display log messages
#include <Sample/Sample_Quantification3d/Logger/Sample_Quantification3dLog.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_QUANTIFICATION3D_LOG_WARN(
            [eSample_Quantification3dMessage::eIPSDKLibInitWarn]
            % initRes.getMsg());
        break;
    case ipsdk::core::eLibInitStatus::eLIS_Failed:
        // IPSDK library initialization; notify the user and exit
        SAMPLE_QUANTIFICATION3D_LOG_ERROR(
            [eSample_Quantification3dMessage::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, ipsdk::image::file::eTiffDirectoryMode::eTDM_Volume);
    } catch(const image::file::IPSDKImageFileException& e) {

        // loadTiffImageFile function threw an exception; display error log
        // message
        SAMPLE_QUANTIFICATION3D_LOG_ERROR(
            [eSample_Quantification3dMessage::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 3d 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::separatedBilateral3dImg(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);

During the next step, we will automatically separate these particles using a binary separation technic based on watershed algorithm (Watershed Binary Separation 3d).

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

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

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

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

    // definition of measure set on shapes
    ipsdk::shape::analysis::MeasureInfoSetPtr pMeasureInfoSet3d = ipsdk::shape::analysis::MeasureInfoSet::create3dInstance();
    createMeasureInfo(pMeasureInfoSet3d, "Area3dMsr");
    createMeasureInfo(pMeasureInfoSet3d, "EquivalentRayMsr");
    createMeasureInfo(pMeasureInfoSet3d, "MaxFeretDiameterMsr", ipsdk::imaproc::shape::analysis::createMaxFeretDiameterMsrParams(180));
    createMeasureInfo(pMeasureInfoSet3d, "MeanMsr");

We can now compute these measures :

    // extract contours from connected component (label) image
    ipsdk::shape::segmentation::Shape3dCollPtr pShape3dColl = ipsdk::imaproc::shape::segmentation::labelShapeExtraction3d(pLabelImg);

    // shape analysis computation
    ipsdk::shape::analysis::MeasureSetPtr pMeasureSet = ipsdk::imaproc::shape::analysis::shapeAnalysis3d(pInGreyImg,  pShape3dColl,  pMeasureInfoSet3d);

We note that unlike the 2d quantification sample, the shapes are not explicitly extracted from the labelled image. Instead, a smart version of the Shape Analysis 3d function is used. It extracts only the usefull shape information to compute the measures. Even if it is possible to explicitly extract the shapes from the labelled image, this approach is preferable since the shapes polyhedral approximation is computed only if it is required to compute a measure.

Lastly, 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& pArea3dOutMsr = pMeasureSet->getMeasure("Area3dMsr");
    const ipsdk::shape::analysis::ValueMeasureResult<ipReal64>& outAreaMsrResults = 
        static_cast<const ipsdk::shape::analysis::ValueMeasureResult<ipReal64>&>(pArea3dOutMsr->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