isoview('on'|'off') missed switching .cube_scaling='off'|'on'
[scilab.git] / scilab / modules / graphics / help / en_US / axes_operations / isoview.xml
1 <?xml version="1.0" encoding="UTF-8"?>
2 <!--
3  * Scilab ( http://www.scilab.org/ ) - This file is part of Scilab
4  * Copyright (C) INRIA - Serge Steer
5  * Copyright (C) 2016, 2018 - Samuel GOUGEON
6  *
7  * Copyright (C) 2012 - 2016 - Scilab Enterprises
8  *
9  * This file is hereby licensed under the terms of the GNU GPL v2.0,
10  * pursuant to article 5.3.4 of the CeCILL v.2.1.
11  * This file was originally licensed under the terms of the CeCILL v2.1,
12  * and continues to be available under such terms.
13  * For more information, see the COPYING file which you should have received
14  * along with this program.
15  *
16  -->
17 <refentry xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink"
18           xmlns:svg="http://www.w3.org/2000/svg" xmlns:mml="http://www.w3.org/1998/Math/MathML"
19           xmlns:db="http://docbook.org/ns/docbook" xmlns:scilab="http://www.scilab.org"
20           xml:lang="en" xml:id="isoview">
21     <refnamediv>
22         <refname>isoview</refname>
23         <refpurpose>tunes isometric rendering of graphical axes
24         </refpurpose>
25     </refnamediv>
26     <refsynopsisdiv>
27         <title>Syntax</title>
28         <synopsis>isoview
29             isoview on
30             isoview off
31             isoview(idGraphics [,"on"|"off"])
32             isoview(xmin, xmax, ymin, ymax)    // DEPRECATED. use replot()
33         </synopsis>
34     </refsynopsisdiv>
35     <refsection role="arguments">
36         <title>Arguments</title>
37         <variablelist>
38             <varlistentry>
39                 <term>"on" | "off" | &lt;none&gt;</term>
40                 <listitem>
41                     Enables or disables or switches the isometric rendering for all considered axes.
42                     <para/>
43                 </listitem>
44             </varlistentry>
45             <varlistentry>
46                 <term>idGraphics</term>
47                 <listitem>
48                     Vector of graphic handles. All the related axes are processed.
49                     By default, the current axes is processed.
50                     <para/>
51                 </listitem>
52             </varlistentry>
53             <varlistentry>
54                 <term>xmin, xmax, ymin, ymax</term>
55                 <listitem>
56                     Four decimal numbers: new axes bounds.
57                     <warning>These parameters will be removed from Scilab 6.1.
58                         Please use <link linkend="replot">replot</link>
59                         after <function>isoview</function> instead.
60                     </warning>
61                     <para/>
62                 </listitem>
63             </varlistentry>
64         </variablelist>
65     </refsection>
66     <refsection role="description">
67         <title>Description</title>
68         <para>
69             <function>isoview</function> is used to set or relax isometric rendering scales
70             on the x, y (and z) axes, without changing the size of the graphic window.
71         </para>
72         <para>
73             <literal>isoview()</literal> or simply <literal>isoview</literal>
74             toggles the isoview status of the current axes, and keeps its current
75             bounds: isometric scales are set whenever
76             they were free, or scales are relaxed whenever they were isometric.
77         </para>
78         <para>
79             <literal>isoview("on")</literal> or <literal>isoview on</literal>
80             sets isometric scales for the current axes.
81         </para>
82         <para>
83             <literal>isoview("off")</literal> or <literal>isoview off</literal>
84             relaxes x, y (and z)  scales for the current axes.
85         </para>
86         <para>
87             <literal>isoview(idGraphics,..)</literal> runs on axes related
88             to each graphic object listed in the vector <varname>idGraphics</varname>:
89             <itemizedlist>
90                 <listitem>
91                     If <varname>idGraphics(i)</varname> is a figure's handle,
92                     all its Axes are considered.
93                 </listitem>
94                 <listitem>
95                     If <varname>idGraphics(i)</varname> is an Axes,
96                     it is considered as is.
97                 </listitem>
98                 <listitem>
99                     If <varname>idGraphics(i)</varname> is the handle of a
100                     sub-axes component (such as a polyline, a compound, etc),
101                     its hosting axes is considered.
102                 </listitem>
103             </itemizedlist>
104         </para>
105         <para>
106             <literal>isoview(xmin, xmax, ymin, ymax)</literal> sets the current
107             axes in isometric mode, and then sets its bounds to the given values.
108             <warning>
109                 This usage is deprecated and will be removed from Scilab 6.1 onwards. Please use
110                 <link linkend="replot">replot</link> after
111                 <function>isoview</function> instead.
112             </warning>
113         </para>
114         <note>
115             The current axes graphical entity is still the same after calling <literal>isoview(..)</literal>.
116         </note>
117         <note>To plot some curves directly in isometric mode without calling
118             <function>isoview</function> afterwards, the <literal>plot2d(...,frameflag=4)</literal>
119             option may be used at call time.
120         </note>
121         <refsect3>
122             <title>Rendering according to .isoview and .cube_scaling settings</title>
123             <para>
124             <table align="middle">
125                 <tr>
126                     <th>isoview(..)</th><th>gca().isoview</th>
127                                        <th>gca().cube_scaling</th>
128                                        <td><emphasis role="bold">Rendering</emphasis></td>
129                 </tr>
130                 <tr>
131                     <th>on</th><td align="center">on</td>
132                                <td align="center">off</td>
133                                <td>X, Y and Z are isometric</td>
134                 </tr>
135                 <tr>
136                     <th>off</th><td align="center">off</td>
137                                 <td align="center">on</td>
138                                 <td>independent X, Y and Z scales. In 3D, improved aspect ratios when X/Y/Z ranges are very different.</td>
139                 </tr>
140                 <tr>
141                     <th></th><td align="center">off</td>
142                             <td align="center">off</td>
143                             <td>Independent X, Y, Z scales. In 3D, rendered X/Y/Z scales ratios are close to the data ones</td>
144                 </tr>
145                 <tr>
146                     <th></th><td align="center">on</td>
147                              <td align="center">on</td>
148                              <td>Scales are such that the axes looks square or cubic</td>
149                 </tr>
150             </table>
151             </para>
152         </refsect3>
153     </refsection>
154     <refsection role="examples">
155         <title>Examples</title>
156         <programlisting role="example"><![CDATA[
157 t = [0:0.1:2*%pi]';
158 clf
159 nc = 3;
160
161 subplot(2,nc,1)
162 plot2d(cos(t),sin(t))
163 xtitle("True circle")
164 a1 = gca();
165
166 subplot(2,nc,nc+1)
167 plot2d(cos(t),sin(t))
168 isoview
169
170 subplot(2,nc,2)
171 plot2d(7*cos(t),2*sin(t))
172 xtitle("True ellipse")
173 a2 = gca();
174
175 subplot(2,nc,nc+2)
176 plot2d(7*cos(t),2*sin(t))
177 isoview
178
179 // plot of a sphere using facets computed by eval3dp
180 deff("[x,y,z] = sph(alp,tet)",[
181     "x = r*cos(alp).*cos(tet)+orig(1)*ones(tet)"; ..
182     "y = r*cos(alp).*sin(tet)+orig(2)*ones(tet)"; ..
183     "z = r*sin(alp)+orig(3)*ones(tet)"]);
184 r = 3; orig = [0 0 0];
185 [xx,yy,zz] = eval3dp(sph,linspace(-%pi/2,%pi/2,40),linspace(0,%pi*2,40));
186 subplot(2,nc,3)
187 plot3d(xx, yy, zz, alpha=60, flag=[color("green") 8 4])
188 zlabel("isoview off", "rotation", -90, "fontsize",4)
189 xtitle("True sphere")
190 a3 = gca();
191 subplot(2,nc,nc+3)
192 plot3d(xx, yy, zz, alpha=60, flag=[color("green") 8 4])
193 zlabel("isoview on", "rotation", -90, "fontsize",4)
194 isoview
195
196 // Switching isoview status for all axes
197 isoview(gcf())
198
199 // Forcing isoview for all axes of the current figure
200 isoview(gcf(), "on")
201
202 // Relaxing isoview for the current axes
203 isoview off
204
205 // Setting isoview for top axes
206 isoview(gcf(),"off")
207 isoview([a1 a2 a3], "on")
208              ]]></programlisting>
209         <scilab:image>
210             t = [0:0.1:2*%pi]';
211             clf
212             f = gcf();
213             f.axes_size = [850 400];
214             nc = 3;
215             subplot(2,nc,1)
216             plot2d(cos(t),sin(t))
217             xtitle("True circle")
218             a1 = gca();
219             subplot(2,nc,nc+1)
220             plot2d(cos(t),sin(t))
221             isoview
222
223             subplot(2,nc,2)
224             plot2d(7*cos(t),2*sin(t))
225             xtitle("True ellipse")
226             a2 = gca();
227             subplot(2,nc,nc+2)
228             plot2d(7*cos(t),2*sin(t))
229             isoview
230
231             // plot of a sphere using facets computed by eval3dp
232             deff("[x,y,z] = sph(alp,tet)",["x = r*cos(alp).*cos(tet)+orig(1)*ones(tet)"; ..
233             "y = r*cos(alp).*sin(tet)+orig(2)*ones(tet)"; ..
234             "z = r*sin(alp)+orig(3)*ones(tet)"]);
235             r = 3; orig = [0 0 0];
236             [xx,yy,zz] = eval3dp(sph,linspace(-%pi/2,%pi/2,40),linspace(0,%pi*2,40));
237             subplot(2,nc,3)
238             plot3d(xx, yy, zz, alpha=60, flag=[color("green") 8 4])
239             zlabel("isoview off", "rotation", -90, "fontsize",4)
240             xtitle("True sphere")
241             a3 = gca();
242             subplot(2,nc,nc+3)
243             plot3d(xx, yy, zz, alpha=60, flag=[color("green") 8 4])
244             zlabel("isoview on", "rotation", -90, "fontsize",4)
245             isoview
246         </scilab:image>
247         <programlisting role="example"><![CDATA[
248 // Using plot2d(..., frameflag=4) :
249 r = linspace(1,10,200);
250 t = r*3;
251 scf();
252 subplot(1,2,1)
253 plot2d(r.*sin(t),r.*cos(t))
254 xtitle("plot2d(..)")
255
256 subplot(1,2,2)
257 plot2d(r.*sin(t),r.*cos(t),frameflag=4)
258 xtitle("with frameflag=4")
259              ]]></programlisting>
260         <scilab:image>
261             r = linspace(1,10,200);
262             t = r*3;
263             scf();
264             subplot(1,2,1)
265             plot2d(r.*sin(t),r.*cos(t))
266             xtitle("plot2d(..)")
267
268             subplot(1,2,2)
269             plot2d(r.*sin(t),r.*cos(t),frameflag=4)
270             xtitle("with frameflag=4")
271         </scilab:image>
272     </refsection>
273     <refsection role="see also">
274         <title>See also</title>
275         <simplelist type="inline">
276             <member>
277                 <link linkend="replot">replot</link>
278             </member>
279             <member>
280                 <link linkend="axes_properties">Axes properties</link>
281             </member>
282         </simplelist>
283     </refsection>
284
285     <refsection role="history">
286         <title>History</title>
287         <revhistory>
288             <revision>
289                 <revnumber>6.0.0</revnumber>
290                 <revdescription>
291                     <itemizedlist>
292                         <listitem>input flags "on"|"off" added.</listitem>
293                         <listitem>input parameters &lt;none&gt; or idGraphics added.</listitem>
294                         <listitem>
295                             <literal>isoview(xmin, xmax, ymin, ymax)</literal> marked as deprecated.
296                         </listitem>
297                     </itemizedlist>
298                 </revdescription>
299             </revision>
300             <revision>
301                 <revnumber>6.0.2</revnumber>
302                 <revdescription>
303                     "isoview on" now forces .cube_scaling="off", and
304                     "isoview off" forces .cube_scaling="on".
305                 </revdescription>
306             </revision>
307         </revhistory>
308     </refsection>
309 </refentry>