<?xml version="1.0" encoding="UTF-8"?>
<!--
 * Scilab ( https://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:mml="http://www.w3.org/1998/Math/MathML" xmlns:db="http://docbook.org/ns/docbook" xmlns:scilab="http://www.scilab.org"  xml:lang="en" xml:id="geom3d">
    <refnamediv>
        <refname>geom3d</refname>
        <refpurpose>projection from 3D on 2D after a 3D
            plot
        </refpurpose>
    </refnamediv>
    <refsynopsisdiv>
        <title>Syntax</title>
        <synopsis>[x,y]=geom3d(x1,y1,z1)</synopsis>
    </refsynopsisdiv>
    <refsection>
        <title>Arguments</title>
        <variablelist>
            <varlistentry>
                <term>x1,y1,z1</term>
                <listitem>
                    <para>real vectors of the same size (points in 3D).</para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>x,y</term>
                <listitem>
                    <para>
                        real vectors of the same size as <literal>x1</literal>,
                        <literal>y1</literal> and <literal>z1</literal>.
                    </para>
                </listitem>
            </varlistentry>
        </variablelist>
    </refsection>
    <refsection>
        <title>Description</title>
        <para>
            After having used a 3D plot function such as <literal>plot3d</literal>,
            <literal>plot3d1</literal> or <literal>param3d</literal>, <literal>geom3d</literal> gives
            the mapping between a point in 3D space <literal>(x1(i),y1(i),z1(i))</literal>
            and the corresponding point <literal>(x(i),y(i))</literal> in the projected 2D
            plan. Then all the 2D graphics primitives working on <literal>(x,y)</literal>
            can be used for superposition on the 3D plot.
        </para>
    </refsection>
    <refsection>
        <title>Examples</title>
        <programlisting role="example"><![CDATA[
deff("[z]=surface(x,y)","z=sin(x)*cos(y)")
t=%pi*(-10:10)/10;
// 3D plot of the surface
fplot3d(t,t,surface,35,45,"X@Y@Z")
// now (t,t,sin(t).*cos(t)) is a curve on the surface
// which can be drawn using geom3d and xpoly
[x,y]=geom3d(%pi/2,0,surface(%pi/2,0))
 ]]></programlisting>
        <scilab:image>deff("[z]=surface(x,y)","z=sin(x)*cos(y)")
            t=%pi*(-10:10)/10;
            fplot3d(t,t,surface,35,45,"X@Y@Z")
            [x,y]=geom3d(%pi/2,0,surface(%pi/2,0))
        </scilab:image>


        <programlisting role="example"><![CDATA[

my_plot_desc          = "plot3d and use of geom3d";

  r = (%pi):-0.01:0;
x = r.*cos(10*r);
y = r.*sin(10*r);

deff("[z]=Surf(x,y)","z=sin(x)*cos(y)");
t=%pi*(-10:10)/10;

// Plot the surface'
fplot3d(t,t,Surf,35,45,"X@Y@Z",[19,2,3]);

// Add 2d graphics on 3d graphic'
z=(sin(x).*cos(y));
[x1,y1] = geom3d(x,y,z);
xpoly(x1,y1,"lines");

// Adjust some plotting parameters'
BackgroundColorId           = color(70,174,255);
current_axe                 = gca();
plot_3d                     = current_axe.children(2);
plot_3d.hiddencolor         = 32;
polyline                    = current_axe.children(1)';;
polyline.foreground         = 8;
current_axe.rotation_angles = [70,47];
current_axe.background      = BackgroundColorId;

// A second 2d graphics'
[x1,y1] = geom3d([0,0],[0,0],[5,0]);
xsegs(x1,y1);
xstring(x1(1),y1(1),"The point (0,0,0)");

xtitle(my_plot_desc," "," "," ");

 ]]></programlisting>
        <scilab:image>

            my_plot_desc          = "plot3d and use of geom3d";

            r = (%pi):-0.01:0;
            x = r.*cos(10*r);
            y = r.*sin(10*r);

            deff("[z]=Surf(x,y)","z=sin(x)*cos(y)");
            t=%pi*(-10:10)/10;

            // Plot the surface'
            fplot3d(t,t,Surf,35,45,"X@Y@Z",[19,2,3]);

            // Add 2d graphics on 3d graphic'
            z=(sin(x).*cos(y));
            [x1,y1] = geom3d(x,y,z);
            xpoly(x1,y1,"lines");

            // Adjust some plotting parameters'
            BackgroundColorId           = color(70,174,255);
            current_axe                 = gca();
            plot_3d                     = current_axe.children(2);
            plot_3d.hiddencolor         = 32;
            polyline                    = current_axe.children(1)';;
            polyline.foreground         = 8;
            current_axe.rotation_angles = [70,47];
            current_axe.background      = BackgroundColorId;

            // A second 2d graphics'
            [x1,y1] = geom3d([0,0],[0,0],[5,0]);
            xsegs(x1,y1);
            xstring(x1(1),y1(1),"The point (0,0,0)");

            xtitle(my_plot_desc," "," "," ");
        </scilab:image>
    </refsection>
</refentry>
