<?xml version="1.0" encoding="UTF-8"?>
<!--
 * Scilab ( http://www.scilab.org/ ) - This file is part of Scilab
 * Copyright (C) INRIA
 *
 * 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="plot3d3">
    <refnamediv>
        <refname>plot3d3</refname>
        <refpurpose>mesh plot surface defined by rectangular
            facets
        </refpurpose>
    </refnamediv>
    <refsynopsisdiv>
        <title>Syntax</title>
        <synopsis>plot3d3(X,Y,Z [,vect,theta,alpha,leg,flag,ebox])
            plot3d3(X,Y,Z, &lt;opt_args&gt;)
        </synopsis>
    </refsynopsisdiv>
    <refsection>
        <title>Arguments</title>
        <variablelist>
            <varlistentry>
                <term>X, Y, Z:</term>
                <listitem>
                    <para>3 real matrices defining a data structure.</para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>vect</term>
                <listitem>
                    <para>a real vector.</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 four.
                        <literal>flag=[vertical_color, horizontal_color,type,box]</literal>.
                    </para>
                    <variablelist>
                        <varlistentry>
                            <term>vertical_color</term>
                            <listitem>
                                <para>an integer (surface color), default is 3.</para>
                                <para>Colormap index defining the color used to draw vertical edges.</para>
                            </listitem>
                        </varlistentry>
                        <varlistentry>
                            <term>horizontal_color</term>
                            <listitem>
                                <para>an integer (surface color), default is 4.</para>
                                <para>Colormap index defining the color used to draw horizontal edges.</para>
                            </listitem>
                        </varlistentry>
                        <varlistentry>
                            <term>type</term>
                            <listitem>
                                <para>an integer (scaling) default is 2.</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), default is 4.</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. 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>plot3d3</literal> performs a mesh plot of a surface defined by
            rectangular facets. (X,Y,Z) are three matrices which describe a surface.
            The surface is composed of four sided polygons.
        </para>
        <para>The X-coordinates of a facet are given by
            X(i,j), X(i+1,j), X(i+1,j+1) and X(i,j+1). Similarly Y and Z matrices contain Y and Z-coordinates.
        </para>
        <para>
            The <literal>vect</literal> vector is used when multiple surfaces are coded
            in the same (X,Y,Z) matrices. <literal>vect(j)</literal> gives the line at which
            the coding of the jth surface begins. See <literal>plot3d2</literal> for a full
            description. As a mesh plot, the only available property you can edit is
            the <literal>visible</literal> option (see <link linkend="axes_properties">axes_properties</link>).
        </para>
    </refsection>
    <refsection>
        <title>Examples</title>
        <programlisting role="example"><![CDATA[
u = linspace(-%pi/2,%pi/2,40);
v = linspace(0,2*%pi,20);
X = cos(u)'*cos(v);
Y = cos(u)'*sin(v);
Z = sin(u)'*ones(v);
plot3d3(X,Y,Z);
e=gce(); // get the current entity
e.visible='off';
e.visible='on'; // back to the mesh view
 ]]></programlisting>
        <scilab:image>u = linspace(-%pi/2,%pi/2,40);
            v = linspace(0,2*%pi,20);
            X = cos(u)'*cos(v);
            Y = cos(u)'*sin(v);
            Z = sin(u)'*ones(v);
            plot3d3(X,Y,Z);
        </scilab:image>

    </refsection>
    <refsection role="see also">
        <title>See also</title>
        <simplelist type="inline">
            <member>
                <link linkend="plot3d2">plot3d2</link>
            </member>
            <member>
                <link linkend="plot3d">plot3d</link>
            </member>
            <member>
                <link linkend="param3d">param3d</link>
            </member>
        </simplelist>
    </refsection>
</refentry>
