/ 
CGI-Wiki-Plugin-Locator-UTM-0.04
River stage one • 1 direct dependent • 1 total dependent
/ CGI::Wiki::Plugin::Locator::UTM

NAME

CGI::Wiki::Plugin::Locator::UTM - A CGI::Wiki plugin to manage international location data.

SYNOPSIS

  use CGI::Wiki;
  use CGI::Wiki::Plugin::Locator::UTM;

  my $wiki = CGI::Wiki->new( ... );
  my $locator = CGI::Wiki::Plugin::Locator::UTM->new('International');
  $wiki->register_plugin( $locator );

  $wiki->write_node( "King's Head",
                     "Tip top pride",
                     $checksum,
		     { lat => 51.507497,
                       long => -0.271797
                     }
                    );

  # Just retrieve the location
  my ( $lat, $long ) = $locator->location( node => "King's Head" );

  # or as coordinates
  my ( $zone, $east, $north ) = $locator->coordinates( node => "King's Head" );

  # Find the straight-line distance between two nodes, in kilometres.
  my $distance = $locator->distance( from_node => "King's Head",
                                     to_node   => "Calthorpe Arms" );

  # Find all the things within 200 metres of a given place.
  my @others = $locator->find_within_distance( node   => "Albion",
                                               metres => 200 );

DESCRIPTION

This module provides access to the Universal Transverse Mercator international coordinates system. It is a thin wrapper for the module Geo::Coordinates::UTM. To use this module, you must specify an ellipsoid, on which the mercator projection is based.

METHODS

new
my $locator = CGI::Wiki::Plugin::Locator::UK->new('Clarke 1880');

The parameter is the name of the ellipsoid to be used for coordinate conversion. The default value of this is 'International'. Please see Geo::Coordinates::UTM for explanation and for the full list of valid values.

Note that you can only do coordinate conversion within one ellipsoid.

location
my ($lat, $long) = $locator->coordinates( node => "King's Head" );

Returns the latitude and longitude co-ordinates stored as metadata last time the node was written.

coordinates
my ($zone, $x, $y) = $locator->coordinates( node => "King's Head" );

my ($zone, $x, $y) = $locator->coordinates( lat => 51.507497,
					     long => -0.271797);

Returns the UTM easting and northing co-ordinates. See Geo::Coordinates::UTM for the meaning of the zone value.

distance
  # Find the straight-line distance between two nodes, in kilometres.
  my $distance = $locator->distance( from_node => "King's Head",
                                     to_node   => "Duke Of York" );

  # Or in metres between a node and a point.
  my $distance = $locator->distance(from_lat  => 51.507497,
                                    from_long => -0.271797,
				    to_node   => "Duke of Cambridge",
				    unit      => "metres" );

Defaults to kilometres if unit is not supplied or is not recognised. Recognised units at the moment: metres, kilometres.

Returns undef if one of the endpoints does not exist, or does not have both co-ordinates defined.

Note: Works to the nearest metre. Well, actually, calls int and rounds down, but if anyone cares about that they can send a patch.

find_within_distance
# Find all the things within 200 metres of a given place.
my @others = $locator->find_within_distance( node   => "Albion",
                                             metres => 200 );

# Or within 200 metres of a given location.
my @things = $locator->find_within_distance( lat => 51.507497,
                                             long => -0.271797,
                                             metres => 200 );

Requires the node metadata to be stored in the database, in particular zone, easting and northing.

Units currently understood: metres, kilometres. If both node and os_x/os_y are supplied then node takes precedence. Croaks if insufficient start point data supplied.

og_config
my $config = OpenGuides::Config->new(file => 'wiki.conf');
$locator->og_config($config);
...
$ellipsoid = $locator->og_config->ellipsoid;

This is a get-and-set method, used in conjunction with the OpenGuides package to make all the information from the configuration available to the plugin.

pre_write
$ap->despatch( 'pre_write', $node, $content, \%metadata );

This is a CGI::Wiki::AutoPlugin compatible method, which should be called before committing data to the wiki store. This performs the necessary geodata convertions needed between coordinate systems.

This is a refactoring of code in OpenGuides::Template which deals with converting input data into the coordinate system used on a particular guide. This pre-write method updates the metadata hash to populate the remaining fields of latitude, longitude, x, y, which are not already populated.

SEE ALSO

AUTHOR

Ivor Williams (ivorw at CPAN dot org)

ACKNOWLEDGEMENT

This module is derived from CGI::Wiki::Plugin::Locator::UK, written by Kate Pugh.

COPYRIGHT

Copyright (C) 2004 Ivor Williams.  All Rights Reserved.

This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself.