* Bug 14544 fixed: scatter and scatter3 canceled upstream drawlater
[scilab.git] / scilab / modules / graphics / help / en_US / 3d_plot / scatter3.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) Scilab Enterprises - 2015 - 2012 - Juergen Koch
5  *
6  * Copyright (C) 2012 - 2016 - Scilab Enterprises
7  *
8  * This file is hereby licensed under the terms of the GNU GPL v2.0,
9  * pursuant to article 5.3.4 of the CeCILL v.2.1.
10  * This file was originally licensed under the terms of the CeCILL v2.1,
11  * and continues to be available under such terms.
12  * For more information, see the COPYING file which you should have received
13  * along with this program.
14  *
15  -->
16 <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="scatter3">
17     <refnamediv>
18         <refname>scatter3</refname>
19         <refpurpose>3D scatter plot</refpurpose>
20     </refnamediv>
21     <refsynopsisdiv>
22         <title>Syntax</title>
23         <synopsis>
24             polyline = scatter3(x, y, z, msizes, mcolors, "fill", marker, &lt;marker_property,value&gt;)
25             polyline = scatter3(axes_handle,...)
26         </synopsis>
27     </refsynopsisdiv>
28     <refsection>
29         <title>Arguments</title>
30         <variablelist>
31             <varlistentry>
32                 <term>x, y, z</term>
33                 <listitem>
34                     <para>
35                         columns or rows vectors of n real numbers specifying the
36                         <varname>x</varname>, <varname>y</varname> and <varname>z</varname>
37                         coordinates of the centers of markers.
38                     </para>
39                 </listitem>
40             </varlistentry>
41             <varlistentry>
42                 <term>msizes</term>
43                 <listitem>
44                     <para>
45                         Specifying the sizes of the markers.
46                         To plot each marker with equal size, specify <varname>msizes</varname> as a scalar.
47                         To plot each marker with a different size, specify <varname>msizes</varname>
48                         as a vector with n components.
49                         The units for <varname>msizes</varname> is points squared, with a default
50                         value of 36 points squared.
51                         The size equals the area of the circle surrounding the marker.
52                     </para>
53                 </listitem>
54             </varlistentry>
55             <varlistentry>
56                 <term>mcolors</term>
57                 <listitem>
58                     <para>
59                         Specifying the colors of the markers.
60                         To plot each marker with the same color, specify <varname>mcolors</varname>
61                         as a string representing a known color: see <link linkend="color_list">color_list</link>.
62                         A color can also be specified by a vector of 3 RGB values.
63                         RGB values correspond to red, green and blue intensity between 0 and 1.
64                         To plot each marker with a different color, specify <varname>mcolors</varname>
65                         as a vector with n components.
66                         The values of <varname>mcolors</varname> are linearly mapped to the colors
67                         in the current colormap.
68                         Colors can also by specified by a matrix of RGB values or a vector of
69                         strings representing known colors.
70                         A matrix of RGB values has 3 columns and n rows.
71                         The default color is "blue".
72                     </para>
73                 </listitem>
74             </varlistentry>
75             <varlistentry>
76                 <term>"fill"</term>
77                 <listitem>
78                     <para>
79                         This string indicates that the markers are filled with some colors.
80                         By default the filling colors of markers are the same as their shape ones.
81                         However, both colors can be set independently by using the properties
82                         <literal>"markerFaceColor"</literal> or <literal>"markerBackgroundColor"</literal>.
83                     </para>
84                 </listitem>
85             </varlistentry>
86             <varlistentry>
87                 <term>marker</term>
88                 <listitem>
89                     <para>
90                         Select the type of the marker. The same marker shape is used for all
91                         specified points.
92                         The figure below shows the 15 different marker types.
93                     </para>
94                     <para>
95                         <inlinemediaobject>
96                             <imageobject>
97                                 <imagedata fileref="../../images/marks.svg"/>
98                             </imageobject>
99                         </inlinemediaobject>
100                     </para>
101                     <para>
102                         Marker types are specified by strings: see the table below.
103                     </para>
104                     <para>
105                         <informaltable border="1">
106                             <tr>
107                                 <td>
108                                     String
109                                 </td>
110                                 <td>
111                                     Marker type
112                                 </td>
113                             </tr>
114                             <tr>
115                                 <td>
116                                     <literal>"."</literal>
117                                 </td>
118                                 <td>Point</td>
119                             </tr>
120                             <tr>
121                                 <td>
122                                     <literal>"+"</literal>
123                                 </td>
124                                 <td>Plus sign</td>
125                             </tr>
126                             <tr>
127                                 <td>
128                                     <literal>"x"</literal>
129                                 </td>
130                                 <td>Cross</td>
131                             </tr>
132                             <tr>
133                                 <td>
134                                     <literal>"circle plus"</literal>
135                                 </td>
136                                 <td>Circle with plus</td>
137                             </tr>
138                             <tr>
139                                 <td>
140                                     <literal>"filled diamond"</literal>
141                                 </td>
142                                 <td>Filled diamond</td>
143                             </tr>
144                             <tr>
145                                 <td>
146                                     <literal>"d"</literal> or
147                                     <literal>"diamond"</literal>
148                                 </td>
149                                 <td>Diamond</td>
150                             </tr>
151                             <tr>
152                                 <td>
153                                     <literal>"^"</literal>
154                                 </td>
155                                 <td>Upward-pointing triangle</td>
156                             </tr>
157                             <tr>
158                                 <td>
159                                     <literal>"v"</literal>
160                                 </td>
161                                 <td>Downward-pointing triangle</td>
162                             </tr>
163                             <tr>
164                                 <td>
165                                     <literal>"diamond plus"</literal>
166                                 </td>
167                                 <td>Diamond with plus</td>
168                             </tr>
169                             <tr>
170                                 <td>
171                                     <literal>"o"</literal>
172                                 </td>
173                                 <td>Circle (default)</td>
174                             </tr>
175                             <tr>
176                                 <td>
177                                     <literal>"*"</literal>
178                                 </td>
179                                 <td>Asterisk</td>
180                             </tr>
181                             <tr>
182                                 <td>
183                                     <literal>"s"</literal> or
184                                     <literal>"square"</literal>
185                                 </td>
186                                 <td>Square</td>
187                             </tr>
188                             <tr>
189                                 <td>
190                                     <literal>"&gt;"</literal>
191                                 </td>
192                                 <td>Right-pointing triangle</td>
193                             </tr>
194                             <tr>
195                                 <td>
196                                     <literal>"&lt;"</literal>
197                                 </td>
198                                 <td>Left-pointing triangle</td>
199                             </tr>
200                             <tr>
201                                 <td>
202                                     <literal>"pentagram"</literal> or
203                                     <literal>"p"</literal>
204                                 </td>
205                                 <td>Five-pointed star</td>
206                             </tr>
207                         </informaltable>
208                     </para>
209                 </listitem>
210             </varlistentry>
211             <varlistentry>
212                 <term>&lt;marker_property, value&gt;</term>
213                 <listitem>
214                     <para>
215                         A sequence of property value pairs can be used to specify type, color and
216                         line width of the markers.
217                     </para>
218                 </listitem>
219             </varlistentry>
220             <varlistentry>
221                 <term>&lt;"marker", value&gt; or &lt;"markerStyle", value&gt;</term>
222                 <listitem>
223                     <para>
224                         Specify the type of the marker, see the table above.
225                     </para>
226                 </listitem>
227             </varlistentry>
228             <varlistentry>
229                 <term>&lt;"markerEdgeColor", value&gt; or &lt;"markerForeground", value&gt;</term>
230                 <listitem>
231                     <para>
232                         Specify the foreground color of the marker.
233                         A color can be specified by a string representing a known color:
234                         see <link linkend="color_list">color_list</link>.
235                         A color can also be specified by a vector of 3 RGB values.
236                         RGB values correspond to red, green and blue intensity between 0 and 1.
237                         This option is superseded by the <varname>mcolors</varname> argument.
238                     </para>
239                 </listitem>
240             </varlistentry>
241             <varlistentry>
242                 <term>&lt;"markerFaceColor", value&gt; or &lt;"markerBackground", value&gt;</term>
243                 <listitem>
244                     <para>
245                         Specify the background color of the marker.
246                         A color can be specified by a string representing a known color:
247                         see <link linkend="color_list">color_list</link>.
248                         A color can also be specified by a vector of 3 RGB values.
249                         RGB values correspond to red, green and blue intensity between 0 and 1.
250                         This option is superseded by argument <varname>mcolors</varname>.
251                     </para>
252                 </listitem>
253             </varlistentry>
254             <varlistentry>
255                 <term>&lt;"linewidth", value&gt; or &lt;"thickness", value&gt;</term>
256                 <listitem>
257                     <para>
258                         Specify the thickness of the edge of the marker.
259                         The unit for the value is one point.
260                     </para>
261                 </listitem>
262             </varlistentry>
263             <varlistentry>
264                 <term>axes_handle</term>
265                 <listitem>
266                     <para>This optional argument forces the scatter plot to appear inside the
267                         selected axes given by <literal>axes_handle</literal> rather than inside the
268                         current axes, see <link linkend="gca">gca</link>.
269                     </para>
270                 </listitem>
271             </varlistentry>
272             <varlistentry>
273                 <term>polyline</term>
274                 <listitem>
275                     <para>
276                         Handle of the created polyline.
277                     </para>
278                 </listitem>
279             </varlistentry>
280         </variablelist>
281     </refsection>
282     <refsection>
283         <title>Description</title>
284         <para>
285             <literal>scatter3(x,y,z)</literal> creates a scatter plot with markers at the locations
286             specified by <varname>x</varname>, <varname>y</varname>, and <varname>z</varname>.
287             The default type of the marker is a circle, the default color is "blue" and the default
288             marker size is 36.
289             This means the circle surrounding the marker has an area of 36 points squared.
290         </para>
291         <para>
292             Using <literal>scatter3(x,y,z,s,c)</literal> different sizes and colors for each marker
293             can be specified.
294             There are many different ways to specify marker types, marker colors and marker sizes.
295             For more details see the description of the arguments and the examples.
296         </para>
297         <note>
298             <itemizedlist>
299               <listitem>
300                 To skip an argument, just replace it with <literal>[]</literal> as in
301                 <literal>scatter3(x,y,z,[],mcolors)</literal>.
302               </listitem>
303               <listitem>
304                  When the axes is rotated, the markers are automatically rotated as well in order
305                  to show always the same face to the observer.
306               </listitem>
307             </itemizedlist>
308         </note>
309     </refsection>
310     <refsection>
311         <title>Examples</title>
312         <para>
313             Create 3D scatter plot
314         </para>
315         <programlisting role="example"><![CDATA[
316 // x, y and z initialisation
317 t = 1:200;
318 x = t .* cos(t) .* sin(t);
319 y = t .* sin(t) .* sin(t);
320 z = t .* cos(t);
321 // create 3D scatter plot
322 scatter3(x, y, z);
323 // modify rotation angles
324 gca().rotation_angles = [60, 45];
325  ]]></programlisting>
326         <scilab:image>
327             t = 1:200
328             x = t.*cos(t).*sin(t)
329             y = t.*sin(t).*sin(t)
330             z = t.*cos(t)
331             scatter3(x,y,z)
332             gca().rotation_angles = [60, 45];
333         </scilab:image>
334         <para>
335             Vary marker size
336         </para>
337         <programlisting role="example"><![CDATA[
338 // x, y and z initialisation
339 t = 1:200;
340 x = t .* cos(t) .* sin(t);
341 y = t .* sin(t) .* sin(t);
342 z = t .* cos(t);
343 // size according to radius
344 s = linspace(50, 1, length(t));
345 // create 3D scatter plot
346 scatter3(x, y, z, s);
347 // modify rotation angles
348 gca().rotation_angles = [60, 45];
349  ]]></programlisting>
350         <scilab:image>
351             t = 1:200
352             x = t .* cos(t) .* sin(t)
353             y = t .* sin(t) .* sin(t)
354             z = t .* cos(t)
355             s = linspace(50, 1, length(t))
356             scatter3(x, y, z, s)
357             gca().rotation_angles = [60, 45];
358         </scilab:image>
359         <para>
360             Vary marker size and color
361         </para>
362         <programlisting role="example"><![CDATA[
363 // x, y and z initialisation
364 t = 1:200;
365 x = t .* cos(t) .* sin(t);
366 y = t .* sin(t) .* sin(t);
367 z = t .* cos(t);
368 // size according to radius
369 s = linspace(50, 1, length(t));
370 // set color map
371 gcf().color_map = coolcolormap(64);
372 // color according to radius
373 c = t;
374 // create 3D scatter plot
375 scatter3(x, y, z, s, c);
376 // modify rotation angles
377 gca().rotation_angles = [60, 45];
378  ]]></programlisting>
379         <scilab:image>
380             t = 1:200
381             x = t.*cos(t).*sin(t)
382             y = t.*sin(t).*sin(t)
383             z = t.*cos(t)
384             s = linspace(50,1,length(t))
385             gcf().color_map = coolcolormap(64);
386             c = t
387             scatter3(x,y,z,s,c)
388             gca().rotation_angles = [60, 45];
389         </scilab:image>
390         <para>
391             Fill the markers
392         </para>
393         <programlisting role="example"><![CDATA[
394 // x, y and z initialisation
395 z = linspace(0, 25, 200);
396 x = z .* cos(z);
397 y = z .* sin(z);
398 // create 3D scatter plot
399 scatter3(x, y, z, "fill");
400 // modify rotation angles
401 gca().rotation_angles = [60, 45];
402  ]]></programlisting>
403         <scilab:image>
404             z = linspace(0,25,200)
405             x = z.*cos(z)
406             y = z.*sin(z)
407             scatter3(x,y,z,"fill")
408             gca().rotation_angles = [60, 45];
409         </scilab:image>
410         <para>
411             Specify marker symbol
412         </para>
413         <programlisting role="example"><![CDATA[
414 // x, y and z initialisation
415 z = linspace(0, 25, 200);
416 x = z .* cos(z);
417 y = z .* sin(z);
418 // create 3D scatter plot
419 scatter3(x, y, z, "*");
420 // modify rotation angles
421 gca().rotation_angles = [60, 45];
422  ]]></programlisting>
423         <scilab:image>
424             z = linspace(0,25,200)
425             x = z.*cos(z)
426             y = z.*sin(z)
427             scatter3(x,y,z,"*")
428             gca().rotation_angles = [60,45];
429         </scilab:image>
430         <para>
431             Change marker edge and face color
432         </para>
433         <programlisting role="example"><![CDATA[
434 // x, y and z initialisation
435 z = linspace(0, 25, 200);
436 x = z .* cos(z);
437 y = z .* sin(z);
438 // create 3D scatter plot
439 scatter3(x, y, z,...
440         "markerEdgeColor", "black",...
441         "markerFaceColor", [0 .8 .8]);
442 // modify rotation angles
443 gca().rotation_angles = [60, 45];
444  ]]></programlisting>
445         <scilab:image>
446             z = linspace(0,25,200)
447             x = z.*cos(z)
448             y = z.*sin(z)
449             scatter3(x,y,z,...
450             "markerEdgeColor","black",...
451             "markerFaceColor",[0 .8 .8])
452             gca().rotation_angles = [60, 45];
453         </scilab:image>
454         <para>
455             Specify subplot for scatter plot
456         </para>
457         <programlisting role="example"><![CDATA[
458 // x, y and z initialisation
459 n = 20;
460 [x, y] = meshgrid(linspace(-2, 2, n));
461 z = exp(-x.^2 - y.^2);
462 // create 3D scatter subplot
463 subplot(2,1,1)
464 scatter3(gca(), x(:), y(:), z(:));
465 // modify rotation angles
466 gca().rotation_angles = [60,45];
467 // create 3D scatter subplot
468 subplot(2,1,2)
469 scatter3(gca(), x(:), y(:), z(:), "markerFaceColor", [0 .8 .8]);
470 // modify rotation angles
471 gca().rotation_angles = [60,45];
472  ]]></programlisting>
473         <scilab:image>
474             n = 20
475             [x,y] = meshgrid(linspace(-2,2,n))
476             z = exp(-x.^2 - y.^2)
477             subplot(2,1,1)
478             scatter3(gca(), x(:), y(:), z(:))
479             gca().rotation_angles = [60, 45];
480             subplot(2,1,2)
481             scatter3(gca(),x(:),y(:),z(:),"markerFaceColor",[0 .8 .8])
482             gca().rotation_angles = [60, 45];
483         </scilab:image>
484         <para>
485             Modify scatter plot after creation
486         </para>
487         <programlisting role="example"><![CDATA[
488 // x, y and z initialisation
489 t = 1:200;
490 x = t .* cos(t) .* sin(t);
491 y = t .* sin(t) .* sin(t);
492 z = t .* cos(t);
493 // size according to radius
494 s = linspace(50, 1, length(t));
495 // create 3D scatter plot
496 scatter3(x, y, z, s);
497 // modify rotation angles
498 gca().rotation_angles = [60,45];
499  ]]></programlisting>
500         <scilab:image>
501             t = 1:200
502             x = t.*cos(t).*sin(t)
503             y = t.*sin(t).*sin(t)
504             z = t.*cos(t)
505             s = linspace(50,1,length(t))
506             p = scatter3(x,y,z,s)
507             gca().rotation_angles = [60,45];
508         </scilab:image>
509         <programlisting role="example"><![CDATA[
510 // modify polyline
511 p.mark_foreground = color(0.5, 0, 0);
512 p.mark_background = color(0.5, 0.5, 0);
513  ]]></programlisting>
514         <scilab:image>
515             t = 1:200
516             x = t.*cos(t).*sin(t)
517             y = t.*sin(t).*sin(t)
518             z = t.*cos(t)
519             s = linspace(50,1,length(t))
520             p = scatter3(x,y,z,s)
521             set(gca(),"rotation_angles",[60,45])
522             // modify polyline
523             p.mark_foreground = color(0.5, 0, 0)
524             p.mark_background = color(0.5, 0.5, 0)
525         </scilab:image>
526     </refsection>
527     <refsection role="see also">
528         <title>See also</title>
529         <simplelist type="inline">
530             <member>
531                 <link linkend="scatter">scatter</link>
532             </member>
533             <member>
534                 <link linkend="param3d">param3d</link>
535             </member>
536             <member>
537                 <link linkend="gca">gca</link>
538             </member>
539             <member>
540                 <link linkend="gcf">gcf</link>
541             </member>
542             <member>
543                 <link linkend="color_list">color_list</link>
544             </member>
545             <member>
546                 <link linkend="polyline_properties">polyline_properties</link>
547             </member>
548         </simplelist>
549     </refsection>
550     <refsection>
551         <title>History</title>
552         <revhistory>
553             <revision>
554                 <revnumber>6.0.0</revnumber>
555                 <revremark>
556                     Function <function>scatter3</function> introduced.
557                 </revremark>
558             </revision>
559         </revhistory>
560     </refsection>
561 </refentry>