CornerDetectorSusan.hh

/*
This file is distributed as part of the BIAS library (Basic ImageAlgorithmS)
but it has not been developed by the authors of BIAS.

For copyright, author and license information see below.
*/


/* {{{ Copyright etc. */

/**********************************************************************\

  SUSAN Version 2l by Stephen Smith
  Oxford Centre for Functional Magnetic Resonance Imaging of the Brain,
  Department of Clinical Neurology, Oxford University, Oxford, UK
  (Previously in Computer Vision and Image Processing Group - now
  Computer Vision and Electro Optics Group - DERA Chertsey, UK)
  Email:    steve@fmrib.ox.ac.uk
  WWW:      http://www.fmrib.ox.ac.uk/~steve

  (C) Crown Copyright (1995-1999), Defence Evaluation and Research Agency,
  Farnborough, Hampshire, GU14 6TD, UK
  DERA WWW site:
  http://www.dera.gov.uk/
  DERA Computer Vision and Electro Optics Group WWW site:
  http://www.dera.gov.uk/imageprocessing/dera/group_home.html
  DERA Computer Vision and Electro Optics Group point of contact:
  Dr. John Savage, jtsavage@dera.gov.uk, +44 1344 633203

  A UK patent has been granted: "Method for digitally processing
  images to determine the position of edges and/or corners therein for
  guidance of unmanned vehicle", UK Patent 2272285. Proprietor:
  Secretary of State for Defence, UK. 15 January 1997

  This code is issued for research purposes only and remains the
  property of the UK Secretary of State for Defence. This code must
  not be passed on without this header information being kept
  intact. This code must not be sold.

\**********************************************************************/

/* }}} */
/* {{{ Readme First */

/**********************************************************************\

  SUSAN Version 2l
  SUSAN = Smallest Univalue Segment Assimilating Nucleus

  Email:    steve@fmrib.ox.ac.uk
  WWW:      http://www.fmrib.ox.ac.uk/~steve

  Related paper:
  @article{Smith97,
        author = "Smith, S.M. and Brady, J.M.",
        title = "{SUSAN} - A New Approach to Low Level Image Processing",
        journal = "Int. Journal of Computer Vision",
        pages = "45--78",
        volume = "23",
        number = "1",
        month = "May",
        year = 1997}

  To be registered for automatic (bug) updates of SUSAN, send an email.

  Compile with:
  gcc -O4 -o susan susan2l.c -lm

  See following section for different machine information. Please
  report any bugs (and fixes). There are a few optional changes that
  can be made in the "defines" section which follows shortly.

  Usage: type "susan" to get usage. Only PGM format files can be input
  and output. Utilities such as the netpbm package and XV can be used
  to convert to and from other formats. Any size of image can be
  processed.

  This code is written using an emacs folding mode, making moving
  around the different sections very easy. This is why there are
  various marks within comments and why comments are indented.


  SUSAN QUICK:

  This version of the SUSAN corner finder does not do all the
  false-corner suppression and thus is faster and produced some false
  positives, particularly on strong edges. However, because there are
  less stages involving thresholds etc., the corners that are
  correctly reported are usually more stable than those reported with
  the full algorithm. Thus I recommend at least TRYING this algorithm
  for applications where stability is important, e.g., tracking.

  THRESHOLDS:

  There are two thresholds which can be set at run-time. These are the
  brightness threshold (t) and the distance threshold (d).

  SPATIAL CONTROL: d

  In SUSAN smoothing d controls the size of the Gaussian mask; its
  default is 4.0. Increasing d gives more smoothing. In edge finding,
  a fixed flat mask is used, either 37 pixels arranged in a "circle"
  (default), or a 3 by 3 mask which gives finer detail. In corner
  finding, only the larger 37 pixel mask is used; d is not
  variable. In smoothing, the flat 3 by 3 mask can be used instead of
  a larger Gaussian mask; this gives low smoothing and fast operation.

  BRIGHTNESS CONTROL: t

  In all three algorithms, t can be varied (default=20); this is the
  main threshold to be varied. It determines the maximum difference in
  greylevels between two pixels which allows them to be considered
  part of the same "region" in the image. Thus it can be reduced to
  give more edges or corners, i.e. to be more sensitive, and vice
  versa. In smoothing, reducing t gives less smoothing, and vice
  versa. Set t=10 for the test image available from the SUSAN web
  page.

  ITERATIONS:

  With SUSAN smoothing, more smoothing can also be obtained by
  iterating the algorithm several times. This has a different effect
  from varying d or t.

  FIXED MASKS:

  37 pixel mask:    ooo       3 by 3 mask:  ooo
                   ooooo                    ooo
                  ooooooo                   ooo
                  ooooooo
                  ooooooo
                   ooooo
                    ooo

  CORNER ATTRIBUTES dx, dy and I
  (Only read this if you are interested in the C implementation or in
  using corner attributes, e.g., for corner matching)

  Corners reported in the corner list have attributes associated with
  them as well as positions. This is useful, for example, when
  attempting to match corners from one image to another, as these
  attributes can often be fairly unchanged between images. The
  attributes are dx, dy and I. I is the value of image brightness at
  the position of the corner. In the case of susan_corners_quick, dx
  and dy are the first order derivatives (differentials) of the image
  brightness in the x and y directions respectively, at the position
  of the corner. In the case of normal susan corner finding, dx and dy
  are scaled versions of the position of the centre of gravity of the
  USAN with respect to the centre pixel (nucleus).

  BRIGHTNESS FUNCTION LUT IMPLEMENTATION:
  (Only read this if you are interested in the C implementation)

  The SUSAN brightness function is implemented as a LUT
  (Look-Up-Table) for speed. The resulting pointer-based code is a
  little hard to follow, so here is a brief explanation. In
  setup_brightness_lut() the LUT is setup. This mallocs enough space
  for *bp and then repositions the pointer to the centre of the
  malloced space. The SUSAN function e^-(x^6) or e^-(x^2) is
  calculated and converted to a uchar in the range 0-100, for all
  possible image brightness differences (including negative
  ones). Thus bp[23] is the output for a brightness difference of 23
  greylevels. In the SUSAN algorithms this LUT is used as follows:

  p=in + (i-3)*x_size + j - 1;
  p points to the first image pixel in the circular mask surrounding
  point (x,y).

  cp=bp + in[i*x_size+j];
  cp points to a position in the LUT corresponding to the brightness
  of the centre pixel (x,y).

  now for every pixel within the mask surrounding (x,y),
  n+=*(cp-*p++);
  the brightness difference function is found by moving the cp pointer
  down by an amount equal to the value of the pixel pointed to by p,
  thus subtracting the two brightness values and performing the
  exponential function. This value is added to n, the running USAN
  area.

  in SUSAN smoothing, the variable height mask is implemented by
  multiplying the above by the moving mask pointer, reset for each new
  centre pixel.
  tmp = *dpt++ * *(cp-brightness);

\**********************************************************************/

/* }}} */

#ifndef __CornerDetectorSusan_hh__
#define __CornerDetectorSusan_hh__

#include "CornerDetectorBase.hh"

#define DEFAULT_THRESH 50
#define DEFAULT_QUICK false
/// size for non-max corner suppression; SEVEN_SUPP or FIVE_SUPP
#define SEVEN_SUPP 
/// max corners per frame, for susan and our "harris"
#define MAX_CORNERS   10000   
#define CORNERDETECTOR_SUSAN_MAXNUM_DEFAULT 1850

namespace BIAS {

  /** 
      @class cornerstruct
      @ingroup g_feature
      @brief used only by Susan corner detector 
  */
  struct cornerstruct   {
    int x, y, info, dx, dy, I;
  };

  typedef struct cornerstruct CORNER_LIST[MAX_CORNERS];

  /** @class CornerDetectorSusan
      @ingroup g_feature
      @brief The Susan corner detector (oxford implementation, see license)

      See documentation inside CornerDetectorSusan.hh
      @author woelk 09/2004 */
  template <class StorageType>
  class BIASFeatureDetector_EXPORT CornerDetectorSusan 
    : public CornerDetectorBase<StorageType>
  {
  public:
    CornerDetectorSusan();
    ~CornerDetectorSusan();

    /** @brief Susan Corner Detector returning homogenous points, 
        @author woelk */
    virtual int Detect(const Image<StorageType>& image, 
                       std::vector<HomgPoint2D>& pvec, 
                       std::vector<QUAL>& quality);

    /** @brief Susan Corner Detector returning corner list, 
        fast interface for daimler
        @author woelk */
    int Detect(const Image<StorageType>& image, CORNER_LIST corner_list,
              int& num);

    /** @brief Susan Corner Detector returning corner list, 
        only detects corners where roi!=0
        @author woelk */
    int Detect(const Image<StorageType>& image, const Image<StorageType>& roi,
               CORNER_LIST corner_list, int& num);

  protected:
    /// parameter
    int _Threshold;
    bool _Quick;

    /// local vars for susan
    int *_cgx, *_cgy, *_r, _susansize, _susanthresh, _num;
    StorageType *_bp;

    /// protected function for susan
    void _int_to_uchar(const int *r, StorageType *in, int size);

    /// protected function for susan
    //void _setup_brightness_lut(StorageType **bp, int thresh, int form);
    void _setup_brightness_lut(int thresh, int form);

    /// returns the number of corners found
    int _susan_corners(const StorageType *in, int *r, StorageType *bp, 
                       CORNER_LIST corner_list, int x_size, 
                       int y_size);
    
    /** faster version of the above 
        @author woelk 08 2003  */
    int _susan_corners(const StorageType *in, int *r, StorageType *bp, 
                       CORNER_LIST corner_list, int x_size, 
                       int y_size, const StorageType *roi);

    /// returns the number of corners found
    int _susan_corners_quick(const StorageType *in, int *r, StorageType *bp, 
                             CORNER_LIST corner_list, int x_size, 
                             int y_size);

    /// allocates the internal data structures for susan corner detector
    inline void _SusanReAllocMem(int x_size, int y_size)
    {
      _susansize=x_size*y_size;
      if (_cgx!=NULL) delete[] _cgx;
      if (_cgy!=NULL) delete[] _cgy;
      if (_r!=NULL) delete[] _r;
      _r = new int[_susansize];
      _cgx=new int[_susansize];
      _cgy=new int[_susansize];
    };

  }; // class

} // namespace


#endif // __CornerDetectorSusan_hh__