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