<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE MAN SYSTEM "../../manrev.dtd">
<MAN>
  <LANGUAGE>eng</LANGUAGE>

  <TITLE>plot3d1</TITLE>

  <TYPE>Scilab Function</TYPE>

  <DATE>April 1993</DATE>

  <SHORT_DESCRIPTION name="plot3d1">3D gray or color level plot of a
  surface</SHORT_DESCRIPTION>

  <CALLING_SEQUENCE>
    <CALLING_SEQUENCE_ITEM>plot3d1(x,y,z,[theta,alpha,leg,flag,ebox])</CALLING_SEQUENCE_ITEM>

    <CALLING_SEQUENCE_ITEM>plot3d1(xf,yf,zf,[theta,alpha,leg,flag,ebox])</CALLING_SEQUENCE_ITEM>

    <CALLING_SEQUENCE_ITEM></CALLING_SEQUENCE_ITEM>

    <CALLING_SEQUENCE_ITEM>plot3d1(x,y,z,&lt;opts_args&gt;)</CALLING_SEQUENCE_ITEM>

    <CALLING_SEQUENCE_ITEM>plot3d1(xf,yf,zf,&lt;opts_args&gt;)</CALLING_SEQUENCE_ITEM>
  </CALLING_SEQUENCE>

  <PARAM>
    <PARAM_INDENT>
      <PARAM_ITEM>
        <PARAM_NAME>x,y</PARAM_NAME>

        <PARAM_DESCRIPTION>
          <SP>: row vectors of sizes n1 and n2 (x-axis and y-axis
          coordinates). These coordinates must be monotone.</SP>
        </PARAM_DESCRIPTION>
      </PARAM_ITEM>

      <PARAM_ITEM>
        <PARAM_NAME>z</PARAM_NAME>

        <PARAM_DESCRIPTION>
          <SP>: matrix of size (n1,n2). <VERB>z(i,j)</VERB> is the value of
          the surface at the point (x(i),y(j)).</SP>
        </PARAM_DESCRIPTION>
      </PARAM_ITEM>

      <PARAM_ITEM>
        <PARAM_NAME>xf,yf,zf</PARAM_NAME>

        <PARAM_DESCRIPTION>
          <SP>: matrices of size (nf,n). They define the facets used to draw
          the surface. There are <VERB>n</VERB> facets. Each facet
          <VERB>i</VERB> is defined by a polygon with <VERB>nf</VERB> points.
          The x-axis, y-axis and z-axis coordinates of the points of the ith
          facet are given respectively by <VERB>xf(:,i)</VERB>,
          <VERB>yf(:,i)</VERB> and <VERB>zf(:,i)</VERB>.</SP>
        </PARAM_DESCRIPTION>
      </PARAM_ITEM>

      <PARAM_ITEM>
        <PARAM_NAME>&lt;opt_args&gt;</PARAM_NAME>

        <PARAM_DESCRIPTION>
          <SP>: This represents a sequence of statements <VERB>key1=value1, key2=value2</VERB>,... where <VERB>key1</VERB>,
          <VERB>key2,...</VERB> can be one of the following: theta, alpha
          ,leg,flag,ebox (see definition below).</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 labels for each axis with @ as a field
          separator, for example "X@Y@Z".</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>: an integer (surface color).</SP>

                <PARAM_INDENT>
                  <PARAM_ITEM>
                    <PARAM_NAME>mode&gt;0</PARAM_NAME>

                    <PARAM_DESCRIPTION>
                      <SP>: the surface is painted with color
                      <VERB>"mode"</VERB> ; the boundary of the facet is drawn
                      with current line style and color.</SP>
                    </PARAM_DESCRIPTION>
                  </PARAM_ITEM>

                  <PARAM_ITEM>
                    <PARAM_NAME>mode=0:</PARAM_NAME>

                    <PARAM_DESCRIPTION>
                      <SP>a mesh of the surface is drawn.</SP>
                    </PARAM_DESCRIPTION>
                  </PARAM_ITEM>

                  <PARAM_ITEM>
                    <PARAM_NAME>mode&lt;0:</PARAM_NAME>

                    <PARAM_DESCRIPTION>
                      <SP>the surface is painted with color
                      <VERB>"-mode"</VERB> ; the boundary of the facet is not
                      drawn.</SP>

                      <P>Note that the surface color treatement can be done
                      using <VERB>color_mode</VERB> and
                      <VERB>color_flag</VERB> options through the surface
                      entity properties (see
                      <LINK>surface_properties</LINK>).</P>
                    </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>

                      <P>Note that axes boundaries can be customized through
                      the axes entity properties (see
                      <LINK>axes_properties</LINK>).</P>
                    </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>

                      <P>Note that axes aspect can also be customized through
                      the axes entity properties (see
                      <LINK>axes_properties</LINK>).</P>
                    </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>: It specifies the boundaries of the plot as the vector
          <VERB>[xmin,xmax,ymin,ymax,zmin,zmax]</VERB>. This argument is used
          together with <VERB>type</VERB> in <VERB>flag</VERB> : if it is set
          to <VERB>1</VERB>, <VERB>3</VERB> or <VERB>5</VERB> (see above to
          see the corresponding behaviour). If <VERB>flag</VERB> is missing,
          <VERB>ebox</VERB> is not taken into acoount.</SP>

          <P>Note that, when specified, the <VERB>ebox</VERB> argument acts on
          the <VERB>data_bounds</VERB> field that can also be reset through
          the axes entity properties (see <LINK>axes_properties</LINK>).</P>
        </PARAM_DESCRIPTION>
      </PARAM_ITEM>
    </PARAM_INDENT>
  </PARAM>

  <DESCRIPTION>
    <P><VERB>plot3d1</VERB> plots a surface with colors depending on the
    z-level of the surface. This special plot function can also be enabled
    setting <VERB>color_flag=1</VERB> after a <VERB>plot3d</VERB> (see
    <LINK>surface_properties</LINK>)</P>

    <P>Enter the command <VERB>plot3d1()</VERB> to see a demo.</P>
  </DESCRIPTION>

  <EXAMPLE><![CDATA[// simple plot using z=f(x,y) 
t=[0:0.3:2*%pi]'; z=sin(t)*cos(t'); 
plot3d1(t,t,z) 
// same plot using facets computed by genfac3d 
[xx,yy,zz]=genfac3d(t,t,z); 
clf(); 
plot3d1(xx,yy,zz) 
// multiple plots 
clf(); 
plot3d1([xx xx],[yy yy],[zz 4+zz]) 
// simple plot with viewpoint and captions 
clf() ;
plot3d1(1:10,1:20,10*rand(10,20),35,45,"X@Y@Z",[2,2,3]) 
// same plot without grid 
clf() 
plot3d1(1:10,1:20,10*rand(10,20),35,45,"X@Y@Z",[-2,2,3]) 
// plot of a sphere using facets computed by eval3dp 
deff("[x,y,z]=sph(alp,tet)",["x=r*cos(alp).*cos(tet)+orig(1)*ones(tet)";.. 
"y=r*cos(alp).*sin(tet)+orig(2)*ones(tet)";.. 
"z=r*sin(alp)+orig(3)*ones(tet)"]); 
r=1; orig=[0 0 0]; 
[xx,yy,zz]=eval3dp(sph,linspace(-%pi/2,%pi/2,40),linspace(0,%pi*2,20)); 
clf() 

plot3d(xx,yy,zz)
e=gce();
e.color_flag=1;
scf(2);
plot3d1(xx,yy,zz) // the 2 graphics are similar

]]></EXAMPLE>

  <SEE_ALSO>
    <SEE_ALSO_ITEM>
      <LINK>plot3d</LINK>
    </SEE_ALSO_ITEM>

    <SEE_ALSO_ITEM>
      <LINK>gca</LINK>
    </SEE_ALSO_ITEM>

    <SEE_ALSO_ITEM>
      <LINK>gce</LINK>
    </SEE_ALSO_ITEM>

    <SEE_ALSO_ITEM>
      <LINK>scf</LINK>
    </SEE_ALSO_ITEM>

    <SEE_ALSO_ITEM>
      <LINK>clf</LINK>
    </SEE_ALSO_ITEM>
  </SEE_ALSO>

  <AUTHOR>J.Ph.C.</AUTHOR>
</MAN>
