<?xml version="1.0" encoding="ISO-8859-1"?>
<!--
 * Scilab ( http://www.scilab.org/ ) - This file is part of Scilab
 * Copyright (C) ENPC - Jean-Philippe Chancelier
 * 
 * This file must be used under the terms of the CeCILL.
 * This source file is licensed as described in the file COPYING, which
 * you should have received as part of this distribution.  The terms
 * are also available at    
 * http://www.cecill.info/licences/Licence_CeCILL_V2-en.txt
 *
 -->
<refentry version="5.0-subset Scilab" xml:id="plot3d" xml:lang="en"
          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">
  <info>
    <pubdate>$LastChangedDate$</pubdate>
  </info>

  <refnamediv>
    <refname>plot3d</refname>

    <refpurpose>esboo 3d de uma superfcie</refpurpose>
  </refnamediv>

  <refsynopsisdiv>
    <title>Seqncia 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>Parmetros</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 montonas.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>z</term>

        <listitem>
          <para>matriz de tamanho (n1,n2). <literal>z(i,j)</literal>  o valor
          da superfcie 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 superfcie. H <literal>n</literal> facetas. Cada
          faceta <literal>i</literal>  definida por um polgono com
          <literal>nf</literal> pontos. As coordenadas dos eixos x, y e z dos
          pontos da i-sima faceta so 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 prxima a cada borda
          da faceta (a cor da faceta  interpolada).</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>&lt;opt_args&gt;</term>

        <listitem>
          <para>representa uma seqncia de sentenas <literal>key1=value1,
          key2=value2</literal>,... onde <literal>key1</literal>,
          <literal>key2,...</literal> pode ser um dos seguintes: theta, alpha
          , leg, flag, ebox (ver definies abaixo).</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>theta, alpha</term>

        <listitem>
          <para>valores reais de dados em graus, as coordenadas esfricas de
          observao do ponto.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>leg</term>

        <listitem>
          <para>string definindo os rtulos 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 trs.
          <literal>flag=[mode,type,box]</literal>.</para>

          <variablelist>
            <varlistentry>
              <term>mode</term>

              <listitem>
                <para>um inteiro (cor da superfcie).</para>

                <variablelist>
                  <varlistentry>
                    <term>mode&gt;0</term>

                    <listitem>
                      <para>a superfcie  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 superfcie  desenhada.</para>
                    </listitem>
                  </varlistentry>

                  <varlistentry>
                    <term>mode&lt;0:</term>

                    <listitem>
                      <para>a superfcie  pintada com a cor
                      <literal>"-mode"</literal> ; a borda da faceta no 
                      desenhada.</para>

                      <para>Note que o tratamento de cor da superfcie pode
                      ser feito utilizando-se as opes
                      <literal>color_mode</literal> e
                      <literal>color_flag</literal> atravs das propriedades
                      da entidade superfcie (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 esboo  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 relo de
                      aspecto extrema, as fronteiras so 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 relo de
                      aspecto extrema, as fronteiras so computadas
                      utilizando-se dados fornecidos.</para>
                    </listitem>
                  </varlistentry>

                  <varlistentry>
                    <term>type=3:</term>

                    <listitem>
                      <para>fronteiras 3d isomtricas 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 isomtricas derivadas dos dados, de
                      modo semelhante a <literal>type=2</literal>.</para>
                    </listitem>
                  </varlistentry>

                  <varlistentry>
                    <term>type=5:</term>

                    <listitem>
                      <para>fronteiras 3d isomtricas 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 isomtricas expandidas derivadas dos
                      dados, de modo semelhante a
                      <literal>type=2</literal>.</para>

                      <para>Note que as fronteiras dos eixos podem ser
                      customizadas atravs 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 esboo).</para>

                <variablelist>
                  <varlistentry>
                    <term>box=0:</term>

                    <listitem>
                      <para>nada  desenhado ao redor do esboo.</para>
                    </listitem>
                  </varlistentry>

                  <varlistentry>
                    <term>box=1:</term>

                    <listitem>
                      <para>no implementado ( como box=0).</para>
                    </listitem>
                  </varlistentry>

                  <varlistentry>
                    <term>box=2:</term>

                    <listitem>
                      <para>apenas os eixos atrs da superfcie so
                      desenhados.</para>
                    </listitem>
                  </varlistentry>

                  <varlistentry>
                    <term>box=3:</term>

                    <listitem>
                      <para>uma caixa cercando a superfcie  desenhada e
                      legendas so adicionadas.</para>
                    </listitem>
                  </varlistentry>

                  <varlistentry>
                    <term>box=4:</term>

                    <listitem>
                      <para>uma caixa cercando a superfcie  desenhada e
                      legendas e eixos so adicionados.</para>

                      <para>Note que o aspecto dos eixos pode ser customizado
                      atravs 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 esboo atravs 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>
          no  levado em conta.</para>

          <para>Note que, quando especificado, o argumento
          <literal>ebox</literal> age no campo <literal>data_bounds</literal>
          que tambm pode ser ajustado atravs das propriedades da entidade de
          eixos (ver <link
          linkend="axes_properties">axes_properties</link>).</para>
        </listitem>
      </varlistentry>
    </variablelist>
  </refsection>

  <refsection>
    <title>Descrio</title>

    <para><literal>plot3d(x,y,z,[theta,alpha,leg,flag,ebox])</literal> desenha
    a superfcie parametrizada <literal>z=f(x,y)</literal>.</para>

    <para><literal>plot3d(xf,yf,zf,[theta,alpha,leg ,flag,ebox])</literal>
    desenha uma superfcie definida por um conjunto de facetas. Voc pode
    desenhar esboos multiplos substituindo <literal>xf</literal>,
    <literal>yf</literal> e <literal>zf</literal> por mltiplas matrizes
    montadas por linhas como <literal>[xf1 xf2 ...]</literal>, <literal>[yf1
    yf2 ...]</literal> e <literal>[zf1 zf2 ...]</literal>. Note que os dados
    tambm podem ser ajustados ou recebidos atravs das propriedades da
    entidade superfcie (ver <link
    linkend="surface_properties">surface_properties</link>).</para>

    <para></para>

    <para>Voc pode fornecer uma cor especfica para cada faceta utilizando
    <literal>list(zf,colors)</literal> ao invs 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 no  desenhada.</para>

    <para></para>

    <para>Tambm  possvel obter cores interpoladas para as facetas. Para
    este tipo de cor, o argumento deve ser uma matriz nf x n fornecendo as
    cores prximas a cada borda da faceta de cada faceta. Neste caso, valores
    positivos para cores significam que as bordas no seram desenhadas. Note
    que as cores tambm podem ser ajustadas atravs das propriedades da
    entidade Surface (superfcie) (via <literal>tlist</literal> affectations)
    e editadas utilizando-se a opo <literal>color_flag</literal> (ver <link
    linkend="surface_properties">surface_properties</link>).</para>

    <para></para>

    <para>Os arugumentos opcionais <literal>theta, alpha, leg ,flag,
    ebox</literal>, podem ser passados por uma seqncia de argumentos
    <literal>key1=value1, key2=value2</literal>, ... Neste caso, a ordem no
    tem significado especial. Note que todos estes argumentos, exceto
    <literal>flag</literal> podem ser customizados atravs de propriedades da
    entidade de eixos (ver <link
    linkend="axes_properties">axes_properties</link>). Como descrito
    anteriormente, a opo <literal>flag</literal> lida com as propriedades da
    entidade superfcie 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>

    <para>Voc pode utilizar a funo <literal>genfac3d</literal> para
    computar facetas de quatro lados da superfcie
    <literal>z=f(x,y)</literal>. <literal>eval3dp</literal> tambm pode ser
    utilizado.</para>

    <para></para>

    <para>Entre com o comando <literal>plot3d()</literal> para visualizar uma
    demonstrao.</para>
  </refsection>

  <refsection>
    <title>Exemplos</title>

    <programlisting role="example"><![CDATA[ 
// esboo simples utilizando z=f(x,y) 
t=[0:0.3:2*%pi]';
z=sin(t)*cos(t');
plot3d(t,t,z) 
// o mesmo esboo utilizando facetas computadas por genfac3d
[xx,yy,zz]=genfac3d(t,t,z); 
clf() 
plot3d(xx,yy,zz)
// esboos mltiplos
clf()
plot3d([xx xx],[yy yy],[zz 4+zz]) 
// esboos mltiplos utilizando-se cores
clf()
plot3d([xx xx],[yy yy],list([zz zz+4],[4*ones(1,400) 5*ones(1,400)])) 
// esboo simples utilizando ponto de observao e legendas
clf() 
plot3d(1:10,1:20,10*rand(10,20),alpha=35,theta=45,flag=[2,2,3]) 
// esboo 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 = hotcolormap(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])

//operaes disponveis apenas no novo modo de grficos
delete(gcf());
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 aleatria
e.data = TL;
TL2 = tlist(["3d" "x" "y" "z" "color"],f.x,f.y,f.z,4*rand(1,800)); // vetor de cores aleatrio
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 padro
e.color_flag= 3; // modo de gradao interpolada (baseada na cor azul padro)
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 superfcie)
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 esto 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=hotcolormap(512);
c=[1:400,1:400];
TL.color = [c;c+1;c+2;c+3];
h.data = TL;
h.color_flag=3; // modo de gradao 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>The result of the preceding example:</para>

    <mediaobject>
      <imageobject>
        <imagedata align="center" fileref="../images/plot3d_patch.png" />
      </imageobject>
    </mediaobject>

    <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>The result of the preceding example:</para>

    <mediaobject>
      <imageobject>
        <imagedata align="center" fileref="../images/plot3d_patch_vertex.png" />
      </imageobject>
    </mediaobject>

    <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></para>
  </refsection>

  <refsection>
    <title>Ver Tambm</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="xdel">xdel</link></member>

      <member><link linkend="delete">delete</link></member>

      <member><link linkend="axes_properties">axes_properties</link></member>
    </simplelist>
  </refsection>

  <refsection>
    <title>Autor</title>

    <para>J.Ph.C.</para>
  </refsection>
</refentry>