The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
Image-Maps-Plot-FromLatLong-0.12
River stage zero No dependents
++
/ Image::Maps::Plot::FromLatLong

NAME

Image::Maps::Plot::FromLatLong - plots points on Mercator Projection world/regional map

SYNOPSIS

        use Image::Maps::Plot::FromLatLong;

        # Get ready
        $m = new Image::Maps::Plot::FromLatLong (
                MAP=>"THE WORLD",
                PATH=>"C:/out.html",    # Extension is irrelevant
                FONT=>"C:/winnt/fonts/arial.ttf",
        );

        # Now, Create an HTML page with images:
        $m->create_html;
        # Or just the image
        $m->create_imagefile;
        # Or get a reference to an image blob:
        $m->get_blob;

        # Create HTML pages of all maps in the db, with index
        my $m = new Image::Maps::Plot::FromLatLong(
                FONT=>'c:/winnt/fonts/arial.ttf',
        );
        $m->all("C:/");

        # Add a map
        $Image::Maps::Plot::FromLatLong::MAPS{"LONDON AREA"} = {
                FILE => 'C:\PhotoWebServer\Perl\site\lib\Image\Maps\Plot\london_bourghs.jpg',
                DIM      => [650,640],
                SPOTSIZE => 5,
                ANCHOR_PIXELS => [447,397],             # Greenwich on the pixel map
                ANCHOR_LATLON => [51.466,0],    # Greenwich lat/lon
                ANCHOR_NAME       => 'Greenwich',
                ANCHOR_PLACE  => 'Observatory',
                ONEMILE         => 19.5,                        # 1 km = .6 miles  (10km=180px = 10miles=108px)
        };


        # Add a user to the db
        $m->load_db (".earth.dat");
        $m->add_entry ('Ike Elben Goddard','Hungary','H-1165');
        $m->save_db (".aliyah.dat");

        # Create map content on the fly:
        $maker = new Image::Maps::Plot::FromLatLong(
                MAP     => "THE WORLD",
                FONT=>'c:/winnt/fonts/arial.ttf',
                PATH    => "/Two.foo",
                DBFILE  => undef,
                LOCATIONS => {
                  'Lee' => {
                         'LAT' => '51.592423',
                         'PLACE' => '#ffff44',
                         'LON' => '-0.171996'
                   },
                  'Lee Again' => {
                        'PLACE' => '#ffff77',
                        'LAT' => 46,
                        'LON' => 16
                  },
                },
        );


        __END__

DESCRIPTION

Plots points defined by latitude/longitude on JPEG Mercator Projection maps, optionally creating an HTML page with image map to display the image.

PREREQUISITES

        Data::Dumper;
        File::Basename;
        strict;
        warnings.

        WWW::MapBlast 0.02
        Image::Thumbnail 0.011

DISTRIBUTION CONTENTS

In addition to this file, the distribution uses the included files for default settings: they should be placed in the same directory as the module itself only if you wish to use default settings.

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

EXPORTS

None.

CONSTRUCTOR new

Returns an object in this class.

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.

DBFILE

Name of the configuration/db file - defaults to .earth.dat, which comes with the distribution: set to undef if you do not wish to use the default (perhaps because you are using the LOCATIONS field to supply a 'database' - see the next item).

LOCATIONS

Optional: a reference to a hash that will add and replace items in the module's content 'database'. Format of the hash referred to should be:

        $LOCATIONS = {
            'This key is a printable proper name' => {
        'LAT' => 11111111,      # Latitude value, or 11111111 if unknown
            'PLACE' => 'An Image;:Magick Colour Name or printable descriptor of the location',
            'LON' => 11111111   # Longitude value, or 11111111 if unknown
        },

If PLACE fields are supplied as hex colour names (# prefix) then their values will not be printed.

Note that if you supply this field without supplying the DBFILE with a value of undef, you will inherit the default location 'database'.

IMG_URI_PREFIX

If supplied, will be prefixed to the value of the IMG src attribute in HTML pages generated.

CHAT

Set if you want rabbit (Amos: that's London-speak for talk) to STDERR.

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.

FONT

Font for the above: absolute path or something Image Magick can find.

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

KEYS2VALUES

If set, will assume the 'place' sub-keys in locations hash are colour values for spots printed.

BORDER, FILL

Border and fill colours: if not set, SPOTCOLOUR will set them both.

CSS

Formatted inline CSS to go within a STYLE type='text/css' block in the header.

EXTRA_HTML

If defined, added at the end of the page.

METHOD create_html

Creates an image and an HTML page.

Requires that the PATH field be set (see CONSTRUCTOR).

METHOD create_imagefile

Creates just an image file.

Requires that the PATH field be set (see CONSTRUCTOR).

METHOD create_blob

Creates an image and return a reference to it's BLOB.

Requires that the PATH field be set (see CONSTRUCTOR).

METHOD all (base_path,base_url,title, blurb)

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 "new"), a title, and blurb to add beneath the list of hyperlinks to the maps.

If no base path is supplied, the PATH field is used.

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.

METHOD load_db

A method that loads a "database" hash from the specified path.

Returns a true value on success, undef on failure.

METHOD save_db

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.

METHOD add_entry

A method that accepts: $name, $latitude, $longitude, maybe $place_or_colour

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 the time.

Does not save them to file - you must do that manually ("METHOD 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.

See also "ADDING MAPS".

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

ADDING MAPS

A future version 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 content listed below.

FILE

scalar file name of Mercator Projection map.

DIM

anon array of dimensions of map in pixels [x,y]. You could create DIM on the fly using Image::Magick, 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

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.

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 isn't quite right - see "NOTES ON LATITUDE AND LONGITUDE". This will be adjusted in a later version.

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

REVSIONS

1.2

Corrected a slight mis-positioning of points.

Replaced GD with Image::Magick as I was seeing terrible JPEG output with GD.

Replaced support for non-maintained Image::GD::Thumbnail with Image::Thumbnail; evaluate a require of this at run time rather than using the apparently still shakey pragmas.

Added methods to create just images and to return references to image blobs.

1.0

Don't remember.

0.25

Clean IMG path and double-header bugs

0.23

Added more documentation; escaping of href text

0.22

Added thumbnail images to index page

SEE ALSO

perl(1); Image::Magick (http://www.ImageMagick.org); File::Basename; Acme::Pony; Data::Dumper; WWW::MapBlast; Image::Thumbnail

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 the CIA, About.com, The University of Texas, and The Ordnance Survey for their public-domain maps.

AUTHOR

Lee Goddard <lgoddard -at- cpan -point- 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.