<?xml version="1.0" encoding="UTF-8"?>
<refentry xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink"
          xmlns:svg="http://www.w3.org/2000/svg" xmlns:ns5="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="linear_interpn" xml:lang="pt">
    <refnamediv>
        <refname>linear_interpn</refname>
        <refpurpose>interpolação linear n-dimensional</refpurpose>
    </refnamediv>
    <refsynopsisdiv>
        <title>Seqüência de Chamamento</title>
        <synopsis>
            vp = linear_interpn(xp1,xp2,..,xpn, x1,...,xn, v)
            vp = linear_interpn(xp1,xp2,..,xpn, x1,...,xn, v, out_mode)
        </synopsis>
    </refsynopsisdiv>
    <refsection>
        <title>Parâmetros</title>
        <variablelist>
            <varlistentry>
                <term>xp1, xp2, .., xpn</term>
                <listitem>
                    <para>vetores de reais (ou matrizes) de mesmo tamanho </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>x1 ,x2, ..., xn</term>
                <listitem>
                    <para> vetores linhas estritamente crescentes (com pelo menos 2
                        elementos) definindo o grid de interpolação n-dimensional
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>v</term>
                <listitem>
                    <para>vetor (caso n=1), matriz (caso n=2) ou hipermatriz (caso n
                        &gt; 2) com valores da função subjacente interpolada nos pontos do
                        grid.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>out_mode</term>
                <listitem>
                    <para>(opcional) string definindo a avaliação fora do grid
                        (extrapolação)
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>vp</term>
                <listitem>
                    <para>
                        vetor ou matriz de mesmo tamanho que <literal>xp1, ...,
                            xpn
                        </literal>
                    </para>
                </listitem>
            </varlistentry>
        </variablelist>
    </refsection>
    <refsection>
        <title>Descrição</title>
        <para>
            Dado um grid n-dimensional definido pelos n vetores <literal>x1 ,x2,
                ..., xn
            </literal>
            eos valores <literal>v</literal> de uma função (aqui
            nomeada <emphasis>f</emphasis>) nos pontos do grid :
        </para>
        <para>
            <table align="center">
            <tr><td>
                    v(i<subscript>1</subscript>,
                      i<subscript>2</subscript>,…,
                      i<subscript>n</subscript>) =
                      <emphasis>f</emphasis>(x1(i<subscript>1</subscript>),
                                             x2(i<subscript>2</subscript>),…,
                                             xn(i<subscript>n</subscript>))
                </td>
            </tr>
            </table>
        </para>
        <para>
            esta função computa o interpolante linear de <emphasis>f</emphasis>
            do grid (chamado de s a partir daqui) nos pontos nos quais as coordenadas
            são definidas pelos vetores (ou matrizes) <literal>xp1, xp2, ...,
                xpn
            </literal>
            :
        </para>
        <para>
            <table align="center">
            <tr align="center">
                <td>vp(i) = <emphasis>s</emphasis>(xp1(i), xp2(i), …, xpn(i))</td></tr>
            <tr align="center"><td>or</td></tr>
            <tr align="center">
                <td>vp(i,j) = <emphasis>s</emphasis>(xp1(i,j), xp2(i,j), …, xpn(i,j))</td>
            </tr>
            </table>
            caso xpk sejam matrizes.
        </para>
        <para>
            O parâmetro <literal>out_mode</literal> ajusta a regra para
            extrapolação: se notarmos
            <emphasis>Pi=(xp1(i),xp2(i),...,xpn(i))</emphasis> , então
            <literal>out_mode</literal> define a regra de avaliação quando:
        </para>
        <para>
            <table align="center">
            <tr><td>P(i) ∉ [x1(1), x1($)] × [x2(1), x2($)] × … × [xn(1), xn($)]</td></tr>
            </table>
        </para>
        <para>As escolhas são: </para>
        <variablelist>
            <varlistentry>
                <term>"by_zero"</term>
                <listitem>
                    <para>uma extrapolação por zero é feita </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>"by_nan"</term>
                <listitem>
                    <para>uma extrapolação por NaN </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>"C0"</term>
                <listitem>
                    <para>a extrapolação é definida como segue: </para>
                    <programlisting role=""><![CDATA[
s(P) = s(proj(P)) onde  proj(P) é o ponto mais próximo de P
                  localizado na fronteira do grid.
 ]]></programlisting>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>"natural"</term>
                <listitem>
                    <para>a extrapolação é feita usando o remendo n-linear mais próximo
                        do ponto.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>"periodic"</term>
                <listitem>
                    <para>
                        <literal>s</literal> é estendido por periodicidade.
                    </para>
                </listitem>
            </varlistentry>
        </variablelist>
    </refsection>
    <refsection>
        <title>Exemplos </title>
        <programlisting role="example"><![CDATA[
// exemplo 1 : interpolação linear 1d
x = linspace(0,2*%pi,11);
y = sin(x);
xx = linspace(-2*%pi,4*%pi,400)';
yy = linear_interpn(xx, x, y, "periodic");
clf()
plot2d(xx,yy,style=2)
plot2d(x,y,style=-9, strf="000")
xtitle("Interpolação linear de sin(x) com 11 pontos de interpolação")

// exemplo 2 : interpolação bilinear
n = 8;
x = linspace(0,2*%pi,n); y = x;
z = 2*sin(x')*sin(y);
xx = linspace(0,2*%pi, 40);
[xp,yp] = ndgrid(xx,xx);
zp = linear_interpn(xp,yp, x, y, z);
clf()
plot3d(xx, xx, zp, flag=[2 6 4])
[xg,yg] = ndgrid(x,x);
param3d1(xg,yg, list(z,-9*ones(1,n)), flag=[0 0])
xtitle("Interpolação bilinear de 2sin(x)sin(y)")
legends("pontos de interpolação",-9,1)
show_window()

// exemplo 3 : interpolação bilinear e experimentação
//             com todos os tipos de outmode
nx = 20; ny = 30;
x = linspace(0,1,nx);
y = linspace(0,2, ny);
[X,Y] = ndgrid(x,y);
z = 0.4*cos(2*%pi*X).*cos(%pi*Y);
nxp = 60 ; nyp = 120;
xp = linspace(-0.5,1.5, nxp);
yp = linspace(-0.5,2.5, nyp);
[XP,YP] = ndgrid(xp,yp);
zp1 = linear_interpn(XP, YP, x, y, z, "natural");
zp2 = linear_interpn(XP, YP, x, y, z, "periodic");
zp3 = linear_interpn(XP, YP, x, y, z, "C0");
zp4 = linear_interpn(XP, YP, x, y, z, "by_zero");
zp5 = linear_interpn(XP, YP, x, y, z, "by_nan");
clf()
subplot(2,3,1)
   plot3d(x, y, z, leg="x@y@z", flag = [2 4 4])
   xtitle("função inicial 0.4 cos(2 pi x) cos(pi y)")
subplot(2,3,2)
   plot3d(xp, yp, zp1, leg="x@y@z", flag = [2 4 4])
   xtitle("Natural")
subplot(2,3,3)
   plot3d(xp, yp, zp2, leg="x@y@z", flag = [2 4 4])
   xtitle("Periodic")
subplot(2,3,4)
   plot3d(xp, yp, zp3, leg="x@y@z", flag = [2 4 4])
   xtitle("C0")
subplot(2,3,5)
   plot3d(xp, yp, zp4, leg="x@y@z", flag = [2 4 4])
   xtitle("by_zero")
subplot(2,3,6)
   plot3d(xp, yp, zp5, leg="x@y@z", flag = [2 4 4])
   xtitle("by_nan")
show_window()

// exemplo 4 : interpolação trilinear (ver ajuda de splin3d
//             que tem os mesmos exemplos com
//             interpolação por spline tricúbico)
exec("SCI/modules/interpolation/demos/interp_demo.sci")
func =  "v=(x-0.5).^2 + (y-0.5).^3 + (z-0.5).^2";
deff("v=f(x,y,z)",func);
n = 5;
x = linspace(0,1,n); y=x; z=x;
[X,Y,Z] = ndgrid(x,y,z);
V = f(X,Y,Z);
// computando (e exibindo) o interpolante linear em algumas fatias
m = 41;
dir = ["z="  "z="  "z="  "x="  "y="];
val = [ 0.1   0.5   0.9   0.5   0.5];
ebox = [0 1 0 1 0 1];

XF=[]; YF=[]; ZF=[]; VF=[];
for i = 1:length(val)
   [Xm,Xp,Ym,Yp,Zm,Zp] = slice_parallelepiped(dir(i), val(i), ebox, m, m, m);
   Vm = linear_interpn(Xm,Ym,Zm, x, y, z, V);
   [xf,yf,zf,vf] = nf3dq(Xm,Ym,Zm,Vm,1);
   XF = [XF xf]; YF = [YF yf]; ZF = [ZF zf]; VF = [VF vf];
   Vp =  linear_interpn(Xp,Yp,Zp, x, y, z, V);
   [xf,yf,zf,vf] = nf3dq(Xp,Yp,Zp,Vp,1);
   XF = [XF xf]; YF = [YF yf]; ZF = [ZF zf]; VF = [VF vf];
end
nb_col = 128;
vmin = min(VF); vmax = max(VF);
color = dsearch(VF,linspace(vmin,vmax,nb_col+1));
clf()
gcf().color_map = jet(nb_col);
gca().hiddencolor = gca().background;
colorbar(vmin,vmax)
plot3d(XF, YF, list(ZF,color), flag=[-1 6 4])
xtitle("Interpolação trilinear de"+func)
show_window()
 ]]></programlisting>
    </refsection>
    <refsection role="see also">
        <title>Ver Também</title>
        <simplelist type="inline">
            <member>
                <link linkend="interpln">interpln</link>
            </member>
            <member>
                <link linkend="splin">splin</link>
            </member>
            <member>
                <link linkend="splin2d">splin2d</link>
            </member>
            <member>
                <link linkend="splin3d">splin3d</link>
            </member>
        </simplelist>
    </refsection>
</refentry>
