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 The interface to Geo::Distance is fairly stable nowadays. If this
47 changes it will be noted here.
48 0.21 - All distance calculations are now handled by GIS::Distance.
50 0.10 - The closest() method has a changed argument syntax and no longer
52 supports array searches.
53 0.09 - Changed the behavior of the reg_unit function.
55 0.07 - OO only, and other changes all over.
57
59 "alt" - See GIS::Distance::ALT.
60 "cos" - See GIS::Distance::Cosine.
62 "gcd" - See GIS::Distance::GreatCircle.
64 "hsin" - See GIS::Distance::Haversine.
66 "mt" - See GIS::Distance::MathTrig.
68 "null" - See GIS::Distance::Null.
70 "polar" - See GIS::Distance::Polar.
72 "tv" - See GIS::Distance::Vincenty.
74
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 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 # DMS to Decimal
88 my $decimal = $degrees + ($minutes/60) + ($seconds/3600);
89 # Precision Six Integer to Decimal
91 my $decimal = $integer * .000001;
92 If you want to convert from decimal radians to degrees you can use
94 Math::Trig's rad2deg function.
95
97 new
98 my $geo = new Geo::Distance;
99 my $geo = new Geo::Distance( no_units=>1 );
100 Returns a blessed Geo::Distance object. The new constructor accepts
102 one optional argument.
103 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 formula
111 if($geo->formula eq 'hsin'){ ... }
112 $geo->formula('cos');
113 Allows you to retrieve and set the formula that is currently being used
115 to calculate distances. See the available "FORMULAS".
116 "hsin" is the default. Both "mt" and "cos" are inferior in speed and
118 accuracy to "hsin".
119 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 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 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 # 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 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 # 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 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 distance
158 my $distance = $geo->distance( 'unit_type', $lon1,$lat1 => $lon2,$lat2 );
159 Calculates the distance between two lon/lat points.
161 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 This method finds the closest locations within a certain distance and
173 returns an array reference with a hash for each location matched.
174 The closest method requires the following arguments:
176 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 The following arguments are optional:
185 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 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
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
210 This library is free software; you can redistribute it and/or modify it
211 under the same terms as Perl itself.
212perl v5.30.0 2019-07-26 Geo::Distance(3pm)