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_script_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 dilatation 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:

import os
import sys, getopt
import PyIPSDK
import PyIPSDK.IPSDKIPLFiltering as filter
import PyIPSDK.IPSDKIPLBinarization as bin
import PyIPSDK.IPSDKIPLAdvancedMorphology as advmorpho
import PyIPSDK.IPSDKIPLShapeAnalysis as shapeanalysis

Then we define the input parameters.

    # retrieve program parameters
    inputImgPath, outputReportPath, inHalfKnlSize, inSpaceSigma, inDilateFactor = readCmdArguments(argv)

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

    # opening of input image
    greyImg = PyIPSDK.loadTiffImageFile(inputImgPath, PyIPSDK.eTiffDirectoryMode.eTDM_Volume)

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
    greyFilteredImg = filter.separatedBilateral3dImg(greyImg, 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
    binImg,  threshold = bin.otsuThresholdImg(greyFilteredImg)
    PyIPSDK.saveTiffImageFile(os.path.join(tmpPath, "binImg.tif"), binImg)

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
    binSepImg = advmorpho.watershedBinarySeparation3dImg(binImg, 5, PyIPSDK.eWatershedSeparationMode.eWSM_Split)
    PyIPSDK.saveTiffImageFile(os.path.join(tmpPath, "binSepImg.tif"), binSepImg)

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

    # connected components analysis of separated binary image
    labelImg = advmorpho.connectedComponent3dImg(binSepImg)
    PyIPSDK.saveTiffImageFile(os.path.join(tmpPath, "labelImg.tif"), labelImg)

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 a geometric calibration (if available)
    geometricCalibration = PyIPSDK.createGeometricCalibration3d(0.01, 0.02, 0.05, "mm");

    # definition of measure set on shapes
    measureInfoSet3d = PyIPSDK.createMeasureInfoSet3d(geometricCalibration);
    PyIPSDK.createMeasureInfo(measureInfoSet3d, "Area3dMsr");
    PyIPSDK.createMeasureInfo(measureInfoSet3d, "EquivalentRayMsr");
    PyIPSDK.createMeasureInfo(measureInfoSet3d, "MaxFeretDiameterMsr",  shapeanalysis.createMaxFeretDiameterMsrParams(180));
    PyIPSDK.createMeasureInfo(measureInfoSet3d, "MeanMsr");

We can now compute these measures :

    # shape analysis computation
    measureSet = shapeanalysis.labelAnalysis3d(greyImg, labelImg, measureInfoSet3d)

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
    print("Saving measure report in file " + outputReportPath)
    PyIPSDK.saveCsvMeasureFile(outputReportPath, measureSet)

Data can also be directly accessed through python using the following syntax :

    # retrieve area measure results
    areaMsrResults = measureSet.getMeasure("Area3dMsr").getMeasureResult()

    # extract associated results collection
    areaValues = areaMsrResults.getColl(0)
    print("First label area equals " + str(areaValues[1]))

Or plotted using histogram measure feature (requests matplotlib to be installed):

        # retrieve histogram from measure results
        areaHistogram = areaMsrResults.extractHistogram(15, 0)
        
        # plot histogram results
        import matplotlib.pyplot as plt
        fig, ax = plt.subplots()
        ax.bar(areaHistogram.getBinMidValues(), areaHistogram.getFrequencies(), areaHistogram.getBinWidth(), color='r')
        plt.title("Area histogram")
        plt.xlabel('Bin mean')
        plt.ylabel('Frequencies')
        plt.grid(True)
        plt.show()

See the full source listing