Synopsis

use Cartog::GMT;

# set up the map
$map = new Map;
$map->output('test.eps');
$map->defaults('defaults.txt');
$map->verbose(1);

# get a layers set
$layers = new Layers;

# Each GMT program has an associated layer method of the same name.
$layers->pscoast("$common $res -Sc");

# a second argument which is a string is executed with its output 
# piped to the GMT program.
$layers->grdimage("$common -C$ccpt", "cat topo.grd");
$layers->grdcontour("$common -C5 -A20f6 -S20 -W2/200", "cat topo.grd");

# give the map its layers set
$map->layers($layers);

# draw it
$map->draw() or die;

DESCRIPTION

The Generic Mapping Tools (GMT) is a collection of programs for cartography, and more general technical illustration, with output in high-quality PostScript. This module provides a simple interface to these tools.

Map class

The package offers a Map class, with instantiation in the usual perl manner:

$map = new Map

Map methods allow one to specify a (PostScript) output file, a file of GMT defaults values (see gmtset(1)), a wrapper script (see below) and the verbosity level.

$map->defaults('defaults.txt');
$map->output('test.eps');
$map->wrapper('GMT')
$map->verbose(1);

The map's layers method requires a Layers object.

$map->layers($layers);

Layers class

The Layers object implements a list of system calls to the GMT programs. One must must initialise the object

$layers = new Layers;

before passing it to the map, or use

$layers = $map->layers(new Layers);

to initialise and assign at the same time.

Each GMT program has an associated Layers method of the same name. The first argument of the method will be used as the system call arguments for the program.

$layers->pscoast("$common $res -Sc");

If the second argument is present then its type determines the iterpretation: a string is interpreted as a system command whose output is piped to the GMT program; the following are equivalent.

$layers->grdimage("topo.grd $common -C$ccpt");
$layers->grdimage("$common -C$ccpt", "cat topo.grd");

If the second argument is a (reference to) a function then it is assumed to take the form

callback(*STREAM, $data);

and should write, to the STREAM, lines of input for the GMT command. The optional second argument can be used to pass data to the callback function without introducing global variables. The following code

sub mycat
{
  my ($stream, $file) = @_;
  open FILE, "< $file";
  print $stream <FILE>;
  close FILE;
  return 1;
}

$layers->pstext("$common -D0/0p", \&mycat, "villages.dat");

is functionally equivalent to

$layers->pstext("villages.dat $common -D0/0p");

ie, it feeds the file villages.dat to pstext, but with the callback method one has the opportunity to filter the contents of a file before pstext reads it.

Note that the -K and -O options (specifying whether each layer is an initial or final layer) are generated automatically by the Cartog::GMT module, and need not be included in the options.

Drawing

When the layers have been specified, the map may be drawn with the Map draw method:

$map->draw() or die;

Note that the GMT commands are not executed until the draw method has been called, and that they are then executed in the order in which the layer methods were called. This incudes the execution of the callback functions mentioned above.

Wrappers

In some situations it is convenient to call a wrapper script to set the environment before calling GMT programs. For example, the Debian Linux system does not put the GMT programs on the usual path, and one needs to call the wrapper script GMT to access the programs:

GMT pscoast ...

and so on. To use a wrapper GMT use the wrapper method on your Map.

$map->wrapper('GMT');

Caveats

The layer methods are automatically generated with AUTOLOAD, so that a Layers method call such as

$layers->pscroast("$common $res -Sc");

will not produce an error until the failure of the corresponding system call following $map->draw().

Note that layer methods should only be (the names of) GMT programs which produce PostScript output. No checking that this is the case is done.

EXPORT

None by default.

AUTHOR

J.J. Green

SEE ALSO

GMT(1), gmtset(1), perl(1).