ltiLocationSearchEvaluation.h

/*
 * Copyright (C) 1998, 1999, 2000, 2001, 2002, 2003
 * Lehrstuhl fuer Technische Informatik, RWTH-Aachen, Germany
 *
 * This file is part of the LTI-Computer Vision Library (LTI-Lib)
 *
 * The LTI-Lib is free software; you can redistribute it and/or
 * modify it under the terms of the GNU Lesser General Public License (LGPL)
 * as published by the Free Software Foundation; either version 2.1 of
 * the License, or (at your option) any later version.
 *
 * The LTI-Lib is distributed in the hope that it will be
 * useful, but WITHOUT ANY WARRANTY; without even the implied warranty
 * of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU Lesser General Public License for more details.
 *
 * You should have received a copy of the GNU Lesser General Public
 * License along with the LTI-Lib; see the file LICENSE.  If
 * not, write to the Free Software Foundation, Inc., 59 Temple Place -
 * Suite 330, Boston, MA 02111-1307, USA.
 */


/*--------------------------------------------------------------------
 * project ....: LTI-Lib: Image Processing and Computer Vision Library
 * file .......: ltiLocationSearchEvaluation.h
 * authors ....: Pablo Alvarado
 * organization: LTI, RWTH Aachen
 * creation ...: 25.11.2003
 * revisions ..: $Id: ltiLocationSearchEvaluation.h,v 1.2 2007/04/09 12:15:44 alvarado Exp $
 */

#ifndef _LTI_LOCATION_SEARCH_EVALUATION_TESTER_H_
#define _LTI_LOCATION_SEARCH_EVALUATION_TESTER_H_

#include "ltiKdTree.h"
#include "ltiParetoFront.h"
#include "ltiPyramidLocationSearch.h"

namespace lti {

  /**
   * Pareto evaluation of the lti::pyramidLocationSearch functor.
   *
   * This class tests the parameterization of the lti::pyramidLocationSearch
   * functor by searching the Pareto front of some fittness measures, using
   * the genetic search framework provided by the paretoFront class.
   *
   * The fitness criteria used here are:
   * - number of locations
   * - reciprocal of location  number (1/number of locations)
   * - number of occupied levels in the pyramid
   * - reciprocal of the time taken to extract all locations
   * - scale repeatability, i.e. considering scale changes only
   * - rotation repeatability, i.e. considering rotations only
   * - rotation scale repeatability, i.e. considering scale and rotation 
   * - scale stable locations, i.e. considering scale changes only
   * - rotation stable locations, i.e. considering rotations only
   * - rotation scale stable locations, i.e. considering scale and rotation 
   * 
   * For the evaluation of a parameterization the algorithm takes all
   * images stored in the file specified in parameters::images.  For
   * each one of them a set of rotations and scalings are applied, to
   * the image and the locations estracted from it.  Since the geometric
   * transformation is known, we have a "should-be" set of locations, obtained
   * transforming the original image locations.  This set is compared with
   * the locations extracted from the transformed image.  The correspondences
   * are counted and they constitute in percentage the fitness measure.
   *
   * The "repeatability" measures equal the "stable locations"  normalized
   * by the total number of locations.
   */
  class locationSearchEvaluation : public paretoFront {
  public:

    /**
     * The parameters for the class locationSearchEvaluation
     */
    class parameters : public paretoFront::parameters {
    public:
      /**
       * Default constructor
       */
      parameters();

      /**
       * Copy constructor
       * @param other the parameters object to be copied
       */
      parameters(const parameters& other);

      /**
       * Destructor
       */
      ~parameters();

      /**
       * Returns name of this type
       */
      const char* getTypeName() const;

      /**
       * Copy the contents of a parameters object
       * @param other the parameters object to be copied
       * @return a reference to this parameters object
       */
      parameters& copy(const parameters& other);

      /**
       * Copy the contents of a parameters object
       * @param other the parameters object to be copied
       * @return a reference to this parameters object
       */
      parameters& operator=(const parameters& other);


      /**
       * Returns a pointer to a clone of the parameters
       */
      virtual functor::parameters* clone() const;

      /**
       * Write the parameters in the given ioHandler
       * @param handler the ioHandler to be used
       * @param complete if true (the default) the enclosing begin/end will
       *        be also written, otherwise only the data block will be written.
       * @return true if write was successful
       */
      virtual bool write(ioHandler& handler,const bool& complete=true) const;

      /**
       * Read the parameters from the given ioHandler
       * @param handler the ioHandler to be used
       * @param complete if true (the default) the enclosing begin/end will
       *        be also written, otherwise only the data block will be written.
       * @return true if write was successful
       */
      virtual bool read(ioHandler& handler,const bool& complete=true);

#     ifdef _LTI_MSC_6
      /**
       * This function is required by MSVC only, as a workaround for a
       * very awful bug, which exists since MSVC V.4.0, and still by
       * V.6.0 with all bugfixes (so called "service packs") remains
       * there...  This method is also public due to another bug, so please
       * NEVER EVER call this method directly: use read() instead
       */
      bool readMS(ioHandler& handler,const bool& complete=true);

      /**
       * This function is required by MSVC only, as a workaround for a
       * very awful bug, which exists since MSVC V.4.0, and still by
       * V.6.0 with all bugfixes (so called "service packs") remains
       * there...  This method is also public due to another bug, so please
       * NEVER EVER call this method directly: use write() instead
       */
      bool writeMS(ioHandler& handler,const bool& complete=true) const;
#     endif

      // ------------------------------------------------
      // the parameters
      // ------------------------------------------------

      /**
       * @name Fitness measures
       *
       * Value containing the 1D fitness measures to be computed.
       * The constants defined here are:
       * - numberOfLocations
       * - locationsReciprocal (1/number of locations)
       * - occupiedLevels
       * - time
       * - scaleRepeatability
       * - rotationRepeatability
       * - rotationScaleRepeatability
       * - scaleStable
       * - rotationStable
       * - rotationScaleStable
       *
       * This sequence is important, since it determines the positions of
       * the single measures in the fitness output vector.
       *
       * If more fitness measures are selected than the inherited parameter
       * fitnessSpaceDimensionality, then the first ones in this sequence
       * will be selected.
       *
       * If less fitness measure are selected than the inherited parameter
       * fitnessSpaceDimensionality, then the rest of the vector will be
       * filled with zeros.
       *
       * The difference between the "*Repeatibility" and the "*Stable" measures
       * is that the first ones are the number of stable locations normalized
       * to the total number of locations, i.e. their maximal value will be
       * always 1.0.  The "*Stable" unnormalized fitness measures may be
       * important to optimize in those applications that require many 
       * stable locations to work, and not only the major part of them.
       */
      //@{
      /** 
       * Total number of locations detected per image.
       *
       * Default value: false
       */
      bool numberOfLocations;

      /**
       * Locations' reciprocal
       *
       * This is the inverse of the number of location (1/number of locations).
       * It is often better to search of parameterizations that produce a 
       * low number of locations.  The used value will be 1/(1+\#locs) to avoid
       * divisions by zero.
       *
       * Default value: false
       */
      bool locationsReciprocal;

      /**
       * Percentage of generated levels with locations.  Useful to detect how
       * many levels are really necessary.
       *
       * Default value: false
       */
      bool occupiedLevels;
      
      /**
       * Mean time required to extract the locations
       *
       * Default value: true
       */
      bool time;

      /**
       * Repeatability considering only image scaling
       *
       * Default value: false
       */
      bool scaleRepeatability;

      /**
       * Repeatability considering only image rotation 
       *
       * Default value: false
       */
      bool rotationRepeatability; 
      
      /**
       * Repeatability considering both rotation and scaling
       *
       * Default value: true
       */
      bool rotationScaleRepeatability;

      /**
       * Absolute number of stable locations considering only image scaling
       *
       * Default value: false
       */
      bool scaleStable;

      /**
       * Absolute number of stable locations considering only image rotation 
       *
       * Default value: false
       */
      bool rotationStable; 
      
      /**
       * Absolute number of stable locations considering both rotation and
       * scaling
       *
       * Default value: true
       */
      bool rotationScaleStable;

      //@}

      /**
       * Name of a file containing all images to be analyzed.
       *
       * Default value: "images.txt"
       */
      std::string images;

      /**
       * Mask posfix
       *
       * For each image file in \a images, a manual segmented mask can
       * be used to ignore those locations outside the objects of interest.
       *
       * The filename of the masks will be assumed to be the same
       * image name with the given postfix.  For example, if a image is
       * called "test.png" and the postfix is "-preseg", then the
       * mask will be assumed to be "test-preseg.png".
       *
       * Default value: "_premask"
       */
      std::string postfix;

      /**
       * Values for all parameters of the pyramidLocationSearch functor
       * that will be used as minima.
       * 
       * Default value:
       *          numLevels 4
       *          upsampleFirstLevel 0
       *          pyramidParameters::factor 0.5
       *          pyramidParameters::gaussian false
       *          pyramidParameters::interpolatorType BilinearInterpolator
       *          interpolateMaxima false
       *          smoothingGaussianVariance 0
       *          spatialMaximumNeighborhoodSize 3
       *          peakSelectionMode GradientMagnitude
       *          doGLevelDistance 1
       *          doGKernelVariance 1
       *          saliencyThreshold 0
       *          edgenessThreshold 2
       *          orientationWindowRadius = 2
       */
      pyramidLocationSearch::parameters minValues;

      /**
       * Values for all parameters of the pyramidLocationSearch functor
       * that will be used as minima.
       * 
       * Default value:
       *          numLevels 30
       *          upsampleFirstLevel 3
       *          pyramidParameters::factor pow(0.5,1.0/8.0)
       *          pyramidParameters::gaussian true
       *          pyramidParameters::interpolatorType BiquadraticInterpolator
       *          interpolateMaxima true
       *          smoothingGaussianVariance 5
       *          spatialMaximumNeighborhoodSize 7
       *          peakSelectionMode DoG
       *          doGLevelDistance 4
       *          doGKernelVariance 4
       *          saliencyThreshold 0.99
       *          edgenessThreshold 10
       *          orientationWindowRadius = 5
       */
      pyramidLocationSearch::parameters maxValues;

      /**
       * Additive angle change.
       *
       * The interval from firstAngle to lastAngle will be divided in
       * subintervals with a width stepAngle.
       *
       * This must be given in radians, but if you give a value greater than
       * 2*Pi, it will be assumed to be in degrees.
       *
       * Default value: lti::degToRad(10), i.e. 10 degrees in radians.
       */
      float stepAngle;

      /**
       * Multiplicative scaling change.
       *
       * The scaling interval will begin with firstScaling, which will be
       * multiplied each type by stepScaling until last scaling is reached.
       *
       * This value must be greater than 1.
       *
       * Default value: sqrt(2)
       */
      float stepScaling;

      /**
       * First scaling of the image will downsample it by a factor of 4
       *
       * Default value: 0.25
       */
      float firstScaling;

      /**
       * Last scaling of the image will be an upsampling by a factor of 2
       *
       * Default value: 2
       */
      float lastScaling;

      /**
       * First angle
       *
       * This must be given in radians, but if you give a value greater than
       * 2*Pi, it will be assumed to be in degrees.
       *
       * Default value 0
       */
      float firstAngle;

      /**
       * Last rotation angle
       *
       * This must be given in radians, but if you give a value greater than
       * 2*Pi, it will be assumed to be in degrees.
       *
       * Default value: 2*Pi
       */
      float lastAngle;

      /**
       * If true, a location will be considered to match only if position AND
       * rotation lie within the tolerance levels.  If false, only the position
       * will be considered while analyzing the repeatability
       *
       * Default value: true
       */
      bool considerAngle;

      /**
       * Tolerance for scale deviation.
       *
       * Between two candidate matching locations, the match will be accepted
       * only if the ratio between scale of both locations does not goes
       * beneath the given tolerance value, which must be always smaller than
       * one.
       * 
       * Default value: 1/sqrt(2)
       */
      float scaleTolerance;

      /**
       * Tolerance for position deviation.
       *
       * Between two candidate matching locations, the match will be accepted
       * only if the distance between both locations does not exceed the given
       * tolerance value, which must be always positive.
       * 
       * Default value: 1.5f
       */
      float positionTolerance;

      /**
       * Angular tolerance.
       *
       * Two locations, which coincide in position and scale, match together
       * if the angular difference is smaller than the given angle.
       * 
       * This must be given in radians, but if you give a value greater than
       * 2*Pi, it will be assumed to be in degrees.
       *
       * Default value: lti::degToRad(10), i.e. 10 degrees in radians.
       */
      float angleTolerance;
    };

    /**
     * Default constructor
     */
    locationSearchEvaluation();

    /**
     * Construct a functor using the given parameters
     */
    locationSearchEvaluation(const parameters& par);

    /**
     * Copy constructor
     * @param other the object to be copied
     */
    locationSearchEvaluation(const locationSearchEvaluation& other);

    /**
     * Destructor
     */
    virtual ~locationSearchEvaluation();

    /**
     * Returns the name of this type ("locationSearchEvaluation")
     */
    virtual const char* getTypeName() const;

    /**
     * Returns a pointer to a clone of this functor.
     */
    virtual functor* clone() const;

    /**
     * Returns used parameters
     */
    const parameters& getParameters() const;

    /**
     * Set parameters
     */
    bool setParameters(const functor::parameters& par);

    /**
     * @name Public methods to be reimplemented
     */
    //@{

    /**
     * Convert a binary-chain representation of a chromosome to a valid
     * parameter object.
     */
    virtual bool chromosomeToPhenotype(const chromosome& genotype,
                                       functor::parameters& phenotype) const;

    /**
     * Return a fresh allocated parameters for the evaluated functor, which is
     * equivalent to the given genotype.
     */
    virtual functor::parameters* 
    chromosomeToPhenotype(const chromosome& genotype) const;

    /**
     * Convert a valid parameters object (phenotype) into binary-chain
     * representation of a chromosome.
     */
    virtual bool phenotypeToChromosome(const functor::parameters& phenotype,
                                       chromosome& genotype) const;

    /**
     * Return the length in bits for a chromosome.
     *
     * This method needs to be reimplemented, in order to get some 
     * default implementations to work.
     */
    virtual int getChromosomeSize() const;

    /**
     * Evaluate Chromosome
     *
     * This method is one of the most important ones for the pareto evaluation.
     * Its task is to produce a multidimensional fitness measure for a given
     * chromosome.
     *
     * It returns true if the evaluation was successful, of false if the
     * phenotype represents some invalid parameterization.  It is highly 
     * recomended that the mutation and crossover methods are reimplemented to 
     * avoid invalid parameterizations.
     */
    virtual bool evaluateChromosome(const chromosome& individual,
                                    dvector& fitness); 

    //@}

    /**
     * @name Evaluation Functions
     *
     * The real evaluation is provided here in order to compute measures
     * independently of the Pareto Front.
     */
    //@{
    /**
     * Index names for the complete multidimensional fitness measure
     */
    enum {
      IdxTime,              /**< Well, this is not really time, because that
                             *   would be "cost" instead of "fitness", in
                             *   reality, * this dimension contains 1.0/time in
                             *   s^-1, meaning the number of complete
                             *   location extractions per second.
                             */
      IdxNumberOfLocations, /**< Mean number of extracted locations 
                             */
      IdxLocationsRecip,    /**< Location reciprocal.
                             *
                             *   Inverse of the number of locations detected.
                             */
      IdxOccupiedLevels,    /**< Mean number of occupied levels.
                             */
      IdxScalePosRep,       /**< Scale repeatability defined as total
                             *   number of stable locations divided by
                             *   the total number of locations for
                             *   changes of scaling only.
                             */
      IdxRotationPosRep,    /**< Rotation repeatability defined as
                             *   total number of stable locations
                             *   divided by the total number of
                             *   locations for changes in the rotation
                             *   only.
                             */
      IdxRSPosRep,          /**< Rotation repeatability defined as
                             *   total number of stable locations
                             *   divided by the total number of
                             *   locations for changes in the rotation
                             *   and scale. This will only be computed
                             *   if the RSRepeatability bit in the parameters
                             *   is enabled (it costs too much time!).
                             */
      IdxScaleARep,         /**< Scale angular repeatability defined as
                             *   total number of angular stable
                             *   locations divided by the total number
                             *   of locations for changes of scaling
                             *   only.
                             */
      IdxRotationARep,      /**< Rotation angular repeatability defined
                             *   as total number of angular stable
                             *   locations divided by the total number
                             *   of locations for changes in the
                             *   rotation only.
                             */
      IdxRSARep,            /**< Angular repeatability defined as total
                             *   number of angular stable locations
                             *   divided by the total number of
                             *   locations for changes in the rotation
                             *   and scale.  This will only be computed
                             *   if the RSRepeatability bit in the parameters
                             *   is enabled (it costs too much time!).
                             */
      IdxScalePosStable,    /**< Scale stability defined as total
                             *   number of stable locations divided by
                             *   the total number of locations for
                             *   changes of scaling only.
                             */
      IdxRotationPosStable, /**< Rotation stability defined as
                             *   total number of stable locations
                             *   divided by the total number of
                             *   locations for changes in the rotation
                             *   only.
                             */
      IdxRSPosStable,       /**< Rotation stability defined as
                             *   total number of stable locations
                             *   divided by the total number of
                             *   locations for changes in the rotation
                             *   and scale. This will only be computed
                             *   if the RSStability bit in the parameters
                             *   is enabled (it costs too much time!).
                             */
      IdxScaleAStable,      /**< Scale angular stability defined as
                             *   total number of angular stable
                             *   locations divided by the total number
                             *   of locations for changes of scaling
                             *   only.
                             */
      IdxRotationAStable,   /**< Rotation angular stability defined
                             *   as total number of angular stable
                             *   locations divided by the total number
                             *   of locations for changes in the
                             *   rotation only.
                             */
      IdxRSAStable,         /**< Angular stability defined as total
                             *   number of angular stable locations
                             *   divided by the total number of
                             *   locations for changes in the rotation
                             *   and scale.  This will only be computed
                             *   if the RSStability bit in the parameters
                             *   is enabled (it costs too much time!).
                             */
    };
                  


    /**
     * Evaluate the set of images (in the parameters) using the
     * given parameterization.
     *
     * @param param parameters of the location selector to be used in
     *              the evaluation.
     * @param fitness multidimensional fitness measures for each image in
     *                one row.
     * @param onlyMeanAndVariance if true, the mean and variance of all
     *        results will be computed.  Otherwise all fitness measures
     *        for all images will be provided.
     */
    bool evaluate(const pyramidLocationSearch::parameters& param,
                  dmatrix& fitness,const bool onlyMeanAndVariance = false);

    /**
     * Evaluation of the location search with the given channel using
     * the given parameterization.
     */
    bool evaluate(const channel& chnl,
                  const pyramidLocationSearch::parameters& param,
                  dvector& fitness);

    //@}

  protected:
    /**
     * Total number of fitness measures that will be computed
     * 
     */
    static const int totalFitnessDimensionality;

    /**
     * Evaluation of the location search with the given channel
     * using the given parameterization.
     */
    bool evaluate(const channel& chnl,
                  const channel8& mask,
                  dvector& fitness);

    /**
     * Compare both location sets.
     *
     * @param olocs original image location set.
     * @param blocs back-transformed location set from the location extracted
     *              from the transformed image.
     * @param posStable number of locations stable respect their position
     * @param rotStable number of locations also stable in detected
     *                  rotation angle (rotStable <= posStable).
     * @return true if successful, false otherwise.
     */
    bool compare(const kdTree<tpoint<float>,int>& olocs,
                 const std::vector<location>& olocs,
                 const std::vector<location>& blocs,
                 int& posStable,
                 int& rotStable) const;

  private:
    /**
     * Structure containing a single enum with the number of bits required
     * for each parameter.
     */
    struct bits;

    /**
     * Functor used for the location search need only one setup for one
     * parameter set
     */
    pyramidLocationSearch locationSearcher;

    /**
     * Get the image name
     */
    std::string getMaskName(const std::string& imgName,
                            const std::string& postfix) const;

    /**
     * All channels read.
     *
     * Since the tests take a very long time, usually just a few images
     * are used here.  It is much better to read them once here.
     */
    std::vector<channel> imageData;

    /**
     * All mask for channels read.
     *
     * Since the tests take a very long time, usually just a few images
     * are used here.  It is much better to read them once and cache them here.
     *
     * The maskData contains the segmentation mask of the imageData, used to
     * optimize the selection of mask in the imporant regions.  If a
     * channel is empty, all locations will be valid.
     */
    std::vector<channel8> maskData;

  };
}

#endif