view release on metacpan or  search on metacpan

README.md  view on Meta::CPAN

```perl
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"](#formulas) are available that provide different levels
of accuracy versus speed.

[GIS::Distance::Fast](https://metacpan.org/pod/GIS%3A%3ADistance%3A%3AFast), 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

```perl
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](https://metacpan.org/pod/Geo%3A%3APoint)
objects.

Returns a [Class::Measure::Length](https://metacpan.org/pod/Class%3A%3AMeasure%3A%3ALength) object for the distance between the
two degree lats/lons.

See ["distance\_metal"](#distance_metal) for a faster, but less feature rich, method.

## distance\_metal

This works just like ["distance"](#distance) except for:

- Does not accept [Geo::Point](https://metacpan.org/pod/Geo%3A%3APoint) objects.  Only decimal latitude and longitude
pairs.
- Does not return a [Class::Measure](https://metacpan.org/pod/Class%3A%3AMeasure) 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](https://metacpan.org/pod/GIS%3A%3ADistance%3A%3AGeoEllipsoid) 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"](#speed) section.

# ARGUMENTS

```perl
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:

```perl
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](https://metacpan.org/pod/GIS%3A%3ADistance%3A%3AFast) 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:

```perl
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](https://metacpan.org/pod/GIS%3A%3ADistance%3A%3AFast) to get the XS variants for most of the
PP formulas.

Use ["distance\_metal"](#distance_metal) instead of ["distance"](#distance).

Call the undocumented `_distance()` function that each formula class
has.  For example you could bypass this module entirely and just do:

```perl
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: