1Geo::Distance(3pm)    User Contributed Perl Documentation   Geo::Distance(3pm)
2
3
4

NAME

6       Geo::Distance - Calculate distances and closest locations. (DEPRECATED)
7

SYNOPSIS

9           use Geo::Distance;
10
11           my $geo = new Geo::Distance;
12           $geo->formula('hsin');
13
14           $geo->reg_unit( 'toad_hop', 200120 );
15           $geo->reg_unit( 'frog_hop' => 6 => 'toad_hop' );
16
17           my $distance = $geo->distance( 'unit_type', $lon1,$lat1 => $lon2,$lat2 );
18
19           my $locations = $geo->closest(
20               dbh => $dbh,
21               table => $table,
22               lon => $lon,
23               lat => $lat,
24               unit => $unit_type,
25               distance => $dist_in_unit
26           );
27

DESCRIPTION

29       This perl library aims to provide as many tools to make it as simple as
30       possible to calculate distances between geographic points, and anything
31       that can be derived from that.  Currently there is support for finding
32       the closest locations within a specified distance, to find the closest
33       number of points to a specified point, and to do basic point-to-point
34       distance calculations.
35

DEPRECATED

37       This module has been gutted and is now a wrapper around GIS::Distance,
38       please use that module instead.
39
40       When switching from this module to GIS::Distance make sure you reverse
41       the coordinates when passing them to "distance" in GIS::Distance.
42       GIS::Distance takes lat/lon pairs while Geo::Distance takes lon/lat
43       pairs.
44

ARGUMENTS

46   no_units
47       Set this to disable the loading of the default units as described in
48       "UNITS".
49

ACCESSORS

51   formula
52           if ($geo->formula() eq 'hsin') { ... }
53           $geo->formula('cos');
54
55       Set and get the formula that is currently being used to calculate
56       distances.  See the available "FORMULAS".
57
58       "hsin" is the default.
59

METHODS

61   distance
62           my $distance = $geo->distance( 'unit_type', $lon1,$lat1 => $lon2,$lat2 );
63
64       Calculates the distance between two lon/lat points.
65
66   closest
67           my $locations = $geo->closest(
68               dbh => $dbh,
69               table => $table,
70               lon => $lon,
71               lat => $lat,
72               unit => $unit_type,
73               distance => $dist_in_unit
74           );
75
76       This method finds the closest locations within a certain distance and
77       returns an array reference with a hash for each location matched.
78
79       The closest method requires the following arguments:
80
81           dbh - a DBI database handle
82           table - a table within dbh that contains the locations to search
83           lon - the longitude of the center point
84           lat - the latitude of the center point
85           unit - the unit of measurement to use, such as "meter"
86           distance - the distance, in units, from the center point to find locations
87
88       The following arguments are optional:
89
90           lon_field - the name of the field in the table that contains the longitude, defaults to "lon"
91           lat_field - the name of the field in the table that contains the latitude, defaults to "lat"
92           fields - an array reference of extra field names that you would like returned with each location
93           where - additional rules for the where clause of the sql
94           bind - an array reference of bind variables to go with the placeholders in where
95           sort - whether to sort the locations by their distance, making the closest location the first returned
96           count - return at most these number of locations (implies sort => 1)
97
98       This method uses some very simplistic calculations to SQL select out of
99       the dbh.  This means that the SQL should work fine on almost any
100       database (only tested on MySQL and SQLite so far) and this also means
101       that it is fast.  Once this sub set of locations has been retrieved
102       then more precise calculations are made to narrow down the result set.
103       Remember, though, that the farther out your distance is, and the more
104       locations in the table, the slower your searches will be.
105
106   reg_unit
107           $geo->reg_unit( $radius, $key );
108           $geo->reg_unit( $key1 => $key2 );
109           $geo->reg_unit( $count1, $key1 => $key2 );
110           $geo->reg_unit( $key1 => $count2, $key2 );
111           $geo->reg_unit( $count1, $key1 => $count2, $key2 );
112
113       This method is used to create custom unit types.  There are several
114       ways of calling it, depending on if you are defining the unit from
115       scratch, or if you are basing it off of an existing unit (such as
116       saying 12 inches = 1 foot ).  When defining a unit from scratch you
117       pass the name and rho (radius of the earth in that unit) value.
118
119       So, if you wanted to do your calculations in human adult steps you
120       would have to have an average human adult walk from the crust of the
121       earth to the core (ignore the fact that this is impossible).  So,
122       assuming we did this and we came up with 43,200 steps, you'd do
123       something like the following.
124
125           # Define adult step unit.
126           $geo->reg_unit( 43200, 'adult step' );
127           # This can be read as "It takes 43,200 adult_steps to walk the radius of the earth".
128
129       Now, if you also wanted to do distances in baby steps you might think
130       "well, now I gotta get a baby to walk to the center of the earth".
131       But, you don't have to!  If you do some research you'll find (no
132       research was actually conducted) that there are, on average, 4.7 baby
133       steps in each adult step.
134
135           # Define baby step unit.
136           $geo->reg_unit( 4.7, 'baby step' => 'adult step' );
137           # This can be read as "4.7 baby steps is the same as one adult step".
138
139       And if we were doing this in reverse and already had the baby step unit
140       but not the adult step, you would still use the exact same syntax as
141       above.
142

FORMULAS

144       ·   "alt" - See GIS::Distance::ALT.
145
146       ·   "cos" - See GIS::Distance::Cosine.
147
148       ·   "gcd" - See GIS::Distance::GreatCircle.
149
150       ·   "hsin" - See GIS::Distance::Haversine.
151
152       ·   "mt" - See GIS::Distance::MathTrig.
153
154       ·   "null" - See GIS::Distance::Null.
155
156       ·   "polar" - See GIS::Distance::Polar.
157
158       ·   "tv" - See GIS::Distance::Vincenty.
159

LATITUDE AND LONGITUDE

161       When a function needs a longitude and latitude, they must always be in
162       decimal degree format.  Here is some sample code for converting from
163       other formats to decimal:
164
165           # DMS to Decimal
166           my $decimal = $degrees + ($minutes/60) + ($seconds/3600);
167
168           # Precision Six Integer to Decimal
169           my $decimal = $integer * .000001;
170
171       If you want to convert from decimal radians to degrees you can use
172       Math::Trig's rad2deg function.
173

UNITS

175       The "distance" and "closest" functions take an argument containing the
176       name of a registered unit, such as "kilometer", to do the computation
177       of distance with.  By default a useful set of units are registered and
178       custom units may be added with "reg_unit".  The default set of units
179       are:
180
181           kilometer, kilometre, meter, metre, centimeter, centimetre, millimeter,
182           millimetre, yard, foot, inch, light second, mile, nautical mile,
183           poppy seed, barleycorn, rod, pole, perch, chain, furlong, league, fathom
184
185       The "no_units" argument may be set to disable the default units from
186       being registered.
187

STABILITY

189       The interface to Geo::Distance is fairly stable nowadays.  If this
190       changes it will be noted here.
191
192       ·   0.21 - All distance calculations are now handled by GIS::Distance.
193
194       ·   0.10 - The closest() method has a changed argument syntax and no
195           longer supports array searches.
196
197       ·   0.09 - Changed the behavior of the reg_unit function.
198
199       ·   0.07 - OO only, and other changes all over.
200

SUPPORT

202       Please submit bugs and feature requests to the Geo-Distance GitHub
203       issue tracker:
204
205       <https://github.com/bluefeet/Geo-Distance/issues>
206
207       Note that, due to the "DEPRECATED" nature of this distribution, new
208       features and such may be denied.
209

AUTHORS

211           Aran Clary Deltac <bluefeet@gmail.com>
212           gray <gray@cpan.org>
213           Anirvan Chatterjee <anirvan@base.mx.org>
214           AEvar Arnfjoerd` Bjarmason <avarab@gmail.com>
215           Niko Tyni <ntyni@debian.org>
216

LICENSE

218       This library is free software; you can redistribute it and/or modify it
219       under the same terms as Perl itself.
220
221
222
223perl v5.32.1                      2021-02-01                Geo::Distance(3pm)
Impressum