"Fossies" - the Fresh Open Source Software Archive

Member "sip-0.12.1/help/en_US/bwdist.xml" (8 Apr 2012, 14188 Bytes) of package /linux/privat/sip-0.12.1.tar.gz:


As a special service "Fossies" has tried to format the requested source page into HTML format using (guessed) XML source code syntax highlighting (style: standard) with prefixed line numbers. Alternatively you can here view or download the uninterpreted source code file. See also the latest Fossies "Diffs" side-by-side code changes report for "bwdist.xml": 0.5.6_vs_0.12.1.

    1 <?xml version="1.0" encoding="ISO-8859-1"?><refentry xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:svg="http://www.w3.org/2000/svg" xmlns:mml="http://www.w3.org/1998/Math/MathML" xmlns:db="http://docbook.org/ns/docbook" version="5.0-subset Scilab" xml:lang="en" xml:id="bwdist"><info><pubdate>February 2004</pubdate></info><refnamediv><refname>bwdist</refname><refpurpose>distance transforms</refpurpose></refnamediv>
    2    <refsynopsisdiv><title>Calling Sequence</title><synopsis>[dt [, label]] = bwdist(img [,algorithm, max_dist])</synopsis></refsynopsisdiv>
    3    <refsection><title>Parameters</title>
    4       <variablelist>
    5          <varlistentry>
    6             <term>img</term>
    7             <listitem>
    8       Binary image. If every pixel is different than 0, the output is
    9       undefined and may contain arbitrary values.
   10    </listitem>
   11          </varlistentry>
   12          <varlistentry>
   13             <term>algorithm</term>
   14             <listitem>
   15       Listed below are various algorithms that are available in SIP,
   16       together with the shortest string form accepted (for speed
   17       of use). This argument is CASE-INSENSITIVE, for convenience. Some of the
   18       algorithms are faster than others, but this depends heavily
   19       on the size and content of the input.
   20       <variablelist>
   21                   <varlistentry>
   22                      <term>'euclidean' or 'euclid'</term>
   23                      <listitem>the default fast exact euclidean
   24          algorithm. Currently, it is the same as the
   25          'maurer' bellow. (DEFAULT)
   26          </listitem>
   27                      <varlistentry>
   28                         <term>'maurer' or 'mau'</term>
   29                         <listitem>very fast (and
   30             recent) exact euclidean algorithm, based on certain dimensionality
   31             properties of Voronoi diagrams. It is the best method together with
   32             Meijster, in general. The implementation of this algorithm is able
   33             to output the <literal>label</literal> array of nearest pixels
   34             (col-major) id's to each 0-pixel </listitem>
   35                      </varlistentry>
   36                      <varlistentry>
   37                         <term>'meijster' or 'mei'</term>
   38                         <listitem>very fast (and
   39             recent) exact euclidean algorithm, based on certain dimensionality
   40             properties of Voronoi diagrams. It is the best method together with
   41             Maurer, in general. For most cases it is slightly faster than
   42             Maurer, but uses a little more memory.
   43          </listitem>
   44                      </varlistentry>
   45                   </varlistentry>
   46                   <varlistentry>
   47                      <term>'cuisenaire pmn'</term>
   48                      <listitem>very fast exact euclidean
   49             algorithm. It is based on propagation of multiple
   50             neighborhoods to build up an exact EDT.
   51             </listitem>
   52                   </varlistentry>
   53                   <varlistentry>
   54                      <term>'cuisenaire pmon'</term>
   55                      <listitem>a variation of the latter that uses
   56             multiple oriented neighborhoods It seems to be slightly
   57             slower, in general, but can be faster for some cases (we
   58             don't know exactly which)
   59             </listitem>
   60                   </varlistentry>
   61                   <varlistentry>
   62                      <term>'cuisenaire psn4'</term>
   63                      <listitem>a variation
   64             of the latter that uses only 4-neighborhood. This is
   65             faster but less precise</listitem>
   66                   </varlistentry>
   67                   <varlistentry>
   68                      <term>'cuisenaire psn8'</term>
   69                      <listitem>a variation of the latter that uses
   70             diagonal neighborhood
   71             after 4-neighborhood to improve the precision. This is
   72             faster than the full 'pmn' algorithm, but less
   73             precise. It is a little slower than psn4 but considerably more
   74             precise.
   75          </listitem>
   76                   </varlistentry>
   77                   <varlistentry>
   78                      <term>'lotufo-zampirolli' or 'lotufo-z'</term>
   79                      <listitem>very fast exact euclidean
   80             algorithm. Seems to be slightly slower than maurer and
   81             cuisenaire, in general, but can be faster for some
   82             cases.
   83             </listitem>
   84                   </varlistentry>
   85                   <varlistentry>
   86                      <term>'IFT 8' or 'IFT'</term>
   87                      <listitem>a fast algorithm using the euclidean
   88             metric. For large and thick shapes, there may be a few
   89             small errors, which are dispensable for most practical
   90             applications.</listitem>
   91                   </varlistentry>
   92                   <varlistentry>
   93                      <term>'IFT 4'</term>
   94                      <listitem>the same algorithm but with
   95             4-neighborhood propagation. This means that this method
   96             is about 2x faster but less precise</listitem>
   97                   </varlistentry>
   98                   <varlistentry>
   99                      <term>'exact dilations' or 'exact dil'</term>
  100                      <listitem>will perform an exact euclidean
  101             algorithm that is slow for medium shapes, but
  102             it is always exact and reasonably fast for thin
  103             shapes.</listitem>
  104                   </varlistentry>
  105                </variablelist>
  106             </listitem> 
  107          </varlistentry> 
  108          <varlistentry>
  109             <term>max_dist</term>
  110             <listitem>
  111       The maximum distance to be computed. Defaults to infinity (all distances
  112       are computed). The resulting <literal>dt</literal> will be computed with a
  113       specialized fast propagation algorithm (currently only
  114       <literal>'cuisenaire pmn'</literal> is implemented with this option) that will
  115       visit only the required pixels within max_dist of the 0-pixels.  This will
  116       likely be faster than thresholding a full DT (computed with the default
  117       best algorithm for this) only if the number of affected pixels is
  118       sufficiently smaller than the entire image.
  119       </listitem>
  120          </varlistentry>
  121          <varlistentry>
  122             <term>dt</term> 
  123             <listitem>
  124       The distance transform of the image. It is undefined if the
  125       input is an image without any pixels equal to 0. If
  126       <literal>max_dist</literal> has been specified, then only the distances up
  127       to and including <literal>max_dist</literal> will be present; 1-pixels that are further than 
  128       <literal>max_dist</literal> are marked with a very large number,
  129       guaranteed to be larger than <literal>max_dist^2</literal>
  130             </listitem> 
  131          </varlistentry>
  132          <varlistentry>
  133             <term>label</term> 
  134             <listitem>
  135       The label map of the image. Only certain algorithm options 
  136       will be able to output this (currently only 'maurer'). If you don't specify the algorithm,
  137       then by having this in the left hand side in the function call will cause 
  138       <literal>'maurer'</literal> to run. Currently this doesn't work with
  139       <literal>max_dist</literal>.
  140       </listitem> 
  141          </varlistentry>
  142       </variablelist> 
  143    </refsection> 
  144    <refsection><title>Description</title> 
  145       <para>
  146  Function bwdist computes the distance transform. For each
  147  foreground pixel (i.e. value '1') in the input image, the
  148  distance transform assigns a value that is the smallest  distance
  149  between that pixel and the all the 0-pixels (you can also think of
  150  the distance to the outer boundary of the object). 
  151  </para>
  152       <para>
  153  Many different methods are provided for comparison purposes. If you
  154  are going to use bwdist extensively, you may test all the algorithms
  155  to find the best one for your particular type of image. 
  156  </para>
  157    </refsection> 
  158    <refsection><title>Examples</title><programlisting role="example"><![CDATA[
  159    xset('auto clear', 'on');
  160    // First, a simple example to illustrate the concept
  161    A = zeros(15,10);
  162    A(4:12,3:7)=1;
  163    A(4:5,3:4)=0
  164    D = bwdist(A)
  165    D = sqrt(D)
  166    // Note how the values in D were calculated.
  167    // For each pixel p such that A(p)=1, D(p) is the minimum euclidean 
  168    // distance of p and the 0-pixels (background).
  169 
  170    // To get the column-major index of the nearest 0-pixels, use the label output
  171    [D,L] = bwdist(A);
  172    L
  173 
  174    // -----------------------------------
  175    //  Now to a more interesting example
  176    // -----------------------------------
  177    A = gray_imread(SIPDIR + 'images/escher.png');
  178    imshow(A,2);
  179    D = bwdist(A);
  180    imshow(log(1+D),[]); // normalizes image to enhance visualization
  181    D = bwdist(A,'exact dilations');
  182    imshow(log(1+D),[]);
  183 
  184    // nearest 0-pixels to any pixel (label map)
  185    [D,L] = bwdist(A);
  186    // each 0-pixel's zone of influence has a different id: the col-major
  187    // index of the nearest 0-pixel.
  188    // 
  189    // Each Voronoi region is now mapped to a different color
  190    imshow(L+1, rand(max(L)+1, 3)); 
  191 
  192    // To obtain an external EDT, simply invert the shape:
  193    B = 1-A;
  194    D = bwdist(B,'maurer');
  195    imshow(log(1+D),[]);
  196    // To obtain an external+internal EDT, simply compute
  197    // the binary border of the shape and pass its negative
  198    // to bwdist:
  199    A = bwborder(A);
  200    A = 1-A;
  201    D = bwdist(A,'lotufo-zampirolli');
  202    imshow(log(1+D),[]);
  203    // computation only up to a given distance
  204    D = bwdist(A,'cuisenaire pmn', 12);
  205    // correct way to display a partial DT is to clamp high values to max_dist
  206    imshow(sqrt(D),[0 12]);
  207 
  208    // ---------------------------------
  209    //  Other forms to visualize the DT
  210    // ---------------------------------
  211    // Wrapping (note the wavefronts of iso-distance)
  212    imshow(modulo(sqrt(D),10),[])
  213    // Usual:
  214    D = bwdist(A);
  215    D = normal(sqrt(D),1000,1);
  216    imshow(D,hotcolormap(1000));
  217    // There is also of DT application in the example for the "watershed"
  218    // function.
  219    xset('auto clear', 'off');
  220 ]]></programlisting></refsection> 
  221 
  222     <para><emphasis role="bold">The original image, distance map and its closest feature label map:</emphasis></para>
  223     <para><imagedata fileref="../../images/escher.png" /> <imagedata fileref="../images/skeleton-escher-dt.png" /> <imagedata fileref="../images/escher-dt-label_interior.png" /></para>
  224 
  225     <para><emphasis role="bold">The distance map of the border (yielding
  226     non-zero distances inside and outside), the associated closest feature label map, and
  227     the propagating wavefronts:</emphasis></para>
  228     <para><imagedata fileref="../images/escher-dt-in_out.png" /> <imagedata fileref="../images/escher-dt-label-inout.png" /> <imagedata fileref="../images/escher-dt-modulo.png" /></para>
  229 
  230 
  231    <refsection><title>Bibliography</title>
  232       <variablelist>
  233          <varlistentry><term>Maurer</term><listitem>  
  234             <para>
  235    Maurer, C.R. and  R. Qi and  V. Raghavan,
  236    "A Linear Time Algorithm for Computing the Euclidean Distance Transform in Arbitrary Dimensions",
  237    IEEE Transactions on Pattern Analysis and Machine Intelligence,
  238    vol. 25, no. 2, pp. 265-270, february 2003.
  239    </para>
  240          </listitem></varlistentry>
  241          <varlistentry><term>Meijster</term><listitem>  
  242             <para>
  243    A. Meijster, J.B.T.M. Roerdink, and W.H. Hesselink "A General Algorithm
  244    for Computing Distance Transforms in Linear Time",
  245    proc. of 5th Int. Conf. Mathematical Morphology and its Applications to
  246    Image and Signal Processing, 2000
  247    </para>
  248          </listitem></varlistentry>
  249          <varlistentry><term>Cuisenaire</term><listitem>
  250             <para>
  251    Cuisenaire, O and  Macq, B,
  252    "Fast Euclidean Distance Transformation by Propagation Using
  253    Multiple Neighborhoods", Computer Vision and Image Understanding, no. 2,
  254    vol 76, 163--172, 76, 1999.
  255    </para>
  256             <para>
  257    Chapter 3 of "Distance transformations: fast algorithms and applications 
  258    to medical image processing", Olivier Cuisenaire's Ph.D. Thesis, October 
  259    1999, Université catholique de Louvain, Belgium.
  260    </para>
  261          </listitem></varlistentry>
  262          <varlistentry><term>IFT</term><listitem>  
  263             <para>
  264    "Multiscale Skeletons by Image Foresting Transform
  265    and its Application to Neuromorphometry", 
  266    A.X. Falcao, L. da F. Costa, B.S. da Cunha,
  267    Pattern Recognition, 2002. 
  268    </para>
  269          </listitem></varlistentry>
  270          <varlistentry><term>Lotufo-Zampirolli</term><listitem>
  271             <para>
  272    R. Lotufo and F. Zampirolli, Fastmultidimensional parallel
  273    euclidean distance
  274    transform based on mathematical morphology, in T. Wu and D. Borges, editors,
  275    Proccedings of SIBGRAPI 2001, XIV Brazilian Symposium on Computer Graphics 
  276    and Image Processing, pages 100-105. IEEE Computer Society, 2001.
  277    </para>
  278          </listitem></varlistentry>
  279          <varlistentry><term>Exact Dilations</term><listitem>
  280             <para>
  281    "Multiresolution shape representation without border shifting",
  282    L. da F. Costa, and L. F. Estrozi, Electronics Letters, no. 21, vol. 35, 
  283    pp. 1829-1830, 1999.
  284    </para>
  285             <para>
  286    "Shape Analysis and Classification", 
  287    L. da F. Costa and R.M. Cesar Jr., CRC Press. 
  288    </para>
  289          </listitem></varlistentry>
  290       </variablelist>
  291    </refsection>
  292    <refsection><title>Authors</title><simplelist type="vert">
  293       <member> Ricardo Fabbri &lt;ricardofabbri
  294    (AT) users DOT sf DOT net&gt; </member>
  295    </simplelist></refsection> 
  296    <refsection><title>Availability</title> The latest version
  297 of the Scilab Image Processing toolbox can be found at <para>
  298          http://siptoolbox.sourceforge.net
  299       </para>
  300    </refsection> 
  301    <refsection><title>See Also</title><simplelist type="inline">
  302       <member> 
  303          <link linkend="skel">skel</link> 
  304       </member>
  305       <member> 
  306          <link linkend="thin">thin</link> 
  307       </member>
  308       <member> 
  309          <link linkend="edilate">edilate</link> 
  310       </member>
  311       <member> 
  312          <link linkend="bwlabel">bwlabel</link> (connected component labeling)
  313       </member>
  314    </simplelist></refsection>
  315 </refentry>