<?xml version="1.0" encoding="UTF-8"?>
<!--
 * Scilab ( https://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="plot3d1" xml:lang="pt">
    <refnamediv>
        <refname>plot3d1</refname>
        <refpurpose>Esboço 3d em níveis de cinza ou de cores de uma
            superfície
        </refpurpose>
    </refnamediv>
    <refsynopsisdiv>
        <title>Seqüência de Chamamento</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>Parâmetros</title>
        <variablelist>
            <varlistentry>
                <term>x,y</term>
                <listitem>
                    <para>vetores linhas de tamanhos n1 e n2 (coordenadas dos eixos x e
                        y). Estas coordenadas devem ser monótonas.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>z</term>
                <listitem>
                    <para>
                        matriz de tamanho (n1,n2). <literal>z(i,j)</literal> é o valor
                        da superfície no ponto (x(i),y(j)).
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>xf,yf,zf</term>
                <listitem>
                    <para>matrizes de tamanho (nf,n). Elas definem as facetas usadas
                        para desenhar a superfície. Há <literal>n</literal> facetas. Cada
                        faceta <literal>i</literal> é definida por um polígono com
                        <literal>nf</literal> pontos. As coordenadas dos eixos x, y e z dos
                        pontos da i-ésima faceta são dados respectivamente por
                        <literal>xf(:,i)</literal>, <literal>yf(:,i)</literal> e
                        <literal>zf(:,i)</literal>.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>&lt;opt_args&gt;</term>
                <listitem>
                    <para>
                        representa uma seqüência de declarações <literal>key1=value1,
                            key2=value2
                        </literal>
                        ,... onde <literal>key1</literal>,
                        <literal>key2,...</literal> pode ser um dos seguintes: theta, alpha
                        , leg, flag, ebox (ver definições abaixo).
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>theta, alpha</term>
                <listitem>
                    <para>valores reais de dados em graus, as coordenadas esféricas do
                        ponto de observação.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>leg</term>
                <listitem>
                    <para>string definindo os rótulos para cada eixo com @ como um
                        separador de campos, por exemplo "X@Y@Z".
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>flag</term>
                <listitem>
                    <para>um vetor real de tamanho três.
                        <literal>flag=[mode,type,box]</literal>.
                    </para>
                    <variablelist>
                        <varlistentry>
                            <term>mode</term>
                            <listitem>
                                <para>um inteiro (cor da superfície).</para>
                                <variablelist>
                                    <varlistentry>
                                        <term>mode&gt;0</term>
                                        <listitem>
                                            <para>a superfície é pintada com a cor
                                                <literal>"mode"</literal> ; a borda da faceta é
                                                desenhada com o estilo e linha e cor correntes.
                                            </para>
                                        </listitem>
                                    </varlistentry>
                                    <varlistentry>
                                        <term>mode=0:</term>
                                        <listitem>
                                            <para>uma malha da superfície é desenhada. </para>
                                        </listitem>
                                    </varlistentry>
                                    <varlistentry>
                                        <term>mode&lt;0:</term>
                                        <listitem>
                                            <para> a superfície é pintada com a cor
                                                <literal>"-mode"</literal> ; a borda da faceta não é
                                                desenhada.
                                            </para>
                                            <para>Note que o tratamento de cor da superfície pode
                                                ser feito utilizando-se as opções
                                                <literal>color_mode</literal> e
                                                <literal>color_flag</literal> através das propriedades
                                                da entidade Surface (ver <link linkend="surface_properties">surface_properties</link>).
                                            </para>
                                        </listitem>
                                    </varlistentry>
                                </variablelist>
                            </listitem>
                        </varlistentry>
                        <varlistentry>
                            <term>type</term>
                            <listitem>
                                <para>um inteiro (tipo de escala).</para>
                                <variablelist>
                                    <varlistentry>
                                        <term>type=0:</term>
                                        <listitem>
                                            <para>o esboço é feito utilizando-se a escala 3d
                                                corrente (definida por uma chamada anterior a
                                                <literal>param3d</literal>, <literal>plot3d</literal>,
                                                <literal>contour</literal> ou
                                                <literal>plot3d1</literal>).
                                            </para>
                                        </listitem>
                                    </varlistentry>
                                    <varlistentry>
                                        <term>type=1:</term>
                                        <listitem>
                                            <para>re-escala automaticamente caixas 3d com relação de
                                                aspecto extrema, as fronteiras são especificadas pelo
                                                valor do argumento opcional
                                                <literal>ebox</literal>.
                                            </para>
                                        </listitem>
                                    </varlistentry>
                                    <varlistentry>
                                        <term>type=2:</term>
                                        <listitem>
                                            <para>re-escala automaticamente caixas 3d com relação de
                                                aspecto extrema, as fronteiras são computadas
                                                utilizando-se dados fornecidos.
                                            </para>
                                        </listitem>
                                    </varlistentry>
                                    <varlistentry>
                                        <term>type=3:</term>
                                        <listitem>
                                            <para>fronteiras 3d isométricas com fronteiras da caixa
                                                dadas por <literal>ebox</literal>, de modo semelhante a
                                                <literal>type=1</literal>.
                                            </para>
                                        </listitem>
                                    </varlistentry>
                                    <varlistentry>
                                        <term>type=4:</term>
                                        <listitem>
                                            <para>fronteiras 3d isométricas derivadas dos dados, de
                                                modo semelhante a <literal>type=2</literal>.
                                            </para>
                                        </listitem>
                                    </varlistentry>
                                    <varlistentry>
                                        <term>type=5:</term>
                                        <listitem>
                                            <para>fronteiras 3d isométricas expandidas com
                                                fronteiras fornecidas por <literal>ebox</literal>, de
                                                modo semelhante a <literal>type=1</literal>.
                                            </para>
                                        </listitem>
                                    </varlistentry>
                                    <varlistentry>
                                        <term>type=6:</term>
                                        <listitem>
                                            <para> fronteiras 3d isométricas expandidas derivadas
                                                dos dados, de modo semelhante a
                                                <literal>type=2</literal>.
                                            </para>
                                            <para>Note que as fronteiras dos eixos podem ser
                                                customizadas através das propriedades da entidade Axes
                                                (ver <link linkend="axes_properties">axes_properties</link>).
                                            </para>
                                        </listitem>
                                    </varlistentry>
                                </variablelist>
                            </listitem>
                        </varlistentry>
                        <varlistentry>
                            <term>box</term>
                            <listitem>
                                <para>um inteiro (moldura ao redor do esboço).</para>
                                <variablelist>
                                    <varlistentry>
                                        <term>box=0:</term>
                                        <listitem>
                                            <para>nada é desenhado ao redor do esboço. </para>
                                        </listitem>
                                    </varlistentry>
                                    <varlistentry>
                                        <term>box=1:</term>
                                        <listitem>
                                            <para>não implementado (é como box=0). </para>
                                        </listitem>
                                    </varlistentry>
                                    <varlistentry>
                                        <term>box=2:</term>
                                        <listitem>
                                            <para>apenas os eixos atrás da superfície são
                                                desenhados.
                                            </para>
                                        </listitem>
                                    </varlistentry>
                                    <varlistentry>
                                        <term>box=3:</term>
                                        <listitem>
                                            <para>uma caixa cercando a superfície é desenhada e
                                                legendas são adicionadas.
                                            </para>
                                        </listitem>
                                    </varlistentry>
                                    <varlistentry>
                                        <term>box=4:</term>
                                        <listitem>
                                            <para>uma caixa cercando a superfície é desenhada e
                                                legendas e eixos são adicionados.
                                            </para>
                                            <para>Note que o aspecto dos eixos pode ser customizado
                                                através das propriedades da entidade Axes (ver <link linkend="axes_properties">axes_properties</link>).
                                            </para>
                                        </listitem>
                                    </varlistentry>
                                </variablelist>
                            </listitem>
                        </varlistentry>
                    </variablelist>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>ebox</term>
                <listitem>
                    <para>especifica as fronteiras do esboço através do vetor
                        <literal>[xmin,xmax,ymin,ymax,zmin,zmax]</literal>. Este argumento é
                        utilizado junto com <literal>type</literal> em
                        <literal>flag</literal> : é ajustado para <literal>1</literal>,
                        <literal>3</literal> ou <literal>5</literal> (volte acima para ver o
                        comportamento correspondente). Se <literal>flag</literal> estiver
                        faltando, <literal>ebox</literal> não é levado em conta.
                    </para>
                    <para>Note que, quando especificado, o argumento
                        <literal>ebox</literal> age no campo <literal>data_bounds</literal>
                        que também pode ser ajustado através das propriedades da entidade de
                        eixos (ver <link linkend="axes_properties">axes_properties</link>).
                    </para>
                </listitem>
            </varlistentry>
        </variablelist>
    </refsection>
    <refsection>
        <title>Descrição</title>
        <para>
            <literal>plot3d1</literal> esboça uma superfície com cores
            dependendo do nível z da superfície. Esta função de esboço especial também
            pode ser habilitada ajustando <literal>color_flag=1</literal> após um
            <literal>plot3d</literal> (ver <link linkend="surface_properties">surface_properties</link>)
        </para>
        <para>
            Entre com o comando <literal>plot3d1()</literal> para visualizar uma
            demonstração.
        </para>
    </refsection>
    <refsection>
        <title>Exemplos</title>

        <programlisting role="example"><![CDATA[
// esboço simples utilizando 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[
// mesmo esboço utilizando facetas computadas por 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[
// esboços múltiplos
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[
// esboço simples com ponto de vista e legendas
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[
// mesmo esboço sem 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[
// mesmo esboço sem grid
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) // os dois gráficos são similares
 ]]></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>Ver Também</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>
