Elaine, shiks-appeal is a myth, like the Yeti, or his North American cousin, the Sasquatch
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.