<?xml version="1.0" encoding="UTF-8"?>
<!--
 * Scilab ( https://www.scilab.org/ ) - This file is part of Scilab
 * Copyright (C) INRIA - Serge Steer
 * Copyright (C) 2016, 2018 - Samuel GOUGEON
 *
 * 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="isoview">
    <refnamediv>
        <refname>isoview</refname>
        <refpurpose>tunes isometric rendering of graphical axes
        </refpurpose>
    </refnamediv>
    <refsynopsisdiv>
        <title>Syntax</title>
        <synopsis>
            isoview
            isoview on
            isoview off
            isoview(idGraphics)
            isoview(idGraphics,"on"|"off")
        </synopsis>
    </refsynopsisdiv>
    <refsection role="arguments">
        <title>Arguments</title>
        <variablelist>
            <varlistentry>
                <term>"on" | "off" | &lt;none&gt;</term>
                <listitem>
                    Enables or disables or switches the isometric rendering for all considered axes.
                    <para/>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>idGraphics</term>
                <listitem>
                    Vector of graphic handles. All the related axes are processed.
                    By default, the current axes is processed.
                    <para/>
                </listitem>
            </varlistentry>
        </variablelist>
    </refsection>
    <refsection role="description">
        <title>Description</title>
        <para>
            <function>isoview</function> is used to set or relax isometric rendering scales
            on the x, y (and z) axes, without changing the size of the graphic window.
        </para>
        <para>
            <literal>isoview()</literal> or simply <literal>isoview</literal>
            toggles the isoview status of the current axes, and keeps its current
            bounds: isometric scales are set whenever
            they were free, or scales are relaxed whenever they were isometric.
        </para>
        <para>
            <literal>isoview("on")</literal> or <literal>isoview on</literal>
            sets isometric scales for the current axes.
        </para>
        <para>
            <literal>isoview("off")</literal> or <literal>isoview off</literal>
            relaxes x, y (and z)  scales for the current axes.
        </para>
        <para>
            <literal>isoview(idGraphics,..)</literal> runs on axes related
            to each graphic object listed in the vector <varname>idGraphics</varname>:
            <itemizedlist>
                <listitem>
                    If <varname>idGraphics(i)</varname> is a figure's handle,
                    all its Axes are considered.
                </listitem>
                <listitem>
                    If <varname>idGraphics(i)</varname> is an Axes,
                    it is considered as is.
                </listitem>
                <listitem>
                    If <varname>idGraphics(i)</varname> is the handle of a
                    sub-axes component (such as a polyline, a compound, etc),
                    its hosting axes is considered.
                </listitem>
            </itemizedlist>
        </para>
        <note>
            The current axes graphical entity is still the same after calling <literal>isoview(..)</literal>.
        </note>
        <note>To plot some curves directly in isometric mode without calling
            <function>isoview</function> afterwards, the <literal>plot2d(...,frameflag=4)</literal>
            option may be used at call time.
        </note>
        <refsect3>
            <title>Rendering according to .isoview and .cube_scaling settings</title>
            <para>
            <table align="middle">
                <tr>
                    <th>isoview(..)</th><th>gca().isoview</th>
                                       <th>gca().cube_scaling</th>
                                       <td><emphasis role="bold">Rendering</emphasis></td>
                </tr>
                <tr>
                    <th>on</th><td align="center">on</td>
                               <td align="center">off</td>
                               <td>X, Y and Z are isometric</td>
                </tr>
                <tr>
                    <th>off</th><td align="center">off</td>
                                <td align="center">on</td>
                                <td>independent X, Y and Z scales. In 3D, improved aspect ratios when X/Y/Z ranges are very different.</td>
                </tr>
                <tr>
                    <th></th><td align="center">off</td>
                            <td align="center">off</td>
                            <td>Independent X, Y, Z scales. In 3D, rendered X/Y/Z scales ratios are close to the data ones</td>
                </tr>
                <tr>
                    <th></th><td align="center">on</td>
                             <td align="center">on</td>
                             <td>Scales are such that the axes looks square or cubic</td>
                </tr>
            </table>
            </para>
        </refsect3>
    </refsection>
    <refsection role="examples">
        <title>Examples</title>
        <programlisting role="example"><![CDATA[
t = [0:0.1:2*%pi]';
clf
nc = 3;

subplot(2,nc,1)
plot2d(cos(t),sin(t))
xtitle("True circle")
a1 = gca();

subplot(2,nc,nc+1)
plot2d(cos(t),sin(t))
isoview

subplot(2,nc,2)
plot2d(7*cos(t),2*sin(t))
xtitle("True ellipse")
a2 = gca();

subplot(2,nc,nc+2)
plot2d(7*cos(t),2*sin(t))
isoview

// plot of a sphere using facets computed by eval3dp
deff("[x,y,z] = sph(alp,tet)",[
    "x = r*cos(alp).*cos(tet)+orig(1)*ones(tet)"; ..
    "y = r*cos(alp).*sin(tet)+orig(2)*ones(tet)"; ..
    "z = r*sin(alp)+orig(3)*ones(tet)"]);
r = 3; orig = [0 0 0];
[xx,yy,zz] = eval3dp(sph,linspace(-%pi/2,%pi/2,40),linspace(0,%pi*2,40));
subplot(2,nc,3)
plot3d(xx, yy, zz, alpha=60, flag=[color("green") 8 4])
zlabel("isoview off", "rotation", -90, "fontsize",4)
xtitle("True sphere")
a3 = gca();
subplot(2,nc,nc+3)
plot3d(xx, yy, zz, alpha=60, flag=[color("green") 8 4])
zlabel("isoview on", "rotation", -90, "fontsize",4)
isoview

// Switching isoview status for all axes
isoview(gcf())

// Forcing isoview for all axes of the current figure
isoview(gcf(), "on")

// Relaxing isoview for the current axes
isoview off

// Setting isoview for top axes
isoview(gcf(),"off")
isoview([a1 a2 a3], "on")
             ]]></programlisting>
        <scilab:image>
            t = [0:0.1:2*%pi]';
            clf
            f = gcf();
            f.axes_size = [850 400];
            nc = 3;
            subplot(2,nc,1)
            plot2d(cos(t),sin(t))
            xtitle("True circle")
            a1 = gca();
            subplot(2,nc,nc+1)
            plot2d(cos(t),sin(t))
            isoview

            subplot(2,nc,2)
            plot2d(7*cos(t),2*sin(t))
            xtitle("True ellipse")
            a2 = gca();
            subplot(2,nc,nc+2)
            plot2d(7*cos(t),2*sin(t))
            isoview

            // plot of a sphere using facets computed by eval3dp
            deff("[x,y,z] = sph(alp,tet)",["x = r*cos(alp).*cos(tet)+orig(1)*ones(tet)"; ..
            "y = r*cos(alp).*sin(tet)+orig(2)*ones(tet)"; ..
            "z = r*sin(alp)+orig(3)*ones(tet)"]);
            r = 3; orig = [0 0 0];
            [xx,yy,zz] = eval3dp(sph,linspace(-%pi/2,%pi/2,40),linspace(0,%pi*2,40));
            subplot(2,nc,3)
            plot3d(xx, yy, zz, alpha=60, flag=[color("green") 8 4])
            zlabel("isoview off", "rotation", -90, "fontsize",4)
            xtitle("True sphere")
            a3 = gca();
            subplot(2,nc,nc+3)
            plot3d(xx, yy, zz, alpha=60, flag=[color("green") 8 4])
            zlabel("isoview on", "rotation", -90, "fontsize",4)
            isoview
        </scilab:image>
        <programlisting role="example"><![CDATA[
// Using plot2d(..., frameflag=4) :
r = linspace(1,10,200);
t = r*3;
scf();
subplot(1,2,1)
plot2d(r.*sin(t),r.*cos(t))
xtitle("plot2d(..)")

subplot(1,2,2)
plot2d(r.*sin(t),r.*cos(t),frameflag=4)
xtitle("with frameflag=4")
             ]]></programlisting>
        <scilab:image localized="true">
            r = linspace(1,10,200);
            t = r*3;
            scf();
            subplot(1,2,1)
            plot2d(r.*sin(t),r.*cos(t))
            xtitle("plot2d(..)")

            subplot(1,2,2)
            plot2d(r.*sin(t),r.*cos(t),frameflag=4)
            xtitle("with frameflag=4")
        </scilab:image>
    </refsection>
    <refsection role="see also">
        <title>See also</title>
        <simplelist type="inline">
            <member>
                <link linkend="replot">replot</link>
            </member>
            <member>
                <link linkend="axes_properties">Axes properties</link>
            </member>
        </simplelist>
    </refsection>
    <refsection role="history">
        <title>History</title>
        <revhistory>
            <revision>
                <revnumber>6.0.0</revnumber>
                <revdescription>
                    <itemizedlist>
                        <listitem>input flags "on"|"off" added.</listitem>
                        <listitem>input parameters &lt;none&gt; or idGraphics added.</listitem>
                        <listitem>
                            <literal>isoview(xmin, xmax, ymin, ymax)</literal> marked as deprecated.
                        </listitem>
                    </itemizedlist>
                </revdescription>
            </revision>
            <revision>
                <revnumber>6.0.2</revnumber>
                <revdescription>
                    "isoview on" now forces .cube_scaling="off", and
                    "isoview off" forces .cube_scaling="on".
                </revdescription>
            </revision>
            <revision>
                <revnumber>6.1</revnumber>
                <revdescription>
                    The syntax <literal>isoview(xmin, xmax, ymin, ymax)</literal> is no longer available.
                </revdescription>
            </revision>
        </revhistory>
    </refsection>
</refentry>