<?xml version="1.0" encoding="UTF-8"?>
<!--
 * Scilab ( http://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:ns3="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="contour2d" xml:lang="pt">
    <refnamediv>
        <refname>contour2d</refname>
        <refpurpose>curvas de nível de uma superfície em um esboço 2d</refpurpose>
    </refnamediv>
    <refsynopsisdiv>
        <title>Seqüência de Chamamento</title>
        <synopsis>contour2d(x,y,z,nz,[style,strf,leg,rect,nax])
            contour2d(x,y,z,nz,&lt;opt_args&gt;)
        </synopsis>
    </refsynopsisdiv>
    <refsection>
        <title>Parâmetros</title>
        <variablelist>
            <varlistentry>
                <term>x,y</term>
                <listitem>
                    <para>vetores de reais de tamanhos n1 e n2: o grid. </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>z</term>
                <listitem>
                    <para>matriz de reais de tamanho (n1,n2), os valores da função sobre
                        o grid ou uma função Scilab que define uma superfície
                        <literal>z=f(x,y)</literal>.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>nz</term>
                <listitem>
                    <para>os valores de nível ou o número de níveis.</para>
                    <variablelist>
                        <varlistentry>
                            <term/>
                            <listitem>
                                <para>
                                    Se <literal>nz</literal> for um inteiro, seu valor
                                    fornece o número de níveis igualmente espaçados de zmin a zmax
                                    como segue:
                                </para>
                                <programlisting role=""><![CDATA[
z= zmin + (1:nz)*(zmax-zmin)/(nz+1)
 ]]></programlisting>
                                <para>
                                    Note que os níveis <literal>zmin</literal> e
                                    <literal>zmax</literal> não são desenhados (genericamente eles
                                    são reduzidos a pontos) mas podem ser adicionados através
                                    de
                                </para>
                                <programlisting role=""><![CDATA[
[im,jm] = find(z == zmin); // ou zmax
plot2d(x(im)',y(jm)',-9,"000") ]]></programlisting>
                            </listitem>
                        </varlistentry>
                        <varlistentry>
                            <term/>
                            <listitem>
                                <para>
                                    Se <literal>nz</literal> for um vetor,
                                    <literal>nz(i)</literal> fornece o valor da i-ésima curva de
                                    nível.
                                </para>
                            </listitem>
                        </varlistentry>
                    </variablelist>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>&lt;opt_args&gt;</term>
                <listitem>
                    <para>representa uma seqüência de declarações
                        <literal>key1=value1,key2=value2</literal>,... onde
                        <literal>key1</literal>, <literal>key2,...</literal> pode ser um dos
                        seguintes: style, leg, rect, nax, strf ou axesflag e frameflag (ver
                        <link linkend="plot2d">plot2d</link>)
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>style,strf,leg,rect,nax</term>
                <listitem>
                    <para>
                        ver <link linkend="plot2d">plot2d</link>. O argumento
                        <literal>style</literal> fornece os estilos de tracejado ou cores
                        que serão usadas para as curvas de nível. Deve ter o mesmo tamanho
                        que o número de níveis.
                    </para>
                </listitem>
            </varlistentry>
        </variablelist>
    </refsection>
    <refsection>
        <title>Descrição</title>
        <para>
            <literal>contour2d</literal> desenha curvas de nível de uma
            superfície <literal>z=f(x,y)</literal> em um esboço 2d. Os valores de
            <literal>f(x,y)</literal> são dados pela matriz <literal>z</literal> nos
            pontos de grid definidos por por <literal>x</literal> e
            <literal>y</literal>.
        </para>
        <para>Você pode modificar o formato dos pontos flutuantes impressos sobre
            os níveis utilizando <literal>xset("fpf",string)</literal> onde
            <literal>string</literal> fornece o formato em na sintaxe de formato C
            (por exemplo <literal>string="%.3f"</literal>). Use
            <literal>string=""</literal> para voltar ao formato padrão e use
            <literal>string=" "</literal> para suprimir a impressão. Este último
            recurso é útil em conjunção com <link linkend="legends">legends</link>
            para exibir os números de nível em uma legenda e não diretamente em curvas
            de nível como de uso (ver Exemplos).
        </para>
        <para>
            Os argumentos opcionais <literal>style,strf,leg,rect,nax</literal>,
            podem ser passados através de uma seqüência de declarações
            <literal>key1=value1, key2=value2</literal>, ... onde podem ser
            <literal>style</literal>,<literal>strf</literal>,<literal>leg</literal>,<literal>rect</literal>,<literal>nax</literal>.
            Neste caso, a ordem não tem significado especial.
        </para>
        <para>
            Use <literal>contour</literal> para esboçar curvas de nível em uma
            superfície 3d.
        </para>
    </refsection>
    <refsection>
        <title>Exemplos</title>
        <programlisting role="example"><![CDATA[
contour2d(1:10,1:10,rand(10,10),5,rect=[0,0,11,11])
// mudando o formato de impressão dos níveis
xset("fpf","%.2f")
clf()
contour2d(1:10,1:10,rand(10,10),5,rect=[0,0,11,11])

// agora, um exemplo com números de níveis desenhados em uma legenda
// Cuidado, há alguns truques aqui...
x = linspace(0,4*%pi,80);
z = cos(x')*cos(x);
clf(); f=gcf();
xset("fpf"," ")  // truque 1: isto faz com que alguns números de níveis não sejam
                 //          impressos sobre as curvas de nível
f.color_map=jetcolormap(7);
// truque 2: para fazer com que se possa colocar a legenda à direita sem
//          sem interferir com as curvas de nível use rect com um valor xmax
//          grande o suficiente
contour2d(x,x,z,-0.75:0.25:0.75,frameflag=3,rect=[0,0,5*%pi,4*%pi])
// truque 3: use legends (note que a função mais prática legend
//          não funcionará quando um dos níveis for formado por duas curvas)
legends(string(-0.75:0.25:0.75),1:7,"lr");
xtitle("Algumas curvas de nível da função cos(x)cos(y)")
 ]]></programlisting>
    </refsection>
    <refsection>
        <title>Ver Também </title>
        <simplelist type="inline">
            <member>
                <link linkend="contour">contour</link>
            </member>
            <member>
                <link linkend="contour2di">contour2di</link>
            </member>
            <member>
                <link linkend="plot2d">plot2d</link>
            </member>
        </simplelist>
    </refsection>
</refentry>
