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", "argb".
  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                         <listitem>
 152                             <para>
 153                                 When image_type is equal to argb, hypermat of int8 or uint8 will give the ARGB components, hypermat of doubles will give normalized ARGB 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 ARGB colors, matrices of uint32 will give ARGB colors.
 154                             </para>
 155                         </listitem>
 156                     </itemizedlist>
 157                 </listitem>
 158             </varlistentry>
 159             <varlistentry>
 160                 <term>clip_state: </term>
 161                 <listitem>
 162                     <para>
 163                         this field contains the <literal>clip_state</literal> property value for
 164                         the <literal>Matplot</literal>. It should be :
 165                     </para>
 166                     <itemizedlist>
 167                         <listitem>
 168                             <para>
 169                                 <literal>"off"</literal> this means that the <literal>Matplot</literal> is not
 170                                 clipped.
 171                             </para>
 172                         </listitem>
 173                         <listitem>
 174                             <para>
 175                                 <literal>"clipgrf"</literal> this means that the <literal>Matplot</literal> is clipped
 176                                 outside the <literal>Axes</literal> box.
 177                             </para>
 178                         </listitem>
 179                         <listitem>
 180                             <para>
 181                                 <literal>"on"</literal> this means that the <literal>Matplot</literal> is clipped
 182                                 outside the rectangle given by property <literal>clip_box</literal>.
 183                             </para>
 184                         </listitem>
 185                     </itemizedlist>
 186                 </listitem>
 187             </varlistentry>
 188             <varlistentry>
 189                 <term>clip_box: </term>
 190                 <listitem>
 191                     <para>
 192                         this field is to determinate the <literal>clip_box</literal> property.
 193                         By default its value should be an empty matrix if <literal>clip_state</literal> is
 194                         <literal>"off"</literal>. Other cases the vector <literal>[x,y,w,h]</literal>
 195                         (upper-left point width height) defines the portions of the <literal>Matplot</literal>
 196                         to display, however <literal>clip_state</literal> property value will be changed.
 197                     </para>
 198                 </listitem>
 199             </varlistentry>
 200             <varlistentry>
 201                 <term>user_data: </term>
 202                 <listitem>
 203                     <para>
 204                         this field can be use to store any scilab variable in the
 205                         <literal>Matplot</literal> data structure, and to retreive it.
 206                     </para>
 207                 </listitem>
 208             </varlistentry>
 209         </variablelist>
 210     </refsection>
 211     <refsection>
 212         <title>Examples</title>
 213         <programlisting role="example"><![CDATA[
 214 Matplot((1:xget("lastpattern")))
 215 e=gce(); // get current entity
 216
 217 e.data=e.data($:-1:1) // reverse order
 218  ]]></programlisting>
 219         <scilab:image>
 220             Matplot((1:xget("lastpattern")));
 221             e=gce();
 222             e.data=e.data($:-1:1);
 223         </scilab:image>
 224     </refsection>
 225     <refsection role="see also">
 226         <title>See Also</title>
 227         <simplelist type="inline">
 228             <member>
 229                 <link linkend="set">set</link>
 230             </member>
 231             <member>
 232                 <link linkend="get">get</link>
 233             </member>
 234             <member>
 235                 <link linkend="delete">delete</link>
 236             </member>
 237             <member>
 238                 <link linkend="grayplot">grayplot</link>
 239             </member>
 240             <member>
 241                 <link linkend="Matplot">Matplot</link>
 242             </member>
 243             <member>
 244                 <link linkend="Matplot1">Matplot1</link>
 245             </member>
 246             <member>
 247                 <link linkend="graphics_entities">graphics_entities</link>
 248             </member>
 249             <member>
 250                 <link linkend="grayplot_properties">grayplot_properties</link>
 251             </member>
 252         </simplelist>
 253     </refsection>
 254     <refsection>
 255         <title>History</title>
 256         <revhistory>
 257             <revision>
 258                 <revnumber>5.5.0</revnumber>
 259                 <revremark>
 260                     Property image_type introduced.
 261                 </revremark>
 262                 <revremark>
 263                     Property rect introduced.
 264                 </revremark>
 265             </revision>
 266         </revhistory>
 267     </refsection>
 268 </refentry>