Geo::Distance(3pm)

💖 Geo::Distance — the perl page (3pm) 💖

okay bestie, so this is Geo::Distance, a User Contributed Perl Documentation page. it calculates distances and finds closest locations. and uh. it's DEPRECATED. we'll get to that, i promise, but like. brace yourself. 😭

---

✨ NAME ✨

Geo::Distance — calculate distances and closest locations. (DEPRECATED)

---

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

like, look at it go. toad hops. frog hops. iconic. 🐸

---

🌸 DESCRIPTION 🌸

so the whole goal of this perl library? give you as many tools as possible so that calculating distances between geographic points — and literally anything you can derive from that — is as simple as it can possibly be. periodt.

right now it supports:

• finding the closest locations within a specified distance
• finding the closest number of points to a specified point
• basic point-to-point distance calculations

that's the whole vibe. 🫶

---

💀 DEPRECATED 💀

not me having to tell you this — this module has been gutted and is now just a wrapper around GIS::Distance. please use that module instead, bestie. fr fr.

⚠️ when you switch from this module to GIS::Distance, make sure you reverse the coordinates when passing them to distance in GIS::Distance. GIS::Distance takes lat/lon pairs while Geo::Distance takes lon/lat pairs. yes this is the classic trap. do not fall in it. 🕳️

---

🎀 ARGUMENTS 🎀

no_units

set this to disable the loading of the default units as described in "UNITS". that's it, that's the argument. 💅

---

⭐ ACCESSORS ⭐

formula

if ($geo->formula() eq 'hsin') { ... }
$geo->formula('cos');

set and get the formula that's currently being used to calculate distances. see the available "FORMULAS" below. 🌈

"hsin" is the default.

---

👑 METHODS 👑

distance

my $distance = $geo->distance( 'unit_type', $lon1,$lat1 => $lon2,$lat2 );

calculates the distance between two lon/lat points. that's it. that's the whole method. slay. ✨

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 required arguments, no skips allowed:

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 optional arguments (the little extras 💅):

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)

so here's the tea on how it works internally: this method uses some very simplistic calculations to SQL select out of the dbh. which means the SQL should work fine on almost any database (only tested on MySQL and SQLite so far) and it also means it's fast. once that sub set of locations has been retrieved, more precise calculations are made to narrow down the result set. 🧚

😭 but remember, bestie: the farther out your distance is, and the more locations in the table, the slower your searches will be. it's giving "pay for what you ask for".

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're defining the unit from scratch, or if you're 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. no notes. 👑

---

🔥 FORMULAS 🔥

• "alt" — see GIS::Distance::ALT.
• "cos" — see GIS::Distance::Cosine.
• "gcd" — see GIS::Distance::GreatCircle.
• "hsin" — see GIS::Distance::Haversine.
• "mt" — see GIS::Distance::MathTrig.
• "null" — see GIS::Distance::Null.
• "polar" — see GIS::Distance::Polar.
• "tv" — see GIS::Distance::Vincenty.

---

🌈 LATITUDE AND LONGITUDE 🌈

whenever a function needs a longitude and latitude, they must always be in decimal degree format. here's 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;

and if you want to convert from decimal radians to degrees, you can use Math::Trig's rad2deg function. 🧮

---

🦄 UNITS 🦄

the distance and closest functions take an argument containing the name of a registered unit, such as "kilometer", to do the computation of distance with. by default a useful set of units are registered and custom units may be added with reg_unit. the default set of units are:

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

the no_units argument may be set to disable the default units from being registered. 💅

---

🫶 STABILITY 🫶

the interface to Geo::Distance is fairly stable nowadays. if this changes it will be noted here. 📝

• 0.21 — all distance calculations are now handled by GIS::Distance.
• 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.

---

💜 SUPPORT 💜

please submit bugs and feature requests to the Geo-Distance GitHub issue tracker:

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

🌸 note that, due to the DEPRECATED nature of this distribution, new features and such may be denied. they said what they said.

---

⭐ AUTHORS ⭐

Aran Clary Deltac <bluefeet@gmail.com>
gray <gray@cpan.org>
Anirvan Chatterjee <anirvan@base.mx.org>
AEvar Arnfjoer` Bjarmason <avarab@gmail.com>
Niko Tyni <ntyni@debian.org>

the whole squad. legends only. 👑

---

🎀 LICENSE 🎀

this library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

---

and that's the whole page, bestie!! 💖✨🎀🦋🌸💅🫶🔥👑🌈⭐💀🙈🍓🧚💜

this was brought to you by perl v5.36.0, dated 2023-02-26 — go forth and calculate some distances (in GIS::Distance, preferably 😭). mwah 💋