User data and the GMT API

All GMT modules are file based, i.e., data are passed by reading or writing files. Therefore, getting data to and from memory in MATLAB, Python, Julia, or C/C++ applications require you to create a virtual file to represents this memory. The names of such virtual files are then given as the file arguments expected by the modules.

1. Set user data as GMT input

Most external applications will pass data in memory via the helper containers GMT_VECTOR or GMT_MATRIX. If your data are given as one or more column vectors then you will use GMT_VECTOR, while for a data matrix (row or column oriented) you will use GMT_MATRIX. The data types can be anything (doubles, ints, chars, etc.), and for GMT_VECTOR each column may be different. Create a container for your vectors or matrix using GMT_Create_Data. This step will set the dimensions of your input data (rows, cols, etc). Then, attach your actual vectors (one by one) or matrix using GMT_Put_Vector or GMT_Put_Matrix.

2. Create a virtual input file(s)

GMT modules deal with five different types of data: Data tables (GMT_DATASET), text tables (GMT_TEXTSET), grids (GMT_GRID), color tables (GMT_PALETTE) and images (GMT_IMAGE). Thus, when you open a virtual file on a container for reading you must specify one of those five families. For instance, If you created a GMT_VECTOR container and want to use this to pass data table information to psxy then you will open a virtual file of type GMT_IS_DATASET, but to indicate that the object is actually a GMT_VECTOR you must add GMT_VIA_VECTOR to the family type. For a user matrix to be read by grdmath you will likewise open a virtual file of type GMT_IS_GRID and add GMT_VIA_MATRIX. This task is performed with GMT_Open_VirtualFile and returns a text string with the name of the "file". Depending on the module and data type you may have any number of virtual input files. You may also mix virtual and actual files.

3. Create a virtual output file

If you want to access GMT output in your program you will also need to create a virtual file to hold the output. Now, your direction will be GMT_OUT and you can specify any of the five data types as well as GMT_VECTOR and GMT_MATRIX. The latter two lets you receive data back in a format that may be closer to your own data organization. The resulting file name that GMT_Open_VirtualFile provides is then given to the module as the output destination file name.

4. Call the module

Create the command arguments and include the virtual file names for input(s) and output and call the GMT module of interest. Internally, GMT knows that any input/output grids or data tables may have been passed as vectors or matrices and will act accordingly.

5. Access GMT output data in your program

Given the virtual output file name you created earlier you now call GMT_Read_VirtualFile to receive a pointer to the container that holds the data. If the container is GMT_VECTOR or GMT_MATRIX then you access their arrays using GMT_Get_Vector or GMT_Get_Matrix, respectively. However, you can also request any of the standard five GMT objects, especially from C-like languages. You can now close the virtual files and use the data in your program.

6. Scope

User data fed into GMT via virtual files are considered read-only in the sense that we will not attempt to reallocate or free this data. However, the data values may change due to operations in the modules. Data returned from GMT via virtual files are arrays created by GMT. These will automatically be freed when the GMT session ends, so if your workflow requires you to terminate the GMT session then you need to duplicate this information before it is wiped. Alternatively, you can build the virtual output file using a pre-allocated container where your own allocated output arrays or matrices are passed in. In this case no memory is allocated in GMT and we write to this memory, again without any attempts to reallocate or free. This memory will outlive the GMT session. It is up to you to ensure enough memory has been allocated since GMT cannot reallocate if more is needed, leading to truncation or error.

7. Data type restrictions

Because GMT represents grids internally as floats and data tables as doubles, you should try to match these types in your own program. If you do not then GMT must duplicate the data to fit its internal data model.