.\" 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::Gpx::Point 3pm"
.TH Geo::Gpx::Point 3pm "2023-11-25" "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::Gpx::Point \- Class to store and edit GPX Waypoints
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&  use Geo::Gpx::Point;
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
Geo::Gpx::Point provides a data structure for \s-1GPX\s0 points and provides accessor methods to read and edit point data.
.SS "Constructor Method"
.IX Subsection "Constructor Method"
.ie n .IP "new( lat => $lat, lon => $lon [, ele => $ele, desc => $desc, X ] )" 4
.el .IP "new( lat => \f(CW$lat\fR, lon => \f(CW$lon\fR [, ele => \f(CW$ele\fR, desc => \f(CW$desc\fR, X ] )" 4
.IX Item "new( lat => $lat, lon => $lon [, ele => $ele, desc => $desc, X ] )"
Create and return a new point as per the fields provided, which can be any of \f(CW\*(C`lat lon ele time magvar geoidheight name cmt desc src link sym type fix sat hdop vdop pdop ageofdgpsdata dgpsid\*(C'\fR. Most expect numberial values except: \f(CW\*(C`name\*(C'\fR, \f(CW\*(C`cmt\*(C'\fR, \f(CW\*(C`desc\*(C'\fR, \f(CW\*(C`src\*(C'\fR, \f(CW\*(C`sym\*(C'\fR, \f(CW\*(C`type\*(C'\fR, \f(CW\*(C`fix\*(C'\fR that can contain strings.
.Sp
\&\f(CW\*(C`lat\*(C'\fR and \f(CW\*(C`lon\*(C'\fR are required, all others keys are optional.
.Sp
.Vb 2
\&  %fields = ( lat => 47.0871, lon => 70.9318, ele => 808.000, name => \*(AqMSA\*(Aq, desc => \*(AqA nice view of the River at the top\*(Aq);
\&  $pt = Geo::Gpx::Point\->new( %fields );
.Ve
.Sp
The \f(CW\*(C`link\*(C'\fR field is expected to be structured as:
.Sp
.Vb 1
\&  link => { href => \*(Aqhttp://hexten.net/\*(Aq, text => \*(AqHexten\*(Aq, type => \*(AqBlah\*(Aq },
.Ve
.ie n .IP "flex_coordinates( $lat, $lon, %fields )" 4
.el .IP "flex_coordinates( \f(CW$lat\fR, \f(CW$lon\fR, \f(CW%fields\fR )" 4
.IX Item "flex_coordinates( $lat, $lon, %fields )"
Takes latitude and longitude decimal values or strings and returns a \f(CW\*(C`Geo::Gpx::Point\*(C'\fR object. The latitude should always appear before the longitude and both can be in formatted form (i.e Degrees, Minutes, Seconds or \*(L"dms\*(R") and the constructor will attempt to convert them to decimals. Any other \fI\f(CI%fields\fI\fR are optional.
.Sp
.Vb 1
\&  $pt = Geo::Gpx::Point\->flex_coordinates( \*(Aq47.0871\*(Aq, \*(Aq\-70.9318\*(Aq, desc => \*(AqMont Ste\-Anne\*(Aq );
.Ve
.Sp
If a string reference is passed as the first argument (instead of \fI\f(CI$lat\fI\fR and \fI\f(CI$lon\fI\fR), the constructor will attempt to parse it as coordinates (decimal-form only). For instance you can simply call \f(CW\*(C`flex_coordinates( \*(Aq47.0871 \-70.9318\*(Aq )\*(C'\fR with or without a comma along with optional fields.
.Sp
.Vb 2
\&  $str_ref = \e\*(Aq47.0871 \-70.9318\*(Aq;
\&  $pt = Geo::Gpx::Point\->flex_coordinates($str_ref, desc => \*(AqMont Ste\-Anne\*(Aq );
.Ve
.IP "\fBclone()\fR" 4
.IX Item "clone()"
Returns a deep copy of the \f(CW\*(C`Geo::Gpx::Point\*(C'\fR.
.Sp
.Vb 1
\&  $clone = $ggp\->clone;
.Ve
.SS "\s-1AUTOLOAD\s0 Methods"
.IX Subsection "AUTOLOAD Methods"
.ie n .IP "\fIfield\fR( $value )" 4
.el .IP "\fIfield\fR( \f(CW$value\fR )" 4
.IX Item "field( $value )"
Methods with respect to fields of the object can be autoloaded.
.Sp
Possible fields consist of those listed and accepted by \f(CW\*(C`new()\*(C'\fR, specifically:
lat, lon, ele, time, magvar, geoidheight, name, cmt, desc, src, link, sym, type, fix, sat, hdop, vdop, pdop, ageofdgpsdata, and dgpsid.
.Sp
Some fields may contain a value of 0. It is safer to check if a field is defined with \f(CW\*(C`if (defined $point\->ele)\*(C'\fR rather than \f(CW\*(C`if ($point\->ele)\*(C'\fR.
.Sp
Caution should be used if setting a \fI\f(CI$value\fI\fR as no checks are performed to ensure the value is appropriate or in the proper format.
.SS "Object Methods"
.IX Subsection "Object Methods"
.ie n .IP "distance_to( $pt or lat => $lat, lon => $lon, [ %options ] )" 4
.el .IP "distance_to( \f(CW$pt\fR or lat => \f(CW$lat\fR, lon => \f(CW$lon\fR, [ \f(CW%options\fR ] )" 4
.IX Item "distance_to( $pt or lat => $lat, lon => $lon, [ %options ] )"
Returns the distance in meters from the \f(CW\*(C`Geo::Gpx::Point\*(C'\fR \fI\f(CI$pt\fI\fR or from the coordinates provided by \fI\f(CI$lat\fI\fR and \fI\f(CI$lon\fI\fR. The distance is calculated as the straight-line distance, ignoring any topography. \fI\f(CI$pt\fI\fR must be the first argument if specified.
.Sp
\&\fI\f(CI%options\fI\fR may be any of the following \fIkey/value\fR pairs (all optional):
.Sp
    \f(CW\*(C`dec => \f(CI$decimals\f(CW\*(C'\fR: how many digits to return after the decimal point. Defaults to 6 but this will change to 1 or 2 in the future.
    \f(CW\*(C`km  => \f(CIboole\f(CW\*(C'\fR:     scale the return value to kilometers rather than meters (default is false).
    \f(CW\*(C`rad => \f(CI$radius\f(CW\*(C'\fR:   the earth's radius in kilometers (see below).
.Sp
\&\fI\f(CI$radius\fI\fR should rarely be specified unless the user knows what they are doing. The default is the global average of 6371 kilometers and any value outside the 6357 to 6378 range will be ignored. This implies that a given value would affect the returned distance by at most 0.16 percent versus the global average.
.IP "\fBto_geocalc()\fR" 4
.IX Item "to_geocalc()"
Returns a point as a Geo::Calc object. (Requires that the Geo::Calc module be installed.)
.IP "\fBto_tcx()\fR" 4
.IX Item "to_tcx()"
Returns a point as a basic Geo::TCX::Trackpoint object, i.e. a point with only Position information. (Requires that the Geo::TCX module be installed.)
.IP "time_datetime ()" 4
.IX Item "time_datetime ()"
Return a DateTime object corresponding to the time of the point. The \f(CW\*(C`time_zone\*(C'\fR of the object will be \f(CW\*(AqUTC\*(Aq\fR. Specify \f(CW\*(C`time_zone => $tz\*(C'\fR to set a different one.
.IP "\fBsumm()\fR" 4
.IX Item "summ()"
For debugging purposes mostly. Summarizes the fields of point by printing to screen. Returns nothing.
.IP "\fBas_string()\fR" 4
.IX Item "as_string()"
Returns a string with the coordinates e.g. \f(CW\*(C`lat="47.0871" lon="\-70.9318"\*(C'\fR.
.SS "Overloaded Methods"
.IX Subsection "Overloaded Methods"
\&\f(CW\*(C`as_string()\*(C'\fR is called when using a \f(CW\*(C`Geo::Gpx::Point\*(C'\fR instance as a string.
.SH "EXAMPLES"
.IX Header "EXAMPLES"
Coming soon.
.SH "AUTHOR"
.IX Header "AUTHOR"
Patrick Joly \f(CW\*(C`<patjol@cpan.org>\*(C'\fR.
.SH "VERSION"
.IX Header "VERSION"
1.10
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fBperl\fR\|(1).