<?xml version="1.0" encoding="ISO-8859-1" standalone="no"?>
<!DOCTYPE MAN SYSTEM "../../manrev.dtd">
<MAN>
  <LANGUAGE>eng</LANGUAGE>
  <TITLE>contour</TITLE>
  <TYPE>Scilab Function</TYPE>
  <DATE>April 1993</DATE>
  <SHORT_DESCRIPTION name="contour"> level curves on a 3D surface</SHORT_DESCRIPTION>
  <CALLING_SEQUENCE>
    <CALLING_SEQUENCE_ITEM>contour(x,y,z,nz,[theta,alpha,leg,flag,ebox,zlev])</CALLING_SEQUENCE_ITEM>
    <CALLING_SEQUENCE_ITEM>contour(x,y,z,nz,&lt;opt_args&gt;)  </CALLING_SEQUENCE_ITEM>
  </CALLING_SEQUENCE>
  <PARAM>
    <PARAM_INDENT>
      <PARAM_ITEM>
        <PARAM_NAME>x,y</PARAM_NAME>
        <PARAM_DESCRIPTION>
          <SP>: two real row vectors of size n1 and n2.</SP>
        </PARAM_DESCRIPTION>
      </PARAM_ITEM>
      <PARAM_ITEM>
        <PARAM_NAME>z</PARAM_NAME>
        <PARAM_DESCRIPTION>
          <SP>: real matrix of size (n1,n2), the values of the function or  a
	    Scilab function which defines the surface  <VERB>z=f(x,y)</VERB>. </SP>
        </PARAM_DESCRIPTION>
      </PARAM_ITEM>
      <PARAM_ITEM>
        <PARAM_NAME>nz</PARAM_NAME>
        <PARAM_DESCRIPTION>
          <SP>: the level values or the number of levels.</SP>
          <PARAM_INDENT>
            <PARAM_ITEM>
              <PARAM_NAME>-  </PARAM_NAME>
              <PARAM_DESCRIPTION>
                <SP>If <VERB>nz</VERB> is an integer, its value gives the number of
  level curves  equally spaced from zmin to zmax as follows:</SP>
                <VERBATIM>
<![CDATA[
 z= zmin + (1:nz)*(zmax-zmin)/(nz+1)
   ]]>
                </VERBATIM>
                <SP> Note that the <VERB>zmin</VERB> and
                <VERB>zmax</VERB> levels are not drawn  (generically
                they are reduced to points) but they can be added
                with</SP>
                <VERBATIM>
<![CDATA[
 [im,jm] = find(z == zmin);     // or zmax 
 plot2d(x(im)',y(jm)',-9,"000")
   ]]>
                </VERBATIM>
              </PARAM_DESCRIPTION>
            </PARAM_ITEM>
            <PARAM_ITEM>
              <PARAM_NAME>-  </PARAM_NAME>
              <PARAM_DESCRIPTION>
                <SP>If <VERB>nz</VERB> is a vector,
              <VERB>nz(i)</VERB> gives the value of the ith level
              curve. Note that it can be useful in order to see
              <VERB>zmin</VERB> and   <VERB>zmax</VERB> level curves
              to add an epsilon tolerance: <VERB>nz=[zmin+%eps,..,zmax-%eps]</VERB>.</SP>
              </PARAM_DESCRIPTION>
            </PARAM_ITEM>
          </PARAM_INDENT>
        </PARAM_DESCRIPTION>
      </PARAM_ITEM>
      <PARAM_ITEM>
        <PARAM_NAME>&lt;opt_args&gt;  </PARAM_NAME>
        <PARAM_DESCRIPTION>
          <SP>: a sequence of statements <VERB>key1=value1, key2=value2</VERB>,
  ... where keys may be
  <VERB>theta</VERB>,<VERB>alpha</VERB>,<VERB>leg</VERB>,<VERB>flag</VERB>, <VERB>ebox</VERB>,<VERB>zlev</VERB> (see below). In
  this case, the order has no special meaning.</SP>
        </PARAM_DESCRIPTION>
      </PARAM_ITEM>
      <PARAM_ITEM>
        <PARAM_NAME>theta, alpha</PARAM_NAME>
        <PARAM_DESCRIPTION>
          <SP>: real values giving in degree the spherical coordinates of  the observation point.</SP>
        </PARAM_DESCRIPTION>
      </PARAM_ITEM>
      <PARAM_ITEM>
        <PARAM_NAME>leg</PARAM_NAME>
        <PARAM_DESCRIPTION>
          <SP>: string defining the captions for each axis with @ as a field separator, for example &quot;X@Y@Z&quot;.</SP>
        </PARAM_DESCRIPTION>
      </PARAM_ITEM>
      <PARAM_ITEM>
        <PARAM_NAME>flag</PARAM_NAME>
        <PARAM_DESCRIPTION>
          <SP>: a real vector of size three <VERB>flag=[mode,type,box]</VERB>.</SP>
          <PARAM_INDENT>
            <PARAM_ITEM>
              <PARAM_NAME>mode</PARAM_NAME>
              <PARAM_DESCRIPTION>
                <SP>: string representation mode.</SP>
		<PARAM_INDENT>
                  <PARAM_ITEM>
                    <PARAM_NAME>mode=0: </PARAM_NAME>
		    <PARAM_DESCRIPTION>
		    <SP>the level curves are drawn on the surface defined by
			(x,y,z).</SP>
		    </PARAM_DESCRIPTION>
                  </PARAM_ITEM>
                  <PARAM_ITEM>
                    <PARAM_NAME>mode=1: </PARAM_NAME>
		    <PARAM_DESCRIPTION>
		      <SP>the level curves are drawn on a 3D plot and
			on the plan defined by  the equation z=zlev.</SP>
		    </PARAM_DESCRIPTION>
                  </PARAM_ITEM>
                  <PARAM_ITEM>
                    <PARAM_NAME>mode=2:</PARAM_NAME> 
		    <PARAM_DESCRIPTION>
		      <SP>the level curves are drawn on a 2D plot.</SP>
		    </PARAM_DESCRIPTION>
                  </PARAM_ITEM>
		</PARAM_INDENT>
	      </PARAM_DESCRIPTION>

	    </PARAM_ITEM>

            <PARAM_ITEM>
              <PARAM_NAME>type</PARAM_NAME>
              <PARAM_DESCRIPTION>
                <SP>: an integer (scaling).</SP>
                <PARAM_INDENT>
                  <PARAM_ITEM>
                    <PARAM_NAME>type=0</PARAM_NAME>
                    <PARAM_DESCRIPTION>
                      <SP>the plot is made using the current 3D scaling (set by
			a previous call to <VERB>param3d</VERB>,
			<VERB>plot3d</VERB>, <VERB>contour</VERB> or
			<VERB>plot3d1</VERB>).</SP> 
                    </PARAM_DESCRIPTION>
                  </PARAM_ITEM>
                  <PARAM_ITEM>
                    <PARAM_NAME>type=1</PARAM_NAME>
                    <PARAM_DESCRIPTION>
                      <SP>rescales automatically 3d boxes with extreme aspect
			ratios, the boundaries are specified by the value of
			the optional argument <VERB>ebox</VERB>.</SP> 
                    </PARAM_DESCRIPTION>
                  </PARAM_ITEM>
                  <PARAM_ITEM>
                    <PARAM_NAME>type=2</PARAM_NAME>
                    <PARAM_DESCRIPTION>
                      <SP>rescales automatically 3d boxes with extreme aspect
			ratios, the boundaries are computed using the given
			data.</SP> 
                    </PARAM_DESCRIPTION>
                  </PARAM_ITEM>
                  <PARAM_ITEM>
                    <PARAM_NAME>type=3</PARAM_NAME>
                    <PARAM_DESCRIPTION>
                      <SP>3d isometric with box bounds given by optional
			<VERB>ebox</VERB>, similarily to
			<VERB>type=1</VERB></SP> 
                    </PARAM_DESCRIPTION>
                  </PARAM_ITEM>
                  <PARAM_ITEM>
                    <PARAM_NAME>type=4</PARAM_NAME>
                    <PARAM_DESCRIPTION>
                      <SP>3d isometric bounds  derived from the data, to
			similarily<VERB>type=2</VERB></SP> 
                    </PARAM_DESCRIPTION>
                  </PARAM_ITEM>
                  <PARAM_ITEM>
                    <PARAM_NAME>type=5</PARAM_NAME>
                    <PARAM_DESCRIPTION>
                      <SP>3d expanded isometric bounds  with box bounds given
			by optional <VERB>ebox</VERB>, similarily to
			<VERB>type=1</VERB></SP> 
                    </PARAM_DESCRIPTION>
                  </PARAM_ITEM>
                  <PARAM_ITEM>
                    <PARAM_NAME>type=6</PARAM_NAME>
                    <PARAM_DESCRIPTION>
                      <SP>3d expanded isometric bounds  derived from the data,
			similarily to <VERB>type=2</VERB></SP> 
                    </PARAM_DESCRIPTION>
                  </PARAM_ITEM>
                </PARAM_INDENT>
              </PARAM_DESCRIPTION>
            </PARAM_ITEM>
            <PARAM_ITEM>
              <PARAM_NAME>box</PARAM_NAME>
              <PARAM_DESCRIPTION>
                <SP>: an integer (frame around the plot).</SP>
                <PARAM_INDENT>
                  <PARAM_ITEM>
                    <PARAM_NAME>box=0</PARAM_NAME>
                    <PARAM_DESCRIPTION>
                      <SP>nothing is drawn around the plot.</SP>
                    </PARAM_DESCRIPTION>
                  </PARAM_ITEM>
                  <PARAM_ITEM>
                    <PARAM_NAME>box=1</PARAM_NAME>
                    <PARAM_DESCRIPTION>
                      <SP>unimplemented (like box=0).</SP>
                    </PARAM_DESCRIPTION>
                  </PARAM_ITEM>
                  <PARAM_ITEM>
                    <PARAM_NAME>box=2</PARAM_NAME>
                    <PARAM_DESCRIPTION>
                      <SP>only the axes behind the surface are drawn.</SP>
                    </PARAM_DESCRIPTION>
                  </PARAM_ITEM>
                  <PARAM_ITEM>
                    <PARAM_NAME>box=3</PARAM_NAME>
                    <PARAM_DESCRIPTION>
                      <SP>a box surrounding the surface is drawn and captions are added.</SP>
                    </PARAM_DESCRIPTION>
                  </PARAM_ITEM>
                  <PARAM_ITEM>
                    <PARAM_NAME>box=4</PARAM_NAME>
                    <PARAM_DESCRIPTION>
                      <SP>a box surrounding the surface is drawn, captions and axes are added.</SP>
                    </PARAM_DESCRIPTION>
                  </PARAM_ITEM>
                </PARAM_INDENT>
              </PARAM_DESCRIPTION>
            </PARAM_ITEM>
          </PARAM_INDENT>
        </PARAM_DESCRIPTION>
      </PARAM_ITEM>
      <PARAM_ITEM>
        <PARAM_NAME>ebox</PARAM_NAME>
        <PARAM_DESCRIPTION>
          <SP>: used when <VERB>type</VERB> in <VERB>flag</VERB> is 1. It
	    specifies the boundaries of the plot as the vector
	    <VERB>[xmin,xmax,ymin,ymax,zmin,zmax]</VERB>.</SP> 
        </PARAM_DESCRIPTION>
      </PARAM_ITEM>
      <PARAM_ITEM>
        <PARAM_NAME>zlev</PARAM_NAME>
        <PARAM_DESCRIPTION>
          <SP>: real number.</SP>
        </PARAM_DESCRIPTION>
      </PARAM_ITEM>
    </PARAM_INDENT>
  </PARAM>
  <DESCRIPTION>
    <P><VERB>contour</VERB> draws level curves of a surface z=f(x,y). The level curves are
    drawn on a 3D surface. The optional arguments are the same as for the function 
    <VERB>plot3d</VERB> (except <VERB>zlev</VERB>) and their meanings are the same. 
    They control the drawing of level curves on a 3D plot.
    Only <VERB>flag(1)=mode</VERB> has a special meaning.
  </P>
    <DESCRIPTION_INDENT>
      <DESCRIPTION_ITEM label="mode=0">
        <SP>: the level curves are drawn on the surface defined by (x,y,z).</SP>
      </DESCRIPTION_ITEM>
      <DESCRIPTION_ITEM label="mode=1">
        <SP>: the level curves are drawn on a 3D plot and on the plan defined
	  by  the equation z=zlev.</SP> 
      </DESCRIPTION_ITEM>
      <DESCRIPTION_ITEM label="mode=2">
        <SP>: the level curves are drawn on a 2D plot.</SP>
      </DESCRIPTION_ITEM>
    </DESCRIPTION_INDENT>
    <P>
    You can change the format of the floating point number printed on the levels
    by using <VERB>xset(&quot;fpf&quot;,string)</VERB> where <VERB>string</VERB> gives the 
    format in C format syntax (for example <VERB>string=&quot;%.3f&quot;</VERB>). Use 
    <VERB>string=&quot;&quot;</VERB> to switch back to default format and Use 
    <VERB>string=&quot; &quot;</VERB> to suppress printing.</P>
    <P>
    Usually we use <VERB>contour2d</VERB> to draw levels curves on a 2D plot.</P>
    <P>
    Enter the command <VERB>contour()</VERB> to see a demo.</P>
  </DESCRIPTION>
  <EXAMPLE>
<![CDATA[
t=linspace(-%pi,%pi,30);
function z=my_surface(x,y),z=x*sin(x)^2*cos(y),endfunction

contour(t,t,my_surface,10)
// changing the format of the printing of the levels
xset("fpf","%.1f")
xbasc()
contour(t,t,my_surface,10)
// 3D
xbasc()
z=feval(t,t,my_surface);
plot3d(t,t,z);contour(t,t,z+0.2*abs(z),20,flag=[0 2 4]);
//

 ]]>
  </EXAMPLE>
  <SEE_ALSO>
    <SEE_ALSO_ITEM>
      <LINK>contour2d</LINK>
    </SEE_ALSO_ITEM>
    <SEE_ALSO_ITEM>
      <LINK>plot3d</LINK>
    </SEE_ALSO_ITEM>
  </SEE_ALSO>
  <AUTHOR>J.Ph.C.  </AUTHOR>
</MAN>
