CannyEdge.hh

/*
 This file is part of the BIAS library (Basic ImageAlgorithmS).

 Copyright (C) 2003-2009    (see file CONTACT for details)
 Multimediale Systeme der Informationsverarbeitung
 Institut fuer Informatik
 Christian-Albrechts-Universitaet Kiel


 BIAS is free software; you can redistribute it and/or modify
 it under the terms of the GNU Lesser General Public License as published by
 the Free Software Foundation; either version 2.1 of the License, or
 (at your option) any later version.

 BIAS 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 BIAS; if not, write to the Free Software
 Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
 */

#ifndef __CANNYEDGE_HH_
#define __CANNYEDGE_HH_

#include "FilterBase.hh"
#include "Convolution.hh"
#include "Gauss.hh"

namespace BIAS {
  /** @class CannyEdge
      @ingroup g_filter
      @brief Canny edge detector

      uses gradient calculation on upsampled images<br>
      Low and High thresholds for hysteresis can either be set manually or be determined by histogram segmentation.<br />
      For the latter, use SetThresholdsRelative(low, high) to set the number of pixels in percent in the magnitude image to not<br />
      be evaluated by hysteresis. Per default, the lowest 60 percent of all pixels define the lower threshold and the upper 10 percent<br />
      of all pixels define the higher threshold.<br>
      Implementation follows the online tutorial of http://www.pages.drexel.edu/~weg22/can_tut.html closely.
      <br /><br />
      Only tested for InputStorageType unsigned char, OutputStorageType float!

      @author fkellner 11/2008 */
  template <class InputStorageType, class OutputStorageType>
  class BIASFilter_EXPORT CannyEdge: public FilterBase<InputStorageType, OutputStorageType> {
    public:
      
      /// @brief Constructor, setting default values
      CannyEdge();
      
      virtual ~CannyEdge();

      /// @brief call for getting all intermediary results
      virtual int Filter(const Image<InputStorageType>& src,
                         Image<OutputStorageType>& gx,
                         Image<OutputStorageType>& gy,
                         Image<OutputStorageType>& magnitude,
                         Image<OutputStorageType>& gdir,
                         Image<OutputStorageType>& dst);

      /// @brief call for only getting the (binary) edge image
      virtual int Filter(const Image<InputStorageType>& src,
                         Image<OutputStorageType>& dst);

      /// @brief get copy of this filter
      virtual CannyEdge<InputStorageType, OutputStorageType>* Clone() const 
      { return new CannyEdge<InputStorageType, OutputStorageType>(*this); }

      /// @brief not implemented
      virtual void GetBordersValid_(int &border_x, int &border_y) const;

      /// @brief before edge detection, the input image is blurred with a gaussian. Set sigma here (defaults to 1.4)
      int SetGaussSigma(float sigma);
      
      /// @brief set absolute value of low and high thresholds for hysteresis in magnitude gradient image 
      int SetThresholdsAbsolute(OutputStorageType lowAbs_, OutputStorageType highAbs_);

      /// @brief set value of low and high thresholds for hysteresis in magnitude gradient image in terms of percent of image pixels 
      int SetThresholdsRelative(unsigned int low_, unsigned int high_);

      /** @brief set edge width for hysteresis. 
       * In the hysteresis step, we walk along the detected edge pixels and look at the neighboring pixels in gradient direction to 
       * determine a pixel best suiting the edge (in terms of highest magnitude). edgeWidth defines the pixel offset to the neighbor
       * pixels, so that the default value of 1 will result in a result image with one pixel wide edges. A value of 3 will result in
       * a thicker edge, but might give more connectivity along the edges.
       */ 
      int SetEdgeWidth(unsigned int edgeWidth);
      
    protected:

      int SmoothImage_(const Image<InputStorageType>& src,
                               Image<OutputStorageType>& smoothed);

      int CalculateGradients_(const Image<OutputStorageType>& src,
                                      Image<OutputStorageType>& gx,
                                      Image<OutputStorageType>& gy,
                                      Image<OutputStorageType>& magnitude,
                                      Image<OutputStorageType>& gdir,
                                      Image<OutputStorageType>& dst);

      // gradient x direction filter
      Convolution<OutputStorageType, OutputStorageType> ConvX_;
      // gradient y direction filter
      Convolution<OutputStorageType, OutputStorageType> ConvY_;

      // determine thresholds from given pixel percentage values low and high.
      int DetermineThresholds_(const Image<OutputStorageType> &src, OutputStorageType &low, OutputStorageType &high);
      
    private:
      Gauss<InputStorageType, OutputStorageType> gauss_;

      float gsigma_;

      unsigned int w_, h_;
      
      unsigned int thresLow_, thresHigh_;
      OutputStorageType thresLowAbs_, thresHighAbs_;
      bool useAbsThresholds_;
      
      unsigned int edgeWidth_;
  };

}

#endif /* CANNYEDGE_HH_ */