<?xml version="1.0" encoding="ISO-8859-1"?>
<!--
 * Scilab ( http://www.scilab.org/ ) - This file is part of Scilab
 * Copyright (C) INRIA - Fabrice Leray
 * 
 * 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="plot" 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>plot</refname>

    <refpurpose>Esboo 2d</refpurpose>
  </refnamediv>

  <refsynopsisdiv>
    <title>Seqncia de Chamamento</title>

    <synopsis>plot(y,&lt;LineSpec&gt;,&lt;GlobalProperty&gt;)
plot(x,y,&lt;LineSpec&gt;,&lt;GlobalProperty&gt;)
plot(x1,y1,&lt;LineSpec1&gt;,x2,y2,&lt;LineSpec2&gt;,...xN,yN,&lt;LineSpecN&gt;,&lt;GlobalProperty1&gt;,&lt;GlobalProperty2&gt;,..&lt;GlobalPropertyM&gt;)
plot(&lt;axes_handle&gt;,...)</synopsis>
  </refsynopsisdiv>

  <refsection>
    <title>Parmetros</title>

    <variablelist>
      <varlistentry>
        <term>x</term>

        <listitem>
          <para>uma matriz ou vetor de reais. Se omitido,  assumido como
          sendo o vetor <literal>1:n</literal> onde <literal>n</literal>  o
          nmero de pontos de curva dado pelo parmetro
          <literal>y</literal>.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>y</term>

        <listitem>
          <para>uma matriz de reais ou um vetor. <literal>y</literal> tambm
          pode ser uma funo definida como um macro ou uma primitiva. </para>
        </listitem>
      </varlistentry>

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

        <listitem>
          <para>este argumento opcional deve ser usado como um atalho para
          especificar um modo de desenhar uma linha. Podemos ter um
          <literal>LineSpec</literal> por<literal> y</literal> ou
          <literal>{x,y}</literal> previamente entrados. As opes
          <literal>LineSpec</literal> lidam com os especificadores LineStyle,
          Marker e Color (ver <link linkend="LineSpec">LineSpec</link>). Estes
          especificadores determinam o estilo de linha, de marcas e a cor das
          linhas esboadas. </para>
        </listitem>
      </varlistentry>

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

        <listitem>
          <para>este argumento opcional representa uma seqncia de pares de
          declaraes <literal>{PropertyName,PropertyValue}</literal> tque
          define propriedades globais de objetos a serem aplicadas a todas as
          curvas criadas pelo esboo. Para uma visualizao completa de das
          propriedades disponveis veja <link
          linkend="GlobalProperty">GlobalProperty</link>.</para>
        </listitem>
      </varlistentry>

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

        <listitem>
          <para>este argumento opcional fora o esboo a aparecer dentro dos
          eixos selecionados fornecidos por <literal>axes_handle</literal> ao
          invs dos eixos correntes (ver <link
          linkend="gca">gca</link>).</para>
        </listitem>
      </varlistentry>
    </variablelist>
  </refsection>

  <refsection>
    <title>Descrio</title>

    <para><literal>plot</literal> esboa um conjunto de curvas 2d.
    <literal>plot</literal> foi reconstrudo para lidar melhor com a sintaxe
    do Matlab. Para melhorar a compatibilidade grfica com o Matlab, utilize
    <literal>plot</literal> (ao invs de <link
    linkend="plot2d">plot2d</link>).</para>

    <para>Especificao de entrada de dados:</para>

    <para>Neste pargrafo, para sermos mais claros, no mencionaremos os
    argumentos opcionais <literal>LineSpec</literal> ou
    <literal>GlobalProperty</literal> j que eles no interferem na entrada de
    dados (exceto pelas propriedades <literal>"Xdata"</literal>,
    <literal>"Ydata"</literal> e <literal>"Zdata"</literal>, ver <link
    linkend="GlobalProperty">GlobalProperty</link>).  assumido que todos
    estes argumentos podem estar presentes tambm.</para>

    <para>Se <literal>y</literal>  um vetor, plot(y) esboa um vetor
    <literal>y</literal> versus o vetor
    <literal>1:size(y,'*')</literal>.</para>

    <para>Se <literal>y</literal>  uma matriz, plot(y) esboa cada coluna de
    <literal>y</literal> versus o vetor <literal>1:size(y,1)</literal>.</para>

    <para>Se <literal>x</literal> e <literal>y</literal> so vetores,
    plot(x,y) esboa o vetor <literal>y</literal> versus o vetor
    <literal>x</literal>. Os vetores <literal>x</literal> e
    <literal>y</literal> devem ter o mesmo nmero de entradas.</para>

    <para>Se <literal>x</literal>  um vetor e <literal>y</literal> uma matriz
    plot(x,y) esboa cada coluna de <literal>y</literal> versus o vetor
    <literal>x</literal>. Neste caso, o nmero de colunas de
    <literal>y</literal> deve ser igual ao nmero de entradas de
    <literal>x</literal>.</para>

    <para>Se <literal>x</literal> e <literal>y</literal> so matrizes,
    plot(x,y) esboa cada coluna de <literal>y</literal> versus a coluna
    correspondente de <literal>x</literal>. Neste caso, os tamanhos
    <literal>x</literal> e <literal>y</literal> devem ser os mesmos.</para>

    <para>Finalmente, se apenas <literal>x</literal> ou <literal>y</literal> 
    uma matriz, o vetor  esboado versus cada linha ou cada coluna da matriz.
    A escolha  feita dependendo se a dimenso de linha ou coluna do vetor
    coincide com a dimenso de linha ou coluna da matriz. No caso de uma
    matriz quadrada (apenas <literal>x</literal> ou penas
    <literal>y</literal>), a prioridade  dada a colunas ao invs de linhas
    (ver exemplos abaixo).</para>

    <para><literal>y</literal> tambm pode ser uma funo definida como um
    macro ou uma primitiva. Neste caso, os dados <literal>x</literal> devem
    ser fornecidos (como um vetor ou uma matriz) e a computao correspondente
    de <literal>y(x)</literal>  feita implicitamente.</para>

    <para>Os argumentos <literal>LineSpec</literal> e
    <literal>GlobalProperty</literal> devem ser utilizados para customizar o
    esboo. Aqui est uma lista completa das opes disponveis.</para>

    <variablelist>
      <varlistentry>
        <term>LineSpec</term>

        <listitem>
          <para>esta opo pode ser utilizada para se especificar, de um modo
          curto e fcil, como as curvas so desenhadas. Deve sempre ser um
          string contendo referncias aos especificadores LineStyle, Marker e
          Color.</para>

          <para>Essas referncias devem ser ajustadas denro do string (a ordem
          no  importante) de modo a no ter ambigidades. Por exemplo, para
          especificar uma linha vermelha de trao longo com marcas de rombos,
          pode-se escrever : <literal>'r--d'</literal> ou
          <literal>'--dire'</literal> ou <literal>'--reddiam'</literal> ou
          outra sentena sem ambigidade... ou de modo completo
          <literal>'diamondred--'</literal> (ver <link
          linkend="LineSpec">LineSpec</link>).</para>

          <para>Note que os estilos de linha e marcas (e tamanhos) e as cores,
          podem ser (re*)ajustados atravs das propriedades da entidade
          poligonal (ver <link
          linkend="polyline_properties">polyline_properties</link>).</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>GlobalProperty</term>

        <listitem>
          <para>esta opo pode ser utilizada para especificar como as linhas
          sero desenhadas com mais opes que via
          <literal>LineSpec</literal>. Deve sempre ser um par de declaraes
          constituidos de um string definindo <literal>PropertyName</literal>,
          (nome da propriedade) e seu valor associado
          <literal>PropertyValue</literal> (que pode ser um string, um inteiro
          ou qualquer outra coisa... dependendo do tipo de
          <literal>PropertyName</literal>). Utilizando-se
          <literal>GlobalProperty</literal>, pode-se ajustar vrias
          propriedades : todas as propriedades disponveis via LineSpec e
          mais: a cor da marca (plano de fundo e primeiro plano), a
          visibilidade, o recorte e a espessura das curvas. (ver <link
          linkend="GlobalProperty">GlobalProperty</link>)</para>

          <para>Note que todas as propriedades podem ser (re-)ajustadas
          atravs das propriedades de entidades poligonais (ver <link
          linkend="polyline_properties">polyline_properties</link>).</para>
        </listitem>
      </varlistentry>
    </variablelist>
  </refsection>

  <refsection>
    <title>Observaes </title>

    <para>Por padro, esboos sucessivos so superpostos. Para limpar o esboo
    anterior, use <literal>clf()</literal>. Para habilitar o modo
    <literal>auto_clear</literal> (limpeza automtica) como modo padro, edite
    seus eixos fazendo o seguinte:</para>

    <para>da=gda();</para>

    <para>da.auto_clear = 'on'</para>

    <para>Para uma melhor exibio, a funo <literal>plot</literal> pode
    modificar a propriedade <literal>box</literal> de seu Axes (eixos) raze.
    Isto acontece quando uma entidade Axes  criada por uma chamada a
    <literal>plot</literal> ou  vazia antes da chamada. Se um dos eixos 
    centrado na origem, box  desabilitado. Em caso contrrio, box 
    habilitado.</para>

    <para>Para mais informaes sobre a propriedade box e sobre o
    posicionamento dos eixos, veja <link
    linkend="axes_properties">axes_properties</link></para>

    <para>Uma tabela de cores padro  utilizada para colorir as curvas
    esboadas quando voc no especifica as cores. Ao desenhar linhas
    mltiplas, o comando plot automaticamente atribui as cores abaixo de modo
    cclico. Aqui esto as cores utilizadas:</para>

    <informaltable border="1">
      <tr>
        <td><literal>R</literal></td>

        <td><literal>G</literal></td>

        <td><literal>B</literal></td>
      </tr>

      <tr>
        <td>0.</td>

        <td>0.</td>

        <td>1.</td>
      </tr>

      <tr>
        <td>0.</td>

        <td>0.5</td>

        <td>0.</td>
      </tr>

      <tr>
        <td>1.</td>

        <td>0.</td>

        <td>0.</td>
      </tr>

      <tr>
        <td>0.</td>

        <td>0.75</td>

        <td>0.75</td>
      </tr>

      <tr>
        <td>0.75</td>

        <td>0.</td>

        <td>0.75</td>
      </tr>

      <tr>
        <td>0.75</td>

        <td>0.75</td>

        <td>0.</td>
      </tr>

      <tr>
        <td>0.25</td>

        <td>0.25</td>

        <td>0.25</td>
      </tr>
    </informaltable>

    <para></para>

    <para>Entre com o comando <literal>plot</literal> para visualizar uma
    demonstrao.</para>
  </refsection>

  <refsection>
    <title>Exemplos</title>

    <programlisting role="example"><![CDATA[ 
// inicializao de x
x=[0:0.1:2*%pi]';
//esboo simples
plot(sin(x))
clf()
plot(x,sin(x))
//esboos mltiplos
clf()
plot(x,[sin(x) sin(2*x) sin(3*x)])
clf()

// eixo  direita
plot(x,sin(x)) 
a=gca(); // manipulador da entidade Axes
a.y_location ="right"; 
clf()

// eixo centrado em (0,0)
plot(x-4,sin(x),x+2,cos(x))
a=gca(); // manipulador da entidade Axes
a.x_location = "middle"; 
a.y_location = "middle"; 

// algumas operaes em entidades criadas por plot...
a=gca();
a.isoview='on'; 
a.children // listando os galhos da entidade Axes: aqui,  um galho Compound composto por duas entidades 
poly1= a.children.children(2); //armazenando um manipulador Polyline em poly1
poly1.foreground = 4; // outro modo de se mudar o estilo...
poly1.thickness = 3;  // ...e a espessura de uma curva.
poly1.clip_state='off' // controle de recorte
a.isoview='off'; 

//exemplos com LineSpec e GlobalProperty:
clf();
t=0:%pi/20:2*%pi;
plot(t,sin(t),'ro-.',t,cos(t),'cya+',t,abs(sin(t)),'--mo')
scf(2)
plot([t ;t],[sin(t) ;cos(t)],'xdat',[1:2])
scf(3)
axfig3 = gca();
scf(4) // deveria permanecer em branco
plot(axfig3,[t ;t],[sin(t) ;cos(t)],'zdat',[1:2],'marker','d','markerfac','green','markeredg','yel')
xdel(winsid())

//especificao de dados
t=-%pi:0.1:%pi;
size(t)
plot(t) // esboos simples de y versus tamanho do vetor t
clf(); // limpando figura

plot(t,sin(t)); // esboa sin(t) versus t
clf();

t=[1     1     1     1
   2     3     4     5
   3     4     5     6
   4     5     6     7];

plot(t) // esboa cada coluna t column versus tamanho de linha
clf();

subplot(221)
plot(t,sin(t)); // esboa sin(t) versus t coluna por coluna desta vez
xtitle("sin(t) versus t")
subplot(222)
plot(t,sin(t)')
xtitle("sin(t)'' versus t")
subplot(223)
plot(t',sin(t))
a=gca();
a.data_bounds=[0 -1;7 1]; // para ver a linha vertical escondida pelo eixo y
xtitle("sin(t) versus t''")
subplot(224)
plot(t',sin(t)')
xtitle("sin(t)'' versus t''")

clf();

//caso especial 1
//x : vector ([5 6 7 8]) and y : matrix (t)
x=[5 6 7 8]
plot(x,t);
plot(x',t); // idem, x  automaiticamente transposto para corresponder a t (aqui as colunas)
clf()

// apenas um caso de possibilidade de correspondncia: como realizar quatro esboos idnticos 4 de quatro maneiras 4...
// x  um vetor 1x4 (vector) y is uma matriz no-quadrada 4x5
subplot(221);
plot(x,[t [8;9;10;12]]');
subplot(222);
plot(x',[t [8;9;10;12]]');
subplot(223);
plot(x,[t [8;9;10;12]]');
subplot(224);
plot(x',[t [8;9;10;12]]');
clf()

//caso especial 2
// caso onde apenas x ou y  uma matriz quadrada
//x : matrix (t) e y  : vetor ([1 2 3 4])
plot(t,[1 2 3 4]) // equivalente a plot(t,[1 1 1 1;2 2 2 2;3 3 3 3;4 4 4 4])
plot(t,[1;2;3;4]) // o mesmo esboo
clf();

// t  transposto: note a prioridade dada ao tratamento das colunas
plot(t',[1 2 3 4]) // equivalente a plot(t',[1 1 1 1;2 2 2 2;3 3 3 3;4 4 4 4])
plot(t',[1 2 3 4]') // o mesmo esboo
clf();

// y  uma funo definida por...
// ..uma primitiva
plot(1:0.1:10,sin) // equivalente a plot(1:0.1:10,sin(1:0.1:10))
clf();

// ...uma macro:
deff('[y]=toto(x)','y=x.*x')
plot(1:10,toto)
 ]]></programlisting>
  </refsection>

  <refsection>
    <title>Ver Tambm</title>

    <simplelist type="inline">
      <member><link linkend="plot2d">plot2d</link></member>

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

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

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

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

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

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

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

  <refsection>
    <title>Autor</title>

    <para>F.Leray</para>
  </refsection>
</refentry>