GMT - API GMT接口 Word版

The Generic Mapping Tools C/C++ Application Programming Interface

Version 5.0.0b, August 2011

P?l (Paul)Wessel

SOEST, University of Hawai’i at Mˉanoa

Walter H. F. Smith

Laboratory for Satellite Altimetry, NOAA/NESDIS

Remko Scharroo

Altimetrics LLC, Cornish, New Hampshire

Joaquim F. Luis

Universidade do Algarve, Faro, Portugal

Generic Mapping Tools Graphics

ii

Contents

Front page i Contents ii 1 Introduction 1

1.1 Preamble . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1 1.2 Definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2 1.3 Recognized resources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2 1.3.1 CPT palette tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3 1.3.2 Data tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3 1.3.3 Text tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3 1.3.4 GMT grids . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3 1.3.5 User data columns . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3 1.3.6 User data matrices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4 2 Overview of the GMT C Application Program Interface 5

2.1 Initialize a new GMT session . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5 2.2 Register input or output resources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6 2.2.1 Resource initialization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6

2.2.2 Dimension parameters for user column vectors . . . . . . . . . . . . . . . . . . . 7 2.2.3 Dimension parameters for user 2-D table arrays . . . . . . . . . . . . . . . . . . . 8 2.3 Create empty resources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8 2.4 Import Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9 2.4.1 Enable Data Import . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9

2.4.2 Import a data set . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9 2.4.3 Importing a data record . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10 2.4.4 Disable Data Import . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11 2.5 Prepare program options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11 2.5.1 Set program options via text arguments . . . . . . . . . . . . . . . . . . . . . . . 11 2.5.2 Set program options via linked structures . . . . . . . . . . . . . . . . . . . . . . 12 2.5.3 Convert between text and linked structures . . . . . . . . . . . . . . . . . . . . . 12 2.5.4 Manage the linked list of options . . . . . . . . . . . . . . . . . . . . . . . . . . . 13 2.5.5 Parsing GMT common options . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14 2.6 Calling a GMT module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14 2.7 Exporting Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14 2.7.1 Enable Data Export . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15 2.7.2 Exporting a data set . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15 2.7.3 Exporting a data record . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16 2.7.4 Disable Data Export . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16 2.8 Destroy allocated resources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16 2.9 Terminate a GMT session . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16 2.10 Report errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17 2.11 FORTRAN 77 interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17 Index 18 1

1. Introduction

1.1 Preamble

Figure 1.1:GMT 4 programs contain all the high-level functionality.

Prior to version 5, the bulk of GMT functionality was coded directly in the standard GMT C programmodules (e.g., surface.c, psxy.c, grdimage.c). 版本5之前,大部分的功能是直接在标准GMT C程序模块编码(如。surface.c, psxy.c, grdimage.c)

The GMT library only offered access to lower-level functionsfrom which those high-level GMT programs were built. “GMT lib只提供访问底层函数，这些是从那些高层GMT项目创建的。

The standard GMT programs have been verysuccessful, with tens of thousands of users world-wide. 标准GMT程序是非常成功的,它拥有成千上万的全球用户。

However, the design of the main programs preventeddevelopers from leveraging GMT functionality from within other programming environments since access toGMT tools could only be achieved via system calls. 然而,主程序阻止了开发人员利用GMT功能在其他编程环境自访问GMT工具，只能通过系统调用实现。

Consequently, all data i/o had to be done via temporaryfiles.

因此,所有的数据i / o必须通过临时文件。

The design also prevented the GMT developers themselves from taking advantage of these modulesdirectly.该设计还阻止了GMT开发人员自己直接利用这些模块。

For instance, the tool pslegend needed to make extensive use of system calls to psxy and pstextin order to plot the lines, symbols and text that make up a map legend. 例如,工具pslegend需要大量的使用系统来调用来psxy和pstext绘制线条、符号和文字构成一个地图图例。

Figure 1.2: GMT 4 programs contain all the high-level functionality. 图1.2: GMT 4程序包含所有的高级功能。

Starting with GMT version 5, all standard GMT programs are split into short driver program (the “new”GMT programs) and a function “module”.

从GMT版本5,所有标准GMT项目被分为短驱动程序(“new”GMT程序)和一个函数“模块”。 The drivers simply call the corresponding GMT modules; it isthese modules that do most of the work. 驱动简单地调用相应的GMT模块;这些模块会做大部分工作。

These new functions have been placed in a new GMT high-levelAPI library and can be called from a variety of environments (C/C++, Fortran, Python, Matlab, VisualBasic, etc.)1. 这些新功能被放置在一个新的GMT高级API库,可以从各种环境被调用(C / c++,Fortran,Python,Matlab,Visual Basic,等等。)1。

For example, the main program blockmean.c has been reconfigured as a high-level function (1Currently, only C/C++ and Matlab are being tested.)GMT_blockmean(),

例如,主程序blockmean.c已经被改造为一个高级功能(1目前,只有c / c++和Matlab进行测试)。GMT_blockmean(),

which does the actual spatial averaging and passes the result back to the callingprogram.

该方法对网格间隔框内的值取平均值,并将结果返回给调用程序。

The previous behavior of blockmean.c is replicated by a short driver program that simply collectsuser arguments and then calls GMT_blockmean(). 前面blockmean.c的行为是复制短期的驱动程序,简单地收集用户参数,然后调用GMT_blockmean()方法。

Indeed, the driver programs for all the standard GMTprograms are so short and simple that the makefile generates them on-the-fly when it compiles and linksthem with the GMT library into executables.

事实上, 所有标准GMT程序的驱动程序是如此短暂而简单,动态生成makefile何时进行编译和链接它们与GMT库为可执行文件。

Thus, blockmean.c and others do no longer exist. 因此,blockmean.c和其他行为不再存在。

In order for this interface to be as flexible as possible we have generalized the notion of input and output.

为了让这个接口是尽可能灵活，我们有广义的输入和输出的概念。

Now, data that already reside in an application’s memory may serve as input to a GMT function. 现在,数据已经存在于应用程序的内存，可以作为一个GMT函数的输入。 Othersources of input may be file pointers and file descriptors (as well as the already-supported mechanism forpassing file names).

其他来源的输入可能是文件指针和文件描述符(以及已经支持机制传递文件名)。 For standard data table i/o, the GMT API takes care of the task of assembling anycombination of files, pointers, and memory locations into a single virtual data set from which the GMTfunction may read (a) all records at once into memory, or (b) read one record at a time.对于标准的数据表的i / o,GMT API的任务是汇编任何组合文件,指针和在一个虚拟数据集中的内存位置的组合，从GMT函数可能读的(a)一次读取所有数据记录到内存,或者(b)一次读取一个数据记录。

Likewise, GMTfunctions may write their output to a virtual destination, which might be a memory location in the user’sapplication, a file pointer or descriptor, or an output file.

同样,GMT函数可以写他们的输出到一个虚拟的目的地,这可能是一个在用户的应用程序中的内存位置,一个文件指针或描述符,或一个输出文件。

The GMT functions are unaware of these detailsand simply read from a “source” and write to a “destination”.

GMT的函数是没有意识到这些细节和简单地读取一个“源”和写一个“目的地”。

Here, we document the new functions in the GMT API library for application developers who wish to callthese functions from their own custom programs.

在这里,我们记录了新功能在GMT API库为应用程序开发人员希望调用这些函数从他们自己的自定义项目。

At this point, only the new high-level GMT API is fullydocumented and intended for public use.

在这一点上,只有新的高层GMT API是完全文档化并供公众使用。

The structure and documentation of the under-lying lower-levelGMT library is not finalized Developers using these functions may risk disruption to their programs due tochanges we may make in the library in support of the GMT API.文档的结构和在基本低层GMT库并未定案开发人员使用这些函数可能会破坏他们的项目风险变化引起我们可能在库中支持GMT API。

1.2 Definitions

For the purpose of this documentation a few definitions are needed: 对于本文档需要一些定义

1. “Standard GMT program” refers to one of the traditional stand-alone

command-line executables knownto all GMT users, e.g., blockmean, psxy, grdimage, etc. Prior to version 5, these were the onlyGMT executables available.

“Standard GMT program”指的是一个传统的独立的命令行可执行文件，它被所有GMT用户知道,如,blockmean,psxy,grdimage等。版本5之前的,这些都是唯一的GMT可执行可用的。 2. “GMT module” refers to the function in the GMT API library that is responsible for all the action takenby the corresponding GMT program.

“GMT module”指的是函数在GMT API库,负责所有相应的GMT程序所采取的行动计划。 All such modules are given the same name as the correspondingprogram but carry the prefix GMT_, e.g., GMT_blockmean.

所有这些模块被赋予了与相应程序的名称相同但带有前缀gmt的字段,例如。

,GMT_blockmean。

3. “GMT application” refers to a new application written by developers and may call one or more GMTfunctions to create a new GMT-compatible executable.

“GMT application”指一个新的应用程序开发人员写的,可能调用一个或多个GMT函数来创建一个新的GMT兼容的可执行文件

4. In the API description that follows we will use the type long to mean a 4-byte (for 32-bit systems) or 8-byte (for 64-bit systems) integer.

在API描述中它遵循我们将使用的类型long意味着一个4字节(32位系统)或8字节(64位操作系统的)整形类型。

Since different operating systems have their own way of defining 8-byteintegers it is recommended that developers use the type GMT_LONG for this purpose; it is guaranteed toyield the correct type that the GMT functions expect.

因为不同的操作系统有自己的方式定义8字节的整数,因此建议开发人员使用类型GMT_LONG,它是保证产生GMT函数期望的正确的类型,

In version 5, the standard GMT programs are themselves specific but overly simple examples of GMTapplications that only call the single GMT function they are associated with.

在版本5，标准GMT程序是自己特定的但过度简单的GMT应用程序例子,只有调用相关联单个

GMT函数。

However, some exceptionssuch as pslegend and gmtconvert call several modules. 然而,也一些例外,如pslegend和gmtconvert会调用几个模块。

1.3 Recognized resources

The GMT API knows how to read and write four types of data common to GMT operations: CPT palettetables, data tables (ASCII or binary), text tables, and GMT grids. GMT API知道如何读取和写入四种常见GMT数据:CPT调色板表,数据表(ASCII或二进制),文本表,GMT网格。

In addition, we have two data types tofacilitate the passing of simple user arrays (one or more data columns of any data type, e.g., double, char)and 2-D user matrix (of any data type and column/row organization).

此外,我们有两个数据类型来促进通过简单的用户数组(一个或多个数据列的任何数据类型,例如。,double,char)和二维用户矩阵(任何数据类型和列/行组织)。

There are many attributes for each ofthese entities and therefore we use a top-level structure to keep them all in one container.

对于每个这样的实体都有许多属性,因此我们使用一个顶级结构来把它们保存在一个容器。 These containersare given or returned by the GMT API functions using opaque pointer addresses void **.

这些容器都给予还是返回的GMT API函数都使用不透明的指针地址void **。

Below wediscuss these containers in some detail; we will later present how they are used when importing or exportingthem to or from files, memory locations, or streams. 下面我们详细讨论这些容器;我们稍后会呈现怎样使用它们在导入或导出他们或从文件、内存位

置,或流。

The first four are the standard GMT types, while thelatter two are the special user data containers.

前4个是标准的GMT类型,而后者两个是特殊的用户数据的容器。

1.3.1 CPT palette tables

The color palette table files, or just CPT tables, contain colors and patterns used for plotting data such assurfaces (i.e., GMT grids) or symbols, lines and polygons (i.e., GMT tables). 颜色调色板表文件,或者只是CPT表,包含颜色和模式用于绘制数据,如表面(即。,GMT网格)或符号,线和多边形(即。,GMT表

GMT programs will generallyread in a CPT palette table, make it the current palette, do the plotting, and destroy the table when done.)。GMT程序通常会读在CPT调色板表,使它成为当前调色板,绘图,并在表完成后摧毁。

The information is referred to via a pointer to struct GMT_PALETTE. 这些信息通过一个structGMT_PALETTE指针提及。

Thus, the arguments to GMT APIfunctions that handle palettes expect this type of variable.

因此,参数传递给API函数,函数处理调色板所期望这种的类型的变量

1.3.2 Data tables

Much data processed in GMT come in the form of ASCII or binary data tables. 在GMT中多数的数据形式是ASCII或二进制数据表。

These may have any numberof header records (ASCII only) and perhaps segment headers.

这些可能会有任意数量的头记录(仅ASCII)也许是段标题。

GMT programs will read one or many suchtables when importing data. GMT程序将读取一个或许多这样的表在导入数据。

However, to avoid memory duplication some programs may prefer to readrecords one at the time.

然而,为了避免内存复制，一些程序可能更喜欢同时阅读一个记录。

The GMT API has functions that let you read record-by-record by presentinga virtual data set that combines all the data tables specified as input.

“GMT API函数有个功能，它能使你阅读纪录记录通过提供一个虚拟数据集，从而结合所有数据表指定为输入。

This simplifies record processingconsiderably. 这大大简化了记录处理。

A struct GMT_DATASET may contain any number of tables, each with any number ofsegments, and each segment with any number of records.

一个GMT_DATASET结构可以包含任意数量的表,每个表都有任意数量的段,每段有任意数量的记录。Thus, the arguments to GMT API functions thathandle such data sets expect this type of variable.

因此, GMTAPI函数的参数处理此数据集期望这种类型的变量。

1.3.3 Text tables

Some data needed by GMT are simply free-form ASCII text tables. 一些数据所需要的仅仅是自由格式的GMT ASCII文本表。

These are handled similarly to datatables. 这些都是处理类似于数据表。

E.g., they may have any number of header records and even segment headers, and GMT programscan read one or more tables or get text records one at the time.

,他们可能有任意数量的头记录甚至段标题,GMT程序可以读取一个或多个表或得到文本记录在那时。

A struct GMT_TEXTSET may containany number of tables, each with any number of segments, and each segment with any number of records.

一个struct GMT_TEXTSET可以包含任意数量的表,每个都有任意数量的段,每段与任意数量的记录。

Thus, the arguments to GMT API functions that handle such data sets expect this type of variable.

因此, GMTAPI函数的参数处理此数据集期望这种类型的变量。

1.3.4 GMT grids

GMT grids are used to represent equidistant and organized 2-D surfaces. GMT网格用于表示等距和有组织的二维表面。

These can be plotted as contourmaps, color images, or as perspective surfaces. 这些可以作为等高线图策划,彩色图像,或称为观察表面。

Because the native GMT grid is simply a 1-D float arraywith all the metadata kept in a separate header, we pass this information via a struct GMT_GRID, whichis a container that holds both items. 因为本地GMT网格是一个简单的一维浮点数数组，它所有的元数据保存在一个单独的头,我们得到这些信息通过一个struct GMT_GRID,它是一个容器,拥有两项。 Thus, the arguments to GMT API functions that handle such GMT gridsexpect this type of variable.,参数传递给GMT API函数,处理此类GMT网格期望的这种类型的变量。

1.3.5 User data columns

struct GMT_VECTOR {

long id; /* An identification number*/一个标识号

long n_rows; /* Number of rows in each vector*/在每一个向量的行数 long n_columns; /* Number of vectors*/向量的数量

long alloc_mode; /* Determines if we may free the vectors or not*/决定我们是否释放向量 long *type; /* Array with data type for each vector*/每个向量的数组数据类型 void **data; /* Array with void pointers for each vector */每个向量的空指针数组 };

Table 1.1: Definition of the GMT_VECTOR structure used to pass user data columns. 表1.1:定义gmt向量结构用于传递用户数据列。

Programs that may wish to call GMT modules may have input data in their own particular structures.

程序可能希望调用GMT模块输入他们自己的特殊结构的数据。

Forinstance, the user’s program may have three column arrays of type float and wishes to use these as theinput source to the GMT_surface module, which normally expects a struct GMT_DATASET via fileor reference.

例如,用户的程序可能有三个列浮点数类型的数组，希望使用这些作为GMT_surface模块的输入源，它通常预计一个struct GMT_DATASET通过文件或引用。

Simply create a struct GMT_VECTOR (see section 2.3) and assign the void pointers toyour data columns and provide the required information on length and data types (see Table 1.1).

简单地创建一个GMT_VECTOR结构(见2.3节)和分配空指针,你的数据列和提供所需的信息和数

据类型的长度(见表1.1)。

By lettingthe GMT module know you are passing a data set via a struct GMT_VECTOR it will know how to readthe data properly.

通过让GMT模块知道你的一个数据集是通过一个struct GMT_VECTOR，它将知道如何正确地读取数据。

1.3.6 User data matrices

struct GMT_MATRIX {

long id; /* An identification number*/一个标识号

long n_rows; /* Number of rows in the matrix*/在矩阵的行数 long n_columns; /* Number of columns in the matrix*/在矩阵的列数 long n_layers; /* Number of layers in a 3-D matrix*/的层数3d矩阵

long registration; /*0 for gridline and 1 for pixel registration*/0和1的栅格线像素登记 long shape; /*0 = C (rows) and 1 = Fortran (cols) */0 = C(行)和1 = Fortran(关口

long dim; /*Length of dimension for row (C) or column (Fortran)*/长度维度,行(C)或列(Fortran) long alloc_mode; /* Determines if we may free the vectors or not*/如果我们可以自由决定的向量

或不是

long type; /* The matrix data type*/数据类型的矩阵

double limit[6]; /* The min and max limits on x-, y-, and z-ranges*/ min和max限制x,y,z的范围, void *data; /* Void pointer to the data matrix*/void指针数据矩阵 };

Table 1.2: Definition of the GMT_MATRIX structure used to pass a user data matrix. 表1.2:定义GMT_MATRIX结构用于传递用户数据矩阵。

Likewise, a programs may have an integer 2-D matrix in memory and wish to use that as the input grid tothe GMT_grdfilter module, which normally expects a struct GMT_GRID

via file or reference.

同样,一个项目可能会有一个整数二维矩阵在内存和希望使用,它将作为输入网格数据输入到GMT_grdfilter模块,它通常会通过文件或引用预定义一个GMT_GRIDstruct。

Asfor user vectors, we create a struct GMT_MATRIX (see section 2.3), assign its void pointer to your datacolumns and provide information on dimensions and data type (see Table 1.2).

至于用户向量,我们创建一个GMT_MATRIX struct(见2.3节),void 指针将分配到你的数据列,并提供信息维度和数据类型(见表1.2)。

Letting the GMT moduleknow you are passing a grid via a struct GMT_MATRIX it will know how to read the matrix properly.

让GMT模块知道你是通过一个网格通过一个struct GMT_MATRIX将知道如何阅读矩阵正确。

2. GMT C API 的概述

Users who wish to create their own GMT applications based on the API must make sure their program goesthrough the steps below;

用户希望创建自己的基于API的GMT应用程序必须确保他们的程序会通过下面的步骤;

details for each step will be revealed in the sections to follow.

为每个步骤的细节将显示需要遵循的部分

We have kept the APIsimple: In addition to the GMT modules,there are only 14 public functions to become familiar with. Thelayout here assumes you wish to use data in memory as input sources; if the data are simply command-linefiles then things simplify considerably.

我们保留了API的简单:除了GMT模块, 只有14个公共函数来熟悉. 这里假设您的布局希望使用内存中的数据作为输入来源, 如果数据是简单的命令行文件那么事情大大简化。

1. Initialize a new GMT session by callingGMT_Create_Session,which allocates a GMT

API controlstructure and returns a pointer to it. This pointer must be used as first argument to all subsequent GMTAPI function calls within the same session.

初始化一个新的GMT会话调用GMT_Create_Session这分配一个GMT API控制结构,并返回一个指向它。这个指针必须作为第一个参数所有后续GMT API函数调用在同一会话初始化一个新的GMT会话调用

2. For each intended call to a GMT function, several steps are involved:

对于每个必要的GMT方法的调用,涉及几个步骤:

(a) Register the input sources and register the output destination

usingGMT_Register_IO, unlessyou know you are working with a single file or standard input/output. The resources will typicallybe files, memory locations, already-opened file handles, and even process streams.

登记注册的输入源和输出目的地使用GMT_Register_IO,除非你知道你正在使用的是一个文件或标准输入/输出。资源通常是文件、内存位置,已经打开文件句柄,甚至过程流

(b) Each resource registration will generate a unique ID number. For memory resources,these numbersare then converted to unique filenames of the form “@GMTAPI@-######” that are used with GMTmodules.

每个资源登记将生成一个惟一的ID号码。对于内存资源, 这些数字都会被转化为独特文件名的形式

“@GMTAPI@-######”这将被用于用GMT模块

When GMT i/o library functions encounter such filenames they extract the ID and make aconnection to the resource registered under that ID.

当GMT i / o库函数遇到这些文件名，那么他们只需提取ID和创建一个连接在注册资源的ID下

Any number of table data or text sources will becombined into a single virtual source for GMT functions to operate on. In contrast, CPT and Gridresources are operated on individually.

任何数量的表数据或文本消息来源将会被整合到一个单一的虚拟源以便GMT函数来操作。相比之下,CPT和网格资源是单独操作。

(c) Enable data import once all registrations are complete.

(d) Read into memory all data that will be passed to GMT functions via pointers. You may choose toread everything into memory at once or process the data record-by-record (tables only).

读取到的内存中所有的数据将通过指针传递给GMT函数, 你可以选择立刻读取任何信息从内存中或处理数据记录的记录(仅表格)。

(e) Prepare the program options required and call the GMT function you wish to use.

准备需要的程序选项和调用您希望使用的GMT函数

(f) Process the results that were returned to memory via pointers rather than written to files.

处理结果并通过指针返回到内存,更优于写入文件

(g) Destroy the resources allocated by GMT functions to hold the results.

通过GMT函数销毁资源分配并保存结果

3. Repeat steps a–f as many times as your application requires. All API functions return a status codewhich is GMTAPI_OK (0) if all is well. For non-zero return values, use GMT_Report_Errortogenerate an error message.

多次重复步骤a-f若你的应用程序需要，所有API函数返回一个状态码是GMTAPI_OK(0)如果一切都好。对于非零返回值,用GMT_Report_Error来生成一个错误消息。

4. We terminate the GMT session by callingGMT_Destroy_Session.Advanced programs may be calling more than one GMT session and thus run several sessions,

perhapsconcurrently as different threads on multi-core machines. We will now discuss these steps in more detail.

我们调用GMT_Destroy_Session来终止GMT会话，好的的程序可能会调用多个GMT会话,因此运行多次会话,为不同的线程可能同时在多核机器, 现在我们将详细讨论这些步骤。

2.1 Initialize a new GMT session

Most applications will need to initialize only a single GMT session. This is true of all the standard GMTprograms since they only call one GMT module and then exit.

大多数应用程序需要初始化只使用一个GMT会话，这是真正的所有标准的GMT项目,因为他们只调用一个GMT模块,然后退出

Most user-developed GMT applications arelikely to only initialize one session even though they may call many GMT modules.

大多数用户自行开发的GMT应用程序可能只初始化一个会话,即使他们可能调用许多GMT模块

However, the GMTAPI supports any number of simultaneous sessions should the programmer wish to take advantage of it.

然而,GMT API支持同时任意数量的会话，程序员应该学会利用这点

This might be useful when you have access to several CPUs and want to spread the computing load1. In thefollowing discussion we will simplify our treatment to the use of a single session only.

当然，这可能是用于你想访问几个cpu和想分散计算负载。在下面的讨论中我们将简化我们的处理并只使用单个会话

The GMT_Create_Sessionis used to initiate the new session. GMT_Create_Session是用于启动新的会话 The full function prototype is

GMT_Create_Session (struct GMTAPI_CTRL **API, char *tag, long mode)

1However, there is no thread-support yet.没有线程支持

and you will typically call it thus:

你通常会这样调用它

GMT_LONG error, mode = GMTAPI_GMT; struct GMTAPI_CTRL *API = NULL;

error = GMT_Create_Session (&API, \

where API is a pointer to the allocated GMT API control structure. You will need to pass this pointer to allsubsequent GMT API functions.

这里的API是GMT API 控制结构的一个指针, 你将需要通过这个指针操作所有后续GMT API函数。

The key task of this initialization is to set up the GMT machinery and itsinternal variables used for map projections, plotting, etc. The initialization also allocates space for internalstructures used to register resources.

初始化的关键是建立了GMT机械及其内部变量，用于地图投影, 策划, 等。初始化也为内部结构分配空间用于注册资源等，

If you expect to call modules that also require the PSL library, then setmode to GMTAPI_GMTPSL (1); else simply pass GMTAPI_GMT (0).

如果您希望调用模块,也需要PSL库，然后设置模式GMTAPI_GMTPSL(1),否则，设置为

GMTAPI_GMT (0)

2.2 Register input or output resources

注册输入或输出资源。

When using the standard GMT programs, you specify input files on the command line or via special programoptions (e.g., -Iintensity.nc).The output of the programs are either written to standard output (which youredirect to files or other programs) or to files specified by specific program options (e.g., -Goutput.nc).

当使用标准的GMT程序,您在命令行上或通过特殊程序选项(如。,-Iintensity.nc)来指定输入文件。程序的输出要么是写入标准输出(您重定向到文件或其他程序)或文件所指定的特定程序选项(如。,-Goutput.nc)

However, the GMT API allows you to also specify input (and output) to come from (or go to) open filehandles or program memory locations. We will examine this more closely below.

然而,GMT API允许您指定输入(或输出)来自(或到)打开的文件句柄或程序的内存位置。我们将更严密地检查这些下面

Registering a resource is arequired step before attempting to import or export data other that via file options and standard input/output.

注册一个资源是一个必要的步骤，在通过文件选项和标准输入/输出导入或导出数据之前。

The basic registration machinery involves a direct or indirect call to

基本的登记器包括直接或间接调用

GMT_Register_IO (struct GMTAPI_CTRL *API, long family, long method, long geometry,void **ptr, double wesn[],long direction, void *data, long *ID)

where family specifies what kind of resource is to be registered (see Table 2.1 for list of all families),

family指定什么样的资源要注册(见表2.1为列表的所有family),

method specifies how we expect to access this resource (see Table 2.2 for recognized methods, as well asmodifiers you can add; these are listed in Table 2.3),

method指定我们期望如何访问这个资源(见表2.2为公认的方法,以及修饰符可以添加;这些都列在表2.3) geometry specifies the geometry of the data (seeTable 2.4 for recognized geometries), geometry指定数据的几何形状(见表2.4为公认的几何图形),

ptr is the address of an opaque pointer to the named resource. ptr是一个指向资源的不透明指针的地址。

ForGMT_IS_GMTGRID resources you may request to obtain a subset via the wesn array (see Table 2.5 forinformation);otherwise, pass NULL to obtain the entire grid.

对于GMT_IS_GMTGRID资源你可以要求获得通过wesn数组子集(见表2.5信息); 否则,设置为NULL以获得整个网格。

The direction indicates input or outputand is either GMT_IN (0) or GMT_OUT (1). direction指示输入或输出,要么是GMT_IN(0)或GMT_OUT(1)。 The data set is associated with the ptr. data关联于ptr

Finally, the functionreturns a unique resource ID via the ID parameter.

最后,该函数通过ID参数返回一个独特的资源ID

If registered resources are to be given as program arguments you will need to pass

them via a text stringthat represents a special file name.

如果注册资源是作为程序参数，你将需要通过一个特殊的文件名称的文本字符串来达到目的

We ensure proper formatting by using the function

我们通过使用以下函数来确保适当的格式

GMT_Encode_ID (struct GMTAPI_CTRL *API, char *filename, long ID)

which accepts the unique ID and writes the filename that you can use as argument to a program option.

它接受独特的ID，写作为一个程序选项的参数的文件名

filenamemust have enough space to hold 16 bytes. filename必须有足够的空间来容纳16字节

family GMT_IS_DATASET GMT_IS_TEXTSET GMT_IS_GMTGRID GMT_IS_CPT source points to A [multi-segment] table file A [multi-segment] text file A GMT grid file A CPT file Table 2.1: Integer constants defined for use when specifying input or output data families.整数常量定义了使用当指定的输入或输出数据的family

2.2.1 Resource initialization

资源初始化

All GMT programs dealing with (a) input or output files given on the command line or (b) defaulting to thestandard input or output streams if no files are given, must call the i/o initializer functionGMT_Init_IO

所有GMT程序处理(a)命令行上给出的输入或输出文件或(b)默认的标准输入或输出流，如果没有文件被给出，必须调用i / o的初始化函数GMT_Init_IO

method GMT_IS_FILE GMT_IS_STREAM GMT_IS_FDESC GMT_IS_COPY GMT_IS_REF GMT_IS_READONLY how to read/write data Pointer to name of a file Pointer to open file (or process) Pointer to integer file descriptor Pointer to memory to copy data from Pointer to memory to reference data from (realloc OK) Pointer to memory to read data from Table 2.2: Integer constants defined for use when specifying input or output methods.

整数常量定义了使用当指定的输入或输出method approach GMT_VIA_VECTOR GMT_VIA_MATRIX how method is modified The user’s data columns are addressed via a GMT_VECTOR structure The user’s grid is addressed via a GMT_MATRIX structure Table 2.3: Integer constants defined for use when user data forms are involved.

整数常量定义了使用当用户数据形式参与

These are to be added to themethod used when registering the resource.

这些都是添加到方法注册时使用的资源

once for each direction (input and output). For input it will determine how many input sources have alreadybeen registered.

一旦每个direction (输入和输出)确定。对于输入它将确定有多少输入源已经被注册

If none are present it will scan the program arguments for any filenames given on thecommand line, and register these input resources.

如果为空,它将扫描程序的参数对于任何命令行上给出的文件名,并注册这些输入资源

Finally, if we still have found no input sources we willspecify the standard input stream as the single input source.

最后,如果我们还没有发现任何输入源我们将指定标准输入流作为单个输入资源

Likewise, for output: If none has been registeredwe specify the standard output stream as the output destination.

同样,对于输出:如果没有注册我们指定标准输出流作为输出目的地

Only one output destination is allowed to beactive when the module writes data.

写数据时只有一个输出资源是允许在活跃的模块中

The prototype for this function is

GMT_Init_IO (struct GMTAPI_CTRL *API, long family, long geometry, long direction, long mode, struct GMT_OPTION *head)

where family specifies what kind of resource is to be registered, family指定什么样的资源要注册,

geometry specifies the geometry ofthe data, geometry指定几何形状的数据

the direction is either GMT_IN or GMT_OUT, direction是GMT_IN or GMT_OUT中的一个

the mode is a bit flag that determines what wedo if no resources have been registered. mode是一个位标志,决定了我们所做的,如果没有资源已经被注册

Here, 1 (GMT_REG_FILES_IF_NONE) means “add commandline (option) files if none have been registered already” 添加命令行(选项)文件如果没有注册,

2 (GMT_REG_FILES_ALWAYS) means “alwaysadd any command line files”总是添加任何

命令行文件, 4 (GMT_REG_STD_IF_NONE) means “add std* if no other input/outputhave

been specified”如果没有其他输入/输出已经被指定则添加std *,

and 8 (GMT_REG_STD_ALWAYS) means “总是添加std *即使资源已经被注册”. The standard behavior is 5 (GMT_REG_DEFAULT)标准的行为是这.

Finally, head is the first elementof the option structure list.

最后, head是选项列表结构的第一个元素

Since GMT needs to know how you plan to access this resource you need topass one of the bit-flags

GMT需要知道你计划如何访问这个资源，这将需要一个位标志

GMT_BY_REC(which will initialize the machinery for record-by-record i/o这将初始化机械为

纪录记录i / o) orGMT_BY_SET(which expects the machinery to return the entire data set

back to the calling program这预计项目会一次性使用整个数据源在调用程序的时候

). Thisis easiest to accomplished by a bit-wise OR operation, i.e., by passing method | GMT_BY_REC.这是最容易完成通过OR操作符，如：通过传递方法|GMT_BY_REC

Many programs will register an export location to hold the results of a GMT function (say, a filteredgrid), but then wish to use that location as an input resource in the next step. 许多程序将注册一个出口位置来保存一个GMT函数的结果(比如,一个过滤网格),但是然后希望使用该位置作为输入资源在下一步。

This is accomplished byfirst un-registering the export resource and then re-registering the same array location as an import source,thereby changing the direction of the data set.

这是完成通过第一次未注册输出资源 ，然后重注册同样的数组位置作为一个输入资源，改变数据设置的方向。

2.2.2 Dimension parameters for user column vectors

Dimension参数被用于用户列向量

We refer to Table 1.1. The type array must hold the data type of each data column in the user’s program.

我们参考表1.1。数组类型必须持有每个数据列的数据类型在用户的程序中

All types other than GMTAPI_DOUBLE will need to be converted internally in GMT to double, thuspossibly increasing memory requirements.

所有类型除了GMTAPI_DOUBLE需要在GMT内部转换为double,从而可能增加内存需求 If the type is GMTAPI_DOUBLE then GMT will be able touse the column directly by reference.

如果类型是GMTAPI_DOUBLE那么GMT将能够直接引用列。

The n_columns and n_rows parameters inform of the number ofvectors and their common length.

这个n列和n行参数将通知向量的数量和它们共同的长度。

These are known in the case of input but may be unknowable in the caseof output; if so you may pass 0 for these values and set alloc_mode to 1; this will make sure GMT willallocate the necessary memory at the location you specify.

这些都是已知的情况下的输入但可能不可知的情况的下输出;如果是这样的话,你可以将这些值设为0，但设置alloc_mode为1,这种分配方式将确保GMT将在您指定的位置分配必要的内存。

geometry

description

Not a geographic item Multi-dimensional point data

Geographic or Cartesian line segments Geographic or Cartesian closed polygons 2-D gridded surface

GMT_IS_TEXT GMT_IS_POINT GMT_IS_LINE

GMT_IS_POLYGON GMT_IS_SURFACE

Table 2.4: Integer constants defined to register different geometries. 整数常量定义注册不同几何图形数据

Index 0 XLO 1 XHI 2 YLO

content

x_min(west) boundary of grid subset x_max(east) boundary of grid subset y_min(south) boundary of grid subset

3 YHI y_max(north) boundary of grid subset

Table 2.5: Domain boundaries (wesn) used when selecting subsets of grids. 域边界(wesn)时选择使用网格子集

2.2.3 Dimension parameters for user 2-D table arrays

Dimension参数为2 d表数组的用户

We refer to Table 1.2. The type parameter specifies the data type used for the array in the user’s program.

我们参考表1.2。在用户的程序中类型参数指定数据类型被用于数组。

All types other than GMTAPI_FLOAT will need to be converted internally in GMT to float, thus possiblyincreasing memory requirements.

所有类型除了GMTAPI_FLOAT需要在GMT内部转换为float,从而可能增加内存需求。 If the type is GMTAPI_FLOAT then GMT may be able to use the matrixdirectly. 如果类型是GMTAPI_FLOAT然后GMT可以使用矩阵直接。

The n_rows and n_columns parameters simply specify the dimensions of the matrix. 参数n行和n列简单地指定矩阵的维数。

Theseare known in the case of input but may be unknowable in the case of output; if so you may pass 0 for thesevalues and set alloc_mode to 1; this will make sure GMT will allocate the necessary memory at thelocation you specify.

这些都是已知的情况下的输入但可能不可知的情况下的输出;如果是这样的话,你可以不将这些值设为0，但设置alloc_mode为1,这种分配方式将确保GMT将在您指定的位置分配必要的记忆 Fortran users will instead have to specify a size large enough to hold the anticipatedoutput data.

Fortran用户将必须指定一个规模大得足以容纳预期的输出数据。

The registration and limit gives the grid registration and domain. 注册和限制给网格注册和域。

Finally, use the dimentry to indicate if the memory matrix has a dimension that exceeds that of the leading row (or column)dimension.

最后,使用昏暗的条目来表示如果内存矩阵有一个超过先前的行(或列)尺寸维度,

Note: For GMT_IS_TEXTSET the user matrix is expected to be a 2-D character array with rowlength by dim] but we only consider the first n_columns characters.

注意:对于GMT_IS_TEXTSET用户矩阵预计将是一个带有行长度2 d字符数组但暗淡的，但我们只考虑第n列字符

For data grids you will also need tospecify the registration (see the GMT Cookbook and Reference, Appendix B for description of thetwo forms of registration) and data domain limits.

对于网格数据您还需要指定注册(参见“GMT食谱和参考,附录B为描述的两种形式的注册)和数据域的限制

2.3 Create empty resources

If your session needs to build and populate GMT resources in ways that do not depend on external resources(files, memory locations, etc.), then you can obtain a “blank slate” of certain GMT structures.

如果你的会话需要构建和填充GMT资源的方式,不依赖于外部资源(文件、内存位置,等等),那么您可以获得一个“空白”的特定的GMT结构。

This is donewith the GMT_Create_Datafunction, whose prototype is . 用GMT_Create_Data函数可以完成,

GMT_Create_Data (struct GMTAPI_CTRL *API, long family, long par[], void **data, long *ID)

where data returns the address of an opaque pointer to the allocated resource. data返回一个分配资源的不透明指针的地址。 Pass family as one of

GMT_IS_GMTGRID, GMT_IS_DATASET, or GMT_IS_CPT, or the special families(或特殊的families)GMT_IS_VECTORor GMT_IS_MATRIX when handling user data(当处理用户数据). Depending on the data type chosen you may need to passadditional parameters via the par array, 根据数据类型，通过par数组选择你可能需要设置的额外的参数, as indicated below: 标示的意义：

1). GMT_IS_GMTGRID: An empty GMT_GRID structure with a header is allocated; the data array isNULL. The par argument is not used.

一个空的被分配一个头的GMT_GRID结构;数据数组为空。不使用的par参数

2). GMT_IS_DATASET: An empty GMT_DATASET structure consisting of par[0] tables, each withpar[1] segments, each with par[2] columns, all with par[3] records, is allocated. 一个空的GMT_DATASET结构被下面的组成，par[0]tables,每个都有par[1]segments,每个都有par[2]columns,所有par[3]records,被分配

3). GMT_IS_TEXTSET: An empty GMT_TEXTSET structure consisting of par[0] tables, each withpar[1] segments, all with par[2] text record, is allocated.

一个空的GMT_TEXTSET结构组成的par[0]tables,每个都有par[1]segments,所有都有par[2]text record,被分配。

4). GMT_IS_CPT : An empty GMT_PALETTE structure with par[0] palette entries is allocated.

一个空的gmt调色板结构与par[0]调色板条目被分配。

5). GMT_IS_VECTOR: An empty GMT_VECTOR structure with par[0] column entries is allocated. 一个空的g GMT_VECTOR结构与par[0]column ent里斯被分配 6). GMT_IS_MATRIX: An empty GMT_VECTOR structure is allocated. 一个空的GMT_VECTOR结构被分配。

In all cases the data entries are initialized to zero (NULL in the case of text). 在所有情况下数据条目将被初始化为0(NULL对于文本)。

The data pointer is expectedto point to NULL when calling the function. 数据指针将指向空当调用该函数。

Note: if you need to duplicate an existing data structure thesimplest way is to use GMT_Get_Data after registering the original structure as the data source.

注意:如果你需要复制现有的数据结构的最简单的方法是使用GMT_Get_Data在登记原结构数据源后。

2.4 Import Data

If your main program needs to read any of the four recognized data types (CPT files, data tables, text tables,or GMT grids) you will use the GMT_Get_Data.

如果你的主程序需要读任何的四个公认的数据类型(CPT文件、数据表、文本表,或GMT网格)您将使用GMT_Get_Data。

In the case of data and text tables, you may also considerthe GMT_Get_Recordfunction. 对于数据和文本表,你也可以考虑GMT_Get_Record功能。

As a general rule, your program organization will simplify if you canread the entire resource into memory with GMT_Get_Data.

一般来说,如果你用GMT_Get_Data阅读整个资源到内存，那么你的程序组织将变得简化。 However, if this leads to unacceptable wasteof memory or if the program logic is particularly simple, it may be better to obtain one data record at thetime via GMT_Get_Record.

然而,如果这导致不可接受的浪费内存或如果程序逻辑是特别简单,它或许能更好地获得一个数据记录当时通过GMT_Get_Record。

Both of these input functions takes a parameter called mode. 这两种输入函数都接受一个参数称为mode。

The mode parameter generally takeson different meanings for the different data types and will be discussed below.

mode参数通常需要在含义不同的不同数据类型使用,将在下面讨论。

However, one bit settingis common to all types: By default, you are only allowed to read a data source once; the source isthen flagged as having been read and subsequent attempts to read from the same source will quietly beignored.

然而,一位设置是常见的所有类型:默认情况下,你一次只能读一个数据源;源会被标记为已读，而随后的尝试读取相同的源会被悄悄地忽略了。

In the unlikely event you need to re-read a source you can override this default behavior by addingGMT_IO_RESET to your mode parameter.

在不太可能的情况下你需要重读一个源可以覆盖这个默认行为通过添加GMT_IO_RESET作为你的模式参数。

Note that this override does not apply to sources that are streamsor file handles. 注意,这个覆盖并不适用于源,流或文件句柄。

2.4.1 Enable Data Import

Once all input resources have been registered, we signal the API that we are done with the registration phaseand are ready to start the actual data import.

一旦所有输入资源已经注册,我们发出API信号,我们已经完成了登记阶段和已经准备好开始实际的数据导入。

We do so by calling GMT_Begin_IO. 我们通过调用GMT_Begin_IO。

This function enablesdata import and prepares the registered sources for the upcoming import.

这个功能使数据导入和准备注册来源为即将到来的进口。 The prototype is

GMT_Begin_IO (struct GMTAPI_CTRL *API, long family, long direction, long mode) where family specifies what kind of resources is about to be read or written (see Table 2.1 for list of allfamilies).

family指定什么样的资源将被读或写(见表2.1的所有家庭的列表)。

The direction is either GMT_IN or GMT_out, and for import we obviously use GMT_IN.direction是GMT_IN或GMT_out,我们显然用GMT_IN。

The mode parameter controls how the resources will be accessed: Select GMT_BY_SET to read entiretables, CPT files, or grids, and use GMT_BY_REC when you need to access a dataset record by record.

mode参数控制资源访问:选择GMT_BY_SET阅读整个表,CPT文件,或网格,并使用GMT_BY_REC

当你需要访问一个数据集记录的记录。

Thelatter selection involves determining which is the first input file and setting up procedures for skipping to thenext input file in a virtual data set. No input functions will be able to read any data before GMT_Begin_IOhas been called.

后者的选择涉及确定哪些是第一个输入文件和设置程序跳转到下一个输入文件在一个虚拟数据集。没有输入函数将能够阅读任何数据在GMT_Begin_IO之前。

As you might guess, there is a companion GMT_End_IOfunction that disables dataaccess.

你可能已经猜到了,有一个相对应的GMT_End_IO功能,禁用数据访问。

You can use these several times to switch modes between registering data resources, doing theimporting/exporting, and disabling further data access, perhaps to do more registration.

您可以使用这些几次开关模式注册数据资源之间,做进口/出口,禁用进一步数据访问,也许是为了做更多的注册。

We will discussGMT_End_IOonce we are done with the data import. 我们将讨论GMT_End_IO一旦我们完成了数据导入。

2.4.2 Import a data set

If your main program needs to import any of the four recognized data types (CPT table, data table, text tableor GMT grid) you will use the GMT_Get_Datafunction.

如果你的主程序需要输入任何四个公认的数据类型(CPT表、数据表、文本表或GMT网格)您将使用GMT_Get_Data函数。

Because of the similarities of these four importfunctions we use an generic form:

因为这四个导入功能的相似性,我们使用一个通用的形式:

GMT_Get_Data (struct GMTAPI_CTRL *API, long family, long method, long geometry, double wesn[], long mode, void **input, void **data)

where data can be the address of an opaque pointer to any of the four structures discussed above.

data可以是一个不透明的地址指针指向任何四个结构上面所讨论的。 Most ofthese arguments have been discussed earlier. 大多数这些参数在前面已经讨论过。

This function can be called in three different situations: 这个函数可以在三个不同的情况下被调用:

1. If you have a single source (filename, stream pointer, etc.) you can call GMT_Get_Datadirectly;there is no need to first register the source with GMT_Register_IOor gather the sources withGMT_Init_IO.

如果你有一个单一的资源(文件名,流指针,等等。)你可以直接调用GMT_Get_Data;不需要预先用GMT_Register_IO注册资源或初始化GMT_Init_IO资源.

2. If you want to specify stdin as source then use input as NULL. 如果你想指定stdin作为资源那么使input为NULL

3. If you already registered all available sources with GMT_Init_IOthen you pass geometry = 0.

如果你已经用GMT_Init_IO注册的所有可用的资源那么你pass geometry = 0。

In all cases, cast the address of the actual pointer to your CPT table, grid, or data set to void ** whencalling GMT_Get_Data.

在所有的情况下,把实际指针的地址指向CPT表、网格,或数据设置为void * *当调用GMT_Get_Data时。

Space will be allocated to hold the results, if needed. 如果需要的话，可分配用于保存结果的内存空间,。

mode parameter takeson different meanings for the different data types. mode参数在不同的数据类型下呈现不同的含义。

1）.CPT table : mode are bit-flags that controls how the CPT file’s back-, fore-, and NaN-colors should beinitialized.

CPT表:mode是位标志,控制CPT文件的前景、背景或者无颜色将被初始化。

Select 0 to read the CPT file’s back-, fore-, and NaN-colors, 2 to replace these with the GMTdefault values, or 4 to replace them with the color tables entries for highest and lowest value. 选择0将阅读CPT文件前景、背景或者无颜色,2来取代这些与GMT的默认值,或4来取代它们与颜色表条目最高及最低的值。 2）.Data table : mode is not used. 3）.Text table : mode is not used.

4）.GMT grid : Here mode determines how we read the grid: To get the entire grid and its header,

GMT grid：这里mode决定了我们怎样读网格:取得整个网格和它的头,

pass GMT_GRID_ALL.通过gmt网格所有。 However, if you need to extract a sub-region you must first get the headeronly by passing GMT_GRID_HEADER, then use the header structure attributes x_min, x_max,y_min, and y_max to specify a subset via wesn, and then call GMT_Get_Dataa second time,with mode = GMT_GRID_DATA and passing your

wesn array.

然而,如果你需要提取一个次区域你必须首先得到头只有通过GMT_GRID_HEADER,然后使用头结构属性x_min, x_max,y_min, and y_max指定wesn的一个子集,然后调用GMT_Get_Data一次,mode = GMT_GRID_DATA和传递你的wesn数组。

In the event your data array shouldbe allocated to hold both the real and imaginary parts of a complex data set you must add eitherGMT_GRID_COMPLEX_REAL or GMT_GRID_COMPLEX_IMAG to mode so as to allow for theextra space and to position the input values correctly.

如果您的数据数组应该分配给持有和实数的虚数的一个复杂的数据集必须添加

GMT_GRID_COMPLEX_REAL或GMT_GRID_COMPLEX_IMAG到mode以允许额外的空间和位置正确地输入值。

2.4.3 Importing a data record

If your program must read data table records one-by-one you will instead use the 如果你的程序必须一个一个地读取数据表记录你将转而使用 GMT_Get_Recordfunction; the prototype is

GMT_Get_Record (struct GMTAPI_CTRL *API, long mode, void **data)

where data is usually the address of a pointer to a double array with the current row; You need to allocateany memory for this array if the method used to register the source was GMT_IS_ARRAY; otherwise itpoints to memory internal to GMT.

这里的data通常是一个指向当前double数组的地址；你需要分配内存对于这个数组如果方法用于注册源是GMT_IS_ARRAY;否则它指向内存内部GMT。

Normally (mode == GMT_READ_DOUBLE or 0), we return a pointer to the double array.

通常(mode = = GMT_READ_DOUBLE或0),我们返回double数组指针。

To readtext record, supply instead mode == GMT_READ_TEXT or 1) and we instead return a pointer to the textrecord.

阅读文本记录,供应相反mode = = GMT_READ_TEXT或1)和代替的是返回一个指针到文本记录。 However, if you have input records that mixes organized floating-point columns with text itemsyou could pass mode == GMT_READ_MIXED (2). Then, GMT will attempt to extract the floating-pointvalues; you can still access the record string, as discussed below.

然而,如果你有输入记录,那将混合有组织的浮点列与文本项,您可以通过mode = =

GMT_READ_MIXED(2)。然后,GMT将试图提取浮点值;您仍然可以访问记录的字符串,如下面所讨论的。

Finally, if your application needs to benotified when GMT closes one file and opens another, add GMT_FILE_BREAK to mode and check forthe return code

GMT_IO_NEXT_FILE (By default, we treat the combination of many input files as onevirtual file).

最后,如果您的应用程序需要的时候通知GMT关闭一个文件并打开另一个,添加

GMT_FILE_BREAK到mode并检查返回代码GMT_IO_NEXT_FILE(默认情况下,我们将结合很多输入文件作为一个虚拟文件)。

Using GMT_Get_Recordrequires you to first initialize the source(s) withGMT_Init_IO. 使用GMT_Get_Record需要您首先初始化资源(s)用GMT_Init_IO。

This function returns status codes that your program will need to examine to take appropriate response:

GMT_IO_TABLE_HEADER: We read a table header; to examine this text string (if working with ASCIIdata), see API->GMT->current.io.segment_header. 我们读表头;检查这个文本字符串(如果使用ASCII数据),

GMT_IO_SEGMENT_HEADER: We read a segment header; to examine this text string (if workingwith ASCII data), see API->GMT->current.io.current_record.我们读一段标题;检查这个文本字符串(如果使用ASCII数据)

GMT_IO_MISMATCH: The number of columns read is less than what the program expected.列数读不到什么程序预期。

GMT_IO_EOF: We have reached the end of the source.我们已到达资源结束。

GMT_IO_NAN: The record has NaNs in fields that we do not allow to have NaNs, and hence, it is a badrecord (see GMT’s IO_NAN_RECORD defaults). NaNs记录在字段,我们不允许有NaNs,因此,它是一个糟糕的记录(参见GMT的IO_NAN_RECORD默认设置)。

GMT_IO_GAP: A user-defined data gap has been encountered (see GMT’s -g option)Developers who need to import data on a record-by-record basis should consult the source code of, say,blockmean_func.c or pstext_func.c.

一个用户定义的数据差距已经遇到了(参见GMT的- g选项)开发人员需要导入的数据记录,记录的基础应该咨询的源代码,说,blockmean_func.c或pstext_func.c。

2.4.4 Disable Data Import

Once all input resources have been imported we disable further input to prevent accidental reading fromoccurring (due to poor program structure, bugs, etc.).

一旦所有输入资源已经输入，我们将禁用进一步输入防止意外读取的发生(由于贫穷的程序结构、

缺陷等等)。

We do so by calling GMT_End_IO. 我们通过调用GMT_End_IO。

This functiondisables further data import这个函数禁用进一步数据导入 and its prototype is

GMT_End_IO (struct GMTAPI_CTRL *API, long direction, long mode) and we specify direction = GMT_IN , At the moment, mode is not used. 和我们指定direction = GMT_IN,目前, mode是不被应用的。

This call will also reallocateany arrays used into their proper lengths. 这个调用也将重新分配任何数组使用到适当的长度。

2.5 Prepare program options

准备程序选项

All GMT modules are available in two different flavors. 所有GMT模块可以用两个不同的风格来使用。

The two versions differ in how the commandoptions are passed to the module: 这两个命令选项的差异表现在命令选项传递给模块:

GMT_module_cmd : Expects an array of text options and a count of how many options are passed (i.e.,the argc, argv[] model). 预计一组文本选项和一个多少选项数目传递

GMT_module : Expects a pointer to a doubly-linked list of objects with individual options for the currentprogram. 预计一个指向一个双链接列表的对象与当前的程序的独特选择。

Here, GMT_module stands for any of the GMT modules, such as GMT_psxy.

在这里,GMT模块代表任何GMT模块,如GMT_psxy。

There are no restrictions onthe use of these modules and the developer may choose either form or mix and match depending on howoptions are to be assembled. 没有限制使用这些模块,开发人员可以选择要么形式或混合和匹配取决于选项怎样组装。

In the implementation, GMT_module_cmd is simply a wrapper that createsthe option list from the arguments and then calls GMT_module.

在这个实现中, GMT_module_cmd是一个简单的包装器,它创建选项列表的从参数中,然后调用GMT_module。

2.5.1 Set program options via text arguments

设置程序选项同过文本参数

The module prototype for the text-based interface is 该模块的原型基于文本的界面

GMT_module_cmd (struct GMTAPI_CTRL *API, long argc, char *argv[])

In addition to the API control structure pointer, we expect an array argv of character strings that eachholds a single command line argument

除了API控制结构的指针,我们期待一个字符串的数组argv,每个拥有一个命令行参数

(e.g., “-R120:30/134:45/8S/3N”) as well as the count argc of howmany options are passed.以及选项个数。 This, of course, is almost exactly how the stand-alone GMT programs are called(and reflects how they themselves are activated internally). 当然,这几乎是完全独立的GMT如何程序被调用(和反映出他们自己内部怎么被激活)。

Depending on how your program obtains thenecessary options you may find that this interface offers all you need.

这取决于你的程序获得你可能会发现的需要的选项,,这个接口提供了你所需要的。

Note: if argc == 0 then argv willbe further examined to see if it contains several options within a single string.

注意:如果argc == 0然后argv会进一步检查,看它是否包含几个选项在单个字符串。

If so we will break these intoseparate options. 如果我们将它们分成单独的选项。 This is useful if you wish to pass a single string such as “-R120:30/134:45/8S/3N -JM6imydata.txt -Sc0.2c”.这是有用的,如果你想通过一个字符串,如…

2.5.2 Set program options via linked structures

设置程序选项通过链接结构

The second, linked-list interface allows developers using higher-level programming languages to passall command options via a pointer to a NULL-terminated, doubly-linked list of option structures, eachcontaining information about a single option.

第二个,链表接口允许开发人员使用更高级的编程语言来传递所有命令选项通过一个指向一个以null结尾,双链接列表的选项包含信息的结构,每个包含了单个选项信息。 The prototype for this interface is

GMT_module (struct GMTAPI_CTRL *API, struct GMT_OPTIONS *options) Here, instead of text arguments we pass the pointer to the linked list of options mentioned above. 在这里,代替文本参数我们传递的指针与上面提到的选项链接列表。

Usingthis interface can be more involved since you need to generate the linked list of program options; however,utility functions exist to simplify its use.

使用这个接口可以更多的参与,因为您需要生成链接列表的项目选项;然而,实用函数存在简化它

的使用。

This interface is intended for programs whose internal workings arebetter suited to generate such arguments.

此接口用于程序的内部工作方式更适合生成这样的争论。

The order in the list is not important as GMT will sort it internallyaccording to need. 列表中的顺序并不重要,因为它在内部GMT将会根据需要排序。 The option structure is defined in Table 2.6.

struct GMT_OPTION { char option; char *arg;

/* Single character of the option (e.g.,’G’ for -G */ /* String pointer with arguments (NULL if not used) */ /* Pointer to next option (NULL for last option) */ /* Pointer to previous option (NULL for first option) */

struct GMT_OPTION *next; struct GMT_OPTION *prev; };

Txable 2.6: Definition of the structure used to hold a single program option.

2.5.3 Convert between text and linked structures

文本和链接结构的转换

To assist programmers there are also two convenience functions that allow you to convert between the twoargument formats.

协助程序员也有两个方便的功能,允许你把这两个参数格式之间转换 They are

GMT_Create_Options (struct GMTAPI_CTRL *API, long argc,void *args, struct GMT_OPTIONS **list)

This function accepts your array of text arguments (cast via a void pointer), allocates the necessary space,performs the conversion, and returns the address to a pointer to the head of the linked list of programoptions.

这个函数接受你的文本参数数组(cast通过一个空指针),分配必要的空间,执行转换,并返回一个指向的地址头部的链表的程序的选项。

This may now be passed to the relevant GMT_module. 现在可能会传递给相关gmt模块。

Note that if your list of text argumentswere obtained from a C main() function then argv[0] will contain the name of the calling program.

注意,如果你的文本参数列表取自一个C main()函数然后argv[0]将包含调用程序的名称。 To avoid passing this as a file name option, call GMT_Create_Optionswith argc-1 and argv+1.

避免将这作为一个文件名选项,调用GMT_Create_Options用argc-1或argv + 1。

If,you wish to pass a single text string with multiple options (in lieu of an array of text strings), then pass arg= 0.

如果你想通过一个文本字符串与多个选项(代替文本字符串的数组),然后通过arg = 0。 When no longer needed you can remove the entire list by calling当不再需要你可以删除整个列表通过调用

GMT_Destroy_Options (struct GMTAPI_CTRL *API, struct GMT_OPTION **list) The inverse function prototype is逆函数原型

GMT_Create_Args (struct GMTAPI_CTRL *API, long *argc, char **argv[], struct GMT_OPTIONS *list)

which allocates space for the text strings and performs the conversion; it passes back the count of thearguments and a pointer to the text array. 它分配空间的文本字符串并执行转换,它传回的计数参数和一个指针数组的文本。

Note that argv[0] will not contain the name of the program asis the case the arguments presented by a C main() function. 注意argv[0]不会包含的程序的名称作为参数的情况提出了一个C main()函数。

When you no longer have any use for the textarray,当你不再有任何使用文本数组, call

GMT_Destroy_Args (struct GMTAPI_CTRL *API, long argc, char *argv[]) to deallocate the space used. 来解除分配使用的空间。

Finally, to convert the linked list of option structures to a single text stringcommand,最后,将链接列表的选项结构到一个文本字符串命令, use

GMT_Create_Cmd (struct GMTAPI_CTRL *API, char **cmd, struct GMT_OPTION **list) to deallocate the space used. 来解除分配使用的空间。

Developers who plan to import and export GMT shell scripts might find itconvenient to use these functions.开发者计划进出口GMT shell脚本可能会发现可以很方便地使用这些功能。

2.5.4 Manage the linked list of options

Several additional utility functions are available for programmers who wish to manipulate program optionstructures within their own programs. These allow you to create new option structures, append them to thelinked list, replace existing options with new values, find a particular option, and remove options from thelist.

//有几个额外的方法可以用来操作自己的程序中的选项，它们可以新建、添加、替换、移除、查找。

Note: The order in which the options appear in the linked list is of no consequence to

GMT˙Internally,选择的顺序出现在链表都是不重要的,GMT˙在内部

GMT will sort and process the options in the manner required. Externally, you are free to maintain your ownorder.

//在manner required GMT会自己整理和处理选项，在外部，你可以自由的管理你的顺序，外部,你也可以保持自己的订单

Make a new option structureGMT_Make_Optionwill allocate a new option structure, assign it values given the option and argparameter (pass NULL if there is no argument for this option), and returns the pointer option that pointsto the allocated structure. The prototype is使一个新选项结构gmt使选项将分配一个新选项结构, 它值分配给该选项和参数的参数(通过NULL如果没有理由这个选项),并返回指针选项,指向分配结构。

//创建一个新的选项结构GMT_Make_Option，将指定一个新的选项结构，同时分配它的值，给出选项和参数(若无参数则为NULL)，返回一个指向该结构的指针，

GMT_Make_Option (struct GMTAPI_CTRL *API, char option, char *arg, struct GMT_OPTION **option)

Should memory allocation fail the function will print an error message and return an error code (optionwill then be NULL).

//当内存分配错误时将返回一个错误的消息，和一个错误的指针(选项将变成NULL)； Append an option to the linked list，添加

GMT_Append_Option will append the specified option to the end of the doubly-linked list.

//GMT_Append_Option 将添加一个指定的选项在列表的最后 Theprototype is

GMT_Append_Option (struct GMTAPI_CTRL *API, struct GMT_OPTION *option, struct GMT_OPTION **list)

An error will be reported if the list is empty (NULL). //当列表为空时将出错，

Find an option in the linked list

//查找

GMT_Find_Option will return a pointer ptr to the first option in the linked list starting at list whoseoption character equals option. If not found we return NULL.

//GMT_Find_Option 将返回一个列表中第一个与查找对象相同的指针，否则为NULL， The prototype is

GMT_Find_Option (struct GMTAPI_CTRL *API, char option, struct GMT_OPTION *list, struct GMT_OPTION **ptr)

If you need to look for multiple occurrences of a certain option you will need to call GMT_Find_Optionagain, passing the option following the previously found option as the list entry, i.e.,如果你需要寻找多次出现某种选择你需要再次调用gmt找到选项,通过选择以下先前发现选项的列表条目,即 list = *ptr->next;

Update an existing option in the list//更新一个存在列表中的选项

GMT_Update_Optionwill first determine if option exists; if so it will delete it. Then, it will make anew option from the arguments and append it to the end of the linked list. //GMT_Update_Option将先检查选项是否存在，若存在则先删除，然后创建一个新的，再添加到列表的最后， The prototype is

long GMT_Update_Option (struct GMTAPI_CTRL *API, char option, char *arg, struct GMT_OPTION *list)

An error will be reported if (a) list is NULL or (b) the option is not found. //未找到选项或者列表为空将出错。

Delete an existing option in the linked list //删除

You may use GMT_Delete_Optionto remove option from the linked list. //使用GMT_Delete_Option从列表中移除一个选项 The prototype is

long GMT_Delete_Option (struct GMTAPI_CTRL *API,struct GMT_OPTION *current) We return an error if the option is not found in the list. //未找到选项将出错，

Note: Only the first occurrence of the specifiedoption will be deleted. If you need to delete all such options you will need to call this function in a loopuntil it returns a non-zero status.

//注意：只会删除列表中第一个符合条件的选项，要全删则需循环调用该方法。

Specify a file via a linked optionTo specify an input file name via an option, simply use can be used toexplicitly indicate an output file.

In order to append to an existing file, use >>.同样,可以使用>来显式地指示一个输出文件。 //为了在已存在的文件中添加内容则用 >> 符号

For example the following

command would read from file.A and append to file.B: gmtconvert ->file.B

These options also work on the command line but usually one would have to escape the special charactersas they are used for file redirection.这些选项在命令行上也工作,但通常人们会为了躲避特殊字符<和>作为他们用于文件重定向。

2.5.5 Parsing GMT common options

While all the main GMT modules have their own specific option parser, we also provide a general parserthat only examines the common GMT options such as -R, -J, -V, //当所有的主要GMT单元(psxy等)都有了它们自己特定的解析器，我们也要提供一些简单的解析器，它们仅仅用来检查GMT命令选项中的类似-R，-J的元素 etc. The prototype of this parser is

long GMT_Parse_Common (struct GMTAPI_CTRL *API, struct GMT_OPTION *list) An error will be reported if any of the common GMT options fail to parse. //解析失败将会报告错误

All other options, includingfile names, will be silently ignored. The parsing will update the internal GMT information structure thataffects program operations.

//所有其他选项，包括文件名，将被忽略。解析器会更新GMT内部信息结构，这将会影响程序的运行。

2.6 Calling a GMT module

//调用GMT单元

Given your linked list of program options (or text array) and possibly some registered

resources, you cannow call the required GMT module using one of the two flavors discussed in section 2.5. 鉴于你的链接列表的项目选项(或文本数组)和可能的一些注册资源, //给出选项列表(或者文字数组)和注册的资源，你就能 用2.5中的两种方法调用GMT单元， All modules returnan error or status code that your program should consider before processing the results.

//所有的单元都会返回错误或者状态，

2.7 Exporting Data

//输出数据

If your program needs to write any of the four recognized data types (CPT files, data tables, text tables,or GMT grids) you can use the GMT_Put_Data. //如果你的程序需要写四种数据中的任何一种，你可以调用GMT_Put_Data。

In the case of data tables, you may also consider theGMT_Put_Recordfunction. As a general rule, your program organization may simplify if you canwrite the export the entire resource with GMT_Put_Data.对于数据表,你也可以考虑gmt将记录功能。作为一般规则,你的程序组织可以简化如果您可以编写导出整个资源与gmt将数据。

//当输出data tables 时，你可以考虑下GMT_Put_Record 方法，一般来说，为了程序简单化，都是使用GMT_Put_Data来输出数据

However, if the program logic is simple oralready involves using GMT_Get_Record, it may be better to export one data record at the time viaGMT_Put_Record.然而,如果程序逻辑是简单的或已经涉及到使用gmt得到记录,它可能是更好的出口一个数据记录当时通过gmt将记录。

//不管怎样，当你的程序逻辑简单或者已经用到了GMT_Get_Record方法，那么使用

GMT_Put_Record输出数据将会更简单一些

Both of these output functions takes a parameter called mode. The mode parameter generally takeson different meanings for the different data types and will be discussed below.这两种输出函数接受一个参数称为mode。mode参数通常需要在不同的含义为不同的数据类型,将在下面讨论。

//两种方法都带了参数，不同的数据，参数的含义也不相同。

However, one bit settingis common to all types: By default, you are only allowed to write a data resource once; the resource isthen flagged to have been written and subsequent attempts to write from the same resource will quietly beignored. //然而,一位设置是常见的所有类型:默认情况下，你一次只能写一个数据资源；资源然后标记所被写,随后试图写相同的资源会被悄悄地忽略了。

In the unlikely event you need to re-write a resource you can override this default behavior byadding GMT_IO_RESET to your mode parameter.

//一般你不需要重写资源文件，你可以覆盖默认的行为通过添加GMT_IO_RESET在你的mode参数，

2.7.1 Enable Data Export

Similar to the data import procedures, once all output destinations have been

registered, we signal the APIthat we are done with the registration phase and are ready to start the actual data export. 类似于数据导入程序,一旦所有输出目的地已经注册,我们信号API,我们已经完成了登记阶段和已经准备好开始实际的数据导出。

//类似数据输入，当所有的输出数据都被注册我们将会发出消息通知API已完成注册和开始数据输出

本文来源：https://www.bwwdw.com/article/menr.html