NAME
Geo::Distance - Compute the Distances between Two Geographic Locations
SYNOPSIS
use Geo::Distance;
my $geo = new Get::Distance;
my $dist1 = $geo->distance( unit=>'mile', lon1=>$lon1, lat1=>$lat1, lon2=>$lon2, lat2=>$lat2 );
my $dist2 = $geo->distance_dirty('light_second',$lon1,$lat1,$lon2,$lat2);or
use Geo::Distance qw{ :all };
my $dist1 = geo_distance( unit=>'meter', lon1=>$lon1, lat1=>$lat1, lon2=>$lon2, lat2=>$lat2 );
my $dist2 = geo_distance_dirty('inch',$lon1,$lat1,$lon2,$lat2);DESCRIPTION
This perl library provides the ability to calculate the distance between two geographic points. There is both a function oriented interface, and an object oriented interface. Both have the same capabilities. Your choice of interface depends on your programming style and needs. Geo::Distance only recognizes standard decimal based longitude and latitude measurements. If you have other coordinate systems that you would like to use, then take a peak at the Geo::Coordinates module and the Geo::Coordinates::* family of conversion modules.
The latest version of the Geo::Distance (and Geo::Coordinates) modules can be found at:
http://www.bluefeet.net/perl/modules/geo/distance/OO VERSUS POLLUTION
This module provides two styles of programming, the first of which being an elegant object oriented interface and the second being a namespace polluting function interface. Personally, I like to pollute my namespace, but an object oriented interface does come in handy at times.
Both the object oriented interface and the function interface have the same functions, just with slightly different names.
At the moment there are several ways to import functions. The most common being the :all export tag. This will export the geo_distance() and geo_distance_dirty() functions. You may also export the functions individually, as follows:
# Export just geo_distance().
use Geo::Distance qw{ &geo_distance };
# Export just geo_distance_dirty().
use Geo::Distance qw{ &geo_distance_dirty };
# Export both functions.
use Geo::Distance qw{ &geo_distance &geo_distance_dirty };
# or
use Geo::Distance qw{ :all };METHODS
Currently there are two methods supplied by this module, both with function oriented and object oriented interface. Whatever the interface, these methods take the same arguments and return the same results.
DISTANCE
Takes a name value pairs in a hash style. All arguments will be validated. Returns the distance between the two locations in the unit type passed to it.
# unit => mile|light_second|kilometer|meter|centimeter|yard|foot|inches
# lon1,lat1 => Latitude and longitude in decimal format for the first location.
# lon2,lat2 => Ditto, but for the second location.
my $dist1 = geo_distance( unit=>'meter', lon1=>$lon1, lat1=>$lat1, lon2=>$lon2, lat2=>$lat2 );
my $dist2 = $geo->distance( unit=>'mile', lon1=>$lon1, lat1=>$lat1, lon2=>$lon2, lat2=>$lat2 );DISTANCE_DIRTY
This method is used internally by distance() to do the actual distance calculation. The benefit of using distance_dirty() is that it is faster than its counterpart because it does not check the input and does not accept a hash style argument list.
This method takes 5 arguments. They are unit, lon1, lat1, lon2, and lat2. See the distance method for a description of these arguments.
my $dist1 = $geo->distance_dirty('light_second',$lon1,$lat1,$lon2,$lat2);
my $dist2 = geo_distance_dirty('inch',$lon1,$lat1,$lon2,$lat2);TODO
Detect coordinate types and automatically send them through Geo::Coordinates to be converted to decimal.
BUGS
None known right now, but by the time you read this, who knows? Check http://www.bluefeet.net/perl/modules/geo/distance/ for the latest bugs and enhancements.
NOTES
Geo::Distance is currently in its alpha stage. The interface may, and probably will change, features will be added and removed without notice, and good things will hopefully happen before the bad. So, until this module reaches beta stage, don't be too peeved if something doesn't work when you upgrade.
This module relies on Math::Trig (great_circle_distance) for most of its computations. Math::Trig is a core Perl module.
AUTHOR
Copyright (C) 2003 Aran Clary Deltac (CPAN: BLUEFEET)
This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
Address bug reports and comments to: <geo_distance@bluefeet.net>. When sending bug reports, please provide the version of Geo::Distance, the version of Perl, and the name and version of the operating system you are using. Patches are welcome if you are brave!
SEE ALSO
Geo::Coordinates - A wrapper for converting between various geographic coordinates.
Math::Trig - Inverse and hyperbolic trigonemetric Functions.