<?xml version="1.0" encoding="UTF-8"?>
<!--
 * Scilab ( http://www.scilab.org/ ) - This file is part of Scilab
 * Copyright (C) 2008 - INRIA - Farid BELAHCENE
 * Copyright (C) 2012 - 2016 - Scilab Enterprises
 * Copyright (C) 2020 - Samuel GOUGEON
 *
 * 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: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="meshgrid" xml:lang="en">
    <refnamediv>
        <refname>meshgrid</refname>
        <refpurpose>
            Create matrices or 3-D arrays from vectors replicated in 2 or 3 dimensions
        </refpurpose>
    </refnamediv>
    <refsynopsisdiv>
        <title>Syntax</title>
        <synopsis>
            U = meshgrid(u)
            [U, V] = meshgrid(u)
            [X, Y] = meshgrid(x, y)
            [X, Y, Z] = meshgrid(x, y, z)
        </synopsis>
    </refsynopsisdiv>
    <refsection>
        <title>Arguments</title>
        <variablelist>
            <varlistentry>
                <term>u, x, y, z</term>
                <listitem>
                    Vectors of any types, of lengths nu, nx, ny, nz.
                    <para/>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>U, V</term>
                <listitem>
                    Square matrices of size nu x nu
                    <para/>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>X, Y, Z</term>
                <listitem>
                    Matrices or hypermatrices of the same size
                    [<emphasis role="bold">ny</emphasis>, nx] or
                    [<emphasis role="bold">ny</emphasis>, nx, nz].
                    <para/>
                </listitem>
            </varlistentry>
        </variablelist>
    </refsection>
    <refsection>
        <title>Description</title>
        <para>
            meshgrid(..) builds matrices or 3-D hypermatrices by replicating input vectors
            along 2 or 3 dimensions.
        </para>
        <para>
            <note>
                To create arrays of size [<emphasis role="bold">nx</emphasis>, ny] instead of
                [ny, nx], or with more than 3 dimensions, please use
                <literal>ndgrid(x, y)</literal> or <literal>ndgrid(x, y, z,..)</literal>.
            </note>
        </para>
        <para>
            <warning>
                Most of Scilab 2D or 3D graphical functions like <literal>champ()</literal>,
                <literal>grayplot()</literal>, <literal>Sgrayplot()</literal>,
                <literal>plot3d()</literal>, <literal>contour()</literal>, etc.. work with grids
                generated with <literal>ndgrid()</literal>, not from
                <literal>meshgrid()</literal>. Data computed on grids coming from
                <literal>meshgrid()</literal> will require being transposed (please see the
                example thereafter).
            </warning>
        </para>
    </refsection>
    <refsection>
        <title>Examples</title>
        <programlisting role="example"><![CDATA[
[X, Y] = meshgrid(0:2)
 ]]></programlisting>
    <screen>
--> [X, Y] = meshgrid(0:2)
 X  =
   0.   1.   2.
   0.   1.   2.
   0.   1.   2.

 Y  =
   0.   0.   0.
   1.   1.   1.
   2.   2.   2.
</screen>
        <para/>
        <programlisting role="example"><![CDATA[
[X, Y] = meshgrid(["a" "bc" "αβγδ"], [-3 5])
 ]]></programlisting>
    <screen>
--> [X, Y] = meshgrid(["a" "bc" "αβγδ"], [-3 5])
 X  =
!a  bc  αβγδ  !
!a  bc  αβγδ  !

 Y  =
  -3.  -3.  -3.
   5.   5.   5.
</screen>
        <para/>
        <para>
            Application to grids for graphics:
        </para>
        <programlisting role="example"><![CDATA[
// Generating data
x = -1:0.1:1.7;
y = -1:0.1:1;
[X, Y] = meshgrid(x, y);
Z = sinc(2*%pi * X.*Y);

// Setting the graphic figure
clf
drawlater
gcf().color_map = parulacolormap(64);
gcf().axes_size = [650 530];

// Plotting
subplot(2,2,1)
Sgrayplot(x, y, Z')
title(["Sgrayplot(x, y, Z'' ) " "$←\;Z^t\; required$"], "fontsize",3)
isoview, colorbar

subplot(2,2,2)
plot3d(x, y, Z', -125,50)
gce().color_flag = 1;
title(["plot3d(x, y, Z'' ) " "$←\;Z^t\; required$"], "fontsize",3)
isoview

subplot(2,2,3)
champ(x,y,sin(2*X'),cos(2*Y'))
title(["champ(x, y, sin(X'' ),cos(Y'' ))" "$←\;X^t\;\;Y^t\; required$"], "fontsize",3)
isoview

subplot(2,2,4)
surf(X, Y, Z)
title("surf(X, Y, Z)", "fontsize",3)
isoview

gcf().children.tight_limits = ["on" "on" "on"];
drawnow
 ]]></programlisting>
        <para/>
        <scilab:image>
            // Generating data
            x = -1:0.1:1.7;
            y = -1:0.1:1;
            [X, Y] = meshgrid(x, y);
            Z = sinc(2*%pi * X.*Y);

            // Setting the graphic figure
            clf
            drawlater
            gcf().color_map = parulacolormap(64);
            gcf().axes_size = [650 530];

            // Plotting
            subplot(2,2,1)
            Sgrayplot(x, y, Z')
            title(["Sgrayplot(x, y, Z'' ) " "$←\;Z^t\; required$"], "fontsize",3)
            isoview, colorbar

            subplot(2,2,2)
            plot3d(x, y, Z', -125,50)
            gce().color_flag = 1;
            title(["plot3d(x, y, Z'' ) " "$←\;Z^t\; required$"], "fontsize",3)
            isoview

            subplot(2,2,3)
            champ(x,y,sin(2*X'),cos(2*Y'))
            title(["champ(x, y, sin(X'' ),cos(Y'' ))" "$←\;X^t\;\;Y^t\; required$"], "fontsize",3)
            isoview

            subplot(2,2,4)
            surf(X, Y, Z)
            title("surf(X, Y, Z)", "fontsize",3)
            isoview

            gcf().children.tight_limits = ["on" "on" "on"];
            drawnow
        </scilab:image>
    </refsection>
    <refsection role="see also">
        <title>See also</title>
        <simplelist type="inline">
            <member>
                <link linkend="ndgrid">ndgrid</link>
            </member>
            <member>
                <link linkend="repmat">repmat</link>
            </member>
            <member>
                <link linkend="feval">feval</link>
            </member>
        </simplelist>
    </refsection>
</refentry>
