NAME

PDL::Graphics::PGPLOT::Map - Interface to the GMT coastline database for plotting maps

Perl/PDL interface to GMT's pscoast function to get binary coastline/river/boundary info into a (big) PDL of latitude/longitude line segments.

NOTE: This module *requires* bad value support! (Use a recent (cvs) version of PDL. Set WITH_BADVAL => 1 in perldl.conf).

SYNOPSIS

  use PDL;
  use PDL::Graphics::Map;
  use PDL::Graphics::PGPLOT;

  #
  ## plot just the coastlines in a linear projection
  #

  dev "pdlmap1.ps/CPS";
  worldmap ({WEST  => -180, EAST  => 180, SOUTH => -90, NORTH => 90});

  # or, alternatively, in two steps:
  dev "pdlmap2.ps/CPS";
  my ($lon, $lat) = PDL::Graphics::PGPLOT::Map::fetch (
                                     {BOX => [-180, 180, -90, 90],
                                      SEPARATOR    => -999});
  # Plot the entire set of coastline polylines 
  line $lon, $lat, {MISSING => -999};

  #
  ## Plot coastlines, lat/lon grids and labels in an Azimuthal Equidistant projection
  #

  dev "pdlmap3.ps/CPS";
  worldmap ({PROJECTION => 'AZEQDIST', # Azimuthal Equidistant projection
             CENTER  => [-170, 70],    # map centered at 170 deg west lon, 70 deg north lat
             RADIUS  => 3000,          # 3000 kilometer minimum radius
             LONGRID => 10,            # longitude grid lines every 10 degrees
             LATGRID => 10});          # latitude grid lines every 10 degrees

  #
  ## Plot points on the map
  #

  my ($lon, $lat) = getsomepoints();
  map_points ($lon, $lat, {PROJECTION => 'AZEQDIST', CENTER  => [-170, 70]});

  #
  ## Plot lines on the map
  #

  my ($lon, $lat) = getsomemorepoints();
  map_line ($lon, $lat, {PROJECTION => 'AZEQDIST', CENTER  => [-170, 70], MISSING => -999});

For more information on GMT, see http://www.soest.hawaii.edu/gmt/

DESCRIPTION

This is the PDL interface to the GMT map databases, allowing one to create pleasing world maps in either of two projections:

1) linear (no projection) 2) Azimuthal Equidistant

using PGPLOT.

Routines are also supplied to allow plotting of points and lines (supplied in degrees lon/lat) on the maps with the correct projection supplied.

FUNCTIONS

worldmap

Plot a world map using PGPLOT.

Arguments: just a hash reference which can contain the following keywords:

  PROJECTION  : LINEAR (default) or AZEQDIST

For LINEAR projections:

  WEST  : the Western border of the map (degrees west -180 - 180)  
  EAST  : the Eastern border of the map (degrees west -180 - 180)
  SOUTH : the Southern border of the map (degrees north -90 - 90)
  NORTH : the Northern border of the map (degrees north -90 - 90)

For AZEQDIST projections:

  CENTER  : A list ref to the center point of the projection, in degrees, ie: [-170, 70]
  RADIUS  : A minimum radius in kilometers

For all projections:

  RESOLUTION : The size of the map database used:  "full", "high", "intermediate", "low" or "crude"

  RIVER_DETAIL : A list reference to which rivers to plot:
                    1 = Permanent major rivers
                    2 = Additional major rivers
                    3 = Additional rivers
                    4 = Minor rivers
                    5 = Intermittent rivers - major
                    6 = Intermittent rivers - additional
                    7 = Intermittent rivers - minor
                    8 = Major canals
                    9 = Minor canals
                   10 = Irrigation canals                
                                    
  BOUNDARIES : A list reference to which boundaries to plot:
                    1 = National boundaries
                    2 = State boundaries within the Americas
                    3 = Marine boundaries                                                           

  COASTS : A boolean value:  plot coasts = true, don't = false

  LONGRID  : The grid spacing for longitude lines in degrees (undef = no lon grids)
  LATGRID  : The grid spacing for latitude lines in degrees (undef = no lat grids)

map_points

Plots lon/lat points on an existing map with projection.

  map_points ($lon, $lat, {PROJECTION => ..., CENTER => [...,...]});

  PROJECTION defaults to LINEAR.  If AZEQDIST is specified, then the 
  CENTER lon/lat must be specified.

map_line

Plots lon/lat lines on an existing map with projection.

  map_line ($lon, $lat, {PROJECTION => ..., CENTER => [...,...], MISSING => ...});

  PROJECTION defaults to LINEAR.  If AZEQDIST is specified, then the 
  CENTER lon/lat must be specified.  To plot more than one line
  segment, specify MISSING to be a separator value.

fetch

Get lon and lat PDLs.

Arguments: A hash reference with these options available: BOX : An array ref containing [minlon, maxlon, minlat, maxlat] in degrees -180 to 180, -90 to 90

  RESOLUTION : The size of the map database used:  "full", "high", "intermediate", "low" or "crude"

  RIVER_DETAIL : A list reference to which rivers to plot:
                    1 = Permanent major rivers
                    2 = Additional major rivers
                    3 = Additional rivers
                    4 = Minor rivers
                    5 = Intermittent rivers - major
                    6 = Intermittent rivers - additional
                    7 = Intermittent rivers - minor
                    8 = Major canals
                    9 = Minor canals
                   10 = Irrigation canals                
                                    
  BOUNDARIES : A list reference to which boundaries to plot:
                    1 = National boundaries
                    2 = State boundaries within the Americas
                    3 = Marine boundaries                                                           

  COASTS : A boolean value:  plot coasts = true, don't = false
  SEPARATOR : A numeric value:  The value to place between each separate line segment.

Returns: ($lon, $lat) large 1-D PDLs

AUTHOR

Doug Hunt, dhunt\@ucar.edu.

CPAN RT