{"id":22282127,"url":"https://github.com/genericmappingtools/gmtmex","last_synced_at":"2025-06-14T14:05:25.091Z","repository":{"id":22321431,"uuid":"95832169","full_name":"GenericMappingTools/gmtmex","owner":"GenericMappingTools","description":"GMT API for MATLAB","archived":false,"fork":false,"pushed_at":"2024-01-07T07:11:39.000Z","size":3662,"stargazers_count":46,"open_issues_count":6,"forks_count":19,"subscribers_count":7,"default_branch":"master","last_synced_at":"2025-04-05T03:31:50.033Z","etag":null,"topics":["generic-mapping-tools","geophysics","geospatial","matlab"],"latest_commit_sha":null,"homepage":"https://github.com/GenericMappingTools/gmtmex/wiki","language":"MATLAB","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"lgpl-2.1","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/GenericMappingTools.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null}},"created_at":"2017-06-30T00:39:06.000Z","updated_at":"2025-03-10T11:19:07.000Z","dependencies_parsed_at":"2024-01-07T08:22:02.526Z","dependency_job_id":null,"html_url":"https://github.com/GenericMappingTools/gmtmex","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/GenericMappingTools/gmtmex","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GenericMappingTools%2Fgmtmex","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GenericMappingTools%2Fgmtmex/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GenericMappingTools%2Fgmtmex/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GenericMappingTools%2Fgmtmex/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/GenericMappingTools","download_url":"https://codeload.github.com/GenericMappingTools/gmtmex/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GenericMappingTools%2Fgmtmex/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":259827647,"owners_count":22917711,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["generic-mapping-tools","geophysics","geospatial","matlab"],"created_at":"2024-12-03T16:25:41.626Z","updated_at":"2025-06-14T14:05:25.044Z","avatar_url":"https://github.com/GenericMappingTools.png","language":"MATLAB","readme":"# GMT/MEX - GMT API for MATLAB\n\n# Extended Docs\n\nhttps://github.com/GenericMappingTools/gmtmex/wiki\n\n# Introduction\n\nThe GMT MATLAB interface makes it possible to access all GMT modules from MATLAB. Users of MATLAB can write MATLAB scripts\nthat call upon GMT modules to do any of the things GMT normally can do, and return the results (grids, data-tables, CPTs,\ntext-files, and even final images via psconvert) to MATLAB variables. MATLAB matrices can be given as input to GMT modules.\nExamples below will give you the general idea.\n\n# Installing\n\n## Windows\n\nThe Windows installers come already with the gmtmex.mexw64|32 and gmt.m files necessary run the MEX. Only make sure that the\nGMT6.4 binary dir is either in the Windows path (the installer does that for you) and in the MATLAB path (you have to do it\nyourself). If you want to (re)build the MEX file yourself, see the compile_mex.bat in the source SVN repository.\n\n## macOS\n\nWe have successfully built the MATLAB interface under macOS. However, due to the way MATLAB handles shared libraries it is a\ndelicate process, with several caveats. This may change over time as we work with MathWorks to straighten out the kinks.\nThe following works:\n\n * Install the GMT macOS Bundle\n * Run the gmt_prepmex.sh script in the bundle's share/tools directory.  This will duplicate\n   the GMT 6.4 installation into /opt/gmt and re-baptize all the shared libraries.\n * Use gmtswitch to make /opt/gmt the current active GMT version\n * Checkout the gmtmex project via git into some directory, i.e.,\n   ```\n   git clone https://github.com/GenericMappingTools/gmtmex.git\n   ```\n * In `gmtmex/`, run autoconf then configure --enable-matlab (and maybe --enable-debug) is you\n   can help debug things.\n * Run make which builds the gmtmex.mexmaci64 (x86_64) or gmtmex.mexmaca64 (arm64).  This executable\n   is accessed by the gmt.m script.\n * Set your MATLAB path so these two can be found (or copy them to a suitable directory).\n * Make sure your gmt.conf file has the entry GMT_CUSTOM_LIBS=/opt/gmt/lib/gmt/plugins/supplements.so.\n\nYou can also build your own bundle (see CMakeLists.txt in main GMT directory).  The above works\nwith UNIX installations from fink or HomeBrew but fails for us if under MacPorts (then, MATLAB\nwill complain about wrong shared HDF5 library and we crash).\nIf you wish to help debug in XCode then see the gmtmex wiki for more details.  While the latest\n2023b MATLAB version works with XCode 14, earlier versions may require an older Xcode version.\nWe used the 2023b MATLAB version to build the interface.\n\n## Unix/Linux\n\nPreliminary experiments indicate we will have to fight the shared library dilemma here as well.\nVolunteers on Linux wishing to run the GMT MATLAB interface are needed to make progress.\n\n# Using\n\nThe MATLAB wrapper was designed to work in a way the closest as possible to the command line version\nand yet to provide all the facilities of the MATLAB IDE (the ML command line desktop). In this sense,\nall **GMT** options are put in a single text string that is passed, plus the data itself when it applies,\nto the ``gmt()`` command. For example to reproduce the CookBook example of an Hemisphere map using a\nAzimuthal projection\n\n    gmt('pscoast -Rg -JA280/30/3.5i -Bg -Dc -A1000 -Gnavy -P \u003e GMT_lambert_az_hemi.ps')\n\nbut that is not particularly interesting as after all we could do the exact same thing on the a shell\ncommand line. Things start to get interesting when we can send data *in* and *out* from MATLAB to\n**GMT**. So, consider the following example\n\n    t = rand(100,3) * 150;\n    G = gmt('surface -R0/150/0/150 -I1', t);\n\nHere we just created a random data *100x3* matrix and told **GMT** to grid it using it's program\n*surface*. Note how the syntax follows closely the standard usage but we sent the data to be\ninterpolated (the *t* matrix) as the second argument to the ``gmt()`` function. And on return we\ngot the *G* variable that is a structure holding the grid and it's metadata. See the\n``grid struct`` for the details of its members.\n\nImagining that we want to plot that random data art, we can do it with a call to *grdimage*, like\n\n    gmt('grdimage -JX8c -Ba -P -Cblue,red \u003e crap_img.ps', G)\n\nNote that we now sent the *G grid* as argument instead of the **-G** *gridname* that we would have\nused in the command line. But for readability we could well had left the **-G** option in command string. E.g:\n\n    gmt('grdimage -JX8c -Ba -P -Cblue,red -G \u003e crap_img.ps', G)\n\nWhile for this particular case it makes no difference to use or not the **-G**, because there is **only**\none input, the same does not hold true when we have more than one. For example, we can run the same example\nbut compute the CPT separately.\n\n    cpt = gmt('grd2cpt -Cblue,red', G);\n    gmt('grdimage -JX8c -Ba -P -C -G \u003e crap_img.ps', G, cpt)\n\nNow we had to explicitly write the **-C** \u0026 **-G** (well, actually we could have omitted the **-G** because\nit's a mandatory input but that would make the things more confusing). Note also the order of the input data variables.\nIt is crucial that any *required* (primary) input data objects (for grdimage that is the grid) are given before\nany *optional* (secondary) input data objects (here, that is the CPT object).  The same is true for modules that\nreturn more than one item: List the required output object first followed by optional ones.\n\nTo illustrate another aspect on the importance of the order of input data let us see how to plot a sine curve\nmade of colored filled circles.\n\n    x = linspace(-pi, pi)';            % The *xx* var\n    seno = sin(x);                     % *yy*\n    xyz  = [x seno seno];              % Duplicate *yy* so that it can be colored\n    cpt  = gmt('makecpt -T-1/1/0.1');  % Create a CPT\n    gmt('psxy -R-3.2/3.2/-1.1/1.1 -JX12c -Sc0.1c -C -P -Ba \u003e seno.ps', xyz, cpt)\n\nThe point here is that we had to give *xyz, cpt* and not *cpt, xyz* (which would error) because optional input data\nassociated with an option letter **always comes after the required input**.\n\nTo plot text strings we send in the input data wrapped in a cell array. Example:\n\n    lines = {'5 6 Some label', '6 7 Another label'};\n    gmt('pstext -R0/10/0/10 -JM6i -Bafg -F+f18p -P \u003e text.ps', lines)\n\nand we get back text info in cell arrays as well. Using the *G* grid computed above we can run *gmtinfo* on it\n\n    info = gmt('info', G)\n\nAt the end of an **GMT** session work we call the internal functions that will do the house keeping of\nfreeing no longer needed memory. We do that with this command:\n\n    gmt('destroy')\n\n\nSo that's basically how it works. When numeric data have to be sent *in* to **GMT** we use\nMATLAB variables holding the data in matrices or structures or cell arrays, depending on data type. On\nreturn we get the computed result stored in variables that we gave as output arguments.\nThings only complicate a little more for the cases where we can have more than one *input* or\n*output* arguments, since the order or the arguments matter (Remember the rule: primary first, secondary second).\nThe file *gallery.m*, that reproduces the examples in the Gallery section of the GMT\ndocumentation, has many (not so trivial) examples on usage of the MEX GMT API.\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgenericmappingtools%2Fgmtmex","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgenericmappingtools%2Fgmtmex","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgenericmappingtools%2Fgmtmex/lists"}