.. highlightlang:: us .. index:: XYZCreate .. _xyzcreate: XYZCreate ========= .. us.tag XYZCreate ENGLISH Changed534 Changed5200 :ref:`XYZCreate` creates a new 3D dataset. The 3D dataset can be created from scattered XYZ triples or from a rectangular grid (matrix). .. function:: hData = XYZCreate(ssName, rvX, rvY, rvZ) hData = XYZCreate(ssName, rvX, rvY, rvZ, bIsoScale) hData = XYZCreate(ssName, rvX, rvY, rvZ, bIsoScale, svWOT) hData = XYZCreate(ssName, rvX, rvY, rmZMatrix) hData = XYZCreate(ssName, rvX, rvY, rmZMatrix, bIsoScale) hData = XYZCreate(ssName, rmZMatrix, rvRect) .. us.return **Return Value** *hData* is the handle of the dataset. If the dataset cannot be created *hData* is 0. .. us.params **Parameters** .. uparam:: ssName *ssName* is a scalar string. .. 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:: rmZMatrix *rmZMatrix* is a matrix with z-coordinates. If the distance between the rows and columns of the matrix is constant, the x- and y-coordinates can be specified with the *rvRect* parameter. If the rows and columns are not evenly spaced, 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. If the matrix contains invalid values (1e10 or NANs), the missing points will be interpolated. The invalid values at the edges are used to calculate the data hull. .. uparam:: rvRect *rvRect* specifies the range of the z Matrix in the xy plane. .. list-table:: :header-rows: 1 * - Value - Meaning * - rvRect[1] - xmin of the first matrix column * - rvRect[2] - ymin of the first matrix row * - rvRect[3] - xmax of the last matrix column * - rvRect[4] - ymax of the last matrix row .. uparam:: bIsoScale *bIsoScale* is TRUE (1), if isolines should be automatically created for the dataset, and FALSE (0), when no isolines should be created. If the function is called with 4 parameters TRUE will be used for *bIsoScale*. .. uparam:: svWOT *svWOT* is a string vector that sets the Full Load Line (WOT). Each vector element contains a symbol and can have one of the following values ``"a"``, ``"e"``, ``"v"``, ``"A"``, ``"E"``, ``"V"``, ``""``. The symbols have the following meanings: .. list-table:: :header-rows: 1 * - Value - Meaning * - ``"a"`` - Start of the Full Load Line (WOT) without labels. * - ``"e"`` - End of the Full Load Line (WOT) without labels. * - ``"v"`` - Point belongs to Full Load Line (WOT) and will not be labeled. * - ``"A"`` - Start of the Full Load Line (WOT) with labels. * - ``"E"`` - End of the Full Load Line (WOT) with labels. * - ``"V"`` - Point belongs to Full Load Line (WOT) and will be labeled. * - ``""`` - (empty string) Point does not belong to Full Load Line (WOT). .. us.comment **Comment** All vectors must have the same number of elements for XYZ triples. The triples can be scattered in the x/y plane. At least three triples are necessary to create a 3D dataset. If the function is called without the parameter *svWOT*, a convex hull is calculated. If the dataset is created from a matrix, the data hull can be specified by using the function :ref:`XYZSetHullNewData`. Before the dataset is created the triple points are filtered. This filter categorize the data into 100 by 100 bins in the x- and y-direction. For each bin only one data point, the "median" point, is used. For a grid of 100 by 100 bins, the number of data points is reduced to 10,000 data points. Because not all bins contain points the number is usually smaller. If all points lie on a straight line, only 100 points are returned. To disable the filter, invoke the following function call in the command window:: WriteProfileInt("Settings", "XYZFilterCallback_enable", 0); To enable the filter:: WriteProfileInt("Settings", "XYZFilterCallback_enable", 1); **Map correction at the map border** The linear and non-linear interpolation is based on a triangulation of the data points in the X/Y plane. If boundary points are nearly collinear or coplanar the triangulation process can lead to neary flat triangles near the map border. This will cause unexpected isolines shapes at the border. The following example shows in the two upper graphs the course of the Contours with uncorrected data and in the lower two charts the course of the corrected data. Data points near the data hull will be moved perpendicular to the hull. .. image:: S:/uniplot-obj/images/xyz_flat_triangle_correction.* The correction can be disabled :ref:`tools-more-options`. The default value is "switched on". A tolerance to find the data points at the border can be set. The default value is 0.1 % of the data range. Example: The tolerance for speed values in the range 500 to 6500 rpm is 6 rpm. The setting can be switched off via script as following :: WriteProfileInt("Settings", "XYZRemoveFlatTriangles", 0); Enable:: WriteProfileInt("Settings", "XYZRemoveFlatTriangles", 1); .. us.example **Example** Copy the following example into an UniPlot Editor (:ref:`file-new` ``[Program editor]``) and choose :ref:`uniscript-save-execute` to execute the script. A 2 by 3 matrix dataset will be created. The x-coordinates specify the columns and the y-coordinates the matrix rows. :: x = [1, 1.5, 2] y = [1, 5] z = [1, 1, 3; 1, 2, 3] hData = XYZCreate("Test", x, y, z); if (hData == 0) { error(); } hLayer = LayerCreate(); hDoc = DocCreate(); hPage = PageCreate(); DocAddPage(hDoc, hPage); PageAddLayer(hPage, hLayer); LayerAddDataset(hLayer, hData); LayerAutoScale(hLayer); PageReplot(hPage); .. us.history **History** .. list-table:: :header-rows: 1 * - Version - Description * - R2016.1 - Nearly flat triangle corrected added. * - 5.3.4 - Function call with three parameters fixed: ``XYZCreate(ssName, rmZMatrix, rvRect)``. .. seealso:: :ref:`overview-xyz-datasets`, :ref:`overview-data-file-informations-for-datasets`, :ref:`LayerAddDataset`, :ref:`XYZDestroy`, :ref:`XYZCreateFromMatrix`, :ref:`XYZGetMatrixRange`, :ref:`XYZGetMatrix`, :ref:`XYZGetData`, :ref:`XYZGetMatrixRowData`, :ref:`XYZGetMatrixColData`, :ref:`reduce3d` :sub:`id-428507`