Provided by: libgeo-distance-perl_0.20-1_all bug

NAME

       Geo::Distance - Calculate Distances and Closest Locations

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 point-to-point 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(1-a) )
         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 Flat-Earth 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 ill-conditioned.

   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.

   mt: Math::Trig great_circle_distance
       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.

TODO

       •   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.

       •   Tests!  We need more tests!

       •   For NASA-quality accuracy a geoid forumula.

       •   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/cgi-bin/geo/gisfaq?Q5.1 <http://www.census.gov/cgi-bin/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.