NICE_SemSeg/semseg/SemanticSegmentation.h

/**
* @file SemanticSegmentation.h
* @brief abstract interface for semantic segmentation algorithms
* @author Erik Rodner, Alexander Freytag, Sven Sickert
* @date 03/19/2009, latest update: 14-05-2014 (dd-mm-yyyy)

*/
#ifndef SEMANTICSEGMENTATIONINCLUDE
#define SEMANTICSEGMENTATIONINCLUDE

// standard library includes
#include <vector>

// nice-core includes
#include <core/basics/Persistent.h>
#include "core/image/MultiChannelImage3DT.h"

// nice-vislearning includes
#include "vislearning/cbaselib/MultiDataset.h"
#include "vislearning/cbaselib/LocalizationResult.h"
#include "vislearning/cbaselib/CachedExample.h"
#include "vislearning/cbaselib/Example.h"

#ifndef ROADWORKSADD
#define ROADWORKSADD fthrow(NICE::Exception, "addNewExample(const NICE::Vector & newExample, const int & newClassNo): not yet implemented!");
#endif
#ifndef ROADWORKSADDNOVEL
#define ROADWORKSADDNOVEL fthrow(NICE::Exception, "addNovelExamples(): not yet implemented!");
#endif
#ifndef ROADWORKSGETNOVEL
#define ROADWORKSGETNOVEL fthrow(NICE::Exception, "getNovelExamples(): not yet implemented!");
#endif

namespace OBJREC
{

/** abstract interface for semantic segmentation algorithms */
class SemanticSegmentation : public NICE::Persistent
{

  protected:

    /////////////////////////
    /////////////////////////
    // PROTECTED VARIABLES //
    /////////////////////////
    /////////////////////////

    /** accessible class names and information about
        number of classes etc. */
    const ClassNames * classNames;

    /** enum type for imagetype */
    enum IMAGETYP
    {
      IMAGETYPE_RGB = 0,
      IMAGETYPE_GRAY
    };

    /** whether to load images with color information */
    IMAGETYP imagetype;

    int iterationCountSuffix;

    /** whether to do a coarse segmentation or not */
    bool coarseMode;

    /** whether to run in 3D mode or not */
    bool run3Dseg;

    /////////////////////////
    /////////////////////////
    //  PROTECTED METHODS  //
    /////////////////////////
    /////////////////////////

  public:

    ///////////////////// ///////////////////// /////////////////////
    //                   CONSTRUCTORS / DESTRUCTORS
    ///////////////////// ///////////////////// /////////////////////

    /** default constructor
     * @author Alexander Freytag
     * @date 06-02-2014 ( dd-mm-yyy )
    */
    SemanticSegmentation ( );

    /** simple constructor
        @param conf global settings
        @param classNames this ClassNames object while be stored as a attribute
    */
    SemanticSegmentation ( const NICE::Config *conf,
                           const ClassNames *classNames );

    /** simple destructor */
    virtual ~SemanticSegmentation();

    /**
    * @brief Setup internal variables and objects used
    * @author Alexander Freytag
    * @param conf Config file to specify variable settings
    * @param s_confSection
    */
    void initFromConfig(const NICE::Config *conf, const std::string & s_confSection = "SemanticSegmentation");

    ///////////////////// ///////////////////// /////////////////////
    //                      SEGMENTATION STUFF
    ///////////////////// ///////////////////// /////////////////////

    /**
     * @brief return whether 3D mode is activated or not
     * @return bool 3d mode status
     */
    bool isMode3D ()
    {
        return run3Dseg;
    }

    /** load img from file call localize(CachedExample *ce) etc. */
    void semanticseg ( const std::string & filename,
                       NICE::ImageT<int> & segresult,
                       NICE::MultiChannelImageT<double> & probabilities );

    /**
     * @brief Pre-processing and classification of a 3D image
     * @param filelist filename list of images that represent slices of a stack
     * @param segresult segmentation results (output)
     * @param probabilities probabilities for each pixel (output)
     */
    void semanticseg ( const std::vector<std::string> & filelist,
                       NICE::MultiChannelImageT<int> & segresult,
                       NICE::MultiChannelImage3DT<double> & probabilities );

    /**
     * Classify each voxel of a 3D image (image stack)
     * @author Sven Sickert
     * @param filelist filename list of images that represent slices of a stack
     * @param segresult segmentation results (output)
     * @param probabilities probabilities for each pixel (output)
     */
    virtual void classify ( const std::vector<std::string> & filelist,
                    NICE::MultiChannelImageT<int> & segresult,
                    NICE::MultiChannelImage3DT<double> & probabilities );

    /** this function has to be overloaded by all subclasses
        @param ce image data
        @param segresult result of the semantic segmentation with a label for each
        pixel
        @param probabilities multi-channel image with one channel for each class and
               corresponding probabilities for each pixel
    */
    virtual void semanticseg ( OBJREC::CachedExample *ce,
                               NICE::ImageT<int> & segresult,
                               NICE::MultiChannelImageT<double> & probabilities ) = 0;

    /**
     * Classify each voxel of a 3D image (image stack)
     * @author Sven Sickert
     * @param ce 3d image data
     * @param segresult segmentation results (output)
     * @param probabilities probabilities for each pixel (output)
     */
    virtual void semanticseg ( OBJREC::CachedExample *ce,
                               NICE::MultiChannelImageT<int> & segresult,
                               NICE::MultiChannelImage3DT<double> & probabilities ) = 0;


    /** training function (has to be overloaded by all subclasses)
     * @param md the data set
     */
    virtual void train ( const MultiDataset * md ) = 0;

    /**
     * @brief train the actual training method
     * @param trainp pointer to training data
     */
    virtual void train ( const LabeledSet * trainp ){}

    /**
     * @brief Load image slices into a MultiChannelImage3DT
     * @author Sven Sickert
     * @param filelist filename list of images that represent slices of a stack
     * @param imgData output
     */
    template<class SrcP>
    void make3DImage ( const std::vector<std::string> & filelist,
                       NICE::MultiChannelImage3DT<SrcP> & imgData );


    ///////////////////// ///////////////////// /////////////////////
    //                      DATA CONVERSION
    ///////////////////// ///////////////////// /////////////////////

    /**
     * convert different datatypes
     */
    void convertVVectorToExamples ( NICE::VVector &feats,OBJREC::Examples &examples, std::vector<int> &label );
    void convertExamplesToVVector ( NICE::VVector &feats,OBJREC::Examples &examples, std::vector<int> &label );
    void convertExamplesToLSet ( OBJREC::Examples &examples, OBJREC::LabeledSetVector &lvec );
    void convertLSetToExamples ( OBJREC::Examples &examples, OBJREC::LabeledSetVector &lvec, const bool & removeOldDataPointer=false );
    void convertLSetToSparseExamples ( OBJREC::Examples &examples, OBJREC::LabeledSetVector &lvec );


    ///////////////////// ///////////////////// /////////////////////
    //                       ONLINE LEARNING
    ///////////////////// ///////////////////// /////////////////////

    virtual void addNewExample(const NICE::Vector & newExample, const int & newClassNo)
    {
      ROADWORKSADD;
    }

    /**
     * @brief Add those examples, which belong to the most novel region seen so far
     *
     * @return void
     **/
    virtual void addNovelExamples()
    {
      ROADWORKSADDNOVEL;
    }

    ///////////////////// ///////////////////// /////////////////////
    //                         GET / SET
    ///////////////////// ///////////////////// /////////////////////

    /**
     * @brief Get a pointer to the examples extracted from the most novel region seen so far
     *
     * @return Examples *
     **/
    virtual const Examples * getNovelExamples() const
    {
      ROADWORKSGETNOVEL;
    }

    /**
     * @brief Save probability maps of all classes to image files
     * @author Sven Sickert
     * @param prob class probability maps
     */
    void saveProbabilityMapAsImage( const NICE::MultiChannelImage3DT<double> & prob );

    /**
     * @author Alexander Freytag
     * @date 06-02-2014 ( dd-mm-yyyy )
     */
    void setClassNames ( const OBJREC::ClassNames * _classNames  ) ;

    void setIterationCountSuffix( const int & _iterationCountSuffix);

    ///////////////////// INTERFACE PERSISTENT /////////////////////
    // interface specific methods for store and restore
    ///////////////////// INTERFACE PERSISTENT /////////////////////

    /**
     * @brief Load active-segmentation-object from external file (stream)
     * @author Alexander Freytag
     */
    virtual void restore ( std::istream & is, int format = 0 );

    /**
     * @brief Save active-segmentation-object to external file (stream)
     * @author Alexander Freytag
     */
    virtual void store( std::ostream & os, int format = 0 ) const;

    /**
     * @brief Clear active-segmentation-object object
     * @author Alexander Freytag
     */
    virtual void clear ();

};


} // namespace

#include "SemanticSegmentation.tcc"

#endif