.. highlightlang:: us

.. index:: XYZSetProps

.. _xyzsetprops:

XYZSetProps
===========

.. us.tag  XYZSetProps NOTREADYENGLISH XYZSet New403 Changed412 Changed5300

:ref:`XYZSetProps` sets the dataset properties of a 3D dataset.

.. function::  bool = XYZSetProps(hData, ssProps)

.. us.return

**Return Value**

If the function succeeds, the return value bool is TRUE (1); otherwise it is
FALSE (0). 

.. us.params

**Parameters**

.. uparam:: hData

   Is the handle of a dataset created with :ref:`XYZCreate`.

.. uparam:: ssProps

   *ssProps* is a scalar string with ``NAME='VALUE'``-pairs. Each pair sets one
   property. The property pairs are separated by a blank, a newline or a tab
   character.

.. us.example

**Example**

The following example sets the bubble plot option and turns off the isolines.
All other properties are not changed.

::

   XYZSetProps(hData, "bubble='1' isolines='0'")

Calculates isolines and sets lables the isolines at random positions 
(one label per iso line)::

   XYZSetProps(hData, "iso-values='auto' iso-label-type='auto'")

Another Example::

   XYZSetProps(hData, "hull-label-distance='0.2' " + ...
           "marker='1' marker-label='0' " +  ...
           "iso-pen-color='silver' iso-values = 'auto:15' " + ...
           "iso-label-type ='random'"); 

Set iso line colors::

       rmColor = [255,0,0;  255,127,0;  0,255,0;  0,0,255];
       // the last color (blue) will be used for all remaining iso lines
       // (5., 6., etc.).
       ssColor = sty_RGB_to_prop_color(rmColor);
       ssProp = sprintf("iso-pen-color = '%s'", ssColor);
       XYZSetProps(hData, ssProp);

.. us.comment

**Comment**

The following table contains all properties of a 3D dataset. The column Type 
contains the valid value range. A property can have one of the following 
data types: bool, int, double, color, curve_style, marker_style.

bool is the value '0' or '1'. '0' means the off, false and'1' means on or true.

int is an in integer number ('1', '-1', '144').

double is a real number like '1.23', '5000', '1e3'.

color is a name like 'mediumblue' (see color table), or a value like '#0000CD' 
or an expression of the form 'rgb(0,0,205)'.

curve_style can be 'solid' (or '0'), 'dash', 'dot', 'dashdot',
'dashdotdot' ( or '4').

Properties in alphabetic order:

.. list-table::
   :header-rows: 1

   * - Property
     - Type
     - Default Value
     - Comment
   * - base-value-3d
     - double
     - ``'0.0'``
     - 
   * - bubble
     - bool
     - ``'0'``
     - 
   * - bubble-color-type
     - int
     - ``'1'``
     - 
   * - bubble-size-max
     - double
     - ``'1.0'``
     - Max bubble size in centimeter.
   * - bubble-size-min
     - double
     - ``'0.2'``
     - Min bubble size in centimeter.
   * - bubble-scale-max
     - double
     - ``'2.0'``
     - Is used to set the max value instead of the data max value, if
       ``bubble-use-scaleval`` is set to 1.
   * - bubble-scale-min
     - double
     - ``'1.0'``
     - Is used to set the min value instead of the data min value, if
       ``bubble-use-scaleval`` is set to 1.
   * - bubble-size-type
     - int
     - ``'1'``
     - 1: diameter, 2: area
   * - bubble-no-edge
     - int
     - ``'0'``
     - If set to 1 an edge line is displayed.
   * - bubble-use-scaleval
     - int
     - ``'0'``
     - If set to 1 the min/max scale value is used to calculate the bubble size.
   * - color-matrix
     - bool
     - ``'0'``
     - 
   * - color-matrix-line-color
     - color
     - 'black'
     - 
   * - color-matrix-line-width
     - int
     - ``'2'``
     - 
   * - color-matrix-showzval
     - bool
     - ``'1'``
     - 
   * - color-matrix-cliptext
     - bool
     - ``'1'``
     - 
   * - color-matrix-shrinktext
     - bool
     - ``'1'``
     - 
   * - color-matrix-showedge
     - bool
     - ``'1'``
     - 
   * - color-matrix-clipzmin
     - bool
     - ``'0'``
     - 
   * - filled
     - bool
     - ``'0'``
     - 
   * - hull-label
     - bool
     - ``'1'``
     - 
   * - hull-label-distance
     - double
     - ``'0.3'``
     - distance in centimeters
   * - hull-label-horizontal
     - bool
     - ``'1'``
     - 
   * - hull-pen-color
     - color
     - ``'black'``
     - 
   * - hull-pen-style
     - curve_style
     - ``'solid'``
     - possible values: '0' or 'solid' ,  '1' or 'dash', '2' or'dot',  '3' or 'dashdot',  '4' or 'dashdotdot'.
   * - hull-pen-width
     - int
     - ``'4'``
     - 
   * - hull-spline
     - bool
     - ``'0'``
     - 
   * - hull-type
     - int
     - ``'1'``
     - 
   * - inside-3d-pen-color
     - color
     - ``'black'``
     - 
   * - inside-3d-pen-style
     - curve_style
     - ``'solid'``
     - possible values: '0' or 'solid' ,  '1' or 'dash', '2' or'dot',  '3' or 'dashdot',  '4' or 'dashdotdot'.
   * - inside-3d-pen-width
     - int
     - ``'2'``
     - 
   * - inside-color-3d
     - color
     - ``'white'``
     - 
   * - interpolation-density
     - string
     - ``'40,40'``
     - 
   * - interpolation-on-grid
     - bool
     - ``'0'``
     - 
   * - interpolation-range
     - string
     - ``'auto'``
     - 
   * - interpolation-smooth-factor
     - int
     - ``'0'``
     - 
   * - interpolation-type
     - int
     - ``'3'``
     - '1' (linear Interpolation), '2' (Non linear Interpolation), '3' (Thin-Plate-Spline Interpolation)
   * - iso-colors
     - string
     - ``'auto'``
     - 
   * - iso-colors-alpha
     - string
     - ``'auto'``
     - Scalar or comma separated list of alpha values.
   * - iso-colormap
     - string
     - ``'viridis'``
     - 
   * - iso-colormap-enable
     - bool
     - ``'0'``
     - 
   * - iso-label-type
     - string
     - ``'auto'``
     - 
   * - iso-min-color
     - string
     - ``'auto'``
     - 
   * - iso-min-color-alpha
     - string
     - ``'auto'``
     - Alpha value for for min color.
   * - iso-pen-color
     - string
     - ``'black'``
     - 
   * - iso-pen-styles
     - string
     - ``'solid'``
     - possible values: '0' or 'solid' ,  '1' or 'dash', '2' or'dot',  '3' or 'dashdot',  '4' or 'dashdotdot'.
   * - iso-pen-width
     - string
     - ``'1'``
     - 
   * - iso-values
     - string
     - ``'auto'``
     - 
   * - isolines
     - bool
     - ``'1'``
     - 
   * - isolines-3d
     - bool
     - ``'0'``
     - 
   * - label-font-angle
     - double
     - ``'0.0'``
     - 
   * - label-font-color
     - color
     - ``'black'``
     - 
   * - label-font-face-name
     - string
     - ``''``
     - 
   * - label-font-height
     - int
     - ``'-9'``
     - 
   * - label-font-italic
     - bool
     - ``'0'``
     - 
   * - label-font-pitch-and-family
     - int
     - ``'0'``
     - 
   * - label-font-strikeout
     - bool
     - ``'0'``
     - 
   * - label-font-underline
     - bool
     - ``'0'``
     - 
   * - label-font-weight
     - int
     - ``'400'``
     - 
   * - label-format
     - string
     - ``'auto'``
     - 
   * - label-in-a-box
     - bool
     - ``'0'``
     - 
   * - label-in-line-color
     - int
     - ``'0'``
     - 
   * - label-transparent
     - bool
     - ``'0'``
     - 
   * - label-orientation
     - int
     - ``'0'``
     - 
   * - marker
     - bool
     - ``'0'``
     - 
   * - marker-edge-color
     - color
     - ``'black'``
     - 
   * - marker-edge-width
     - int
     - ``'1'``
     - 
   * - marker-fill-color
     - color
     - ``'red'``
     - 
   * - marker-fill-alpha
     - int
     - ``'255'``
     - ``'0'``: transparent, ``'255'``: opaque, Exception: The value ``'1'`` sets alpha to opaque to be compatible with older versions. 
   * - marker-label
     - bool
     - ``'0'``
     - 
   * - marker-label-font-angle
     - double
     - ``'0.0'``
     - 
   * - marker-label-font-color
     - color
     - ``'black'``
     - 
   * - marker-label-font-face-name
     - string
     - ``''``
     - 
   * - marker-label-font-height
     - int
     - ``'12'``
     - 
   * - marker-label-font-italic
     - int
     - ``'0'``
     - 
   * - marker-label-font-pitch-and-family
     - int
     - ``'0'``
     - 
   * - marker-label-font-strikeout
     - int
     - ``'0'``
     - 
   * - marker-label-font-underline
     - int
     - ``'0'``
     - 
   * - marker-label-font-weight
     - int
     - ``'400'``
     - 
   * - marker-line-index
     - bool
     - ``'0'``
     - 
   * - marker-size
     - double
     - ``'0.25'``
     - 
   * - marker-style
     - marker_style
     - ``'3'``
     - 
   * - max-marker
     - bool
     - ``'0'``
     - 
   * - max-marker-edge-color
     - color
     - ``'black'``
     - 
   * - max-marker-edge-width
     - int
     - ``'1'``
     - 
   * - max-marker-fill-color
     - color
     - ``'red'``
     - 
   * - max-marker-fill-alpha
     - int
     - ``'255'``
     - ``'0'``: transparent, ``'255'``: opaque, Exception: The value ``'1'`` sets alpha to opaque to be compatible with older versions. 
   * - max-marker-size
     - double
     - ``'0.25'``
     - 
   * - max-marker-style
     - marker_style
     - ``'1'``
     - See :ref:`XYSetProps`
   * - min-marker
     - bool
     - ``'0'``
     - 
   * - min-marker-edge-color
     - color
     - ``'black'``
     - 
   * - min-marker-edge-width
     - int
     - ``'1'``
     - 
   * - min-marker-fill-color
     - color
     - ``'red'``
     - 
   * - min-fill-alpha
     - int
     - ``'255'``
     - ``'0'``: transparent, ``'255'``: opaque, Exception: The value ``'1'`` sets alpha to opaque to be compatible with older versions. 
   * - min-marker-size
     - double
     - ``'0.25'``
     - 
   * - min-marker-style
     - marker_style
     - ``'0'``
     - See :ref:`XYSetProps`
   * - name
     - string
     - ``''``
     - 
   * - outside-3d-pen-color
     - color
     - ``'black'``
     - 
   * - outside-3d-pen-style
     - curve_style
     - ``'solid'``
     - possible values: '0' or 'solid' ,  '1' or 'dash', '2' or'dot',  '3' or 'dashdot',  '4' or 'dashdotdot'.
   * - outside-3d-pen-width
     - int
     - ``'2'``
     - 
   * - outside-color
     - color
     - ``'#7F7F7F'``
     - 
   * - outside-hull-3d-type
     - int
     - ``'2'``
     - 
   * - scatter-bar-width
     - double
     - ``'3.0'``
     - 
   * - scatter-label-offset-x
     - double
     - ``'0.0'``
     - 
   * - scatter-label-offset-y
     - double
     - ``'0.0'``
     - 
   * - spline
     - bool
     - ``'0'``
     - 
   * - surface-attributes
     - int
     - ``'0'``
     - 
   * - surface-type
     - int
     - ``'1'``
     - 
   * - triangulation
     - bool
     - ``'0'``
     - 

**Properties in Categories:**

**Isolines**

.. list-table::
   :header-rows: 1

   * - Property
     - Type
     - Default Value
   * - isolines
     - bool
     - ``'1'``
   * - spline
     - bool
     - ``'0'``
   * - iso-values
     - string
     - ``'auto'`` or ``'auto:10'`` or ``'auto:linear,10'``
   * - filled
     - bool
     - ``'0'``
   * - iso-min-color
     - string
     - ``'auto'``
   * - iso-min-color-alpha
     - int
     - ``'255'``
   * - iso-colors
     - string
     - ``'auto'``
   * - iso-colors-alpha
     - string
     - ``'255'``
   * - iso-pen-color
     - string
     - ``'black'``
   * - iso-pen-styles
     - string
     - ``'solid'``
   * - iso-pen-width
     - string
     - ``'1'``

Note:

**iso-values** specifies the isolines to be plotted. iso-values is either
the string "auto" or a string of comma separated values ("22.3,25,100,200,500.12"). 
The "auto" string can be followed by a colon and the number of
automatically calculated isoline values in the range 1 to 100, e.g. "auto:6".
The text "auto:linear,XX" creates a linear scaling. ``XX`` is the number of values,
e. g. "auto:linear,10".

**iso-min-color** is used when "filled='1'" is set.

**iso-colors** is a single color or a comma separated list of colors.
If iso-values is set to 'auto' the iso-min-color and the last specified color 
is used to calculate a color gradient. If iso-values is a list of values
the number of iso-colors must match the number of isoline values otherwise
a color gradient between the last specified color and the iso-min-color is
calculated.

**iso-pen-color**, **iso-pen-styles**, **iso-pen-width** are comma separted
list of values. If the number of elements do not match the number of isoline values
the list will be filled with the last specified value in the list.

**Isoline Labels**

.. list-table::
   :header-rows: 1

   * - Property
     - Type
     - Default Value
   * - iso-label-type
     - string
     - ``'auto'``
   * - label-format
     - string
     - ``'auto'``
   * - label-in-a-box
     - bool
     - ``'0'``
   * - label-in-line-color
     - int
     - ``'0'``
   * - label-transparent
     - int
     - ``'0'``
   * - label-orientation
     - int
     - ``'0'``
   * - label-font-angle
     - double
     - ``'0.0'``
   * - label-font-color
     - color
     - ``'black'``
   * - label-font-face-name
     - string
     - ``''``
   * - label-font-height
     - int
     - ``'-9'``
   * - label-font-italic
     - bool
     - ``'0'``
   * - label-font-pitch-and-family
     - int
     - ``'0'``
   * - label-font-strikeout
     - bool
     - ``'0'``
   * - label-font-underline
     - bool
     - ``'0'``
   * - label-font-weight
     - int
     - ``'400'``

Note:

**iso-label-type** set the label position.

.. list-table::
   :header-rows: 1

   * - Value
     - Meaning
   * - 'none' or '0'
     - isolines are not labeled.
   * - 'user' or '1'
     - labels are not changed.
   * - 'stripes' or '2'
     - labels the isolines at the intersection between two vertical lines and the isolines.
   * - 'middle' or '3'
     - every isoline is labeld in the middle of the line.
   * - 'random' or '4'
     - labels each line at an random position.
   * - 'auto' or '5'
     - same as 'random'.

**label-format** 'auto' or a number (see :ref:`XYZSetLabelFormat`).

**label-transparent** If set to '1', the label will be plotted transparent.
If set to '0' the labels will be plotted with a white background rectangle.

**Bubble-Plots**

.. list-table::
   :header-rows: 1

   * - Property
     - Type
     - Default Value
   * - bubble
     - bool
     - ``'0'``
   * - bubble-color-type
     - int
     - ``'1'``
   * - bubble-size-max
     - double
     - ``'1.0'``
   * - bubble-size-min
     - double
     - ``'0.2'``
   * - bubble-size-type
     - int
     - ``'1'``

Note:

**bubble-color-type** '1' solid color, '2' color gradient.

**bubble-size-type** '1' z-value proportional to the marker area, '2' z-value
proportional to the marker diameter.

**Hull**

.. list-table::
   :header-rows: 1

   * - Property
     - Type
     - Default Value
   * - hull-label
     - bool
     - ``'1'``
   * - hull-label-distance
     - double
     - ``'0.3'``
   * - hull-label-horizontal
     - bool
     - ``'1'``
   * - hull-pen-color
     - color
     - ``'black'``
   * - hull-pen-style
     - curve_style
     - ``'solid'``
   * - hull-pen-width
     - int
     - ``'4'``
   * - hull-spline
     - bool
     - ``'0'``
   * - hull-type
     - int
     - ``'1'``

Note:

**hull-type** sets the hull type.

.. list-table::
   :header-rows: 1

   * - Value
     - Meaning
   * - '0'
     - No hull (HULL_NONE)
   * - '1'
     - North part of the hull (HULL_NORTH)
   * - '2'
     - Spline connection (HULL_NORTH_SPLINE)
   * - '3'
     - Entire hull (HULL_ENTIRE)
   * - '4'
     - Entire hull - North part with spline connection (HULL_ENTIRE_SPLINE)
   * - '5'
     - User defined hull (HULL_USERDEF)

**3D Surface Plot**

.. list-table::
   :header-rows: 1

   * - Property
     - Type
     - Default Value
   * - base-value-3d
     - double
     - ``'0.0'``
   * - inside-3d-pen-color
     - color
     - ``'black'``
   * - inside-3d-pen-style
     - curve_style
     - ``'solid'``
   * - inside-3d-pen-width
     - int
     - ``'2'``
   * - inside-color-3d
     - color
     - ``'white'``
   * - outside-3d-pen-color
     - color
     - ``'black'``
   * - outside-3d-pen-style
     - curve_style
     - ``'solid'``
   * - outside-3d-pen-width
     - int
     - ``'2'``
   * - outside-color
     - color
     - ``'#7F7F7F'``
   * - outside-hull-3d-type
     - int
     - ``'2'``
   * - surface-attributes
     - int
     - ``'0'``
   * - surface-type
     - int
     - ``'1'``
   * - isolines-3d
     - bool
     - ``'0'``

Note:

**surface-type** sets the surface type (see 
:ref:`XYZSet3DSurfaceType`). Valid range is '0' to '7'.

**Interpolation**

.. list-table::
   :header-rows: 1

   * - Property
     - Type
     - Default Value
   * - interpolation-density
     - string
     - ``'40,40'``
   * - interpolation-on-grid
     - bool
     - ``'0'``
   * - interpolation-range
     - string
     - ``'auto'``
   * - interpolation-smooth-factor
     - int
     - ``'0'``
   * - interpolation-type
     - int
     - ``'3'``

Meaning of the property **interpolation-type**:

.. list-table::
   :header-rows: 1

   * - Value
     - Meaning
   * - 1
     - linear Interpolation
   * - 2
     - Non linear Interpolation
   * - 3
     - Thin-Plate-Spline Interpolation

**Scatter Plot**

.. list-table::
   :header-rows: 1

   * - Property
     - Type
     - Default Value
   * - marker
     - bool
     - ``'0'``
   * - marker-edge-color
     - color
     - ``'black'``
   * - marker-edge-width
     - int
     - ``'1'``
   * - marker-fill-color
     - color
     - ``'red'``
   * - marker-fill-alpha
     - int
     - ``'255'``
   * - marker-label
     - bool
     - ``'0'``
   * - marker-label-font-angle
     - double
     - ``'0.0'``
   * - marker-label-font-color
     - color
     - ``'black'``
   * - marker-label-font-face-name
     - string
     - ``''``
   * - marker-label-font-height
     - int
     - ``'12'``
   * - marker-label-font-italic
     - int
     - ``'0'``
   * - marker-label-font-pitch-and-family
     - int
     - ``'0'``
   * - marker-label-font-strikeout
     - int
     - ``'0'``
   * - marker-label-font-underline
     - int
     - ``'0'``
   * - marker-label-font-weight
     - int
     - ``'400'``
   * - marker-line-index
     - bool
     - ``'0'``
   * - marker-size
     - double
     - ``'0.25'``
   * - marker-style
     - marker_style
     - ``'3'``
   * - max-marker
     - bool
     - ``'0'``
   * - max-marker-edge-color
     - color
     - ``'black'``
   * - max-marker-fill-alpha
     - int
     - ``'255'``
   * - max-marker-edge-width
     - int
     - ``'1'``
   * - max-marker-fill-color
     - color
     - ``'red'``
   * - max-marker-size
     - double
     - ``'0.25'``
   * - max-marker-style
     - marker_style
     - ``'1'``
   * - min-marker
     - bool
     - ``'0'``
   * - min-marker-edge-color
     - color
     - ``'black'``
   * - min-marker-edge-width
     - int
     - ``'1'``
   * - min-marker-fill-color
     - color
     - ``'red'``
   * - min-marker-fill-alpha
     - int
     - ``'255'``
   * - min-marker-size
     - double
     - ``'0.25'``
   * - min-marker-style
     - marker_style
     - ``'0'``

**Color Matrix**

.. list-table::
   :header-rows: 1

   * - Property
     - Type
     - Default Value
   * - color-matrix
     - bool
     - 0
   * - color-matrix-line-color
     - color
     - ``black``
   * - color-matrix-line-width
     - int
     - ``2``
   * - color-matrix-showzval
     - bool
     - ``1``
   * - color-matrix-cliptext
     - bool
     - ``1``
   * - color-matrix-shrinktext
     - bool
     - ``1``
   * - color-matrix-showedge
     - bool
     - ``1``
   * - color-matrix-clipzmin
     - bool
     - ``0``

**Others**

.. list-table::
   :header-rows: 1

   * - Property
     - Type
     - Default Value
   * - name
     - string
     - ``''``
   * - scatter-bar-width
     - double
     - ``'3.0'``
   * - scatter-label-offset-x
     - double
     - ``'0.0'``
   * - scatter-label-offset-y
     - double
     - ``'0.0'``
   * - triangulation
     - bool
     - ``'0'``

Note:

Information to the column **Type** can be found in the :ref:`XYSetProps` function
help.

For more information open the file :file:`script\\do_sty4.ic`.

**Color Table**

.. image:: S:/uniplot-obj/images/color-table.*

.. us.history

**History**

.. list-table::
   :header-rows: 1

   * - Version
     - Description
   * - 5.30
     - New attributes (Color matrix).
   * - 4.0.3
     - New.

.. seealso::
   :ref:`overview-xyz-datasets`,
   :ref:`XYZGetProps`,
   :ref:`XYZSetDefault`,
   :ref:`XYSetProps`

:sub:`id-1762688`