4af78627e66a30ff59c3d8f4c8796c85548b0d6f
[scilab.git] / scilab / modules / graphics / help / en_US / 2d_plot / Matplot_properties.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="Matplot_properties">
14     <refnamediv>
15         <refname>Matplot properties</refname>
16         <refpurpose>
17             description of the Matplot entities properties
18         </refpurpose>
19     </refnamediv>
20     <refsection>
21         <title>Description</title>
22         <para>
23             The <literal>Matplot</literal> entity is a leaf of the graphics entities hierarchy. It
24             represents 2D plots of surface using colors and images (see
25             <function>Matplot</function> and <function>Matplot1</function>).
26         </para>
27         <variablelist>
28             <varlistentry>
29                 <term>parent: </term>
30                 <listitem>
31                     <para>
32                         this property contains the handle of the parent. The parent of the
33                         <literal>Matplot</literal> entity should be of the type <literal>"Axes"</literal>.
34                     </para>
35                 </listitem>
36             </varlistentry>
37             <varlistentry>
38                 <term>children: </term>
39                 <listitem>
40                     <para>
41                         this property contains a vector with the <literal>children</literal> of
42                         the handle. However, <literal>Matplot</literal> handles currently do not
43                         have any <literal>children</literal>.
44                     </para>
45                 </listitem>
46             </varlistentry>
47             <varlistentry>
48                 <term>visible: </term>
49                 <listitem>
50                     <para>
51                         this field contains the <literal>visible</literal> property value for
52                         the entity. It should be <literal>"on" </literal> or <literal>"off"</literal> .
53                         By default, the plot is visible, the property's value is
54                         <literal>"on"</literal>. If <literal>"off"</literal> the plot is not drawn on the
55                         screen.
56                     </para>
57                 </listitem>
58             </varlistentry>
59             <varlistentry>
60                 <term>data: </term>
61                 <listitem>
62                     <para>
63                         this field defines a [<literal>m</literal>x<literal>n</literal>]
64                         <literal>color</literal> data matrix (double, (u)int8, (u)int16, (u)int32) or hypermatrix.
65                         The colors are interpreted according to the image_type property.
66                         The color associated to <literal>color(i,j)</literal> is used do draw a small square
67                         of length 1 with center at location <literal>(x=j,y=(m-i+1))</literal>.
68                     </para>
69                 </listitem>
70             </varlistentry>
71             <varlistentry>
72                 <term>rect: </term>
73                 <listitem>
74                     <para>
75                         this field contains a row-vector defined by <literal>[xmin, ymin, xmax, ymax]</literal>.
76                         It specifies a rectangle in the current scale and the matrix is drawn inside this rectangle.
77                     </para>
78                 </listitem>
79             </varlistentry>
80             <varlistentry>
81                 <term>image_type: </term>
82                 <listitem>
83                     <para>
84                         this field defines the image type. It could be one of the values: "rgb", "rgba", "gray", "index",
85                         "red", "green", "blue", "rgb332", "rgb444", "rgb555", "rgba5551".
86                     </para>
87                     <para>
88                         Colors are determinated by the data type and by image_type:
89                     </para>
90                     <itemizedlist>
91                         <listitem>
92                             <para>
93                                 When image_type is equal to index, the data are just considered as an index in the colormap.
94                             </para>
95                         </listitem>
96                         <listitem>
97                             <para>
98                                 When image_type is equal to rgb, hypermat of int8 or uint8 will give the RGB components, hypermat of doubles will give normalized RGB components (values between 0 and 1), matrices of int8 or uint8 where number of rows is a multiple of 3 will give the RGB components, matrices of int32 will give RGB colors, matrices of uint32 will give RGBA colors where the alpha channel will be set to 0xFF.
99                             </para>
100                         </listitem>
101                         <listitem>
102                             <para>
103                                 When image_type is equal to rgba, hypermat of int8 or uint8 will give the RGBA components, hypermat of doubles will give normalized RGBA components (values between 0 and 1), matrices of int8 or uint8 where number of rows is a multiple of 4 will give the RGB components, matrices of int32 will give RGBA colors, matrices of uint32 will give RGBA colors.
104                             </para>
105                         </listitem>
106                         <listitem>
107                             <para>
108                                 When image_type is equal to gray, matrices of int8 or uint8 will give Gray level color (R-G-B=GRAY-GRAY-GRAY), for other types, data will be considered as RGB ones and converted into gray colors (0.299*R+0.587*G+0.114*B).
109                             </para>
110                         </listitem>
111                         <listitem>
112                             <para>
113                                 When image_type is equal to red, matrices of int8 or uint8 will give Red level color (R-G-B=RED-00-00), for other types, data will be considered as RGB ones and converted into red colors (a mask is applied to keep the Red component).
114                             </para>
115                         </listitem>
116                         <listitem>
117                             <para>
118                                 When image_type is equal to green, matrices of int8 or uint8 will give Green level color (R-G-B=00-GREEN-00), for other types, data will be considered as RGB ones and converted into green colors (a mask is applied to keep the Green component).
119                             </para>
120                         </listitem>
121                         <listitem>
122                             <para>
123                                 When image_type is equal to blue, matrices of int8 or uint8 will give Blue level color (R-G-B=00-00-BLUE), for other types, data will be considered as RGB ones and converted into blue colors (a mask is applied to keep the Blue component).
124                             </para>
125                         </listitem>
126                         <listitem>
127                             <para>
128                                 When image_type is equal to rgb332, matrices of int8 or uint8 will give RGB colors where R component is wrote on 3 bits, G component on 3 bits and B component on 2 bits. For other data types, RGB (8-8-8) data are converted into RGB (3-3-2).
129                             </para>
130                         </listitem>
131                         <listitem>
132                             <para>
133                                 When image_type is equal to rgb444, matrices of int16 or uint16 will give RGB colors where each components is wrote on 4 bits. For other data types, RGB (8-8-8) data are converted into RGB (4-4-4).
134                             </para>
135                         </listitem>
136                         <listitem>
137                             <para>
138                                 When image_type is equal to rgb555, matrices of int16 or uint16 will give RGB colors where each components is wrote on 5 bits. For other data types, RGB (8-8-8) data are converted into RGB (5-5-5).
139                             </para>
140                         </listitem>
141                         <listitem>
142                             <para>
143                                 When image_type is equal to rgb4444, matrices of int16 or uint16 will give RGBA colors where each components is wrote on 4 bits. For other data types, RGBA (8-8-8-8) data are converted into RGBA (4-4-4-4).
144                             </para>
145                         </listitem>
146                         <listitem>
147                             <para>
148                                 When image_type is equal to rgb5551, matrices of int16 or uint16 will give RGBA colors where each non-alpha components is wrote on 5 bits and the alpha component on 1 bit. For other data types, RGBA (8-8-8-8) data are converted into RGBA (5-5-5-1).
149                             </para>
150                         </listitem>
151                     </itemizedlist>
152                 </listitem>
153             </varlistentry>
154             <varlistentry>
155                 <term>clip_state: </term>
156                 <listitem>
157                     <para>
158                         this field contains the <literal>clip_state</literal> property value for
159                         the <literal>Matplot</literal>. It should be :
160                     </para>
161                     <itemizedlist>
162                         <listitem>
163                             <para>
164                                 <literal>"off"</literal> this means that the <literal>Matplot</literal> is not
165                                 clipped.
166                             </para>
167                         </listitem>
168                         <listitem>
169                             <para>
170                                 <literal>"clipgrf"</literal> this means that the <literal>Matplot</literal> is clipped
171                                 outside the <literal>Axes</literal> box.
172                             </para>
173                         </listitem>
174                         <listitem>
175                             <para>
176                                 <literal>"on"</literal> this means that the <literal>Matplot</literal> is clipped
177                                 outside the rectangle given by property <literal>clip_box</literal>.
178                             </para>
179                         </listitem>
180                     </itemizedlist>
181                 </listitem>
182             </varlistentry>
183             <varlistentry>
184                 <term>clip_box: </term>
185                 <listitem>
186                     <para>
187                         this field is to determinate the <literal>clip_box</literal> property.
188                         By default its value should be an empty matrix if <literal>clip_state</literal> is
189                         <literal>"off"</literal>. Other cases the vector <literal>[x,y,w,h]</literal>
190                         (upper-left point width height) defines the portions of the <literal>Matplot</literal>
191                         to display, however <literal>clip_state</literal> property value will be changed.
192                     </para>
193                 </listitem>
194             </varlistentry>
195             <varlistentry>
196                 <term>user_data: </term>
197                 <listitem>
198                     <para>
199                         this field can be use to store any scilab variable in the
200                         <literal>Matplot</literal> data structure, and to retreive it.
201                     </para>
202                 </listitem>
203             </varlistentry>
204         </variablelist>
205     </refsection>
206     <refsection>
207         <title>Examples</title>
208         <programlisting role="example"><![CDATA[
209 Matplot((1:xget("lastpattern")))
210 e=gce(); // get current entity
211
212 e.data=e.data($:-1:1) // reverse order
213  ]]></programlisting>
214         <scilab:image>
215             Matplot((1:xget("lastpattern")));
216             e=gce();
217             e.data=e.data($:-1:1);
218         </scilab:image>
219     </refsection>
220     <refsection role="see also">
221         <title>See Also</title>
222         <simplelist type="inline">
223             <member>
224                 <link linkend="set">set</link>
225             </member>
226             <member>
227                 <link linkend="get">get</link>
228             </member>
229             <member>
230                 <link linkend="delete">delete</link>
231             </member>
232             <member>
233                 <link linkend="grayplot">grayplot</link>
234             </member>
235             <member>
236                 <link linkend="Matplot">Matplot</link>
237             </member>
238             <member>
239                 <link linkend="Matplot1">Matplot1</link>
240             </member>
241             <member>
242                 <link linkend="graphics_entities">graphics_entities</link>
243             </member>
244             <member>
245                 <link linkend="grayplot_properties">grayplot_properties</link>
246             </member>
247         </simplelist>
248     </refsection>
249     <refsection>
250         <title>History</title>
251         <revhistory>
252             <revision>
253                 <revnumber>5.5.0</revnumber>
254                 <revremark>
255                     Property image_type introduced.
256                 </revremark>
257                 <revremark>
258                     Property rect introduced.
259                 </revremark>
260             </revision>
261         </revhistory>
262     </refsection>
263 </refentry>