scilab/modules/graphics/help/en_US/3d_plot/param3d1.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) ENPC - Jean-Philippe Chancelier
   5  *
   6  * This file must be used under the terms of the CeCILL.
   7  * This source file is licensed as described in the file COPYING, which
   8  * you should have received as part of this distribution.  The terms
   9  * are also available at
  10  * http://www.cecill.info/licences/Licence_CeCILL_V2.1-en.txt
  11  *
  12  -->
  13 <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="param3d1" xml:lang="en">
  14     <refnamediv>
  15         <refname>param3d1</refname>
  16         <refpurpose>3D plot of parametric curves</refpurpose>
  17     </refnamediv>
  18     <refsynopsisdiv>
  19         <title>Calling Sequence</title>
  20         <synopsis>param3d1(x,y,z,[theta,alpha,leg,flag,ebox])
  21             param3d1(x,y,list(z,colors),[theta,alpha,leg,flag,ebox])
  22         </synopsis>
  23     </refsynopsisdiv>
  24     <refsection>
  25         <title>Arguments</title>
  26         <variablelist>
  27             <varlistentry>
  28                 <term>x,y,z</term>
  29                 <listitem>
  30                     <para>matrices of the same size (nl,nc).</para>
  31                     <para>Each column i of the matrices corresponds to the coordinates
  32                         of the ith curve. You can give a specific color for each curve by
  33                         using <literal>list(z,colors)</literal> instead of
  34                         <literal>z</literal>, where <literal>colors</literal> is a vector of
  35                         size <literal>nc</literal>. If <literal>color(i)</literal> is
  36                         negative the curve is plotted using the mark with id
  37                         <literal>abs(style(i))</literal>; if <literal>style(i)</literal> is
  38                         strictly positive, a plain line with color id
  39                         <literal>style(i)</literal> or a dashed line with dash id
  40                         <literal>style(i)</literal> is used.
  41                     </para>
  42                 </listitem>
  43             </varlistentry>
  44             <varlistentry>
  45                 <term>theta,alpha</term>
  46                 <listitem>
  47                     <para>real values giving in degree the spherical coordinates of the
  48                         observation point. <emphasis>The default values are 35 and 45
  49                             degree.
  50                         </emphasis>
  51                     </para>
  52                 </listitem>
  53             </varlistentry>
  54             <varlistentry>
  55                 <term>leg</term>
  56                 <listitem>
  57                     <para>string defining the captions for each axis with @ as a field
  58                         separator, for example "X@Y@Z".
  59                     </para>
  60                 </listitem>
  61             </varlistentry>
  62             <varlistentry>
  63                 <term>flag=[type,box]</term>
  64                 <listitem>
  65                     <para>
  66                         <literal>type</literal> and <literal>box</literal> have the
  67                         same meaning as in <literal>plot3d</literal>:
  68                     </para>
  69                     <variablelist>
  70                         <varlistentry>
  71                             <term>type</term>
  72                             <listitem>
  73                                 <para>an integer (scaling).</para>
  74                                 <variablelist>
  75                                     <varlistentry>
  76                                         <term>type=0</term>
  77                                         <listitem>
  78                                             <para>the plot is made using the current 3D scaling (set
  79                                                 by a previous call to <literal>param3d</literal>,
  80                                                 <literal>plot3d</literal>, <literal>contour</literal> or
  81                                                 <literal>plot3d1</literal>).
  82                                             </para>
  83                                         </listitem>
  84                                     </varlistentry>
  85                                     <varlistentry>
  86                                         <term>type=1</term>
  87                                         <listitem>
  88                                             <para>rescales automatically 3d boxes with extreme
  89                                                 aspect ratios, the boundaries are specified by the value
  90                                                 of the optional argument <literal>ebox</literal>.
  91                                             </para>
  92                                         </listitem>
  93                                     </varlistentry>
  94                                     <varlistentry>
  95                                         <term>type=2 </term>
  96                                         <listitem>
  97                                             <para>rescales automatically 3d boxes with extreme
  98                                                 aspect ratios, the boundaries are computed using the
  99                                                 given data. <emphasis>This is the default
 100                                                     value.
 101                                                 </emphasis>
 102                                             </para>
 103                                         </listitem>
 104                                     </varlistentry>
 105                                     <varlistentry>
 106                                         <term>type=3</term>
 107                                         <listitem>
 108                                             <para>3d isometric with box bounds given by optional
 109                                                 <literal>ebox</literal>, similarily to
 110                                                 <literal>type=1</literal>.
 111                                             </para>
 112                                         </listitem>
 113                                     </varlistentry>
 114                                     <varlistentry>
 115                                         <term>type=4</term>
 116                                         <listitem>
 117                                             <para>3d isometric bounds derived from the data,
 118                                                 similarily<literal> to type=2</literal>.
 119                                             </para>
 120                                         </listitem>
 121                                     </varlistentry>
 122                                     <varlistentry>
 123                                         <term>type=5</term>
 124                                         <listitem>
 125                                             <para>3d expanded isometric bounds with box bounds given
 126                                                 by optional <literal>ebox</literal>, similarily to
 127                                                 <literal>type=1</literal>.
 128                                             </para>
 129                                         </listitem>
 130                                     </varlistentry>
 131                                     <varlistentry>
 132                                         <term>type=6</term>
 133                                         <listitem>
 134                                             <para>3d expanded isometric bounds derived from the
 135                                                 data, similarily to <literal>type=2</literal>.Note that
 136                                                 axes boundaries can be customized through the axes
 137                                                 entity properties (see <link linkend="axes_properties">axes_properties</link>).
 138                                             </para>
 139                                         </listitem>
 140                                     </varlistentry>
 141                                 </variablelist>
 142                             </listitem>
 143                         </varlistentry>
 144                         <varlistentry>
 145                             <term>box</term>
 146                             <listitem>
 147                                 <para>an integer (frame around the plot).</para>
 148                                 <variablelist>
 149                                     <varlistentry>
 150                                         <term>box=0</term>
 151                                         <listitem>
 152                                             <para>nothing is drawn around the plot.</para>
 153                                         </listitem>
 154                                     </varlistentry>
 155                                     <varlistentry>
 156                                         <term>box=1</term>
 157                                         <listitem>
 158                                             <para>unimplemented (like box=0).</para>
 159                                         </listitem>
 160                                     </varlistentry>
 161                                     <varlistentry>
 162                                         <term>box=2</term>
 163                                         <listitem>
 164                                             <para>only the axes behind the surface are drawn.</para>
 165                                         </listitem>
 166                                     </varlistentry>
 167                                     <varlistentry>
 168                                         <term>box=3</term>
 169                                         <listitem>
 170                                             <para>a box surrounding the surface is drawn and
 171                                                 captions are added.
 172                                             </para>
 173                                         </listitem>
 174                                     </varlistentry>
 175                                     <varlistentry>
 176                                         <term>box=4</term>
 177                                         <listitem>
 178                                             <para>a box surrounding the surface is drawn, captions
 179                                                 and axes are added.Note that axes aspect can also be
 180                                                 customized through the axes entity properties (see <link linkend="axes_properties">axes_properties</link>).
 181                                                 <emphasis>This is the default value.</emphasis>
 182                                             </para>
 183                                         </listitem>
 184                                     </varlistentry>
 185                                 </variablelist>
 186                             </listitem>
 187                         </varlistentry>
 188                     </variablelist>
 189                 </listitem>
 190             </varlistentry>
 191             <varlistentry>
 192                 <term>ebox</term>
 193                 <listitem>
 194                     <para>It specifies the boundaries of the plot as the vector
 195                         <literal>[xmin,xmax,ymin,ymax,zmin,zmax]</literal>. This argument is
 196                         used together with <literal>type</literal> in
 197                         <literal>flag</literal> : if it is set to <literal>1</literal>,
 198                         <literal>3</literal> or <literal>5</literal> (see above to see the
 199                         corresponding behaviour). If <literal>flag</literal> is missing,
 200                         <literal>ebox</literal> is not taken into acount. Note that, when
 201                         specified, the <literal>ebox</literal> argument acts on the
 202                         <literal>data_bounds</literal> field that can also be reset through
 203                         the axes entity properties (see <link linkend="axes_properties">axes_properties</link>). The
 204                         <literal>ebox</literal> default value is
 205                         <literal>[0,1,0,1,0,1]</literal>.
 206                     </para>
 207                 </listitem>
 208             </varlistentry>
 209         </variablelist>
 210     </refsection>
 211     <refsection>
 212         <title>Description</title>
 213         <para>
 214             <literal>param3d1</literal> is used to plot 3D curves defined by
 215             their coordinates <literal>x</literal>, <literal>y</literal> and
 216             <literal>z</literal>. Note that data can also be got or modified through
 217             the surface entity properties (see <link linkend="surface_properties">surface_properties</link>).
 218         </para>
 219         <para>
 220             Note that properties like <literal>rotation angles</literal>,
 221             <literal>colors</literal> and <literal>thickness</literal> of the plotted
 222             curves can also be got or modified through the polyline entity properties
 223             (see <link linkend="polyline_properties">polyline_properties</link>).
 224         </para>
 225         <para>
 226             Enter the command <literal>param3d1()</literal> to see a
 227             demo.
 228         </para>
 229     </refsection>
 230     <refsection>
 231         <title>Examples</title>
 232         <programlisting role="example"><![CDATA[
 233 xset('window',20) // create a window number 20
 234 t=[0:0.1:5*%pi]';
 235 param3d1([sin(t),sin(2*t)],[cos(t),cos(2*t)],..
 236          list([t/10,sin(t)],[3,2]),35,45,"X@Y@Z",[2,3])
 237
 238 xdel(20);
 239 a=get("current_axes");//get the handle of the newly created axes
 240 t=[0:0.1:5*%pi]';
 241 param3d1([sin(t),sin(2*t)],[cos(t),cos(2*t)],[t/10,sin(t)])
 242 a.rotation_angles=[65,75];
 243 a.data_bounds=[-1,-1,-1;1,1,2]; //boundaries given by data_bounds
 244 a.thickness = 2;
 245 h=a.children //get the handle of the param3d entity: an Compound composed of 2 curves
 246 h.children(1).foreground = 3 // first curve
 247 curve2 = h.children(2);
 248 curve2.foreground = 6;
 249 curve2.mark_style = 2;
 250  ]]></programlisting>
 251         <scilab:image>param3d1();</scilab:image>
 252     </refsection>
 253     <refsection role="see also">
 254         <title>See Also</title>
 255         <simplelist type="inline">
 256             <member>
 257                 <link linkend="param3d">param3d</link>
 258             </member>
 259             <member>
 260                 <link linkend="plot3d">plot3d</link>
 261             </member>
 262             <member>
 263                 <link linkend="plot2d">plot2d</link>
 264             </member>
 265             <member>
 266                 <link linkend="gca">gca</link>
 267             </member>
 268             <member>
 269                 <link linkend="xdel">xdel</link>
 270             </member>
 271             <member>
 272                 <link linkend="delete">delete</link>
 273             </member>
 274         </simplelist>
 275     </refsection>
 276 </refentry>