<?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="plot3d1" 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>plot3d1</refname>

    <refpurpose>Esboo 3d em nveis de cinza ou de cores de uma
    superfcie</refpurpose>
  </refnamediv>

  <refsynopsisdiv>
    <title>Seqncia 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>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>&lt;opt_args&gt;</term>

        <listitem>
          <para>representa uma seqncia de declaraes <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 do
          ponto de observao. </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 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 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 relao 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 relao 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 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 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 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 esboo atravs 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> 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>plot3d1</literal> esboa uma superfcie com cores
    dependendo do nvel z da superfcie. Esta funo de esboo especial tambm
    pode ser habilitada ajustando <literal>color_flag=1</literal> aps um
    <literal>plot3d</literal> (ver <link
    linkend="surface_properties">surface_properties</link>)</para>

    <para>Entre com o comando <literal>plot3d1()</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'); 
plot3d1(t,t,z) 
// mesmo esboo utilizando facetas computadas por genfac3d 
[xx,yy,zz]=genfac3d(t,t,z); 
clf(); 
plot3d1(xx,yy,zz) 
// esboos mltiplos 
clf(); 
plot3d1([xx xx],[yy yy],[zz 4+zz]) 
// esboo simples com ponto de vista e legendas 
clf() ;
plot3d1(1:10,1:20,10*rand(10,20),35,45,"X@Y@Z",[2,2,3]) 
// mesmo esboo sem grid
clf() 
plot3d1(1:10,1:20,10*rand(10,20),35,45,"X@Y@Z",[-2,2,3]) 
// esboo de uma esfera 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)
e=gce();
e.color_flag=1;
scf(2);
plot3d1(xx,yy,zz) // os dois grficos so similares
 ]]></programlisting>
  </refsection>

  <refsection>
    <title>Ver Tambm</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>

  <refsection>
    <title>Autor</title>

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