Local Features - documentation significantly improved

features/localfeatures/GenericLFSelection.h

@@ -1,5 +1,5 @@
 /** 
-* @file GenericLocalFeatureSelection.h
+* @file GenericLFSelection.h
 * @brief This class provides a generic chooser function for different descriptors, which are derived from LocalFeatureRepresentation.
 * @date 26.10.2011
 */
@@ -19,80 +19,143 @@
 #include "vislearning/features/localfeatures/LFColorSande.h"
 #include "vislearning/features/localfeatures/LFonHSG.h"
 
-/** NOTE: This class only returns Descriptors, which NOT need any given positions. All Descriptors calculate there own positions, on DIFFERENT ways. **/
-
 
 namespace OBJREC {
 
+  /** @class GenericLFSelection
+ * @brief Select a specific LF-Type (local feature representation). LFs compute Descriptors, which DO NOT need given positions, but calculate them ON THEIR OWN!
+ * All Descriptor-Methods calculate there own positions previously, and on DIFFERENT ways.
+ */
 class GenericLFSelection
 {
     public:
+      
+      //! enum specifying for which step the feature extractor shall be used (this influences the config section which will be used)
+      enum UsageForTrainOrTest { NOTSPECIFIED = 0,
+             TRAINING,
+             TESTING
+      };
 
       /** LocalFeature Selector
        * @brief This methode switches between the different LocalFeature-Types. One has to set the "localfeature_type" on a valid value and the methode returns a LocalFeatureRepresentation derived Object.
-       * @param[in] Config* - A pointer to the given configfile, which must contain "section" - "localfeature_type"
-       * @param[in] string  - This string defines the value for "section" in the configfile.
+       * @param[in] conf - A pointer to the given configfile, which must contain "section" - "localfeature_type"
+       * @param[in] section - This string defines the value for "section" in the configfile.
+       * @param[in] useForTrainOrTest - Specify whether we use the LFRep for Training, Testing, or for both - this influences the choice of the config section that is handed over to the LFRep-method
        * @return LocalFeatureRepresentation* - The LocalFeatureRepresentation which contains the selected LocalFeature-Type.
        */
       static
-      LocalFeatureRepresentation *selectLocalFeatureRep ( const NICE::Config *conf, std::string section = "features" )
+      LocalFeatureRepresentation *selectLocalFeatureRep ( const NICE::Config *conf, std::string section = "features", const UsageForTrainOrTest & useForTrainOrTest = NOTSPECIFIED )
       {
-	  // return Value
-	  LocalFeatureRepresentation *lfrep = NULL;
-	
-	  // string which defines the localfeature_type (for Ex. Sande, ...)
-	  std::string localfeature_type = conf->gS(section, "localfeature_type", "");
-	
-	  if ( localfeature_type == "mikolajczyk" )
-	  {
-	    lfrep = new LFMikolajczyk ( conf );
-	  }
-	  else if ( localfeature_type == "color" )
-	  {
-	    lfrep = new LFColorSande ( conf );
-	  }
-	  else if ( ( localfeature_type == "sift" ) || ( localfeature_type == "siftpp" ) ) 
-	  {
-            lfrep = new LFSiftPP ( conf );
-	  }
-	  else if ( ( localfeature_type == "generic_local" ) || ( localfeature_type == "generic" ) )
-	  {
-            int numFeatures = conf->gI(section, "localfeature_count");
-	    lfrep = new LFGenericLocal ( conf, numFeatures );
-	  }
-	  else if ( ( localfeature_type == "grey" ) || ( localfeature_type == "patches" ) )
-	  {
-	    int numFeatures = conf->gI(section, "localfeature_count");
-	    lfrep = new LFPatches ( conf, numFeatures );
-	  } 
-	  else if( ( localfeature_type == "onHSG" ) )
-	  {
-	    lfrep = new LFonHSG( conf);
-	  }
-	  else 
-	  {
-		  lfrep = NULL;
-	  }
+        // return Value
+        LocalFeatureRepresentation *lfrep = NULL;
+      
+        // string which defines the localfeature_type (for Ex. Sande, ...)
+        std::string localfeature_type = conf->gS(section, "localfeature_type", "");
+      
+        if ( localfeature_type == "mikolajczyk" )
+        {
+          lfrep = new LFMikolajczyk ( conf );
+        }
+        else if ( localfeature_type == "VANDESANDE" ) //previously: "color"
+        {
+          if ( useForTrainOrTest == TRAINING )
+          {
+            lfrep = new LFColorSande ( conf, "LFColorSandeTrain" );
+          }
+          else if ( useForTrainOrTest == TESTING )
+          {
+            lfrep = new LFColorSande ( conf, "LFColorSandeTest" );
+          }
+          else //not specified whether for training or testing, so we do not care about
+          {
+            lfrep = new LFColorSande ( conf );            
+          }          
+        }
+        else if ( ( localfeature_type == "sift" ) || ( localfeature_type == "siftpp" ) ) 
+        {
+                lfrep = new LFSiftPP ( conf );
+        }
+        else if ( ( localfeature_type == "generic_local" ) || ( localfeature_type == "generic" ) )
+        {
+                int numFeatures = conf->gI(section, "localfeature_count");
+          lfrep = new LFGenericLocal ( conf, numFeatures );
+        }
+        else if ( ( localfeature_type == "grey" ) || ( localfeature_type == "patches" ) )
+        {
+          int numFeatures = conf->gI(section, "localfeature_count");
+          lfrep = new LFPatches ( conf, numFeatures );
+        } 
+        else if( ( localfeature_type == "onHSG" ) )
+        {
+          if ( useForTrainOrTest == TRAINING )
+          {
+            lfrep = new OBJREC::LFonHSG ( conf, "HSGTrain" );
+          }
+          else if ( useForTrainOrTest == TESTING )
+          {
+            lfrep = new OBJREC::LFonHSG ( conf, "HSGTest" );
+          }
+          else //not specified whether for training or testing, so we do not care about
+          {
+            lfrep = new OBJREC::LFonHSG( conf);
+          }           
+          
+        }
+        else 
+        {
+          lfrep = NULL;
+        }
+
+//         if ( conf->gB(section, "localfeature_cache_read", false) )
+//         {
+//           int numFeatures = conf->gI(section, "localfeature_count", -1);
+//           LocalFeatureRepresentation *lfrep_read = new LFReadCache ( conf, lfrep, numFeatures );
+//           lfrep = lfrep_read;
+//         }
+// 
+//         // no correct localfeature_type was given
+//         if ( lfrep == NULL )
+//           fthrow(NICE::Exception, "Local feature type not found: " << localfeature_type );
+// 
+//         if ( conf->gB(section, "localfeature_cache_write", false) )
+//         {
+//           LocalFeatureRepresentation *lfrep_write = new LFWriteCache ( conf, lfrep );
+//           lfrep = lfrep_write;
+//         }
 
-	  if ( conf->gB(section, "localfeature_cache_read", false) )
-	  {
-		  int numFeatures = conf->gI(section, "localfeature_count", -1);
-		  LocalFeatureRepresentation *lfrep_read = new LFReadCache ( conf, lfrep, numFeatures );
-		  lfrep = lfrep_read;
-	  }
+        // read features?
+        bool readfeat;
+        readfeat = conf->gB ( section, "localfeature_cache_read", true );
+        // write features?
+        bool writefeat;  
+        writefeat = conf->gB ( section, "localfeature_cache_write", true );   
 
-	  // no correct localfeature_type was given
-	  if ( lfrep == NULL )
-		  fthrow(NICE::Exception, "Local feature type not found: " << localfeature_type );
+        LocalFeatureRepresentation *writeFeats = NULL;
+        LocalFeatureRepresentation *readFeats = NULL;
+        if ( writefeat )
+        {
+          // write the features to a file, if there isn't any to read
+          writeFeats = new LFWriteCache ( conf, lfrep );
+          lfrep = writeFeats;
+        }
 
-	  if ( conf->gB(section, "localfeature_cache_save", false) )
-	  {
-		  LocalFeatureRepresentation *lfrep_save = new LFWriteCache ( conf, lfrep );
-		  lfrep = lfrep_save;
-	  }
-		  
-	  return lfrep;
-      }
+        if ( readfeat )
+        {
+          int numFeatures = conf->gI(section, "localfeature_count", -1);
+          // read the features from a file
+          if ( writefeat )
+          {
+            readFeats = new LFReadCache ( conf, writeFeats, numFeatures );
+          }
+          else
+          {
+            readFeats = new LFReadCache (conf, lfrep, numFeatures );
+          }
+          lfrep = readFeats; 
+        }  
+          
+        return lfrep;
+        }
 };
 
 }

features/localfeatures/GenericLocalFeatureSelection.h

@@ -21,6 +21,10 @@
 
 namespace OBJREC {
 
+  /** @class GenericLocalFeatureSelection
+ * @brief Select a specific LocalFeature-Type. LocalFeatures compute Descriptors, which DO need given positions (no internal position calculation)!
+ *
+ */  
 class GenericLocalFeatureSelection
 {
   public:

features/localfeatures/IDRandomSampling.h

@@ -18,25 +18,27 @@
 namespace OBJREC
 {
 
-/** random interest point sampling */
-class IDRandomSampling: public InterestDetector
-{
+  /** @class IDRandomSampling
+ * @brief random interest point sampling
+ */
+  class IDRandomSampling: public InterestDetector
+  {
 
-protected:
-	int numSamples;
-	double minScale;
+  protected:
+    int numSamples;
+    double minScale;
 
-public:
+  public:
 
-	IDRandomSampling(const NICE::Config *conf, int numSamples);
+    IDRandomSampling(const NICE::Config *conf, int numSamples);
 
-	virtual ~IDRandomSampling();
-	int getInterests(const NICE::Image & img,
-			std::vector<NICE::Vector> & positions) const;
-	int getInterests(const ImagePyramid & imp,
-			std::vector<NICE::Vector> & positions) const;
+    virtual ~IDRandomSampling();
+    int getInterests(const NICE::Image & img,
+        std::vector<NICE::Vector> & positions) const;
+    int getInterests(const ImagePyramid & imp,
+        std::vector<NICE::Vector> & positions) const;
 
-};
+  };
 
 } // namespace
 

features/localfeatures/LFGenericLocal.h

@@ -1,9 +1,8 @@
 /** 
 * @file LFGenericLocal.h
-* @brief generic local features
+* @brief generic local features ( Random Sampling of POIs and SIFT as descriptor)
 * @author Erik Rodner
 * @date 02/05/2008
-
 */
 #ifndef LFGENERICLOCALINCLUDE
 #define LFGENERICLOCALINCLUDE
@@ -21,33 +20,36 @@
 
 namespace OBJREC {
 
-/** generic local features */
-class LFGenericLocal : public LocalFeatureRepresentation
-{
+  /** generic local features */
+  /** @class LFGenericLocal
+ * @brief Generic local features ( actually: Random Sampling of POIs followed by SIFT as descriptor)
+ */  
+  class LFGenericLocal : public LocalFeatureRepresentation
+  {
+
+      protected:
+    LocalFeature *lf;
+    InterestDetector *id;
+
+      public:
+    
+    /** simple constructor */
+    LFGenericLocal( const NICE::Config *conf, int numFeatures );
+        
+    /** simple destructor */
+    virtual ~LFGenericLocal();
+      
+    int getDescSize () const;
 
-    protected:
-	LocalFeature *lf;
-	InterestDetector *id;
+    int extractFeatures ( const NICE::Image & img, 
+              NICE::VVector & features, 
+              NICE::VVector & positions) const;
+              
+    void visualizeFeatures ( NICE::Image & mark,
+          const NICE::VVector & positions,
+          size_t color ) const;
 
-    public:
-  
-	/** simple constructor */
-	LFGenericLocal( const NICE::Config *conf, int numFeatures );
-      
-	/** simple destructor */
-	virtual ~LFGenericLocal();
-     
-	int getDescSize () const;
-
-	int extractFeatures ( const NICE::Image & img, 
-			      NICE::VVector & features, 
-			      NICE::VVector & positions) const;
-			      
-	void visualizeFeatures ( NICE::Image & mark,
-				 const NICE::VVector & positions,
-				 size_t color ) const;
-
-};
+  };
 
 
 } // namespace

features/localfeatures/LFWriteCache.h

@@ -1,6 +1,6 @@
 /** 
 * @file LFWriteCache.h
-* @brief write local features to file
+* @brief Write local features to file (whenever a descriptor is computed, it will be checked whether a corresponding file already exists. If not, we save the descriptor)
 * @author Erik Rodner
 * @date 02/14/2008
 
@@ -18,59 +18,62 @@
 
 namespace OBJREC {
 
-/** write local features to file */
-class LFWriteCache : public LocalFeatureRepresentation
-{
+  /** @class LFWriteCache
+  * @brief Write local features to file (whenever a descriptor is computed, it will be checked whether a corresponding file already exists. If not, we save the descriptor)
+  *
+  */  
+  class LFWriteCache : public LocalFeatureRepresentation
+  {
 
-    protected:
-	const LocalFeatureRepresentation *lfrep;
+      protected:
+        const LocalFeatureRepresentation *lfrep;
 
-	std::string cachedir;
+        std::string cachedir;
 
-	int descFormat;
-	int cachemode;
+        int descFormat;
+        int cachemode;
 
 
-    public:
-  
-		/** simple constructor */
-		LFWriteCache( const NICE::Config *conf, 
-				const LocalFeatureRepresentation *lfrep ); 
-		
-		/** simple destructor */
-		virtual ~LFWriteCache();
-	
-		int getDescSize () const;
-	
-		/**
-		* extract features for gray images
-		* @param img input image
-		* @param features output features
-		* @param positions position of the features
-		* @return 
-		*/
-		int extractFeatures ( const NICE::Image & img, 
-					NICE::VVector & features, 
-					NICE::VVector & positions ) const;
-		
-		/**
-		* extract features for color images
-		* @param img input image
-		* @param features output features
-		* @param positions position of the features
-		* @return 
-		*/
-		int extractFeatures ( const NICE::ColorImage & img, 
-					NICE::VVector & features, 
-					NICE::VVector & positions ) const;
-	
-		void visualize ( NICE::Image & img, 
-			const NICE::Vector & feature ) const;
-	
-		void visualizeFeatures ( NICE::Image & mark,
-					const NICE::VVector & positions,
-					size_t color ) const;
-};
+      public:
+    
+        /** simple constructor */
+        LFWriteCache( const NICE::Config *conf, 
+            const LocalFeatureRepresentation *lfrep ); 
+        
+        /** simple destructor */
+        virtual ~LFWriteCache();
+      
+        int getDescSize () const;
+      
+        /**
+        * extract features for gray images
+        * @param img input image
+        * @param features output features
+        * @param positions position of the features
+        * @return 
+        */
+        int extractFeatures ( const NICE::Image & img, 
+              NICE::VVector & features, 
+              NICE::VVector & positions ) const;
+        
+        /**
+        * extract features for color images
+        * @param img input image
+        * @param features output features
+        * @param positions position of the features
+        * @return 
+        */
+        int extractFeatures ( const NICE::ColorImage & img, 
+              NICE::VVector & features, 
+              NICE::VVector & positions ) const;
+      
+        void visualize ( NICE::Image & img, 
+          const NICE::Vector & feature ) const;
+      
+        void visualizeFeatures ( NICE::Image & mark,
+              const NICE::VVector & positions,
+              size_t color ) const;
+  };
 
 
 } // namespace

features/localfeatures/LocalFeature.h

@@ -1,7 +1,7 @@
 /** 
 * @file LocalFeature.h
-* @brief local feature interface
-* @author Erik Rodner
+* @brief Abstract class for Local Features ( ONLY DESCRIPTORS, NO DETECTORS )
+* @author Erik Rodner, Alexander Freytag
 * @date 02/05/2008
 
 */
@@ -17,31 +17,34 @@
 
 namespace OBJREC {
 
-/** local feature interface */
-class LocalFeature
-{
+    /** @class LocalFeature
+  * @brief Abstract class for Local Features ( ONLY DESCRIPTORS, NO DETECTORS )
+  *
+  */
+  class LocalFeature
+  {
 
-    protected:
+      protected:
 
-    public:
-  
-	/** simple constructor */
-	LocalFeature();
-      
-	/** simple destructor */
-	virtual ~LocalFeature();
-
-	virtual int getDescSize() const = 0;
-
-	virtual int getDescriptors ( const NICE::Image & img, NICE::VVector & positions, NICE::VVector & descriptors) const = 0;
-	
-	virtual int getDescriptors ( const NICE::ColorImage & img, NICE::VVector & positions, NICE::VVector & descriptors) const;
-	
-	virtual void visualizeFeatures ( NICE::Image & mark,
-				 const NICE::VVector & positions,
-				 size_t color ) const;
+      public:
     
-};
+    /** simple constructor */
+    LocalFeature();
+        
+    /** simple destructor */
+    virtual ~LocalFeature();
+
+    virtual int getDescSize() const = 0;
+
+    virtual int getDescriptors ( const NICE::Image & img, NICE::VVector & positions, NICE::VVector & descriptors) const = 0;
+    
+    virtual int getDescriptors ( const NICE::ColorImage & img, NICE::VVector & positions, NICE::VVector & descriptors) const;
+    
+    virtual void visualizeFeatures ( NICE::Image & mark,
+          const NICE::VVector & positions,
+          size_t color ) const;
+      
+  };
 
 
 } // namespace

features/localfeatures/LocalFeatureLFInterface.cpp

@@ -10,34 +10,36 @@ using namespace NICE;
 
 LocalFeatureLFInterface::LocalFeatureLFInterface( const Config *conf, LocalFeatureRepresentation *_lfpres )
 {
-	lfpres = _lfpres;
+  lfpres = _lfpres;
 }
 
 LocalFeatureLFInterface::~LocalFeatureLFInterface()
 {
-	delete lfpres;
+  delete lfpres;
 }
 
 
 int LocalFeatureLFInterface::getDescriptors ( const NICE::Image & img, VVector & positions, VVector & descriptors ) const
 {
-	lfpres->extractFeatures(img, descriptors, positions);
-	assert(descriptors.size() == positions.size());
-    return 0;
+  //TODO do we want to ignore the positions of lfrep and use the given ones, or do we indeed want to compute positions on our own? If so, why do we use the Interface to LocalFeature, and not directly LocalFeatureRepresentation?    
+  lfpres->extractFeatures(img, descriptors, positions);
+  assert(descriptors.size() == positions.size());
+  return 0;
 }
 
 int LocalFeatureLFInterface::getDescriptors ( const NICE::ColorImage & img, VVector & positions, VVector & descriptors) const
 {
-	lfpres->extractFeatures(img, descriptors, positions);
-	assert(descriptors.size() == positions.size());
-	return 0;
+  //TODO do we want to ignore the positions of lfrep and use the given ones, or do we indeed want to compute positions on our own? If so, why do we use the Interface to LocalFeature, and not directly LocalFeatureRepresentation?
+  lfpres->extractFeatures(img, descriptors, positions);
+  assert(descriptors.size() == positions.size());
+  return 0;
 }
 
 void LocalFeatureLFInterface::visualizeFeatures ( NICE::Image & mark,
-				 const VVector & positions,
-				 size_t color ) const
+        const VVector & positions,
+        size_t color ) const
 {
-	//cerr << "LocalFeatureLFInterface::visualizeFeatures(...) not yet implemented" << endl;
-	lfpres->visualizeFeatures(mark, positions, color);
+  //cerr << "LocalFeatureLFInterface::visualizeFeatures(...) not yet implemented" << endl;
+  lfpres->visualizeFeatures(mark, positions, color);
 }
 

features/localfeatures/LocalFeatureLFInterface.h

@@ -1,6 +1,6 @@
 /** 
 * @file LocalFeatureLFInterface.h
-* @brief interface to LF
+* @brief Interface to use a LocalFeature (Descriptor only) with routines of LocalFeatureRepresentations (Detector + Descriptor)
 * @author Björn Fröhlich
 * @date 09/07/2010
 
@@ -19,50 +19,53 @@
 
 namespace OBJREC {
 
-/** local feature with LF */
-class LocalFeatureLFInterface : public LocalFeature
-{
 
-    protected:
-		LocalFeatureRepresentation *lfpres;
+  /** @class LocalFeatureLFInterface
+  * @brief Interface to use a LocalFeature (Descriptor only) with routines of LocalFeatureRepresentations (Detector + Descriptor)
+  *
+  */  
+  class LocalFeatureLFInterface : public LocalFeature
+  {
 
-    public:
-  
-	/** simple constructor */
-		LocalFeatureLFInterface ( const NICE::Config *conf, LocalFeatureRepresentation *_lfpres );
-      
-	/** simple destructor */
+      protected:
+      LocalFeatureRepresentation *lfpres;
+
+      public:
+    
+    /** simple constructor */
+      LocalFeatureLFInterface ( const NICE::Config *conf, LocalFeatureRepresentation *_lfpres );
+        
+    /** simple destructor */
 
-	virtual ~LocalFeatureLFInterface();
-	
-	/**
-	 * returns the size of each the SIFT-Feature
-	 * @return 128
-	 */
-	int getDescSize() const { return lfpres->getDescSize(); };
-	
-	/** 
-	 * get the descriptor
-	 * @param img input image
-	 * @param positions positions for the SIFT features
-	 * @param descriptors output
-	 * @return 0
-	 */
-	int getDescriptors ( const NICE::Image & img, NICE::VVector & positions, NICE::VVector & descriptors ) const;
-	
-	/** 
-	 * get the descriptor
-	 * @param img input color image
-	 * @param positions positions for the SIFT features
-	 * @param descriptors output
-	 * @return 0
-	 */
-	int getDescriptors ( const NICE::ColorImage & img, NICE::VVector & positions, NICE::VVector & descriptors) const;
-				     
-	void visualizeFeatures ( NICE::Image & mark, const NICE::VVector & positions, size_t color ) const;
+    virtual ~LocalFeatureLFInterface();
+    
+    /**
+    * @brief returns the size of each the SIFT-Feature
+    */
+    int getDescSize() const { return lfpres->getDescSize(); };
+    
+    /** 
+    * @brief get the descriptor
+    * @param img input image
+    * @param positions positions for local features
+    * @param descriptors output
+    * @return 0
+    */
+    int getDescriptors ( const NICE::Image & img, NICE::VVector & positions, NICE::VVector & descriptors ) const;
+    
+    /** 
+    * @brief get the descriptor
+    * @param img input color image
+    * @param positions positions for the SIFT features
+    * @param descriptors output
+    * @return 0
+    */
+    int getDescriptors ( const NICE::ColorImage & img, NICE::VVector & positions, NICE::VVector & descriptors) const;
+              
+    void visualizeFeatures ( NICE::Image & mark, const NICE::VVector & positions, size_t color ) const;
 
-     
-};
+      
+  };
 
 
 } // namespace

features/localfeatures/LocalFeatureRepresentation.h

@@ -1,7 +1,7 @@
 /** 
 * @file LocalFeatureRepresentation.h
-* @brief absract class for the representation of an image with local feature descriptors
-* @author Erik Rodner
+* @brief Absract class for Local Feature Representations (Detector + Descriptor)
+* @author Erik Rodner, Alexander Freytag
 * @date 11/19/2007
 
 */
@@ -21,6 +21,12 @@
 namespace OBJREC {
 
 /** absract class for the representation of an image with local feature descriptors */
+/** NOTE: This class returns Descriptors, which DO NOT need any given positions. All Descriptors calculate there own positions, on DIFFERENT ways. **/
+
+  /** @class LocalFeatureRepresentation
+ * @brief Absract class for Local Feature Representations (Detector + Descriptor)
+ *
+ */
 class LocalFeatureRepresentation
 {