Provided by: libgis-distance-perl_0.20-1_all 
NAME
GIS::Distance - Calculate geographic distances.
SYNOPSIS
use GIS::Distance;
# Use the GIS::Distance::Haversine formula by default.
my $gis = GIS::Distance->new();
# Or choose a different formula.
my $gis = GIS::Distance->new( 'Polar' );
# Returns a Class::Measure object.
my $distance = $gis->distance( $lat1, $lon1, $lat2, $lon2 );
print $distance->meters();
DESCRIPTION
This module calculates distances between geographic points on, at the moment, planet
Earth. Various "FORMULAS" are available that provide different levels of accuracy versus
speed.
GIS::Distance::Fast, a separate distribution, ships with C implementations of some of the
formulas shipped with GIS::Distance. If you're looking for speed then install it and the
::Fast formulas will be automatically used by this module.
METHODS
distance
my $distance = $gis->distance( $lat1, $lon1, $lat2, $lon2 );
my $point1 = Geo::Point->latlong( $lat1, $lon1 );
my $point2 = Geo::Point->latlong( $lat2, $lon2 );
my $distance = $gis->distance( $point1, $point2 );
Takes either two decimal latitude and longitude pairs, or two Geo::Point objects.
Returns a Class::Measure::Length object for the distance between the two degree lats/lons.
See "distance_metal" for a faster, but less feature rich, method.
distance_metal
This works just like "distance" except for:
• Does not accept Geo::Point objects. Only decimal latitude and longitude pairs.
• Does not return a Class::Measure object. Instead kilometers are always returned.
• Does no argument checking.
• Does not support formula arguments which are supported by at least the
GIS::Distance::GeoEllipsoid formula.
Calling this gets you pretty close to the fastest bare metal speed you can get. The speed
improvements of calling this is noticeable over hundreds of thousands of iterations only
and you've got to decide if its worth the safety and features you are dropping. Read more
in the "SPEED" section.
ARGUMENTS
my $gis = GIS::Distance->new( $formula );
When you call "new()" you may pass a partial or full formula class name as the first
argument. The default is "Haversive".
If you pass a partial name, as in:
my $gis = GIS::Distance->new( 'Haversine' );
Then the following modules will be looked for in order:
GIS::Distance::Fast::Haversine
GIS::Distance::Haversine
Haversine
Install GIS::Distance::Fast to get access to the "Fast::" (XS) implementations of the
formula classes.
You may globally disable the automatic use of the "Fast::" formulas by setting the
"GIS_DISTANCE_PP" environment variable. Although, its likely simpler to just provide a
full class name to get the same effect:
my $gis = GIS::Distance->new( 'GIS::Distance::Haversine' );
SPEED
Not that this module is slow, but if you're doing millions of distance calculations a
second you may find that adjusting your code a bit may make it faster. Here are some
options.
Install GIS::Distance::Fast to get the XS variants for most of the PP formulas.
Use "distance_metal" instead of "distance".
Call the undocumented "_distance()" function that each formula class has. For example you
could bypass this module entirely and just do:
use GIS::Distance::Fast::Haversine;
my $km = GIS::Distance::Fast::Haversine::_distance( @coords );
The above would be the ultimate speed demon (as shown in benchmarking) but throws away
some flexibility and adds some foot-gun support.
Here's a benchmarks for these options:
2019-03-13T09:34:00Z
GIS::Distance 0.15
GIS::Distance::Fast 0.12
GIS::Distance::Fast::Haversine 0.12
GIS::Distance::Haversine 0.15
Rate
PP Haversine - GIS::Distance->distance 123213/s
XS Haversine - GIS::Distance->distance 196232/s
PP Haversine - GIS::Distance->distance_metal 356379/s
PP Haversine - GIS::Distance::Haversine::_distance 385208/s
XS Haversine - GIS::Distance->distance_metal 3205128/s
XS Haversine - GIS::Distance::Fast::Haversine::_distance 8620690/s
You can run your own benchmarks using the included "author/bench" script. The above
results were produced with:
author/bench -f Haversine
The slowest result was about "125000/s", or about "8ms" each call. This could be a
substantial burden in some contexts, such as live HTTP responses to human users and
running large batch jobs, to name just two.
In conclusion, if you can justify the speed gain, switching to "distance_metal" and
installing GIS::Distance::Fast looks to be an ideal setup.
As always with performance and benchmarking, YMMV.
COORDINATES
When passing latitudinal and longitudinal coordinates to "distance" 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.
FORMULAS
These formulas come bundled with this distribution:
• GIS::Distance::ALT
• GIS::Distance::Cosine
• GIS::Distance::GreatCircle
• GIS::Distance::Haversine
• GIS::Distance::MathTrig
• GIS::Distance::Null
• GIS::Distance::Polar
• GIS::Distance::Vincenty
These formulas are available on CPAN:
• "FORMULAS" in GIS::Distance::Fast
• GIS::Distance::GeoEllipsoid
AUTHORING
Take a look at GIS::Distance::Formula for instructions on authoring new formula classes.
SEE ALSO
• Geo::Distance - Is deprecated in favor of using this module.
• Geo::Distance::Google - While in the Geo::Distance namespace, this isn't actually
related to Geo::Distance at all. Might be useful though.
• GIS::Distance::Lite - An old fork of this module, not recommended.
• Geo::Distance::XS - Used to be used by Geo::Distance but no longer is.
• Geo::Ellipsoid - Or use GIS::Distance::GeoEllipsoid for a uniform interface.
• Geo::Inverse - Does some distance calculations, but seems less than useful as all the
code looks to be taken from Geo::Ellipsoid.
SUPPORT
Please submit bugs and feature requests to the GIS-Distance GitHub issue tracker:
<https://github.com/bluefeet/GIS-Distance/issues>
AUTHOR
Aran Clary Deltac <bluefeet@gmail.com>
CONTRIBUTORS
Mohammad S Anwar <mohammad.anwar@yahoo.com>
Florian Schlichting <fsfs@debian.org>
LICENSE
This library is free software; you can redistribute it and/or modify it under the same
terms as Perl itself.