1.. set default highlighting language for this document: 2.. highlight:: c 3 4.. _api: 5 6========= 7GMT C API 8========= 9 10Introduction 11============ 12 13.. index:: ! API 14 15Preamble 16-------- 17 18.. figure:: /_images/GMT4_mode.png 19 :height: 554 px 20 :width: 1122 px 21 :align: center 22 :scale: 50 % 23 24 GMT 4 programs contain all the high-level functionality. 25 26 27Prior to version 5, the bulk of GMT functionality was coded directly 28in the standard GMT C program modules (e.g., ``surface.c``, ``grdimage.c``, etc.). The 29GMT library only offered access to low-level functions from which 30those high-level GMT programs were built. The standard GMT programs 31have been very successful, with tens of thousands of users world-wide. 32However, the design of the main programs prevented developers from 33leveraging GMT functionality from within other programming 34environments since access to GMT tools could only be achieved via 35system calls [1]_. Consequently, all data i/o had to be done via 36temporary files. The design also prevented the GMT developers 37themselves from taking advantage of these modules directly. For 38instance, the tool :doc:`/legend` needed to 39make extensive use of system calls to :doc:`/plot` and 40:doc:`/text` in order to plot the lines, 41symbols and text that make up a map legend, making it a very awkward 42program to maintain. 43 44.. figure:: /_images/GMT5_mode.png 45 :height: 399 px 46 :width: 1116 px 47 :align: center 48 :scale: 50 % 49 50 GMT 5 programs contain all the high-level functionality. 51 52 53Starting with GMT version 5, all standard GMT programs have been 54rewritten into separate function "modules" invoked by a single 55driver program called ``gmt.c``. 56The :doc:`/gmt` executable simply calls the corresponding 57GMT modules; it is these modules that do all the work. These new 58functions have been placed in a new GMT high-level API library and can 59be called from a variety of environments (C/C++, Fortran, Julia, Python, 60MATLAB, Visual Basic, R, etc.) [2]_. For example, the main 61program ``blockmean.c`` has been reconfigured as a high-level function 62``GMT_blockmean()``, which does the actual spatial averaging and can 63pass the result back to the calling program (or write it to file). The 64previous behavior of ``blockmean.c`` is achieved by calling ``gmt blockmean``, 65i.e., the module is now just the first argument to the :doc:`/gmt` executable. 66For backwards compatibility with older GMT (4) scripts we optionally 67install numerous symbolic links to the gmt executable with names such 68as blockmean, plot, surface, etc. The gmt executable is smart enough to 69understand when it is being invoked via one of these links and then knows 70which module to call upon. 71Consequently, ``blockmean.c`` and other files do in 72fact no longer exist. 73 74.. figure:: /_images/GMT5_external.png 75 :height: 616 px 76 :width: 1193 px 77 :align: center 78 :scale: 50 % 79 80 GMT 5 API showing current and future external environments. 81 82 83The i/o abstraction layer 84------------------------- 85 86In order for the API to be as flexible as possible we have 87generalized the notions of input and output. Data that already reside in 88an application's memory may serve as input to a GMT module and we refer 89to such data as "Virtual Files". Other 90sources of input may be file pointers and file descriptors (as well as 91the standard mechanism for passing file names). For standard 92data table i/o, the GMT API takes care of the task of assembling any 93combination of files, pointers, and memory locations into *a single 94virtual data set* from which the GMT module may read (a) all 95records at once into memory, or (b) read one record at a time. Likewise, 96GMT functions may write their output to a virtual destination, which 97might be a memory location in the user's application (another Virtual File), a file pointer or 98descriptor, or an output file. The GMT modules are unaware of these 99details and simply read from a "source" and write to a "destination". 100Thus, the standard concept of file-based input/output so familiar to 101any GMT user carries over to the API, except for the generalization 102that files can be virtual files already in memory. Because of this 103design we will see that we need to associate these virtual files 104with special filenames that we may pass to modules, and the modules 105will faithfully treat these as real files. However, under the hood 106the API layer will take care of the differences between real and 107virtual files. 108 109Users who wish to maintain their own data types and memory management 110can also use the GMT modules, but some limitations and requirements do 111apply: The user's data can either be provided as (1) a 2-D matrix (of 112any data type, e.g., float, integer, etc.) and in any memory layout 113configuration (e.g., row-major or column-major layout) or as (2) a 114set of column vectors that each may be of any type. These custom arrays 115will need to be hooked onto the GMT containers :ref:`GMT_MATRIX <struct-matrix>` 116and :ref:`GMT_VECTOR <struct-vector>`, respectively. 117Such objects can then be treated as virtual files for either input of output. 118 119Our audience 120------------ 121 122Here, we document the new functions in the GMT API library for 123application developers who wish to call these functions from their own 124custom programs. At this point, only the new high-level GMT API is 125fully documented and intended for public use. The structure and 126documentation of the under-lying lower-level GMT library is not 127finalized. Developers using these functions may risk disruption to their 128programs due to changes we may make in the library in support of the 129GMT API. However, developers who wish to make supplemental packages to 130be distributed as part of GMT will (other than talk to us) probably 131want to access the entire low-level GMT library as well. It is 132unlikely that the low-level library will ever be fully documented. 133 134There are two classes of development that users can pursue: 135 136#. Building stand-alone custom executables that link with the shared GMT 137 API. Our examples in this documentation are of this kind. There programs 138 are likely to address a user's special data formats or processing needs 139 by leveraging high-level GMT modules to do some of the heavy lifting. 140 141#. Building shared library plugins to extend the breath of GMT. Users who 142 wish to build one or more new modules and distributed then via a plugin 143 that is dynamically loaded at run-time can now do so. At the present, 144 all the modules in the official GMT supplement are compiled into a single 145 plugin that can be accessed at run-time. Similarly, developers may add 146 additional plugin libraries with any number of GMT-like modules and these 147 will then be available from the gmt command (as well as from derived 148 interfaces such as the GMT/MATLAB toolbox and the Python module). An 149 example of plugin development is given by the 150 `GSFML extension to GMT <http://www.soest.hawaii.edu/PT/GSFML/>`_. 151 152Definitions 153----------- 154 155For the purpose of this documentation a few definitions are needed: 156 157#. "Standard GMT program" refers to one of the traditional stand-alone 158 command-line executables known to all GMT users, e.g., 159 :doc:`/blockmean`, :doc:`/plot`, 160 :doc:`/grdimage`, etc. Prior to version 5, 161 these were the only GMT executables available. In GMT 5 and up, these are 162 accessed via the :doc:`/gmt` executable. 163 164#. "\ GMT module" refers to the function in the GMT API library that 165 is responsible for all the action taken by the corresponding 166 standard GMT program. All such modules are given the same names as the 167 corresponding programs e.g., "blockmean", but are invoked via the 168 ``GMT_Call_Module`` function. 169 170#. "\ GMT application" refers to a new application written by any 171 developer. It uses the API, perhaps for custom i/o, and may call one 172 or more GMT functions to create a new GMT-compatible executable. 173 174#. "\ GMT plugin library" refers to a collection of one or more new custom 175 GMT-like modules that are presented as a plugin library. It such libraries 176 are placed in the official GMT plugin directory or their path is added to 177 the GMT defaults parameter :term:`GMT_CUSTOM_LIBS` then the :doc:`/gmt` executable can find them. 178 179#. "Family" refers to one of the many high-level GMT data types (e.g., grids, CPTs) 180 and is typically a required argument to some API functions. 181 182#. "Method" refers to one of several ways in which data can be read or written 183 in the API, including from existing memory variables. 184 185#. "Direction" is typically either GMT_IN (for reading) or GMT_OUT (for writing). 186 187#. In the API description that follows we will use the type ``int`` to 188 mean a 4-byte integer. All integers used in the API are 4-byte 189 integers with the exception of one function where an 8-byte integer is 190 used. Since different operating systems have their own way of 191 defining 8-byte integers we use C99's ``int64_t`` for this purpose; 192 it is guaranteed to yield the correct type that the GMT function 193 expects. 194 195In version 5, the standard GMT programs are themselves simple invocations 196of the :doc:`/gmt` application with the function name as argument. 197However, some of these modules, such as 198:doc:`/legend`, :doc:`/gmtconvert`, 199:doc:`/grdblend`, 200:doc:`/grdfilter` and others may call several additional modules. 201 202API changes from GMT5 to GMT 6 203------------------------------ 204 205The API released with GMT5 was considered experimental as our usage of it in GMT proper 206as well as in the GMT/MATLAB toolbox and the GMT/Python package would undoubtably lead to 207revisions. We developed API to enable GMT access from other environments hence we want 208the library to address the needs of such developers. Here are the changes in the GMT 6 209API that are not backwards compatible with GMT 5: 210 211#. There is no longer a GMT_TEXTSET resource. Data records are now generalized to 212 contain an optional leading numerical array followed by an optional trailing text. 213 A "TEXTSET" in this context is simply a DATASET that has no leading numerical array. 214 This change was necessary so that all modules reading tables expect the same fundamental 215 GMT_DATASET resource. The alternative (which we lived to regret) was that developers 216 calling modules from their environment would have to format their data in different ways 217 depending on the module, and in some case depending on module options. Now, all table 218 modules expect GMT_DATASET. 219#. The function GMT_Alloc_Segment no longer takes the family of the segment (since there are 220 now only DATASET segments) but the family variable has been reused as a mode which is 221 passed as either GMT_WITH_STRINGS or GMT_NO_STRINGS so that data segments can be allocated 222 with or without the optional string array. 223#. We introduce a new structure GMT_RECORD which is used by GMT_Get_Record and GMT_Put_Record. 224 Because such records may have both leading numerical columns and a trailing string these 225 functions needed to work with such a structure rather than either an array or string. 226#. The unused function GMT_Set_Columns needed to accept *direction* so it could be used for 227 either input or output. It is rarely needed but some tools that must only read *N* numerical 228 columns and treat anything beyond that as trailing text (even if numbers) must set the 229 fixed input columns before reading. We also added one more mode (GMT_COL_FIX_NO_TEXT) to 230 enforce reading of a fixed number of numerical columns and skip any trailing text. 231#. The GMT_DATASET structure has gained a new (hidden) enum GMT_enum_read ``type`` which indicates what 232 record types were read to produce this dataset (GMT_READ_DATA, GMT_READ_TEXT, GMT_READ_MIXED). 233 We also changed the geometry from unsigned int to enum GMT_enum_geometry. 234#. The long obsolete enums GMT_READ_DOUBLE and GMT_WRITE_DOUBLE have now fully been removed; 235 use GMT_READ_DATA and GMT_WRITE_DATA instead. 236#. The GMT_Convert_Data function's flag array is now of length 2 instead of 3 (because there are no 237 longer any TEXTSET settings), with what used to be flag3 now being given as flag2. 238 239GMT resources 240------------- 241 242The GMT API knows how to create, duplicate, read and write six types of data objects common to 243GMT operations: Pure data tables (ASCII or binary), grids, images, cubes, color 244palette tables (also known as CPT), PostScript documents, and text tables (ASCII, 245usually a mix of data and free-form text). In addition, we 246provide two data objects to facilitate the passing of simple user arrays 247(one or more equal-length data columns of any data type, e.g., double, 248char) and 2-D or 3-D user matrices (of any data type and column/row 249organization). We refer to these data types as GMT *resources*. 250There are many attributes for each of these resources and therefore we 251use a top-level structure for each object to keep them all within one 252container. These containers are given or returned by GMT API 253functions using opaque pointers (``void *``). Below we provide a brief 254overview of these containers, listing only the most critical members. 255For complete details, see Appendix A. We will later present how they are used when 256importing or exporting them to or from files, memory locations, or 257streams. The first six are the standard GMT objects, while the latter 258two are special data containers to facilitate the passing of user 259data in and out of GMT modules. These resources are defined in the include 260file ``gmt_resources.h``; please consult this file to ensure correctness 261in case the documentation is not up-to-date. Note than in all instances 262the fundamental data variable is called "data". 263 264Data tables 265~~~~~~~~~~~ 266 267Much data processed in GMT come in the form of ASCII, netCDF, or 268native binary data tables. These may have any number of header records 269(ASCII files only) and perhaps segment headers that separate groups of points 270or lines and polygons. GMT programs will read 271one or more such tables when importing data. However, to avoid memory 272duplication or data limitations some programs may prefer to read such records one 273at the time. The GMT API has functions that let you read your data 274record-by-record by presenting a *virtual* data set that combines all the 275data tables specified as input. This simplifies record processing 276considerably. Programs reading an entire data set will encounter several 277structures: A data set (``struct`` :ref:`GMT_DATASET <struct-dataset>`) may contain any number of 278tables (``struct`` :ref:`GMT_DATATABLE <struct-datatable>`), each with any number of segments 279(``struct`` :ref:`GMT_DATASEGMENT <struct-datasegment>`), each segment with any number of 280records, and each record with any number of (fixed) columns. Thus, the arguments 281to GMT API functions that handle such data sets expect a struct :ref:`GMT_DATASET <struct-dataset>`. 282All segments are expected to have the same number of columns. 283 284.. _struct-dataset2: 285 286.. code-block:: c 287 288 struct GMT_DATASET { /* Single container for an array of GMT tables (files) */ 289 uint64_t n_tables; /* The total number of tables contained */ 290 uint64_t n_columns; /* The number of data columns */ 291 uint64_t n_segments; /* The total number of segments across all tables */ 292 uint64_t n_records; /* The total number of data records across all tables */ 293 double *min; /* Minimum coordinate for each column */ 294 double *max; /* Maximum coordinate for each column */ 295 struct GMT_DATATABLE **table; /* Pointer to array of tables */ 296 }; 297 298The top-level dataset structure for pure data tables contains the table structure, as defined below: 299 300.. _struct-datatable2: 301 302.. code-block:: c 303 304 struct GMT_DATATABLE { /* Single container for an array of data segments */ 305 unsigned int n_headers; /* Number of table header records (0 if no header) */ 306 uint64_t n_columns; /* Number of columns (fields) in each record */ 307 uint64_t n_segments; /* Number of segments in the array */ 308 uint64_t n_records; /* Total number of data records across all segments */ 309 double *min; /* Minimum coordinate for each column */ 310 double *max; /* Maximum coordinate for each column */ 311 char **header; /* Array with all table header records, if any) */ 312 struct GMT_DATASEGMENT **segment; /* Pointer to array of segments */ 313 }; 314 315Finally, the table structure depends on a structure for individual data segments: 316 317.. _struct-datasegment2: 318 319.. code-block:: c 320 321 struct GMT_DATASEGMENT { /* For holding segment lines in memory */ 322 uint64_t n_rows; /* Number of points in this segment */ 323 uint64_t n_columns; /* Number of fields in each record (>= 2) */ 324 double *min; /* Minimum coordinate for each column */ 325 double *max; /* Maximum coordinate for each column */ 326 double **data; /* Data x,y, and possibly other columns */ 327 char **text; /* trailing text strings beyond the data */ 328 char *label; /* Label string (if applicable) */ 329 char *header; /* Segment header (if applicable) */ 330 }; 331 332Data sets may have different geometries, such as representing a set of points, 333one or more lines, or closed polygons. 334 335GMT grids 336~~~~~~~~~ 337 338GMT grids are used to represent equidistant and organized 2-D 339surfaces. These can be processed or plotted as contour maps, color images, or 340perspective surfaces. Because the native GMT grid is simply a 1-D 341float array with metadata kept in a separate ``struct`` :ref:`GMT_GRID_HEADER <struct-gridheader>` header, we pass 342this information via a ``struct`` :ref:`GMT_GRID <struct-grid>`, which is a container that 343holds both items. Thus, the arguments to GMT API functions that handle 344GMT grids expect this type of variable. 345 346.. _struct-grid2: 347 348.. code-block:: c 349 350 struct GMT_GRID { /* A GMT float grid and header in one container */ 351 struct GMT_GRID_HEADER *header; /* The full GMT header for the grid */ 352 float *data; /* Pointer to the float grid array */ 353 }; 354 355The top-level grid structure, holding both header and data array, depends on the grid header structure: 356 357.. code-block:: c 358 359 struct GMT_GRID_HEADER { 360 uint32_t n_columns; /* Number of columns */ 361 uint32_t n_rows; /* Number of rows */ 362 uint32_t registration; /* GMT_GRID_NODE_REG (0) for node grids, 363 GMT_GRID_PIXEL_REG (1) for pixel grids */ 364 double wesn[4]; /* Min/max x and y coordinates */ 365 double z_min; /* Minimum z value */ 366 double z_max; /* Maximum z value */ 367 double inc[2]; /* The x and y increments */ 368 double z_scale_factor; /* Grid values must be multiplied by this factor */ 369 double z_add_offset; /* After scaling, add this */ 370 char x_units[GMT_GRID_UNIT_LEN80]; /* Units in x-direction */ 371 char y_units[GMT_GRID_UNIT_LEN80]; /* Units in y-direction */ 372 char z_units[GMT_GRID_UNIT_LEN80]; /* Grid value units */ 373 char title[GMT_GRID_TITLE_LEN80]; /* Name of data set */ 374 char command[GMT_GRID_COMMAND_LEN320];/* Name of generating command */ 375 char remark[GMT_GRID_REMARK_LEN160]; /* Comments regarding this data set */ 376 }; 377 378 The basic grid header holds the metadata written to grid files. 379 380GMT images 381~~~~~~~~~~ 382 383GMT images are used to represent bit-mapped images typically obtained 384via the GDAL bridge. These can be reprojected internally, such as when 385used in :doc:`/grdimage`. Since images and grids share the concept of a header, 386we use the same header structure for grids as for images; however, some 387additional metadata attributes are also needed. Finally, the image 388itself may be of any data type and have more than one band (channel). 389Both image and header information are passed via a ``struct`` :ref:`GMT_IMAGE <struct-image>`, 390which is a container that holds both items. Thus, the arguments to 391GMT API functions that handle GMT images expect this type of 392variable. Unlike the other objects, writing images has only partial 393support via :doc:`/grdimage` [3]_. 394For the full definition, see :ref:`GMT_IMAGE <struct-image>`. 395 396.. _struct-image2: 397 398.. code-block:: c 399 400 struct GMT_IMAGE { /* A GMT char image, header, and colormap in one container */ 401 enum GMT_enum_type type; /* Data type, e.g. GMT_FLOAT */ 402 int *colormap; /* Array with color lookup values */ 403 int n_indexed_colors; /* Number of colors in a color-mapped image */ 404 struct GMT_GRID_HEADER *header; /* Pointer to full GMT header for the image */ 405 unsigned char *data; /* Pointer to actual image */ 406 }; 407 408 409GMT cubes 410~~~~~~~~~ 411 412GMT cubes are used to represent 3-D grids where all the horizontal layers 413are represented by a single grid header. Thus, all nodes along the third 414dimension are coregistered and in the horizontal plane they are, like all 415GMT grids, equidistant. However, the spacing in the third dimension (which 416is typically depth or time) does not have to be equidistant. At this moment, 417only :doc:`/greenspline` and :doc:`/grdinterpolate` can produce 3-D cubes while 418the latter can also read them (other grid modules can read individual layers 419of a cube as a single grid). 420We use the same header structure as for grids. However, some 421additional metadata attributes are needed for the third dimension. 422Both the cube and header information are passed via a ``struct`` :ref:`GMT_CUBE <struct-cube>`, 423which is a container that holds all items. Thus, the arguments to 424GMT API functions that handle GMT cubes expect this type of 425variable. 426For the full definition, see :ref:`GMT_CUBE <struct-cube>`. 427 428.. _struct-cube2: 429 430.. code-block:: c 431 432 struct GMT_CUBE { /* A GMT 3-D cube in one container */ 433 struct GMT_GRID_HEADER *header; /* The full GMT header for the grid */ 434 float *data; /* Pointer to the float 3-D array */ 435 }; 436 437Color palette tables (CPT) 438~~~~~~~~~~~~~~~~~~~~~~~~~~ 439 440The color palette table files, or just CPTs, contain colors and 441patterns used for plotting data such as surfaces (i.e., GMT grids) or 442symbols, lines and polygons (i.e., GMT tables). GMT programs will 443generally read in a color palette table, make it the current palette, do 444the plotting, and destroy the table when done. The information is 445accessed via a pointer to ``struct`` :ref:`GMT_PALETTE <struct-palette>`. Thus, the arguments 446to GMT API functions that handle palettes expect this type of 447variable. It is not expected that users will wish to manipulate the CPT 448directly, but rather use this mechanism to hold them in memory and 449pass as arguments to GMT modules. Developers are unlikely to actually 450manipulate the contents of CPT structures but if needed then 451the full definition can be found in :ref:`GMT_PALETTE <struct-palette>`. 452 453.. _struct-palette2: 454 455.. code-block:: c 456 457 struct GMT_PALETTE { /* Holds color-related parameters for look-up */ 458 unsigned int n_headers; /* Number of CPT header records (0 if no header) */ 459 unsigned int n_colors; /* Number of colors in the data array */ 460 unsigned int mode; /* Flags controlling use of BFN colors */ 461 struct GMT_LUT *data; /* CPT lookup data with color information */ 462 struct GMT_BFN bfn[3]; /* Structures with back/fore/nan fills */ 463 char **header; /* Array with all CPT header records, if any) */ 464 }; 465 466PostScript document 467~~~~~~~~~~~~~~~~~~~ 468 469Normally, GMT modules producing PostScript will write to standard output 470or a designated file. Alternatively, you can tell the API to write to a 471memory buffer instead and then receive a structure with the final 472plot (or partial plot) represented as a long text string. 473The full structure definition can be found in :ref:`GMT_POSTSCRIPT <struct-postscript>`. 474 475.. _struct-postscript2: 476 477.. code-block:: c 478 479 struct GMT_POSTSCRIPT { /* Single container for a chunk of PostScript text */ 480 unsigned int n_headers; /* Number of PostScript header records (0 if no header) */ 481 size_t n_bytes; /* Length of data array so far */ 482 unsigned int mode; /* Bit-flag for header (1) and trailer (2) */ 483 char *data; /* Pointer to actual PostScript text */ 484 char **header; /* Array with all PostScript header records, if any) */ 485 }; 486 487User data matrices 488~~~~~~~~~~~~~~~~~~ 489 490Users may write programs that need to call GMT modules but may keep their data in separate 4912-D arrays that the allocate and maintain independent of GMT. 492For instance, a program may have built an integer 2-D matrix in memory and wish to 493use that as the input grid to the ``grdfilter`` module, which 494normally expects a ``struct`` :ref:`GMT_GRID <struct-grid>` with floating point data via an actual or virtual 495file. To handle this case we create a ``struct`` :ref:`GMT_MATRIX <struct-matrix>` container (see :ref:`Create empty resources <sec-create>`), 496assign the appropriate union pointer to your data matrix and provide information on dimensions 497and data type. We then open this container as a virtual file and pass its filename to any module. 498The full structure definition can be found in :ref:`GMT_MATRIX <struct-matrix>`. 499 500.. _struct-matrix2: 501 502.. code-block:: c 503 504 struct GMT_MATRIX { /* Single container to hold a user matrix */ 505 uint64_t n_rows; /* Number of rows in the matrix */ 506 uint64_t n_columns; /* Number of columns in the matrix */ 507 uint64_t n_layers; /* Number of layers in a 3-D matrix */ 508 enum GMT_enum_fmt shape; /* 0 = C (rows) and 1 = Fortran (cols) */ 509 enum GMT_enum_reg registration; /* 0 for gridline and 1 for pixel registration */ 510 size_t dim; /* Allocated length of longest C or Fortran dim */ 511 size_t size; /* Byte length of data */ 512 enum GMT_enum_type type; /* Data type, e.g. GMT_FLOAT */ 513 double range[6]; /* Contains xmin/xmax/ymin/ymax[/zmin/zmax] */ 514 union GMT_UNIVECTOR data; /* Pointer to actual matrix of the chosen type */ 515 char **text; /* Pointer to optional array of strings [NULL] */ 516 }; 517 518The ``enum`` types referenced in :ref:`GMT_VECTOR <struct-vector>` and 519Table :ref:`GMT_MATRIX <struct-matrix>` and summarized in Table :ref:`types <tbl-types>`. 520 521User data columns 522~~~~~~~~~~~~~~~~~ 523 524Likewise, programs may instead be manipulating a set of custom column vectors. 525For instance, the user's program may have allocated and populated 526three column arrays of type float and wishes to use these as the input 527source to the ``surface`` module, which normally expects double 528precision triplets via a ``struct`` :ref:`GMT_DATASET <struct-dataset>` read from an actual or virtual file 529Simply create a new :ref:`GMT_VECTOR <struct-vector>` container 530(see section :ref:`Create empty resources <sec-create>`) and assign the union array pointers (see 531:ref:`univector <struct-univector>`) to your data columns and provide the required 532information on length, data types, and optionally range. Again, once we open this data 533as a virtual file we can pass its filename to any module expecting such data. 534The full structure definition can be found in :ref:`GMT_VECTOR <struct-vector>`. 535 536.. _struct-vector2: 537 538.. code-block:: c 539 540 struct GMT_VECTOR { /* Single container to hold user vectors */ 541 uint64_t n_columns; /* Number of vectors */ 542 uint64_t n_rows; /* Number of rows in each vector */ 543 enum GMT_enum_reg registration; /* 0 for gridline and 1 for pixel registration */ 544 enum GMT_enum_type *type; /* Array with data type for each vector */ 545 union GMT_UNIVECTOR *data; /* Array with unions for each column */ 546 double range[2]; /* The min and max limits on t-range (or 0,0) */ 547 char **text; /* Pointer to optional array of strings [NULL] */ 548 }; 549 550Data record 551~~~~~~~~~~~ 552 553For record-by-record i/o we use the GMT_RECORD structure. 554 555.. _struct-record: 556 557.. code-block:: c 558 559 struct GMT_RECORD { /* Single container for an array of GMT tables (files) */ 560 double *data; /* Pointer to array of double-precision numbers [NULL] */ 561 char *text; /* Pointer to the trailing string [NULL] */ 562 }; 563 564 565.. _chapter-overview: 566 567Overview of the GMT C Application Program Interface 568=================================================== 569 570Users who wish to create their own GMT application based on the API 571must make sure their program goes through the steps below. The details for 572each step will be revealed in the following chapter. We have kept the 573API simple: In addition to the GMT modules, there are only 57 public 574functions to become familiar with, but most applications will only use a 575very small subset of this selection. Functions either return an integer error 576code (when things go wrong; otherwise it is set to ``GMT_NOERROR (0)``), or they 577return a void pointer to a GMT resource (or NULL if things go wrong). 578In either case, the API will report what the error is. The layout here 579assumes you wish to use virtual files as input sources (i.e., data you already 580have in memory); if the data must be 581read from actual data files then things simplify considerably. 582 583To keep things as simple as possible we will assume you are writing an 584application that will read in table data, call a module using the data in 585memory as input, and then save the output from the module back into 586another memory location. No actual processing of the data or further 587calculation will be done here (so a bit of a boring program, but the 588point is to develop something short we can test). Also, to keep the code 589short we completely ignore 590the return codes of the modules for now. We will call our program 591:ref:`example1.c <example-code1>`. Here are the steps: 592 593#. Initialize a new GMT session with GMT_Create_Session_, which 594 allocates a hidden GMT API control structure and returns an opaque 595 pointer to it. This pointer is a *required* argument to all subsequent 596 GMT API function calls within the session. 597 598#. Read a data set (or grid, etc.) into memory with GMT_Read_Data_, 599 which, depending on data type, returns one of the data structures 600 discussed earlier. 601 602#. Associate your data with a virtual file using GMT_Open_VirtualFile_. 603 This steps returns a special filename that you can use to tell a module where 604 to read its input. No actual file is created. 605 606#. Open a new virtual file to hold the output using GMT_Open_VirtualFile_. 607 This step also returns a special filename for the module to send its output. 608 609#. Prepare required arguments (including the two virtual file names) and 610 call the GMT module you wish to use via GMT_Call_Module. 611 612#. Obtain the desired output object via GMT_Read_VirtualFile_, which 613 returns a data structure of requested type. 614 615#. Close the virtual files you have been using with GMT_Close_VirtualFile_. 616 617#. We terminate the GMT session by calling GMT_Destroy_Session_. 618 619Example code 620------------ 621 622For the example code to run you must have Internet access. Compile and run 623this program: 624 625.. _example-code1: 626 627.. code-block:: c 628 629 #include "gmt.h" 630 int main (int argc, char *argv[]) { 631 void *API; /* The API control structure */ 632 struct GMT_DATASET *D = NULL; /* Structure to hold input dataset */ 633 struct GMT_GRID *G = NULL; /* Structure to hold output grid */ 634 char input[GMT_VF_LEN] = {""}; /* String to hold virtual input filename */ 635 char output[GMT_VF_LEN] = {""}; /* String to hold virtual output filename */ 636 char args[128] = {""}; /* String to hold module command arguments */ 637 638 /* Initialize the GMT session */ 639 API = GMT_Create_Session ("test", 2U, 0, NULL); 640 /* Read in our data table to memory */ 641 D = GMT_Read_Data (API, GMT_IS_DATASET, GMT_IS_FILE, GMT_IS_PLP, GMT_READ_NORMAL, NULL, 642 "@Table_5_11.txt", NULL); 643 /* Associate our data table with a virtual file */ 644 GMT_Open_VirtualFile (API, GMT_IS_DATASET, GMT_IS_PLP, GMT_IN, D, input); 645 /* Create a virtual file to hold the resulting grid */ 646 GMT_Open_VirtualFile (API, GMT_IS_GRID, GMT_IS_SURFACE, GMT_OUT, NULL, output); 647 /* Prepare the module arguments */ 648 sprintf (args, "-R0/7/0/7 -I0.2 -D1 -St0.3 %s -G%s", input, output); 649 /* Call the greenspline module */ 650 GMT_Call_Module (API, "greenspline", GMT_MODULE_CMD, args); 651 /* Obtain the grid from the virtual file */ 652 G = GMT_Read_VirtualFile (API, output); 653 /* Close the virtual files */ 654 GMT_Close_VirtualFile (API, input); 655 GMT_Close_VirtualFile (API, output); 656 /* Write the grid to file */ 657 GMT_Write_Data (API, GMT_IS_GRID, GMT_IS_FILE, GMT_IS_SURFACE, GMT_READ_NORMAL, NULL, 658 "junk.nc", G); 659 /* Destroy the GMT session */ 660 GMT_Destroy_Session (API); 661 }; 662 663Compilation 664----------- 665 666To compile this program (we assume it is called example1.c), we use the 667gmt-config script to determine the correct compile and link flags and then run 668gcc: 669 670.. _example-comp: 671 672.. code-block:: bash 673 674 inc=`gmt-config --cflags` 675 lib=`gmt-config --libs` 676 gcc example1.c $inc $lib -o example1 677 ./example1 678 679This obviously assumes you have already installed GMT and that it is in your path. 680If you run example1 it will take a moment (this is mostly due to the gridding 681performed by :doc:`/greenspline`) and then it stops. You should find the resulting 682grid junk.nc in the current directory. Plot it to see if it makes sense, e.g. 683 684.. _example-view: 685 686.. code-block:: bash 687 688 gmt grdimage junk.nc -Jx1:50 -Bafg > junk.ps 689 690If you intend to write applications that take any number of data files 691via the command line then there will be more book-keeping to deal with, 692and we will discuss those steps later. 693Likewise, if you need to process a file record-by-record then more lines 694of code will be required. 695 696Plugins 697------- 698 699Developers who wish to make custom plugin libraries that are compatible 700with GMT should examine the fully functioning examples of more involved 701code, available from the repository gmt-custom, obtainable via 702 703.. code-block:: bash 704 705 git clone https://github.com/GenericMappingTools/custom-supplements.git 706 707 708List of API functions 709--------------------- 710 711The following is an alphabetical listing of all the public API functions in GMT. Click on 712any of them to see the full syntax of each function. 713 714The C/C++ API is deliberately kept small to make it easy to use. 715 716.. _tbl-API: 717 718 +--------------------------+-------------------------------------------------------+ 719 | constant | description | 720 +==========================+=======================================================+ 721 | GMT_Alloc_Segment_ | Allocate data segments | 722 +--------------------------+-------------------------------------------------------+ 723 | GMT_Append_Option_ | Append new option structure to linked list | 724 +--------------------------+-------------------------------------------------------+ 725 | GMT_Begin_IO_ | Enable record-by-record i/o | 726 +--------------------------+-------------------------------------------------------+ 727 | GMT_Call_Module_ | Call any of the GMT modules | 728 +--------------------------+-------------------------------------------------------+ 729 | GMT_Convert_Data_ | Convert between compatible data types | 730 +--------------------------+-------------------------------------------------------+ 731 | GMT_Close_VirtualFile_ | Close a virtual file | 732 +--------------------------+-------------------------------------------------------+ 733 | GMT_Create_Args_ | Convert linked list of options to text array | 734 +--------------------------+-------------------------------------------------------+ 735 | GMT_Create_Cmd_ | Convert linked list of options to command line | 736 +--------------------------+-------------------------------------------------------+ 737 | GMT_Create_Data_ | Create an empty data resource | 738 +--------------------------+-------------------------------------------------------+ 739 | GMT_Create_Options_ | Convert command line options to linked list | 740 +--------------------------+-------------------------------------------------------+ 741 | GMT_Create_Session_ | Initialize a new GMT session | 742 +--------------------------+-------------------------------------------------------+ 743 | GMT_Delete_Option_ | Delete an option structure from the linked list | 744 +--------------------------+-------------------------------------------------------+ 745 | GMT_Destroy_Args_ | Delete text array of arguments | 746 +--------------------------+-------------------------------------------------------+ 747 | GMT_Destroy_Cmd_ | Delete text command of arguments | 748 +--------------------------+-------------------------------------------------------+ 749 | GMT_Destroy_Data_ | Delete a data resource | 750 +--------------------------+-------------------------------------------------------+ 751 | GMT_Destroy_Group_ | Delete a group of data resources | 752 +--------------------------+-------------------------------------------------------+ 753 | GMT_Destroy_Options_ | Delete the linked list of option structures | 754 +--------------------------+-------------------------------------------------------+ 755 | GMT_Destroy_Session_ | Terminate a GMT session | 756 +--------------------------+-------------------------------------------------------+ 757 | GMT_Duplicate_Data_ | Make an identical copy of a data resources | 758 +--------------------------+-------------------------------------------------------+ 759 | GMT_Encode_Options_ | Encode option arguments for external interfaces | 760 +--------------------------+-------------------------------------------------------+ 761 | GMT_Error_Message_ | Return character pointer to last API error message | 762 +--------------------------+-------------------------------------------------------+ 763 | GMT_Expand_Option_ | Expand option with explicit memory references | 764 +--------------------------+-------------------------------------------------------+ 765 | GMT_End_IO_ | Disable further record-by-record i/o | 766 +--------------------------+-------------------------------------------------------+ 767 | GMT_FFT_ | Take the Fast Fourier Transform of data object | 768 +--------------------------+-------------------------------------------------------+ 769 | GMT_FFT_1D_ | Take the Fast Fourier Transform of 1-D float data | 770 +--------------------------+-------------------------------------------------------+ 771 | GMT_FFT_2D_ | Take the Fast Fourier Transform of 2-D float data | 772 +--------------------------+-------------------------------------------------------+ 773 | GMT_FFT_Create_ | Initialize the FFT machinery | 774 +--------------------------+-------------------------------------------------------+ 775 | GMT_FFT_Destroy_ | Terminate the FFT machinery | 776 +--------------------------+-------------------------------------------------------+ 777 | GMT_FFT_Option_ | Explain the FFT options and modifiers | 778 +--------------------------+-------------------------------------------------------+ 779 | GMT_FFT_Parse_ | Parse argument with FFT options and modifiers | 780 +--------------------------+-------------------------------------------------------+ 781 | GMT_FFT_Wavenumber_ | Return wavenumber given data index | 782 +--------------------------+-------------------------------------------------------+ 783 | GMT_Find_Option_ | Find an option in the linked list | 784 +--------------------------+-------------------------------------------------------+ 785 | GMT_Free_ | Free GMT-allocated non-container memory | 786 +--------------------------+-------------------------------------------------------+ 787 | GMT_Get_Common_ | Determine if a GMT common option was set | 788 +--------------------------+-------------------------------------------------------+ 789 | GMT_Get_Coord_ | Create a coordinate array | 790 +--------------------------+-------------------------------------------------------+ 791 | GMT_Get_Default_ | Obtain one of the API or GMT default settings | 792 +--------------------------+-------------------------------------------------------+ 793 | GMT_Get_Enum_ | Obtain one of the API enum constants | 794 +--------------------------+-------------------------------------------------------+ 795 | GMT_Get_FilePath_ | Verify input file exist and replace with full path | 796 +--------------------------+-------------------------------------------------------+ 797 | GMT_Get_Index_ | Convert row, col into a grid or image 1-D index | 798 +--------------------------+-------------------------------------------------------+ 799 | GMT_Get_Index3_ | Convert row, col, layer into a cube 1-D index | 800 +--------------------------+-------------------------------------------------------+ 801 | GMT_Get_Info_ | Obtain meta data (range, dimension), ... from object | 802 +--------------------------+-------------------------------------------------------+ 803 | GMT_Get_Matrix_ | Obtain pointer to user matrix from container | 804 +--------------------------+-------------------------------------------------------+ 805 | GMT_Get_Pixel_ | Get grid or image node | 806 +--------------------------+-------------------------------------------------------+ 807 | GMT_Get_Record_ | Import a single data record | 808 +--------------------------+-------------------------------------------------------+ 809 | GMT_Get_Row_ | Import a single grid row | 810 +--------------------------+-------------------------------------------------------+ 811 | GMT_Get_Status_ | Check status of record-by-record i/o | 812 +--------------------------+-------------------------------------------------------+ 813 | GMT_Get_Strings_ | Obtain pointer to user strings from matrix or vector | 814 +--------------------------+-------------------------------------------------------+ 815 | GMT_Get_Values_ | Convert string into coordinates or dimensions | 816 +--------------------------+-------------------------------------------------------+ 817 | GMT_Get_Vector_ | Obtain pointer to user vector from container | 818 +--------------------------+-------------------------------------------------------+ 819 | GMT_Get_Version_ | Return the current lib version as a float | 820 +--------------------------+-------------------------------------------------------+ 821 | GMT_Init_IO_ | Initialize i/o given registered resources | 822 +--------------------------+-------------------------------------------------------+ 823 | GMT_Init_VirtualFile_ | Reset a virtual file for reuse | 824 +--------------------------+-------------------------------------------------------+ 825 | GMT_Inquire_VirtualFile_ | Get family of a virtual file | 826 +--------------------------+-------------------------------------------------------+ 827 | GMT_Make_Option_ | Create an option structure | 828 +--------------------------+-------------------------------------------------------+ 829 | GMT_Message_ | Issue a message, optionally with time stamp | 830 +--------------------------+-------------------------------------------------------+ 831 | GMT_Open_VirtualFile_ | Select memory location as input or output for module | 832 +--------------------------+-------------------------------------------------------+ 833 | GMT_Option_ | Explain one or more GMT common options | 834 +--------------------------+-------------------------------------------------------+ 835 | GMT_Parse_Common_ | Parse the GMT common options | 836 +--------------------------+-------------------------------------------------------+ 837 | GMT_Put_Levels_ | Put user level coordinates into cube container | 838 +--------------------------+-------------------------------------------------------+ 839 | GMT_Put_Matrix_ | Put user matrix into container | 840 +--------------------------+-------------------------------------------------------+ 841 | GMT_Put_Record_ | Export a data record | 842 +--------------------------+-------------------------------------------------------+ 843 | GMT_Put_Row_ | Export a grid row | 844 +--------------------------+-------------------------------------------------------+ 845 | GMT_Put_Strings_ | Put user strings into various containers | 846 +--------------------------+-------------------------------------------------------+ 847 | GMT_Put_Vector_ | Put user vector into container | 848 +--------------------------+-------------------------------------------------------+ 849 | GMT_Read_Data_ | Import a data resource or file | 850 +--------------------------+-------------------------------------------------------+ 851 | GMT_Read_Group_ | Import a group of data resources or files | 852 +--------------------------+-------------------------------------------------------+ 853 | GMT_Read_VirtualFile_ | Access the output from a module via memory | 854 +--------------------------+-------------------------------------------------------+ 855 | GMT_Register_IO_ | Register a resources for i/o | 856 +--------------------------+-------------------------------------------------------+ 857 | GMT_Report_ | Issue a message contingent upon verbosity level | 858 +--------------------------+-------------------------------------------------------+ 859 | GMT_Set_Default_ | Set one of the API or GMT default settings | 860 +--------------------------+-------------------------------------------------------+ 861 | GMT_Set_Comment_ | Assign a comment to a data resource | 862 +--------------------------+-------------------------------------------------------+ 863 | GMT_Set_Columns_ | Specify how many columns to use for rec-by-rec i/o | 864 +--------------------------+-------------------------------------------------------+ 865 | GMT_Set_Geometry_ | Specify data geometry for rec-by-rec i/o | 866 +--------------------------+-------------------------------------------------------+ 867 | GMT_Set_Index_ | Convert row, col into a grid or image index | 868 +--------------------------+-------------------------------------------------------+ 869 | GMT_Update_Option_ | Modify an option structure | 870 +--------------------------+-------------------------------------------------------+ 871 | GMT_Write_Data_ | Export a data resource | 872 +--------------------------+-------------------------------------------------------+ 873 874 Summary of all the API functions and their purpose. 875 876The GMT C Application Program Interface 877======================================= 878 879Initialize a new GMT session 880---------------------------- 881 882Advanced programs may be calling more than one GMT session and thus 883run several sessions, perhaps concurrently as different threads on 884multi-core machines. We will now discuss these steps in more detail. 885Throughout, we will introduce upper-case GMT C enum constants *in 886lieu* of simple integer constants. These are considered part of the API 887and are available for developers via the ``gmt_resources.h`` include file. 888 889Most applications will need to initialize only a single GMT session. 890This is true of all the standard GMT programs since they only call one 891GMT module and then exit. Most user-developed GMT applications are 892likely to only initialize one session even though they may call many 893GMT modules. However, the GMT API supports any number of 894simultaneous sessions should the programmer wish to take advantage of 895it. This might be useful when you have access to several CPUs and want 896to spread the computing load [4]_. In the following discussion we will 897simplify our treatment to the use of a single session only. 898 899To initiate the new GMT session we use 900 901.. _GMT_Create_Session: 902 903 :: 904 905 void *GMT_Create_Session (const char *tag, unsigned int pad, unsigned int mode, 906 int (*print_func) (FILE *, const char *)); 907 908and you will typically call it like this: 909 910 :: 911 912 void *API = NULL; /* Opaque pointer to GMT controls */ 913 API = GMT_Create_Session ("Session name", 2, 0, NULL); 914 915where ``API`` is an opaque pointer to the hidden GMT API control 916structure. You will need to pass this pointer to *all* subsequent 917GMT API functions; this is how essential internal information is 918passed around. The key task of this initialization is to 919set up the GMT machinery and internal variables used for map 920projections, plotting, i/o, etc. The initialization also allocates space 921for internal structures used to keep track of data. The ``pad`` argument 922specifies how many rows and columns should be used as padding for grids and 923images so that boundary conditions can be applied. GMT uses 2 and we strongly 924recommend that you use that value. In particular, if you choose 0 or 1 there may be certain 925GMT modules that will be unable to do their work properly as they count on those 926boundary rows and columns in the grids. Note that this setting has no effect 927on what is written to a grid file; the padding is an internal feature. 928The ``mode`` argument is only used for external APIs that need 929to communicate their special needs during the session creation. This integer argument 930is a sum of bit flags and the various bits control the following settings: 931 932#. Bit 1 (1 or GMT_SESSION_NOEXIT): If set, then GMT will not call the system exit function when a 933 serious problem has been detected but instead will simply return control 934 to the calling environment. For instance, this is required by the GMT/MATLAB toolbox 935 since calling exit would also exit MATLAB itself. Unless your environment 936 has this feature you should leave this bit alone. 937#. Bit 2 (2 or GMT_SESSION_EXTERNAL): If set, then it means we are calling the GMT API from an external 938 API, such as MATLAB, Octave, or Python. Normal C/C++ programs should 939 leave this bit alone. Its effect is to enable two additional modules 940 for reading and writing GMT resources from these environments (those modules 941 would not make any sense in a Unix command-line environment). 942#. Bit 3 (4 or GMT_SESSION_COLMAJOR): If set, then it means the external API uses a column-major format for 943 matrices (e.g., MATLAB, Fortran). If not set we default to row-major 944 format (C/C++, Python, etc.). 945#. Big 4 (8 or GMT_SESSION_LOGERRORS): If set, we redirect all error messages to a log file based on the 946 session name (we append ".log"). 947#. Bit 5 (16 or GMT_SESSION_RUNMODE): If set, the we enable GMT's modern run-mode (where -O -K are 948 not allowed and PostScript is written to hidden temp file). Default 949 is the GMT classic run-mode. 950#. Bit 6 (32 or GMT_SESSION_NOHISTORY): If set, then we disable GMT's command shorthand via gmt.history files. 951 The default is to allow this communication between GMT modules. 952#. Bit 7 (64 or GMT_SESSION_NOGDALCLOSE): If set with GMT_SESSION_EXTERNAL, then we do not close the 953 GDAL connection as the calling environment requires it to stay open. 954 955The ``print_func`` argument is a pointer to a function that is used to print 956messages from GMT via GMT_Message_ or GMT_Report_ from external environments that cannot use the 957standard printf function (this is the case for the GMT/MATLAB toolbox, for instance). 958For all other uses you should simply pass NULL for this argument. You can also access 959the last cached error message by calling GMT_Error_Message_ which returns a pointer to 960the internal character buffer with that message. Pass NULL and set the mode bit if you 961want writing to a log file instead. 962Should something go wrong during the API initialization then ``API`` will be returned as ``NULL``. 963Finally, GMT_Create_Session_ will examine the environmental parameter TMPDIR (TEMP on Windows) 964to set the GMT temporary directory [/tmp on Unix, current directory on Windows]. 965 966Below is a bare-bones minimalistic GMT program hello.c that initializes and destroys 967a GMT session: 968 969.. _example-code2: 970 971.. code-block:: c 972 973 #include "gmt.h" 974 int main (int argc, char *argv[]) { 975 void *API; /* The API control structure */ 976 /* Initialize the GMT session */ 977 API = GMT_Create_Session ("test", 2U, 0, NULL); 978 /* And now for something original: */ 979 GMT_Message (API, GMT_TIME_NONE, "hello, world\n"); 980 /* Destroy the GMT session */ 981 GMT_Destroy_Session (API); 982 }; 983 984While not super-exiting, this code demonstrates the two essential API calls 985required to initiate and later terminate a GMT session. In between we do what 986all basic programs are supposed to do: print "Hello, world". The user is of course 987allowed to do whatever custom processing before the GMT session is created 988and can do all sorts of stuff after the GMT session is destroyed, as long as 989no GMT functions or resources are accessed. It may be convenient to isolate 990the GMT-specific processing from the custom part of the program and only 991maintain an active GMT session when needed. 992 993Get full path to local or remote files 994-------------------------------------- 995 996If given a filename, GMT will look in several directories to find the given 997input file. However, GMT can also look for files remotely, either via the 998remote file mechanism or URLs. When you have a remote file (@filename) you 999may wish to have GMT automatically download the file and provide you with the 1000local path. This is a job for GMT_Get_FilePath_, whose prototype is 1001 1002.. _GMT_Get_FilePath: 1003 1004 :: 1005 1006 int GMT_Get_FilePath (void *API, unsigned int family, unsigned int direction, 1007 unsigned int mode, char **ptr); 1008 1009where :ref:`family <tbl-family>` and ``direction`` set the data file type and whether it is 1010for input or output, ``mode`` modifies the behavior of the function, and 1011``*ptr`` is a pointer to a character string with the filename in question. Normally, 1012we only look for local files (GMT_FILE_LOCAL [0]), but if ``mode`` contains 1013the bit flag GMT_FILE_REMOTE [1] we will try to download any remote files given 1014to the function. By default, we will replace the filename with the full 1015path. Add the bit flag GMT_FILE_CHECK [2] to only check for the files and return 1016error codes but leave ``*ptr`` alone. 1017 1018 1019Register input or output resources 1020---------------------------------- 1021 1022When using the standard GMT programs, it is common to specify input files on the 1023command line or via special program options (e.g., 1024**-I**\ *intensity.nc*). The outputs of the programs are either written 1025to standard output (which you may redirect to files or pipes into other 1026programs) or to files specified by specific program options (e.g., 1027**-G**\ *output.nc*). Alternatively, the GMT API allows you to specify 1028input (and output) to be associated with open file handles or virtual files. 1029We will examine this more closely below. Registering a 1030resource is a required step before attempting to import or export data 1031that *do not* come from files or standard input/output. 1032 1033.. _sec-res_init: 1034 1035Resource initialization 1036~~~~~~~~~~~~~~~~~~~~~~~ 1037 1038All GMT programs dealing with input or output files given on the 1039command line, and perhaps defaulting to the standard input or output 1040streams if no files are given, must call the i/o initializer function 1041GMT_Init_IO_ once for each direction required (i.e., input and output 1042separately). For input it determines how many input sources have already 1043been registered. If none has been registered then it scans the program 1044arguments for any filenames given on the command line and register these 1045input resources. Finally, if we still have found no input sources we 1046assign the standard input stream as the single input source. For output 1047it is similar: If no single destination has been registered we specify 1048the standard output stream as the output destination. Only one main 1049output destination is allowed to be active when a module writes data 1050(some modules also write additional output via program-specific 1051options). The prototype for this function is 1052 1053.. _GMT_Init_IO: 1054 1055 :: 1056 1057 int GMT_Init_IO (void *API, unsigned int family, unsigned int geometry, 1058 unsigned int direction, unsigned int mode, unsigned int n_args, void *args); 1059 1060where :ref:`family <tbl-family>` specifies what kind of resource is to be registered, 1061:ref:`geometry <tbl-geometry>` specifies the geometry of the data, ``direction`` is either 1062``GMT_IN`` or ``GMT_OUT``, and ``mode`` is a bit flag that determines 1063what we do if no resources have been registered. The choices are 1064 1065 **GMT_ADD_FILES_IF_NONE** (1) means "add command line (option) 1066 files if none have been registered already". 1067 1068 **GMT_ADD_FILES_ALWAYS** (2) means "always add any command line files". 1069 1070 **GMT_ADD_STDIO_IF_NONE** (4) means "add std\* if no other 1071 input/output have been specified". 1072 1073 **GMT_ADD_DEFAULT** (6) means "always add any command line files first, and then 1074 add std\* if no other input/output were specified". 1075 1076 **GMT_ADD_STDIO_ALWAYS** (8) means "always add std\* even if 1077 resources have been registered". 1078 1079 **GMT_ADD_EXISTING** (16) means "only use already registered resources". 1080 1081The standard behavior is ``GMT_ADD_DEFAULT`` (6). Next, ``n_args`` is 0 1082if ``args`` is the head of a linked list of options (further discussed 1083in :ref:`Prepare modules opts <sec-func>`); otherwise ``args`` is an array of ``n_args`` 1084strings (i.e., the int argc, char \*argv[] model) 1085 1086Many programs will register an export location where results of a GMT function (say, a filtered grid) 1087should be returned, but may then wish to use that variable as an *input* resource in a subsequent module 1088call. This is accomplished by re-registering the resource as an *input* source, thereby changing the 1089*direction* of the data set. The function returns 1 if there is an error; otherwise it returns 0. |ex_resource_init| 1090 1091Resource registration 1092~~~~~~~~~~~~~~~~~~~~~ 1093 1094Should your program need to add additional sources (or a destination) to the list of items 1095to be considered you will need to register them manually. This is considered a low-level 1096activity and most applications are unlikely to have to resort to this step. We document 1097it here in case your situation calls for such action. 1098Registration involves a direct or indirect call to 1099 1100.. _GMT_Register_IO: 1101 1102 :: 1103 1104 int GMT_Register_IO (void *API, unsigned int family, unsigned int method, 1105 unsigned int geometry, unsigned int direction, double wesn[], void *ptr); 1106 1107where :ref:`family <tbl-family>` specifies what kind of resource is to be registered, 1108:ref:`method <tbl-methods>` specifies 1109how we to access this resource (see Table :ref:`methods <tbl-methods>` for recognized 1110methods), :ref:`geometry <tbl-geometry>` specifies the geometry of the data, ``ptr`` is the address of the 1111pointer to the named resource. If ``direction`` is ``GMT_OUT`` and the 1112``method`` is not related to a file (filename, stream, or handle), then 1113``ptr`` must be NULL. Note there are some limitations on when you may pass a file pointer 1114as the method. Many grid file formats cannot be read via a stream (e.g., netCDF files) so in 1115those situations you cannot pass a file pointer [and GMT_Register_IO would have no way of knowing 1116this]. For grid (and image) 1117resources you may request to obtain a subset via the :ref:`wesn <tbl-wesn>` array; otherwise, pass NULL 1118(or an array with at least 4 items all set to 0) to obtain the 1119entire grid (or image). The ``direction`` indicates input or output and 1120is either ``GMT_IN`` or ``GMT_OUT``. Finally, the function returns a 1121unique resource ID, or ``GMT_NOTSET`` if there was an error. 1122 1123 1124.. _tbl-family: 1125 1126 +-------------------+---------------------------------+ 1127 | family | source points to | 1128 +===================+=================================+ 1129 | GMT_IS_DATASET | A [multi-segment] data file | 1130 +-------------------+---------------------------------+ 1131 | GMT_IS_GRID | A grid file | 1132 +-------------------+---------------------------------+ 1133 | GMT_IS_IMAGE | An image | 1134 +-------------------+---------------------------------+ 1135 | GMT_IS_CUBE | A 3-D cube | 1136 +-------------------+---------------------------------+ 1137 | GMT_IS_PALETTE | A color palette table [CPT] | 1138 +-------------------+---------------------------------+ 1139 | GMT_IS_POSTSCRIPT | A GMT PostScript object | 1140 +-------------------+---------------------------------+ 1141 | GMT_IS_MATRIX | A custom user data matrix | 1142 +-------------------+---------------------------------+ 1143 | GMT_IS_VECTOR | A custom user data vector | 1144 +-------------------+---------------------------------+ 1145 | GMT_VIA_MATRIX | Modifier for grids and datasets | 1146 +-------------------+---------------------------------+ 1147 | GMT_VIA_VECTOR | Modifier for grids and datasets | 1148 +-------------------+---------------------------------+ 1149 1150 GMT constants used to specify a data family. 1151 1152.. _tbl-methods: 1153 1154 +------------------+------------------------------------------------+ 1155 | method | how to read/write data | 1156 +==================+================================================+ 1157 | GMT_IS_FILE | Pointer to name of a file | 1158 +------------------+------------------------------------------------+ 1159 | GMT_IS_STREAM | Pointer to open stream (or process) | 1160 +------------------+------------------------------------------------+ 1161 | GMT_IS_FDESC | Pointer to integer file descriptor | 1162 +------------------+------------------------------------------------+ 1163 | GMT_IS_DUPLICATE | Pointer to memory we may *duplicate* data from | 1164 +------------------+------------------------------------------------+ 1165 | GMT_IS_REFERENCE | Pointer to memory we may *reference* data from | 1166 +------------------+------------------------------------------------+ 1167 1168 GMT constants used to specify how data will be read or written. 1169 1170.. _tbl-geometry: 1171 1172 +----------------+-----------------------------------------+ 1173 | geometry | description | 1174 +================+=========================================+ 1175 | GMT_IS_NONE | Not a geographic feature | 1176 +----------------+-----------------------------------------+ 1177 | GMT_IS_POINT | Multi-dimensional point data | 1178 +----------------+-----------------------------------------+ 1179 | GMT_IS_LINE | Geographic or Cartesian line segments | 1180 +----------------+-----------------------------------------+ 1181 | GMT_IS_POLYGON | Geographic or Cartesian closed polygons | 1182 +----------------+-----------------------------------------+ 1183 | GMT_IS_PLP | Either points, lines, or polygons | 1184 +----------------+-----------------------------------------+ 1185 | GMT_IS_SURFACE | 2-D gridded surface | 1186 +----------------+-----------------------------------------+ 1187 | GMT_IS_VOLUME | 3-D gridded volume | 1188 +----------------+-----------------------------------------+ 1189 1190 GMT constants used to specify the geometry of the data object. 1191 1192.. _tbl-wesn: 1193 1194 +---------+----------------------------------------------+ 1195 | index | description | 1196 +=========+==============================================+ 1197 | GMT_XLO | x_min (west) boundary of grid subset | 1198 +---------+----------------------------------------------+ 1199 | GMT_XHI | x_max (east) boundary of grid subset | 1200 +---------+----------------------------------------------+ 1201 | GMT_YLO | y_min (south) boundary of grid subset | 1202 +---------+----------------------------------------------+ 1203 | GMT_YHI | y_max (north) boundary of grid subset | 1204 +---------+----------------------------------------------+ 1205 | GMT_ZLO | z_min (bottom) boundary of 3-D matrix subset | 1206 +---------+----------------------------------------------+ 1207 | GMT_ZHI | z_max (top) boundary of 3-D matrix subset | 1208 +---------+----------------------------------------------+ 1209 1210 GMT constants used for domain array indexing. 1211 1212.. _sec-create: 1213 1214Create empty resources 1215---------------------- 1216 1217If your application needs to build and populate GMT resources in ways 1218that do not depend on external resources (files, memory locations, 1219etc.), or you have data read in separately and you wish to build a 1220GMT resource from scratch, then you can obtain an empty object by calling 1221 1222.. _GMT_Create_Data: 1223 1224 :: 1225 1226 void *GMT_Create_Data (void *API, unsigned int family, unsigned int geometry, 1227 unsigned int mode, uint64_t par[], double *wesn, double *inc, 1228 unsigned int registration, int pad, void *data) 1229 1230which returns a pointer to the allocated resource. Pass a valid :ref:`family <tbl-family>` selection. 1231Also pass a compatible :ref:`geometry <tbl-geometry>`. Depending on the family and your particular way of 1232representing dimensions you may pass the additional parameters in one of 1233two ways: 1234 1235#. Actual integer dimensions of items needed (which depends on the ``family``). 1236 1237#. Physical distances and increments of each dimension. 1238 1239For the first case you should pass both ``wesn`` and ``inc`` as NULL (or as arrays with elements all set to 0), 1240and pass the ``par`` array with contents as indicated below: 1241 1242 **GMT_IS_GRID**. 1243 An empty :ref:`GMT_GRID <struct-grid>` structure with a header is allocated; the data 1244 array is NULL. Use ``registration`` to choose either gridline (``GMT_GRID_PIXEL_REG``) or pixel 1245 (``GMT_GRID_NODE_REG``) registration. The domain can be prescribed on one of two ways: 1246 (1) The ``par`` argument is NULL. Then ``wesn`` and ``inc`` can also be NULL but only if the common GMT options 1247 **-R** and **-I** have been set because they are required to get the necessary info. If they 1248 were not set, then ``wesn`` and ``inc`` must in fact be transmitted. If ``wesn`` and ``inc`` 1249 are set (directly or indirectly) then ``par`` is ignored, even if not NULL. 1250 (2) The ``par`` argument is not NULL but both ``wesn`` and ``inc`` are NULL. 1251 Now, ``par[0]`` must have the number of columns and ``par[1]`` must have the number of rows in the grid. Internally, 1252 ``inc`` will be set to 1/1 and ``wesn`` will be set to 0/n_columns/0/n_rows. As an option, add ``GMT_GRID_XY`` to ``mode`` 1253 and we also allocate the grids's *x* and *y* coordinate vectors. 1254 1255 **GMT_IS_IMAGE**. 1256 Same procedure as for **GMT_IS_GRID** but we return an empty :ref:`GMT_IMAGE <struct-image>` object. In either 1257 way of specification you may use ``par[2]`` to pass the number of image bands [1]. 1258 1259 **GMT_IS_CUBE**. 1260 Same procedure as for **GMT_IS_GRID** but both ``wesn``, ``inc`` and ``par`` have one extra 1261 dimension for the depth or time axis. For non-equidistant layers you need to use 1262 ``par[2]`` to sets the number of layers and use ``inc[2] = 0``, otherwise ``wesn`` and ``inc`` can set it all. 1263 1264 **GMT_IS_DATASET**. 1265 We allocate an empty :ref:`GMT_DATASET <struct-dataset>` structure consisting of ``par[0]`` tables, 1266 each with ``par[1]`` segments, each with ``par[2]`` rows, all with ``par[3]`` columns. 1267 The ``wesn``, ``inc``, and ``registration`` argument are ignored. The ``data`` argument should be NULL. As an option, 1268 add ``GMT_WITH_STRINGS`` to ``mode`` and we also allocate the segments' *text* field. 1269 1270 **GMT_IS_PALETTE**. 1271 We allocate an empty :ref:`GMT_PALETTE <struct-palette>` structure with ``par[0]`` palette entries. 1272 The ``wesn``, ``inc``, and ``registration`` arguments are ignored and should be NULL/0. The ``data`` argument should be NULL. 1273 1274 **GMT_IS_POSTSCRIPT**. 1275 We allocate an empty :ref:`GMT_POSTSCRIPT <struct-postscript>` structure with a text buffer of length ``par[0]``. 1276 Give ``par[0]`` = 0 if the PostScript string is allocated or obtained by other means. 1277 The ``wesn``, ``inc``, and ``registration`` arguments are ignored and should be NULL/0. The ``data`` argument should be NULL. 1278 1279 **GMT_IS_VECTOR**. 1280 We allocate an empty :ref:`GMT_VECTOR <struct-vector>` structure with ``par[0]`` column entries. 1281 The number of rows can be specified in one of two ways: (1) Set the number of rows via ``par[1]``. Then, 1282 ``wesn``, ``inc``, and ``registration`` arguments are ignored. 1283 (2) Specify ``wesn``, ``inc``, and ``registration`` and the number of rows will be computed from these 1284 parameters instead. Finally, ``par[2]`` holds the data type of all vectors, if you are allocating them here. 1285 The ``data`` argument should be NULL. If you have custom vectors you wish to use then 1286 pass ``par`` but make sure to select mode GMT_CONTAINER_ONLY so that no memory is allocated. Furthermore, 1287 if you are manually setting up output containers then pass mode as GMT_IS_OUTPUT instead. 1288 Use GMT_Put_Vector_ to hook up your vectors. 1289 1290 **GMT_IS_MATRIX**. 1291 We allocate an empty :ref:`GMT_MATRIX <struct-matrix>` structure. The domain can be prescribed on one of two ways: 1292 (1) Here, ``par[0]`` is the number of columns while ``par[1]`` has the number of rows. Also, 1293 ``par[2]`` indicates the number of layers for a 3-D matrix, or pass 0, 1, or NULL for a 2-D matrix. 1294 Finally, ``par[3]`` holds the data type of the matrix, if you are allocating one. 1295 (2) Pass ``wesn``, ``inc``, ``registration`` and we compute the dimensions of the matrix. 1296 The ``data`` argument should be NULL. As for vectors, to use custom data you must (for input) pass the 1297 mode as GMT_CONTAINER_ONLY and hook your custom matrix in via a call to GMT_Put_Matrix_. The matrix may either 1298 be row- or column-oriented and this is normally determined when you created the session with GMT_Create_Session_ (see the bit 3 setting). 1299 However, you can pass ``pad`` = 1 (GMT_IS_ROW_FORMAT; set row major) or ``pad`` = 2 (GMT_IS_COL_FORMAT; set col major) to override the default. 1300 As for vectors, if this container is for output then pass mode as GMT_IS_OUTPUT instead. 1301 1302Users wishing to pass their own data matrices and vectors to GMT modules will need to do so via 1303the **GMT_IS_MATRIX** and **GMT_IS_VECTOR** containers. However, no module deals with such containers 1304directly (they either expect **GMT_IS_GRID** or **GMT_IS_DATASET**, for instance). 1305The solution is to specify the container type the GMT module expects but add in the special 1306flags **GMT_VIA_MATRIX** or **GMT_VIA*VECTOR**. This will create the **GMT_IS_MATRIX** or 1307**GMT_IS_VECTOR** container the user needs to add the user data, but will also tell GMT how 1308they should be considered by the module. **Note**: When creating your own geographic data 1309(dataset, grid, image, matrix, or vector) you may add ``GMT_DATA_IS_GEO`` to ``mode`` so that 1310the structure that is created will retain this information. 1311 1312For grids and images you may pass ``pad`` to set the padding, or -1 to 1313accept the prevailing GMT default. The ``mode`` determines what is actually 1314allocated when you have chosen grids or images. As for GMT_Read_Data_ 1315you can pass ``GMT_CONTAINER_AND_DATA`` to initialize the header *and* allocate 1316space for the array; here ``data`` must be NULL. Alternatively, you can pass 1317``GMT_CONTAINER_ONLY`` to just initialize the grid or image header, 1318and later call GMT_Create_Data a second time, now passing ``GMT_DATA_ONLY``, to allocate 1319space for the array. In that second call you pass the pointer returned 1320by the first call as ``data`` and specify the family; all other 1321arguments should be NULL or 0. Normally, resources created by this 1322function are considered to be input (i.e., have a direction that is ``GMT_IN``). 1323The exception to this is for containers to hold results from GMT which need have a direction 1324set to ``GMT_OUT``. Such empty containers are requested by passing mode = ``GMT_IS_OUTPUT`` 1325and setting all dimension arguments to 0 or NULL. 1326The function returns a pointer to the 1327data container. In case of an error we return a NULL pointer and pass an 1328error code via ``API->error``. Your C code will have to include "gmt_private.h" to be able to 1329dereference the API pointer. 1330 1331Hooking user arrays to objects 1332~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 1333 1334If you have custom column vector or matrices and you want them to be used as 1335input to GMT modules, you will need to create a :ref:`GMT_VECTOR <struct-vector>` or :ref:`GMT_MATRIX <struct-matrix>` container 1336and hook your items to them. Likewise, if you want to receive the output of GMT modules 1337into user arrays or matrices then you will need to access those data. 1338The following utility functions are used for these tasks: 1339 1340.. _GMT_Put_Matrix: 1341 1342 :: 1343 1344 int GMT_Put_Matrix (void *API, struct GMT_MATRIX *M, unsigned int type, int pad, void *matrix); 1345 1346where ``M`` is a :ref:`GMT_MATRIX <struct-matrix>` created by GMT_Create_Data_, the ``type`` is one of the 1347recognized data :ref:`types <tbl-types>`, ``pad`` indicates if the matrix has or should have padding, 1348and ``matrix`` is your custom matrix. The ``pad`` entry is typically 0 (no pad present), but if you 1349intend the matrix to serve as grid input to a module then GMT will expect 2. If your matrix already has 1350been extended by 2 extra rows and columns then pass ``pad`` = 2. 1351To extract a custom matrix from an output :ref:`GMT_MATRIX <struct-matrix>` you can use 1352 1353.. _GMT_Get_Matrix: 1354 1355 :: 1356 1357 void *GMT_Get_Matrix (void *API, struct GMT_MATRIX *M); 1358 1359which simply returns a pointer to the right union pointer. 1360For vectors the same principles apply: 1361 1362.. _GMT_Put_Vector: 1363 1364 :: 1365 1366 int GMT_Put_Vector (void *API, struct GMT_VECTOR *V, unsigned int col, 1367 unsigned int type, void *vector); 1368 1369where ``V`` is the :ref:`GMT_VECTOR <struct-vector>` created by GMT_Create_Data_, 1370``col`` is the vector column in question, ``type`` is one of the recognized data 1371:ref:`types <tbl-types>` used for this vector, and ``vector`` is a pointer to the 1372user's read-only custom vector. In addition, ``type`` may also be **GMT_TEXT**, 1373in which case we expect an array of strings with numbers, longitudes, latitudes, 1374or ISO datetime strings and we do the conversion to internal numerical values and 1375allocate a vector to hold the result in the given ``col``. By default that vector 1376will be assigned to type **GMT_DOUBLE** but you can add another primary data type 1377for the conversion if you prefer (e.g., **GMT_TEXT**\|\ **GMT_LONG** to get final 1378internal absolute time in integer seconds). For the special data type **GMT_TEXT** GMT 1379allocates internal memory to hold the converted data and ``vector`` is not used 1380any further. 1381 1382To extract a custom vector from an output :ref:`GMT_VECTOR <struct-vector>` you can use 1383 1384.. _GMT_Get_Vector: 1385 1386 :: 1387 1388 void *GMT_Get_Vector (void *API, struct GMT_VECTOR *V, unsigned int col); 1389 1390where ``col`` is the vector number you wish to obtain a pointer to. 1391 1392.. _GMT_Put_Levels: 1393 1394 :: 1395 1396 int GMT_Put_Levels (void *API, struct GMT_CUBE *C, double *levels, uint64_t n_levels); 1397 1398where ``C`` is the :ref:`GMT_CUBE <struct-cube>` created by GMT_Create_Data_, ``levels`` is an array 1399with the (probably) non-equidistant coordinates for the third cube dimension, and ``n_levels`` is their number. 1400This function is typically used when we are creating a cube whose spacing between layers is not equidistant 1401and hence cannot be computed internally from range and increment. 1402 1403.. _GMT_Get_Version: 1404 1405 :: 1406 1407 void *GMT_Get_Version (void *API, unsigned int *major, unsigned int *minor, unsigned int *patch); 1408 1409Returns the current lib version as a float, e.g. *6.0*, and optionally its constituints. Either one or all 1410of in *\ *major*, *\ *minor*, *\ *patch* args can be NULL. If they are not, one gets the corresponding 1411version component. The *API* pointer is actually not used in this function, so passing NULL is the best 1412option. 1413 1414Finally, for either vectors, matrices or palettes you may optionally add a pointer to an 1415array of text strings, one per row (or CPT slice). This is done via 1416 1417.. _GMT_Put_Strings: 1418 1419 :: 1420 1421 int GMT_Put_Strings (void *API, unsigned int family, void *X, char **array); 1422 1423where ``family`` is either GMT_IS_VECTOR, GMT_IS_MATRIX, or GMT_IS_PALETTE, ``X`` is either a 1424:ref:`GMT_VECTOR <struct-vector>`, :ref:`GMT_MATRIX <struct-matrix>` or :ref:`GMT_MATRIX <struct-palette>`, and 1425``array`` is the a pointer to your string array. You may add ``GMT_IS_DUPLICATE`` to 1426``family`` to indicate you want the array of strings to be duplicated; the default 1427is to just set a pointer to ``array``. For GMT_IS_PALETTE you must also add 1428GMT_IS_PALETTE_LABEL or GMT_IS_PALETTE_KEY to indicate which strings are being set. 1429 1430To access the string array from an output vector or matrix container you will use 1431 1432.. _GMT_Get_Strings: 1433 1434 :: 1435 1436 char **GMT_Get_Strings (void *API, unsigned int family, void *X); 1437 1438where again ``family`` is either GMT_IS_VECTOR or GMT_IS_MATRIX and ``X`` is either a 1439:ref:`GMT_VECTOR <struct-vector>` or :ref:`GMT_MATRIX <struct-matrix>`. 1440 1441 1442Manually add segments 1443~~~~~~~~~~~~~~~~~~~~~ 1444 1445If you do not know the number of rows in the segments or you expect different segments to have different 1446lengths then you should set the row dimension to zero in GMT_Create_Data and add the segments 1447manually with ``GMT_Alloc_Segment``, which allocates a new :ref:`GMT_DATASET <struct-dataset>` segment 1448for such multi-segment tables. 1449 1450.. _GMT_Alloc_Segment: 1451 1452 :: 1453 1454 void *GMT_Alloc_Segment (void *API, unsigned int mode, 1455 uint64_t n_rows, uint64_t n_columns, char *header, void *S); 1456 1457where ``header`` is the segment's desired header (or NULL) and `mode` determines if the 1458segment should allocate a string array, which in this case should either be ``GMT_NO_STRINGS`` 1459or ``GMT_WITH_STRINGS``. If ``S`` is not NULL then we simply reallocate the lengths 1460of the segment; otherwise a new segment is first allocated. 1461 1462There is also the option of controlling the allocation of the segment 1463array by setting n_rows = 0. This would allow external arrays (double-precision only) to connect to 1464the S->data[col] arrays and not be freed by GMT's garbage collector. 1465 1466 1467Get information (meta data) about object 1468~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 1469 1470If you are creating objects in an environment where the objects are opaque pointers, then it may 1471be necessary to inquire about an objects dimension, range, registration, padding, etc. We can 1472do this with 1473 1474 1475.. _GMT_Get_Info: 1476 1477 :: 1478 1479 void *_GMT_Get_Info (void *API, unsigned int family, void *data, unsigned int *geometry, 1480 uint64_t dim[], double *range, double *inc, unsigned int *registration, int *pad) 1481 1482where ``family`` is the type of object referenced by ``data``. Depending on the type of object, 1483one or more of ``dim``, ``range``, ``inc``, ``registration``, and ``pad`` will be initialized, 1484but only if they do not point to NULL. The function returns an error code if an invalid family 1485was selected. 1486 1487 1488Duplicate resources 1489------------------- 1490 1491Often you have read or created a data resource and then need an 1492identical copy, presumably to make modifications to. Or, you want a copy 1493with the same dimensions and allocated memory, except data values should 1494not be duplicated. Alternatively, perhaps you just want to duplicate the 1495header and skip the allocation and duplication of the data entirely. These tasks 1496are addressed by 1497 1498.. _GMT_Duplicate_Data: 1499 1500 :: 1501 1502 void *GMT_Duplicate_Data (void *API, unsigned int family, unsigned int mode, 1503 void *data); 1504 1505which returns a pointer to the allocated resource. Specify which 1506:ref:`family <tbl-family>` and select ``mode`` from ``GMT_DUPLICATE_DATA``, 1507``GMT_DUPLICATE_ALLOC``, and ``GMT_DUPLICATE_NONE``, as discussed above 1508(also see ``mode`` discussion above). For :ref:`GMT_GRID <struct-grid>` 1509you may add ``GMT_DUPLICATE_RESET`` which will ensure the duplicate grid 1510will have normal padding (useful when the original has non-standard padding). 1511For :ref:`GMT_DATASET <struct-dataset>` you can 1512add modifiers ``GMT_ALLOC_VERTICAL`` or ``GMT_ALLOC_HORIZONTAL`` to the ``mode`` if you 1513wish to put all the data into a single long table or to paste all tables 1514side-by-side, respectively (thus getting one wide table instead). 1515Additional note for :ref:`GMT_DATASET <struct-dataset>`: Normally we allocate the output given the 1516corresponding input dimensions. You can override these by specifying your 1517alternative dimensions in the input dataset's variable ``dim[]``. 1518The ``data`` is a pointer to the resource you wish to duplicate. In case 1519of an error we return a NULL pointer and pass an error code via 1520``API->error``. 1521 1522Convert between resource types 1523------------------------------ 1524 1525Having a resource in memory you may want to convert it to an alternative 1526representation. For instance, you may have a :ref:`GMT_DATASET <struct-dataset>` 1527but need to strip the information from the 1528data into a VECTOR format, dropping all the segment header information, so 1529that your custom algorithm or other non-GMT functions can be used on the data. 1530In this case you will use 1531 1532.. _GMT_Convert_Data: 1533 1534 :: 1535 1536 void *GMT_Convert_Data (void *API, void *In, unsigned int family_in, 1537 void *Out, unsigned int family_out, unsigned int flag[]); 1538 1539which returns a pointer to the converted resource. Specify the needed 1540:ref:`family <tbl-family>` for both the input and output resources and set the 1541(up to) two flags passed via the ``flag`` array. The first ``flag[0]`` 1542determines how table headers and segment headers should be handled. 1543By default (``flag[0]`` = 0) they are preserved (to the extent possible). 1544E.g., converting a :ref:`GMT_DATASET <struct-dataset>` to MATRIX always means table headers are 1545skipped whereas segment headers are converted to NaN-records. Other 1546values for this flag is 1 (Table headers are not copied, segment headers are preserved), 15472 (Headers are preserved, segment headers are reset to blank), or 15483 (All headers headers are eliminated). Note that this flag only 1549affects duplication of headers. If the new object is written to file at 1550a later stage then it is up to the GMT default setting if headers are written 1551to file or not. 1552The second ``flag[1]`` controls restructuring of tables and segments within 1553a set. For ``flag[1]`` = 0 we retain the original layout. Other selections 1554are ``GMT_WRITE_TABLE_SEGMENT`` (combine all segments into a *single* segment in a *single* table), 1555``GMT_WRITE_TABLE`` (collect all segments into a *single* table), and ``GMT_WRITE_SEGMENT`` 1556(combine segments into *one* segment per table). 1557Many family combinations are simply not allowed, such as grid to color palette, dataset to image, 1558etc. 1559 1560Import Data Sets 1561---------------- 1562 1563If your program needs to import any of the six recognized data types 1564(data table, grid, image, cube, CPT, or PostScript) you will use 1565the GMT_Read_Data_ or GMT_Read_VirtualFile_ functions. The former 1566is typically used when reading from files, streams (e.g., ``stdin``), or 1567an open file handle, while the latter is only used to read from memory. 1568Because of the similarities of these six 1569import functions we use an generic form that covers all of them. 1570 1571All input functions takes a parameter called ``mode``. The ``mode`` 1572parameter generally has different meanings for the different data types 1573and will be discussed below. However, one bit setting is common to all 1574types: By default, you are only allowed to read a data source once; the 1575source is then flagged as having been read and subsequent attempts to 1576read from the same source will result in a warning and no reading takes 1577place. In the unlikely event you need to re-read a source you can 1578override this default behavior by adding ``GMT_IO_RESET`` to your ``mode`` 1579parameter. Note that this override does not apply to sources that are 1580streams or file handles, as it may not be possible to re-read their 1581contents. 1582 1583 1584Import from a file, stream, or handle 1585~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 1586 1587To read an entire resource from a file, stream, or file handle, use 1588 1589.. _GMT_Read_Data: 1590 1591 :: 1592 1593 void *GMT_Read_Data (void *API, unsigned int family, unsigned int method, 1594 unsigned int geometry, unsigned int mode, double wesn[], const char *input, void *ptr); 1595 1596* :ref:`API <GMT_Create_Session>` 1597* :ref:`family <tbl-family>` 1598* :ref:`method <tbl-methods>` 1599* :ref:`geometry <tbl-geometry>` 1600* mode -- *see below* 1601* :ref:`wesn <tbl-wesn>` 1602* input -- a pointer to char holding the file name to read, or NULL if ``stdin`` 1603* ptr -- NULL or the pointer returned by this function after a first call (when reading grids in two steps) 1604* Return: Pointer to data container, or NULL if there were errors (passed back via API->error) 1605 1606 1607where ``ptr`` is NULL except when reading grids in two steps (i.e., 1608first get a grid structure with a header, then read the data). Most of 1609these arguments have been discussed earlier. This function can be called 1610in three different situations: 1611 1612#. If you have a single source (filename, stream pointer, etc.) you can 1613 call GMT_Read_Data_ directly; there is no need to first register 1614 the source with GMT_Register_IO_ or gather the sources with 1615 GMT_Init_IO_. Furthermore, for :ref:`GMT_DATASET <struct-dataset>` you can also 1616 specify a filename that contains UNIX wildcards (e.g., "all_*_[ab]?.txt") 1617 and these will all be read to produce a single multi-table :ref:`GMT_DATASET <struct-dataset>` 1618 (for other datatypes, see GMT_Read_Group_ instead). 1619 1620#. If you want to specify ``stdin`` as source then pass ``input`` as NULL. 1621 1622#. If you already registered all desired sources with GMT_Init_IO_ 1623 then you indicate this choice by passing the invalid ``geometry`` = 0. 1624 1625Space will be allocated to hold the results, as needed, and a pointer to 1626the object is returned. If there are errors we simply return NULL and 1627report the error. Note that you can read in a GMT_IS_MATRIX either from a text 1628table (passing ``geometry`` as GMT_IS_POINT) or from a grid (passing ``geometry`` 1629as GMT_IS_SURFACE). The ``mode`` parameter has different meanings for 1630different data types. 1631 1632**Color palette table**. 1633 ``mode`` contains bit-flags that control how the CPT's back-, 1634 fore-, and NaN-colors should be initialized. Select 0 to use the 1635 CPT resource's back-, fore-, and NaN-colors, 2 to replace these with the current 1636 GMT default values, or 4 to replace them with the color table's 1637 entries for highest and lowest value. 1638 1639**Data table**. 1640 ``mode`` is currently not used. 1641 1642**Text table**. 1643 ``mode`` is currently not used. 1644 1645**GMT grid** or **image**. 1646 Here, ``mode`` determines how we read the grid: To read the entire 1647 grid and its header, pass ``GMT_CONTAINER_AND_DATA``. However, if you may need to 1648 extract a sub-region you must first read the header by passing 1649 ``GMT_CONTAINER_ONLY`` with ``wesn`` = NULL, then examine the header structure range 1650 attributes, specify a subset via the array ``wesn``, and 1651 finally call GMT_Read_Data_ a second time, now with ``mode`` = 1652 ``GMT_DATA_ONLY``, passing your ``wesn`` array and the grid 1653 structure returned from the first call as ``ptr``. In the event your 1654 data array should be allocated to hold both the real and imaginary 1655 parts of a complex data set you must add either 1656 ``GMT_GRID_IS_COMPLEX_REAL`` or ``GMT_GRID_IS_COMPLEX_IMAG`` to 1657 ``mode`` so as to allow for the extra memory needed and to stride 1658 the complex value-pairs correctly. If your grid is huge and you must read 1659 it row-by-row, set ``mode`` to ``GMT_CONTAINER_ONLY`` \| 1660 ``GMT_GRID_ROW_BY_ROW``. You can then access the grid row-by-row 1661 using GMT_Get_Row_. By default, the rows will be automatically 1662 processed in sequential order. To completely specify which row to be read, pass 1663 ``GMT_GRID_ROW_BY_ROW_MANUAL`` instead. 1664 Finally, as an option you may add ``GMT_GRID_XY`` to the mode and we also 1665 allocate the *x* and *y* coordinate vectors for the grid or image. 1666 1667*PostScript*. 1668 ``mode`` is currently not used. 1669 1670If you need to read the same resource more than once you should add the 1671bit flag ``GMT_IO_RESET`` to the given ``mode``. 1672 1673Import a group of data sets 1674~~~~~~~~~~~~~~~~~~~~~~~~~~~ 1675 1676To read a group of resources, you may instead use 1677 1678.. _GMT_Read_Group: 1679 1680 :: 1681 1682 void *GMT_Read_Group (void *API, unsigned int family, unsigned int method, 1683 unsigned int geometry, unsigned int mode, double wesn[], 1684 void *input, unsigned int *n_items, void *ptr); 1685 1686* :ref:`API <GMT_Create_Session>` 1687* :ref:`family <tbl-family>` 1688* :ref:`method <tbl-methods>` 1689* :ref:`geometry <tbl-geometry>` 1690* mode -- *see below* 1691* :ref:`wesn <tbl-wesn>` 1692* input -- Contents depends on the value of *n_items*. If it is zero then we expect 1693 a pointer to char holding UNIX wildcard file name(s) to read, otherwise we expect 1694 a pointer to an array of character strings (*n_items* in total) with names of all 1695 the files to read. If *n_items* is NULL then we assume 0 but cannot return the number 1696 found. 1697* ptr -- NULL or the pointer returned by this function after a first call (applies when reading grids or images in two steps) 1698* Return: Pointer to array of data container, or NULL if there were errors (passed back via API->error) 1699 1700 1701where ``ptr`` is NULL except when reading grids in two steps (i.e., 1702first get a grid structures with a header, then read the data arrays). Most of 1703these arguments have been discussed earlier. It is useful when you need to read 1704a series of files (e.g., from a list with filenames) or want to specify the items 1705to read using a UNIX wildcard specification. **Note**: If used with :ref:`GMT_DATASET <struct-dataset>` 1706then you will receive an array of structures as well. Typically, many data files 1707are read into separate tables that all form part of a single SET (this is what GMT_Read_Data_ does), 1708but if GMT_Read_Group_ is used on the same arguments then an array of one-table sets will 1709be returned instead. The purpose of your application will dictate which form is more convenient. 1710 1711Using user arrays in GMT 1712~~~~~~~~~~~~~~~~~~~~~~~~ 1713 1714If your program uses a matrix or a set of column vectors to hold data 1715and you wish to use such data in a GMT module, you must first create a 1716GMT_MATRIX (for matrices) or GMT_VECTOR (for vectors) to hold your arrays. 1717In this situation you must pass ``dim`` with the final dimensions of 1718your rows and columns when you call GMT_Create_Data_ to make the empty 1719containers. You can then use GMT_Put_Matrix_ and GMT_Put_Vector_ to hook 1720up your own allocated arrays. It is then these containers that you 1721will pass to GMT via *virtual files*. For receiving output from GMT it is 1722normal to simply use Open_VirtualFile and have GMT allocate the space needed. 1723However, if you want the result to be written to your own arrays or matrix 1724then you must call GMT_Create_Data yourself with mode = GMT_IS_OUTPUT and 1725specify the dimensions of your array, then (as for input) assign your memory 1726to the container using GMT_Put_Matrix_ or GMT_Put_Vector_. Finally, if 1727you also need to pass record of strings then see GMT_Put_Strings_ and 1728GMT_Get_Strings_. 1729 1730Open a virtual file (memory location) 1731~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 1732 1733If you have read in or otherwise obtained a data object in memory and you 1734now wish for it to serve as input to a GMT module, you will have to associate 1735that object with a "Virtual File". This step assigns a special filename to the 1736memory location and you can then pass this filename to any module that 1737needs to read that data. It is similar for writing, except you may pass 1738NULL as the object to have GMT automatically allocate the output resource. 1739If you want GMT to write to your preallocated memory then you must instead create a 1740suitable container first (and pass the dimensions of the arrays) and then 1741attach your array(s) using GMT_Put_Matrix_ or GMT_Put_Vector_. 1742The full syntax is 1743 1744.. _GMT_Open_VirtualFile: 1745 1746 :: 1747 1748 int GMT_Open_VirtualFile (void *API, unsigned int family, unsigned int geometry, 1749 unsigned int direction, void *data, char *filename); 1750 1751Here, ``data`` is the pointer to your memory object. The function returns the 1752desired filename via ``filename``. This string must be at least ``GMT_VF_LEN`` bytes (16). 1753The other arguments have been discussed earlier. Specifically for direction, use 1754GMT_IN for reading and GMT_OUT for writing. Simply pass this filename in 1755the calling sequence to the module you want to use to indicate which file should 1756be used for reading or writing. Note that if you plan to pass a matrix or vectors 1757instead of grids or dataset you must add the modifiers GMT_IS_MATRIX or GMT_IS_VECTOR 1758to ``family`` so that the module knows what to do. Finally, in the case of passing 1759``data`` as NULL you may also control what type of matrix or vector will be created in 1760GMT for the output by adding in the modifiers GMT_VIA_type, as listed in :ref:`types <tbl-viatypes>`. 1761**Note**: GMT tries to minimize data duplication if possible, so if your input arrays are 1762compatible with the data type used by the modules then we could use your array directly. 1763This *may* have the side-effect that your input array is modified by the module, especially 1764if the module writes the results to a netCDF grid file. 1765If that is a price you are willing to pay then you can add GMT_IS_REFERENCE to the ``direction`` 1766argument and we will pass the array internally to avoid duplicating memory. For output it is 1767best to pass GMT_IS_REFERENCE as well. 1768 1769Import from a virtual file 1770~~~~~~~~~~~~~~~~~~~~~~~~~~ 1771 1772Once the module completes it will have written its output to the virtual file 1773you initialized with GMT_Open_VirtualFile_. To use the actual 1774data you will need to "read" it into your program. Of course, the data are already 1775in memory but to access it you need to use GMT_Read_VirtualFile_, which expects 1776the output filename you obtained from GMT_Open_VirtualFile_. The syntax is 1777 1778.. _GMT_Read_VirtualFile: 1779 1780 :: 1781 1782 void *GMT_Read_VirtualFile (void *API, char *filename); 1783 1784The function requires the output filename via ``filename`` and then returns 1785the data object, similar to what GMT_Read_Data_ does. 1786 1787Inquire a virtual file for family 1788~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 1789 1790If you do not know what family is being represented by a virtual file 1791then you should first obtain the family via GMT_Inquire_VirtualFile_. The syntax is 1792 1793.. _GMT_Inquire_VirtualFile: 1794 1795 :: 1796 1797 int GMT_Inquire_VirtualFile (void *API, const char *filename); 1798 1799The function requires the virtual file's ``filename`` and then returns the 1800family of the data object. 1801 1802Reset a virtual file for reuse 1803~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 1804 1805Should you need to read a virtual file again then you must first reset 1806it to its original state with GMT_Init_VirtualFile_. The syntax is 1807 1808.. _GMT_Init_VirtualFile: 1809 1810 :: 1811 1812 int GMT_Init_VirtualFile (void *API, unsigned int mode, const char *filename); 1813 1814The function requires the virtual file's ``filename`` and then resets the 1815internal counters (e.g., record numbers and other book-keeping parameters). 1816The ``mode`` is presently not used. 1817 1818Close a virtual file 1819~~~~~~~~~~~~~~~~~~~~ 1820 1821Once you have finished using a virtual file you need to close it. 1822This will reset its internal settings back to what it was before you 1823used it as a virtual file. The syntax is 1824 1825 1826.. _GMT_Close_VirtualFile: 1827 1828 :: 1829 1830 int GMT_Close_VirtualFile (void *API, char *filename); 1831 1832where ``filename`` is the name of the virtual file. 1833 1834 1835Record-by-record input 1836---------------------- 1837 1838In the case of data tables you have the option of selecting 1839record-by-record reading or writing. As a general rule, your program 1840development simplifies if you can read entire resources into memory with 1841GMT_Read_Data_ or GMT_Read_VirtualFile_. However, if this leads to 1842unacceptable memory usage or if the program logic is particularly simple, 1843you may obtain one data record at the time via GMT_Get_Record_ and write 1844one at the time with GMT_Put_Record_. For row-by-row i/o for grids there 1845is the corresponding function GMT_Get_Row_. There are additional overhead involved 1846in setting up record-by-record processing, which is the topic of this section. 1847 1848Enable Data Import 1849~~~~~~~~~~~~~~~~~~ 1850 1851Once all input resources have been registered, we signal the API that we 1852are done with the registration phase and are ready to start the actual 1853data import. This step is only required when reading one record at the 1854time. We initialize record-by-record reading by calling 1855GMT_Begin_IO_. This function enables data 1856record-by-record reading and prepares the registered sources for the 1857upcoming import. The prototype is 1858 1859.. _GMT_Begin_IO: 1860 1861 :: 1862 1863 int GMT_Begin_IO (void *API, unsigned int family, unsigned int direction, 1864 unsigned int header); 1865 1866where :ref:`family <tbl-family>` specifies the resource type to be read or written 1867(only ``GMT_IS_DATASET`` is 1868available for record-by-record handling). The ``direction`` is either 1869``GMT_IN`` or ``GMT_OUT``, so for import we obviously use ``GMT_IN``. The 1870function determines the first input source and sets up procedures for 1871skipping to the next input source in a virtual data set. The 1872GMT_Get_Record_ function will not be able to read any data before 1873GMT_Begin_IO_ has been called. As you might guess, there is a 1874companion GMT_End_IO_ function that completes, then disables 1875record-by-record data access. You can use these several times to switch 1876modes between registering data resources, doing the importing/exporting, 1877and disabling further data access, perhaps to do more registration. We 1878will discuss GMT_End_IO_ once we are done with the data import. The final 1879``header`` argument determines if the common header-block should be 1880written during initialization; choose between ``GMT_HEADER_ON`` and 1881``GMT_HEADER_OFF``. The function returns 1 if there is an 1882error; otherwise it returns 0. 1883 1884Set data geometry 1885~~~~~~~~~~~~~~~~~ 1886 1887Typically only done for output data written record by record, we designate 1888the data set's geometry by calling 1889 1890.. _GMT_Set_Geometry: 1891 1892 :: 1893 1894 int _GMT_Set_Geometry (void *API, unsigned int direction, unsigned int geometry); 1895 1896where ``direction`` is either ``GMT_IN`` or ``GMT_OUT`` and :ref:`geometry <tbl-geometry>` 1897sets the geometry that will be produced (or read). 1898 1899 1900Importing a data record 1901~~~~~~~~~~~~~~~~~~~~~~~ 1902 1903If your program will read data table records one-by-one you must first 1904enable this input mechanism with GMT_Begin_IO_ and then read the 1905records within a loop, repeatedly using 1906 1907.. _GMT_Get_Record: 1908 1909 :: 1910 1911 void *GMT_Get_Record (void *API, unsigned int mode, int *nfields); 1912 1913where the returned value is a pointer to a GMT_RECORD structure, whose 1914member pointers data and text point to ephemeral memory 1915internal to GMT and should be considered read-only. When we reach 1916end-of-file, encounter conversion problems, read header comments, or 1917identify segment headers we instead return a NULL pointer. The ``nfields`` 1918integer pointer will return the number of fields returned; pass NULL if your 1919program should ignore this information. 1920 1921Normally (i.e., ``mode`` = ``GMT_READ_DATA``), we return a pointer to 1922a double array. To read text records, supply instead ``mode`` = 1923``GMT_READ_TEXT`` and we will return a pointer to the text 1924record. However, if you have input records that mixes organized 1925floating-point columns with text items you could pass ``mode`` = 1926``GMT_READ_MIXED``. Then, GMT will attempt to extract the 1927floating-point values from as many columns as needed; you can still access the original record string, as 1928discussed below. Finally, if your application needs to be notified when 1929GMT closes one file and opens the next, add ``GMT_FILE_BREAK`` to 1930``mode`` and check for the status code ``GMT_IO_NEXT_FILE`` (by default, 1931we treat the concatenation of many input files as a single virtual 1932file). Using GMT_Get_Record_ requires you to first initialize the 1933source(s) with GMT_Init_IO_. For certain records, GMT_Get_Record_ 1934will return NULL and sets status codes that your program will need to 1935examine to take appropriate response. Table :ref:`IO-status <tbl-iostatus>` lists the 1936various status codes you can check for, using the ``GMT_Get_Status`` function (see 1937next section). 1938 1939Examining record status 1940~~~~~~~~~~~~~~~~~~~~~~~ 1941 1942Programs that read record-by-record must be aware of what the current 1943record represents. Given the presence of headers, data gaps, NaN-record, 1944etc., the developer may want to check the status after reading the current 1945record. The internal i/o status mode can be interrogated with the function 1946 1947.. _GMT_Get_Status: 1948 1949 :: 1950 1951 int GMT_Get_Status (void *API, unsigned int mode); 1952 1953which returns 0 (false) or 1 (true) if the current status is reflected 1954by the specified ``mode``. There are 11 different modes available to 1955programmers; for a list see Table :ref:`IO-status <tbl-iostatus>` For an example of how 1956these may be used, see the test program ``testgmtio.c``. Developers who plan to import 1957data on a record-by-record basis may also consult the source code of, 1958say, :doc:`/blockmean` or :doc:`/text`, to see examples of working code. 1959 1960.. _tbl-iostatus: 1961 1962 +-----------------------+--------------------------------------------------------+ 1963 | mode | description and return value | 1964 +=======================+========================================================+ 1965 | GMT_IO_DATA_RECORD | 1 if we read a data record | 1966 +-----------------------+--------------------------------------------------------+ 1967 | GMT_IO_TABLE_HEADER | 1 if we read a table header | 1968 +-----------------------+--------------------------------------------------------+ 1969 | GMT_IO_SEGMENT_HEADER | 1 if we read a segment header | 1970 +-----------------------+--------------------------------------------------------+ 1971 | GMT_IO_ANY_HEADER | 1 if we read either header record | 1972 +-----------------------+--------------------------------------------------------+ 1973 | GMT_IO_MISMATCH | 1 if we read incorrect number of columns | 1974 +-----------------------+--------------------------------------------------------+ 1975 | GMT_IO_EOF | 1 if we reached the end of the file (EOF) | 1976 +-----------------------+--------------------------------------------------------+ 1977 | GMT_IO_NAN | 1 if we only read NaNs | 1978 +-----------------------+--------------------------------------------------------+ 1979 | GMT_IO_GAP | 1 if this record implies a data gap | 1980 +-----------------------+--------------------------------------------------------+ 1981 | GMT_IO_NEW_SEGMENT | 1 if we enter a new segment | 1982 +-----------------------+--------------------------------------------------------+ 1983 | GMT_IO_LINE_BREAK | 1 if we encountered a segment header, EOF, NaNs or gap | 1984 +-----------------------+--------------------------------------------------------+ 1985 | GMT_IO_NEXT_FILE | 1 if we finished one file but not the last | 1986 +-----------------------+--------------------------------------------------------+ 1987 1988 The various modes used to test the status of the record-by-record machinery. 1989 1990Importing a grid row 1991~~~~~~~~~~~~~~~~~~~~ 1992 1993If your program must read a grid file row-by-row you must first enable 1994row-by-row reading with GMT_Read_Data_ and then use the 1995GMT_Get_Row_ function in a loop; the prototype is 1996 1997.. _GMT_Get_Row: 1998 1999 :: 2000 2001 int GMT_Get_Row (void *API, int row_no, struct GMT_GRID *G, float *row); 2002 2003where ``row`` is a pointer to a pre-allocated single-precision array to receive the 2004current row, ``G`` is the grid in question, and ``row_no`` is the number 2005of the current row to be read. Note this value is only considered if the 2006row-by-row mode was initialized with ``GMT_GRID_ROW_BY_ROW_MANUAL``. 2007The user must allocate enough space to hold the entire row in memory. 2008 2009Disable Data Import 2010~~~~~~~~~~~~~~~~~~~ 2011 2012Once the record-by-record input processing has completed we disable 2013further input to prevent accidental reading from occurring (due to poor 2014program structure, bugs, etc.). We do so by calling GMT_End_IO_. This 2015function disables further record-by-record data import; its prototype is 2016 2017.. _GMT_End_IO: 2018 2019 :: 2020 2021 int GMT_End_IO (void *API, unsigned int direction, unsigned int mode); 2022 2023and we specify ``direction`` = ``GMT_IN``. At the moment, ``mode`` is not 2024used. This call will also reallocate any arrays obtained into their 2025proper lengths. The function returns 1 if there is an error 2026(whose code is passed back with ``API->error``), otherwise it returns 0 (``GMT_NOERROR``). 2027 2028.. _sec-manipulate: 2029 2030Manipulate data 2031--------------- 2032 2033Once you have created and allocated empty resources, or read in 2034resources from the outside, you may wish to manipulate their contents. 2035This section discusses how to set up loops and access the important 2036variables for each of the supported families. For grids and images it may in addition 2037be required to determine what the coordinates are at each node point. This information 2038can be obtained via arrays of coordinates for each dimension, obtained by 2039 2040.. _GMT_Get_Coord: 2041 2042 :: 2043 2044 double *GMT_Get_Coord (void *API, unsigned int family, unsigned int dim, 2045 void *data); 2046 2047where :ref:`family <tbl-family>` must be ``GMT_IS_GRID`` or ``GMT_IS_DATASET``, ``dim`` is either 2048``GMT_IS_X`` or ``GMT_IS_Y``, and ``data`` is the grid or image pointer. This 2049function will be used below in our example on grid manipulation. 2050 2051Another aspect of dealing with grids and images is to convert a row and column 20522-D reference to our 1-D array index. Because of grid and image boundary padding 2053the relationship is not straightforward, hence we supply 2054 2055.. _GMT_Get_Index: 2056 2057 :: 2058 2059 uint64_t GMT_Get_Index (struct GMT_GRID_HEADER *header, int row, int col); 2060 2061where the ``header`` is the header of either a grid or image, and ``row`` and 2062``col`` is the 2-D position in the grid or image. We return the 1-D array 2063position; again this function is used below in our example. Likewise, for images 2064with many layers we also define 2065 2066.. _GMT_Get_Pixel: 2067 2068 :: 2069 2070 uint64_t GMT_Get_Pixel (struct GMT_GRID_HEADER *header, int row, 2071 int col, int layer); 2072 2073where the ``header`` is the header of an image, and ``row``, ``col`` and 2074``layer`` (= 1 for grids) is the position in the grid or image. 2075 2076For data cubes we need to also supply the ``level`` in the cube. Because 2077each layer is basically a padded grid, we supply 2078 2079.. _GMT_Get_Index3: 2080 2081 :: 2082 2083 uint64_t GMT_Get_Index3 (struct GMT_GRID_HEADER *header, int row, int col, int level); 2084 2085where we return the 1-D array position. 2086 2087Manipulate grids 2088~~~~~~~~~~~~~~~~ 2089 2090Most applications wishing to manipulate grids will want to loop over all 2091the nodes, typically in a manner organized by rows and columns. In doing 2092so, the coordinates at each node may also be required for a calculation. 2093Below is a snippet of code that shows how to do visit all nodes in a 2094grid and assign each node the product x \* y: 2095 2096 :: 2097 2098 int row, col, node; 2099 double *x_coord = NULL, *y_coord = NULL; 2100 /*... create a grid G or read one ... */ 2101 x_coord = GMT_Get_Coord (API, GMT_IS_GRID, GMT_X, G); 2102 y_coord = GMT_Get_Coord (API, GMT_IS_GRID, GMT_Y, G); 2103 for (row = 0; row < G->header->n_rows) { 2104 for (col = 0; col < G->header->n_columns; col++) { 2105 node = GMT_Get_Index (G->header, row, col); 2106 G->data[node] = x_coord[col] * y_coord[row]; 2107 } 2108 } 2109 2110Note the use of GMT_Get_Index_ to get the grid node number associated 2111with the ``row`` and ``col`` we are visiting. Because GMT grids have 2112padding (for boundary conditions) the relationship between rows, 2113columns, and node indices is more complicated and hence we hide that 2114complexity in GMT_Get_Index_. Note that for trivial procedures such 2115setting all grid nodes to a constant (e.g., -9999.0) where the row and 2116column does not enter you can instead do a single loop: 2117 2118 :: 2119 2120 int node; 2121 /*... create a grid G or read one ... */ 2122 for (node = 0; node < G->header->size) G->data[node] = -9999.0; 2123 2124Note we must use ``G->header->size`` (size of allocated array) and not 2125``G->header->nm`` (number of nodes in grid) since the latter is smaller 2126due to the padding and a single loop like the above treats the pad as 2127part of the "inside" grid. Replacing ``size`` by ``nm`` would be a bug. 2128 2129Manipulate data tables 2130~~~~~~~~~~~~~~~~~~~~~~ 2131 2132Another common application is to process the records in a data table. 2133Because GMT considers the :ref:`GMT_DATASET <struct-dataset>` resources to contain one or more 2134tables, each of which may contain one or more segments, all of which may 2135contain one or more columns, you will need to have multiple nested loops to 2136visit all entries. The following code snippet will visit all data 2137records and add 1 to all columns beyond the first two (x and y), and if 2138the data has a trailing string it will print it to stdout: 2139 2140 :: 2141 2142 uint64_t tbl, seg, row, col; 2143 struct GMT_DATATABLE *T = NULL; 2144 struct GMT_DATASEGMENT *S = NULL; 2145 2146 /* ... create a dataset D or read one ... */ 2147 for (tbl = 0; tbl < D->n_tables; tbl++) { /* For each table */ 2148 T = D->table[tbl]; /* Convenient shorthand for current table */ 2149 for (seg = 0; seg < T->n_segments; seg++) { /* For all segments */ 2150 S = T->segment[seg]; /* Convenient shorthand for current segment */ 2151 for (row = 0; row < S->n_rows; row++) { /* For all rows in segment */ 2152 for (col = 2; col < T->n_columns; col++) { /* For all cols > 1 */ 2153 S->data[col][row] += 1.0; /* Just add one */ 2154 } 2155 if (S->text) printf ("Row %d has string: %s\n", (int)row, S->text[row]); 2156 } 2157 } 2158 } 2159 2160Message and Verbose Reporting 2161----------------------------- 2162 2163The API provides two functions for your program to present information 2164to the user during the run of the program. One is used for messages that 2165are always written (optionally with a time stamp) while the other is used 2166for reports whose verbosity level must exceed the verbosity settings specified via **-V**. 2167 2168Verbose reporting 2169~~~~~~~~~~~~~~~~~ 2170 2171.. _GMT_Report: 2172 2173 :: 2174 2175 int GMT_Report (void *API, unsigned int level, const char *message, ...); 2176 2177This function takes a verbosity level and a multi-part message (e.g., a 2178format statement and zero or more variables as required by the format string). The verbosity ``level`` is 2179an integer in the 0–5 range; these levels are listed in Table :ref:`timemodes <tbl-verbosity>` 2180You assign an appropriate verbosity level to your message, and depending 2181on the chosen run-time verbosity level set via **-V** your message may 2182or may not be reported. Only messages whose stated verbosity level is 2183lower or equal to the **-V**\ *level* will be printed. These messages are typically 2184progress reports, etc., and are sent to standard error. 2185 2186 2187.. _tbl-verbosity: 2188 2189 +----------------------+--------------------------------------+ 2190 | constant | description | 2191 +======================+======================================+ 2192 | GMT_MSG_QUIET | Quiet; no messages whatsoever | 2193 +----------------------+--------------------------------------+ 2194 | GMT_MSG_ERROR | Error messages only | 2195 +----------------------+--------------------------------------+ 2196 | GMT_MSG_WARNING | Warnings | 2197 +----------------------+--------------------------------------+ 2198 | GMT_MSG_TICTOC | Time usage for slow algorithms | 2199 +----------------------+--------------------------------------+ 2200 | GMT_MSG_INFORMATION | Informational messages | 2201 +----------------------+--------------------------------------+ 2202 | GMT_MSG_COMPAT | Compatibility warnings | 2203 +----------------------+--------------------------------------+ 2204 | GMT_MSG_DEBUG | Debug messages for developers mostly | 2205 +----------------------+--------------------------------------+ 2206 2207 The different levels of verbosity that can be selected. 2208 2209Error string 2210~~~~~~~~~~~~ 2211 2212.. _GMT_Error_Message: 2213 2214 :: 2215 2216 char * GMT_Error_Message (void *API); 2217 2218This function simply returns a character pointer to the internal error message 2219buffer holding the last error message generated. 2220 2221User messages 2222~~~~~~~~~~~~~ 2223 2224For custom messages to the user that should always be printed, we use 2225 2226.. _GMT_Message: 2227 2228 :: 2229 2230 int GMT_Message (void *API, unsigned int mode, const char *format, ...); 2231 2232This function always prints its message to the standard output. Use the 2233``mode`` value to control if a time stamp should preface the message, 2234and if selected how the time information should be formatted. See 2235Table :ref:`timemodes <tbl-timemodes>` for the various modes. 2236 2237.. _tbl-timemodes: 2238 2239 +------------------+---------------------------------------+ 2240 | constant | description | 2241 +==================+=======================================+ 2242 | GMT_TIME_NONE | Display no time information | 2243 +------------------+---------------------------------------+ 2244 | GMT_TIME_CLOCK | Display current local time | 2245 +------------------+---------------------------------------+ 2246 | GMT_TIME_ELAPSED | Display elapsed time since last reset | 2247 +------------------+---------------------------------------+ 2248 | GMT_TIME_RESET | Reset the elapsed time to 0 | 2249 +------------------+---------------------------------------+ 2250 2251 The different types of message modes. 2252 2253Special GMT modules 2254------------------- 2255 2256There are some differences between calling 2257modules on the command line and using them via the API. These are discussed here. 2258 2259API-only modules 2260~~~~~~~~~~~~~~~~ 2261 2262There are two general-purpose modules that are not part of the command-line version of 2263GMT. These are the read and write modules. Both take an option to specify what GMT 2264resource is being read of written: **-Tc**\|\ **d**\|\ **g**\|\ **i**\|\ **p**, 2265which selects CPT, dataset, grid, image, or PostScript, respectively. In addition 2266both modules accept the *infile* and *outfile* argument for source and destination. These 2267may be actual files of memory locations, of course. 2268 2269PostScript Access 2270~~~~~~~~~~~~~~~~~ 2271 2272The GMT module :doc:`/psconvert` is normally given one or more PostScript files that may be 2273converted to other formats. When accessed by the API it may also be given the special 2274file name "=", which means we are to use the internal PostScript string produced by 2275the latest GMT plotting instead of any actual file name. The module can access this 2276string which must be a complete plot (i.e., it must have header, middle, and trailer 2277and thus be a valid PostScript file). This allows the API to convert plots to a 2278suitable image format without any duplication and manipulation of the PostScript 2279itself. 2280 2281Adjusting headers and comments 2282------------------------------ 2283 2284All header records in incoming datasets are stored in memory. You may 2285wish to replace these records with new information, or append new 2286information to the existing headers. This is achieved with 2287 2288.. _GMT_Set_Comment: 2289 2290 :: 2291 2292 int GMT_Set_Comment (void *API, unsigned int family, unsigned int mode, 2293 void *arg, void *data) 2294 2295Again, :ref:`family <tbl-family>` selects which kind of resource is passed via ``data``. 2296The ``mode`` determines what kind of comment is being considered, how it 2297should be included, and in what form the comment passed via ``arg`` is provided. 2298Table :ref:`comments <tbl-comments>` lists the available options, which may be combined 2299by adding (bitwise "or"). The GMT_Set_Comment_ function does not actually 2300output anything but sets the relevant comment and header records in the 2301relevant structure. When a file is written out the information will be 2302output as well (**Note**: Users can always decide if they wish to turn 2303header output on or off via the common GMT option ``-h``. For 2304record-by-record writing you must enable the header block output when 2305you call GMT_Begin_IO_. 2306 2307.. _tbl-comments: 2308 2309 +-------------------------+---------------------------------------------------+ 2310 | constant | description | 2311 +=========================+===================================================+ 2312 | GMT_COMMENT_IS_TEXT | Comment is a text string | 2313 +-------------------------+---------------------------------------------------+ 2314 | GMT_COMMENT_IS_OPTION | Comment is a linked list of GMT_OPTION structures | 2315 +-------------------------+---------------------------------------------------+ 2316 | GMT_COMMENT_IS_COMMAND | Comment is the command | 2317 +-------------------------+---------------------------------------------------+ 2318 | GMT_COMMENT_IS_REMARK | Comment is the remark | 2319 +-------------------------+---------------------------------------------------+ 2320 | GMT_COMMENT_IS_TITLE | Comment is the title | 2321 +-------------------------+---------------------------------------------------+ 2322 | GMT_COMMENT_IS_NAME_X | Comment is the x variable name (grids only) | 2323 +-------------------------+---------------------------------------------------+ 2324 | GMT_COMMENT_IS_NAME_Y | Comment is the y variable name (grids only) | 2325 +-------------------------+---------------------------------------------------+ 2326 | GMT_COMMENT_IS_NAME_Z | Comment is the z variable name (grids only) | 2327 +-------------------------+---------------------------------------------------+ 2328 | GMT_COMMENT_IS_COLNAMES | Comment is the column names header | 2329 +-------------------------+---------------------------------------------------+ 2330 | GMT_COMMENT_IS_RESET | Comment replaces existing information | 2331 +-------------------------+---------------------------------------------------+ 2332 2333 The modes for setting various comment types. 2334 2335The named modes (*command*, *remark*, *title*, *name_x,y,z* and 2336*colnames* are used to distinguish regular text comments from specific 2337fields in the header structures of the data resources, such as 2338:ref:`GMT_GRID <struct-grid>`. For the various table resources (e.g., :ref:`GMT_DATASET <struct-dataset>`) 2339these modifiers result in a specially formatted comments beginning with 2340"Command: " or "Remark: ", reflecting how this type of information is 2341encoded in the headers. 2342 2343Export Data Sets 2344---------------- 2345 2346If your program needs to write any of the six recognized data types 2347(CPTs, data tables, grids, images, cubes or PostScript) you can use the 2348GMT_Write_Data_ function. 2349 2350Both of these output functions takes a parameter called ``mode``. The 2351``mode`` parameter generally takes on different meanings for the 2352different data types and will be discussed below. However, one bit 2353setting is common to all types: By default, you are only allowed to 2354write a data resource once; the resource is then flagged to have been 2355written and subsequent attempts to write to the same resource will 2356quietly be ignored. In the unlikely event you need to re-write a 2357resource you can override this default behavior by adding ``GMT_IO_RESET`` 2358to your ``mode`` parameter. 2359 2360Exporting a data set 2361~~~~~~~~~~~~~~~~~~~~ 2362 2363To have your program accept results from GMT modules and write them 2364separately requires you to use the GMT_Write_Data_ function. It is very similar to the 2365GMT_Read_Data_ function encountered earlier. 2366 2367Exporting a data set to a file, stream, or handle 2368^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 2369 2370The prototype for writing to a file (via name, stream, or file handle) is 2371 2372.. _GMT_Write_Data: 2373 2374 :: 2375 2376 int GMT_Write_Data (void *API, unsigned int family, unsigned int method, 2377 unsigned int geometry, unsigned int mode, double wesn[], void *output, void *data); 2378 2379* :ref:`API <GMT_Create_Session>` 2380* :ref:`family <tbl-family>` 2381* :ref:`method <tbl-methods>` 2382* :ref:`geometry <tbl-geometry>` 2383* mode -- specific to each data type (\ *see below*) 2384* :ref:`wesn <tbl-wesn>` 2385* output -- 2386* data -- A pointer to any of the six families. 2387* Return: 0 on success, otherwise return -1 and set API->error to reflect to cause. 2388 2389where ``data`` is a pointer to any of the four structures discussed previously. 2390 2391**Color palette table** 2392 ``mode`` controls if the CPT's back-, fore-, and NaN-colors 2393 should be written (1) or not (0). 2394 2395**Data table** 2396 If ``method`` is ``GMT_IS_FILE``, then the value of ``mode`` affects 2397 how the data set is written: 2398 2399 **GMT_WRITE_SET** 2400 The entire data set will be written to the single file [0]. 2401 2402 **GMT_WRITE_TABLE** 2403 Each table in the data set is written to individual files [1]. 2404 You can either specify an output file name that *must* contain 2405 one C-style format specifier for an int variable (e.g., 2406 "New_Table_%06d.txt"), which will be replaced with the table 2407 number (a running number from 0) *or* you must assign to each 2408 table *i* a unique output file name via the 2409 ``D->table[i]->file[GMT_OUT]`` variables prior to calling the 2410 function. 2411 2412 **GMT_WRITE_SEGMENT** 2413 Each segment in the data set is written to an individual file 2414 [2]. Same setup as for ``GMT_WRITE_TABLE`` except we use 2415 sequential segment numbers to build the file names. 2416 2417 **GMT_WRITE_TABLE_SEGMENT** 2418 Each segment in the data set is written to an individual file 2419 [3]. You can either specify an output file name that *must* 2420 contain two C-style format specifiers for two int variables 2421 (e.g., "New_Table_%06d_Segment_%03d.txt"), which will be 2422 replaced with the table and segment numbers, *or* you must 2423 assign to each segment *j* in each table *i* a unique output 2424 file name via the ``D->table[i]->segment[j]->file[GMT_OUT]`` 2425 variables prior to calling the function. 2426 2427 **GMT_WRITE_OGR** 2428 Writes the dataset in OGR/GMT format in conjunction with the 2429 ``-a`` setting [4]. 2430 2431**Text table** 2432 The ``mode`` is used the same way as for data tables. 2433 2434**GMT grid** 2435 Here, ``mode`` may be ``GMT_CONTAINER_ONLY`` to only update a 2436 file's header structure, but normally it is simply ``GMT_CONTAINER_AND_DATA`` 2437 so the entire grid and its header will be exported (a subset is 2438 not allowed during export). However, in the event your data array 2439 holds both the real and imaginary parts of a complex data set you 2440 must add either ``GMT_GRID_IS_COMPLEX_REAL`` or 2441 ``GMT_GRID_IS_COMPLEX_IMAG`` to ``mode`` so as to export the 2442 corresponding grid values correctly. Finally, for native binary 2443 grids you may skip writing the grid header by adding 2444 ``GMT_GRID_NO_HEADER``; this setting is ignored for all other grid 2445 formats. If your output grid is huge and you are building it 2446 row-by-row, set ``mode`` to ``GMT_CONTAINER_ONLY`` \| 2447 ``GMT_GRID_ROW_BY_ROW``. You can then write the grid row-by-row 2448 using GMT_Put_Row_. By default the rows will be automatically 2449 processed in order. To completely specify which row to be written, 2450 use ``GMT_GRID_ROW_BY_ROW_MANUAL`` instead; this requires a file format 2451 that supports direct writes, such as netCDF. Finally, if you are 2452 preparing a geographic grid outside of GMT you need to add the mode 2453 ``GMT_GRID_IS_GEO`` to ensure that the proper metadata will be written 2454 to the netCDF header, thus letting the grid be recognized as such. 2455 2456**Note**: If ``method`` is GMT_IS_FILE, :ref:`family <tbl-family>` is ``GMT_IS_GRID``, 2457and the filename implies a change from NaN to another value then the grid is 2458modified accordingly. If you continue to use that grid after writing please be 2459aware that the changes you specified were applied to the grid. 2460 2461Record-by-record output 2462----------------------- 2463 2464In the case of data tables, you may also 2465consider the GMT_Put_Record_ function for record-by-record writing. As a general rule, your 2466program organization may simplify if you can write the entire 2467resource with GMT_Write_Data_. However, if the program logic is simple 2468or already involves using GMT_Get_Record_, it may be better to export 2469one data record at the time via GMT_Put_Record_. For grids there is the 2470corresponding GMT_Put_Row_ function. 2471 2472Enable Data Export 2473~~~~~~~~~~~~~~~~~~ 2474 2475Similar to the data import procedures, once all output destinations have 2476been registered, we signal the API that we are done with the 2477registration phase and are ready to start the actual data export. As for 2478input, this step is only needed when dealing with record-by-record 2479writing. Again, we enable record-by-record writing by calling 2480GMT_Begin_IO_, this time with ``direction`` = ``GMT_OUT``. This function 2481enables data export and prepares the registered destinations for the 2482upcoming writing. 2483 2484 2485Specifying the number of output columns 2486^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 2487 2488For record-based ASCII input/output you will need to specify the number of 2489columns, unless for output it equals the number of input columns. This is done with 2490the GMT_Set_Columns_ function: 2491 2492.. _GMT_Set_Columns: 2493 2494 :: 2495 2496 void *GMT_Set_Columns (void *API, unsigned int direction, unsigned int n_columns, unsigned int mode); 2497 2498The ``n_columns`` is a number related to the number of columns you plan to read/write, while 2499``mode`` controls what that number means. For input, ``mode`` = ``GMT_COL_FIX`` sets the actual 2500number of numerical columns to read. Anything beyond is considered trailing text and is parsed unless 2501you use ``GMT_COL_FIX_NO_TEXT`` instead. If your records have variable number of numerical columns 2502then you may use ``GMT_COL_VAR``. For output, you can also select from 2503other modes. Here, ``mode`` = ``GMT_COL_ADD`` means it should be added to the known number 2504of input columns to arrive at the number of final output columns, while ``mode`` = ``GMT_COL_SUB`` 2505means this value should be subtracted from the number of input columns to find the number of 2506output columns. 2507 2508 2509Exporting a data record 2510~~~~~~~~~~~~~~~~~~~~~~~ 2511 2512If your program must write data table records one-by-one you must first 2513enable record-by-record writing with GMT_Begin_IO_ and then use the 2514``GMT_Put_Record`` function in a loop; the prototype is 2515 2516.. _GMT_Put_Record: 2517 2518 :: 2519 2520 int GMT_Put_Record (void *API, unsigned int mode, void *rec); 2521 2522where ``rec`` is a pointer to (a) a GMT_RECORD structure for 2523the current row. Alternatively (b), ``rec`` 2524points to a text string. The ``mode`` parameter must be set to reflect 2525what is passed. Using GMT_Put_Record_ requires you to first 2526initialize the destination with GMT_Init_IO_. Note that for 2527``GMT_IS_DATASET`` the methods ``GMT_IS_DUPLICATE`` and 2528``GMT_IS_REFERENCE`` are not supported since you can simply populate the 2529:ref:`GMT_DATASET <struct-dataset>` structure directly. As mentioned, ``mode`` affects what is 2530actually written: 2531 2532**GMT_WRITE_DATA**. 2533 Normal operation that builds the current output record from the numerical values in ``rec``. 2534 2535**GMT_WRITE_TABLE_HEADER**. 2536 For ASCII output mode we write the text string ``rec``. If ``rec`` 2537 is NULL then we write the last read header record. If binary 2538 output mode we quietly skip writing this record. 2539 2540**GMT_WRITE_SEGMENT_HEADER**. 2541 For ASCII output mode we use the text string ``rec`` as the 2542 segment header. If ``rec`` is NULL then we use the current (last 2543 read) segment header record. If binary output mode instead we write 2544 a record composed of NaNs. 2545 2546The function returns 1 if there was an error associated with the 2547writing (which is passed back with ``API->error``), otherwise it returns 25480 (``GMT_NOERROR``). 2549 2550Exporting a grid row 2551~~~~~~~~~~~~~~~~~~~~ 2552 2553If your program must write a grid file row-by-row you must first enable 2554row-by-row writing with GMT_Read_Data_ and then use the 2555GMT_Put_Row_ function in a loop; the prototype is 2556 2557.. _GMT_Put_Row: 2558 2559 :: 2560 2561 int GMT_Put_Row (void *API, int row_no, struct GMT_GRID *G, float *row); 2562 2563where ``row`` is a pointer to a single-precision array with the current 2564row, ``G`` is the grid in question, and ``row_no`` is the number of the 2565current row to be written. Note this value is only considered if the 2566row-by-row mode was initialized with ``GMT_GRID_ROW_BY_ROW_MANUAL``. 2567 2568Disable Data Export 2569~~~~~~~~~~~~~~~~~~~ 2570 2571Once the record-by-record output has completed we disable further output 2572to prevent accidental writing from occurring (due to poor program 2573structure, bugs, etc.). We do so by calling GMT_End_IO_. This 2574function disables further record-by-record data export; here, we 2575obviously pass ``direction`` as ``GMT_OUT``. 2576 2577Destroy allocated resources 2578--------------------------- 2579 2580If your session imported any data sets into memory then you may 2581explicitly free this memory once it is no longer needed and before 2582terminating the session. This is done with the GMT_Destroy_Data_ 2583function, whose prototype is 2584 2585.. _GMT_Destroy_Data: 2586 2587 :: 2588 2589 int GMT_Destroy_Data (void *API, void *data); 2590 2591where ``data`` is the address of the pointer to a data container, i.e., not 2592the pointer to the container but the *address* of that pointer (e.g. &pointer). Note that 2593when each module completes it will automatically free memory created by 2594the API; similarly, when the session is destroyed we also automatically 2595free up memory. Thus, ``GMT_Destroy_Data`` is therefore generally only 2596needed when you wish to directly free up memory to avoid running out of 2597it. The function returns 1 if there is an error when trying to 2598free the memory (the error code is passed back with ``API->error``), 2599otherwise it returns 0 (``GMT_NOERROR``). 2600 2601Destroy groups of allocated resources 2602------------------------------------- 2603 2604If you obtained an array of resources via GMT_Read_Group_ then 2605you will need to destroy these resources with GMT_Destroy_Group_ instead, 2606whose prototype is 2607 2608.. _GMT_Destroy_Group: 2609 2610 :: 2611 2612 int GMT_Destroy_Group (void *API, void *data, unsigned int n); 2613 2614where ``data`` is the address of the array with data containers, i.e., not 2615the array to the containers but the *address* of that array (e.g. &array), 2616and ``n`` is the number of containers. 2617 2618Free other allocated memory 2619--------------------------- 2620 2621Some GMT functions may allocate memory that is not part of the containers 2622and thus cannot be freed with GMT_Destroy_Data_. For these cases there is 2623the GMT_Free_ function, whose prototype is 2624 2625.. _GMT_Free: 2626 2627 :: 2628 2629 int GMT_Free (void *API, void *ptr); 2630 2631where ``ptr`` is the address of the pointer to arbitrary data allocated 2632by the GMT API. The most common use of this function is to free the 2633resources returned by GMT_Encode_Options_. 2634 2635Terminate a GMT session 2636----------------------- 2637 2638Before your program exits it should properly terminate the 2639GMT session, which involves a call to 2640 2641.. _GMT_Destroy_Session: 2642 2643 :: 2644 2645 int GMT_Destroy_Session (void *API); 2646 2647which simply takes the pointer to the GMT API control structure as its 2648only arguments. It terminates the GMT machinery and deallocates all 2649memory used by the GMT API book-keeping. It also unregisters any 2650remaining resources previously registered with the session. The 2651GMT API will only close files that it was responsible for opening in 2652the first place. Finally, the API structure itself is freed so your main 2653program does not need to do so. The function returns 1 if there 2654is an error when trying to free the memory (the error code is passed 2655back with ``API->error``), otherwise it returns 0 (``GMT_NOERROR``). 2656 2657.. _sec-parsopt: 2658 2659Presenting and accessing GMT options 2660------------------------------------ 2661 2662As you develop a program you may wish to rely on some of 2663the GMT common options. For instance, you may wish to have your 2664program present the ``-R`` option to the user, let GMT handle the 2665parsing, and examine the values. You may also wish to encode your own 2666custom options that may require you to parse user text into the 2667corresponding floating point dimensions, constants, coordinates, absolute time, etc. 2668The API provides several functions to simplify these tedious parsing 2669tasks. This section is intended to show how the programmer will obtain 2670information from the user that is necessary to do the task at hand 2671(e.g., special options to provide values and settings for the program). 2672In the following section we will concern ourselves with preparing 2673arguments for calling any of the GMT modules. 2674 2675Display usage syntax for GMT common options 2676~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 2677 2678You can have your program menu display the standard usage message for a 2679GMT common option by calling the function 2680 2681.. _GMT_Option: 2682 2683 :: 2684 2685 int GMT_Option (void *API, const char *options); 2686 2687where ``options`` is a comma-separated list of GMT common options 2688(e.g., "R,J,O,X"). You can repeat this function with different sets of 2689options in order to intersperse your own custom options within an 2690overall alphabetical order; see any GMT module for examples of typical 2691layouts. 2692 2693Parsing the GMT common options 2694~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 2695 2696The parsing of all GMT common option is done by on call to 2697 2698.. _GMT_Parse_Common: 2699 2700 :: 2701 2702 int GMT_Parse_Common (void *API, const char *args, struct GMT_OPTION *list); 2703 2704where ``args`` is a string of the common GMT options your program is allowed to use. 2705An error will be reported if any of the common GMT options fail 2706to parse, and if so we return 1; if no errors we return 0. All 2707other options, including file names, will be silently ignored. The 2708parsing will update the internal GMT information structure that 2709affects module operations. 2710 2711Inquiring about the GMT common options 2712~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 2713 2714The API provide only a limited window into the full GMT machinery 2715accessible to the modules. You can determine if a particular common 2716option has been parsed and in some cases determine the values that were set with 2717 2718.. _GMT_Get_Common: 2719 2720 :: 2721 2722 int GMT_Get_Common (void *API, unsigned int option, double *par); 2723 2724where ``option`` is a single option character (e.g., 'R') and ``par`` is 2725a double array with at least a length of 6. If the particular option has 2726been parsed then the function returns the number of parameters passed 2727back via ``par``; otherwise we return -1. For instance, to determine if 2728the ``-R`` was set and to obtain the specified region you may call 2729 2730 :: 2731 2732 if (GMT_Get_Common (API, 'R', wesn)) != -1) { 2733 /* wesn now contains the boundary information */ 2734 } 2735 2736The ``wesn`` array could now be passed to the various read and create 2737functions for GMT resources. 2738 2739Parsing text values 2740~~~~~~~~~~~~~~~~~~~ 2741 2742Your program may need to request values from the user, such as 2743distances, plot dimensions, coordinates, date/time strings and other data. The conversion 2744from such text to actual distances, taking units into account, is 2745tedious to program. You can simplify this by using 2746 2747.. _GMT_Get_Values: 2748 2749 :: 2750 2751 int GMT_Get_Values (void *API, const char *arg, double par[], int maxpar); 2752 2753where ``arg`` is the text item with one or more values that are 2754separated by commas, spaces, tabs, semi-colons, or slashes, and ``par`` is an array of length ``maxpar`` long 2755enough to hold all the items you are parsing. The function returns the 2756number of items parsed with a maximum of ``maxpar``, or -1 if there is an error. For instance, assume 2757the character string ``origin`` was given by the user as two geographic 2758coordinates separated by a slash (e.g., ``"35:45W/19:30:55.3S"``). We 2759obtain the two coordinates in decimal degrees by calling 2760 2761 :: 2762 2763 n = GMT_Get_Values (API, origin, pair, 2); 2764 2765Your program can now check that ``n`` equals 2 and then use the values 2766in ``pairs`` separately. **Note**: Dimensions given with units of inches, cm, or points 2767are converted to the current default unit set via :term:`PROJ_LENGTH_UNIT`, 2768while distances given in km, nautical miles, miles, feet, or 2769survey feet are returned in meters. Arc lengths in minutes and seconds 2770are returned in decimal degrees, and date/time values are returned in 2771seconds since the current epoch [1970]. 2772 2773Get or set an API or GMT default parameter 2774~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 2775 2776If your program needs to determine one or more of the current 2777API or GMT default settings you can do so via 2778 2779.. _GMT_Get_Default: 2780 2781 :: 2782 2783 int GMT_Get_Default (void *API, const char *keyword, char *value); 2784 2785where ``keyword`` is one such keyword (e.g., :term:`PROJ_LENGTH_UNIT`) and 2786``value`` must be a character string long enough to hold the answer. In 2787addition to the long list of GMT defaults you can also inquire about the 2788API parameters ``API_PAD`` (the current pad setting), ``API_IMAGE_LAYOUT`` (the 2789order and structure of image memory storage), ``API_GRID_LAYOUT`` (order of 2790grid memory storage), ``API_VERSION`` (the API version string), 2791``API_CORES`` (the number of cores seen by the API), 2792``API_BINDIR`` (the API (GMT) executable path), 2793``API_SHAREDIR`` (the API (GMT) shared directory path), 2794``API_DATADIR`` (the API (GMT) data directory path), and 2795``API_PLUGINDIR`` (the API (GMT) plugin path). 2796Depending on what parameter you selected you could further convert it to 2797a numerical value with GMT_Get_Values_ or just use it in a text comparison. 2798 2799To change any of the API or 2800GMT default settings programmatically you would use 2801 2802.. _GMT_Set_Default: 2803 2804 :: 2805 2806 int GMT_Set_Default (void *API, const char *keyword, const char *value); 2807 2808where as before ``keyword`` is one such keyword (e.g., :term:`PROJ_LENGTH_UNIT`) and 2809``value`` must be a character string with the new setting. 2810Note that all settings must be passed as text strings even if many are 2811inherently integers or floats. 2812 2813Get an API enum constant 2814~~~~~~~~~~~~~~~~~~~~~~~~ 2815 2816The GMT API enum constants that are part of the API are defined in the 2817include file gmt_resources.h, which is included by gmt.h. So, if you are 2818writing an application in C/C++ you are including gmt.h and thus have 2819access to all the API enums directly. However, if your application is 2820written in other languages and you are perhaps just interfacing with the 2821shared GMT API library, then you can access any GMT enum via 2822 2823.. _GMT_Get_Enum: 2824 2825 :: 2826 2827 int GMT_Get_Enum (void *API, const char *enumname); 2828 2829where ``enumname`` is the name of one such enum (e.g., GMT_SESSION_EXTERNAL, GMT_IS_DATASET, etc.), 2830including the ones listed in :ref:`types <tbl-types>` and :ref:`types <tbl-viatypes>`; see 2831gmt_resources.h for the full listing. 2832The function returns the corresponding integer value. For unrecognized names we return -99999. 2833**Note**: You may pass a NULL pointer as API if you need to obtain enum values prior to calling GMT_Create_Session_. 2834 2835For indexed access to custom grids and images we may need to know the internal matrix layout. 2836You can change this information via 2837 2838.. _GMT_Set_Index: 2839 2840 :: 2841 2842 int64_t GMT_Set_Index (struct GMT_GRID_HEADER *header, char *code); 2843 2844where the ``header`` is the header of either a grid or image, and ``code`` is a three-character 2845code indication ... 2846 2847.. _sec-func: 2848 2849Call a module 2850------------- 2851 2852One of the advantages of programming with the API is that you 2853have access to the high-level GMT modules. For example, if your 2854program must compute the distance from a node to all other nodes in the grid 2855then you can simply set up options and call :doc:`/grdmath` to do it 2856for you and accept the result back as an input grid. All the module 2857interfaces are identical and are called via 2858 2859.. _GMT_Call_Module: 2860 2861 :: 2862 2863 int GMT_Call_Module (void *API, const char *module, int mode, void *args); 2864 2865Here, ``module`` is the name of any of the GMT modules, such as 2866:doc:`/plot` or :doc:`/grdvolume`. All GMT modules may be called with one of 2867three sets of ``args`` depending on ``mode``. The three modes differ in 2868how the options are passed to the module: 2869 2870 *mode* = ``GMT_MODULE_EXIST``. 2871 Return GMT_NOERROR (0) if the module exists, nonzero otherwise. 2872 2873 *mode* = ``GMT_MODULE_PURPOSE``. 2874 Just print the one-line purpose of the module; args must be NULL. 2875 2876 *mode* = ``GMT_MODULE_LIST``. 2877 Just prints a list of all modules (including those given as plugins); args must be NULL. 2878 2879 *mode* = ``GMT_MODULE_OPT``. 2880 Expects ``args`` to be a pointer to a doubly-linked list of objects with individual 2881 options for the current program. We will see 2882 how API functions can help prepare and maintain such lists. 2883 2884 *mode* = ``GMT_MODULE_CMD``. 2885 Expects ``args`` to be a single text string with all needed options. 2886 2887 *mode > 0*. 2888 Expects ``args`` to be an array of text strings and ``mode`` to be a count of how many 2889 options are passed (i.e., the ``argc, argv[]`` model used by the GMT programs themselves). 2890 2891From external interfaces and with a debug verbosity level set, ``GMT_Call_Module`` will 2892also print out the equivalent command line to standard error (or its substitute). 2893 2894Set program options via text array arguments 2895~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 2896 2897When ``mode > 0`` we expect an array ``args`` of character 2898strings that each holds a single command line option (e.g., 2899"-R120:30/134:45/8S/3N") and interpret ``mode`` to be the count of how 2900many options are passed. This, of course, is almost exactly how the 2901stand-alone GMT programs are called (and reflects how they themselves 2902are activated internally). We call this the "argc-argv" mode. Depending 2903on how your program obtains the necessary options you may find that this 2904interface offers all you need. 2905 2906Set program options via text command 2907~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 2908 2909If ``mode =`` 0 then ``args`` will be examined to see if it contains 2910several options within a single command string. If so we will break 2911these into separate options. This is useful if you wish to pass a single 2912string such as "-R120:30/134:45/8S/3N -JM6i mydata.txt -Sc0.2c". We call 2913this the "command" mode and it is extensively used by the modules themselves. 2914 2915Set program options via linked structures 2916~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 2917 2918The third, linked-list interface allows developers using higher-level 2919programming languages to pass all command options via a pointer to a 2920NULL-terminated, doubly-linked list of option structures, each 2921containing information about a single option. Here, instead of text 2922arguments we pass the pointer to the linked list of options mentioned 2923above, and ``mode`` must be passed as ``GMT_MODULE_OPT``. Using 2924this interface can be more involved since you need to generate the 2925linked list of program options; however, utility functions exist to 2926simplify its use. This interface is intended for programs whose internal 2927workings are better suited to generate such arguments -- we call this the 2928"options" mode. The order in the list is not important as GMT will 2929sort it internally according to need. The option structure is defined below. 2930 2931.. _options: 2932 2933 :: 2934 2935 struct GMT_OPTION { 2936 char option; /* Single option character (e.g., 'G' for -G) */ 2937 char *arg; /* String with arguments (NULL if not used) */ 2938 struct GMT_OPTION *next; /* Next option pointer (NULL for last option) */ 2939 struct GMT_OPTION *prev; /* Previous option (NULL for first option) */ 2940 }; 2941 2942Convert between text and linked structures 2943~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 2944 2945To assist programmers there are also two convenience functions that 2946allow you to convert between the two argument formats. They are 2947 2948.. _GMT_Create_Options: 2949 2950 :: 2951 2952 struct GMT_OPTION *GMT_Create_Options (void *API, int argc, void *args); 2953 2954This function accepts your array of text arguments (cast via a void 2955pointer), allocates the necessary space, performs the conversion, and 2956returns a pointer to the head of the linked list of program options. 2957However, in case of an error we return a NULL pointer and set 2958``API->error`` to indicate the nature of the problem. Otherwise, the 2959pointer may now be passed to the relevant GMT module. Note that if 2960your list of text arguments were obtained from a C ``main()`` function 2961then ``argv[0]`` will contain the name of the calling program. To avoid 2962passing this as a bad file name option, call GMT_Create_Options_ with 2963``argc-1`` and ``argv+1`` instead. If you wish to pass a single text string with 2964multiple options (in lieu of an array of text strings), then pass 2965``argc`` = 0. When no longer needed you can remove the entire list by calling 2966 2967.. _GMT_Destroy_Options: 2968 2969 :: 2970 2971 int GMT_Destroy_Options (void *API, struct GMT_OPTION **list); 2972 2973The function returns 1 if there is an error (which is passed back 2974with ``API->error``), otherwise it returns 0 (``GMT_NOERROR``). 2975 2976The inverse function prototype is 2977 2978.. _GMT_Create_Args: 2979 2980 :: 2981 2982 char **GMT_Create_Args (void *API, int *argc, struct GMT_OPTION *list); 2983 2984which allocates space for the text strings and performs the conversion; 2985it passes back the count of the arguments via ``argc`` and returns a 2986pointer to the text array. In the case of an error we return a NULL 2987pointer and set ``API->error`` to reflect the error type. Note that 2988``argv[0]`` will not contain the name of the program as is the case the 2989arguments presented by a C ``main()`` function. When you no longer have 2990any use for the text array, call 2991 2992.. _GMT_Destroy_Args: 2993 2994 :: 2995 2996 int GMT_Destroy_Args (void *API, int argc, char **argv[]); 2997 2998to deallocate the space used. This function returns 1 if there is 2999an error (which is passed back with ``API->error``), otherwise it returns 0 (``GMT_NOERROR``). 3000 3001Finally, to convert the linked list of option structures to a single 3002text string command, use 3003 3004.. _GMT_Create_Cmd: 3005 3006 :: 3007 3008 char *GMT_Create_Cmd (void *API, struct GMT_OPTION *list); 3009 3010Developers who plan to import and export GMT shell scripts might find 3011it convenient to use these functions. In case of an error we return a 3012NULL pointer and set ``API->error``, otherwise a pointer to an allocated 3013string is returned. When you no longer have 3014any use for the text string, call 3015 3016.. _GMT_Destroy_Cmd: 3017 3018 :: 3019 3020 int GMT_Destroy_Cmd (void *API, char **string); 3021 3022to deallocate the space used. This function returns 1 if there is 3023an error (which is passed back with ``API->error``), otherwise it 3024returns 0 (``GMT_NOERROR``). 3025 3026Manage the linked list of options 3027~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 3028 3029Several additional utility functions are available for programmers who 3030wish to manipulate program option structures within their own programs. 3031These allow you to create new option structures, append them to the 3032linked list, replace existing options with new values, find a particular 3033option, and remove options from the list. **Note**: The order in which the 3034options appear in the linked list is of no consequence to GMT. 3035Internally, GMT will sort and process the options in the manner 3036required. Externally, you are free to maintain your own order. 3037 3038Make a new option structure 3039^^^^^^^^^^^^^^^^^^^^^^^^^^^ 3040 3041GMT_Make_Option_ will allocate a new option structure, assign 3042values given the ``option`` and ``arg`` parameters (pass NULL if there is 3043no argument for this option), and return a pointer to the allocated 3044structure. The prototype is 3045 3046.. _GMT_Make_Option: 3047 3048 :: 3049 3050 struct GMT_OPTION *GMT_Make_Option (void *API, char option, const char *arg); 3051 3052Should memory allocation fail the function will print an error message 3053pass an error code via ``API->error``, and return NULL. 3054 3055Append an option to the linked list 3056^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 3057 3058GMT_Append_Option_ will append the specified ``option`` to the end of 3059the doubly-linked ``list``. The prototype is 3060 3061.. _GMT_Append_Option: 3062 3063 :: 3064 3065 struct GMT_OPTION *GMT_Append_Option (void *API, struct GMT_OPTION *option, 3066 struct GMT_OPTION *list); 3067 3068We return the list back, and if ``list`` is given as NULL we return 3069``option`` as the start of the new list. Any errors result in a NULL 3070pointer with ``API->error`` holding the error type. 3071 3072Find an option in the linked list 3073^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 3074 3075GMT_Find_Option_ will return a pointer ``ptr`` to the first option in 3076the linked list starting at ``list`` whose option character equals 3077``option``. If not found we return NULL. While this is not necessarily 3078an error we still set ``API->error`` accordingly. The prototype is 3079 3080.. _GMT_Find_Option: 3081 3082 :: 3083 3084 struct GMT_OPTION *GMT_Find_Option (void *API, char option, 3085 struct GMT_OPTION *list); 3086 3087If you need to look for multiple occurrences of a certain option you 3088will need to call GMT_Find_Option_ again, passing the option 3089following the previously found option as the ``list`` entry, i.e., 3090 3091 :: 3092 3093 list = *ptr->next; 3094 3095Update an existing option in the list 3096^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 3097 3098GMT_Update_Option_ will replace the argument of ``current`` with the 3099new argument ``arg`` and otherwise leave the option at its place in the 3100list. The prototype is 3101 3102.. _GMT_Update_Option: 3103 3104 :: 3105 3106 int GMT_Update_Option (void *API, struct GMT_OPTION *current, const char *arg); 3107 3108An error will be reported if (a) ``current`` is NULL or (b) ``arg`` is 3109NULL. The function returns 1 if there is an error, otherwise it returns 0 (``GMT_NOERROR``). 3110 3111Delete an existing option in the linked list 3112^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 3113 3114You may use GMT_Delete_Option_ to remove the ``current`` option from the linked 3115``list``. The prototype is 3116 3117.. _GMT_Delete_Option: 3118 3119 :: 3120 3121 int GMT_Delete_Option (void *API, struct GMT_OPTION *current, struct GMT_OPTION **head); 3122 3123We return 1 if the option is not found in the list and set 3124``API->error`` accordingly. **Note**: Only the first occurrence of the 3125specified option will be deleted. If you need to delete all such options 3126you will need to call this function in a loop until it returns a 3127non-zero status. 3128 3129Specify a file via a linked option 3130^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 3131 3132To specify an input file name via an option, simply use < as the 3133option (this is what GMT_Create_Options_ does when it finds filenames 3134on the command line). Likewise, > can be used to explicitly 3135indicate an output file. In order to append to an existing file, use 3136). For example the following command would read from file.A and 3137append to file.B: 3138 3139 :: 3140 3141 gmt convert -<file.A -)file.B 3142 3143These options also work on the command line but usually one would have 3144to escape the special characters <, > and ) as they are normally 3145used for file redirection. 3146 3147Encode option arguments for external interfaces 3148^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 3149 3150Developers writing interfaces between GMT and external platforms such 3151as other languages (Python, Java, Julia, etc.) or tools (MATLAB, Octave, 3152etc.) need to manipulate linked options in a special way. For instance, 3153a GMT call in the MATLAB or Octave application might look like 3154 3155.. code-block:: none 3156 3157 table = gmt('blockmean -R30W/30E/10S/10N -I2m', [x y z]); 3158 grid = gmt('surface -R -I2m -Lu', table, high_limit_grid); 3159 grid2 = gmt('grdmath ? LOG10 ? MUL', grid, grid); 3160 3161Most of the time our implicit rules will take care of the ordering. The 3162rule says that all required input data items must be listed before any 3163secondary input data items, and all primary output items must be listed 3164on the left hand side before any secondary output items. 3165There are three situations where the parsing will need further help; 3166(1) Specifying the positions of memory arguments given to :doc:`/gmtmath`, 3167(2) specifying the positions of memory arguments given to :doc:`/grdmath`, 3168and (3) using -R? when passing a memory grid to the -R option (since just -R 3169means use the previous region in the command history). 3170Thus, in the :doc:`/gmtmath` call we we needed to specify where 3171the specific arguments should be placed among the operators. 3172API developers will rely on GMT_Open_VirtualFile_ to convert the 3173above syntax to correct options for GMT_Call_Module_. 3174The prototype is 3175 3176.. _GMT_Encode_Options: 3177 3178 :: 3179 3180 struct GMT_RESOURCE *GMT_Encode_Options (void *API, const char *module, int n_in, 3181 struct GMT_OPTION **head, int *n_items); 3182 3183where ``module`` is the name of the module whose linked options are 3184pointed to by ``*head``, ``n_in`` contains the number of *input* 3185objects we have to connect (or -1 if not known) and we return an array 3186that contains specific information for those options that 3187(after processing) contain explicit memory references. The number of 3188items in the array is returned via the ``n_items`` variable. The function 3189returns NULL if there are errors and sets ``API->error`` to the corresponding 3190error number. The GMT_RESOURCE structure is defined below: 3191 3192.. .. _struct-grid: 3193 3194.. code-block:: c 3195 3196 struct GMT_RESOURCE { /* Information for passing external resources */ 3197 enum GMT_enum_family family; /* GMT data family */ 3198 enum GMT_enum_geometry geometry; /* One of the recognized GMT geometries */ 3199 enum GMT_enum_std direction; /* Either GMT_IN or GMT_OUT */ 3200 struct GMT_OPTION *option; /* Pointer to the corresponding module option */ 3201 int object_ID; /* Object ID returned by GMT_Register_IO */ 3202 int pos; /* Index into external object in|out arrays */ 3203 int mode; /* 0 means primary i/o object, 1 means secondary */ 3204 void *object; /* Pointer to the registered GMT object */ 3205 }; 3206 3207API developers will need to provide specific code to handle the registration of native 3208structures in their language or application and to translate between the GMT resources 3209and the corresponding native items. Developers should look at an existing and working 3210interface such as the GMT/MATLAB toolbox to see the required steps. **Note**: The array 3211of structures returned by GMT_Encode_Options_ should be freed by GMT_Free_. 3212 3213Expand an option with explicit memory references 3214^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 3215 3216When the external tool or application knows the name of the special file names 3217used for memory references the developer should replace the place-holder ``?`` character 3218in any option string with the actual reference name. This is accomplished by 3219calling GMT_Expand_Option_, with prototype 3220 3221.. _GMT_Expand_Option: 3222 3223 :: 3224 3225 int GMT_Expand_Option (void *API, struct GMT_OPTION *option, const char *name); 3226 3227where ``option`` is the current option and ``name`` 3228is the special file name for the memory reference. 3229 3230The GMT FFT Interface 3231===================== 3232 3233While the i/o options presented so far lets you easily read in a data 3234table or grid and manipulate them, if you need to do the manipulation in the 3235wavenumber domain then this chapter is for you. Here, we outline how to 3236take the Fourier transform of such data, perform calculations in the 3237wavenumber domain, and take the inverse transform before writing the 3238results. To assist programmers we also distribute fully functioning 3239demonstration programs that takes you through the steps we are about to 3240discuss; these demo programs may be used as your starting point for 3241further development and can be found in the gmt-custom repository. 3242 3243Presenting and parsing the FFT options 3244-------------------------------------- 3245 3246Several GMT programs that use the FFTs present the same unified option and 3247modifier sets to the user. The API makes these available as well. If 3248your program needs to present the FFT option usage you can call 3249 3250.. _GMT_FFT_Option: 3251 3252 :: 3253 3254 unsigned int GMT_FFT_Option (void *API, char option, unsigned int dim, 3255 const char *string); 3256 3257Here, ``option`` is the unique character used for this particular 3258program option (most GMT programs have standardized on using 'N' but 3259you are free to choose whatever letter you want except existing GMT common 3260options). The ``dim`` sets the dimension of the transform; currently you 3261must choose 1 or 2, while ``string`` is a one-line message that 3262states what the option does; you should tailor this to your program. If 3263NULL then a generic message is placed instead. 3264 3265To parse the user's selection you call 3266 3267.. _GMT_FFT_Parse: 3268 3269 :: 3270 3271 void *GMT_FFT_Parse (void *API, char option, unsigned int dim, const char *arg); 3272 3273which accepts the user's string option via ``arg``; the other arguments 3274are the same as those above. The function returns an opaque pointer to a 3275structure with the chosen parameters. 3276 3277Initializing the FFT machinery 3278------------------------------ 3279 3280Before your can take any transforms you must initialize the FFT 3281machinery. This process involves a series of preparatory steps that are 3282conveniently performed for you by 3283 3284.. _GMT_FFT_Create: 3285 3286 :: 3287 3288 void *GMT_FFT_Create (void *API, void *X, unsigned int dim, 3289 unsigned int mode, void *F); 3290 3291Here, ``X`` is either your dataset or grid pointer, ``dim`` is the 3292dimension of the transform (1 or 2 only), ``mode`` passes various flags to the setup, such as whether 3293the data is real, imaginary, or complex, and ``F`` is the opaque pointer 3294previously returned by GMT_FFT_Parse_. Depending on the option string you passed to 3295GMT_FFT_Parse_, the data may have a constant level or a trend 3296removed, mirror reflected and extended by various symmetries, padded and 3297tapered to desired transform dimensions, and possibly 3298temporary files are written out before the transform takes place. See the :doc:`/grdfft` 3299man page for a full explanation of the options presented by GMT_FFT_Option_. 3300 3301Taking the FFT 3302-------------- 3303 3304Now that everything has been set up you can perform the transform with 3305 3306.. _GMT_FFT: 3307 3308 :: 3309 3310 void *GMT_FFT (void *API, void *X, int direction, unsigned int mode, void *K); 3311 3312which takes as ``direction`` either ``GMT_FFT_FWD`` or ``GMT_FFT_INV``. The 3313``mode`` is used to specify if we pass a real (``GMT_FFT_REAL``) or complex 3314(``GMT_FFT_COMPLEX``) data set, and ``K`` is the opaque pointer returned 3315by GMT_FFT_Create_. The transform is performed in place and returned 3316via ``X``. When done with your manipulations (below) you can call it 3317again with the inverse direction to recover the corresponding space-domain 3318version of your data. The FFT is fully normalized so that calling 3319forward followed by inverse yields the original data set. The information 3320passed via ``K`` determines if a 1-D or 2-D transform takes place; the 3321key work is done via ``GMT_FFT_1D`` or ``GMT_FFT_2D``, as explained below. 3322 3323Taking the 1-D FFT 3324------------------ 3325 3326A lower-level 1-D FFT is also available via the API, i.e., 3327 3328.. _GMT_FFT_1D: 3329 3330 :: 3331 3332 int GMT_FFT_1D (void *API, float *data, uint64_t n, int direction, 3333 unsigned int mode); 3334 3335which takes as ``direction`` either ``GMT_FFT_FWD`` or ``GMT_FFT_INV``. The 3336``mode`` is used to specify if we pass a real (``GMT_FFT_REAL``) or complex 3337(``GMT_FFT_COMPLEX``) data set, and ``data`` is the 1-D data array of length 3338``n`` that we wish 3339to transform. The transform is performed in place and returned 3340via ``data``. When done with your manipulations (below) you can call it 3341again with the inverse direction to recover the corresponding space-domain 3342version of your data. The 1-D FFT is fully normalized so that calling 3343forward followed by inverse yields the original data set. 3344 3345Taking the 2-D FFT 3346------------------ 3347 3348A lower-level 2-D FFT is also available via 3349 3350.. _GMT_FFT_2D: 3351 3352 :: 3353 3354 int GMT_FFT_2D (void *API, float *data, unsigned int n_columns, 3355 unsigned int n_rows, int direction, unsigned int mode); 3356 3357which takes as ``direction`` either ``GMT_FFT_FWD`` or ``GMT_FFT_INV``. The 3358``mode`` is used to specify if we pass a real (``GMT_FFT_REAL``) or complex 3359(``GMT_FFT_COMPLEX``) data set, and ``data`` is the 2-D data array in 3360row-major format, with row length ``n_columns`` and column length ``n_rows``. 3361The transform is performed in place and returned 3362via ``data``. When done with your manipulations (below) you can call it 3363again with the inverse direction to recover the corresponding space-domain 3364version of your data. The 2-D FFT is fully normalized so that calling 3365forward followed by inverse yields the original data set. 3366 3367Wavenumber calculations 3368----------------------- 3369 3370As your data have been transformed to the wavenumber domain you may wish 3371to operate on the various values as a function of wavenumber. We will 3372show how this is done for datasets and grids separately. First, we 3373present the function that returns an individual wavenumber: 3374 3375.. _GMT_FFT_Wavenumber: 3376 3377 :: 3378 3379 double GMT_FFT_Wavenumber (void *API, uint64_t k, unsigned int mode, void *K); 3380 3381where ``k`` is the index into the array or grid, ``mode`` specifies 3382which wavenumber we want (it is not used for 1-D transform but for the 33832-D transform we can select either the x-wavenumber (0), the 3384y-wavenumber (1), or the radial wavenumber (2)), and finally the opaque 3385vector created by GMT_FFT_Create_. 3386 33871-D FFT manipulation 3388~~~~~~~~~~~~~~~~~~~~ 3389 3390[To be added after gmtfft has been added as new module, probably in 5.4.] 3391 33922-D FFT manipulation 3393~~~~~~~~~~~~~~~~~~~~ 3394 3395The number of complex pairs in the grid is given by the header's ``nm`` 3396variable, while ``size`` will be twice that value as it holds the number 3397of components. To visit all the complex values and obtain the 3398corresponding wavenumber we simply need to loop over ``size`` and call 3399GMT_FFT_Wavenumber_. This code snippet multiples the complex grid by 3400the radial wavenumber: 3401 3402 :: 3403 3404 uint64_t k; 3405 for (k = 0; k < Grid->header->size; k++) { 3406 wave = GMT_FFT_Wavenumber (API, k, 2, K); 3407 Grid->data[k] *= wave; 3408 } 3409 3410Alternatively, you may choose to be more specific about which components 3411are real and imaginary (especially if they are to be treated 3412differently), and set up the loop this way: 3413 3414 :: 3415 3416 uint64_t re, im; 3417 for (re = 0, im = 1; re < Grid->header->size; re += 2, im += 2) { 3418 wave = GMT_FFT_Wavenumber (API, re, 2, K); 3419 Grid->data[re] *= wave; 3420 Grid->data[im] *= 2.0 * wave; 3421 } 3422 3423Destroying the FFT machinery 3424---------------------------- 3425 3426When done you terminate the FFT machinery with 3427 3428.. _GMT_FFT_Destroy: 3429 3430 :: 3431 3432 double GMT_FFT_Destroy (void *API, void *K); 3433 3434which simply frees up the memory allocated by the FFT machinery with GMT_FFT_Create_. 3435 3436FORTRAN Support 3437=============== 3438 3439FORTRAN 90 developers who wish to use the GMT API may use the same 3440API functions as discussed in Chapter 2. As we do not have much (i.e., any) experience 3441with modern Fortran we are not sure to what extent you are able to access 3442the members of the various structures, such as the :ref:`GMT_GRID <struct-grid>` structure. Thus, 3443this part will depend on feedback and for the time being is to be considered 3444preliminary and subject to change. We encourage you to take contact should you 3445wish to use the API with your Fortran 90 programs. 3446 3447FORTRAN 77 Grid i/o 3448------------------- 3449 3450Because of a lack of structure pointers we can only provide a low level of 3451support for Fortran 77. This API is limited to help you inquire, read and write 3452GMT grids directly from Fortran 77. 3453To inquire about the range of information in a grid, use 3454 3455.. _gmt_f77_readgrdinfo: 3456 3457 :: 3458 3459 int gmt_f77_readgrdinfo (unsigned int dim[], double limits[], double inc[], 3460 char *title, char *remark, const char *file) 3461 3462where ``dim`` returns the grid width, height, and registration, ``limits`` returns the min and max values for x, y, and z 3463as three consecutive pairs, ``inc`` returns the x and y increments, while the ``title`` and ``remark`` 3464return the values of these strings. The ``file`` 3465argument is the name of the file we wish to inquire about. The function returns 0 unless there is an error. 3466Note that you must declare your variables so that ``limits`` has at least 6 elements, ``inc`` has at least 2, and ``dim`` has at least 4. 3467 3468To actually read the grid, we use 3469 3470.. _gmt_f77_readgrd: 3471 3472 :: 3473 3474 int gmt_f77_readgrd (float *array, unsigned int dim[], double wesn[], 3475 double inc[], char *title, char *remark, const char *file) 3476 3477where ``array`` is the 1-D grid data array, ``dim`` returns the grid width, height, and registration, 3478``limits`` returns the min and max values for x, y, and z, ``inc`` returns the x and y increments, and 3479the ``title`` and ``remark`` return the values of the corresponding strings. The ``file`` 3480argument is the name of the file we wish to read from. The function returns 0 unless there is an error. 3481Note on input, ``dim[2]`` can be set to 1, which means we will allocate the array for you; otherwise 3482we assume space has already been secured. Also, if ``dim[3]`` is set to 1 we will in-place transpose 3483the array from C-style row-major array order to Fortran column-major array order. 3484 3485Finally, to write a grid to file you can use 3486 3487.. _gmt_f77_writegrd: 3488 3489 :: 3490 3491 int gmt_f77_writegrd_(float *array, unsigned int dim[], double wesn[], double inc[], 3492 const char *title, const char *remark, const char *file) 3493 3494where ``array`` is the 1-D grid data array, ``dim`` specifies the grid width, height, and registration, 3495``limits`` may be used to specify a subset (normally, just pass zeros), ``inc`` specifies the x and y increments, 3496while the ``title`` and ``remark`` supply the values of these strings. The ``file`` 3497argument is the name of the file we wish to write to. The function returns 0 unless there is an error. 3498If ``dim[3]`` is set to 1 we will in-place transpose 3499the array from Fortran column-major array order to C-style row-major array order before writing. Note 3500this means ``array`` will have been transposed when the function returns. 3501 3502External Interfaces 3503=================== 3504 3505Developers may want to access GMT modules from external programming environments, such as MATLAB, 3506Octave, Julia, Python, R, IDL, etc., etc. These all face similar challenges and hence this section 3507will speak in somewhat abstract terms. Specific language addressing the challenges for some of 3508the above-mentioned environments will follow below. 3509 3510The C/C++ API for GMT makes it possible to call any of the ~100 core modules, the 40 or so supplemental 3511modules, and any number of custom modules provided via shared libraries (e.g., the gsfml modules). Many 3512of the external interfaces come equipped with methods to call C functions directly. 3513The key challenges pertain to specifying the input to use in the module and to receive 3514what is produced by the module. 3515As we know from GMT command line usage, all GMT modules expect input to be given via input files (or stdin, except for sources like grids and images). Similarly, output will be written to a specified 3516output file (or stdout if the data type supports it). Clearly, external interfaces 3517could do the same thing. The problem is that most of the time we already will have the input data in 3518memory and would prefer the output to be returned back to memory, thus avoiding using temporary files. 3519Here, we will outline the general approach for using the GMT API. We will describe a relatively low-level approach 3520to calling GMT modules. Once such an interface exists it is simpler to build a more flexible and user-friendly 3521layer on top that can handle argument parsing in a form that makes the interface seem more of a natural 3522extension of your external environment than a forced fit to GMT's command-line heritage. 3523Before we describe the interface it is important to understand that the GMT modules, since the beginning 3524or time, have done the i/o inside the modules. While these steps are helped by i/o library functions, the 3525i/o activities all take place *inside* the modules. This means that external environments in which the desired 3526input data already reside in memory and the desired results should be returned back to memory pose a 3527trickier challenge. We will see the solution to this involves the concept of *virtual* files. 3528 3529.. figure:: /_images/GMT_API_use.* 3530 :width: 500 px 3531 :align: center 3532 3533 GMT Modules can read and write information in may ways. The GMT command line modules 3534 can only access the methods in white, while all methods are available via the C API. 3535 External interfaces will preferentially want the methods in orange. 3536 3537Plain interface 3538--------------- 3539 3540While the syntax of your external environment's language will dictate the details of the implementation, we will in general 3541need to build a function (or class, or method) that allows you to issue a call like this: 3542 3543[*results*] = **gmt** (*module*, *options*, *inputs*) 3544 3545where *results* (i.e., objects returned back to memory) is optional and may be one or more items grouped 3546together, depending on language syntax. If no output is required then no left-hand side 3547assignment will be present. Likewise, *inputs* is optional and may be one or more comma-separated 3548objects present in memory. In most cases, *options* will be required and this is a string with 3549options very similar to the arguments given on the GMT command line. Finally, *module* is required since you 3550must specify which one you want to call. The coding of the **gmt** method, class, or function above may be written entirely in 3551C, partly in C and the external scripting language, or entirely in the scripting language, depending on 3552restrictions on what needs to be done and where this is most easily accomplished. 3553How this is accomplished may vary from environment to environment. 3554 3555.. figure:: /_images/GMT_API_flow.* 3556 :width: 500 px 3557 :align: center 3558 3559 Data pass in and out of the **gmt** interface which may be written in the scripting language used 3560 by the external interface. The native data will need to be encapsulated by GMT containers and this 3561 step may be done by a C **parser** but could also be done by the **gmt** interface directly. Either 3562 of these communicate directly with the C functions in the GMT API. 3563 3564Data containers 3565--------------- 3566 3567The external interface developer will need to create native data classes or structures that are capable of 3568containing the information associated with the six GMT objects: data tables, grids, images, cubes, color palette tables, 3569and PostScript documents. In other words, how your external environment will represent these 3570data in memory. Some of these "containers" may already exist, while others may need to be designed. Most likely, you will end up with 3571a set of six containers that can hold the various GMT data objects and related metadata. In addition, it may 3572be convenient to also consider the two GMT helper objects MATRIX and VECTOR, which may be closer to the native 3573representation of your data than, for instance, the native GMT_DATASET. 3574 3575Input from memory 3576----------------- 3577 3578Whether input comes from memory or from external files, the call to a GMT module is the same: we have to specify 3579*filenames* to provide the input data. Thus, the game is to provide *virtual* file names that represent our in-memory 3580data. The process is relatively simple and may need to be done in a snippet of C 3581code that can be called by a function written in your environments scripting language. The steps go like this: 3582 3583#. Create a GMT C container marked for input and copy or reference your data provided by 3584 your external environment into this container. 3585#. Open a virtual file using this container to represent the input source. 3586#. Insert this virtual file name in the appropriate location in the GMT option string. If the 3587 module imports data from *stdin* then we can use the hidden option -<filename. 3588 3589When the GMT module is run it will know how to make the connections between the virtual file names and 3590the actual data via information stored inside the C API. When the module completes you should close any 3591open virtual files that were used by the module. 3592 3593Output to memory 3594---------------- 3595 3596As the case for selecting input, GMT modules only know about writing results to a file (or stdout). Hence, we must follow the same paradigm as we did for input 3597and identify virtual files to represent the output destinations. The steps are: 3598 3599#. Create an empty GMT C container of the right type marked for output. 3600#. Create a virtual file name to represent this output destination. 3601#. Place this file name in the appropriate location in the GMT option string. If the 3602 module exports data to *stdout* then we can use the hidden option ->filename. 3603 3604When the GMT module is run it will know how to make the connections between the memory allocated by the 3605module and the virtual file names stored inside the C API. Once the module call has completed you can access the 3606results in the external environment by using GMT_Read_VirtualFile_ with the virtual filename you created earlier. This will return a GMT C container with the results, and 3607you can now populate you external data containers with data produced by the GMT module. 3608 3609The magic of knowing 3610-------------------- 3611 3612External developers have access to the two extra API functions GMT_Encode_Options_ and GMT_Expand_Option_. 3613Your **gmt** will need to call GMT_Encode_Options_ to obtain information about what the selected 3614module expects, what its options are, which were selected, and what data types are expected. It may 3615possibly modify the options, such as adding the filename "?" to options that set 3616*required* input and output files and returns an array of structures with specific information about 3617all inputs and outputs. If sources and destinations were missing from your *options* string it is taken 3618to mean that you want to associate these sources and destinations 3619with memory locations rather than actual files. The second function GMT_Expand_Option_ can then then 3620used to replace these place-holder names with the virtual filenames you created earlier. 3621 3622The MATLAB interface 3623~~~~~~~~~~~~~~~~~~~~ 3624 3625We have built a MATLAB/Octave interface to GMT called the toolbox. It was our first attempt to use the C API from an 3626external environment and its development influenced 3627how we designed the final GMT C API. MATLAB represents most data as matrices but there are also structures that 3628can hold many different items, including several matrices and text strings. Thus, we designed several native mex structures 3629that represent the six GMT objects. The main **gmt** function available in MATLAB derives from a small MATLAB script 3630(gmt.m) which handles basic argument testing and then passes the arguments to our C function gmtmex.c. 3631Most of the high-level parsing of options and arguments is done in this function, but we also rely on 3632a C library (gmtmex_parser.c) that hides the details of the implementation. It is this library that 3633does most of the work in translating between the GMT and MATLAB object layouts. Knowing what types are 3634represented by the different sources and destinations is provided by the array of structures returned 3635by GMT_Encode_Options_. 3636 3637The Julia interface 3638~~~~~~~~~~~~~~~~~~~ 3639 3640Unlike the MATLAB interface, the Julia interface GMT.jl is written entirely in the Julia language. 3641 3642The Python interface 3643~~~~~~~~~~~~~~~~~~~~ 3644 3645Unlike the MATLAB interface, the Python interface PyGMT is written entirely in the Python language. 3646 3647Appendix A: GMT resources 3648------------------------- 3649 3650We earlier introduced the six standard GMT resources (dataset, grid, image, cube, color palette table, PostScript) 3651as well as the user vector and matrix. Here are the complete definitions of these structures, including 3652all variables accessible via the structures. 3653 3654Data set 3655~~~~~~~~ 3656 3657Each data set is represented by a :ref:`GMT_DATASET <struct-dataset>` that consists of one or more data 3658tables represented by a :ref:`GMT_DATATABLE <struct-datatable>`, and each table consists of one or more 3659segments represented by a :ref:`GMT_DATASEGMENT <struct-datasegment>`, and each segment contains one or 3660more rows of a fixed number of columns. 3661 3662.. _struct-dataset: 3663 3664.. code-block:: c 3665 3666 struct GMT_DATASET { /* Single container for an array of GMT tables (files) */ 3667 /* Variables we document for the API: */ 3668 uint64_t n_tables; /* Total number of tables (files) contained */ 3669 uint64_t n_columns; /* Number of data columns */ 3670 uint64_t n_segments; /* Total number of segments across all tables */ 3671 uint64_t n_records; /* Total number of data records across all tables */ 3672 double *min; /* Minimum coordinate for each column */ 3673 double *max; /* Maximum coordinate for each column */ 3674 struct GMT_DATATABLE **table; /* Pointer to array of tables */ 3675 unsigned int type; /* The data record type of this dataset */ 3676 unsigned int geometry; /* The geometry of this dataset */ 3677 const char *ProjRefPROJ4; /* To store a referencing system string in PROJ.4 format */ 3678 const char *ProjRefWKT; /* To store a referencing system string in WKT format */ 3679 int ProjRefEPSG; /* To store a referencing system EPSG code */ 3680 void *hidden; /* ---- Variables "hidden" from the API ---- */ 3681 }; 3682 3683Here is the full definition of the ``GMT_DATATABLE`` structure: 3684 3685.. _struct-datatable: 3686 3687.. code-block:: c 3688 3689 struct GMT_DATATABLE { /* To hold an array of line segment structures and header information in one container */ 3690 /* Variables we document for the API: */ 3691 unsigned int n_headers; /* Number of file header records (0 if no header) */ 3692 uint64_t n_columns; /* Number of columns (fields) in each record */ 3693 uint64_t n_segments; /* Number of segments in the array */ 3694 uint64_t n_records; /* Total number of data records across all segments */ 3695 double *min; /* Minimum coordinate for each column */ 3696 double *max; /* Maximum coordinate for each column */ 3697 char **header; /* Array with all file header records, if any) */ 3698 struct GMT_DATASEGMENT **segment; /* Pointer to array of segments */ 3699 void *hidden; /* ---- Variables "hidden" from the API ---- */ 3700 }; 3701 3702Here is the full definition of the ``GMT_DATASEGMENT`` structure: 3703 3704.. _struct-datasegment: 3705 3706.. code-block:: c 3707 3708 struct GMT_DATASEGMENT { /* For holding segment lines in memory */ 3709 /* Variables we document for the API: */ 3710 uint64_t n_rows; /* Number of points in this segment */ 3711 uint64_t n_columns; /* Number of fields in each record (>= 2) */ 3712 double *min; /* Minimum coordinate for each column */ 3713 double *max; /* Maximum coordinate for each column */ 3714 double **data; /* Data x,y, and possibly other columns */ 3715 char **text; /* trailing text strings beyond the data */ 3716 char *label; /* Label string (if applicable) */ 3717 char *header; /* Segment header (if applicable) */ 3718 void *hidden; /* ---- Variables "hidden" from the API ---- */ 3719 }; 3720 3721GMT grid 3722~~~~~~~~ 3723 3724A grid is represented by a :ref:`GMT_GRID <struct-grid>` that consists of a header structure 3725represented by a :ref:`GMT_GRID_HEADER <struct-gridheader>` and an float array ``data`` that 3726contains the grid values. 3727 3728.. _struct-grid: 3729 3730.. code-block:: c 3731 3732 struct GMT_GRID { /* To hold a GMT float grid and its header in one container */ 3733 struct GMT_GRID_HEADER *header; /* Pointer to full GMT header for the grid */ 3734 float *data; /* Pointer to the float grid */ 3735 double *x, *y; /* Vector of coordinates */ 3736 void *hidden; /* ---- Variables "hidden" from the API ---- */ 3737 }; 3738 3739The full definition of the ``GMT_GRID_HEADER`` structure. Most of these members are only used internally: 3740 3741.. _struct-gridheader: 3742 3743.. code-block:: c 3744 3745 struct GMT_GRID_HEADER { 3746 /* Variables we document for the API: 3747 They are copied verbatim to the native grid header and must be 4-byte unsigned ints. */ 3748 uint32_t n_columns; /* Number of columns */ 3749 uint32_t n_rows; /* Number of rows */ 3750 uint32_t registration; /* GMT_GRID_NODE_REG (0) or GMT_GRID_PIXEL_REG (1) */ 3751 3752 /* == The types of the following 12 elements must not be changed. 3753 == They are also copied verbatim to the native grid header. */ 3754 double wesn[4]; /* Min/max x and y coordinates */ 3755 double z_min; /* Minimum z value */ 3756 double z_max; /* Maximum z value */ 3757 double inc[2]; /* x and y increment */ 3758 double z_scale_factor; /* grd values must be multiplied by this */ 3759 double z_add_offset; /* After scaling, add this */ 3760 char x_units[GMT_GRID_UNIT_LEN80]; /* units in x-direction */ 3761 char y_units[GMT_GRID_UNIT_LEN80]; /* units in y-direction */ 3762 char z_units[GMT_GRID_UNIT_LEN80]; /* grid value units */ 3763 char title[GMT_GRID_TITLE_LEN80]; /* name of data set */ 3764 char command[GMT_GRID_COMMAND_LEN320];/* name of generating command */ 3765 char remark[GMT_GRID_REMARK_LEN160]; /* comments re this data set */ 3766 /* == End of "untouchable" header. */ 3767 3768 /* This section is flexible. It is not copied to any grid header 3769 or stored in any file. It is considered private */ 3770 unsigned int type; /* Grid format */ 3771 unsigned int bits; /* Bits per value (e.g., 32 for ints/floats; 8 for bytes) */ 3772 unsigned int complex_mode; /* 0 = normal, GMT_GRID_IS_COMPLEX_REAL = real part of complex 3773 grid, GMT_GRID_IS_COMPLEX_IMAG = imag part of complex grid */ 3774 unsigned int mx, my; /* Actual dimensions of the grid in memory, allowing for the padding */ 3775 size_t nm; /* Number of data items in this grid (n_columns * n_rows) [padding is excluded] */ 3776 size_t size; /* Actual number of items (not bytes) required to hold this grid (= mx * my), per band */ 3777 size_t n_alloc; /* Bytes allocated for this grid */ 3778 unsigned int n_bands; /* Number of bands [1]. Used with IMAGE containers and macros to get ij index from row,col, band */ 3779 unsigned int pad[4]; /* Padding on west, east, south, north sides [2,2,2,2] */ 3780 const char *ProjRefPROJ4; /* To store a referencing system string in PROJ.4 format */ 3781 const char *ProjRefWKT; /* To store a referencing system string in WKT format */ 3782 float nan_value; /* Missing value as stored in grid file */ 3783 double xy_off; /* 0.0 (registration == GMT_GRID_NODE_REG) or 0.5 ( == GMT_GRID_PIXEL_REG) */ 3784 void *hidden; /* ---- Variables "hidden" from the API ---- */ 3785 }; 3786 3787GMT image 3788~~~~~~~~~ 3789 3790An image is similar to a grid except it may have more than one layer (i.e., band). 3791It is represented by a :ref:`GMT_IMAGE <struct-image>` structure that consists of the 3792:ref:`GMT_GRID_HEADER <struct-gridheader>` structure and an char array ``data`` that 3793contains the image values. The type of the array is determined by the value of ``type``. 3794**Note**: The header *size* value reflects number of nodes per band, so the actual memory 3795allocated will be *size * n_bands*. 3796 3797.. _struct-image: 3798 3799.. code-block:: c 3800 3801 struct GMT_IMAGE { 3802 enum GMT_enum_type type; /* Data type, e.g. GMT_FLOAT */ 3803 int *colormap; /* Array with color lookup values */ 3804 int n_indexed_colors; /* Number of colors in a color-mapped image */ 3805 struct GMT_GRID_HEADER *header; /* Pointer to full GMT header for the image */ 3806 unsigned char *data; /* Pointer to actual image */ 3807 unsigned char *alpha; /* Pointer to an optional transparency layer */ 3808 const char *color_interp; /* Color interpretation name */ 3809 double *x, *y; /* Vector of coordinates */ 3810 void *hidden; /* ---- Variables "hidden" from the API ---- */ 3811 }; 3812 3813GMT cube 3814~~~~~~~~ 3815 3816A 3-D cube is similar to a grid but typically has more than one layer. 3817It is represented by a :ref:`GMT_CUBE <struct-cube>` structure that consists of the 3818:ref:`GMT_GRID_HEADER <struct-gridheader>` structure and an float array ``data`` that 3819contains the cube values. 3820**Note**: The header *size* value reflects number of nodes per layer, so the actual memory 3821allocated will be *size * n_bands*, where the latter is one of the parameters in the header. 3822 3823.. _struct-cube: 3824 3825.. code-block:: c 3826 3827 struct GMT_CUBE { 3828 struct GMT_GRID_HEADER *header; /* The full GMT header for the cube */ 3829 float *data; /* Pointer to the float 3-D array */ 3830 unsigned int mode; /* Indicates data originated as a list of 2-D grids rather than a cube */ 3831 double z_range[2]; /* Minimum/maximum z-dimension values (complements header->wesn) */ 3832 double z_inc; /* z-dimension increment (complements header->inc) (0 if variable z spacing) */ 3833 double *x, *y, *z; /* Arrays of x,y,z coordinates */ 3834 char name[GMT_GRID_UNIT_LEN80]; /* Name of variable, if read from file (empty if default) */ 3835 char units[GMT_GRID_UNIT_LEN80]; /* Units in 3rd direction (complements x_units, y_units, z_units) */ 3836 void *hidden; /* ---- Variables "hidden" from the API ---- */ 3837 }; 3838 3839CPT palette table 3840~~~~~~~~~~~~~~~~~ 3841 3842A CPT is represented by a :ref:`GMT_PALETTE <struct-palette>` structure that contains several 3843items, such as a :ref:`GMT_LUT <struct-lut>` structure ``data`` that 3844contains the color information per interval. The background, foreground and Nan-color values have 3845colors specified by the :ref:`GMT_BFN <struct-bnf>` array structure ``bfn``. As each actual 3846color may be specified in different ways, including as an image, each color slice is represented by 3847the :ref:`GMT_FILL <struct-fill>` structure. 3848 3849.. _struct-palette: 3850 3851.. code-block:: c 3852 3853 struct GMT_PALETTE { /* Holds all pen, color, and fill-related parameters */ 3854 /* Variables we document for the API: */ 3855 struct GMT_LUT *data; /* CPT lookup data read by GMT_read_cpt */ 3856 struct GMT_BFN bfn[3]; /* Structures with back/fore/nan fills */ 3857 unsigned int n_headers; /* Number of CPT header records (0 if no header) */ 3858 unsigned int n_colors; /* Number of colors in CPT lookup table */ 3859 unsigned int mode; /* Flags controlling use of BFN colors */ 3860 unsigned int model; /* RGB, HSV, CMYK */ 3861 unsigned int is_wrapping; /* true if a cyclic colortable */ 3862 unsigned int is_gray; /* true if only grayshades are needed */ 3863 unsigned int is_bw; /* true if only black and white are needed */ 3864 unsigned int is_continuous; /* true if continuous color tables have been given */ 3865 unsigned int has_pattern; /* true if CPT contains any patterns */ 3866 unsigned int has_hinge; /* true if CPT has a hinge */ 3867 unsigned int has_range; /* true if CPT has a natural range */ 3868 unsigned int categorical; /* true if CPT applies to categorical data */ 3869 double minmax[2]; /* The default range, if has_range is true */ 3870 double hinge; /* The default hinge, if is_wrapping is true */ 3871 double wrap_length; /* The default period, if has_hinge is true */ 3872 char **header; /* Array with all CPT header records, if any) */ 3873 void *hidden; /* ---- Variables "hidden" from the API ---- */ 3874 }; 3875 3876The full definition of the ``GMT_LUT`` structure. 3877 3878.. _struct-lut: 3879 3880.. code-block:: c 3881 3882 struct GMT_LUT { /* For back-, fore-, and nan-colors */ 3883 double z_low, z_high, i_dz; 3884 double rgb_low[4], rgb_high[4], rgb_diff[4]; 3885 double hsv_low[4], hsv_high[4], hsv_diff[4]; 3886 unsigned int annot; /* 1 for Lower, 2 for Upper, 3 for Both */ 3887 unsigned int skip; /* true means skip this slice */ 3888 struct GMT_FILL *fill; /* For patterns instead of color */ 3889 char *label; /* For non-number labels */ 3890 }; 3891 3892The full definition of the ``GMT_BFN`` structure: 3893 3894.. _struct-bnf: 3895 3896.. code-block:: c 3897 3898 struct GMT_BFN { /* For back-, fore-, and nan-colors */ 3899 double rgb[4]; /* Red, green, blue, and alpha */ 3900 double hsv[4]; /* Hue, saturation, value, alpha */ 3901 unsigned int skip; /* true means skip this slice */ 3902 struct GMT_FILL *fill; /* For patterns instead of color */ 3903 }; 3904 3905The full definition of the ``GMT_FILL`` structure. **Note**: Not part of the GMT API: 3906 3907.. _struct-fill: 3908 3909.. code-block:: c 3910 3911 struct GMT_FILL { /*! Holds fill attributes */ 3912 double rgb[4]; /* Chosen color if no pattern + Transparency 0-1 [0 = opaque] */ 3913 double f_rgb[4], b_rgb[4]; /* Colors applied to unset and set bits in 1-bit image */ 3914 bool use_pattern; /* true if pattern rather than rgb is set */ 3915 int pattern_no; /* Number of a predefined pattern, or -1 if not set */ 3916 unsigned int dpi; /* Desired dpi of image building-block if use_pattern is true */ 3917 char pattern[GMT_BUFSIZ];/* Full filename of user-defined raster pattern */ 3918 }; 3919 3920 3921PostScript text 3922~~~~~~~~~~~~~~~ 3923 3924Bulk PostScript is represented by a :ref:`GMT_POSTSCRIPT <struct-postscript>` structure that contains 3925``data`` that points to the text array containing ``n_bytes`` characters of raw PostScript code. The 3926``mode`` parameter reflects the status of the PostScript document. 3927 3928.. _struct-postscript: 3929 3930.. code-block:: c 3931 3932 struct GMT_POSTSCRIPT { /* Single container for a chunk of PostScript code */ 3933 /* Variables we document for the API: */ 3934 unsigned int n_headers; /* Number of PostScript header records (0 if no header) */ 3935 size_t n_bytes; /* Length of data array so far */ 3936 unsigned int mode; /* Bit-flag for header (1) and trailer (2) */ 3937 char *data; /* Pointer to PostScript code */ 3938 char **header; /* Array with all PostScript header records, if any) */ 3939 void *hidden; /* ---- Variables "hidden" from the API ---- */ 3940 }; 3941 3942Matrix 3943~~~~~~ 3944 3945User matrices are represented by a :ref:`GMT_MATRIX <struct-matrix>` structure that contains 3946``data`` that points to an array of size ``n_columns`` by ``n_rows``. The 3947``type`` indicates the memory type of the matrix, which is represented 3948by the :ref:`GMT_UNIVECTOR <struct-univector>` union. 3949 3950.. _struct-matrix: 3951 3952.. code-block:: c 3953 3954 struct GMT_MATRIX { 3955 uint64_t n_rows; /* Number of rows in the matrix */ 3956 uint64_t n_columns; /* Number of columns in the matrix */ 3957 uint64_t n_layers; /* Number of layers in a 3-D matrix */ 3958 enum GMT_enum_fmt shape; /* 0 = C (rows) and 1 = Fortran (cols) */ 3959 enum GMT_enum_reg registration; /* 0 for gridline and 1 for pixel registration */ 3960 size_t dim; /* Allocated length of longest C or Fortran dim */ 3961 size_t size; /* Byte length of data */ 3962 enum GMT_enum_type type; /* Data type, e.g. GMT_FLOAT */ 3963 double range[6]; /* Contains xmin/xmax/ymin/ymax[/zmin/zmax] */ 3964 union GMT_UNIVECTOR data; /* Union with pointer to actual matrix of the chosen type */ 3965 char **text; /* Pointer to optional array of strings [NULL] */ 3966 char **header; /* Array with all Vector header records, if any) */ 3967 char command[GMT_GRID_COMMAND_LEN320]; /* name of generating command */ 3968 char remark[GMT_GRID_REMARK_LEN160]; /* comments re this data set */ 3969 const char *ProjRefPROJ4; /* To store a referencing system string in PROJ.4 format */ 3970 const char *ProjRefWKT; /* To store a referencing system string in WKT format */ 3971 int ProjRefEPSG; /* To store a referencing system EPSG code */ 3972 void *hidden; /* ---- Variables "hidden" from the API ---- */ 3973 }; 3974 3975Vectors 3976~~~~~~~ 3977 3978User vectors are represented by a :ref:`GMT_VECTOR <struct-vector>` structure that contains 3979``data`` that points to an array of ``n_columns`` individual vectors. The 3980``type`` array indicates the memory type of each vector. Each vector is represented 3981by the :ref:`GMT_UNIVECTOR <struct-univector>` union which can accommodate any data type. 3982 3983.. _struct-vector: 3984 3985.. code-block:: c 3986 3987 struct GMT_VECTOR { 3988 uint64_t n_columns; /* Number of vectors */ 3989 uint64_t n_rows; /* Number of rows in each vector */ 3990 enum GMT_enum_reg registration; /* 0 for gridline and 1 for pixel registration */ 3991 enum GMT_enum_type *type; /* Array with data type for each vector */ 3992 union GMT_UNIVECTOR *data; /* Array with unions for each column */ 3993 double range[2]; /* The min and max limits on t-range (or 0,0) */ 3994 char **text; /* Pointer to optional array of strings [NULL] */ 3995 char **header; /* Array with all Vector header records, if any) */ 3996 char command[GMT_GRID_COMMAND_LEN320]; /* name of generating command */ 3997 char remark[GMT_GRID_REMARK_LEN160]; /* comments re this data set */ 3998 const char *ProjRefPROJ4; /* To store a referencing system string in PROJ.4 format */ 3999 const char *ProjRefWKT; /* To store a referencing system string in WKT format */ 4000 int ProjRefEPSG; /* To store a referencing system EPSG code */ 4001 void *hidden; /* ---- Variables "hidden" from the API ---- */ 4002 }; 4003 4004The full definition of the ``GMT_UNIVECTOR`` union that holds a pointer to any array or matrix type: 4005 4006.. _struct-univector: 4007 4008.. code-block:: c 4009 4010 union GMT_UNIVECTOR { 4011 uint8_t *uc1; /* Pointer for unsigned 1-byte array */ 4012 int8_t *sc1; /* Pointer for signed 1-byte array */ 4013 uint16_t *ui2; /* Pointer for unsigned 2-byte array */ 4014 int16_t *si2; /* Pointer for signed 2-byte array */ 4015 uint32_t *ui4; /* Pointer for unsigned 4-byte array */ 4016 int32_t *si4; /* Pointer for signed 4-byte array */ 4017 uint64_t *ui8; /* Pointer for unsigned 8-byte array */ 4018 int64_t *si8; /* Pointer for signed 8-byte array */ 4019 float *f4; /* Pointer for float array */ 4020 double *f8; /* Pointer for double array */ 4021 }; 4022 4023 4024Appendix B: GMT constants 4025------------------------- 4026 4027To increase readability we have encoded many simple integer constants as named 4028enum. These are listed in the tables below and used as flags to various API 4029functions. 4030 4031.. _tbl-types: 4032 4033 +--------------+------------------------------------------+ 4034 | constant | description | 4035 +==============+==========================================+ 4036 | GMT_CHAR | int8_t, 1-byte signed integer type | 4037 +--------------+------------------------------------------+ 4038 | GMT_UCHAR | int8_t, 1-byte unsigned integer type | 4039 +--------------+------------------------------------------+ 4040 | GMT_SHORT | int16_t, 2-byte signed integer type | 4041 +--------------+------------------------------------------+ 4042 | GMT_USHORT | uint16_t, 2-byte unsigned integer type | 4043 +--------------+------------------------------------------+ 4044 | GMT_INT | int32_t, 4-byte signed integer type | 4045 +--------------+------------------------------------------+ 4046 | GMT_UINT | uint32_t, 4-byte unsigned integer type | 4047 +--------------+------------------------------------------+ 4048 | GMT_LONG | int64_t, 8-byte signed integer type | 4049 +--------------+------------------------------------------+ 4050 | GMT_ULONG | uint64_t, 8-byte unsigned integer type | 4051 +--------------+------------------------------------------+ 4052 | GMT_FLOAT | 4-byte data float type | 4053 +--------------+------------------------------------------+ 4054 | GMT_DOUBLE | 8-byte data float type | 4055 +--------------+------------------------------------------+ 4056 4057 The known data types in the GMT API. 4058 4059When GMT_Open_VirtualFile_ is used with a NULL pointer to create a 4060virtual file for returning results from a GMT module *and* you are 4061using a :ref:`GMT_MATRIX <struct-matrix>` or :ref:`GMT_VECTOR <struct-vector>` 4062as your container, you may prescribe 4063the data type used for the underlying arrays. The constants below 4064can be added to the ``direction`` argument in order to change the 4065default data types [float for matrix and double for vector]. 4066 4067.. _tbl-viatypes: 4068 4069 +------------------+------------------------------------------+ 4070 | constant | description | 4071 +==================+==========================================+ 4072 | GMT_VIA_CHAR | Select GMT_CHAR as array type | 4073 +------------------+------------------------------------------+ 4074 | GMT_VIA_UCHAR | Select GMT_UCHAR as array type | 4075 +------------------+------------------------------------------+ 4076 | GMT_VIA_SHORT | Select GMT_SHORT as array type | 4077 +------------------+------------------------------------------+ 4078 | GMT_VIA_USHORT | Select GMT_USHORT as array type | 4079 +------------------+------------------------------------------+ 4080 | GMT_VIA_INT | Select GMT_INT as array type | 4081 +------------------+------------------------------------------+ 4082 | GMT_VIA_UINT | Select GMT_UINT as array type | 4083 +------------------+------------------------------------------+ 4084 | GMT_VIA_LONG | Select GMT_LONG as array type | 4085 +------------------+------------------------------------------+ 4086 | GMT_VIA_ULONG | Select GMT_ULONG as array type | 4087 +------------------+------------------------------------------+ 4088 | GMT_VIA_FLOAT | Select GMT_FLOAT as array type | 4089 +------------------+------------------------------------------+ 4090 | GMT_VIA_DOUBLE | Select GMT_DOUBLE as array type | 4091 +------------------+------------------------------------------+ 4092 4093 Flags to select the type of arrays used in output GMT_MATRIX or GMT_VECTOR. 4094 4095Footnotes 4096--------- 4097 4098.. [1] 4099 or via a very confusing and ever-changing myriad of low-level library 4100 functions for bold programmers. 4101 4102.. [2] 4103 Currently, C/C++, FORTRAN, MATLAB and Julia are being tested. 4104 4105.. [3] 4106 This may change in later releases. 4107 4108.. [4] 4109 However, there is no thread-support yet, so you will need to manage your 4110 own threads. 4111 4112.. ------------------------------------- Examples code ------------------- 4113 4114.. |ex_resource_init| raw:: html 4115 4116 <a href="#openModal">Example</a> 4117 <div id="openModal" class="modalDialog"> 4118 <div> 4119 <a href="#close" title="Close" class="close">X</a> 4120 <h2>Resource initialization example</h2> 4121 <p> 4122 </p> 4123 </div> 4124 </div> 4125
