.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.43) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). .\" Fear. Run. Save yourself. No user-serviceable parts. . \" fudge factors for nroff and troff .if n \{\ . ds #H 0 . ds #V .8m . ds #F .3m . ds #[ \f1 . ds #] \fP .\} .if t \{\ . ds #H ((1u-(\\\\n(.fu%2u))*.13m) . ds #V .6m . ds #F 0 . ds #[ \& . ds #] \& .\} . \" simple accents for nroff and troff .if n \{\ . ds ' \& . ds ` \& . ds ^ \& . ds , \& . ds ~ ~ . ds / .\} .if t \{\ . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' .\} . \" troff and (daisy-wheel) nroff accents .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' .ds 8 \h'\*(#H'\(*b\h'-\*(#H' .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] .ds ae a\h'-(\w'a'u*4/10)'e .ds Ae A\h'-(\w'A'u*4/10)'E . \" corrections for vroff .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' . \" for low resolution devices (crt and lpr) .if \n(.H>23 .if \n(.V>19 \ \{\ . ds : e . ds 8 ss . ds o a . ds d- d\h'-1'\(ga . ds D- D\h'-1'\(hy . ds th \o'bp' . ds Th \o'LP' . ds ae ae . ds Ae AE .\} .rm #[ #] #H #V #F C .\" ======================================================================== .\" .IX Title "Geo::Distance 3pm" .TH Geo::Distance 3pm "2023-02-26" "perl v5.36.0" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" Geo::Distance \- Calculate distances and closest locations. (DEPRECATED) .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 1 \& use Geo::Distance; \& \& my $geo = new Geo::Distance; \& $geo\->formula(\*(Aqhsin\*(Aq); \& \& $geo\->reg_unit( \*(Aqtoad_hop\*(Aq, 200120 ); \& $geo\->reg_unit( \*(Aqfrog_hop\*(Aq => 6 => \*(Aqtoad_hop\*(Aq ); \& \& my $distance = $geo\->distance( \*(Aqunit_type\*(Aq, $lon1,$lat1 => $lon2,$lat2 ); \& \& my $locations = $geo\->closest( \& dbh => $dbh, \& table => $table, \& lon => $lon, \& lat => $lat, \& unit => $unit_type, \& distance => $dist_in_unit \& ); .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" This perl library aims to provide as many tools to make it as simple as possible to calculate distances between geographic points, and anything that can be derived from that. Currently there is support for finding the closest locations within a specified distance, to find the closest number of points to a specified point, and to do basic point-to-point distance calculations. .SH "DEPRECATED" .IX Header "DEPRECATED" This module has been gutted and is now a wrapper around GIS::Distance, please use that module instead. .PP When switching from this module to GIS::Distance make sure you reverse the coordinates when passing them to \*(L"distance\*(R" in GIS::Distance. GIS::Distance takes lat/lon pairs while Geo::Distance takes lon/lat pairs. .SH "ARGUMENTS" .IX Header "ARGUMENTS" .SS "no_units" .IX Subsection "no_units" Set this to disable the loading of the default units as described in \*(L"\s-1UNITS\*(R"\s0. .SH "ACCESSORS" .IX Header "ACCESSORS" .SS "formula" .IX Subsection "formula" .Vb 2 \& if ($geo\->formula() eq \*(Aqhsin\*(Aq) { ... } \& $geo\->formula(\*(Aqcos\*(Aq); .Ve .PP Set and get the formula that is currently being used to calculate distances. See the available \*(L"\s-1FORMULAS\*(R"\s0. .PP \&\f(CW\*(C`hsin\*(C'\fR is the default. .SH "METHODS" .IX Header "METHODS" .SS "distance" .IX Subsection "distance" .Vb 1 \& my $distance = $geo\->distance( \*(Aqunit_type\*(Aq, $lon1,$lat1 => $lon2,$lat2 ); .Ve .PP Calculates the distance between two lon/lat points. .SS "closest" .IX Subsection "closest" .Vb 8 \& my $locations = $geo\->closest( \& dbh => $dbh, \& table => $table, \& lon => $lon, \& lat => $lat, \& unit => $unit_type, \& distance => $dist_in_unit \& ); .Ve .PP This method finds the closest locations within a certain distance and returns an array reference with a hash for each location matched. .PP The closest method requires the following arguments: .PP .Vb 6 \& dbh \- a DBI database handle \& table \- a table within dbh that contains the locations to search \& lon \- the longitude of the center point \& lat \- the latitude of the center point \& unit \- the unit of measurement to use, such as "meter" \& distance \- the distance, in units, from the center point to find locations .Ve .PP The following arguments are optional: .PP .Vb 7 \& lon_field \- the name of the field in the table that contains the longitude, defaults to "lon" \& lat_field \- the name of the field in the table that contains the latitude, defaults to "lat" \& fields \- an array reference of extra field names that you would like returned with each location \& where \- additional rules for the where clause of the sql \& bind \- an array reference of bind variables to go with the placeholders in where \& sort \- whether to sort the locations by their distance, making the closest location the first returned \& count \- return at most these number of locations (implies sort => 1) .Ve .PP This method uses some very simplistic calculations to \s-1SQL\s0 select out of the dbh. This means that the \s-1SQL\s0 should work fine on almost any database (only tested on MySQL and SQLite so far) and this also means that it is fast. Once this sub set of locations has been retrieved then more precise calculations are made to narrow down the result set. Remember, though, that the farther out your distance is, and the more locations in the table, the slower your searches will be. .SS "reg_unit" .IX Subsection "reg_unit" .Vb 5 \& $geo\->reg_unit( $radius, $key ); \& $geo\->reg_unit( $key1 => $key2 ); \& $geo\->reg_unit( $count1, $key1 => $key2 ); \& $geo\->reg_unit( $key1 => $count2, $key2 ); \& $geo\->reg_unit( $count1, $key1 => $count2, $key2 ); .Ve .PP This method is used to create custom unit types. There are several ways of calling it, depending on if you are defining the unit from scratch, or if you are basing it off of an existing unit (such as saying 12 inches = 1 foot ). When defining a unit from scratch you pass the name and rho (radius of the earth in that unit) value. .PP So, if you wanted to do your calculations in human adult steps you would have to have an average human adult walk from the crust of the earth to the core (ignore the fact that this is impossible). So, assuming we did this and we came up with 43,200 steps, you'd do something like the following. .PP .Vb 3 \& # Define adult step unit. \& $geo\->reg_unit( 43200, \*(Aqadult step\*(Aq ); \& # This can be read as "It takes 43,200 adult_steps to walk the radius of the earth". .Ve .PP Now, if you also wanted to do distances in baby steps you might think \*(L"well, now I gotta get a baby to walk to the center of the earth\*(R". But, you don't have to! If you do some research you'll find (no research was actually conducted) that there are, on average, 4.7 baby steps in each adult step. .PP .Vb 3 \& # Define baby step unit. \& $geo\->reg_unit( 4.7, \*(Aqbaby step\*(Aq => \*(Aqadult step\*(Aq ); \& # This can be read as "4.7 baby steps is the same as one adult step". .Ve .PP And if we were doing this in reverse and already had the baby step unit but not the adult step, you would still use the exact same syntax as above. .SH "FORMULAS" .IX Header "FORMULAS" .IP "\(bu" 4 \&\f(CW\*(C`alt\*(C'\fR \- See GIS::Distance::ALT. .IP "\(bu" 4 \&\f(CW\*(C`cos\*(C'\fR \- See GIS::Distance::Cosine. .IP "\(bu" 4 \&\f(CW\*(C`gcd\*(C'\fR \- See GIS::Distance::GreatCircle. .IP "\(bu" 4 \&\f(CW\*(C`hsin\*(C'\fR \- See GIS::Distance::Haversine. .IP "\(bu" 4 \&\f(CW\*(C`mt\*(C'\fR \- See GIS::Distance::MathTrig. .IP "\(bu" 4 \&\f(CW\*(C`null\*(C'\fR \- See GIS::Distance::Null. .IP "\(bu" 4 \&\f(CW\*(C`polar\*(C'\fR \- See GIS::Distance::Polar. .IP "\(bu" 4 \&\f(CW\*(C`tv\*(C'\fR \- See GIS::Distance::Vincenty. .SH "LATITUDE AND LONGITUDE" .IX Header "LATITUDE AND LONGITUDE" When a function needs a longitude and latitude, they must always be in decimal degree format. Here is some sample code for converting from other formats to decimal: .PP .Vb 2 \& # DMS to Decimal \& my $decimal = $degrees + ($minutes/60) + ($seconds/3600); \& \& # Precision Six Integer to Decimal \& my $decimal = $integer * .000001; .Ve .PP If you want to convert from decimal radians to degrees you can use Math::Trig's rad2deg function. .SH "UNITS" .IX Header "UNITS" The \*(L"distance\*(R" and \*(L"closest\*(R" functions take an argument containing the name of a registered unit, such as \f(CW\*(C`kilometer\*(C'\fR, to do the computation of distance with. By default a useful set of units are registered and custom units may be added with \&\*(L"reg_unit\*(R". The default set of units are: .PP .Vb 3 \& kilometer, kilometre, meter, metre, centimeter, centimetre, millimeter, \& millimetre, yard, foot, inch, light second, mile, nautical mile, \& poppy seed, barleycorn, rod, pole, perch, chain, furlong, league, fathom .Ve .PP The \*(L"no_units\*(R" argument may be set to disable the default units from being registered. .SH "STABILITY" .IX Header "STABILITY" The interface to Geo::Distance is fairly stable nowadays. If this changes it will be noted here. .IP "\(bu" 4 \&\f(CW0.21\fR \- All distance calculations are now handled by GIS::Distance. .IP "\(bu" 4 \&\f(CW0.10\fR \- The \fBclosest()\fR method has a changed argument syntax and no longer supports array searches. .IP "\(bu" 4 \&\f(CW0.09\fR \- Changed the behavior of the reg_unit function. .IP "\(bu" 4 \&\f(CW0.07\fR \- \s-1OO\s0 only, and other changes all over. .SH "SUPPORT" .IX Header "SUPPORT" Please submit bugs and feature requests to the Geo-Distance GitHub issue tracker: .PP .PP Note that, due to the \*(L"\s-1DEPRECATED\*(R"\s0 nature of this distribution, new features and such may be denied. .SH "AUTHORS" .IX Header "AUTHORS" .Vb 5 \& Aran Clary Deltac \& gray \& Anirvan Chatterjee \& \*(Aevar Arnfjo\*:r\*(d- Bjarmason \& Niko Tyni .Ve .SH "LICENSE" .IX Header "LICENSE" This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.