<?xml version="1.0" encoding="UTF-8"?>
<!--
 * Scilab ( http://www.scilab.org/ ) - This file is part of Scilab
 * Copyright (C) ENPC - Jean-Philippe Chancelier
 *
 * Copyright (C) 2012 - 2016 - Scilab Enterprises
 *
 * This file is hereby licensed under the terms of the GNU GPL v2.0,
 * pursuant to article 5.3.4 of the CeCILL v.2.1.
 * This file was originally licensed under the terms of the CeCILL v2.1,
 * and continues to be available under such terms.
 * For more information, see the COPYING file which you should have received
 * along with this program.
 *
 -->
<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" xmlns:scilab="http://www.scilab.org"  xml:lang="en" xml:id="plot3d1">
    <refnamediv>
        <refname>plot3d1</refname>
        <refpurpose>3D gray or color level plot of a
            surface
        </refpurpose>
    </refnamediv>
    <refsynopsisdiv>
        <title>Syntax</title>
        <synopsis>plot3d1(x,y,z,[theta,alpha,leg,flag,ebox])
            plot3d1(xf,yf,zf,[theta,alpha,leg,flag,ebox])
            plot3d1(x,y,z,&lt;opts_args&gt;)
            plot3d1(xf,yf,zf,&lt;opts_args&gt;)
        </synopsis>
    </refsynopsisdiv>
    <refsection>
        <title>Arguments</title>
        <variablelist>
            <varlistentry>
                <term>x,y</term>
                <listitem>
                    <para>row vectors of sizes n1 and n2 (x-axis and y-axis
                        coordinates). These coordinates must be monotone.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>z</term>
                <listitem>
                    <para>
                        matrix of size (n1,n2). <literal>z(i,j)</literal> is the value of
                        the surface at the point (x(i),y(j)).
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>xf,yf,zf</term>
                <listitem>
                    <para>matrices of size (nf,n). They define the facets used to draw
                        the surface. There are <literal>n</literal> facets. Each facet
                        <literal>i</literal> is defined by a polygon with <literal>nf</literal> points.
                        The x-axis, y-axis and z-axis coordinates of the points of the ith
                        facet are given respectively by <literal>xf(:,i)</literal>,
                        <literal>yf(:,i)</literal> and <literal>zf(:,i)</literal>.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>&lt;opt_args&gt;</term>
                <listitem>
                    <para>
                        This represents a sequence of statements <literal>key1=value1, key2=value2</literal>,... where <literal>key1</literal>,
                        <literal>key2,...</literal> can be one of the following: theta, alpha
                        ,leg,flag,ebox (see definition below).
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>theta, alpha</term>
                <listitem>
                    <para>real values giving in degree the spherical coordinates of the
                        observation point.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>leg</term>
                <listitem>
                    <para>string defining the labels for each axis with @ as a field
                        separator, for example "X@Y@Z".
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>flag</term>
                <listitem>
                    <para>a real vector of size three.
                        <literal>flag=[mode,type,box]</literal>.
                    </para>
                    <variablelist>
                        <varlistentry>
                            <term>mode</term>
                            <listitem>
                                <para>an integer (surface color).</para>
                                <variablelist>
                                    <varlistentry>
                                        <term>mode&gt;0</term>
                                        <listitem>
                                            <para>the surface is painted with color
                                                <literal>"mode"</literal> ; the boundary of the facet is drawn
                                                with current line style and color.
                                            </para>
                                        </listitem>
                                    </varlistentry>
                                    <varlistentry>
                                        <term>mode=0:</term>
                                        <listitem>
                                            <para>a mesh of the surface is drawn.</para>
                                        </listitem>
                                    </varlistentry>
                                    <varlistentry>
                                        <term>mode&lt;0:</term>
                                        <listitem>
                                            <para>the surface is painted with color
                                                <literal>"-mode"</literal> ; the boundary of the facet is not
                                                drawn.
                                            </para>
                                            <para>Note that the surface color treatment can be done
                                                using <literal>color_mode</literal> and
                                                <literal>color_flag</literal> options through the surface
                                                entity properties (see
                                                <link linkend="surface_properties">surface_properties</link>).
                                            </para>
                                        </listitem>
                                    </varlistentry>
                                </variablelist>
                            </listitem>
                        </varlistentry>
                        <varlistentry>
                            <term>type</term>
                            <listitem>
                                <para>an integer (scaling).</para>
                                <variablelist>
                                    <varlistentry>
                                        <term>type=0:</term>
                                        <listitem>
                                            <para>the plot is made using the current 3D scaling (set
                                                by a previous call to <literal>param3d</literal>,
                                                <literal>plot3d</literal>, <literal>contour</literal> or
                                                <literal>plot3d1</literal>).
                                            </para>
                                        </listitem>
                                    </varlistentry>
                                    <varlistentry>
                                        <term>type=1:</term>
                                        <listitem>
                                            <para>rescales automatically 3d boxes with extreme aspect
                                                ratios, the boundaries are specified by the value of the
                                                optional argument <literal>ebox</literal>.
                                            </para>
                                        </listitem>
                                    </varlistentry>
                                    <varlistentry>
                                        <term>type=2:</term>
                                        <listitem>
                                            <para>rescales automatically 3d boxes with extreme aspect
                                                ratios, the boundaries are computed using the given
                                                data.
                                            </para>
                                        </listitem>
                                    </varlistentry>
                                    <varlistentry>
                                        <term>type=3:</term>
                                        <listitem>
                                            <para>3d isometric with box bounds given by optional
                                                <literal>ebox</literal>, similarly to
                                                <literal>type=1</literal>.
                                            </para>
                                        </listitem>
                                    </varlistentry>
                                    <varlistentry>
                                        <term>type=4:</term>
                                        <listitem>
                                            <para>3d isometric bounds derived from the data, similarly to
                                                <literal>type=2</literal>.
                                            </para>
                                        </listitem>
                                    </varlistentry>
                                    <varlistentry>
                                        <term>type=5:</term>
                                        <listitem>
                                            <para>3d expanded isometric bounds with box bounds given
                                                by optional <literal>ebox</literal>, similarly to
                                                <literal>type=1</literal>.
                                            </para>
                                        </listitem>
                                    </varlistentry>
                                    <varlistentry>
                                        <term>type=6:</term>
                                        <listitem>
                                            <para>3d expanded isometric bounds derived from the data,
                                                similarly to <literal>type=2</literal>.
                                            </para>
                                            <para>Note that axes boundaries can be customized through
                                                the axes entity properties (see
                                                <link linkend="axes_properties">axes_properties</link>).
                                            </para>
                                        </listitem>
                                    </varlistentry>
                                </variablelist>
                            </listitem>
                        </varlistentry>
                        <varlistentry>
                            <term>box</term>
                            <listitem>
                                <para>an integer (frame around the plot).</para>
                                <variablelist>
                                    <varlistentry>
                                        <term>box=0:</term>
                                        <listitem>
                                            <para>nothing is drawn around the plot.</para>
                                        </listitem>
                                    </varlistentry>
                                    <varlistentry>
                                        <term>box=1:</term>
                                        <listitem>
                                            <para>unimplemented (like box=0).</para>
                                        </listitem>
                                    </varlistentry>
                                    <varlistentry>
                                        <term>box=2:</term>
                                        <listitem>
                                            <para>only the axes behind the surface are drawn.</para>
                                        </listitem>
                                    </varlistentry>
                                    <varlistentry>
                                        <term>box=3:</term>
                                        <listitem>
                                            <para>a box surrounding the surface is drawn and captions
                                                are added.
                                            </para>
                                        </listitem>
                                    </varlistentry>
                                    <varlistentry>
                                        <term>box=4:</term>
                                        <listitem>
                                            <para>a box surrounding the surface is drawn, captions and
                                                axes are added.
                                            </para>
                                            <para>Note that axes aspect can also be customized through
                                                the axes entity properties (see
                                                <link linkend="axes_properties">axes_properties</link>).
                                            </para>
                                        </listitem>
                                    </varlistentry>
                                </variablelist>
                            </listitem>
                        </varlistentry>
                    </variablelist>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>ebox</term>
                <listitem>
                    <para>It specifies the boundaries of the plot as the vector
                        <literal>[xmin,xmax,ymin,ymax,zmin,zmax]</literal>. This argument is used
                        together with <literal>type</literal> in <literal>flag</literal> : if it is set
                        to <literal>1</literal>, <literal>3</literal> or <literal>5</literal> (see above to
                        see the corresponding behaviour). If <literal>flag</literal> is missing,
                        <literal>ebox</literal> is not taken into account.
                    </para>
                    <para>
                        Note that, when specified, the <literal>ebox</literal> argument acts on
                        the <literal>data_bounds</literal> field that can also be reset through
                        the axes entity properties (see <link linkend="axes_properties">axes_properties</link>).
                    </para>
                </listitem>
            </varlistentry>
        </variablelist>
    </refsection>
    <refsection>
        <title>Description</title>
        <para>
            <literal>plot3d1</literal> plots a surface with colors depending on the
            z-level of the surface. This special plot function can also be enabled
            setting <literal>color_flag=1</literal> after a <literal>plot3d</literal> (see
            <link linkend="surface_properties">surface_properties</link>)
        </para>
        <para>
            Enter the command <literal>plot3d1()</literal> to see a demo.
        </para>
    </refsection>
    <refsection>
        <title>Examples</title>
        <programlisting role="example"><![CDATA[
// simple plot using z=f(x,y)
t=[0:0.3:2*%pi]';
z=sin(t)*cos(t');
plot3d1(t,t,z)
 ]]></programlisting>
        <scilab:image>
            t=[0:0.3:2*%pi]';
            z=sin(t)*cos(t');
            plot3d1(t,t,z)
        </scilab:image>
        <programlisting role="example"><![CDATA[
// same plot using facets computed by genfac3d
t=[0:0.3:2*%pi]';
z=sin(t)*cos(t');
[xx,yy,zz]=genfac3d(t,t,z);
plot3d1(xx,yy,zz)
 ]]></programlisting>
        <scilab:image>
            t=[0:0.3:2*%pi]';
            z=sin(t)*cos(t');
            [xx,yy,zz]=genfac3d(t,t,z);
            plot3d1(xx,yy,zz)
        </scilab:image>
        <programlisting role="example"><![CDATA[
// multiple plots
t=[0:0.3:2*%pi]';
z=sin(t)*cos(t');
[xx,yy,zz]=genfac3d(t,t,z);
plot3d1([xx xx],[yy yy],[zz 4+zz])
 ]]></programlisting>
        <scilab:image>
            t=[0:0.3:2*%pi]';
            z=sin(t)*cos(t');
            [xx,yy,zz]=genfac3d(t,t,z);
            plot3d1([xx xx],[yy yy],[zz 4+zz])
        </scilab:image>
        <programlisting role="example"><![CDATA[
// simple plot with viewpoint and captions
plot3d1(1:10,1:20,10*rand(10,20),35,45,"X@Y@Z",[2,2,3])
 ]]></programlisting>
        <scilab:image>
            plot3d1(1:10,1:20,10*rand(10,20),35,45,"X@Y@Z",[2,2,3])
        </scilab:image>

        <programlisting role="example"><![CDATA[
// same plot without grid
plot3d1(1:10,1:20,10*rand(10,20),35,45,"X@Y@Z",[-2,2,3])
 ]]></programlisting>
        <scilab:image>
            plot3d1(1:10,1:20,10*rand(10,20),35,45,"X@Y@Z",[-2,2,3])
        </scilab:image>
        <programlisting role="example"><![CDATA[
// 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));
plot3d(xx,yy,zz)
e=gce();
e.color_flag=1;
scf(2);
plot3d1(xx,yy,zz) // the 2 graphics are similar
 ]]></programlisting>
        <scilab:image>
            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));
            plot3d(xx,yy,zz)
        </scilab:image>
    </refsection>
    <refsection role="see also">
        <title>See also</title>
        <simplelist type="inline">
            <member>
                <link linkend="plot3d">plot3d</link>
            </member>
            <member>
                <link linkend="gca">gca</link>
            </member>
            <member>
                <link linkend="gce">gce</link>
            </member>
            <member>
                <link linkend="scf">scf</link>
            </member>
            <member>
                <link linkend="clf">clf</link>
            </member>
        </simplelist>
    </refsection>
</refentry>
