.. highlightlang:: us

.. _auto_xyz_sub:

auto_xyz_Sub
============

.. index:: auto_xyz_Sub

.. us.tag  auto_xyz_Sub NOTREADYENGLISH auto_xyz Changed5400

:ref:`auto_xyz_Sub` creates a new dataset by subtracting the z coordinates of the
given 3D datasets.

.. function::  hDataNew = auto_xyz_Sub(hData, hData2)
    hDataNew = auto_xyz_Sub(hData_Layer, hData2)
    hDataNew = auto_xyz_Sub(hData_Layer, hData2, nSourceType)

.. us.return

**Return Value**

*hDataNew* is the handle of the new 3D dataset.

.. us.params

**Parameters**

.. uparam:: hData

   *hData* is the first dataset handle. The new dataset (*hData* - *hData2*)
   will be added to the diagram of *hData*.

.. uparam:: hData_Layer

   *hData_Layer* is a vector with one or two elements:

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

   * - Value
     - Meaning
   * - hData_Layer[1]
     - Handle of a dataset. The new dataset is added to the diagram to which the dataset hData_Layer[1] belongs.
   * - hData_Layer[1, 2]
     - The first element is the dataset handle and the second element is the diagram handle (layer). The new dataset is added to the diagram with the handle hData_Layer[2].

.. uparam:: hData2

   *hData2* Is a second 3D dataset.

.. uparam:: nSourceType 

  *nSourceType* is one of the following values:

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

     * - Value
       - Description
     * - 1
       - Use the x,y coordinates of dataset 1 to calculate the result.
     * - 2
       - Use the x,y coordinates of dataset 2 to calculate the result.
     * - 3
       - Use the interpolation matrix to calculate the result (Default)

  For type 1 or 2 the z-coordinates for both datasets are calculated
  at the original x,y-coordinates and the results are added. 
  For type 3 the interpolation matrix is calculated at identical x,y 
  coordinates the than the matrices are added (Default).

  If both maps have identical or quasi identical x,y-coordinates the types 1 
  or 2 will calculate a better result.

.. us.comment

**Comment**

The two datasets can be created from a matrix or from XYZ triples. The new dataset
is created as follows:

*  The overlapping area in the x,y plane of the two datasets is calculated.

* For the overlapping area for each dataset, a new matrix is interpolated. The
  two new matrices have the same number of rows and columns.

*  The operation is performed elementwise on the new interpolated matrices.

* The new dataset is created from the result matrix. The hull is taken from the
  first dataset.

.. us.example

**Example**

::

   hPage = auto_LoadTemplate("test.ipw")
   ssFile1  =  auto_ImportData(GetRootDirectory() + "samples/test1.xls")
   hData1 = auto_LoadDataset("Diagram1", "EngSpd", "PME", "TOEL1");
   ssFile2  =  auto_ImportData(GetRootDirectory() + "samples/test2.xls")
   hData2 = auto_LoadDataset("Diagram2", "EngSpd", "PME", "TOEL1");
   hLayer = PageGetLayerHandle(hPage, "Diagram3");
   hDataNew  =  auto_xyz_Sub([hData1, hLayer], hData2);
   PageReplot(hPage);

.. us.history

**History**

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

   * - Version
     - Description
   * - 5.40.0
     - New parameter *nSourceType*.

.. seealso::
   :ref:`overview-automation`,
   :ref:`auto_LoadDataset`

:sub:`id-385380`