<?xml version="1.0" encoding="UTF-8"?>
<!--
This file is part of the Scilab time frequency toolbox.
This file must be used under the terms of the  terms of the GNU General Public License 
as published by the Free Software Foundation; either version 2 of the License, or
(at your option) any later version.

Copyright (c) 1996 by CNRS (France).
-->


<refentry xml:id="htl" xml:lang="en"
          xmlns="http://docbook.org/ns/docbook"
          xmlns:xlink="http://www.w3.org/1999/xlink"
          xmlns:svg="http://www.w3.org/2000/svg"
          xmlns:scilab="http://www.scilab.org"
          xmlns:ns3="http://www.w3.org/1999/xhtml"
          xmlns:mml="http://www.w3.org/1998/Math/MathML"
          xmlns:db="http://docbook.org/ns/docbook">

  <refnamediv>
    <refname>htl</refname><refpurpose>Hough transform for detection of lines in images.</refpurpose>
  </refnamediv>



  <refsynopsisdiv>
    <title>Calling Sequence</title>
    <synopsis>
      [HT,RHO,THETA]=htl(IM)
      [HT,RHO,THETA]=htl(IM,M,)
      [HT,RHO,THETA]=htl(IM,M,N)
      [HT,RHO,THETA]=htl(IM,M,N,TRACE)
      [HT,RHO,THETA]=htl(...,'plot')
    </synopsis>
  </refsynopsisdiv>

  <refsection>
    <title>Parameters</title>
    <variablelist>
      <varlistentry>
        <term>	IM    :</term>
        <listitem>
          <para>A real Xmax by  Ymax matrix: the image to be analyzed.</para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>	M     :</term>
        <listitem>
          <para>A positive integer value: the desired number of samples along the radial axis
          (default : Xmax).</para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>	N     :</term>
        <listitem>
          <para>A positive integer value: the  desired number of samples along the azimutal (angle)
          axis (default : Ymax).</para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term> TRACE :</term> 
        <listitem>
          <para>A boolean (or a real scalar) if true (or nonzero),the
          progression of the algorithm is shown (default : %f).</para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>	HT    :</term>
        <listitem>
          <para>A real M by N matrix:  the Hough transform result.</para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>'plot':</term>
        <listitem>
          <para>when called with the additional string 'plot', htl
          displays HT using mesh.</para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>	RHO   :</term>
        <listitem>
          <para>A real row vector of size M: the radial coordinates.</para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>	THETA :</term>
        <listitem>
          <para>A real row vector of size N: the  azimutal angles (in radians).</para>
        </listitem>
      </varlistentry>
    </variablelist>
  </refsection>

  <refsection>
    <title>Description</title>
    <para>
      From an image IM, computes the integration of the values
      of the image over all the lines. The lines are parametrized
      using polar coordinates.</para> 
      <para>The origin of the coordinates is fixed at the center of
      the image (in pixel coordinates), THETA is the azimutal angle
      and RHO is the distance to the origin of the
      coordinates. </para>
      <para> Only the values of IM exceeding 5% of the maximum
      are taken into account (to speed up the algorithm).
    </para>
  </refsection>

  <refsection>
    <title>Examples</title>
    <programlisting role="example"><![CDATA[
    N=128; t=(1:N); y=fmlin(N,0.15,0.45);
    [IM,T,F]=tfrwv(y,t,N);
    //Draw the image
    clf;gcf().color_map= jetcolormap(128);
    //Draw the image
    subplot(211);grayplot(1:N,1:N,IM'),ax=gca();
    xlabel(_("Time (pixels)"));ylabel(_("Frequency (pixels)"))

    //Draw the Hough transform result
    [HT,RHO,THETA]=htl(IM,64);
    subplot(212);grayplot(RHO,THETA,HT),
    xlabel(_("Radial coordinate"));ylabel(_("Polar angle"))
    xtitle(_("Hough transform"))

    //Locate the Highest HT value
    [m,ind]=max(HT);
    theta=THETA(ind(2));rho=RHO(ind(1));
    xpoly(rho,theta,"marks");
   
    // Draw the line
    set(gce(),"mark_style",2,"mark_size",2,"mark_foreground",color("red"));
    //Take care rho and theta correspond to an image coordinates in pixels
    xl=N/2-rho*sin(theta)+60*cos(theta)*[-1 1];
    yl=N/2+rho*cos(theta)+60*sin(theta)*[-1 1];
    sca(ax);xpoly(xl,yl);
    set(gce(),"foreground",color("red"),"thickness",3);
    legend("Detected line");
  
    ]]></programlisting>
    <scilab:image><![CDATA[
    N=128; t=(1:N); y=fmlin(N,0.15,0.45);
    [IM,T,F]=tfrwv(y,t,N);
    //Draw the image
    clf;gcf().color_map= jetcolormap(128);
    //Draw the image
    subplot(211);grayplot(1:N,1:N,IM'),ax=gca();
    xlabel(_("Time (pixels)"));ylabel(_("Frequency (pixels)"))

    //Draw the Hough transform result
    [HT,RHO,THETA]=htl(IM,64);
    subplot(212);grayplot(RHO,THETA,HT),
    xlabel(_("Radial coordinate"));ylabel(_("Polar angle"))
    xtitle(_("Hough transform"))

    //Locate the Highest HT value
    [m,ind]=max(HT);
    theta=THETA(ind(2));rho=RHO(ind(1));
    xpoly(rho,theta,"marks");
   
    // Draw the line
    set(gce(),"mark_style",2,"mark_size",2,"mark_foreground",color("red"));
    //Take care rho and theta correspond to an image coordinates in pixels
    xl=N/2-rho*sin(theta)+60*cos(theta)*[-1 1];
    yl=N/2+rho*cos(theta)+60*sin(theta)*[-1 1];
    sca(ax);xpoly(xl,yl);
    set(gce(),"foreground",color("red"),"thickness",3);
    legend("Detected line");
    ]]></scilab:image>
  </refsection>
  <refsection>
    <title>See Also</title>
    <link linkend="Chtl">Chtl</link> <para> An equivalent function written in C an much more efficient.</para>
  </refsection>
  <refsection>
    <title>Authors</title>
    <simplelist type="vert">
      <member>H. Nahrstaedt - Aug 2010</member>
      <member>	O. Lemoine - June 1995.</member>
    </simplelist>
  </refsection>
</refentry>
