<?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="plot3d" xml:lang="pt">
    <refnamediv>
        <refname>plot3d</refname>
        <refpurpose>esboço 3d de uma superfície</refpurpose>
    </refnamediv>
    <refsynopsisdiv>
        <title>Seqüência de Chamamento</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;)
        </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>colors</term>
                <listitem>
                    <para>um vetor de tamanho n fornecendo as cores de cada faceta ou
                        uma matriz de tamanho (nf,n) fornecendo a cor próxima a cada borda
                        da faceta (a cor da faceta é interpolada).
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>&lt;opt_args&gt;</term>
                <listitem>
                    <para>
                        representa uma seqüência de sentenças <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 de
                        observação do ponto.
                    </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 superfície (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 relçã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 relçã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 de
                                                eixos (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 de eixos (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>, se este for 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>plot3d(x,y,z,[theta,alpha,leg,flag,ebox])</literal> desenha
            a superfície parametrizada <literal>z=f(x,y)</literal>.
        </para>
        <para>
            <literal>plot3d(xf,yf,zf,[theta,alpha,leg ,flag,ebox])</literal>
            desenha uma superfície definida por um conjunto de facetas. Você pode
            desenhar esboços multiplos substituindo <literal>xf</literal>,
            <literal>yf</literal> e <literal>zf</literal> por múltiplas matrizes
            montadas por linhas como <literal>[xf1 xf2 ...]</literal>, <literal>[yf1
                yf2 ...]
            </literal>
            e<literal>[zf1 zf2 ...]</literal>. Note que os dados
            também podem ser ajustados ou recebidos através das propriedades da
            entidade superfície (ver <link linkend="surface_properties">surface_properties</link>).
        </para>
        <para/>
        <para>Você pode fornecer uma cor específica para cada faceta utilizando
            <literal>list(zf,colors)</literal> ao invés de <literal>zf</literal>, onde
            <literal>colors</literal> é um vetor de tamanho <literal>n</literal>. Se
            <literal>colors(i)</literal> for positivo, fornece a cor da faceta
            <literal>i</literal> e a borda da faceta é desenhada utilizando-se o
            estilo de linha e cor correntes. Se <literal>colors(i)</literal> for
            negativo, o identificador de cor <literal>-colors(i)</literal> é utilizado
            e a borda da faceta não é desenhada.
        </para>
        <para/>
        <para>Também é possível obter cores interpoladas para as facetas. Para
            este tipo de cor, o argumento deve ser uma matriz nf x n fornecendo as
            cores próximas a cada borda da faceta de cada faceta. Neste caso, valores
            positivos para cores significam que as bordas não seram desenhadas. Note
            que as cores também podem ser ajustadas através das propriedades da
            entidade Surface (superfície) (via <literal>tlist</literal> affectations)
            e editadas utilizando-se a opção <literal>color_flag</literal> (ver <link linkend="surface_properties">surface_properties</link>).
        </para>
        <para/>
        <para>
            Os arugumentos opcionais <literal>theta, alpha, leg ,flag,
                ebox
            </literal>
            ,podem ser passados por uma seqüência de argumentos
            <literal>key1=value1, key2=value2</literal>, ... Neste caso, a ordem não
            tem significado especial. Note que todos estes argumentos, exceto
            <literal>flag</literal> podem ser customizados através de propriedades da
            entidade de eixos (ver <link linkend="axes_properties">axes_properties</link>). Como descrito
            anteriormente, a opção <literal>flag</literal> lida com as propriedades da
            entidade superfície para <literal>mode</literal> (ver <link linkend="surface_properties">surface_properties</link>) e as propriedades
            de eixos (Axes) para <literal>type</literal> e <literal>box</literal> (ver
            <link linkend="axes_properties">axes_properties</link>).
        </para>
        <para/>
        <para>
            Você pode utilizar a função <literal>genfac3d</literal> para
            computar facetas de quatro lados da superfície
            <literal>z=f(x,y)</literal>. <literal>eval3dp</literal> também pode ser
            utilizado.
        </para>
        <para/>
        <para>
            Entre com o comando <literal>plot3d()</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');
plot3d(t,t,z)
// o mesmo esboço utilizando facetas computadas por genfac3d
[xx,yy,zz]=genfac3d(t,t,z);
clf()
plot3d(xx,yy,zz)
// esboços múltiplos
clf()
plot3d([xx xx],[yy yy],[zz 4+zz])
// esboços múltiplos utilizando-se cores
clf()
plot3d([xx xx],[yy yy],list([zz zz+4],[4*ones(1,400) 5*ones(1,400)]))
// esboço simples utilizando ponto de observação e legendas
clf()
plot3d(1:10,1:20,10*rand(10,20),alpha=35,theta=45,flag=[2,2,3])
// esboço de uma esfera utilizando utilizando facetas computadas por 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)
clf();
f=gcf();
f.color_map = hot(128);
r=0.3;orig=[1.5 0 0];
[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])

//operações disponíveis apenas no novo modo de gráficos
close()
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)); // matriz de cores aleatória
e.data = TL;
TL2 = tlist(["3d" "x" "y" "z" "color"],f.x,f.y,f.z,4*rand(1,800)); // vetor de cores aleatório
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); // nenhuma cor
e.data = TL4;
e.color_flag=1 // índice de cor proporcional à altitude (coordenada z)
e.color_flag=2; // de volta ao modo padrão
e.color_flag= 3; // modo de gradação interpolada (baseada na cor azul padrão)
clf()
plot3d([xx xx],[yy yy],list([zz zz+4],[4*ones(1,400) 5*ones(1,400)]))
h=gce(); //obtendo manipulador da entidade corrente (aqui é a superfície)
a=gca(); //obtendo eixos correntes
a.rotation_angles=[40,70];
a.grid=[1 1 1]; //criando grides
a.data_bounds=[-6,0,-1;6,6,5];
a.axes_visible="off"; //os eixo estão escondidos
a.axes_bounds=[.2 0 1 1];
h.color_flag=1; //colorindo de acordo com z
h.color_mode=-2;  //removendo as bordas das facetas ajustando color_mode para a cor branca
h.color_flag=2; //colorindo de acordo com as cores fornecidas
h.color_mode = -1; // colocando de volta as bordas das facetas ajustando color_mode de volta para preto
f=gcf();//obtendo o manipulador da figura raiz
f.color_map=hot(512);
c=[1:400,1:400];
TL.color = [c;c+1;c+2;c+3];
h.data = TL;
h.color_flag=3; // modo de gradação interpolada
 ]]></programlisting>
        <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>
        <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))';

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>
        <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>
        <para/>
    </refsection>
    <refsection role="see also">
        <title>Ver Também</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>
