ltiEdgeSaliency.h

/*
 * Copyright (C) 2000, 2001, 2002, 2003, 2004, 2005, 2006
 * 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 Digital Image/Signal Processing Library
 * file .......: ltiEdgeSaliency.h
 * authors ....: Stefan Syberichs
 * organization: LTI, RWTH Aachen
 * creation ...: 17.3.2000
 * revisions ..: $Id: ltiEdgeSaliency.h,v 1.8 2006/02/08 11:03:05 ltilib Exp $
 */


#ifndef _LTI_EDGE_SALIENCY_H_
#define _LTI_EDGE_SALIENCY_H_

#include "ltiObject.h"
#include "ltiMatrix.h"
#include "ltiVector.h"
#include "ltiSaliency.h"

namespace lti {

  /**
   * A class for edge based strcutural saliency calculations.
   *
   * Structural Saliency as proposed by A. Shashua and S. Ullman
   * extracts salient information out of edge images. A salient
   * structure in our terms is a long line of pixels with low
   * curvation.  This modifier can be used to produce input data for a
   * feature map as well as a preprocessing stage for further
   * segmentation.  The methods work on binary (!) edge maps
   * (lti::channel or lti::channel8), where a white pixel should mark
   * an edge point and a black pixel is part of the background. Edge
   * data like that can be generated by the edge detectors lti::susanEdges
   * or lti::cannyEdges.
   * The behaviour of the edgeSaliency methods can be controled by 8
   * parameters in a very wide range, where the optimal values have to
   * be adapted to the actual problem.
   *
   * For more information see <em> A. Shashua, S.Ullman 1988: Structural
   * Saliency, Proceedings of the international conference on Computer
   * Vision, 482-488 (ISBN 0-8186-0883-8)</em>
   *
   * Usage:
   *
   * \code
   *  // ---- preparations to obtain binary edges --- //
   *
   *  lti::splitImageToRGB rgb;
   *  lti::channel8 R, G, B, edges;
   *  lti::image theimage;
   *
   *  // load an image
   *  ...
   *
   *  // rgb or any other channel split
   *  rgb.apply(theimage, R, G, B);
   *
   *
   *  lti::susanEdges susanedge;
   *  lti::susanEdges::parameters edgeparams;
   *
   *  edgeparams.gamma = 10;
   *  susanedge.setParameters(edgeparams);
   *
   *  // extract binary edges from red channel
   *  susanedge.apply(R, edges);
   *
   *  // --- actual saliency part --- //
   *
   *  lti::edgeSaliency sal;
   *  lti::channel salmap;
   *  lti::edgeSaliency::parameters salparam;
   *
   *  salparam.iterations = 20;
   *  salparam.couplingCenter = 0.2;
   *  salparam.couplingNeighbour = 0.0;
   *  salparam.rho = 0.6;
   *  salparam.initialSigma = 1.0;
   *  salparam.gamma = 0.5;
   *  salparam.curvationTable=lti::edgeSaliency::parameters::biased;
   *
   *  sal.setParameters(salparam);
   *
   *  sal.apply(edges, salmap);
   *
   *  // ready. the saliency map is in salmap now.
   *
   * \endcode
   */
  class edgeSaliency : public saliency {
  public:

    typedef vector<float> eVector;

    /**
     * the parameters for the class edgeSaliency
     */
    class parameters : public saliency::parameters {
    public:

      enum curvationType {standard, biased};

      /**
       * default constructor
       */
      parameters();

      /**
       * copy constructor
       */
      parameters(const parameters& other);

      /**
       * destructor
       */
      ~parameters();

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

      /**
       * copy member
       */
      parameters& copy(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;

      /**
       * 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 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 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 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
      // --------------------------------------------

      /**  A coupling constant for the parameter sigma. couplingCenter is
       *   the coupling value
       *   in case that the regarded pixel is an edge and the regarded
       *   neighbour is a background pixel. A non-zero value for
       *   <code> couplingCenter </code> provides the ability for
       *   the saliency algorithmn to close gaps in a line segment.
       *   reasonable values are
       *   <pre>
       *   0 <=  couplingCenter <= 0.7
       *   </pre>
       *   A high couplingCenter value will blur the resulting saliency map.
       *   The default is 0.0;
       */
      float couplingCenter;

      /** A coupling constant for the parameter sigma. CouplingNeighbour
       *  is the coupling value
       *  in case that the regarded pixel is a part of the background and
       *  the regarded neighbour is an edge pixel. A non-zero value for
       *  <code> couplingCenter </code> provides the ability for
       *  the saliency algorithmn to close gaps in a line segment.
       *  reasonable values are
       *  <pre>
       *  0 <=  couplingNeighbour <= 0.5
       *  </pre>
       *  Any non-zero will significantly blur the resulting saliency map.
       *  The default is 0.0
       */
      float couplingNeighbour;

      /**
       * the intial coupling constant for active orientation elements.
       *
       * in the initial computation step, all orientation elements
       * that are made up by two edge pixels are marked as <em>
       * active </em> by initialising them with <code> initialSigma
       * </code>.  <code> initialSigma </code> is normaly 1.0. Such
       * orientation elements, that are made up by one edge and one
       * background pixel are initialised with either
       * <code>couplingCenter</code> or <code>couplingNeighbour</code>.
       * The default is 1.0
       */
      float initialSigma;

      /** Number of updating iterations.
       *
       * Since the the updating procedure of the saliency activities
       * is implemented as a locally connected network, the saliency
       * map is calculated in a recursive manner. The result will
       * converge for an infinite number of iterations, but any number
       * of runs between 20 and 30 should be enough.  The default is 20.
       */
      int iterations;

      /**
       * Gap attenuation factor.
       *
       * The parameter rho is used to penalize the existance of long
       *  gaps in the regarded structures.  the factor rho is always
       *  associated to an orientation element, where the constant
       *  value 1.0 is assigned to a fully active element, and the
       *  value of <code>rho</code> to any other element. A small
       *  <code>rho</code> leads to a suppresion of fragmented
       *  structures.
       *
       *  Reasonable values are:
       *  <pre>
       *  0.1 <= rho <= 0.7
       *  </pre>
       *  The default is 0.4
       */
      float rho;

      /**
       * threshold for cutting off the saliency map.
       *
       * if <code>gamma</code> is non-zero, the all final saliency
       * values that are lower than gamma will be cut off (i.e. set to
       * black) in the resulting saliency map. This can be used to get
       * rid of weak, unsalient structures in the image.
       *
       * Reasonable values are:
       * <pre>
       * 0 <= gamma <= 0.5
       * </pre>
       * This paramter has no effect, if the map is not normalised !
       * The default is 0.5.
       */
      float gamma;

      /**
       * normalize the saliency map (recommended).
       *
       * the resulting map is normalised with regard
       * to the maximum value.
       * The map is normalised, if <code>normalise</code> is <code>true</code>.
       * The default is <code>true</code>
       */
      bool normalise;

      /**
       * binarise the resulting saliency map.
       * If normalisation and a reasonable gamma are chosen,
       * the rest of the saliency information is set to
       * 1.0 (or 255 respectively). Used as a preprocessing stage
       * for further segmentation (use with care!).
       * This parameter has no effect if the map is not normalised !
       * The default is <code>false</code>.
       */
      bool binarise;

      /**
       * type of curvation table.
       * The curvation factor between to orientation elements is used to
       * promote line elements with low curvation, or to penalize strong
       * curvations. Curvation in this manner means depends on the  angle
       * between two sucvcessive orientation elements according to:
       *
       * \f[ c=\exp\left(-\cfrac{2\alpha\tan(\alpha/2)}{\delta}\right)\f]
       * 0 < c < 1
       *
       * where <code>alpha</code> is the mentioned angle and delta the length
       * of an orientation element. The the shape of the curvation function
       * c strongly depends on the denominator delta, i.e. the way in which
       * <em>low</em> curvations are penalized.
       * Therefor, two curvation lookup tables have been provided with
       * two characteristic shapes:
       *
       * - <b>standard</b> curvation with <code>delta = 1</code> which
       *   penalizes low,  non-zeo curvations stronger than the
       *
       * - <b>biased</b> curvation, where <code>delta = 2</code>.
       *
       * The default is <code>edgeSaliency::parameters::standard</code>
       */
      curvationType curvationTable;
    };

    /**
     * default constructor
     */
    edgeSaliency();

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

    /**
     * destructor
     */
    virtual ~edgeSaliency();

    /**
     * returns the name of this type ("edgeSaliency")
     */
    virtual const char* getTypeName() const;


    /**
     * Applies structural saliency computation on-place.
     * @param srcdest channel8 with the source data (binary edges,
     *                black bakcground!).The result will be left here too.
     * @return true if successful, false otherwise.
     */
    bool apply(channel8& srcdest) const;

    /**
     * Applies structural saliency computation on-place.
     * @param srcdest channel8 with the source data (binary edges,
     *                black bakcground!).The result will be left here too.
     * @return true if successful, false otherwise.
     */
    bool apply(channel& srcdest) const;

    /**
     * Applies strcuctural saliency computation on-copy.
     * @param src channel8 with the source data (binary edges, black
     *                     background).
     * @param dest channel8 where the result will be left.
     * @return true if successful, false otherwise.
     */
    bool apply(const channel8& src,channel8& dest) const;

    /**
     * Applies strcuctural saliency computation on-copy.
     * @param src channel8 with the source data (binary edges, black
     * background)
     * @param dest channel where the result will be left.
     * @return true if successful, false otherwise.
     */
    bool apply(const channel& src,channel& dest) const;

    /**
     * Applies strcuctural saliency computation on-copy.
     * This is the fastest method, since all other apply
     * members refer to this method using additional casts or copy operations!
     * @param src channel8 with the source data (binary edges, black
     *            background)
     * @param dest channel8 where the result will be left.
     * @return true if successful, false otherwise.
     */
    virtual bool apply(const channel8& src, channel& dest) const;

    /**
     * copy data of "other" functor.
     */
    edgeSaliency& copy(const edgeSaliency& other);

    /**
     * returns a pointer to a clone of the functor.
     */
    virtual functor* clone() const;

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


  private:

    /**
     * the one and only saliency computation.
     * the local saliency values of each orientation element E_i
     * of each pixel of the image is update according to the
     * following equations:
     *
     * \code
     *
     * E_i(0) = sigma_i
     * E_i(n+1) = sigma_i + rho_i * max E_j(n) * curvation(i,j)
     *
     * \endcode
     *
     * where <code>sigma_i</code> is the appropriate sigma of an
     * orientation element, given by one of the parameters
     * <em>initialSigma</em>, <em>couplingCenter</em>, or
     * <em>couplingNeighbour</em> (for explanantion see parameter
     * class).  <code>rho_i</code> is the gap factor and E the
     * saliency activity.  The number of loops <code>n</code> is given
     * by the parameter <code>iterations</code>, where n=20 is a good
     * choice (The saliency will converge for an infinite number of
     * updates).
     */
    void updateSaliency(const channel8& src, channel& map) const;

    /**
     * Same thing as the update method above.
     * The <code>src</code> is casted to lti::channel8
     * to invoke the original update method.
     */
    void updateSaliency(const channel& src, channel& map) const;

    /**
     * returns a rho depending on sigma.
     *
     * If an edge element is <em>active</em>, i.e. if its sigma value
     * is non-zero, the function returns the value 1.0.  Otherwise,
     * the value specified by the parameter <code>rho<code> is
     * returned to penalize a <em>virtual</em>edge element.  <b> The
     * behaviour of this function is subject to change!<b> @param
     * sigma the sigma value to determine whether an element is
     * <em>active</em> or <em>virtual</em>.  @result 1.0 if the edge
     * is <em>active</em> or the parameter rho otherwise.
     */
    float rho(const float sigma) const;

    /**
     * returns a local curvation value.
     *
     * The curvation of two successive orientation elements i and j
     * is calculated according to:
     *
     * \f[ c=\exp\left(-\cfrac{2\alpha\tan(\alpha/2)}{\delta}\right)\f]
     * 0 < c < 1
     *
     * where <code>alpha</code> is the angle between the
     * elements i and j. <code>delta</code> is 1.0 (standard)
     * or 2.0 (biased).
     */
    float curvation(const int pi, const int pj) const;

    /**
     * biased curvation table
     */
    static float curvationLookupTable2[8][8];

    /**
     * standard curvation table
     */
    static float curvationLookupTable1[8][8];

    /**
     * radian angles
     */
    static float radAngles16[16][16];

    /**
     * geometric length
     */
    static float geometricLength[16];

    /**
     * get orientation
     */
    int getOrientation16(const point here, const point there) const;

    /**
     * get neighbour of a given point
     */
    point getNeighbour(const point here, const int direction) const;

    /**
     * orientation square mean
     */
    float orientationSquareMean(const int i, const int j)const;
  };
}

#endif