1Geo::Distance(3pm) User Contributed Perl Documentation Geo::Distance(3pm)
2
6 Geo::Distance - Calculate distances and closest locations. (DEPRECATED)
7
9 use Geo::Distance;
10 my $geo = new Geo::Distance;
12 $geo->formula('hsin');
13 $geo->reg_unit( 'toad_hop', 200120 );
15 $geo->reg_unit( 'frog_hop' => 6 => 'toad_hop' );
16 my $distance = $geo->distance( 'unit_type', $lon1,$lat1 => $lon2,$lat2 );
18 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
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
37 This module has been gutted and is now a wrapper around GIS::Distance,
38 please use that module instead.
39 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
46 no_units
47 Set this to disable the loading of the default units as described in
48 "UNITS".
49
51 formula
52 if ($geo->formula() eq 'hsin') { ... }
53 $geo->formula('cos');
54 Set and get the formula that is currently being used to calculate
56 distances. See the available "FORMULAS".
57 "hsin" is the default.
59
61 distance
62 my $distance = $geo->distance( 'unit_type', $lon1,$lat1 => $lon2,$lat2 );
63 Calculates the distance between two lon/lat points.
65 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 This method finds the closest locations within a certain distance and
77 returns an array reference with a hash for each location matched.
78 The closest method requires the following arguments:
80 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 The following arguments are optional:
89 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 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 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 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 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 # 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 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 # 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 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
144 • "alt" - See GIS::Distance::ALT.
145 • "cos" - See GIS::Distance::Cosine.
147 • "gcd" - See GIS::Distance::GreatCircle.
149 • "hsin" - See GIS::Distance::Haversine.
151 • "mt" - See GIS::Distance::MathTrig.
153 • "null" - See GIS::Distance::Null.
155 • "polar" - See GIS::Distance::Polar.
157 • "tv" - See GIS::Distance::Vincenty.
159
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 # DMS to Decimal
166 my $decimal = $degrees + ($minutes/60) + ($seconds/3600);
167 # Precision Six Integer to Decimal
169 my $decimal = $integer * .000001;
170 If you want to convert from decimal radians to degrees you can use
172 Math::Trig's rad2deg function.
173
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 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 The "no_units" argument may be set to disable the default units from
186 being registered.
187
189 The interface to Geo::Distance is fairly stable nowadays. If this
190 changes it will be noted here.
191 • 0.21 - All distance calculations are now handled by GIS::Distance.
193 • 0.10 - The closest() method has a changed argument syntax and no
195 longer supports array searches.
196 • 0.09 - Changed the behavior of the reg_unit function.
198 • 0.07 - OO only, and other changes all over.
200
202 Please submit bugs and feature requests to the Geo-Distance GitHub
203 issue tracker:
204 <https://github.com/bluefeet/Geo-Distance/issues>
206 Note that, due to the "DEPRECATED" nature of this distribution, new
208 features and such may be denied.
209
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
218 This library is free software; you can redistribute it and/or modify it
219 under the same terms as Perl itself.
220perl v5.34.0 2021-07-22 Geo::Distance(3pm)