NAME

PDL::Graphics::PLplot::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 version of PDL. Set WITH_BADVAL => 1 in perldl.conf).

SYNOPSIS

  use PDL;
  use PDL::Graphics::PLplot::Map;

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

  my $pl = PDL::Graphics::PLplot::Map->new (DEV => "png", FILE => "map.png");
  $pl->worldmap (MAPBOX => [-180, 180, -90, 90]);

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

  $pl = PDL::Graphics::PLplot::Map->new (DEV => "png", FILE => "map1.png");
  $pl->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();
  $pl->map_plot ($lon, $lat, PLOTTYPE => 'POINTS', SYMBOL => 1, PROJECTION => 'AZEQDIST', CENTER  => [-170, 70]);

  #
  ## Plot lines on the map
  #

  my ($lon, $lat) = getsomemorepoints();
  $pl->map_plot ($lon, $lat, PLOTTYPE => 'LINE', 
                             PROJECTION => 'AZEQDIST', 
                             CENTER  => [-170, 70]);

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

DESCRIPTION

This is the PDL/PLplot 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

The design is modular to allow addition of other projections.

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

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

  PROJECTION  : LINEAR (default) or AZEQDIST

For LINEAR projections:

  MAPBOX: An array ref containing [WEST, EAST, SOUTH, NORTH] in degrees
          -180 to 180, -90 to 90, ie: MAPBOX => [-180, 180, -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                                                           

  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_plot

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

  map_plot ($lon, $lat, PROJECTION => ..., CENTER => [...,...]);

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

fetch

Get lon and lat PDLs.

Arguments: A hash reference with these options available: MAPBOX : 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

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

AUTHOR

Doug Hunt, dhunt\@ucar.edu.