octave_packages/image-1.0.15/bwdist.m

   1 ## Copyright (C) 2006  Stefan Gustavson
   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 2, 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{D} =} bwdist(@var{bw})
  18 ##
  19 ## Computes the distance transform of the image @var{bw}.
  20 ## @var{bw} should be a binary 2D array, either a Boolean array or a
  21 ## numeric array containing only the values 0 and 1.
  22 ## The return value @var{D} is a double matrix of the same size as @var{bw}.
  23 ## Elements with value 0 are considered background pixels, elements
  24 ## with value 1 are considered object pixels. The return value
  25 ## for each background pixel is the distance (according to the chosen
  26 ## metric) to the closest object pixel. For each object pixel the
  27 ## return value is 0.
  28 ##
  29 ## @deftypefnx{Function File} {@var{D} =} bwdist(@var{bw}, @var{method})
  30 ##
  31 ## @var{method} is a string to choose the distance metric. Currently
  32 ## available metrics are 'euclidean', 'chessboard', 'cityblock' and
  33 ## 'quasi-euclidean', which may each be abbreviated to any string
  34 ## starting with 'e', 'ch', 'ci' and 'q', respectively.
  35 ## If @var{method} is not specified, 'euclidean' is the default.
  36 ##
  37 ## @deftypefnx {Function File} {[@var{D},@var{C}] =} bwdist(@var{bw}, @var{method})
  38 ##
  39 ## If a second output argument is given, the linear index for the
  40 ## closest object pixel is returned for each pixel. (For object
  41 ## pixels, the index points to the pixel itself.) The return value
  42 ## @var{C} is a matrix the same size as @var{bw}.
  43 ## @end deftypefn
  44
  45 # This M wrapper is an almost direct pass-through to an oct function,
  46 # but it might prove useful for a future extension to handle N-D data.
  47 # The algorithm implemented by __bwdist() is 2D-only.
  48
  49 function [D, C] = bwdist(bw, method = "euclidean")
  50
  51   if (!ischar(method))
  52     error("bwdist: method name must be a string");
  53   endif
  54
  55   if (nargout < 2)
  56     D = __bwdist(bw, method);
  57   else
  58     [D, C] = __bwdist(bw, method);
  59   endif
  60
  61 endfunction