<?xml version="1.0" encoding="UTF-8"?>
<!--
 * Scilab ( https://www.scilab.org/ ) - This file is part of Scilab
 * Copyright (C) INRIA - Djalel Abdemouche
 *
 * Copyright (C) 2012 - 2016 - Scilab Enterprises
 *
 * This file is hereby licensed under the terms of the GNU GPL v2.0,
 * pursuant to article 5.3.4 of the CeCILL v.2.1.
 * This file was originally licensed under the terms of the CeCILL v2.1,
 * and continues to be available under such terms.
 * For more information, see the COPYING file which you should have received
 * along with this program.
 *
 -->
<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="param3d_properties">
    <refnamediv>
        <refname>param3d properties</refname>
        <refpurpose>description of the 3D curves
            entities properties
        </refpurpose>
    </refnamediv>
    <refsection>
        <title>Description</title>
        <para>The Param3d entity is a leaf of the graphics entities hierarchy.</para>
        <variablelist>
            <varlistentry>
                <term>visible: </term>
                <listitem>
                    <para>
                        This field contains the <literal>visible</literal> property value for
                        the entity . It should be <literal>"on" </literal> or <literal>"off"</literal> .
                        By default, the curves are visibles, the value's property is
                        <literal>"on" </literal>. If <literal>"off"</literal> the curves are not drawn on
                        the screen.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>data: </term>
                <listitem>
                    <para>This field contains the coordinates of the 3d curves. it is the
                        matrix <literal>[X,Y,Z]</literal> such as <literal>X(:,i)</literal>,
                        <literal>Y(:,i)</literal>, <literal>Z(:,i)</literal> contain the 3D coordinates of
                        the <literal>i</literal>'th curve. This field contains the default
                        <literal>line_style</literal> property value for Segs, Arcs, Rectangle and
                        Polyline objects.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>line_mode: </term>
                <listitem>
                    <para>
                        This field contains the default <literal>line_mode</literal> property
                        value for the polyline. Its value should be <literal>"on" </literal>(line
                        drawn) or <literal>"off"</literal> (no line drawn).
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>line_style: </term>
                <listitem>
                    <para>This field selects the type of line to be used to draw lines . Its
                        value should be an integer in [1 6]. 1 stands for solid, the other
                        values stand for a selection of dashes.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>polyline_style: </term>
                <listitem>
                    <para>This field selects the way curve are drawn: interpolated
                        (default), staircase, barplot, arrowed and filled modes are available
                        through integer index [1:5].
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>mark_mode: </term>
                <listitem>
                    <para>
                        This field contains the default <literal>mark_mode</literal> property
                        value. Its value should be <literal>"on"</literal> or <literal>"off"</literal>
                        (default value).
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>mark_style: </term>
                <listitem>
                    <para>
                        This field contains the default <literal>mark_style</literal> property
                        value. The <literal>mark_style</literal> selects the type of mark to be
                        displayed. Its value should be an integer in [0 9] which stands for:
                        dot, plus, cross, star, filled diamond, diamond, triangle up, triangle
                        down, trefle and circle. The figure below shows the aspects of the marks
                        depending on the <literal>mark_style</literal> and the
                        <literal>mark_foreground</literal> and
                        <literal>mark_background</literal> properties.
                    </para>
                    <para>
                        <mediaobject>
                            <imageobject>
                                <imagedata fileref="../../images/marks.svg"/>
                            </imageobject>
                        </mediaobject>
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>mark_size_unit: </term>
                <listitem>
                    <para>
                        This field contains the default <literal>mark_size_unit</literal>
                        property value. If <literal>mark_size_unit</literal> is set to
                        <literal>"point"</literal>, then the <literal>mark_size</literal> value is
                        directly given in points. When <literal>mark_size_unit</literal> is set to
                        <literal>"tabulated"</literal>, <literal>mark_size</literal> is computed relative
                        to the font size array: therefore, its value should be an integer in
                        [0 5] which stands for 8pt, 10pt, 12pt, 14pt, 18pt and 24pt. Note that
                        <link linkend="param3d">param3d</link> and pure scilab functions use
                        <literal>tabulated</literal> mode as default ; when using <link linkend="plot">plot</link>
                        function, the <literal>point</literal> mode is automatically enabled.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>mark_size: </term>
                <listitem>
                    <para>
                        This field contains the default <literal>mark_size</literal> property
                        value
                    </para>
                    <para>
                        . The <literal>mark_size</literal> selects the font size of the mark to
                        be displayed. Its value should be an integer in [0 5] which stands for
                        8pt, 10pt, 12pt, 14pt, 18pt and 24pt.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>mark_foreground: </term>
                <listitem>
                    <para>
                        This field contains the <literal>mark_foreground</literal> property
                        value which is the marks' edge color. Its value should be a color
                        index (relative to the current color_map).
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>mark_background: </term>
                <listitem>
                    <para>
                        This field contains the <literal>mark_background</literal> property
                        value which is the marks' face color. Its value should be a color
                        index (relative to the current color_map).
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>thickness: </term>
                <listitem>
                    <para>
                        This field contains the default <literal>thickness</literal> value of
                        the lines used to draw the axes and the curves. It should be a
                        positive integer.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>foreground: </term>
                <listitem>
                    <para>This field contains the color index used to draw the curves. Its
                        value should be a color index (relative to the current colormap).
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>clip_state: </term>
                <listitem>
                    <para>
                        This field contains the default <literal>clip_state</literal> property
                        value. Its value should be :
                    </para>
                    <itemizedlist>
                        <listitem>
                            <para>
                                <literal>"off"</literal> this means that all curves created after
                                that are not clipped (default value).
                            </para>
                        </listitem>
                        <listitem>
                            <para>
                                <literal>"clipgrf"</literal> this means that all curves created
                                after that are clipped outside the Axes boundaries.
                            </para>
                        </listitem>
                        <listitem>
                            <para>
                                <literal>"on"</literal> this means that all curves created after
                                that are clipped outside the rectangle given by property
                                clip_box.
                            </para>
                        </listitem>
                    </itemizedlist>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>clip_box: </term>
                <listitem>
                    <para>
                        This field contains the default <literal>clip_box</literal> property
                        value. Its value should be an empty matrix if clip_state is
                        <literal>"off"</literal>. Other case the clipping is given by the vector
                        <literal>[x,y,w,h]</literal> (upper-left point width height).
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>user_data: </term>
                <listitem>
                    <para>This field can be use to store any scilab variable in the
                        param3d data structure, and to retrieve it.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>parent: </term>
                <listitem>
                    <para>This property contains the handle of the parent. The parent of the
                        3D curves entity should be of type <literal>"Axes"</literal> or
                        <literal>"Compound"</literal>.
                    </para>
                </listitem>
            </varlistentry>
        </variablelist>
    </refsection>
    <refsection>
        <title>Examples</title>
        <programlisting role="example"><![CDATA[

   a=get("current_axes");//get the handle of the newly created axes
   t=[0:0.1:5*%pi]';
   param3d1([sin(t),sin(2*t)],[cos(t),cos(2*t)],[t/10,sin(t)])

   a.rotation_angles=[65,75];
   a.data_bounds=[-1,-1,-1;1,1,2]; //boundaries given by data_bounds
   a.thickness = 2;
   h=a.children //get the handle of the param3d entity: an Compound composed of 2 curves
   h.children(1).foreground = 3 // first curve
   curve2 = h.children(2);
   curve2.foreground = 6;
   curve2.mark_style = 2;


  ]]></programlisting>
    </refsection>
    <refsection role="see also">
        <title>See also</title>
        <simplelist type="inline">
            <member>
                <link linkend="set">set</link>
            </member>
            <member>
                <link linkend="get">get</link>
            </member>
            <member>
                <link linkend="delete">delete</link>
            </member>
            <member>
                <link linkend="param3d">param3d</link>
            </member>
            <member>
                <link linkend="param3d1">param3d1</link>
            </member>
            <member>
                <link linkend="graphics_entities">graphics_entities</link>
            </member>
        </simplelist>
    </refsection>
    <refsection>
        <title>History</title>
        <revhistory>
            <revision>
                <revnumber>5.4.0</revnumber>
                <revremark>line_style value 0 is obsolete, use 1 instead (both are equivalent for SOLID). Using value 0 will produce an error in Scilab 5.4.1.</revremark>
            </revision>
        </revhistory>
    </refsection>
</refentry>
