scatter with extended polyline properties mark_size, mark_foreground, mark_background
[scilab.git] / scilab / modules / graphics / help / en_US / GlobalProperty.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 - Fabrice Leray
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="GlobalProperty">
14     <refnamediv>
15         <refname>GlobalProperty</refname>
16         <refpurpose>
17             to customize the objects appearance (curves, surfaces...) in a plot
18             or surf command
19         </refpurpose>
20     </refnamediv>
21     <refsection>
22         <title>Description</title>
23         <para>
24             The <literal>GlobalProperty</literal> is an optional argument
25             that can be used inside a <link linkend="plot">plot</link> or
26             <link linkend="surf">surf</link> command. It allows a global
27             customization of all the new plotted lines (respectively surfaces).
28             It has to be given as a couple
29             {<literal>PropertyName</literal>,
30             <literal>PropertyValue</literal>}. Several couples can be set
31             at the same time in a <function>plot</function> or
32             <function>surf</function> call.
33         </para>
34         <para>
35             <literal>PropertyName</literal> must be a string defining the
36             property to set. The <literal>PropertyValue</literal> can be a
37             real, integer or string (scalar or matrix) depending on the type of
38             property used. For example, to specify a red (color) longdash-dot
39             (line style) with diamond marker (marker), the sequence should be:
40             <literal>'Colo'</literal>, <literal>'red'</literal>, <literal>'LineSt'</literal>, <literal>'-.'</literal>, <literal>'Marker'</literal>, <literal>'diam'</literal>.
41         </para>
42         <para>
43             As you can see, a full complete spelling of each property name and
44             value is not required but those arguments, specified in any order,
45             must remain unambiguous. Furthermore, the string specification is
46             not case sensitive. <literal>GlobalProperty</literal> is
47             predominant on all <literal>LineSpec</literal> previously stated.
48         </para>
49         
50         <para>
51             Here is a complete list of the <literal>PropertyName</literal> you
52             can specify (using <link linkend="plot">plot</link> or <link linkend="surf">surf</link>) and their available
53             associated <literal>PropertyValue</literal>. If not specified,
54             those properties are available for both <literal>Polyline</literal>
55             and <literal>Fac3d</literal> objects (created respectively by
56             <function>plot</function> or <function>surf</function>) and, as
57             previously said, they are applied to the new created objects (lines
58             or surfaces).
59         </para>
60         <para>
61             Sometimes, you may have two <literal>PropertyName</literal>
62             corresponding to one property: the first one is the equivalent
63             default Matlab name, the second is the default name used by Scilab
64             (i.e.: <literal>Color</literal> or <literal>Foreground</literal>
65             for a line, see below).
66         </para>
67         <variablelist>
68             <varlistentry>
69                 <term>CData or ColorData: </term>
70                 <listitem>
71                     <para>
72                         a real matrix specifying the color at every points
73                         defined by <literal>Z</literal> matrix. This property
74                         is linked to the object's
75                         <literal>data.color</literal> property (see
76                         <link linkend="surface_properties">surface properties</link>).
77                         <note>
78                             Note that this property is available for surfaces only.
79                         </note>
80                     </para>
81                 </listitem>
82             </varlistentry>
83             <varlistentry>
84                 <term>CDataMapping or ColorDataMapping: </term>
85                 <listitem>
86                     <para>
87                         a string with value <literal>'scaled'</literal> or
88                         <literal>'direct'</literal>. If a <literal>data.color</literal>
89                         is set, each index color data specifies a single value
90                         for each vertex. <literal>cdata_mapping</literal>
91                         determines whether those indices are scaled
92                         to map linearly into the current colormap
93                         (<literal>'scaled'</literal> mode)
94                         or point directly into this colormap
95                         (<literal>'direct'</literal> mode).
96                         This property is useful when
97                         <literal>color_flag</literal> equals
98                         <literal>2</literal>, <literal>3</literal> or
99                         <literal>4</literal>.
100                         <note>
101                             Note that this property exists only with
102                             <literal>Fac3d</literal> entities. Note also that
103                             <function>plot3d</function> has
104                             <literal>'direct'</literal> mode by default and
105                             <function>surf</function> has <literal>'scaled'</literal> mode by default.
106                         </note>
107                     </para>
108                 </listitem>
109             </varlistentry>
110             <varlistentry>
111                 <term>Clipping: </term>
112                 <listitem>
113                     <para>
114                         a string <literal>"on"</literal> or <literal>"off"</literal> defining the
115                         clipping mode (<literal>"on"</literal> by default). It
116                         is equivalent to the <literal>clip_state</literal>
117                         property. This field contains the
118                         <literal>visible</literal> property (see <link linkend="polyline_properties">polyline properties</link>).
119                         <note>
120                             Note that this property is not yet available for
121                             surface entities.
122                         </note>
123                     </para>
124                 </listitem>
125             </varlistentry>
126             <varlistentry>
127                 <term>Color or Foreground: </term>
128                 <listitem>
129                     <para>
130                         a string defining a known color (see <link linkend="color_list">color_list</link>) or a
131                         <literal>1</literal>x<literal>3</literal> (or <literal>3</literal>x<literal>1</literal>) RGB
132                         vector defining a color number. Color number is given as
133                         a 3-uple <literal>R</literal>, <literal>G</literal>,
134                         <literal>B</literal> corresponding respectively to red,
135                         green and blue intensity between 0 and 1. This property
136                         is linked to the object's <literal>foreground</literal> property
137                         (see <link linkend="polyline_properties">polyline properties</link>).
138                         <warning>
139                             Color is not available for surfaces objects. The
140                             <literal>Foreground</literal> property exists for
141                             surfaces objects but is linked to the Matlab
142                             <literal>EdgeColor</literal> property (see
143                             <link linkend="surface_properties">surface properties</link>).
144                         </warning>
145                     </para>
146                 </listitem>
147             </varlistentry>
148             <varlistentry>
149                 <term>EdgeColor or Foreground: </term>
150                 <listitem>
151                     <para>
152                         a string defining a known color (see <link linkend="color_list">color_list</link>) or a
153                         <literal>1</literal>x<literal>3</literal> (or <literal>3</literal>x<literal>1</literal>) RGB
154                         vector defining a color number. Color number is given as
155                         a 3-uple <literal>R</literal>, <literal>G</literal>,
156                         <literal>B</literal> corresponding respectively to red,
157                         green and blue intensity between 0 and 1. This property
158                         is linked to the surface <literal>foreground</literal>
159                         property (see <link linkend="surface_properties">surface
160                             properties
161                         </link>
162                         ).
163                         <warning>
164                             For <literal>polyline</literal> objects, the
165                             <literal>Foreground</literal> property
166                             exists with a different meaning (see above) and
167                             <literal>EdgeColor</literal> does not exist at all.
168                         </warning>
169                     </para>
170                 </listitem>
171             </varlistentry>
172             <varlistentry>
173                 <term>FaceColor: </term>
174                 <listitem>
175                     <para>
176                         a string with value <literal>'none'</literal>,
177                         <literal>'flat'</literal> or <literal>'interp'</literal>
178                         specifying the way the facet's color are rendered.
179                         When <literal>'none'</literal> is selected, a mesh of
180                         the surface is drawn; if <literal>'flat'</literal>
181                         (default mode) is set, the <literal>Fac3d</literal>
182                         <literal>color.data</literal> values determine one color
183                         per facet using the color of the first vertex of the
184                         facet. If the value is <literal>'interp'</literal>, an
185                         interpolated shading is done on the surface using
186                         <literal>color.data</literal> to determine a color at each vertex of each facet.
187                     </para>
188                 </listitem>
189             </varlistentry>
190             <varlistentry>
191                 <term>LineStyle: </term>
192                 <listitem>
193                     <para>
194                         this property value should be a string defining a line
195                         style. This property is linked to the object's
196                         <literal>line_style</literal> property
197                         (see <link linkend="polyline_properties">polyline
198                             properties
199                         </link>
200                         or
201                         <link linkend="surface_properties">surface
202                             properties
203                         </link>
204                         ).
205                     </para>
206                     <para/>
207                     <informaltable border="1">
208                         <tr>
209                             <td>
210                                 <literal>Specifier</literal>
211                             </td>
212                             <td>
213                                 <literal>Line Style</literal>
214                             </td>
215                         </tr>
216                         <tr>
217                             <td>
218                                 <literal>-</literal>
219                             </td>
220                             <td>Solid line (default)</td>
221                         </tr>
222                         <tr>
223                             <td>
224                                 <literal>--</literal>
225                             </td>
226                             <td>Dashed line</td>
227                         </tr>
228                         <tr>
229                             <td>
230                                 <literal>:</literal>
231                             </td>
232                             <td>Dotted line</td>
233                         </tr>
234                         <tr>
235                             <td>
236                                 <literal>-.</literal>
237                             </td>
238                             <td>Dash-dotted line</td>
239                         </tr>
240                         <tr>
241                             <td>
242                                 <literal>none</literal>
243                             </td>
244                             <td>No line</td>
245                         </tr>
246                     </informaltable>
247                 </listitem>
248             </varlistentry>
249             <varlistentry>
250                 <term>Marker or MarkStyle: </term>
251                 <listitem>
252                     <para>
253                         a string defining the marker type. Note that if you
254                         specify a marker without a line style, both line (with
255                         default solid mode enabled) and marker are drawn.This
256                         property is linked to the object's
257                         <literal>mark_style</literal> and
258                         <literal>mark_mode</literal> properties (see
259                         <link linkend="polyline_properties">polyline
260                             properties
261                         </link>
262                         or <link linkend="surface_properties">surface properties</link>).
263                     </para>
264                     <informaltable border="1">
265                         <tr>
266                             <td>
267                                 <literal>Specifier</literal>
268                             </td>
269                             <td>
270                                 <literal>Marker Type</literal>
271                             </td>
272                         </tr>
273                         <tr>
274                             <td>
275                                 <literal>+</literal>
276                             </td>
277                             <td>Plus sign</td>
278                         </tr>
279                         <tr>
280                             <td>
281                                 <literal>o</literal>
282                             </td>
283                             <td>Circle</td>
284                         </tr>
285                         <tr>
286                             <td>
287                                 <literal>*</literal>
288                             </td>
289                             <td>Asterisk</td>
290                         </tr>
291                         <tr>
292                             <td>
293                                 <literal>.</literal>
294                             </td>
295                             <td>Point</td>
296                         </tr>
297                         <tr>
298                             <td>
299                                 <literal>x</literal>
300                             </td>
301                             <td>Cross</td>
302                         </tr>
303                         <tr>
304                             <td>
305                                 <literal>'square'</literal> or
306                                 <literal>'s'</literal>
307                             </td>
308                             <td>Square</td>
309                         </tr>
310                         <tr>
311                             <td>
312                                 <literal>'diamond'</literal> or
313                                 <literal>'d'</literal>
314                             </td>
315                             <td>Diamond</td>
316                         </tr>
317                         <tr>
318                             <td>
319                                 <literal>^</literal>
320                             </td>
321                             <td>Upward-pointing triangle</td>
322                         </tr>
323                         <tr>
324                             <td>
325                                 <literal>v</literal>
326                             </td>
327                             <td>Downward-pointing triangle</td>
328                         </tr>
329                         <tr>
330                             <td>
331                                 <literal>&gt;</literal>
332                             </td>
333                             <td>Right-pointing triangle</td>
334                         </tr>
335                         <tr>
336                             <td>
337                                 <literal>&lt;</literal>
338                             </td>
339                             <td>Left-pointing triangle</td>
340                         </tr>
341                         <tr>
342                             <td>
343                                 <literal>'pentagram'</literal> or
344                                 <literal>'p'</literal>
345                             </td>
346                             <td>Five-pointed star (pentagram)</td>
347                         </tr>
348                         <tr>
349                             <td>
350                                 <literal>'none'</literal>
351                             </td>
352                             <td>No marker (default)</td>
353                         </tr>
354                     </informaltable>
355                 </listitem>
356             </varlistentry>
357             <varlistentry>
358                 <term>MarkerEdgeColor or MarkForeground: </term>
359                 <listitem>
360                     <para>
361                         a string defining a known color (see <link
362                         linkend="color_list">color_list</link>) or a
363                         <literal>1</literal>x<literal>3</literal> (or <literal>3</literal>x<literal>1</literal>) RGB
364                         vector defining a color number. Color number is given as a 3-uple
365                         <literal>R</literal>, <literal>G</literal>, <literal>B</literal> corresponding
366                         respectively to red, green and blue intensity between 0 and 1. This
367                         property is linked to the object's <literal>mark_foreground</literal>
368                         property (see <link linkend="polyline_properties">polyline properties</link> or
369                         <link linkend="surface_properties">surface properties</link>).
370                     </para>
371                 </listitem>
372             </varlistentry>
373             <varlistentry>
374                 <term>MarkerFaceColor or MarkBackground: </term>
375                 <listitem>
376                     <para>
377                         a string defining a known color (see <link
378                         linkend="color_list">color_list</link>) or a
379                         <literal>1</literal>x<literal>3</literal> (or
380                         <literal>3</literal>x<literal>1</literal>) RGB
381                         vector defining a color number. Color number is given as
382                         a 3-uple <literal>R</literal>, <literal>G</literal>,
383                         <literal>B</literal> corresponding respectively to red,
384                         green and blue intensity between 0 and 1. This
385                         property is linked to the object's <literal>mark_background</literal>
386                         property (see <link linkend="polyline_properties">polyline properties</link>
387                         or <link linkend="surface_properties">surface properties</link>).
388                     </para>
389                 </listitem>
390             </varlistentry>
391             <varlistentry>
392                 <term>MarkerSize or MarkSize: </term>
393                 <listitem>
394                     <para>
395                         a scalar defining the marker size in <literal>point</literal> unit. This
396                         property is linked to the object's <literal>mark_size</literal> property
397                         with <literal>mark_size_unit</literal> enabled to <literal>"point"</literal> (see
398                         <link linkend="polyline_properties">polyline properties</link> or
399                         <link linkend="surface_properties">surface properties</link>).
400                     </para>
401                 </listitem>
402             </varlistentry>
403             <varlistentry>
404                 <term>Visible: </term>
405                 <listitem>
406                     <para>
407                         a string <literal>"on"</literal> or <literal>"off"</literal> defining the
408                         visibility mode (<literal>"on"</literal> by default).
409                         This property is linked to the object's
410                         <literal>visible</literal> property (see
411                         <link linkend="polyline_properties">polyline properties</link> or
412                         <link linkend="surface_properties">surface properties</link>).
413                     </para>
414                 </listitem>
415             </varlistentry>
416             <varlistentry>
417                 <term>X data: </term>
418                 <listitem>
419                     <para>
420                         a real vector or matrix (re-)defining the given data for
421                         all the plotted lines or surfaces. Concerning
422                         dimensions, note that this new data must match all the
423                         previous specified <literal>X</literal> data: that
424                         is to say all those data matrices must be of the same
425                         dimensions. This property is linked to the object's
426                         <literal>data.x</literal> property (see
427                         <link linkend="polyline_properties">polyline properties</link> or
428                         <link linkend="surface_properties">surface properties</link>).
429                     </para>
430                 </listitem>
431             </varlistentry>
432             <varlistentry>
433                 <term>Y data: </term>
434                 <listitem>
435                     <para>
436                         a real vector or matrix (re-)defining the given data for
437                         all the plotted lines or surfaces. Concerning
438                         dimensions, note that this new data must match all the
439                         previous specified <literal>Y</literal> data: that
440                         is to say all those data matrices must be of the same
441                         dimensions. This property is linked to the object's
442                         <literal>data.y</literal> property (see
443                         <link linkend="polyline_properties">polyline properties</link> or
444                         <link linkend="surface_properties">surface properties</link>).
445                     </para>
446                 </listitem>
447             </varlistentry>
448             <varlistentry>
449                 <term>Z data: </term>
450                 <listitem>
451                     <para>
452                         when used with <function>plot</function>, a real vector
453                         or matrix adding a <literal>Z</literal> data for all the
454                         plotted lines; with <function>surf</function>, a real
455                         matrix (re-)defining the given data for all the
456                         surfaces. Concerning dimensions, note that this new data
457                         must match all the previous specified
458                         <literal>X</literal> and <literal>Y</literal>
459                         data. This property is linked to the object's
460                         <literal>data.z</literal> property (see <link
461                         linkend="polyline_properties">polyline properties</link>
462                         or <link linkend="surface_properties">surface properties</link>).
463                     </para>
464                 </listitem>
465             </varlistentry>
466         </variablelist>
467     </refsection>
468     <refsection>
469         <title>Examples</title>
470         <programlisting role="example"><![CDATA[ 
471 // --------------------
472 // With the plot command :
473 // --------------------
474 x=1:10; // Init.
475 plot(x,sin(x),'colo','red','linest','-.','marker','>','markeredg','cyan','markerFace','yellow','markersize',5)
476 clf();
477
478 // combinations' order in {PropertyName,PropertyValue} does not matter
479 plot(x,sin(x),'marker','p','markerfac','cyan','markersiz',10)
480 clf();
481
482 // combination of LineSpec and GlobalProperty shows the GlobalProperty predominance
483 plot(x,x.*x,'*cya--','color','gr','linestyle','-','marker','sq','markersize',6,'markforegroun','red','markbackgro',[0.2 0.5 0.6])
484 clf();
485
486 //multiple plots with different LineSpecs and finally some global GlobalProperty
487 clf();
488 t=0:%pi/20:2*%pi;
489 plot(t,sin(t),'ro-.',t,cos(t),'cya+',t,abs(sin(t)),'--mo','markstyl','diam')
490
491 // --------------------
492 // With the plot2d command :
493 // --------------------
494 function draw_marks(title)
495   a=gca();
496   a.title.text=title;
497   a.mark_size=8;
498   a.data_bounds=[-1.5 1.5 -1.5 1.5];
499
500   theta=(1/15)*(2*%pi)*[0:15];
501   plot2d(cos(theta),sin(theta));
502
503   for i=0:14 do
504     theta=(i/15)*(2*%pi);
505     plot2d(cos(theta),sin(theta),style=-i);
506   end
507 endfunction
508
509 clf();
510 subplot(2,2,1)
511 draw_marks("black foreground / white background")
512
513 subplot(2,2,2)
514 a=gca();
515 a.mark_foreground=-1;
516 a.mark_background=4;
517 draw_marks("black foreground / cyan background")
518
519 subplot(2,2,3)
520 a=gca();
521 a.mark_background=0;
522 draw_marks("black foreground / invisible background")
523
524 subplot(2,2,4)
525 a=gca();
526 a.mark_foreground=0;
527 a.mark_background=4;
528 draw_marks("invisible foreground / cyan background")
529
530 // --------------------
531 // With the surf command :
532 // --------------------
533
534
535 Z= [   0.0001    0.0013    0.0053   -0.0299   -0.1809   -0.2465   -0.1100   -0.0168   -0.0008   -0.0000
536     0.0005    0.0089    0.0259   -0.3673   -1.8670   -2.4736   -1.0866   -0.1602   -0.0067    0.0000
537     0.0004    0.0214    0.1739   -0.3147   -4.0919   -6.4101   -2.7589   -0.2779    0.0131    0.0020
538    -0.0088   -0.0871    0.0364    1.8559    1.4995   -2.2171   -0.2729    0.8368    0.2016    0.0130
539    -0.0308   -0.4313   -1.7334   -0.1148    3.0731    0.4444    2.6145    2.4410    0.4877    0.0301
540    -0.0336   -0.4990   -2.3552   -2.1722    0.8856   -0.0531    2.6416    2.4064    0.4771    0.0294
541    -0.0137   -0.1967   -0.8083    0.2289    3.3983    3.1955    2.4338    1.2129    0.2108    0.0125
542    -0.0014   -0.0017    0.3189    2.7414    7.1622    7.1361    3.1242    0.6633    0.0674    0.0030
543     0.0002    0.0104    0.1733    1.0852    2.6741    2.6725    1.1119    0.1973    0.0152    0.0005
544     0.0000    0.0012    0.0183    0.1099    0.2684    0.2683    0.1107    0.0190    0.0014    0.0000];
545
546 clf();
547 f=gcf();
548 f.figure_size = [610,724];
549 subplot(211)
550 surf(Z,'facecol','interp','ydat',101:110,'edgecol','mage')
551 subplot(212)
552 surf(Z,'edgeco','b','marker','d','markersiz',9,'markerfac','k','xdata',-50:-41)
553  ]]></programlisting>
554     </refsection>
555     <refsection role="see also">
556         <title>See Also</title>
557         <simplelist type="inline">
558             <member>
559                 <link linkend="LineSpec">LineSpec</link>
560             </member>
561             <member>
562                 <link linkend="plot">plot</link>
563             </member>
564             <member>
565                 <link linkend="surf">surf</link>
566             </member>
567             <member>
568                 <link linkend="clf">clf</link>
569             </member>
570             <member>
571                 <link linkend="polyline_properties">polyline properties</link>
572             </member>
573             <member>
574                 <link linkend="surface_properties">surface properties</link>
575             </member>
576         </simplelist>
577     </refsection>
578 </refentry>