The GMT/MATLAB API Wiki

1 Introduction

The GMT/MATLAB® API (here called gmt-mex) is a toolbox for MATLAB (it can also be used with Octave). It requires GMT 5.4.x or later, available via the main GMT Download page. With GMT 5.4.x installed users with access to MATLAB® (*) can configure and build the gmt-mex API. One obstacle we are working around on UNIX has to do with shared library conflicts. Because MATLAB® installs several of the same shared libraries that GMT depends on (netcdf, hdf5) and because those libraries tend to be older versions, we may run into problems when a GMT module needs netCDF/HDF but MATLAB® instead loads its own version and then there is a version conflict. Because MATLAB® does not supply include files for these libraries one cannot easily build GMT using their libraries. We will be working with MathWorks to find a good solution. In the meantime we have found a workaround; see below.

2 Install and Build gmt-mex

There are different steps for the different platforms. So far we have been able to do this under Windows and OS X. We will need help from people wishing to run gmt-mex under Linux.

2.1 Install gmt-mex for Windows

The simplest way is to use the gmt-mex enabled Windows GMT 5.4.x installer in the GMT Download page. Since the gmtmex.mexw64|32 and gmt.m files are stored in the bin directory, you will have to add GMTROOT/bin directory to MATLAB®'s search path. Alternatively, see Build gmt-mex under Windows for how to build gmt-mex under Windows.

2.2 Install gmt-mex for OS X

Provided you have a recent MATLAB 201xa|b installed in /Applications, the simplest way is to use the gmt-mex enabled GMT 5.4.0 installer, available from ftp://ftp.soest.hawaii.edu/gmt/bin/mex-gmt-5.4.0-darwin-x84_64.tbz, which when extracted creates a complete GMT 5.4.0 distribution in /opt/gmt:

cd /; sudo tar xjvf <Downloaddirectory>/mex-gmt-5.4.0-darwin-x84_64.tbz
Note: This distribution was built on OS X Sierra using a fully updated MacPorts distribution and is not guaranteed to work for other OS X versions and Unix distributions (fink, HomeBrew). Make sure /opt/gmt/bin is in your PATH. Alternatively, see Build gmt-mex under OS X for how to build gmt-mex under OS X.

2.3 Install gmt-mex for Linux

No luck yet so we need Linux-savvy volunteers; see Build gmt-mex under Linux for how to build gmt-mex under Linux.

3 Test your gmt-mex Installation

Start MATLAB® and make sure your path includes the GMT installation, e.g.,

path ('/opt/gmt/bin', path)   % On OSX or
path ('c:/programs/gmt5/bin', path);   % On Windows

Then try a few simple commands:

  1. gmt
    This should give you the one-line GMT5 synopsis message "Usage: gmt('module_name options', numeric_opts)".
  2. gmt ('psbasemap', '-R0/10/0/15 -JM6i -P -Baf -BWSne+glightblue > map1.ps')
    This should create a basic map called map1.ps in the current directory.
  3. gmt ('pscoast', '-R0/10/0/15 -JM6i -P -Baf -BWSne -Glightbrown > map2.ps')
    This should create a basic map of Africa called map2.ps in the current directory.

If command 1 fails then your path is likely to be wrong. If command 2 fails then your combination of GMT and MATLAB® is possibly not working well - please post your results to the user forum. If command 2 works but 3 fails then you probably have trouble with the netCDF/HDF shared libraries. Again, please post your experiences.

4. Using gmt-mex

Currently, please see the MATLAB Wrapper discussion in the main GMT documentation for typical examples of how to use GMT from within MATLAB®, including how to pass data to and from GMT. Note: Ignore the Installation section which is now superseded by this wiki.

5. Read the toolbox publication

Our initial discussion of the toolbox has been published in G-cubed and you can download a zip file with examples and test data.


(*) MATLAB is a registered trademark of The MathWorks, Inc.