Initial Upload

.gitignore

@@ -0,0 +1 @@
+.DS_Store

README.md

@@ -1,2 +1,17 @@
 # gmt_API_example
-examples for using GMT's c_api
+Examples for using GMT's C_API
+
+## What's GMT?
+The Generic Mapping Tools (GMT) are widely used across the Earth, Ocean, and Planetary sciences and beyond. A diverse community uses GMT to process data, generate publication-quality illustrations, automate workflows, and make animations. Scientific journals, posters at meetings, Wikipedia pages, and many more publications display illustrations made by GMT. And the best part: it is free, open source software licensed under the [LGPL](https://www.gnu.org/licenses/lgpl-3.0.html).
+
+For those who wants to know more, please go to [GMT_site](https://www.generic-mapping-tools.org).
+
+## What are these examples?
+
+* **example1**: call a GMT module to gridding a table data.
+* **example2**: read a grid file and call GMT modules to plot the grid to an image file.
+* **example3**: create a GMT grid container and call GMT modules to plot the grid to an image file.
+
+## How to run the examples?
+
+Simply go to a example folder and run the `compile.sh`.

example1/compile.sh

@@ -0,0 +1,6 @@
+#!/bin/bash
+
+inc=`gmt-config --cflags`
+lib=`gmt-config --libs`
+g++ gridding.cpp $inc $lib -o gridding
+./gridding

example1/gridding.cpp

@@ -0,0 +1,47 @@
+#include "gmt.h"
+#include "iostream"
+#include "string"
+
+int main(int argc, char *argv[])
+{
+	// Initiate a new GMT session
+	void *API = GMT_Create_Session("gridding_example", 2U, 0, NULL);
+
+	// Read table file from disk
+	struct GMT_DATASET *D = reinterpret_cast<GMT_DATASET*>(
+		GMT_Read_Data (API, GMT_IS_DATASET, GMT_IS_FILE, GMT_IS_PLP, 
+			GMT_READ_NORMAL, NULL, "table.txt", NULL));
+
+	// load dataset to a virtual file for gridding
+	// data type of a GMT virtual file must be GMT_STR16
+	char table_file[GMT_STR16] = {""};
+	GMT_Open_VirtualFile(API, GMT_IS_DATASET, GMT_IS_PLP, GMT_IN, D, table_file);
+
+	// create a virtual file to hold result
+	char grid_file[GMT_STR16] = {""};
+	GMT_Open_VirtualFile(API, GMT_IS_GRID, GMT_IS_SURFACE, GMT_OUT, NULL, grid_file);
+
+	// prepare CMD arguments for the gridding module
+	std::string table_file_str = table_file;
+	std::string grid_file_str = grid_file;
+	std::string args_gridding = "-R0/1000/0/1000 -I10 -D1 -St0.3 " + 
+		table_file_str + " -G" + grid_file_str;
+	// call the greenspline module for gridding
+	GMT_Call_Module(API, "greenspline", GMT_MODULE_CMD, (char*) args_gridding.c_str());
+
+	// get grid file from the virtual file for outputting
+	struct GMT_GRID *G = reinterpret_cast<GMT_GRID*>(
+		GMT_Read_VirtualFile(API, grid_file));
+
+	// write the grid to file
+	GMT_Write_Data(API, GMT_IS_GRID, GMT_IS_FILE, GMT_IS_SURFACE, GMT_READ_NORMAL, NULL,
+		"table.nc", G);
+
+	// close virtual files
+	GMT_Close_VirtualFile (API, table_file);
+	GMT_Close_VirtualFile (API, grid_file);
+
+	// end the GMT session
+	GMT_Destroy_Session(API);
+	return 0;
+}

example2/compile.sh

@@ -0,0 +1,6 @@
+#!/bin/bash
+
+inc=`gmt-config --cflags`
+lib=`gmt-config --libs`
+g++ plot_grid.cpp $inc $lib -o plot_grid
+./plot_grid

example2/plot_grid.cpp

@@ -0,0 +1,84 @@
+#include "gmt.h"
+#include "stdio.h"
+#include "unistd.h"
+#include "iostream"
+#include "string"
+
+int main(int argc, char *argv[])
+{
+	std::string cpt_file = "user.cpt";
+	std::string ps_file = "user.ps";
+
+	// Initiate a new GMT session
+	// you need to destroy the session later
+	void *API = GMT_Create_Session("plot_grid_example", 2U, 0, NULL);
+
+	struct GMT_GRID *G = reinterpret_cast<GMT_GRID*>(
+		GMT_Read_Data (API, GMT_IS_GRID, GMT_IS_FILE, GMT_IS_SURFACE, 
+			GMT_READ_NORMAL, NULL, "table.nc", NULL));
+
+	// start the plotting
+	// 1. set GMT defaults
+	std::string args_defaults = "FONT_ANNOT_PRIMARY=10.5p,Times-Roman,black \
+MAP_FRAME_PEN=thinnest,black \
+MAP_GRID_PEN_PRIMARY=thinnest,black \
+MAP_TICK_PEN_PRIMARY=thinnest,black \
+MAP_TICK_LENGTH_PRIMARY=1p/0.5p \
+MAP_TITLE_OFFSET=7.5p \
+MAP_GRID_CROSS_SIZE_PRIMARY=2p \
+FONT_LABEL=10.5p,Times-Roman,black \
+MAP_LABEL_OFFSET=5p \
+MAP_ANNOT_OFFSET_PRIMARY=2.5p";
+	// call gmtset
+	GMT_Call_Module (API, "gmtset", GMT_MODULE_CMD, (char*) args_defaults.c_str());
+
+	// load the grid to a virtual file for plotting
+	char grid_name[GMT_STR16] = {""};
+	GMT_Open_VirtualFile (API, GMT_IS_GRID, GMT_IS_SURFACE, GMT_IN, G, grid_name);
+	// get string type of grid name
+	std::string grid_name_str = grid_name;
+
+	// prepare cpt file
+	std::string args_cpt = grid_name_str + " -Crainbow -R0/1000/0/1000 -Z -D ->" + cpt_file;
+	// call grd2cpt
+	GMT_Call_Module (API, "grd2cpt", GMT_MODULE_CMD, (char*) args_cpt.c_str());
+
+	// plot the image
+	std::string args_image = grid_name_str + " -R0/1000/0/1000 -C" + cpt_file + 
+		" -Bxag+l\"x (m)\" -Byag+l\"y (m)\" -JX1.5i/1.5i -X1.5i -Y1.5i -K -P --MAP_FRAME_AXES=WesNZ ->" + ps_file;
+	// call grdimage
+	GMT_Call_Module (API, "grdimage", GMT_MODULE_CMD, (char*) args_image.c_str());
+
+	// plot color bar
+	std::string args_bar = "-Dx0.1i/-0.2i+w1.3i/0.05i+h -C" + cpt_file + 
+		" -Bxa -By+lm -O -)" + ps_file;
+	// call psscale
+	GMT_Call_Module (API, "psscale", GMT_MODULE_CMD, (char*) args_bar.c_str());
+
+	// convert ps file to raster formats
+	std::string args_pic = ps_file + " -A -TEG -E300";
+	// call psconvert
+	GMT_Call_Module (API, "psconvert", GMT_MODULE_CMD, (char*) args_pic.c_str());
+
+	// close virtual file
+	GMT_Close_VirtualFile (API, grid_name);
+
+	// destroy data container
+	GMT_Destroy_Data(API, G);
+
+	// end the GMT session
+	GMT_Destroy_Session(API);
+
+	// remove temporary files. including GMT defaults
+	remove(cpt_file.c_str());
+	remove(ps_file.c_str());
+	// if exist, delete
+	std::string hist_file = "gmt.history";
+	std::string conf_file = "gmt.conf";
+	if (!access(hist_file.c_str(), F_OK))
+		remove(hist_file.c_str());
+	if (!access(conf_file.c_str(), F_OK))
+		remove(conf_file.c_str());
+
+	return 0;
+}

example3/compile.sh

@@ -0,0 +1,6 @@
+#!/bin/bash
+
+inc=`gmt-config --cflags`
+lib=`gmt-config --libs`
+g++ plot_memory.cpp $inc $lib -o plot_memory
+./plot_memory

example3/plot_memory.cpp

@@ -0,0 +1,113 @@
+#include "gmt.h"
+#include "stdio.h"
+#include "unistd.h"
+#include "iostream"
+#include "string"
+
+int main(int argc, char *argv[])
+{
+	std::string cpt_file = "user.cpt";
+	std::string ps_file = "user.ps";
+
+	// Initiate a new GMT session
+	// you need to destroy the session later
+	void *API = GMT_Create_Session("plot_memory_example", 2U, 0, NULL);
+
+	// prepare header info
+	int m = 101, n = 81;
+	double wesn[4] = {0, 100, 0, 80};
+	double inc[2] = {1, 1};
+	// create an empty data container of GMT_GRID type
+	// forcedly convert pointer type (C++ standard)
+	// you need to destroy the data later
+	struct GMT_GRID *G = reinterpret_cast<GMT_GRID*>(
+		GMT_Create_Data(API, GMT_IS_GRID, GMT_IS_SURFACE, 
+			GMT_CONTAINER_AND_DATA, NULL, &wesn[0], &inc[0], 
+			GMT_GRID_NODE_REG, -1, NULL));
+
+	// manipulate grid data
+	double *x_coord = GMT_Get_Coord(API, GMT_IS_GRID, GMT_X, G);
+	double *y_coord = GMT_Get_Coord(API, GMT_IS_GRID, GMT_Y, G);
+
+	int idx;
+	double minz = 1e+30, maxz = -1e+30;
+	for (int i = 0; i < G->header->n_rows; i++)
+	{
+		for (int j = 0; j < G->header->n_columns; j++)
+		{
+			idx = GMT_Get_Index(API, G->header, i, j);
+			G->data[idx] = x_coord[j] * y_coord[i];
+
+			if (G->data[idx] < minz) minz = G->data[idx];
+			if (G->data[idx] > maxz) maxz = G->data[idx];
+		}
+	}
+
+	G->header->z_min = minz;
+	G->header->z_max = maxz;
+
+	// start the plotting
+	// 1. set GMT defaults
+	std::string args_defaults = "FONT_ANNOT_PRIMARY=10.5p,Times-Roman,black \
+MAP_FRAME_PEN=thinnest,black \
+MAP_GRID_PEN_PRIMARY=thinnest,black \
+MAP_TICK_PEN_PRIMARY=thinnest,black \
+MAP_TICK_LENGTH_PRIMARY=1p/0.5p \
+MAP_TITLE_OFFSET=7.5p \
+MAP_GRID_CROSS_SIZE_PRIMARY=2p \
+FONT_LABEL=10.5p,Times-Roman,black \
+MAP_LABEL_OFFSET=5p \
+MAP_ANNOT_OFFSET_PRIMARY=2.5p";
+	// call gmtset
+	GMT_Call_Module (API, "gmtset", GMT_MODULE_CMD, (char*) args_defaults.c_str());
+
+	// load the grid to a virtual file for plotting
+	char grid_name[GMT_STR16] = {""};
+	GMT_Open_VirtualFile (API, GMT_IS_GRID, GMT_IS_SURFACE, GMT_IN, G, grid_name);
+	// get string type of grid name
+	std::string grid_name_str = grid_name;
+
+	// prepare cpt file
+	std::string args_cpt = grid_name_str + " -Crainbow -R0/100/0/80 -Z -D ->" + cpt_file;
+	// call grd2cpt
+	GMT_Call_Module (API, "grd2cpt", GMT_MODULE_CMD, (char*) args_cpt.c_str());
+
+	// plot the image
+	std::string args_image = grid_name_str + " -R0/100/0/80 -C" + cpt_file + 
+		" -Bxag+l\"x (m)\" -Byag+l\"y (m)\" -JX1.5i/1.5i -X0.5i -Y0.5i -K -P --MAP_FRAME_AXES=WesNZ ->" + ps_file;
+	// call grdimage
+	GMT_Call_Module (API, "grdimage", GMT_MODULE_CMD, (char*) args_image.c_str());
+
+	// plot color bar
+	std::string args_bar = "-Dx0.1i/-0.2i+w1.3i/0.05i+h -C" + cpt_file + 
+		" -Bxa -By+lm -O -)" + ps_file;
+	// call psscale
+	GMT_Call_Module (API, "psscale", GMT_MODULE_CMD, (char*) args_bar.c_str());
+
+	// convert ps file to raster formats
+	std::string args_pic = ps_file + " -A -TEG -E300";
+	// call psconvert
+	GMT_Call_Module (API, "psconvert", GMT_MODULE_CMD, (char*) args_pic.c_str());
+
+	// close virtual file
+	GMT_Close_VirtualFile (API, grid_name);
+
+	// destroy data container
+	GMT_Destroy_Data(API, G);
+
+	// end the GMT session
+	GMT_Destroy_Session(API);
+
+	// remove temporary files. including GMT defaults
+	remove(cpt_file.c_str());
+	remove(ps_file.c_str());
+	// if exist, delete
+	std::string hist_file = "gmt.history";
+	std::string conf_file = "gmt.conf";
+	if (!access(hist_file.c_str(), F_OK))
+		remove(hist_file.c_str());
+	if (!access(conf_file.c_str(), F_OK))
+		remove(conf_file.c_str());
+
+	return 0;
+}