.. highlightlang:: us

.. index:: plotxyz

.. _plotxyz:

plotxyz
=======

.. us.tag  plotxyz ENGLISH New520

:ref:`plotxyz` creates a new 3D dataset and plots the data into a diagram. 
The 3D dataset can be created from scattered XYZ triples or from a rectangular 
grid (matrix).

.. function::  hData = plotxyz(rvX, rvY, rvZ)
    hData = plotxyz(rvX, rvY, rmZ)
    hData = plotxyz(rvX, rvY, rvZ, option)
    hData = plotxyz(rvX, rvY, rmZ, option)

.. us.return

**Return Value**

*hData* is the handle of the dataset. If the dataset cannot be
created *hData* is 0.

.. us.params

**Parameters**

.. uparam:: rvX

   *rvX* is a vector with x-coordinates.

.. uparam:: rvY

   *rvY* is a vector with y-coordinates.

.. uparam:: rvZ

   *rvZ* is a vector with z-coordinates.

.. uparam:: rmZ

   *rmZ* is a matrix with z-coordinates. The coordinates of the matrix columns are
   specified by the vector *rvX* and the rows are specified by the vector *rvY*.
   *rvX* and *rvY* should be sorted in ascending order. If they are not sorted
   the function will sort the vectors and the z matrix.

.. uparam:: option

   The optional parameter *option*  is an object with options. See example. The
   following options will be evaluated:

   .. list-table::
      :header-rows: 0

      * - xTitle
        - x axis titel, Default = "": If value = "" the title will not be modified.
      * - yTitle
        - y axis titel, Default = "": If value = "" the title will not be modified.
      * - zTitle
        - z axis titel, Default = "": If value = "" the title will not be modified.
      * - name
        - Dataset name.
      * - hLayer
        - Dataset will be added to this valid layer.
      * - autoscale
        - If value = 1 the axis will be autoscaled.
      * - props
        - This element can contain dataset poperties, see :ref:`XYZSetProps`.
      * - hData
        - Handle of a 3D dataset which properties will be copied into the new dataset.
      * - Layer3D
        - If value = 1 the layer will be plotted as a 3D box, Value = 0 2D box.
          Value = -1 not altered. Default value = -1.

.. us.example

**Example**

::

   nRC = 40
   xmin = 0.05-PI/2;
   xmax = 0.05+PI;
   ymin = -PI/2;
   ymax =  PI/2
   x = linspace(xmin, xmax, nRC);
   y = linspace(ymin, ymax, nRC);
   <xx, yy> = meshdom(x,y);
   zz = real(tan(xx + 1i * yy));
   /*
   option = [.]; // Create object
   option.name = "real(tan(xx + 1i * y))";
   option.autoscale = 1;
   option.props = "surface-type = '2'"; // STYLE_SURF_COLORGRADIENT
   option.Layer3D = 1;
   */
   // another syntax to create the option object
   option = [. name = "real(tan(xx + 1i * y))", autoscale = 1,
               props = "surface-type = '2'", Layer3D = 1];
   plotxyz(x, y, zz, option);

.. seealso::
   :ref:`DocCreate`,
   :ref:`PageCreate`,
   :ref:`PageGetParentDocument`,
   :ref:`LayerCreate`,
   :ref:`XYCreate`,
   :ref:`GetParent`,
   :ref:`XYZSetProps`

:sub:`id-839714`