Mean smoothing 3d

module demonstrating the usage of a mean smoothing filter on a 3d image More...

module demonstrating the usage of a mean smoothing filter on a 3d image

Overview

This application applies a mean smoothing filter on a 3d input image loaded from a given input TIFF file, and saves the result in a given TIFF file.

See also

Mean smoothing 3d algorithm

Usage

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

   <application_exe_filename> [--inputImgFilePath <input_image_file_path>] [--outputImgFilePath <output_image_file_path>] [--inHalfKnlSizeX <half_kernel_size_along_x>] [--inHalfKnlSizeY <half_kernel_size_along_y>] [--inHalfKnlSizeZ <half_kernel_size_along_z>]
     
   Arguments:
      --inputImgFilePath  optional; specifies the name of the TIFF file, from
                          which the 3d input image will be loaded; if not 
                          specified by the user, the input image is loaded from
                          file 
                          <DEV_ROOT>/data/Sample/images/Rope3d.tif
                          
      --outputImgFilePath optional; specifies the name of the TIFF file, in
                          which the 3d output image resulting from the 
                          computation of the mean smoothing filter will be saved;
                          if not specified by the user, the output image is 
                          saved in file
                          <TEMPORARY_IPSDK_DIR>/Sample/meanSmoothing3d.tif

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

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

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

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

Source code documentation

The sequence of operations executed in this application is very similar to what is done in Lightness sample application:

Start by including all the necessary header files:

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

// used to initialize IPSDK environment
#include <IPSDKCore/Config/LibraryInitializer.h>

// used to compute mean smoothing on input image
#include <IPSDKIPL/IPSDKIPLFiltering/Processor/MeanSmoothing3dImg/MeanSmoothing3dImg.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_MeanSmoothing3d/Logger/Sample_MeanSmoothing3dLog.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 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_MEANSMOOTHING3D_LOG_WARN(
            [eSample_MeanSmoothing3dMessage::eIPSDKLibInitWarn]
            % initRes.getMsg());
        break;
    case ipsdk::core::eLibInitStatus::eLIS_Failed:
        // IPSDK library initialization; notify the user and exit
        SAMPLE_MEANSMOOTHING3D_LOG_ERROR(
            [eSample_MeanSmoothing3dMessage::eIPSDKLibInitFailed]
            % initRes.getMsg());
        return -1;
        break;
    default:
        break;
    }

Then we declare objects 'inImgFilePath' and 'outImgFilePath':

    // boost objects, used to store input and output images files paths
    boost::filesystem::path inImgFilePath, outImgFilePath;

We also declare variables that will store the half kernel size used to apply mean smoothing filter and specified by the user (or its default value if the user did not specify its value).

    // variable storing expected kernel 3d size
    ipsdk::ipUInt32 inHalfKnlSizeX, inHalfKnlSizeY, inHalfKnlSizeZ;

Paths and half kernel size values are updated from the command line, by calling function "readCmdArguments":

    // read program options from command line, and, if appropriate,
    // initialize input and output images files paths
    if(!readCmdArguments(argc, argv, inImgFilePath, outImgFilePath, 
                         inHalfKnlSizeX, inHalfKnlSizeY, inHalfKnlSizeZ))
        return -1;

And we load our input image from the associated TIFF file:

    // declare the variable that will contain the input image, loaded from
    // TIFF file
    ipsdk::image::ImagePtr pInImg3d;
    try {
        // read input image from specified path
        // input image plans are interpreted as a 3d stack
        pInImg3d = ipsdk::image::file::loadTiffImageFile(inImgFilePath,
                                                         file::eTiffDirectoryMode::eTDM_Volume);
    } catch(const image::file::IPSDKImageFileException& e) {

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

We can now apply the "meanSmoothing3d" filter operation on our freshly loaded input image, by calling "ipsdk::imaproc::filter::meanSmoothing3d". This function takes our object pInImg3d, and returns the resulting image in an object of type ImagePtr, that we store in our variable pOutImg.

Once again, the call of "meanSmoothing3d" function is enclosed in a try/catch block to handle any failure during this operation. If the operation fails, we notify the user and clean IPSDK environment before exiting.

    // declare the variable that will contain the output image, resulting from
    // the mean smoothing 3d
    ImagePtr pOutImg;
    try {
        // mean smoothing 3d of input image
        pOutImg = ipsdk::imaproc::filter::meanSmoothing3dImg(pInImg3d, inHalfKnlSizeX, inHalfKnlSizeY, inHalfKnlSizeZ);

    } catch(const processor::IPSDKBaseProcessingException& e) {

        // one of the 2 previous function calls
        SAMPLE_MEANSMOOTHING3D_LOG_ERROR(
            [eSample_MeanSmoothing3dMessage::eErrorMeanSmoothing]
            % 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 output image is then saved to the TIFF file specified in object "outImgFilePath":

    try {
        // save the resulting image in specified path
        ipsdk::image::file::saveTiffImageFile(outImgFilePath, pOutImg);
    } catch(const image::file::IPSDKImageFileException& e) {

        SAMPLE_MEANSMOOTHING3D_LOG_ERROR(
            [eSample_MeanSmoothing3dMessage::eErrorSavingImgTiffFile]
            % outImgFilePath % 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;
    }

Finally, we clean IPSDK environment and exit:

    ipsdk::core::LibraryInitializer::getInstance().clear();
    return 0;
}

See the full source listing