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

NAME

6       GIS::Distance - Calculate geographic distances.
7

SYNOPSIS

9           use GIS::Distance;
10
11           # Use the GIS::Distance::Haversine formula by default.
12           my $gis = GIS::Distance->new();
13
14           # Or choose a different formula.
15           my $gis = GIS::Distance->new( 'Polar' );
16
17           # Returns a Class::Measure object.
18           my $distance = $gis->distance( $lat1, $lon1, $lat2, $lon2 );
19
20           print $distance->meters();
21

DESCRIPTION

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
27       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

METHODS

33   distance
34           my $distance = $gis->distance( $lat1, $lon1, $lat2, $lon2 );
35
36           my $point1 = Geo::Point->latlong( $lat1, $lon1 );
37           my $point2 = Geo::Point->latlong( $lat2, $lon2 );
38           my $distance = $gis->distance( $point1, $point2 );
39
40       Takes either two decimal latitude and longitude pairs, or two
41       Geo::Point objects.
42
43       Returns a Class::Measure::Length object for the distance between the
44       two degree lats/lons.
45
46       See "distance_metal" for a faster, but less feature rich, method.
47
48   distance_metal
49       This works just like "distance" except for:
50
51       •   Does not accept Geo::Point objects.  Only decimal latitude and
52           longitude pairs.
53
54       •   Does not return a Class::Measure object.  Instead kilometers are
55           always returned.
56
57       •   Does no argument checking.
58
59       •   Does not support formula arguments which are supported by at least
60           the GIS::Distance::GeoEllipsoid formula.
61
62       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

ARGUMENTS

69           my $gis = GIS::Distance->new( $formula );
70
71       When you call new() you may pass a partial or full formula class name
72       as the first argument.  The default is "Haversive".
73
74       If you pass a partial name, as in:
75
76           my $gis = GIS::Distance->new( 'Haversine' );
77
78       Then the following modules will be looked for in order:
79
80           GIS::Distance::Fast::Haversine
81           GIS::Distance::Haversine
82           Haversine
83
84       Install GIS::Distance::Fast to get access to the "Fast::" (XS)
85       implementations of the formula classes.
86
87       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
92           my $gis = GIS::Distance->new( 'GIS::Distance::Haversine' );
93

SPEED

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
99       Install GIS::Distance::Fast to get the XS variants for most of the PP
100       formulas.
101
102       Use "distance_metal" instead of "distance".
103
104       Call the undocumented _distance() function that each formula class has.
105       For example you could bypass this module entirely and just do:
106
107           use GIS::Distance::Fast::Haversine;
108           my $km = GIS::Distance::Fast::Haversine::_distance( @coords );
109
110       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
113       Here's a benchmarks for these options:
114
115           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
128       You can run your own benchmarks using the included "author/bench"
129       script.  The above results were produced with:
130
131           author/bench -f Haversine
132
133       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
138       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
142       As always with performance and benchmarking, YMMV.
143

COORDINATES

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
149           # DMS to Decimal
150           my $decimal = $degrees + ($minutes/60) + ($seconds/3600);
151
152           # Precision Six Integer to Decimal
153           my $decimal = $integer * .000001;
154
155       If you want to convert from decimal radians to degrees you can use
156       Math::Trig's rad2deg function.
157

FORMULAS

159       These formulas come bundled with this distribution:
160
161       •   GIS::Distance::ALT
162
163       •   GIS::Distance::Cosine
164
165       •   GIS::Distance::GreatCircle
166
167       •   GIS::Distance::Haversine
168
169       •   GIS::Distance::MathTrig
170
171       •   GIS::Distance::Null
172
173       •   GIS::Distance::Polar
174
175       •   GIS::Distance::Vincenty
176
177       These formulas are available on CPAN:
178
179       •   "FORMULAS" in GIS::Distance::Fast
180
181       •   GIS::Distance::GeoEllipsoid
182

AUTHORING

184       Take a look at GIS::Distance::Formula for instructions on authoring new
185       formula classes.
186

SEE ALSO

188       •   Geo::Distance - Is deprecated in favor of using this module.
189
190       •   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
194       •   GIS::Distance::Lite - An old fork of this module, not recommended.
195
196       •   Geo::Distance::XS - Used to be used by Geo::Distance but no longer
197           is.
198
199       •   Geo::Ellipsoid - Or use GIS::Distance::GeoEllipsoid for a uniform
200           interface.
201
202       •   Geo::Inverse - Does some distance calculations, but seems less than
203           useful as all the code looks to be taken from Geo::Ellipsoid.
204

SUPPORT

206       Please submit bugs and feature requests to the GIS-Distance GitHub
207       issue tracker:
208
209       <https://github.com/bluefeet/GIS-Distance/issues>
210

AUTHOR

212           Aran Clary Deltac <bluefeet@gmail.com>
213

CONTRIBUTORS

215           Mohammad S Anwar <mohammad.anwar@yahoo.com>
216           Florian Schlichting <fsfs@debian.org>
217

LICENSE

219       This library is free software; you can redistribute it and/or modify it
220       under the same terms as Perl itself.
221
222
223
224perl v5.36.1                      2023-06-08                GIS::Distance(3pm)
Impressum