Help reformat: use docbook elements
[scilab.git] / scilab / modules / graphics / help / pt_BR / 2d_plot / plot.xml
1 <?xml version="1.0" encoding="ISO-8859-1"?>
2 <!--
3  * Scilab ( http://www.scilab.org/ ) - This file is part of Scilab
4  * Copyright (C) INRIA - Fabrice Leray
5  * Copyright (C) 2018 - Samuel GOUGEON
6  *
7  * Copyright (C) 2012 - 2016 - Scilab Enterprises
8  *
9  * This file is hereby licensed under the terms of the GNU GPL v2.0,
10  * pursuant to article 5.3.4 of the CeCILL v.2.1.
11  * This file was originally licensed under the terms of the CeCILL v2.1,
12  * and continues to be available under such terms.
13  * For more information, see the COPYING file which you should have received
14  * along with this program.
15  *
16  -->
17 <refentry xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink"
18           xmlns:svg="http://www.w3.org/2000/svg" xmlns:ns4="http://www.w3.org/1999/xhtml"
19           xmlns:mml="http://www.w3.org/1998/Math/MathML" xmlns:db="http://docbook.org/ns/docbook"
20           xmlns:scilab="http://www.scilab.org" xml:id="plot" xml:lang="pt">
21     <refnamediv>
22         <refname>plot</refname>
23         <refpurpose>Esboço 2d</refpurpose>
24     </refnamediv>
25     <refsynopsisdiv>
26         <title>Seqüência de Chamamento</title>
27         <synopsis>
28             plot     // demo
29             plot(y)
30             plot(x, y)
31             plot(x, fun)
32             plot(.., LineSpec)
33             plot(.., LineSpec, GlobalProperty)
34             plot(x1,y1,LineSpec1, x2,y2,LineSpec2,...xN,yN,LineSpecN, GlobalProperty1, GlobalProperty2,..GlobalPropertyM)
35             plot(axes_handle,...)
36         </synopsis>
37     </refsynopsisdiv>
38     <refsection role="parameters">
39         <title>Parâmetros</title>
40         <variablelist>
41             <varlistentry>
42                 <term>x</term>
43                 <listitem>
44                     <para>uma matriz ou vetor de reais. Se omitido, é assumido como
45                         sendo o vetor <literal>1:n</literal> onde <literal>n</literal> é o
46                         número de pontos de curva dado pelo parâmetro
47                         <literal>y</literal>.
48                     </para>
49                 </listitem>
50             </varlistentry>
51             <varlistentry>
52                 <term>y</term>
53                 <listitem>
54                     <para>
55                         uma matriz de reais ou um vetor.
56                     </para>
57                 </listitem>
58             </varlistentry>
59             <varlistentry>
60                 <term>fun</term>
61                 <listitem>
62                     <para>
63                         função definida como um macro ou uma primitiva, como em
64                         <literal>plot(x, sin)</literal>
65                     </para>
66                 </listitem>
67             </varlistentry>
68             <varlistentry>
69                 <term>LineSpec</term>
70                 <listitem>
71                     <para>este argumento opcional deve ser usado como um atalho para
72                         especificar um modo de desenhar uma linha. Podemos ter um
73                         <literal>LineSpec</literal> por<literal> y</literal> ou
74                         <literal>{x,y}</literal> previamente entrados. As opções
75                         <literal>LineSpec</literal> lidam com os especificadores LineStyle,
76                         Marker e Color (ver <link linkend="LineSpec">LineSpec</link>). Estes
77                         especificadores determinam o estilo de linha, de marcas e a cor das
78                         linhas esboçadas.
79                     </para>
80                 </listitem>
81             </varlistentry>
82             <varlistentry>
83                 <term>GlobalProperty</term>
84                 <listitem>
85                     <para>este argumento opcional representa uma seqüência de pares de
86                         declarações <literal>{PropertyName,PropertyValue}</literal> tque
87                         define propriedades globais de objetos a serem aplicadas a todas as
88                         curvas criadas pelo esboço. Para uma visualização completa de das
89                         propriedades disponíveis veja <link linkend="GlobalProperty">GlobalProperty</link>.
90                     </para>
91                 </listitem>
92             </varlistentry>
93             <varlistentry>
94                 <term>&lt;axes_handle&gt;</term>
95                 <listitem>
96                     <para>este argumento opcional força o esboço a aparecer dentro dos
97                         eixos selecionados fornecidos por <literal>axes_handle</literal> ao
98                         invés dos eixos correntes (ver <link linkend="gca">gca</link>).
99                     </para>
100                 </listitem>
101             </varlistentry>
102         </variablelist>
103     </refsection>
104     <refsection role="description">
105         <title>Descrição</title>
106         <para>
107             <literal>plot</literal> esboça um conjunto de curvas 2d.
108             <literal>plot</literal> foi reconstruído para lidar melhor com a sintaxe
109             do Matlab. Para melhorar a compatibilidade gráfica com o Matlab, utilize
110             <literal>plot</literal> (ao invés de <link linkend="plot2d">plot2d</link>).
111         </para>
112         <para>Especificação de entrada de dados:</para>
113         <para>Neste parágrafo, para sermos mais claros, não mencionaremos os
114             argumentos opcionais <literal>LineSpec</literal> ou
115             <literal>GlobalProperty</literal> já que eles não interferem na entrada de
116             dados (exceto pelas propriedades <literal>"Xdata"</literal>,
117             <literal>"Ydata"</literal> e <literal>"Zdata"</literal>, ver <link linkend="GlobalProperty">GlobalProperty</link>). É assumido que todos
118             estes argumentos podem estar presentes também.
119         </para>
120         <para>
121             Se <literal>y</literal> é um vetor, plot(y) esboça um vetor
122             <literal>y</literal> versus o vetor
123             <literal>1:size(y,'*')</literal>.
124         </para>
125         <para>
126             Se <literal>y</literal> é uma matriz, plot(y) esboça cada coluna de
127             <literal>y</literal> versus o vetor <literal>1:size(y,1)</literal>.
128         </para>
129         <para>
130             Se <literal>x</literal> e <literal>y</literal> são vetores,
131             plot(x,y) esboça o vetor <literal>y</literal> versus o vetor
132             <literal>x</literal>. Os vetores <literal>x</literal> e
133             <literal>y</literal> devem ter o mesmo número de entradas.
134         </para>
135         <para>
136             Se <literal>x</literal> é um vetor e <literal>y</literal> uma matriz
137             plot(x,y) esboça cada coluna de <literal>y</literal> versus o vetor
138             <literal>x</literal>. Neste caso, o número de colunas de
139             <literal>y</literal> deve ser igual ao número de entradas de
140             <literal>x</literal>.
141         </para>
142         <para>
143             Se <literal>x</literal> e <literal>y</literal> são matrizes,
144             plot(x,y) esboça cada coluna de <literal>y</literal> versus a coluna
145             correspondente de <literal>x</literal>. Neste caso, os tamanhos
146             <literal>x</literal> e <literal>y</literal> devem ser os mesmos.
147         </para>
148         <para>
149             Finalmente, se apenas <literal>x</literal> ou <literal>y</literal> é
150             uma matriz, o vetor é esboçado versus cada linha ou cada coluna da matriz.
151             A escolha é feita dependendo se a dimensão de linha ou coluna do vetor
152             coincide com a dimensão de linha ou coluna da matriz. No caso de uma
153             matriz quadrada (apenas <literal>x</literal> ou penas
154             <literal>y</literal>), a prioridade é dada a colunas ao invés de linhas
155             (ver exemplos abaixo).
156         </para>
157         <para>
158             <literal>y</literal> também pode ser uma função definida como um
159             macro ou uma primitiva. Neste caso, os dados <literal>x</literal> devem
160             ser fornecidos (como um vetor ou uma matriz) e a computação correspondente
161             de <literal>y(x)</literal> é feita implicitamente.
162         </para>
163         <para>
164             Os argumentos <literal>LineSpec</literal> e
165             <literal>GlobalProperty</literal> devem ser utilizados para customizar o
166             esboço. Aqui está uma lista completa das opções disponíveis.
167         </para>
168         <variablelist>
169             <varlistentry>
170                 <term>LineSpec</term>
171                 <listitem>
172                     <para>esta opção pode ser utilizada para se especificar, de um modo
173                         curto e fácil, como as curvas são desenhadas. Deve sempre ser um
174                         string contendo referências aos especificadores LineStyle, Marker e
175                         Color.
176                     </para>
177                     <para>Essas referências devem ser ajustadas denro do string (a ordem
178                         não é importante) de modo a não ter ambigüidades. Por exemplo, para
179                         especificar uma linha vermelha de traço longo com marcas de rombos,
180                         pode-se escrever : <literal>'r--d'</literal> ou
181                         <literal>'--dire'</literal> ou <literal>'--reddiam'</literal> ou
182                         outra sentença sem ambigüidade... ou de modo completo
183                         <literal>'diamondred--'</literal> (ver <link linkend="LineSpec">LineSpec</link>).
184                     </para>
185                     <para>Note que os estilos de linha e marcas (e tamanhos) e as cores,
186                         podem ser (re*)ajustados através das propriedades da entidade
187                         poligonal (ver <link linkend="polyline_properties">polyline_properties</link>).
188                     </para>
189                 </listitem>
190             </varlistentry>
191             <varlistentry>
192                 <term>GlobalProperty</term>
193                 <listitem>
194                     <para>esta opção pode ser utilizada para especificar como as linhas
195                         serão desenhadas com mais opções que via
196                         <literal>LineSpec</literal>. Deve sempre ser um par de declarações
197                         constituidos de um string definindo <literal>PropertyName</literal>,
198                         (nome da propriedade) e seu valor associado
199                         <literal>PropertyValue</literal> (que pode ser um string, um inteiro
200                         ou qualquer outra coisa... dependendo do tipo de
201                         <literal>PropertyName</literal>). Utilizando-se
202                         <literal>GlobalProperty</literal>, pode-se ajustar várias
203                         propriedades : todas as propriedades disponíveis via LineSpec e
204                         mais: a cor da marca (plano de fundo e primeiro plano), a
205                         visibilidade, o recorte e a espessura das curvas. (ver <link linkend="GlobalProperty">GlobalProperty</link>)
206                     </para>
207                     <para>Note que todas as propriedades podem ser (re-)ajustadas
208                         através das propriedades de entidades poligonais (ver <link linkend="polyline_properties">polyline_properties</link>).
209                     </para>
210                 </listitem>
211             </varlistentry>
212         </variablelist>
213     </refsection>
214     <refsection role="description">
215         <title>Observações </title>
216         <para>Por padrão, esboços sucessivos são superpostos. Para limpar o esboço
217             anterior, use <literal>clf()</literal>. Para habilitar o modo
218             <literal>auto_clear</literal> (limpeza automática) como modo padrão, edite
219             seus eixos fazendo o seguinte:
220         </para>
221         <para>da=gda();</para>
222         <para>da.auto_clear = 'on'</para>
223         <para>
224             Para uma melhor exibição, a função <literal>plot</literal> pode
225             modificar a propriedade <literal>box</literal> de seu Axes (eixos) raíze.
226             Isto acontece quando uma entidade Axes é criada por uma chamada a
227             <literal>plot</literal> ou é vazia antes da chamada. Se um dos eixos é
228             centrado na origem, box é desabilitado. Em caso contrário, box é
229             habilitado.
230         </para>
231         <para>Para mais informações sobre a propriedade box e sobre o
232             posicionamento dos eixos, veja <link linkend="axes_properties">axes_properties</link>
233         </para>
234         <para>Uma tabela de cores padrão é utilizada para colorir as curvas
235             esboçadas quando você não especifica as cores. Ao desenhar linhas
236             múltiplas, o comando plot automaticamente atribui as cores abaixo de modo
237             cíclico. Aqui estão as cores utilizadas:
238         </para>
239         <informaltable border="1">
240             <tr>
241                 <td>
242                     <literal>R</literal>
243                 </td>
244                 <td>
245                     <literal>G</literal>
246                 </td>
247                 <td>
248                     <literal>B</literal>
249                 </td>
250             </tr>
251             <tr>
252                 <td>0.</td>
253                 <td>0.</td>
254                 <td>1.</td>
255             </tr>
256             <tr>
257                 <td>0.</td>
258                 <td>0.5</td>
259                 <td>0.</td>
260             </tr>
261             <tr>
262                 <td>1.</td>
263                 <td>0.</td>
264                 <td>0.</td>
265             </tr>
266             <tr>
267                 <td>0.</td>
268                 <td>0.75</td>
269                 <td>0.75</td>
270             </tr>
271             <tr>
272                 <td>0.75</td>
273                 <td>0.</td>
274                 <td>0.75</td>
275             </tr>
276             <tr>
277                 <td>0.75</td>
278                 <td>0.75</td>
279                 <td>0.</td>
280             </tr>
281             <tr>
282                 <td>0.25</td>
283                 <td>0.25</td>
284                 <td>0.25</td>
285             </tr>
286         </informaltable>
287         <para/>
288         <para>
289             Entre com o comando <literal>plot</literal> para visualizar uma
290             demonstração.
291         </para>
292     </refsection>
293     <refsection role="examples">
294         <title>Exemplos</title>
295         <programlisting role="example"><![CDATA[
296 // inicialização de x
297 x=[0:0.1:2*%pi]';
298 //esboço simples
299 plot(sin(x))
300 clf()
301 plot(x,sin(x))
302 //esboços múltiplos
303 clf()
304 plot(x,[sin(x) sin(2*x) sin(3*x)])
305 clf()
306
307 // eixo à direita
308 plot(x,sin(x))
309 a=gca(); // manipulador da entidade Axes
310 a.y_location ="right";
311 clf()
312
313 // eixo centrado em (0,0)
314 plot(x-4,sin(x),x+2,cos(x))
315 a=gca(); // manipulador da entidade Axes
316 a.x_location = "middle";
317 a.y_location = "middle";
318
319 // algumas operações em entidades criadas por plot...
320 isoview()
321 a=gca();
322 a.children // listando os galhos da entidade Axes: aqui, é um galho Compound composto por duas entidades
323 poly1= a.children.children(2); //armazenando um manipulador Polyline em poly1
324 poly1.foreground = 4; // outro modo de se mudar o estilo...
325 poly1.thickness = 3;  // ...e a espessura de uma curva.
326 poly1.clip_state='off' // controle de recorte
327 isoview("off")
328
329 //exemplos com LineSpec e GlobalProperty:
330 clf();
331 t=0:%pi/20:2*%pi;
332 plot(t,sin(t),'ro-.',t,cos(t),'cya+',t,abs(sin(t)),'--mo')
333 scf(2)
334 plot([t ;t],[sin(t) ;cos(t)],'xdat',[1:2])
335 scf(3)
336 axfig3 = gca();
337 scf(4) // deveria permanecer em branco
338 plot(axfig3,[t ;t],[sin(t) ;cos(t)],'zdat',[1:2],'marker','d','markerfac','green','markeredg','yel')
339 xdel(winsid())
340
341 //especificação de dados
342 t=-%pi:0.1:%pi;
343 size(t)
344 plot(t) // esboços simples de y versus tamanho do vetor t
345 clf(); // limpando figura
346
347 plot(t,sin(t)); // esboça sin(t) versus t
348 clf();
349
350 t=[1     1     1     1
351    2     3     4     5
352    3     4     5     6
353    4     5     6     7];
354
355 plot(t) // esboça cada coluna t column versus tamanho de linha
356 clf();
357
358 subplot(221)
359 plot(t,sin(t)); // esboça sin(t) versus t coluna por coluna desta vez
360 xtitle("sin(t) versus t")
361 subplot(222)
362 plot(t,sin(t)')
363 xtitle("sin(t)'' versus t")
364 subplot(223)
365 plot(t',sin(t))
366 a=gca();
367 a.data_bounds=[0 -1;7 1]; // para ver a linha vertical escondida pelo eixo y
368 xtitle("sin(t) versus t''")
369 subplot(224)
370 plot(t',sin(t)')
371 xtitle("sin(t)'' versus t''")
372
373 clf();
374
375 //caso especial 1
376 //x : vector ([5 6 7 8]) and y : matrix (t)
377 x=[5 6 7 8]
378 plot(x,t);
379 plot(x',t); // idem, x é automaiticamente transposto para corresponder a t (aqui as colunas)
380 clf()
381
382 // apenas um caso de possibilidade de correspondência: como realizar quatro esboços idênticos 4 de quatro maneiras 4...
383 // x é um vetor 1x4 (vector) y is uma matriz não-quadrada 4x5
384 subplot(221);
385 plot(x,[t [8;9;10;12]]');
386 subplot(222);
387 plot(x',[t [8;9;10;12]]');
388 subplot(223);
389 plot(x,[t [8;9;10;12]]');
390 subplot(224);
391 plot(x',[t [8;9;10;12]]');
392 clf()
393
394 //caso especial 2
395 // caso onde apenas x ou y é uma matriz quadrada
396 //x : matrix (t) e y  : vetor ([1 2 3 4])
397 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])
398 plot(t,[1;2;3;4]) // o mesmo esboço
399 clf();
400
401 // t é transposto: note a prioridade dada ao tratamento das colunas
402 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])
403 plot(t',[1 2 3 4]') // o mesmo esboço
404 clf();
405
406 // y é uma função definida por...
407 // ..uma primitiva
408 plot(1:0.1:10,sin) // equivalente a plot(1:0.1:10,sin(1:0.1:10))
409 clf();
410
411 // ...uma macro:
412 deff('[y]=toto(x)','y=x.*x')
413 plot(1:10,toto)
414  ]]></programlisting>
415     </refsection>
416     <refsection role="see also">
417         <title>Ver Também</title>
418         <simplelist type="inline">
419             <member>
420                 <link linkend="plot2d">plot2d</link>
421             </member>
422             <member>
423                 <link linkend="surf">surf</link>
424             </member>
425             <member>
426                 <link linkend="scf">scf</link>
427             </member>
428             <member>
429                 <link linkend="clf">clf</link>
430             </member>
431             <member>
432                 <link linkend="xdel">xdel</link>
433             </member>
434             <member>
435                 <link linkend="delete">delete</link>
436             </member>
437             <member>
438                 <link linkend="LineSpec">LineSpec</link>
439             </member>
440             <member>
441                 <link linkend="color_list">Cores nomeadas</link>
442             </member>
443             <member>
444                 <link linkend="GlobalProperty">GlobalProperty</link>
445             </member>
446         </simplelist>
447     </refsection>
448     <refsection role="history">
449         <title>Histórico</title>
450         <revhistory>
451             <revision>
452                 <revnumber>6.0.1</revnumber>
453                 <revdescription>
454                     The "color"|"foreground", "markForeground", and "markBackground" GlobalProperty
455                     colors can now be chosen among the full predefined colors list, or by
456                     their "#RRGGBB" hexadecimal codes, or by their indices in the colormap.
457                 </revdescription>
458             </revision>
459         </revhistory>
460     </refsection>
461 </refentry>