octave_packages/image-1.0.15/houghtf.m

   1 ## Copyright (C) 2008 Soren Hauberg
   2 ##
   3 ## This program is free software; you can redistribute it and/or modify
   4 ## it under the terms of the GNU General Public License as published by
   5 ## the Free Software Foundation; either version 3 of the License, or
   6 ## (at your option) any later version.
   7 ##
   8 ## This program is distributed in the hope that it will be useful,
   9 ## but WITHOUT ANY WARRANTY; without even the implied warranty of
  10 ## MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  11 ## GNU General Public License for more details.
  12 ##
  13 ## You should have received a copy of the GNU General Public License
  14 ## along with this program; if not, write to the Free Software
  15 ## Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
  16
  17 ## -*- texinfo -*-
  18 ## @deftypefn {Function File} @var{H} = houghtf (@var{bw})
  19 ## @deftypefnx{Function File} @var{H} = houghtf (@var{bw}, @var{method})
  20 ## @deftypefnx{Function File} @var{H} = houghtf (@var{bw}, @var{method}, @var{arg})
  21 ## Perform the Hough transform for lines or circles.
  22 ##
  23 ## The @var{method} argument chooses between the Hough transform for lines and
  24 ## circles. It can be either "line" (default) or "circle".
  25 ##
  26 ## @strong{Line Detection}
  27 ##
  28 ## If @var{method} is "line", the function will compute the Hough transform for
  29 ## lines. A line is parametrised in @var{r} and @var{theta} as
  30 ## @example
  31 ## @var{r} = x*cos(@var{theta}) + y*sin(@var{theta}),
  32 ## @end example
  33 ## where @var{r} is distance between the line and the origin, while @var{theta}
  34 ## is the angle of the vector from the origin to this closest point. The result
  35 ## @var{H} is an @var{N} by @var{M} matrix containing the Hough transform. Here,
  36 ## @var{N} is the number different values of @var{r} that has been attempted.
  37 ## This is computed as @code{2*diag_length - 1}, where @code{diag_length} is
  38 ## the length of the diagonal of the input image. @var{M} is the number of
  39 ## different values of @var{theta}. These can be set through the third input
  40 ## argument @var{arg}. This must be a vector of real numbers, and is by default
  41 ## @code{pi*(-90:90)/180}.
  42 ##
  43 ## @strong{Circle Detection}
  44 ##
  45 ## If @var{method} is "circle" the function will compute the Hough transform for
  46 ## circles. The circles are parametrised in @var{r} which denotes the radius of
  47 ## the circle. The third input argument @var{arg} must be a real vector containing
  48 ## the possible values of @var{r}.
  49 ## If the input image is @var{N} by @var{M}, then the result @var{H} will be an
  50 ## @var{N} by @var{M} by @var{K} array, where @var{K} denotes the number of
  51 ## different values of @var{r}.
  52 ##
  53 ## As an example, the following shows how to compute the Hough transform for circles
  54 ## with radius 3 or 7 in the image @var{im}
  55 ## @example
  56 ## bw = edge(im);
  57 ## H = houghtf(bw, "circle", [3, 7]);
  58 ## @end example
  59 ## Here @var{H} will be an NxMx2 array, where @var{H}(:,:,1) will contain the
  60 ## Hough transform for circles with radius 3, and @var{H}(:,:,2) for radius 7.
  61 ## To find good circles you now need to find local maximas in @var{H}. If you
  62 ## find a local maxima in @var{H}(row, col, 1) it means that a good circle exists
  63 ## with center (row,col) and radius 3. One way to locate maximas is to use the
  64 ## @code{immaximas} function.
  65 ##
  66 ## @seealso{hough_line, hough_circle, immaximas}
  67 ## @end deftypefn
  68
  69 function [accum, R] = houghtf(bw, varargin)
  70   ## Default arguments
  71   method = "line";
  72   args = {};
  73
  74   ## Check input arguments
  75   if (nargin == 0)
  76     error("houghtf: not enough input arguments");
  77   endif
  78
  79   if (!ismatrix(bw) || ndims(bw) != 2)
  80     error("houghtf: first arguments must be a 2-dimensional matrix");
  81   endif
  82
  83   if (nargin > 1)
  84     if (ischar(varargin{1}))
  85       method = varargin{1};
  86       args = varargin(2:end);
  87     else
  88       args = varargin;
  89     endif
  90   endif
  91
  92   ## Choose method
  93   switch (lower(method))
  94     case "line"
  95       [accum, R] = hough_line(bw, args{:});
  96     case "circle"
  97       accum = hough_circle(bw, args{:});
  98     otherwise
  99       error("houghtf: unsupported method '%s'", method);
 100   endswitch
 101
 102 endfunction