ocmath_mat_to_regular_xyz

1 Description
2 Syntax
3 Parameters
4 Return
5 Examples
6 Remark
7 See Also
8 Header to Include
9 Reference

Description

Create XYZ mapping. The returned X, Y vectors are equi-spaced gridding with specified minimum and maximum values. It is assumed that X varies across columns and Y varies across rows.

Syntax

int ocmath_mat_to_regular_xyz( const double * pMat, int nRows, int nCols, double dXmin, double dXmax, double dYmin, double dYmax, double * px, double * py, double * pz = NULL, BOOL bColOrder = true )

Parameters

pMat: [input] The source matrix. If it is NULL, the function will return X, Y gridding and ignore Z output, otherwise, the source matrix must be stored in column order, as c/c++ multi-dimensional array does.
nRows: [input] The number of rows of the matrix, determine how many points in the Y vector
nCols: [input] The number of columns of the matrix, determine how many points in the X vector
dXmin: [input] The minimum of the X matrix coordinate
dXmax: [input] The maximum of the X matrix coordinate
dYmin: [input] The minimum of the Y matrix coordinate
dYmax: [input] The maximum of the Y matrix coordinate
px: [output] The x position of scatters, must not be NULL
py: [output] The y position of scatters, must not be NULL
pz: [output] The value of scatters, can be NULL and pMat is ignored in case of creating XY gridding only
bColOrder: [input] Specifies the order of data storage in outputs. If this parameter is true, XYZ gridding follows the column order (X varies first). The output vector pz is just the copy of input matrix pMat. In this case, pz and pMat can both be NULL to save time and memory. If this parameter is false, XYZ gridding follows the row order (Y varies first). The output vector pz is the transpose of input matrix pMat.

Return

If the function succeeds the return value is the number of scatters.

If the matrix is ill-defined, that is, nCols or nRows are less than 2, the return value is OE_INVALID_DIMENSION.

If pX or pY is NULL, the return value is OE_NULL_POINTER.

Examples

EX1

// Source matrix is a user defined array.
#include <wks2mat.h>
#define N    12
#define ROW 4
#define COL 3

void ocmath_mat_to_regular_xyz_ex1()
{
    double a[N];
    double b[N];
    double c[N];
    double mat[N] = {1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12};

    double dXmin = 0.1, dXmax = 0.3, dYmin = 10, dYmax = 40;
    
    int nRows = ROW, nCols = COL;

    int nRet = ocmath_mat_to_regular_xyz(mat, nRows, nCols, dXmin, dXmax, dYmin, dYmax, a, b, c);

    if (nRet < 0)
        printf("Invalid X, Y inputs!\n");
    if (nRet == 0)
        printf("The numbers of rows and columns must be larger than 1!\n");
    if (nRet > 0)
    {
        for(int i=0; i<N; i++)
        {
            printf("%g\t%g\t%g\n", a[i], b[i], c[i]);
        }
    }
}

EX2

// Source matrix is the active layer (Origin matrix window).
#include <wks2mat.h>
void ocmath_mat_to_regular_xyz_ex2()
{
    // Create a MatrixLayer, and set its dimension and number of rows & cols.
    MatrixLayer ml = Project.ActiveLayer();
    MatrixObject mo = ml.MatrixObjects(0);

    int nRows = mo.GetNumRows();
    int nCols = mo.GetNumCols();

    double dXmin, dXmax, dYmin, dYmax;
    mo.GetXY(dXmin, dYmin, dXmax, dYmax);
    
    Matrix& mat = mo.GetDataObject();
   
    vector<double> a;
    vector<double> b;
    vector<double> c;
    
    a.SetSize(nRows * nCols);
    b.SetSize(nRows * nCols);
    c.SetSize(nRows * nCols);

    // Note: data in mat is in column order. If set bColOrder = false, mat will be transposed and
    // copied to vector c.
    int nRet = ocmath_mat_to_regular_xyz(mat, nRows, nCols, dXmin, dXmax, dYmin, dYmax, a, b, c, true);

    if (nRet > 0)
    {
        // Create a worksheet to show XYZ scatters.
        Worksheet wks;
        wks.Create();
        wks.SetSize(-1, 3);
        Dataset dsX(wks, 0), dsY(wks, 1), dsZ(wks, 2);
        dsX.Append(a); dsY.Append(b); dsZ.Append(c);
    }    
}

EX3

// The matrix is empty (so does pz). The function creates XY grid only.
#include <wks2mat.h>
void ocmath_mat_to_regular_xyz_ex3()
{
    int nRows = 5;
    int nCols = 6;
    double dXmin = 1.0;
    double dXmax = 6.0;
    double dYmin = 10.0;
    double dYmax = 50.0;

    vector<double> a;
    vector<double> b;
    a.SetSize(nRows * nCols);
    b.SetSize(nRows * nCols);
    
    int nRet = ocmath_mat_to_regular_xyz(NULL, nRows, nCols, dXmin, dXmax, dYmin, dYmax, a, b, NULL, false);

    if (nRet > 0)
    {
        // Create a worksheet to show XYZ scatters.
        Worksheet wks;
        wks.Create();
        wks.SetSize(-1, 3);
        Dataset dsX(wks, 0), dsY(wks, 1);
        dsX.Append(a); dsY.Append(b);
    }    
}