1GIS::Distance(3pm) User Contributed Perl Documentation GIS::Distance(3pm)
2
6 GIS::Distance - Calculate geographic distances.
7
9 use GIS::Distance;
10 # Use the GIS::Distance::Haversine formula by default.
12 my $gis = GIS::Distance->new();
13 # Or choose a different formula.
15 my $gis = GIS::Distance->new( 'Polar' );
16 # Returns a Class::Measure object.
18 my $distance = $gis->distance( $lat1, $lon1, $lat2, $lon2 );
19 print $distance->meters();
21
23 This module calculates distances between geographic points on, at the
24 moment, planet Earth. Various "FORMULAS" are available that provide
25 different levels of accuracy versus speed.
26 GIS::Distance::Fast, a separate distribution, ships with C
28 implementations of some of the formulas shipped with GIS::Distance. If
29 you're looking for speed then install it and the ::Fast formulas will
30 be automatically used by this module.
31
33 distance
34 my $distance = $gis->distance( $lat1, $lon1, $lat2, $lon2 );
35 my $point1 = Geo::Point->latlong( $lat1, $lon1 );
37 my $point2 = Geo::Point->latlong( $lat2, $lon2 );
38 my $distance = $gis->distance( $point1, $point2 );
39 Takes either two decimal latitude and longitude pairs, or two
41 Geo::Point objects.
42 Returns a Class::Measure::Length object for the distance between the
44 two degree lats/lons.
45 See "distance_metal" for a faster, but less feature rich, method.
47 distance_metal
49 This works just like "distance" except for:
50 • Does not accept Geo::Point objects. Only decimal latitude and
52 longitude pairs.
53 • Does not return a Class::Measure object. Instead kilometers are
55 always returned.
56 • Does no argument checking.
58 • Does not support formula arguments which are supported by at least
60 the GIS::Distance::GeoEllipsoid formula.
61 Calling this gets you pretty close to the fastest bare metal speed you
63 can get. The speed improvements of calling this is noticeable over
64 hundreds of thousands of iterations only and you've got to decide if
65 its worth the safety and features you are dropping. Read more in the
66 "SPEED" section.
67
69 my $gis = GIS::Distance->new( $formula );
70 When you call new() you may pass a partial or full formula class name
72 as the first argument. The default is "Haversive".
73 If you pass a partial name, as in:
75 my $gis = GIS::Distance->new( 'Haversine' );
77 Then the following modules will be looked for in order:
79 GIS::Distance::Fast::Haversine
81 GIS::Distance::Haversine
82 Haversine
83 Install GIS::Distance::Fast to get access to the "Fast::" (XS)
85 implementations of the formula classes.
86 You may globally disable the automatic use of the "Fast::" formulas by
88 setting the "GIS_DISTANCE_PP" environment variable. Although, its
89 likely simpler to just provide a full class name to get the same
90 effect:
91 my $gis = GIS::Distance->new( 'GIS::Distance::Haversine' );
93
95 Not that this module is slow, but if you're doing millions of distance
96 calculations a second you may find that adjusting your code a bit may
97 make it faster. Here are some options.
98 Install GIS::Distance::Fast to get the XS variants for most of the PP
100 formulas.
101 Use "distance_metal" instead of "distance".
103 Call the undocumented _distance() function that each formula class has.
105 For example you could bypass this module entirely and just do:
106 use GIS::Distance::Fast::Haversine;
108 my $km = GIS::Distance::Fast::Haversine::_distance( @coords );
109 The above would be the ultimate speed demon (as shown in benchmarking)
111 but throws away some flexibility and adds some foot-gun support.
112 Here's a benchmarks for these options:
114 2019-03-13T09:34:00Z
116 GIS::Distance 0.15
117 GIS::Distance::Fast 0.12
118 GIS::Distance::Fast::Haversine 0.12
119 GIS::Distance::Haversine 0.15
120 Rate
121 PP Haversine - GIS::Distance->distance 123213/s
122 XS Haversine - GIS::Distance->distance 196232/s
123 PP Haversine - GIS::Distance->distance_metal 356379/s
124 PP Haversine - GIS::Distance::Haversine::_distance 385208/s
125 XS Haversine - GIS::Distance->distance_metal 3205128/s
126 XS Haversine - GIS::Distance::Fast::Haversine::_distance 8620690/s
127 You can run your own benchmarks using the included "author/bench"
129 script. The above results were produced with:
130 author/bench -f Haversine
132 The slowest result was about "125000/s", or about "8ms" each call.
134 This could be a substantial burden in some contexts, such as live HTTP
135 responses to human users and running large batch jobs, to name just
136 two.
137 In conclusion, if you can justify the speed gain, switching to
139 "distance_metal" and installing GIS::Distance::Fast looks to be an
140 ideal setup.
141 As always with performance and benchmarking, YMMV.
143
145 When passing latitudinal and longitudinal coordinates to "distance"
146 they must always be in decimal degree format. Here is some sample code
147 for converting from other formats to decimal:
148 # DMS to Decimal
150 my $decimal = $degrees + ($minutes/60) + ($seconds/3600);
151 # Precision Six Integer to Decimal
153 my $decimal = $integer * .000001;
154 If you want to convert from decimal radians to degrees you can use
156 Math::Trig's rad2deg function.
157
159 These formulas come bundled with this distribution:
160 • GIS::Distance::ALT
162 • GIS::Distance::Cosine
164 • GIS::Distance::GreatCircle
166 • GIS::Distance::Haversine
168 • GIS::Distance::MathTrig
170 • GIS::Distance::Null
172 • GIS::Distance::Polar
174 • GIS::Distance::Vincenty
176 These formulas are available on CPAN:
178 • "FORMULAS" in GIS::Distance::Fast
180 • GIS::Distance::GeoEllipsoid
182
184 Take a look at GIS::Distance::Formula for instructions on authoring new
185 formula classes.
186
188 • Geo::Distance - Is deprecated in favor of using this module.
189 • Geo::Distance::Google - While in the Geo::Distance namespace, this
191 isn't actually related to Geo::Distance at all. Might be useful
192 though.
193 • GIS::Distance::Lite - An old fork of this module, not recommended.
195 • Geo::Distance::XS - Used to be used by Geo::Distance but no longer
197 is.
198 • Geo::Ellipsoid - Or use GIS::Distance::GeoEllipsoid for a uniform
200 interface.
201 • Geo::Inverse - Does some distance calculations, but seems less than
203 useful as all the code looks to be taken from Geo::Ellipsoid.
204
206 Please submit bugs and feature requests to the GIS-Distance GitHub
207 issue tracker:
208 <https://github.com/bluefeet/GIS-Distance/issues>
210
212 Aran Clary Deltac <bluefeet@gmail.com>
213
215 Mohammad S Anwar <mohammad.anwar@yahoo.com>
216 Florian Schlichting <fsfs@debian.org>
217
219 This library is free software; you can redistribute it and/or modify it
220 under the same terms as Perl itself.
221perl v5.36.1 2023-06-08 GIS::Distance(3pm)