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