<?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:ns4="http://www.w3.org/1999/xhtml" xmlns:mml="http://www.w3.org/1998/Math/MathML" xmlns:db="http://docbook.org/ns/docbook" xmlns:scilab="http://www.scilab.org"  xml:id="plot3d" xml:lang="en">
    <refnamediv>
        <refname>plot3d</refname>
        <refpurpose>3D plot of a surface</refpurpose>
    </refnamediv>
    <refsynopsisdiv>
        <title>Syntax</title>
        <synopsis>plot3d(x,y,z,[theta,alpha,leg,flag,ebox])
            plot3d(x,y,z,&lt;opt_args&gt;)

            plot3d(xf,yf,zf,[theta,alpha,leg,flag,ebox])
            plot3d(xf,yf,zf,&lt;opt_args&gt;)

            plot3d(xf,yf,list(zf,colors),[theta,alpha,leg,flag,ebox])
            plot3d(xf,yf,list(zf,colors),&lt;opt_args&gt;)

            plot3d(z)
        </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>colors</term>
                <listitem>
                    <para>a vector of size n giving the color of each facets or a matrix
                        of size (nf,n) giving color near each facet boundary (facet color is
                        interpolated ).
                    </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 (by default, <varname>alpha</varname>=35° and <varname>theta</varname>=45°).
                    </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" (by default, axis have no label).
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>flag</term>
                <listitem>
                    <para>a real vector of size three.
                        <literal>flag=[mode,type,box]</literal>(by default <varname>flag</varname>=[2,8,4]).
                    </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 (by default <varname>ebox</varname> is missing).
                    </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>plot3d(z)</literal> draws the parametric surface <literal>z=f(x,y)</literal> where
            <literal>x=1:m</literal>, <literal>y=1:n</literal> and <literal>[m,n]=size(z)</literal> where <literal>m</literal> and <literal>n</literal> must be greater than 1.
        </para>
        <para>
            <literal>plot3d(x,y,z,[theta,alpha,leg,flag,ebox])</literal> draws
            the parametric surface <literal>z=f(x,y)</literal>.
        </para>
        <para>
            <literal>plot3d(xf,yf,zf,[theta,alpha,leg ,flag,ebox])</literal>
            draws a surface defined by a set of facets. You can draw multiple plots by
            replacing <literal>xf</literal>, <literal>yf</literal> and
            <literal>zf</literal> by multiple matrices assembled by rows as
            <literal>[xf1 xf2 ...]</literal>, <literal>[yf1 yf2 ...]</literal> and
            <literal>[zf1 zf2 ...]</literal>. Note that data can also be set or get
            through the surface entity properties (see <link linkend="surface_properties">surface_properties</link>).
        </para>
        <para/>
        <para>You can give a specific color for each facet by using
            <literal>list(zf,colors)</literal> instead of <literal>zf</literal>, where
            <literal>colors</literal> is a vector of size <literal>n</literal>. If
            <literal>colors(i)</literal> is positive it gives the color of facet
            <literal>i</literal> and the boundary of the facet is drawn with current
            line style and color. If <literal>colors(i)</literal> is negative, color
            id <literal>-colors(i)</literal> is used and the boundary of the facet is
            not drawn.
        </para>
        <para/>
        <para>It is also possible to get interpolated color for facets. For that
            the color argument must be a matrix of size nfxn giving the color near
            each boundary of each facets. In this case positive values for colors mean
            that the boundary are not drawn. Note that colors can also be set through
            the surface entity properties (via <literal>tlist</literal> affectations)
            and edited using <literal>color_flag</literal> option (see <link linkend="surface_properties">surface_properties</link>).
        </para>
        <para/>
        <para>
            The optional arguments <literal>theta, alpha, leg ,flag,
                ebox
            </literal>
            ,can be passed by a sequence of statements
            <literal>key1=value1, key2=value2</literal>, ... In this case, the order
            has no special meaning. Note that all these optional arguments except
            <literal>flag</literal> can be customized through the axes entity
            properties (see <link linkend="axes_properties">axes_properties</link>).
            As described before, the <literal>flag</literal> option deals with surface
            entity properties for <literal>mode</literal> (see <link linkend="surface_properties">surface_properties</link>) and axes
            properties for <literal>type</literal> and <literal>box</literal> (see
            <link linkend="axes_properties">axes_properties</link>).
        </para>
        <para/>
        <para>
            You can use the function <literal>genfac3d</literal> to compute four
            sided facets from the surface <literal>z=f(x,y)</literal>.
            <literal>eval3dp</literal> can also be used.
        </para>
        <para/>
        <para>
            Enter the command <literal>plot3d()</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');
plot3d(t,t,z)
 ]]></programlisting>

        <scilab:image>
            t=[0:0.3:2*%pi]';
            z=sin(t)*cos(t');
            plot3d(t,t,z)
        </scilab:image>

        <programlisting role="example"><![CDATA[
t=[0:0.3:2*%pi]';
z=sin(t)*cos(t');
// same plot using facets computed by genfac3d
[xx,yy,zz]=genfac3d(t,t,z);
plot3d(xx,yy,zz)
 ]]></programlisting>

        <scilab:image>
            t=[0:0.3:2*%pi]';
            z=sin(t)*cos(t');
            // same plot using facets computed by genfac3d
            [xx,yy,zz]=genfac3d(t,t,z);
            plot3d(xx,yy,zz)
        </scilab:image>

        <programlisting role="example"><![CDATA[
// multiple plots
t=[0:0.3:2*%pi]';
z=sin(t)*cos(t');
// same plot using facets computed by genfac3d
[xx,yy,zz]=genfac3d(t,t,z);
plot3d([xx xx],[yy yy],[zz 4+zz])
 ]]></programlisting>

        <scilab:image>
            // multiple plots
            t=[0:0.3:2*%pi]';
            z=sin(t)*cos(t');
            // same plot using facets computed by genfac3d
            [xx,yy,zz]=genfac3d(t,t,z);
            plot3d([xx xx],[yy yy],[zz 4+zz])
        </scilab:image>

        <programlisting role="example"><![CDATA[
// multiple plots using colors
t=[0:0.3:2*%pi]';
z=sin(t)*cos(t');
// same plot using facets computed by genfac3d
[xx,yy,zz]=genfac3d(t,t,z);
plot3d([xx xx],[yy yy],list([zz zz+4],[4*ones(1,400) 5*ones(1,400)]))
 ]]></programlisting>

        <scilab:image>
            t=[0:0.3:2*%pi]';
            z=sin(t)*cos(t');
            // same plot using facets computed by genfac3d
            [xx,yy,zz]=genfac3d(t,t,z);
            plot3d([xx xx],[yy yy],list([zz zz+4],[4*ones(1,400) 5*ones(1,400)]))
        </scilab:image>

        <programlisting role="example"><![CDATA[
// simple plot with viewpoint and captions
plot3d(1:10,1:20,10*rand(10,20),alpha=35,theta=45,flag=[2,2,3])
 ]]></programlisting>

        <scilab:image>
            plot3d(1:10,1:20,10*rand(10,20),alpha=35,theta=45,flag=[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));
clf();plot3d(xx,yy,zz)
 ]]></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));
            clf();plot3d(xx,yy,zz)
        </scilab:image>

        <programlisting role="example"><![CDATA[
f=gcf();
f.color_map = hotcolormap(128);
r=0.3;orig=[1.5 0 0];
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)"]);
[xx,yy,zz]=eval3dp(sph,linspace(-%pi/2,%pi/2,40),linspace(0,%pi*2,20));
[xx1,yy1,zz1]=eval3dp(sph,linspace(-%pi/2,%pi/2,40),linspace(0,%pi*2,20));
cc=(xx+zz+2)*32;cc1=(xx1-orig(1)+zz1/r+2)*32;
clf();plot3d1([xx xx1],[yy yy1],list([zz,zz1],[cc cc1]),theta=70,alpha=80,flag=[5,6,3])
 ]]></programlisting>

        <scilab:image>
            f=gcf();
            f.color_map = hotcolormap(128);
            r=0.3;orig=[1.5 0 0];
            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)"]);
            [xx,yy,zz]=eval3dp(sph,linspace(-%pi/2,%pi/2,40),linspace(0,%pi*2,20));
            [xx1,yy1,zz1]=eval3dp(sph,linspace(-%pi/2,%pi/2,40),linspace(0,%pi*2,20));
            cc=(xx+zz+2)*32;cc1=(xx1-orig(1)+zz1/r+2)*32;
            clf();plot3d1([xx xx1],[yy yy1],list([zz,zz1],[cc cc1]),theta=70,alpha=80,flag=[5,6,3])
        </scilab:image>

        <programlisting role="example"><![CDATA[
t=[0:0.3:2*%pi]'; z=sin(t)*cos(t');
[xx,yy,zz]=genfac3d(t,t,z);
plot3d([xx xx],[yy yy],list([zz zz+4],[4*ones(1,400) 5*ones(1,400)]))
e=gce();
f=e.data;
TL = tlist(["3d" "x" "y" "z" "color"],f.x,f.y,f.z,6*rand(f.z)); // random color matrix
e.data = TL;
TL2 = tlist(["3d" "x" "y" "z" "color"],f.x,f.y,f.z,4*rand(1,800)); // random color vector
e.data = TL2;
TL3 = tlist(["3d" "x" "y" "z" "color"],f.x,f.y,f.z,[20*ones(1,400) 6*ones(1,400)]);
e.data = TL3;
TL4 = tlist(["3d" "x" "y" "z"],f.x,f.y,f.z); // no color
e.data = TL4;
e.color_flag=1 // color index proportional to altitude (z coord.)
e.color_flag=2; // back to default mode
e.color_flag= 3; // interpolated shading mode (based on blue default color)
clf()
plot3d([xx xx],[yy yy],list([zz zz+4],[4*ones(1,400) 5*ones(1,400)]))
h=gce(); //get handle on current entity (here the surface)
a=gca(); //get current axes
a.rotation_angles=[40,70];
a.grid=[1 1 1]; //make grids
a.data_bounds=[-6,0,-1;6,6,5];
a.axes_visible="off"; //axes are hidden
a.axes_bounds=[.2 0 1 1];
h.color_flag=1; //color according to z
h.color_mode=-2;  //remove the facets boundary by setting color_mode to white color
h.color_flag=2; //color according to given colors
h.color_mode = -1; // put the facets boundary back by setting color_mode to black color
f=gcf();//get the handle of the parent figure
f.color_map=hotcolormap(512);
c=[1:400,1:400];
TL.color = [c;c+1;c+2;c+3];
h.data = TL;
h.color_flag=3; // interpolated shading mode
 ]]></programlisting>

        <scilab:image>
            t=[0:0.3:2*%pi]'; z=sin(t)*cos(t');
            [xx,yy,zz]=genfac3d(t,t,z);
            plot3d([xx xx],[yy yy],list([zz zz+4],[4*ones(1,400) 5*ones(1,400)]))
            e=gce();
            f=e.data;
            TL = tlist(["3d" "x" "y" "z" "color"],f.x,f.y,f.z,6*rand(f.z)); // random color matrix
            e.data = TL;
            TL2 = tlist(["3d" "x" "y" "z" "color"],f.x,f.y,f.z,4*rand(1,800)); // random color vector
            e.data = TL2;
            TL3 = tlist(["3d" "x" "y" "z" "color"],f.x,f.y,f.z,[20*ones(1,400) 6*ones(1,400)]);
            e.data = TL3;
            TL4 = tlist(["3d" "x" "y" "z"],f.x,f.y,f.z); // no color
            e.data = TL4;
            e.color_flag=1 // color index proportional to altitude (z coord.)
            e.color_flag=2; // back to default mode
            e.color_flag= 3; // interpolated shading mode (based on blue default color)
            clf()
            plot3d([xx xx],[yy yy],list([zz zz+4],[4*ones(1,400) 5*ones(1,400)]))
            h=gce(); //get handle on current entity (here the surface)
            a=gca(); //get current axes
            a.rotation_angles=[40,70];
            a.grid=[1 1 1]; //make grids
            a.data_bounds=[-6,0,-1;6,6,5];
            a.axes_visible="off"; //axes are hidden
            a.axes_bounds=[.2 0 1 1];
            h.color_flag=1; //color according to z
            h.color_mode=-2;  //remove the facets boundary by setting color_mode to white color
            h.color_flag=2; //color according to given colors
            h.color_mode = -1; // put the facets boundary back by setting color_mode to black color
            f=gcf();//get the handle of the parent figure
            f.color_map=hotcolormap(512);
            c=[1:400,1:400];
            TL.color = [c;c+1;c+2;c+3];
            h.data = TL;
            h.color_flag=3; // interpolated shading mode
        </scilab:image>
        <para>We can use the plot3d function to plot a set of patches (triangular,
            quadrangular, etc).
        </para>
        <programlisting role="example"><![CDATA[
// The plot3d function to draw patches:
// patch(x,y,[z])
// patch(x,y,[list(z,c)])
// The size of x : number of points in the patches x number of patches
// y and z have the same sizes as x
// c:
// - a vector of size number of patches: the color of the patches
// - a matrix of size number of points in the patches x number of
//   patches: the color of each points of each patches

// Example 1: a set of triangular patches

x = [0 0;
     0 1;
     1 1];

y = [1 1;
     2 2;
     2 1];

z = [1 1;
     1 1;
     1 1];

tcolor = [2 3]';

subplot(2,2,1);
plot3d(x,y,list(z,tcolor));
xtitle('A triangle set of patches');
// Example 2: a mixture of triangular and quadrangular patches

xquad = [5, 0;
         10,0;
         15,5;
         10,5];

yquad = [15,0;
         20,10;
         15,15;
         10,5];

zquad = ones(4,2);

xtri = [ 0,10,10, 5, 0;
        10,20,20, 5, 0;
        20,20,15,10,10];

ytri = [ 0,10,20, 5,10;
        10,20,20,15,20;
         0, 0,15,10,20];

ztri = zeros(3,5);

subplot(2,2,3);
plot3d(xquad,yquad,zquad);
plot3d(xtri,ytri,ztri);
xtitle('Mixing triangle and quadrangle set of patches');

// Example 3: some rabbits

rabxtri = [ 5,  5, 2.5,  7.5, 10;
            5, 15, 5,   10,   10;
           15, 15, 5,   10,   15];

rabytri = [10, 10, 9.5,  2.5, 0;
           20, 10, 12,   5,   5;
           10   0   7    0    0];
rabztri = [0,0,0,0,0;
           0,0,0,0,0;
           0,0,0,0,0];

rabtricolor_byface = [2 2 2 2 2];

rabtricolor = [2,2,2,2,2;
               3,3,3,3,3;
               4,4,4,4,4];

rabxquad = [0, 1;
            0, 6;
            5,11;
            5, 6];

rabyquad = [18,23;
            23,28;
            23,28;
            18,23];

rabzquad = [1,1;
            1,1;
            1,1;
            1,1];

rabquadcolor_byface = [2 2];

rabquadcolor = [2,2;
                3,3;
                4,4;
                5,5];

subplot(2,2,2);
plot3d(rabxtri, rabytri, list(rabztri,rabtricolor));
plot3d(rabxquad,rabyquad,list(rabzquad,rabquadcolor));
h = gcf();
h.children(1).background = 1;
xtitle('A psychedelic rabbit set of patches');

subplot(2,2,4);
plot3d(rabxtri, rabytri, list(rabztri,rabtricolor_byface));
plot3d(rabxquad,rabyquad,list(rabzquad,rabquadcolor_byface));
h = gcf();
h.children(1).background = 1;
xtitle('A standard rabbit set of patches');
 ]]></programlisting>

        <scilab:image>

            x = [0 0;
            0 1;
            1 1];

            y = [1 1;
            2 2;
            2 1];

            z = [1 1;
            1 1;
            1 1];

            tcolor = [2 3]';

            subplot(2,2,1);
            plot3d(x,y,list(z,tcolor));
            xtitle('A triangle set of patches');
            // Example 2: a mixture of triangular and quadrangular patches

            xquad = [5, 0;
            10,0;
            15,5;
            10,5];

            yquad = [15,0;
            20,10;
            15,15;
            10,5];

            zquad = ones(4,2);

            xtri = [ 0,10,10, 5, 0;
            10,20,20, 5, 0;
            20,20,15,10,10];

            ytri = [ 0,10,20, 5,10;
            10,20,20,15,20;
            0, 0,15,10,20];

            ztri = zeros(3,5);

            subplot(2,2,3);
            plot3d(xquad,yquad,zquad);
            plot3d(xtri,ytri,ztri);
            xtitle('Mixing triangle and quadrangle set of patches');

            // Example 3: some rabbits

            rabxtri = [ 5,  5, 2.5,  7.5, 10;
            5, 15, 5,   10,   10;
            15, 15, 5,   10,   15];

            rabytri = [10, 10, 9.5,  2.5, 0;
            20, 10, 12,   5,   5;
            10   0   7    0    0];
            rabztri = [0,0,0,0,0;
            0,0,0,0,0;
            0,0,0,0,0];

            rabtricolor_byface = [2 2 2 2 2];

            rabtricolor = [2,2,2,2,2;
            3,3,3,3,3;
            4,4,4,4,4];

            rabxquad = [0, 1;
            0, 6;
            5,11;
            5, 6];

            rabyquad = [18,23;
            23,28;
            23,28;
            18,23];

            rabzquad = [1,1;
            1,1;
            1,1;
            1,1];

            rabquadcolor_byface = [2 2];

            rabquadcolor = [2,2;
            3,3;
            4,4;
            5,5];

            subplot(2,2,2);
            plot3d(rabxtri, rabytri, list(rabztri,rabtricolor));
            plot3d(rabxquad,rabyquad,list(rabzquad,rabquadcolor));
            h = gcf();
            h.children(1).background = 1;
            xtitle('A psychedelic rabbit set of patches');

            subplot(2,2,4);
            plot3d(rabxtri, rabytri, list(rabztri,rabtricolor_byface));
            plot3d(rabxquad,rabyquad,list(rabzquad,rabquadcolor_byface));
            h = gcf();
            h.children(1).background = 1;
            xtitle('A standard rabbit set of patches');
        </scilab:image>

        <para>We can also use the plot3d function to plot a set of patches using
            vertex and faces.
        </para>
        <programlisting role="example"><![CDATA[
// Vertex / Faces example: 3D example

// The vertex list contains the list of unique points composing each patch
// The points common to 2 patches are not repeated in the vertex list

vertex = [0 1 1;
          0 2 2;
          1 2 3;
          1 1 4];

// The face list indicates which points are composing the patch.
face = [1 2 3;
        1 3 4];

tcolor = [2 3]';

// The formula used to translate the vertex / face representation into x, y, z lists

xvf = matrix(vertex(face,1),size(face,1),length(vertex(face,1))/size(face,1))';
yvf = matrix(vertex(face,2),size(face,1),length(vertex(face,1))/size(face,1))';
zvf = matrix(vertex(face,3),size(face,1),length(vertex(face,1))/size(face,1))';

scf();
subplot(2,1,1);
plot3d(xvf,yvf,list(zvf,tcolor));
xtitle('A triangle set of patches - vertex / face mode - 3d');

// 2D test
// We use the 3D representation with a 0 Z values and then switch to 2D representation

// Vertex / Faces example: 3D example

// The vertex list contains the list of unique points composing each patch
// The points common to 2 patches are not repeated in the vertex list

vertex = [0 1;
          0 2;
          1 2;
          1 1];

// The face list indicates which points are composing the patch.
face = [1 2 3;
        1 3 4];

// The formula used to translate the vertex / face representation into x, y, z lists

xvf = matrix(vertex(face,1),size(face,1),length(vertex(face,1))/size(face,1))';
yvf = matrix(vertex(face,2),size(face,1),length(vertex(face,1))/size(face,1))';
zvf = matrix(zeros(vertex(face,2)),size(face,1),length(vertex(face,1))/size(face,1))';
tcolor = [2 3]';

subplot(2,1,2);
plot3d(xvf,yvf,list(zvf,tcolor));
xtitle('A triangle set of patches - vertex / face mode - 2D');
a = gca();
a.view = '2d';
 ]]></programlisting>
        <scilab:image>

            vertex = [0 1 1;
            0 2 2;
            1 2 3;
            1 1 4];

            // The face list indicates which points are composing the patch.
            face = [1 2 3;
            1 3 4];

            tcolor = [2 3]';

            // The formula used to translate the vertex / face representation into x, y, z lists

            xvf = matrix(vertex(face,1),size(face,1),length(vertex(face,1))/size(face,1))';
            yvf = matrix(vertex(face,2),size(face,1),length(vertex(face,1))/size(face,1))';
            zvf = matrix(vertex(face,3),size(face,1),length(vertex(face,1))/size(face,1))';

            scf();
            subplot(2,1,1);
            plot3d(xvf,yvf,list(zvf,tcolor));
            xtitle('A triangle set of patches - vertex / face mode - 3d');

            // 2D test
            // We use the 3D representation with a 0 Z values and then switch to 2D representation

            // Vertex / Faces example: 3D example

            // The vertex list contains the list of unique points composing each patch
            // The points common to 2 patches are not repeated in the vertex list

            vertex = [0 1;
            0 2;
            1 2;
            1 1];

            // The face list indicates which points are composing the patch.
            face = [1 2 3;
            1 3 4];

            // The formula used to translate the vertex / face representation into x, y, z lists

            xvf = matrix(vertex(face,1),size(face,1),length(vertex(face,1))/size(face,1))';
            yvf = matrix(vertex(face,2),size(face,1),length(vertex(face,1))/size(face,1))';
            zvf = matrix(zeros(vertex(face,2)),size(face,1),length(vertex(face,1))/size(face,1))';
            tcolor = [2 3]';

            subplot(2,1,2);
            plot3d(xvf,yvf,list(zvf,tcolor));
            xtitle('A triangle set of patches - vertex / face mode - 2D');
            a = gca();
            a.view = '2d';
        </scilab:image>
        <para> How to set manually some ticks </para>
        <programlisting role="example"><![CDATA[
plot3d();
h = gca();
h.x_ticks = tlist(['ticks','locations','labels'],[-2,-1,0,1,2],['-2','-1','0','1','2']);
h.y_ticks = tlist(['ticks','locations','labels'],[-4,-3,-2,-1,0,1,2,3,4],['-4','-3','-2','-1','0','1','2','3','4']);
h.z_ticks = tlist(['ticks','locations','labels'],[-1,0,1],['Point 1','Point 2','Point 3']);
 ]]></programlisting>
        <scilab:image>
            plot3d();
            h = gca();
            h.x_ticks = tlist(['ticks','locations','labels'],[-2,-1,0,1,2],['-2','-1','0','1','2']);
            h.y_ticks = tlist(['ticks','locations','labels'],[-4,-3,-2,-1,0,1,2,3,4],['-4','-3','-2','-1','0','1','2','3','4']);
            h.z_ticks = tlist(['ticks','locations','labels'],[-1,0,1],['Point 1','Point 2','Point 3']);
        </scilab:image>

        <para/>
    </refsection>
    <refsection role="see also">
        <title>See also</title>
        <simplelist type="inline">
            <member>
                <link linkend="eval3dp">eval3dp</link>
            </member>
            <member>
                <link linkend="genfac3d">genfac3d</link>
            </member>
            <member>
                <link linkend="geom3d">geom3d</link>
            </member>
            <member>
                <link linkend="param3d">param3d</link>
            </member>
            <member>
                <link linkend="plot3d1">plot3d1</link>
            </member>
            <member>
                <link linkend="clf">clf</link>
            </member>
            <member>
                <link linkend="gca">gca</link>
            </member>
            <member>
                <link linkend="gcf">gcf</link>
            </member>
            <member>
                <link linkend="close">close</link>
            </member>
            <member>
                <link linkend="delete">delete</link>
            </member>
            <member>
                <link linkend="axes_properties">axes_properties</link>
            </member>
        </simplelist>
    </refsection>
</refentry>
