135c5d501310253eaa9eace60b81c51e27111294
[scilab.git] / scilab / modules / graphics / help / en_US / 3d_plot / surface_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 - Djalel Abdemouche
5  * Copyright (C) INRIA - Fabrice Leray
6  * Copyright (C) 2012 - 2016 - Scilab Enterprises
7  * Copyright (C) 2018 - Samuel GOUGEON
8  *
9  * This file is hereby licensed under the terms of the GNU GPL v2.0,
10  * pursuant to article 5.3.4 of the CeCILL v.2.1.
11  * This file was originally licensed under the terms of the CeCILL v2.1,
12  * and continues to be available under such terms.
13  * For more information, see the COPYING file which you should have received
14  * along with this program.
15  *
16  -->
17 <refentry xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink"
18           xmlns:svg="http://www.w3.org/2000/svg" xmlns:mml="http://www.w3.org/1998/Math/MathML"
19           xmlns:db="http://docbook.org/ns/docbook" xmlns:scilab="http://www.scilab.org"
20           xml:lang="en" xml:id="surface_properties">
21     <refnamediv>
22         <refname>surface properties</refname>
23         <refpurpose>description of the 3D entities
24             properties
25         </refpurpose>
26     </refnamediv>
27     <refsection>
28         <title>Description</title>
29         <para>The Surface entity is a leaf of the graphics entities hierarchy. Two
30             classes appears under this type of entity : <literal>Plot3d</literal> and
31             <literal>Fac3d</literal> according to the plotting function or the way data is
32             entered. <literal>Fac3d</literal> and <literal>Plo3d</literal> entities are similar
33             but <literal>Fac3d</literal> is more complete and accept more options than
34             <literal>Plot3d</literal>. To always have <literal>Fac3d</literal> entities, simply
35             use <literal>genfac3d</literal> to pre-build matrices before using
36             <literal>plot3d</literal> or use the <literal>surf</literal> command.
37         </para>
38         <para>Here are the properties contained in a surface entity:</para>
39         <variablelist>
40             <varlistentry>
41                 <term>parent: </term>
42                 <listitem>
43                     <para>This property contains the handle of the parent. The parent of the
44                         surface entity should be of type <literal>"Axes"</literal> or
45                         <literal>"Compound"</literal>.
46                     </para>
47                 </listitem>
48             </varlistentry>
49             <varlistentry>
50                 <term>children: </term>
51                 <listitem>
52                     <para>
53                         This property contains a vector with the <literal>children</literal> of
54                         the handle. However, surface handles currently do not have any
55                         <literal>children</literal>.
56                     </para>
57                 </listitem>
58             </varlistentry>
59             <varlistentry>
60                 <term>visible: </term>
61                 <listitem>
62                     <para>
63                         <itemizedlist>
64                             <listitem>
65                                 <emphasis role="bold">"on"</emphasis> (default): The surface is
66                                 displayed, possibly with its mesh and markers.
67                             </listitem>
68                             <listitem>
69                                 <emphasis role="bold">"off"</emphasis> : The surface and its mesh
70                                 and markers are hidden.
71                             </listitem>
72                         </itemizedlist>
73                     </para>
74                 </listitem>
75             </varlistentry>
76             <varlistentry>
77                 <term>surface_mode: </term>
78                 <listitem>
79                     <para>
80                         <itemizedlist>
81                             <listitem>
82                                 <emphasis role="bold">"on"</emphasis> (default): facets (body and
83                                 edges) are drawn.
84                             </listitem>
85                             <listitem>
86                                 <emphasis role="bold">"off"</emphasis> : facets (body and edges)
87                                 are hidden. But markers -- if any -- are still displayed
88                                 (provided that <literal>.mark_mode = "on"</literal>).
89                             </listitem>
90                         </itemizedlist>
91                     </para>
92                 </listitem>
93             </varlistentry>
94             <varlistentry>
95                 <term>foreground: </term>
96                 <listitem>
97                     <para>
98                         If <literal>color_mode &gt;= 0</literal>, this field contains the color
99                         index used to draw the edges. If not, foreground is not used at all.
100                         The foreground value should be an integer color index (relative to the
101                         current colormap).
102                     </para>
103                 </listitem>
104             </varlistentry>
105             <varlistentry>
106                 <term>thickness: </term>
107                 <listitem>
108                     <para>This property is a positive real specifying the width of facets contours
109                         in pixels. The displayed width is actually determined by rounding the supplied width
110                         to the nearest integer. The only exception is vectorial export where the whole <literal>thickness</literal>
111                         value is considered.
112                     </para>
113                 </listitem>
114             </varlistentry>
115             <varlistentry>
116                 <term>mark_mode: </term>
117                 <listitem>
118                     <para>
119                         This field contains the default <literal>mark_mode</literal> property
120                         value for the surface. Its value should be <literal>"on"</literal> (marks
121                         drawn) or <literal>"off"</literal> (no marks drawn).
122                     </para>
123                 </listitem>
124             </varlistentry>
125             <varlistentry>
126                 <term>mark_style: </term>
127                 <listitem>
128                     <para>
129                         The <literal>mark_style</literal> property value is used to select the
130                         type of mark to use when <literal>mark_mode</literal> property is
131                         <literal>"on"</literal>. The value should be an integer in [0 14] which
132                         stands for: dot, plus, cross, star, filled diamond, diamond, triangle
133                         up, triangle down, diamond plus, circle, asterisk, square, triangle
134                         right, triangle left and pentagram.The figure below shows the aspects of the marks
135                         depending on the <literal>mark_style</literal> and the
136                         <literal>mark_foreground</literal> and
137                         <literal>mark_background</literal> properties.
138                     </para>
139                     <para>
140                         <inlinemediaobject>
141                             <imageobject>
142                                 <imagedata fileref="../../images/marks.svg"/>
143                             </imageobject>
144                         </inlinemediaobject>
145                     </para>
146                 </listitem>
147             </varlistentry>
148             <varlistentry>
149                 <term>mark_size_unit: </term>
150                 <listitem>
151                     <para>
152                         This field contains the default <literal>mark_size_unit</literal>
153                         property value. If <literal>mark_size_unit</literal> is set to
154                         <literal>"point"</literal>, then the <literal>mark_size</literal> value is
155                         directly given in points. When <literal>mark_size_unit</literal> is set to
156                         <literal>"tabulated"</literal>, <literal>mark_size</literal> is computed relative
157                         to the font size array: therefore, its value should be an integer in
158                         [0 5] which stands for 8pt, 10pt, 12pt, 14pt, 18pt and 24pt. Note that
159                         <link linkend="plot3d">plot3d</link> and pure scilab functions use
160                         <literal>tabulated</literal> mode as default ; when using the
161                         <link linkend="surf">surf</link> (or <link linkend="plot">plot</link> for 2D lines) function, the
162                         <literal>point</literal> mode is automatically enabled.
163                     </para>
164                 </listitem>
165             </varlistentry>
166             <varlistentry>
167                 <term>mark_size: </term>
168                 <listitem>
169                     <para>
170                         The <literal>mark_size</literal> property is used to select the type of
171                         size of the marks when <literal>mark_mode</literal> property is
172                         <literal>"on"</literal>. Its value should be an integer between 0 and 5
173                         which stands for 8pt, 10pt, 12pt, 14pt, 18pt and 24pt.
174                     </para>
175                 </listitem>
176             </varlistentry>
177             <varlistentry>
178                 <term>mark_foreground: </term>
179                 <listitem>
180                     <para>
181                         This field contains the <literal>mark_foreground</literal> property
182                         value which is the marks' edge color. Its value should be a color
183                         index (relative to the current color_map) or 0 for transparent edge.
184                     </para>
185                 </listitem>
186             </varlistentry>
187             <varlistentry>
188                 <term>mark_background: </term>
189                 <listitem>
190                     <para>
191                         This field contains the <literal>mark_background</literal> property
192                         value which is the marks' face color. Its value should be a color
193                         index (relative to the current color_map) or 0 for transparent face.
194                     </para>
195                 </listitem>
196             </varlistentry>
197             <varlistentry>
198                 <term>data: </term>
199                 <listitem>
200                     <para>
201                         This field defines a <literal>tlist</literal> data structure of type
202                         "3d" composed of a row and column indices of each element as the x-,
203                         y- and z-coordinates contained respectively in
204                         <literal>data.x</literal>,<literal>data.y</literal> and <literal>data.z</literal>. The
205                         complementary field named <literal>data.color</literal> is available in case
206                         a real color vector or matrix is specified. If none,
207                         <literal>data.color</literal> is not listed. The surface is painted
208                         according to <literal>color_mode </literal>and <literal>color_flag</literal>
209                         properties.
210                     </para>
211                 </listitem>
212             </varlistentry>
213             <varlistentry>
214                 <term>color_mode: </term>
215                 <listitem>
216                     <para>
217                         color index in <literal>[-size(colormap), size(colormap)]</literal>
218                         <para>
219                             If <emphasis role="italic">color_flag == 0</emphasis> :
220                             The uniform color of the whole upward surface is set to the index
221                             <literal>abs(color_mode)</literal>.
222                         </para>
223                         <para>
224                             In addition, whatever is <literal>color_flag</literal>,
225                             <itemizedlist>
226                                 <listitem>
227                                     <literal>color_mode = 0</literal> makes facets hollow and displays
228                                     only the surface's mesh.
229                                 </listitem>
230                                 <listitem>
231                                     <literal>color_mode > 0</literal> displays facets bodies and
232                                     edges.
233                                 </listitem>
234                                 <listitem>
235                                     <literal>color_mode &lt; 0</literal> hides the mesh and displays
236                                     only facets bodies.
237                                 </listitem>
238                             </itemizedlist>
239                         </para>
240                         <para>
241                             When it is displayed, the mesh color is set to <varname>foreground</varname>.
242                         </para>
243                     </para>
244                 </listitem>
245             </varlistentry>
246             <varlistentry>
247                 <term>color_flag: </term>
248                 <listitem>
249                     <para>Chooses the algorithm used to set the color of the body of the upward face
250                         of facets, when it is displayed.
251                     </para>
252                     <para>
253                         In addition,
254                         <itemizedlist>
255                             <listitem>
256                                 <varname>color_mode</varname> rules the display of the mesh
257                                 (facets edges) and/or body of facets.
258                             </listitem>
259                             <listitem>
260                                 <varname>foreground</varname> and <varname>thickness</varname> rules
261                                 the line color and thickness of the mesh.
262                             </listitem>
263                             <listitem>
264                                 <varname>hiddencolor</varname> rules the color of the backward facets
265                                 face.
266                             </listitem>
267                         </itemizedlist>
268                     </para>
269                     <para>
270                         Here below,
271                         <itemizedlist>
272                             <listitem>
273                                 <emphasis role="bold">nf</emphasis> stands for the number of facets
274                                 of the surface.
275                             </listitem>
276                             <listitem>
277                                 <emphasis role="bold">n</emphasis> stands for the number of
278                                 vertices of each facet. All facets have the same number of vertices.
279                             </listitem>
280                         </itemizedlist>
281                         Then we have:
282                     </para>
283                     <itemizedlist>
284                         <listitem>
285                             <para>
286                                 <term>color_flag = 0</term> <emphasis role="bold">(uniform color)</emphasis> :
287                             </para>
288                             <para>All facets are painted using the same color index and method
289                                 defined by <literal>color_mode</literal> (see above).
290                             </para>
291                         </listitem>
292                         <listitem>
293                             <para>
294                                 <term>color_flag = 1</term>
295                                 <emphasis role="bold">(uniform color on each facet, mapping Z)</emphasis> :
296                             </para>
297                             <para>
298                                 The average Z of each facet is computed according to the Z of
299                                 its vertices.
300                                 Then the [Zmin, Zmax] range of facets Z is computed.
301                                 Each facet gets its uniform color in [1, size(colormap)] according
302                                 to its Z position in [Zmin, Zmax].
303                             </para>
304                         </listitem>
305                     </itemizedlist>
306                     <para>
307                         <emphasis role="bold">color_flag== 2,3 or 4</emphasis> values
308                         are only available with <literal>Fac3d</literal> entities.
309                         These algorithms require the <literal>data.color</literal> input to set
310                         facets colors. If <literal>data.color</literal> is empty, the
311                         <literal>color_flag=1</literal> fallback algorithm is used.
312                     </para>
313                     <itemizedlist>
314                         <listitem>
315                             <para>
316                                 <term>color_flag = 2</term> <emphasis role="bold">('flat' shading)</emphasis> :
317                             </para>
318                             <para>All facets are painted using the color index given in the
319                                 <literal>data.color</literal> property (one color per facet is
320                                 needed). Two cases are then possible :
321                             </para>
322                             <orderedlist>
323                                 <listitem>
324                                     <para>
325                                         <literal>data.color</literal> is a vector of as many
326                                         <literal>color</literal> indices as there are facets,
327                                         <literal>color(i)</literal> being the color index for the
328                                         facet <literal>#i</literal> :
329                                         <itemizedlist>
330                                             <listitem>
331                                                 <literal>color(i)>0</literal>: the boundary of the facet
332                                                 is drawn with current line style and color.
333                                             </listitem>
334                                             <listitem>
335                                                 <literal>color(i)&lt;0</literal>: the facet's
336                                                 boundary is not drawn, and <literal>-color(i)</literal>
337                                                 is used as facet's color.
338                                             </listitem>
339                                         </itemizedlist>
340                                     </para>
341                                 </listitem>
342                                 <listitem>
343                                     <para>
344                                         <literal>data.color</literal> is a matrix of color indices,
345                                         of size (n,nf). Then, the actual color index of the facet is
346                                         set to the average color of all its vertices.
347                                     </para>
348                                 </listitem>
349                             </orderedlist>
350                         </listitem>
351                         <listitem>
352                             <para>
353                                 <term>color_flag = 3</term>
354                                 <emphasis role="bold">(interpolated shading on each facet)</emphasis> :
355                             </para>
356                             <para>
357                                 Facets painting is done by interpolating their vertices colors.
358                                 The indices of vertices color are given in the
359                                 <literal>data.color</literal> property (one color per vertex is
360                                 needed). Two cases are possible :
361                             </para>
362                             <orderedlist>
363                                 <listitem>
364                                     <para>
365                                         <literal>data.color</literal> is a vector of <literal>nf</literal>
366                                         <literal>color</literal> indices,
367                                         <literal>color(i)</literal> being the index of the flat uniform
368                                         color of the facet <literal>#i</literal>.
369                                     </para>
370                                 </listitem>
371                                 <listitem>
372                                     <para>
373                                         <literal>data.color</literal> is a color matrix of size
374                                         (n,nf): The facet #i is drawn with some graded colors
375                                         interpolated between the <literal>color(:,i)</literal>
376                                         colors of its vertices.
377                                     </para>
378                                     <note>
379                                         If the Z coordinate of vertices has been assigned to
380                                         <literal>data.color</literal>, this mode allows to map local Z
381                                         with colors, down to the facet scale. See also the
382                                         <literal>.cdata_mapping</literal> property.
383                                     </note>
384                                 </listitem>
385                             </orderedlist>
386                         </listitem>
387                         <listitem>
388                             <para>
389                                 <term> color_flag = 4</term>
390                                 <emphasis role="bold">(Matlab-like 'flat' shading)</emphasis> :
391                             </para>
392                             <para>
393                                 Same as <literal>color_flag==2</literal>, except that, when
394                                 <literal>data.color</literal> is a color matrix, each facet #i is
395                                 painted with the uniform <literal>color(1,i)</literal> of its
396                                 first vertex (instead of the average color of all its vertices).
397                                 Other vertices colors are ignored.
398                             </para>
399                         </listitem>
400                     </itemizedlist>
401                 </listitem>
402             </varlistentry>
403             <varlistentry>
404                 <term>cdata_mapping: </term>
405                 <listitem>
406                     <para>
407                         <literal>'scaled'</literal> or <literal>'direct'</literal>.
408                         Used only for <literal>color_flag=2|3|4</literal>
409                         (<literal>Fac3d</literal> handles), with some <literal>data.color</literal>
410                         defined. Otherwise ignored.
411                         <itemizedlist>
412                             <listitem>
413                                 <para>
414                                     <emphasis>"direct"</emphasis>: <literal>data.color</literal>
415                                     values are directly considered as color indices in the
416                                     current gcf().color_map.
417                                 </para>
418                             </listitem>
419                             <listitem>
420                                 <para><emphasis>"scaled"</emphasis>: <literal>c=data.color</literal>
421                                     values are linearly mapped on the interval <literal>[1,nC]</literal>,
422                                     with <literal>nC=size(gcf().color_map,1)</literal> is the total
423                                     number of colors in the current colormap. Then,
424                                     <literal>min(c)</literal> represents the color #1, and
425                                     <literal>max(c)</literal> represents the color #nC.
426                                 </para>
427                             </listitem>
428                         </itemizedlist>
429                     </para>
430                 </listitem>
431             </varlistentry>
432             <varlistentry>
433                 <term>hiddencolor: </term>
434                 <listitem>
435                     <para>
436                         Positive index of the color of the uniform backward faces of all facets.
437                         If a negative or null value is provided, backward faces are painted with
438                         the same respective colors as the upward visible ones.
439                     </para>
440                 </listitem>
441             </varlistentry>
442             <varlistentry>
443                 <term>clip_state: </term>
444                 <listitem>
445                     <para>
446                         This field contains the <literal>clip_state</literal> property value for
447                         the surface. It should be :
448                     </para>
449                     <itemizedlist>
450                         <listitem>
451                             <para>
452                                 <literal>"off"</literal> this means that the surface is not
453                                 clipped.
454                             </para>
455                         </listitem>
456                         <listitem>
457                             <para>
458                                 <literal>"clipgrf"</literal> this means that the surface is clipped
459                                 outside the Axes box.
460                             </para>
461                         </listitem>
462                         <listitem>
463                             <para>
464                                 <literal>"on"</literal> this means that the surface is clipped
465                                 outside the rectangle given by property clip_box.
466                             </para>
467                         </listitem>
468                     </itemizedlist>
469                 </listitem>
470             </varlistentry>
471             <varlistentry>
472                 <term>clip_box: </term>
473                 <listitem>
474                     <para>
475                         This field is to determinate the <literal>clip_box</literal> property.
476                         By Default its value should be an empty matrix if clip_state is "off".
477                         Other cases the vector <literal>[x,y,w,h]</literal> (upper-left point width
478                         height) defines the portions of the surface to display, however
479                         <literal>clip_state</literal> property value will be changed.
480                     </para>
481                 </listitem>
482             </varlistentry>
483             <varlistentry>
484                 <term>use_color_material: </term>
485                 <listitem>
486                     <para>This field is use to enable the use of the surface color as diffuse color.
487                         Its default value is <literal>"on"</literal>.
488                     </para>
489                 </listitem>
490             </varlistentry>
491             <varlistentry>
492                 <term>material_shininess: </term>
493                 <listitem>
494                     <para>This field defines the shininess level of the surface. This parameter
495                         controls the shinines color spreading in the surface. Any positive value can
496                         be used. Good values to use are in the [0 10] range, where low values generates
497                         strong highlight and high values generates barely perceptible highlights.
498                         The default value is <literal>"2"</literal>.
499                     </para>
500                 </listitem>
501             </varlistentry>
502             <varlistentry>
503                 <term>ambient_color: </term>
504                 <listitem>
505                     <para>This field defines the ambient color of the surface.
506                         The color is defined by a 3 element vector <literal>"[red, green, blue]"</literal>
507                         with each element in the range [0, 1].
508                         The default value is <literal>"[1 1 1]"</literal>.
509                     </para>
510                 </listitem>
511             </varlistentry>
512             <varlistentry>
513                 <term>diffuse_color: </term>
514                 <listitem>
515                     <para>This field defines the diffuse color of the surface.
516                         The color is defined by a 3 element vector <literal>"[red, green, blue]"</literal>
517                         with each element in the range [0, 1]. Notice that this field is
518                         only used when use_color_material is disabled.
519                         The default value is <literal>"[1 1 1]"</literal>.
520                     </para>
521                 </listitem>
522             </varlistentry>
523             <varlistentry>
524                 <term>specular_color: </term>
525                 <listitem>
526                     <para>This field defines the specular color of the surface.
527                         The color is defined by a 3 element vector <literal>"[red, green, blue]"</literal>
528                         with each element in the range [0, 1].
529                         The default value is <literal>"[1 1 1]"</literal>.
530                     </para>
531                 </listitem>
532             </varlistentry>
533             <varlistentry>
534                 <term>user_data: </term>
535                 <listitem>
536                     <para>This field can be use to store any scilab variable in the surface
537                         data structure, and to retrieve it.
538                     </para>
539                 </listitem>
540             </varlistentry>
541         </variablelist>
542     </refsection>
543     <refsection>
544         <title>Examples</title>
545         <programlisting role="example"><![CDATA[
546 //create a figure
547 t=[0:0.3:2*%pi]'; z=sin(t)*cos(t');
548 [xx,yy,zz]=genfac3d(t,t,z);
549 plot3d([xx xx],[yy yy],list([zz zz+4],[4*ones(1,400) 5*ones(1,400)]))
550 h=get("hdl") //get handle on current entity (here the surface)
551 a=gca(); //get current axes
552 a.rotation_angles=[40,70];
553 a.grid=[1 1 1];
554 //make grids
555 a.data_bounds=[-6,0,-1;6,6,5];
556 a.axes_visible="off";
557 //axes are hidden a.axes_bounds=[.2 0 1 1];
558 f=get("current_figure");
559 //get the handle of the parent figure
560 f.color_map=hotcolormap(64);
561 //change the figure colormap
562 h.color_flag=1;
563 //color according to z
564 h.color_mode=-2;
565 //remove the facets boundary
566 h.color_flag=2;
567 //color according to given colors
568 h.data.color=[1+modulo(1:400,64),1+modulo(1:400,64)];
569 //shaded
570 h.color_flag=3;
571
572 scf(2); // creates second window and use surf command
573 subplot(211)
574 surf(z,'cdata_mapping','direct','facecol','interp')
575
576 subplot(212)
577 surf(t,t,z,'edgeco','b','marker','d','markersiz',9,'markeredg','red','markerfac','k')
578 e=gce();
579 e.color_flag=1 // color index proportional to altitude (z coord.)
580 e.color_flag=2; // back to default mode
581 e.color_flag= 3; // interpolated shading mode (based on blue default color because field data.color is not filled)
582  ]]></programlisting>
583     </refsection>
584     <refsection role="see also">
585         <title>See also</title>
586         <simplelist type="inline">
587             <member>
588                 <link linkend="set">set</link>
589             </member>
590             <member>
591                 <link linkend="get">get</link>
592             </member>
593             <member>
594                 <link linkend="delete">delete</link>
595             </member>
596             <member>
597                 <link linkend="plot3d">plot3d</link>
598             </member>
599             <member>
600                 <link linkend="plot3d1">plot3d1</link>
601             </member>
602             <member>
603                 <link linkend="plot3d2">plot3d2</link>
604             </member>
605             <member>
606                 <link linkend="surf">surf</link>
607             </member>
608             <member>
609                 <link linkend="grayplot_properties">grayplot_properties</link>
610             </member>
611             <member>
612                 <link linkend="Matplot_properties">Matplot_properties</link>
613             </member>
614             <member>
615                 <link linkend="graphics_entities">graphics_entities</link>
616             </member>
617         </simplelist>
618     </refsection>
619 </refentry>