-
Notifications
You must be signed in to change notification settings - Fork 19
Home
Access to GMT from MATLAB is accomplished via a MEX function (also called gmt), which offers further access to all of GMT’s ~140 modules as well as fundamental import, formatting, and export of GMT data objects. Internally, the GMT/MATLAB C API defines six high-level data structures that handle input and output of data via GMT modules. These are data tables (representing one or more sets of points, lines, or polygons), grids (2-D equidistant data matrices), raster images (with 1–4 color bands), raw PostScript code, text tables (free-form text/data mixed records) and color palette tables (i.e., color maps). Correspondingly, we have defined six data structures that we use at the interface between GMT and MATLAB via the gmt MEX function. The GMT/MATLAB API is responsible for translating between the GMT structures and native MATLAB structures, which are:
-
Segments: GMT considers point, line, and polygon data to be organized in one or more segments in a data table. Modules that return segments uses a native MATLAB segment structure that holds the segment data, which may be either numerical, text, or both; it also holds a segment header string which GMT uses to pass metadata. Thus, GMT modules returning segments will typically produce arrays of segments and you may pass these to any other module expecting points, lines, or polygons or use them directly in MATLAB. Since a matrix is the fundamental data type in MATLAB you can also pass any data type matrix directly to GMT modules as well. Consequently, it is very easy to pass data from MATLAB into GMT modules that process data tables as well as to receive data segments from GMT modules that process and produce data tables as output. The toolbox also provides a function for concatenating segments into a single segment.
-
Grids: Many tools consider equidistant grids a particular data type and numerous file formats exist for saving such data. Because GMT relies on GDAL we are able to read and write almost all such formats in addition to a native netCDF4 format that complies with both the COARDS and CF netCDF conventions. We have designed a native MATLAB grid structure that holds header information from the GMT grid as well as the data matrix representing the gridded values. These structures may be passed to GMT modules that expect grids and are returned from GMT modules that produce such grids. In addition, we supply a function to convert a MATLAB matrix and some metadata into a grid structure.
-
Images: The raster image shares many characteristics with the grid structure except the bytes representing each node reflect gray shade, color bands (1, 3, or 4 for indexed, RGB and RGBA, respectively), and possibly transparency values. We therefore represent images in another native MATLAB structure that among other items contains three components: The image matrix, a color map (present for indexed images only), and an alpha matrix (for images specifying transparency on a per-pixel level). As for grids, a wrapper function creating the correct structure is available.
-
Color palettes: GMT uses its flexible Color Palette Table (CPT) format to describe how the color (or pattern) of symbols, lines, polygons or grids should vary as a function of a state variable. In MATLAB, this information is provided in another MATLAB structure that holds the color map as well as an optional alpha array for transparency values. Like grids, these structures may be passed to GMT modules that expect CPTs and will be returned from GMT modules that normally would produce CPT files. The content of the CPT can also be used to change color maps in MATLAB.
-
PostScript: While most users of the GMT/MATLAB toolbox are unlikely to manipulate PostScript directly, the API allows for the passing of PostScript via another data structure.
-
Text data: Because of their variable record lengths and mixed numeric/text contents, we chose to represent text tables by data segments containing a cell array. All GMT modules expecting text tables will use such segments to communicate with MATLAB. If the leading columns of data records contain numerical data, then those components will be decoded into a data matrix instead. You may also pass text data to GMT using text cell arrays, and if only a single text record is involved you can pass that string as is.
The MATLAB structures designed for interfacing with GMT are described in the following tables.
Table 1. The dataset segment structure and its attributes
| member | Description |
|---|---|
| data | Matrix with segment data |
| text | Cell array with any text after data coordinates |
| header | String with segment header |
| comment | Cell array with any dataset comments [empty after first segment] |
| proj4 | Projection string in PROJ4 syntax (optional) |
| wkt | Projection string in WKT syntax (optional) |
Table 2. The Grid structure and its attributes
| member | Description |
|---|---|
| z | Grid matrix |
| x | Vector with x-coordinates |
| y | Vector with y-coordinates |
| range | Vector with range [x_min x_max y_min y_max z_min z_max] |
| inc | Vector with grid spacing [x_inc y_inc] |
| registration | Registration type: 0 = Grid registration; 1 = Pixel registration |
| nodata | The value used to indicate ‘no data’ |
| title | Title (optional) |
| comment | Comment (optional) |
| command | Command used to create the grid (optional) |
| datatype | Data type: ‘float' or 'double' |
| x_unit | Units of x-axis (optional) |
| y_unit | Units of y-axis (optional) |
| z_unit | Units of z-axis (optional) |
| proj4 | Projection string in PROJ4 syntax (optional) |
| wkt | Projection string in WKT syntax (optional) |
Table 3. The Image structure and its attributes
| member | Description |
|---|---|
| image | Image matrix |
| x | Vector with x-coordinates |
| y | [Vector with y-coordinates |
| range | Vector with range [x_min x_max y_min y_max z_min z_max] |
| inc | Vector with grid spacing [x_inc y_inc] |
| registration | Registration type: 0 = Grid registration; 1 = Pixel registration |
| nodata | The value used to indicate ‘no data’ |
| title | Title (optional) |
| comment | Comment (optional) |
| command | Command used to create the image (optional) |
| datatype | datatype: 'uint8' or 'int8' |
| x_unit | Units of x -axis (optional) |
| y_unit | Units of y-axis (optional) |
| z_unit | Units of z-axis (optional) |
| colormap | Color palette structure |
| alpha | Array with alpha (transparency) values (empty if no alpha) |
| layout | A four chars code describing the memory layout |
| proj4 | Projection string in PROJ4 syntax (optional) |
| wkt | Projection string in WKT syntax (optional) |
Table 4. The Color palette table structure and its attributes
| member | Description |
|---|---|
| colormap | Matrix with R/G/B values for all color intervals |
| alpha | Vector with alpha (transparency) values |
| range | Matrix with [z_low z_high] for each color interval |
| minmax | Vector with [z_min z_max] for entire range |
| bfn | Matrix with R/G/B for back-, fore-ground, and NaNs |
| depth | Color depth as 1 (black/white), 8 (gray) or 24 (colors) |
| hinge | Hinge separating two parts of the CPT [NaN means no hinge] |
| cpt | Full GMT cpt array for communicating with GMT |
| model | Color model used: 'rgb', 'hsv', or 'cmyk' |
| comment | Cell array with any dataset comments [empty after first segment] |
Table 5. The PostScript structure and its attributes
| member | Description |
|---|---|
| postscript | Text array with all PostScript code |
| length | Number of bytes in the string |
| mode | Status mode: 1 = Has header, 2 = Has trailer. 3 = Has both. |
| comment | Comment (optional) |
The interaction is done via the MEX-function gmt. This function is invoked with the syntax
[output objects] = gmt(__modulename__, __optionstring__[, input objects]);
where modulename is a string with the name of a GMT module (e.g., 'surface', 'grdimage', 'psmeca', or even a custom extension), while the optionstring is a text string with the options passed to this module. If the module requires data inputs from the MATLAB environment, then these are provided as optional comma-separated arguments following the option string. Should the module produce output(s) then these are captured in standard MATLAB parlance by assigning the result of gmt to one or more comma-separated variables. Some modules do not require an option string or input objects, or neither, and some modules do not produce any output objects.
In addition, it can also use two i/o modules that are irrelevant on the command line: the read and write modules. These modules allow the toolbox to import and export any of the GMT data types to and from external files. For instance, to import a grid from the file relief.nc we run
G = gmt('read', '-Tg relief.nc');
We use the -T option to specify grid (g), image (i), PostScript (p), color palette (c), dataset (d) or textset (t). Results kept in MATLAB can be written out at any time via the write module, e.g., to save the grid Z to a file we use
gmt('write', 'model_surface.nc', Z);
Because GMT data tables often contain headers followed by many segments, each with their individual segment headers, it is best to read such data using the read module since native MATLAB import via load will choke on such headers.