UNITS¶

LATITUDE AND LONGITUDE¶

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

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.

tv: Thaddeus Vincenty Formula¶

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