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

STABILITY

46       The interface to Geo::Distance is fairly stable nowadays.  If this
47       changes it will be noted here.
48
49       0.21 - All distance calculations are now handled by GIS::Distance.
50
51       0.10 - The closest() method has a changed argument syntax and no longer
52       supports array searches.
53
54       0.09 - Changed the behavior of the reg_unit function.
55
56       0.07 - OO only, and other changes all over.
57

FORMULAS

59       "alt" - See GIS::Distance::ALT.
60
61       "cos" - See GIS::Distance::Cosine.
62
63       "gcd" - See GIS::Distance::GreatCircle.
64
65       "hsin" - See GIS::Distance::Haversine.
66
67       "mt" - See GIS::Distance::MathTrig.
68
69       "null" - See GIS::Distance::Null.
70
71       "polar" - See GIS::Distance::Polar.
72
73       "tv" - See GIS::Distance::Vincenty.
74

PROPERTIES

76   UNITS
77       All functions accept a unit type to do the computations of distance
78       with.  By default no units are defined in a Geo::Distance object.  You
79       can add units with reg_unit() or create some default units with
80       default_units().
81
82   LATITUDE AND LONGITUDE
83       When a function needs a longitude and latitude, they must always be in
84       decimal degree format.  Here is some sample code for converting from
85       other formats to decimal:
86
87           # DMS to Decimal
88           my $decimal = $degrees + ($minutes/60) + ($seconds/3600);
89
90           # Precision Six Integer to Decimal
91           my $decimal = $integer * .000001;
92
93       If you want to convert from decimal radians to degrees you can use
94       Math::Trig's rad2deg function.
95

METHODS

97   new
98           my $geo = new Geo::Distance;
99           my $geo = new Geo::Distance( no_units=>1 );
100
101       Returns a blessed Geo::Distance object.  The new constructor accepts
102       one optional argument.
103
104           no_units - Whether or not to load the default units. Defaults to 0 (false).
105                      kilometer, kilometre, meter, metre, centimeter, centimetre, millimeter,
106                      millimetre, yard, foot, inch, light second, mile, nautical mile,
107                      poppy seed, barleycorn, rod, pole, perch, chain, furlong, league,
108                      fathom
109
110   formula
111           if($geo->formula eq 'hsin'){ ... }
112           $geo->formula('cos');
113
114       Allows you to retrieve and set the formula that is currently being used
115       to calculate distances.  See the available "FORMULAS".
116
117       "hsin" is the default.  Both "mt" and "cos" are inferior in speed and
118       accuracy to "hsin".
119
120   reg_unit
121           $geo->reg_unit( $radius, $key );
122           $geo->reg_unit( $key1 => $key2 );
123           $geo->reg_unit( $count1, $key1 => $key2 );
124           $geo->reg_unit( $key1 => $count2, $key2 );
125           $geo->reg_unit( $count1, $key1 => $count2, $key2 );
126
127       This method is used to create custom unit types.  There are several
128       ways of calling it, depending on if you are defining the unit from
129       scratch, or if you are basing it off of an existing unit (such as
130       saying 12 inches = 1 foot ).  When defining a unit from scratch you
131       pass the name and rho (radius of the earth in that unit) value.
132
133       So, if you wanted to do your calculations in human adult steps you
134       would have to have an average human adult walk from the crust of the
135       earth to the core (ignore the fact that this is impossible).  So,
136       assuming we did this and we came up with 43,200 steps, you'd do
137       something like the following.
138
139           # Define adult step unit.
140           $geo->reg_unit( 43200, 'adult step' );
141           # This can be read as "It takes 43,200 adult_steps to walk the radius of the earth".
142
143       Now, if you also wanted to do distances in baby steps you might think
144       "well, now I gotta get a baby to walk to the center of the earth".
145       But, you don't have to!  If you do some research you'll find (no
146       research was actually conducted) that there are, on average, 4.7 baby
147       steps in each adult step.
148
149           # Define baby step unit.
150           $geo->reg_unit( 4.7, 'baby step' => 'adult step' );
151           # This can be read as "4.7 baby steps is the same as one adult step".
152
153       And if we were doing this in reverse and already had the baby step unit
154       but not the adult step, you would still use the exact same syntax as
155       above.
156
157   distance
158           my $distance = $geo->distance( 'unit_type', $lon1,$lat1 => $lon2,$lat2 );
159
160       Calculates the distance between two lon/lat points.
161
162   closest
163           my $locations = $geo->closest(
164               dbh => $dbh,
165               table => $table,
166               lon => $lon,
167               lat => $lat,
168               unit => $unit_type,
169               distance => $dist_in_unit
170           );
171
172       This method finds the closest locations within a certain distance and
173       returns an array reference with a hash for each location matched.
174
175       The closest method requires the following arguments:
176
177           dbh - a DBI database handle
178           table - a table within dbh that contains the locations to search
179           lon - the longitude of the center point
180           lat - the latitude of the center point
181           unit - the unit of measurement to use, such as "meter"
182           distance - the distance, in units, from the center point to find locations
183
184       The following arguments are optional:
185
186           lon_field - the name of the field in the table that contains the longitude, defaults to "lon"
187           lat_field - the name of the field in the table that contains the latitude, defaults to "lat"
188           fields - an array reference of extra field names that you would like returned with each location
189           where - additional rules for the where clause of the sql
190           bind - an array reference of bind variables to go with the placeholders in where
191           sort - whether to sort the locations by their distance, making the closest location the first returned
192           count - return at most these number of locations (implies sort => 1)
193
194       This method uses some very simplistic calculations to SQL select out of
195       the dbh.  This means that the SQL should work fine on almost any
196       database (only tested on MySQL and SQLite so far) and this also means
197       that it is fast.  Once this sub set of locations has been retrieved
198       then more precise calculations are made to narrow down the result set.
199       Remember, though, that the farther out your distance is, and the more
200       locations in the table, the slower your searches will be.
201

AUTHORS

203           Aran Clary Deltac <bluefeet@cpan.org>
204           gray <gray@cpan.org>
205           Anirvan Chatterjee <anirvan@base.mx.org>
206           AEvar Arnfjoerd` Bjarmason <avarab@gmail.com>
207           Niko Tyni <ntyni@debian.org>
208

LICENSE

210       This library is free software; you can redistribute it and/or modify it
211       under the same terms as Perl itself.
212
213
214
215perl v5.30.1                      2020-01-30                Geo::Distance(3pm)
Impressum