• Antelope Release 5.10 Linux CentOS release 7.6.1810 (Core) 3.10.0 2020-05-12

 

NAME

gmtmap - GMT NetCDF file reading utilities

SYNOPSIS

#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)

DESCRIPTION

These subroutines provide an interface to the NetCDF format river and political boundary vector data that is included in the Antelope distribution map data directory in $ANTELOPE/data/maps/mappts. These files, named binned_border_c.cdf, binned_border_f.cdf, binned_border_h.cdf, binned_border_i.cdf, binned_border_l.cdf, binned_river_c.cdf, binned_river_f.cdf, binned_river_h.cdf, binned_river_i.cdf, and binned_river_l.cdf, are exact copies of the same data files provided in the GMT distribution. Although these are all standard version 1.0 NetCDF files, they are composed of certain entries in the NetCDF header dictionaries that are used by these utilities to properly parse the files into latitude-longitude coordinate vectors. Therefore these routines will only work with files that conform to these structures and with these names and located in the standard Antelope directory heirarchy. In other words, these subroutines are not intended to be generic interfaces into any GMT NetCDF files.

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.

EXAMPLE



% 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
        ...
 ...

LIBRARY

-lmappts

AUTHOR

Danny Harvey
Printer icon