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

• CGI::Wiki

• CGI::Wiki::Plugin::Locator::UK

• Geo::Coordinates::UTM

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.