.. highlightlang:: us

.. index:: XYZGetIsoline

.. _xyzgetisoline:

XYZGetIsoline
=============

.. us.tag  XYZGetIsoline NOTREADYENGLISH XYZGet_iso New363

:ref:`XYZGetIsoline` retrieves the isoline x/y coordinates of a 3D dataset.

.. function::  rmXY = XYZGetIsoline(hData, nIsoValue, nLineIndex)

.. us.return

**Return Value**

*rmXY* is a 2 column matrix with the x/y coordinates or 0.0 if the isoline
specified does not exist.

.. us.params

**Parameters**

.. uparam:: hData

   A handle for a dataset created with :ref:`XYZCreate`.

.. uparam:: nIsoValue

   *nIsoValue* is the index of the isoline. The index starts with 1. The index of
   the smallest isoline value is 1.

.. uparam:: nLineIndex

   *nLineIndex* is the index of the isoline element, starting with 1.

.. us.example

**Example**

The following example converts all isolines of a 3D dataset to 2D datasets.

::

   def XYZ_to_XY(hXYZData)
   {
       hLayer = GetParent(hXYZData)
       nIso = XYZGetNumberOfIsoValues(hXYZData);
       rvValues=XYZGetIsoValues(hXYZData);
       for (i in 1:nIso) {
           j = 1;
           while (1) {
               xy = XYZGetIsoline(hXYZData, i, j);
               if (len(xy) == 1) {
                   break;
               }
               hXY = XYCreate(sprintf("%g", rvValues[i]), xy[;1], xy[;2]);
               LayerAddDataset(hLayer, hXY);
               j = j+1;
           }
       }
   }

The following example save the coordinates for each isoline in an Excel Sheet.
Copy the example into a file with the extension ``.ic`` and save the file in the
UniPlot autoload directory. To execute the function select a 3D dataset and
choose the ``Iso to Excel`` command in the user toolbar::

     RegisterCommand("3D-Datensatz", "__IsoToExcel", "Iso to Excel...");
     UserBar_Add("__IsoToExcel");

     def <smMatrix, smType> = XYZ_to_XY(hXYZData)
     {
          oData = [.];
          oData.MaxN = 0;

          nLine = 0;
          nIso = XYZGetNumberOfIsoValues(hXYZData);
          rvValues = XYZGetIsoValues(hXYZData);
          for (i in 1:nIso) {
               j = 1;
               while (1) {
                    rmXY = XYZGetIsoline(hXYZData, i, j);
                    if (len(rmXY) == 1) {
                         break;
                    }
                    if (j == 1) {
                         oValue = [.];
                         oValue.nLine = 0;
                    }
                    oLine = [.];
                    oLine.Value = rvValues[i];
                    oLine.rmXY = rmXY;
                    oValue[j] = oLine;
                    oValue.nLine = oValue.nLine + 1;
                    if (oData.MaxN < nr(rmXY)) {
                         oData.MaxN = nr(rmXY);
                    }
                    j = j+1;
                    nLine = nLine + 1;
               }
               if (j > 1) {
                    oData[i] = oValue;
               }
          }
          iCol = 1;
          smMatrix = strempty(oData.MaxN+2, nLine*2);
          smType = strempty(oData.MaxN+2, nLine*2) + "s";

          rvKeys = oData.keys(1);
          for (i in rvKeys) {
               oValue = oData[i];
               nLine = oValue.nLine;
               for (j in 1:nLine) {
                    iiCol = iCol + (j-1) * 2;
                    smMatrix[1; iiCol] = sprintf("%.10lf", oValue[j].Value);
                    smMatrix[2; iiCol] = sprintf("%d", j);
                    smType[1; iiCol] = "";
                    smType[2; iiCol] = "";
                    rmXY = oValue[j].rmXY;
                    smMatrix[3:nr(rmXY)+2; iiCol, iiCol+1] = smprintf("%.10lf", rmXY);
                    smType[3:nr(rmXY)+2; iiCol, iiCol+1] = "";
               }
               iCol = iCol + nLine * 2;
          }
          return;
     }

     def __IsoToExcel()
     {
          hvHandle = GetActiveXYZHandles();
          if (hvHandle[4] == 0) {
               MessageBoxError("Please select a map dataset");
               return 0;
          }
          
          ssFileName = GetSaveFileName("", "Excel-Tabelle (*.xlsx)|*.xlsx|", 1, 
                                             "Save Isoline values...");
          if (ssFileName == "") {
               return;
          }
          ssFileName = _AddFileNameExtension(ssFileName, ".xlsx");
          <smMatrix, smType> = XYZ_to_XY(hvHandle[4]);
          bRet = ExcelWriteEx(ssFileName, smMatrix, smType);
          if (bRet) {
               ShellExecute(ssFileName);
          } else {
               MessageBoxError("Write Excel File failed.")
          }
     }

.. seealso::
   :ref:`overview-xyz-datasets`

:sub:`id-877726`