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