Image/Maps/Plot/FromPostcode version 1
======================================

NAME
    Image::Maps::Plot::FromPostcode - plots postcodes on world/regional map
    images/HTML

SYNOPSIS
	use Image::Maps::Plot::FromPostcode;

	# Create a single map

	new Image::Maps::Plot::FromPostcode (MAP=>"THE WORLD","PATH"=>"E:/src/pl/out.html");

	# Create all possible maps

	Image::Maps::Plot::FromPostcode::all("E:/src/pl/");

	# Add a user to the db

	Image::Maps::Plot::FromPostcode::load_db (".earth.dat");
	Image::Maps::Plot::FromPostcode::add_entry ('Peter Smith','United Kingdom','BS7 29JT');
	Image::Maps::Plot::FromPostcode::save_db (".london.pm.dat");

	__END__

DESCRIPTION
    Plots postcode-defined points on JPEG maps, and creates an HTML page
    with an image map to display the image.

    I was bored and got this message on a list:

            From: london.pm-admin@london.pm.org
            [mailto:london.pm-admin@london.pm.org]On Behalf Of Philip Newton
            Sent: 21 June 2001 11:44
            To: 'london.pm@london.pm.org'
            Subject: Re: headers

            Simon Wistow wrote:
            > It's more a collection of people who have the common connection
            > that they live and london and like perl.
            > In fact neither of those actually have to be true since I personally
            > know two people on the list who don't program Perl and one of whom
            > doesn't even live in London.

            How many off-London people have we got? (Well, also excluding people who
            live near London.)

            From outside the UK, there's Damian, dha, Paul M, I; Lucy and lathos
            probably also qualify as far as I can tell. Marcel used to work in London
            (don't know whether he still does). Anyone else?

            Cheers,
            Philip
            --
            Philip Newton <Philip.Newton@datenrevision.de>
            All opinions are my own, not my employer's.
            If you're not part of the solution, you're part of the precipitate.

    In the twenty-second weekly summary of the London Perl Mongers mailing
    list, for the week starting 2001-06-18:

            In other news: ... a london.pm world map ...

    Hence the module.

PREREQUISITES
            Data::Dumper;
            File::Basename;
            GD;
            strict;
            warnings.
            WWW::MapBlast 0.02
            Image::GD::Thumbnail 0.011

DISTRIBUTION CONTENTS
    In addition to this file, the distribution relies upon the included
    files:

            .earth.dat
            london_postcodes.jpg
            uk.jpg
            world.jpg

EXPORTS
    None. They're dirty dirty dirty.

CAVEATS
    The exmaple map, london_postcodes.jpg, is inaccurate.

    Whilst degrees of latitude are accurate to two decimal places, Degrees
    of longitude are taken to be 69 miles. This will be adjusted in a later
    version.

    All images must be JPEGs - PNG or other support could easily be added.

USEAGE METHODS
  new

    Not really a constructor, as it does not return a new object of this
    class, but does the whole job of loding, creating and saving the files,
    so maybe it shouldn't be called new.

    Accepts arguments in a hash, where keys/values are as follows:

    MAP Either "THE WORLD", "THE UK", "A BAD MAP OF LONDON", or any other
        key to the "%MAPS" hash defined elsewhere, and documented below.

    PATH
        The path at which to save - will use the filename you supply, but
        please include an extension, coz I'm lazy. You will receive a ".jpg"
        and ".html" file in return.

    DBNAME
        Name of the configuration/db file - defaults to ".earth.dat", which
        comes with the distribution.

    CHAT
        Set if you want rabbit on the screen.

    CREATIONTXT
        Text output onto the image. Defaults to 'Created on <date> by
        <package>.';

    TITLE
        Title text to include on the image (in bold) and as the content of
        the HTML page's "TITLE" element: is appended with the name of the
        map. This defaults to "London.pm", where this module originates.

    INCLUDEANCHOR
        Set if you wish the map's anchor point to be included in the output.

    FNPREFIX
        Filename prefix - added to the start of all files output except the
        db file. Default is "m_".

  &all (base_path,base_url)

    A subroutine, not a method, that produces all available maps, and an
    index page with thumbnails.

    It accepts four arguments, a path at which files can be built, a
    filename prefix (see the section on "new"), a title, and blurb to add
    beneath the list of hyperlinks to the maps.

    An index page will be produced, linking to the following files for each
    map:

        m_"MAPNAME".jpg m_"MAPNAME"_t.jpg m_"MAPNAME".html

    where MAPNAME is ... the name of the map. The "m_" prefix is held in the
    instance variable "FNPREFIX". You may also wish to look at and adjust
    the instance variable "CREATIONTXT".

  &load_db

    A subroutine that loads a database hash from the specified path.

    Returns nothing, but does "die" on failure.

  &save_db

    A subroutine, not a method, that saves the currently loaded database
    hash to the filename specified as the only arguemnt.

    Note tha tyou may want to load a db before saving.

    Returns nothing, but does "die" on failure.

  &add_entry

    A subroutine, not a method, that accepts: $name, $country, $postcode

    Looks up on MapBlast.com the supplied details, and adds them to the db.

    If an entry already exists for $name, will return "undef" unless the
    global scalar "$ADDENTRY" is set to it's default value of "MULTIPLE", in
    which case $name will be appended with $country and $postcode.

    Does not save them to file - you must do that manually (the section on
    "save_db"), but note that you may wish to load the db before adding to
    it and saving.

    Incidentaly returns a reference to the new key.

  &remove_entry

    A subroutine, not a method, that accepts the name field of the entry in
    the db, and returns "1" on success, "undef" if no such entry exists.

NOTES ON LATITUDE AND LONGITUDE
    After http://www.mapblast.com/myblast/helpFaq.mb#2:

        Zero degrees latitude is the equator, with the North pole at 90
        degrees latitude and the South pole at -90 degrees latitude. one
        degree is approximately 69 miles. Greenwich, England is at 51.466
        degrees north of the equator.

        Zero degrees longitude goes through Greenwich, England. Again, Each
        69 miles from this meridian represents approximately 1 degree of
        longitude. East/West is plus/minus respectively.

    Actually, latitude and longitude vary depending upon the degree in hand:
    see The Compton Encyclopdedia for more information.

ADDING MAPS
    The next version, if there is one, may allow you to pass map data to the
    constructor. In the meantime, adding maps is not in itself a big deal,
    perl-wise. Add a new key to the "%MAPS" hash, with the value of an
    anonymous hash with the following content:

    FILE
        scalar file name of map

    DIM anon array of dimensions of map in pixels [x,y]. You could create
        DIM on the fly using "GD", but there's probably no point, as you're
        almost certainly going to have to edit the map to align it with
        longitude and latitude (if you find a stock of public-domain maps
        that are already aligned, please drop the author a line).

    SPOTSIZE
        scalar number for the size of the map-marker spots, in pixels

    ANCHOR_PIXELS
        anon array of the pixel location of the arbitrary anchor pont [x,y]

    ANCHOR_LATLON
        anon array of the latitude/longitude of the arbitrary anchor pont
        [x,y]

    ANCHOR_NAME
        scalar name of the anchor, when marked on map

    ANCHOR_PLACE
        scalar place name of the anchor, when marked on map

    ONEMILE
        scalar representation of 1 mile in pixels

REVSIONS
    0.25 Clean IMG path and double-header bugs 0.22 Added thumbnail images
    to index page 0.23 Added more documentation; escaping of href text

SEE ALSO
    perl(1); the GD manpage; the File::Basename manpage; the Acme::Pony
    manpage; the Data::Dumper manpage; the WWW::MapBlast manpage; the
    Image::GD::Thumbnail manpage

THANKS
    Thanks to the London.pm group for their test data and insipration, to
    Leon for his patience with all that mess on the list, to Philip Newton
    for his frankly amazing knowledge of international postcodes.

    Thanks also to About.com, The University of Texas, and The Ordnance
    Survey for their public-domain maps.

AUTHOR
    Lee Goddard <lgoddard@cpan.org>

COPYRIGHT
    Copyright (C) Lee Goddard, 2001. All Rights Reserved.

    This module is supplied and may be used under the same terms as Perl
    itself.

    The public domain maps provided with this distribution are the property
    of their respective copyright holders.

