Manual Reference Pages  GEO::DISTANCE (3)
.ds Aq ’
NAME
Geo::Distance  Calculate Distances and Closest Locations
CONTENTS
SYNOPSIS
use Geo::Distance;
my $geo = new Geo::Distance;
$geo>formula(hsin);
$geo>reg_unit( toad_hop, 200120 );
$geo>reg_unit( frog_hop => 6 => toad_hop );
my $distance = $geo>distance( unit_type, $lon1,$lat1 => $lon2,$lat2 );
my $locations = $geo>closest(
dbh => $dbh,
table => $table,
lon => $lon,
lat => $lat,
unit => $unit_type,
distance => $dist_in_unit
);
DESCRIPTION
This perl library aims to provide as many tools to make it as simple as possible to calculate
distances between geographic points, and anything that can be derived from that. Currently
there is support for finding the closest locations within a specified distance, to find the
closest number of points to a specified point, and to do basic pointtopoint distance
calculations.
DECOMMISSIONED
The GIS::Distance module is being worked on as a replacement for this module. In the
near future Geo::Distance will become a lightweight wrapper around GIS::Distance so that
legacy code benefits from fixes to GIS::Distance through the old Geo::Distance API. For
any new developement I suggest that you look in to GIS::Distance.
STABILITY
The interface to Geo::Distance is fairly stable nowadays. If this changes it
will be noted here.
0.10  The closest() method has a changed argument syntax and no longer supports array searches.
0.09  Changed the behavior of the reg_unit function.
0.07  OO only, and other changes all over.
PROPERTIES
UNITS
All functions accept a unit type to do the computations of distance with. By default no units
are defined in a Geo::Distance object. You can add units with reg_unit() or create some default
units with default_units().
LATITUDE AND LONGITUDE
When a function needs a longitude and latitude, they must always be in decimal degree format.
Here is some sample code for converting from other formats to decimal:
# DMS to Decimal
my $decimal = $degrees + ($minutes/60) + ($seconds/3600);
# Precision Six Integer to Decimal
my $decimal = $integer * .000001;
If you want to convert from decimal radians to degrees you can use Math::Trig’s rad2deg function.
METHODS
new
my $geo = new Geo::Distance;
my $geo = new Geo::Distance( no_units=>1 );
Returns a blessed Geo::Distance object. The new constructor accepts one optional
argument.
no_units  Whether or not to load the default units. Defaults to 0 (false).
kilometer, kilometre, meter, metre, centimeter, centimetre, millimeter,
millimetre, yard, foot, inch, light second, mile, nautical mile,
poppy seed, barleycorn, rod, pole, perch, chain, furlong, league,
fathom
formula
if($geo>formula eq hsin){ ... }
$geo>formula(cos);
Allows you to retrieve and set the formula that is currently being used to
calculate distances. The available formulas are hsin, polar, cos and mt. hsin
is the default and mt/cos are deprecated in favor of hsin. Polar should be used
when calculating coordinates near the poles.
reg_unit
$geo>reg_unit( $radius, $key );
$geo>reg_unit( $key1 => $key2 );
$geo>reg_unit( $count1, $key1 => $key2 );
$geo>reg_unit( $key1 => $count2, $key2 );
$geo>reg_unit( $count1, $key1 => $count2, $key2 );
This method is used to create custom unit types. There are several ways of calling it,
depending on if you are defining the unit from scratch, or if you are basing it off
of an existing unit (such as saying 12 inches = 1 foot ). When defining a unit from
scratch you pass the name and rho (radius of the earth in that unit) value.
So, if you wanted to do your calculations in human adult steps you would have to have an
average human adult walk from the crust of the earth to the core (ignore the fact that
this is impossible). So, assuming we did this and we came up with 43,200 steps, you’d
do something like the following.
# Define adult step unit.
$geo>reg_unit( 43200, adult step );
# This can be read as "It takes 43,200 adult_steps to walk the radius of the earth".
Now, if you also wanted to do distances in baby steps you might think well, now I
gotta get a baby to walk to the center of the earth. But, you don’t have to! If you do some
research you’ll find (no research was actually conducted) that there are, on average,
4.7 baby steps in each adult step.
# Define baby step unit.
$geo>reg_unit( 4.7, baby step => adult step );
# This can be read as "4.7 baby steps is the same as one adult step".
And if we were doing this in reverse and already had the baby step unit but not
the adult step, you would still use the exact same syntax as above.
distance
my $distance = $geo>distance( unit_type, $lon1,$lat1 => $lon2,$lat2 );
Calculates the distance between two lon/lat points.
closest
my $locations = $geo>closest(
dbh => $dbh,
table => $table,
lon => $lon,
lat => $lat,
unit => $unit_type,
distance => $dist_in_unit
);
This method finds the closest locations within a certain distance and returns an
array reference with a hash for each location matched.
The closest method requires the following arguments:
dbh  a DBI database handle
table  a table within dbh that contains the locations to search
lon  the longitude of the center point
lat  the latitude of the center point
unit  the unit of measurement to use, such as "meter"
distance  the distance, in units, from the center point to find locations
The following arguments are optional:
lon_field  the name of the field in the table that contains the longitude, defaults to "lon"
lat_field  the name of the field in the table that contains the latitude, defaults to "lat"
fields  an array reference of extra field names that you would like returned with each location
where  additional rules for the where clause of the sql
bind  an array reference of bind variables to go with the placeholders in where
sort  whether to sort the locations by their distance, making the closest location the first returned
count  return at most these number of locations (implies sort => 1)
This method uses some very simplistic calculations to SQL select out of the dbh. This
means that the SQL should work fine on almost any database (only tested on MySQL and SQLite so far) and
this also means that it is fast. Once this sub set of locations has been retrieved
then more precise calculations are made to narrow down the result set. Remember, though, that
the farther out your distance is, and the more locations in the table, the slower your searches will be.
FORMULAS
Currently Geo::Distance only has spherical and flat type formulas.
If you have any information concerning ellipsoid and geoid formulas,
the author would much appreciate some links to this information.
tv: Thaddeus Vincenty Formula
This is a highly accurate ellipsoid formula. For most applications
hsin will be faster and accurate enough. I’ve read that this formula can
be accurate to within a few millimeters.
This formula is still considered alpha quality. It has not been tested
enough to be used in production.
hsin: Haversine Formula
dlon = lon2  lon1
dlat = lat2  lat1
a = (sin(dlat/2))^2 + cos(lat1) * cos(lat2) * (sin(dlon/2))^2
c = 2 * atan2( sqrt(a), sqrt(1a) )
d = R * c
The hsin formula is the new standard formula for Geo::Distance because
of it’s improved accuracy over the cos formula.
polar: Polar Coordinate FlatEarth Formula
a = pi/2  lat1
b = pi/2  lat2
c = sqrt( a^2 + b^2  2 * a * b * cos(lon2  lon1) )
d = R * c
While implimented, this formula has not been tested much. If you use it
PLEASE share your results with the author!
cos: Law of Cosines for Spherical Trigonometry
a = sin(lat1) * sin(lat2)
b = cos(lat1) * cos(lat2) * cos(lon2  lon1)
c = arccos(a + b)
d = R * c
Although this formula is mathematically exact, it is unreliable for
small distances because the inverse cosine is illconditioned.
gcd: Great Circle Distance.
c = 2 * asin( sqrt(
( sin(( lat1  lat2 )/2) )^2 +
cos( lat1 ) * cos( lat2 ) *
( sin(( lon1  lon2 )/2) )^2
) )
Similar notes to the mt and cos formula, not too terribly accurate.
This formula uses Meth::Trig’s great_circle_distance function which at this time uses math almost
exactly the same as the cos formula. If you want to use the cos formula you may find
that mt will calculate faster (untested assumption). For some reason mt and cos return
slight differences at very close distances. The mt formula has the same drawbacks as the cos formula.
This is the same formula that was previously the only one used by
Geo::Distance (ending at version 0.06) and was wrongly called the gcd formula.
Math::Trig states that the formula that it uses is:
lat0 = 90 degrees  phi0
lat1 = 90 degrees  phi1
d = R * arccos(cos(lat0) * cos(lat1) * cos(lon1  lon01) + sin(lat0) * sin(lat1))
NOTES
If Geo::Distance::XS is installed, this module will use it. You can
stick with the pure Perl version by setting the GEO_DISTANCE_PP environment
variable before using this module.
o

A second pass should be done in closest before distance calculations are made that does an inner
radius simplistic calculation to find the locations that are obviously within the distance needed.

o

Tests! We need more tests!

o

For NASAquality accuracy a geoid forumula.

o

The closest() method needs to be more flexible and (among other things) allow table joins.


SEE ALSO
Math::Trig  Inverse and hyperbolic trigonemetric Functions.
<http://www.census.gov/cgibin/geo/gisfaq?Q5.1>  A overview of calculating distances.
<http://williams.best.vwh.net/avform.htm>  Aviation Formulary.
AUTHOR
Aran Clary Deltac <bluefeet@cpan.org>
CONTRIBUTORS
gray, <gray at cpan.org>
LICENSE
This library is free software; you can redistribute it and/or modify
it under the same terms as Perl itself.
perl v5.20.3  GEO::DISTANCE (3)  20121019 
Visit the GSP FreeBSD Man Page Interface. Output converted with manServer 1.07. 