Update Matplot doc to take into account image_type property
[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>image_type: </term>
73                 <listitem>
74                     <para>
75                         this field defines the image type. It could be one of the values: "rgb", "rgba", "gray", "index",
76                         "red", "green", "blue", "rgb332", "rgb444", "rgb555", "rgba5551".
77                     </para>
78                     <para>
79                       Colors are determinated by the data type and by image_type:
80                     </para>
81                     <itemizedlist>
82                       <listitem>
83                         <para>
84                           When image_type is equals to index, the data are just considered as an index in the colormap.
85                         </para>
86                       </listitem>
87                       <listitem>
88                         <para>
89                           When image_type is equals 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.
90                         </para>
91                       </listitem>
92                       <listitem>
93                         <para>
94                           When image_type is equals 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.
95                         </para>
96                       </listitem>
97                       <listitem>
98                         <para>
99                           When image_type is equals 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).
100                         </para>
101                       </listitem>
102                       <listitem>
103                         <para>
104                           When image_type is equals 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).
105                         </para>
106                       </listitem>
107                       <listitem>
108                         <para>
109                           When image_type is equals 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).
110                         </para>
111                       </listitem>
112                       <listitem>
113                         <para>
114                           When image_type is equals 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).
115                         </para>
116                       </listitem>
117                       <listitem>
118                         <para>
119                           When image_type is equals 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).
120                         </para>
121                       </listitem>
122                       <listitem>
123                         <para>
124                           When image_type is equals 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).
125                         </para>
126                       </listitem>
127                       <listitem>
128                         <para>
129                           When image_type is equals 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).
130                         </para>
131                       </listitem>
132                       <listitem>
133                         <para>
134                           When image_type is equals 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).
135                         </para>
136                       </listitem>
137                       <listitem>
138                         <para>
139                           When image_type is equals 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).
140                         </para>
141                       </listitem>
142                     </itemizedlist>
143                 </listitem>
144             </varlistentry>
145             <varlistentry>
146                 <term>clip_state: </term>
147                 <listitem>
148                     <para>
149                         this field contains the <literal>clip_state</literal> property value for
150                         the <literal>Matplot</literal>. It should be :
151                     </para>
152                     <itemizedlist>
153                         <listitem>
154                             <para>
155                                 <literal>"off"</literal> this means that the <literal>Matplot</literal> is not
156                                 clipped.
157                             </para>
158                         </listitem>
159                         <listitem>
160                             <para>
161                                 <literal>"clipgrf"</literal> this means that the <literal>Matplot</literal> is clipped
162                                 outside the <literal>Axes</literal> box.
163                             </para>
164                         </listitem>
165                         <listitem>
166                             <para>
167                                 <literal>"on"</literal> this means that the <literal>Matplot</literal> is clipped
168                                 outside the rectangle given by property <literal>clip_box</literal>.
169                             </para>
170                         </listitem>
171                     </itemizedlist>
172                 </listitem>
173             </varlistentry>
174             <varlistentry>
175                 <term>clip_box: </term>
176                 <listitem>
177                     <para>
178                         this field is to determinate the <literal>clip_box</literal> property.
179                         By default its value should be an empty matrix if <literal>clip_state</literal> is
180                         <literal>"off"</literal>. Other cases the vector <literal>[x,y,w,h]</literal>
181                         (upper-left point width height) defines the portions of the <literal>Matplot</literal>
182                         to display, however <literal>clip_state</literal> property value will be changed.
183                     </para>
184                 </listitem>
185             </varlistentry>
186             <varlistentry>
187                 <term>user_data: </term>
188                 <listitem>
189                     <para>
190                         this field can be use to store any scilab variable in the 
191                         <literal>Matplot</literal> data structure, and to retreive it.
192                     </para>
193                 </listitem>
194             </varlistentry>
195         </variablelist>
196     </refsection>
197     <refsection>
198         <title>Examples</title>
199         <programlisting role="example"><![CDATA[ 
200 Matplot((1:xget("lastpattern")))
201 e=gce(); // get current entity
202
203 e.data=e.data($:-1:1) // reverse order
204  ]]></programlisting>
205 <scilab:image>
206 Matplot((1:xget("lastpattern")));
207 e=gce();
208 e.data=e.data($:-1:1);
209 </scilab:image>
210     </refsection>
211     <refsection role="see also">
212         <title>See Also</title>
213         <simplelist type="inline">
214             <member>
215                 <link linkend="set">set</link>
216             </member>
217             <member>
218                 <link linkend="get">get</link>
219             </member>
220             <member>
221                 <link linkend="delete">delete</link>
222             </member>
223             <member>
224                 <link linkend="grayplot">grayplot</link>
225             </member>
226             <member>
227                 <link linkend="Matplot">Matplot</link>
228             </member>
229             <member>
230                 <link linkend="Matplot1">Matplot1</link>
231             </member>
232             <member>
233                 <link linkend="graphics_entities">graphics_entities</link>
234             </member>
235             <member>
236                 <link linkend="grayplot_properties">grayplot_properties</link>
237             </member>
238         </simplelist>
239     </refsection>
240 </refentry>