NAME
GD::Map::Mercator - Create Mercator projected map images using GD
SYNOPSIS
use GD::Map::Mercator;
#
# create a new basemap
#
my $newmap = GD::Map::Mercator->new(
basemap_path => './basemaps',
basemap_name => 'namer.gif',
data_path => './WDB',
min_lat => 15.5,
min_long => -50,
max_lat => 49.5,
max_long => -26,
width => 800,
height => 500,
background => '#FF0023',
foreground => 'black',
thickness => 3,
silent => 1,
);
#
# or load an existing one
#
my $oldmap = GD::Map::Mercator->new(
basemap_path => './basemaps',
basemap_name => 'namer.gif'
);
#
# grab the image as an GD object
#
my $imager = $newmap->image();
#
# draw some stuff on it
#
$imager->lineTo($here, $there);
#
# compute some pixels from lat/long
#
my ($x,$y) = $newmap->project($lat, $long);
#
# or compute lat/long from pixels
#
my ($lat, $long) = $newmap->translate($x, $y);
#
# carve out a section of the map
#
my $submap = $newmap->extract($minlat, $minlong, $maxlat, $maxlong);
#
# create a 1/2 size map
#
my $scaledmap = $newmap->scale(0.5);
#
# and save it
#
$scaledmap->save('scaledmap.gif');DESCRIPTION
Perl module for creating geographic map files with GD using a Mercator Projection.
Originally inspired by GD::Map, but significantly modified to
support the Mercator projection
optimize for performance (theres a lot of data to convert)
expose the map image for direct manipulation by the application
Geospatial Database
The geospatial data is sourced from the CIA World DataBank II repository at http://www.evl.uic.edu/pape/data/WDB/. Note that this database was created in the mid 1980's, so some of the political boundries are not current.
You'll need to download the WDB files and unpack them somewhere. The following files are contained in the archive:
africa-bdy.txt
africa-cil.txt
africa-riv.txt
asia-bdy.txt
asia-cil.txt
asia-riv.txt
europe-bdy.txt
europe-cil.txt
europe-riv.txt
namer-bdy.txt
namer-cil.txt
namer-pby.txt
namer-riv.txt
samer-bdy.txt
samer-cil.txt
samer-riv.txtOnce unpacked, the files need to be filtered and converted via the wdb2merc script included in this bundle. wdb2merc
filters out some noisy data
converts the latitude/longitude coordinates into Mercator projected distances (for faster loading/computation)
writes the results out as binary records which can be loaded much faster, and compresses the data approx. 35%
Creating Maps
Map images are rendered by specifying a bounding box defined by minimum and maximum latitude and longitudes, and the output image dimensions. The resulting image and associated configuration data can be saved for future use, avoiding the overhead of re-rendering by reloading the basemap image and its data.
To create a new basemap:
use GD::Map::Mercator;
my $map = GD::Map::Mercator->new(
basemap_path => "/data/basemaps",
basemap_name => "testing",
data_path => "/usr/local/wdb",
width => $width,
height => $height,
max_long => 162,
min_long => 65,
max_lat => 70,
min_lat => 14,
background => '#FF0023',
foreground => 'black',
thickness => 3,
);This will create testing.png and testing.conf files in /data/basemaps containing a map of the area bounded by 14 deg latitude, 65 deg longitude, and 70 deg latitude, 162 deg longitude. The resulting image will attempt a best fit for the specified $width and $height, but will adjust dimensions as needed to preserve the Mercator scaling. Note that negative latitude values are south of the equator, and negative longitude is west of the meridian (Greenwich, GB). If the maximum longitude is negative and the minimum is positive, the map is assumed to cross the antipodal meridian.
The testing.conf file contains the relevant data for the created map image.
The created base map can be reused later by using the alternate constructor:
use GD::Map::Mercator;
my $map = GD::Map::Mercator->new(
basemap_path => "/data/basemaps",
basemap_name => "testing",
);This constructor will attempt to initialize itself from the specified basemap file.
Using Map Images
After creating or loading a basemap image, you can extract portions of the image, rescale the image, or decorate the image directly by getting the GD::Image object (or rather, a copy of the basemap image):
my $img = $map->image();To compute pixel coordinates from latitude/longitude pairs:
my ($x,$y) = $map->project($lat, $long);If the specified latitude or longitude is outside the range of the map, it returns undef values. Otherwise, the results are a pixel coordinate.
As a shortcut, multiple sets of lat/long points may be specified:
my @coords = $map->project($lat1, $long1, $lat2, $long2, $lat3, $long3, .. );Once you have the map image, and coordinates, the usual GD methods can be used to manipulate the image.
Conversely, you can get the latitude/longitude and Mercator projected distances for given pixel coordinates:
my ($lat,$long, $merclat, $merclong) = $map->translate($x, $y);This might be useful for interactive mapping applications.
The basemap configuration data, including hte bounding box latitude/longitude coordiates, the Mercator projected lat/long distance (in meters), and the image dimensions can also be retrieved:
my ($minlat, $minlong, $maxlat, $maxlong,
$minmerclat, $minmerclong, $maxmerclat, $maxmerclong, $width, $height) = $map->config();The basemap can also be rescaled:
my $newmap = $map->scale($scale);This will create a new GD::Map::Mercator object zoomed in/out as needed, with updated configuration data.
Submaps can be extracted (and optionally scaled):
my $newmap = $map->extract($minlat, $minlong, $maxlat, $maxlong [, $scale ]);Once you've created a new map via scale or extract you can save it as a basemap using
$newmap->save('mynewmap.png');METHODS
Refer to the classdoc output for detailed method descriptions.
EXAMPLES
Some example maps can be viewed here.SEE ALSO
This package was inspired by GD::Map, but this package uses a significantly different rendering technique, and exposes a different interface.
Geo::Mercator is used to compute the projections.
CIA World DataBank II datasets are at http://www.evl.uic.edu/pape/data/WDB/
US Zip Code Database: http://zips.sourceforge.net/
US Census TIGER/Line Data: http://www.census.gov/geo/www/tiger/
Geo::Coder::US and the several other Geo::Coder packages
AUTHOR, COPYRIGHT AND LICENSE
Dean Arnold mailto:darnold@presicient.com
Copyright(C) 2008, Dean Arnold, Presicient Corp., USA
Permission is granted to use, copy, modify, and redistribute this software under the terms of the Perl Artistic license.