#include "gmtmap.h" int gmtmap_open(void **handle) int gmtmap_select(void *handle, char *types, char *resolution, double bb_lonwest, double bb_loneast, double bb_latsouth, double bb_latnorth) int gmtmap_nextseg(void *handle, int *npts, int *bufsize, float **lon, float **lat, char *type, int *level)
A gmtmap object must first be created and initialized with a call to gmtmap_open, which returns a pointer to the object in handle. The new object is malloc'ed if the input handle value is NULL and the object is reused otherwise.
After opening the gmtmap object, a set of map coordinates can be selected with a call to gmtmap_select. One or more map types (for this case either political or river) and map levels (a map level refers to the level of detail so that, for instance, level 1 political boundaries refer to national boundaries whereas level 2 refer to state/provence boundaries) can be specified in the types string which must be one to four whitespace delimited type-levelbitmap specifications in the form "<type1>:<levelbitmap1> [<type2>:<levelbitmap2> [...]]". The <typeX> specifications must be one of "p", for political boundaries, or "r", for rivers. The <levelbitmapX> specifications are bitmaps in which the LSB corresponds to level 1, etc. Each set bit will cause the return of map coordinates at that level. For example, the types string for map coordinates of political boundaries at both the national and state levels and also rivers at only the major river level would be "p:3 r:1". Note that if the <levelbitmapX> specification is set to 0, then no levels and no coordinates will be returned. The desired resolution of the map coordinates is specified with the resolution argument which must be one of "f", for full, "h", for high, "i", for intermediate, "l" for low and "c", for crude. A latitude-longitude bounding box can be specified with the bb_lonwest, ... arguments which will limit the returned map coordinates to those within the bounding box.
After the map is selected, then the coordinates can be retrieved with calls to gmtmap_nextseg. Each call will return the value 1 and fill in the next contiguous set of map coordinates. When there are no more segments for the current map selection, then gmtmap_nextseg will return 0. After all of the segments have been retrieved, another call to gmtmap_select can be made to select another set of coordinates and gmtmap_nextseg can be called again to process the segments from the new selection. The number of points for a particular segment are returned in npts. The map coordinates themselves are returned in the lat and lon floating arrays. The memory for these arrays is dynamically allocated or reused according to the incoming values of lat and lon, along with the bufsize argument. If the input values of lat and lon are NULL, then they are malloc'ed and bufsize is set to the size of the buffers in units of floats. If the input values of lat and lon are not NULL, then they are reused and potentially realloc'ed according to npts and the input value of bufsize. For each segment the map type ("p" or "r") and level are returned in type and level.
% cat testgmt.c #include <stdlib.h> #include "brttutil.h" #include "stock.h" #include "gmtmap.h" int main (int argc, char **argv) { void *handle = NULL; int nsegs, i, j, ret; int npts, bufsize = 0; float *lat=NULL; float *lon=NULL; char type[4]; int level; if (argc != 3) { fprintf (stderr, "usage: testgmt types resolution\n"); exit (1); } /* open the gmtmap */ if (gmtmap_open (&handle) < 0) { die (0, "gmtmap_open() error.\n"); } /* select the map */ nsegs = gmtmap_select (handle, argv[1], argv[2], -180.0, 180.0, -90.0, 90.0); if (nsegs < 0) { die (0, "gmtmap_select(%s,%s) error.\n", argv[1], argv[2] ); } printf ("gmtmap_select(%s,%s) returns %d segments\n", argv[1], argv[2], nsegs); /* parse through the first few segments and print out a few coordinates */ for (i=0; i<nsegs; i++) { if (i > 3) { printf ("...\n"); break; } ret = gmtmap_nextseg (handle, &npts, &bufsize, &lon, &lat, type, &level); if (ret < 0) { die (0, "gmtmap_nextseg(%d) fatal error.\n", i); } if (ret == 0) break; printf ("gmtmap_nextseg(%d) returns %d points for type/level %s:%d:\n", i, npts, type, level); for (j=0; j<npts; j++) { if (j >= 10) { printf ("\t...\n"); break; } printf ("\t%9.4f %8.4f\n", lon[j], lat[j]); } } exit (0); } % cat Makefile BIN = testgmt MAN1 = PF = ldlibs= -lmappts -lbrttutil -lstock -ldeviants include $(ANTELOPEMAKE) DIRS= OBJS= \ testgmt.o testgmt : $(OBJS) $(CC) $(CFLAGS) -o $@ $(OBJS) $(LDFLAGS) $(LDLIBS) % testgmt r:4 f gmtmap_select(r:4,f) returns 7953 segments gmtmap_nextseg(0) returns 3 points for type/level r:3: 94.0000 74.0090 93.9947 74.0031 93.9934 74.0000 gmtmap_nextseg(1) returns 29 points for type/level r:3: 94.0886 74.1569 94.0794 74.1503 94.0825 74.1433 94.0892 74.1369 94.1064 74.1331 94.1269 74.1297 94.1508 74.1272 94.1681 74.1230 94.1850 74.1192 94.1986 74.1144 ... gmtmap_nextseg(2) returns 61 points for type/level r:3: 95.0000 74.4122 94.9764 74.4117 94.9506 74.4094 94.9281 74.4069 94.9083 74.4039 94.8858 74.4017 94.8664 74.3992 94.8436 74.3961 94.8211 74.3936 94.7986 74.3914 ... gmtmap_nextseg(3) returns 44 points for type/level r:3: 95.0000 74.2765 94.9897 74.2747 94.9761 74.2697 94.9628 74.2647 94.9494 74.2597 94.9392 74.2539 94.9258 74.2497 94.9092 74.2447 94.8900 74.2417 94.8678 74.2403 ... ...