octave_packages/image-1.0.15/imfilter.m

   1 ## Copyright (C) 2007  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, or (at your option)
   6 ## any later version.
   7 ##
   8 ## This program is distributed in the hope that it will be useful, but
   9 ## WITHOUT ANY WARRANTY; without even the implied warranty of
  10 ## MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  11 ## General Public License for more details.
  12 ##
  13 ## You should have received a copy of the GNU General Public License
  14 ## along with this file.  If not, see <http://www.gnu.org/licenses/>.
  15
  16 ## -*- texinfo -*-
  17 ## @deftypefn {Function File} @var{J} = imfilter(@var{I}, @var{f})
  18 ## @deftypefnx{Function File} @var{J} = imfilter(@var{I}, @var{f}, @var{options}, ...)
  19 ## Computes the linear filtering of the image @var{I} and the filter @var{f}.
  20 ## The computation is performed using double precision floating point numbers,
  21 ## but the class of the input image is preserved as the following example shows.
  22 ## @example
  23 ## I = 255*ones(100, 100, "uint8");
  24 ## f = fspecial("average", 3);
  25 ## J = imfilter(I, f);
  26 ## class(J)
  27 ## @result{} ans = uint8
  28 ## @end example
  29 ##
  30 ## The function also accepts a number of optional arguments that control the
  31 ## details of the filtering. The following options is currently accepted
  32 ## @table @samp
  33 ## @item S
  34 ## If a scalar input argument is given, the image is padded with this scalar
  35 ## as part of the filtering. The default value is 0.
  36 ## @item "symmetric"
  37 ## The image is padded symmetrically.
  38 ## @item "replicate"
  39 ## The image is padded using the border of the image.
  40 ## @item "circular"
  41 ## The image is padded by circular repeating of the image elements.
  42 ## @item "same"
  43 ## The size of the output image is the same as the input image. This is the default
  44 ## behaviour.
  45 ## @item "full"
  46 ## Returns the full filtering result.
  47 ## @item "corr"
  48 ## The filtering is performed using correlation. This is the default behaviour.
  49 ## @item "conv"
  50 ## The filtering is performed using convolution.
  51 ## @end table
  52 ## @seealso{conv2, filter2, fspecial, padarray}
  53 ## @end deftypefn
  54
  55 function retval = imfilter(im, f, varargin)
  56   ## Check number of input arguments
  57   if (nargin < 2)
  58     print_usage();
  59   endif
  60
  61   ## Check image
  62   if (!ismatrix(im))
  63     error("imfilter: first input argument must be an image");
  64   endif
  65   [imrows, imcols, imchannels, tmp] = size(im);
  66   if (tmp != 1 || (imchannels != 1 && imchannels != 3))
  67     error("imfilter: first input argument must be an image");
  68   endif
  69   C = class(im);
  70
  71   ## Check filter (XXX: matlab support 3D filter, but I have no idea what they do with them)
  72   if (!ismatrix(f))
  73     error("imfilter: second input argument must be a matrix");
  74   endif
  75   [frows, fcols, tmp] = size(f);
  76   if (tmp != 1)
  77     error("imfilter: second argument must be a 2-dimensional matrix");
  78   endif
  79
  80   ## Parse options
  81   res_size = "same";
  82   res_size_options = {"same", "full"};
  83   pad = 0;
  84   pad_options = {"symmetric", "replicate", "circular"};
  85   ftype = "corr";
  86   ftype_options = {"corr", "conv"};
  87   for i = 1:length(varargin)
  88     v = varargin{i};
  89     if (any(strcmpi(v, pad_options)) || isscalar(v))
  90       pad = v;
  91     elseif (any(strcmpi(v, res_size_options)))
  92       res_size = v;
  93     elseif (any(strcmpi(v, ftype_options)))
  94       ftype = v;
  95     else
  96       warning("imfilter: cannot handle input argument number %d", i+2);
  97     endif
  98   endfor
  99
 100   ## Pad the image
 101   im = padarray(im, floor([frows/2, fcols/2]), pad);
 102   if (mod(frows,2) == 0)
 103     im = im(1:end-1, :, :);
 104   endif
 105   if (mod(fcols,2) == 0)
 106     im = im(:, 1:end-1, :);
 107   endif
 108
 109   ## Do the filtering
 110   if (strcmpi(res_size, "same"))
 111     res_size = "valid";
 112   else # res_size == "full"
 113     res_size = "same";
 114   endif
 115   if (strcmpi(ftype, "corr"))
 116     for i = imchannels:-1:1
 117       retval(:,:,i) = filter2(f, im(:,:,i), res_size);
 118     endfor
 119   else
 120     for i = imchannels:-1:1
 121       retval(:,:,i) = conv2(im(:,:,i), f, res_size);
 122     endfor
 123   endif
 124
 125   ## Change the class of the output to the class of the input
 126   ## (the filtering functions returns doubles)
 127   retval = cast(retval, C);
 128
 129 endfunction