NAME

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

GIS::Distance::Fast, a separate distribution, ships with C implmentations 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

    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 );

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

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

    # 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

• 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

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

<https://github.com/bluefeet/GIS-Distance/issues>

AUTHORS

    Aran Clary Deltac <bluefeet@gmail.com>
    Mohammad S Anwar <mohammad.anwar@yahoo.com>

LICENSE