.\" 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
.\" ========================================================================
.\"
.IX Title "GPS::Point 3pm"
.TH GPS::Point 3pm "2022-11-19" "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"
GPS::Point \- Provides an object interface for a GPS point.
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 10
\&  use GPS::Point;
\&  my $obj=GPS::Point\->newGPSD($GPSD_O_line);#e.g. GPSD,O=....
\&  my $obj=GPS::Point\->new(
\&         time        => $time,    #float seconds from the unix epoch
\&         lat         => $lat,     #signed degrees
\&         lon         => $lon,     #signed degrees
\&         alt         => $hae,     #meters above the WGS\-84 ellipsoid
\&         speed       => $speed,   #meters/second (over ground)
\&         heading     => $heading, #degrees clockwise from North
\&         climb       => $climb,   #meters/second
\&         etime       => $etime,   #float seconds
\&         ehorizontal => $ehz,     #float meters
\&         evertical   => $evert,   #float meters
\&         espeed      => $espeed,  #meters/second
\&         eheading    => $ehead,   #degrees
\&         eclimb      => $eclimb,  #meters/second
\&         mode        => $mode,    #GPS mode [?=>undef,None=>1,2D=>2,3D=>3]
\&         tag         => $tag,     #Name of the GPS message for data
\&       );
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This is a re-write of Net::GPSD::Point with the goal of being more re-usable.
.PP
GPS::Point \- Provides an object interface for a \s-1GPS\s0 fix (e.g. Position, Velocity and Time).
.PP
.Vb 1
\&  Note: Please use Geo::Point, if you want 2D or projection support.
.Ve
.SH "USAGE"
.IX Header "USAGE"
.Vb 5
\&  print scalar($point\->latlon), "\en";       #latlon in scalar context
\&  my ($x,$y,$z)=$point\->ecef;               #if Geo::ECEF is available
\&  my $GeoPointObject=$point\->GeoPoint;      #if Geo::Point is available
\&  my @distance=$point\->distance($point2);   #if Geo::Inverse is available
\&  my $distance=$point\->distance($point2);   #if Geo::Inverse\->VERSION >=0.05
.Ve
.SH "USAGE TODO"
.IX Header "USAGE TODO"
.Vb 1
\&  my $obj=GPS::Point\->newNMEA($NMEA_lines); #e.g. GGA+GSA+RMC
.Ve
.SH "CONSTRUCTORS"
.IX Header "CONSTRUCTORS"
.SS "new"
.IX Subsection "new"
.Vb 1
\&  my $obj = GPS::Point\->new();
.Ve
.SS "newGPSD"
.IX Subsection "newGPSD"
.Vb 1
\&  my $obj=GPS::Point\->newGPSD($GPSD_O_line);#e.g. GPSD,O=....
.Ve
.PP
Note: \s-1GPSD\s0 protocol 2 is soon to be defunct.
.SS "newMulti"
.IX Subsection "newMulti"
Constructs a GPS::Point from a Multitude of arguments. Arguments can be a GPS::Point, Geo::Point, {lat=>$lat,lon=>$lon} (can be blessed), [$lat, \f(CW$lon\fR] (can be blessed) or a ($lat, \f(CW$lon\fR) pair.
.PP
.Vb 6
\&  my $point=GPS::Point\->newMulti( $lat, $lon, $alt ); #supports lat, lon and alt
\&  my $point=GPS::Point\->newMulti([$lat, $lon, $alt]); #supports lat, lon and alt
\&  my $point=GPS::Point\->newMulti({lat=>$lat, lon=>$lon, ...});
\&  my $point=GPS::Point\->newMulti(GPS::Point\->new(lat=>$lat, lon=>$lon));
\&  my $point=GPS::Point\->newMulti(Geo::Point\->new(lat=>$lat, long=>$lon, proj=>\*(Aqwgs84\*(Aq));
\&  my $point=GPS::Point\->newMulti({latitude=>$lat, longtude=>$lon});
.Ve
.PP
Note: Hash reference context supports the following keys lat, lon, alt, latitude, longitude, long, altitude, elevation, hae, elev.
.PP
Note: Units are always decimal degrees for latitude and longitude and meters above the \s-1WGS\-84\s0 ellipsoid for altitude.
.SS "initialize, initializeGPSD, initializeMulti"
.IX Subsection "initialize, initializeGPSD, initializeMulti"
.SH "METHODS (Base)"
.IX Header "METHODS (Base)"
.SS "time"
.IX Subsection "time"
Sets or returns seconds since the Unix epoch, \s-1UTC\s0 (float, seconds)
.PP
.Vb 1
\&  print $obj\->time, "\en";
.Ve
.SS "lat, latitude"
.IX Subsection "lat, latitude"
Sets or returns Latitude (float, degrees)
.PP
.Vb 1
\&  print $obj\->lat, "\en";
.Ve
.SS "lon, long, longitude"
.IX Subsection "lon, long, longitude"
Sets or returns Longitude (float, degrees)
.PP
.Vb 1
\&  print $obj\->lon, "\en";
.Ve
.SS "alt, altitude, hae, elevation"
.IX Subsection "alt, altitude, hae, elevation"
Sets or returns Altitude (float, meters)
.PP
.Vb 1
\&  print $obj\->alt, "\en";
.Ve
.SS "speed"
.IX Subsection "speed"
Sets or returns speed (float, meters/sec)
.PP
.Vb 1
\&  print $obj\->speed, "\en";
.Ve
.SS "heading, bearing"
.IX Subsection "heading, bearing"
Sets or returns heading (float, degrees)
.PP
.Vb 1
\&  print $obj\->heading, "\en";
.Ve
.SS "climb"
.IX Subsection "climb"
Sets or returns vertical velocity (float, meters/sec)
.PP
.Vb 1
\&  print $obj\->climb, "\en";
.Ve
.SS "etime"
.IX Subsection "etime"
Sets or returns estimated timestamp error (float, seconds, 95% confidence)
.PP
.Vb 1
\&  print $obj\->etime, "\en";
.Ve
.SS "ehorizontal"
.IX Subsection "ehorizontal"
Sets or returns horizontal error estimate (float, meters)
.PP
.Vb 1
\&  print $obj\->ehorizontal, "\en";
.Ve
.SS "evertical"
.IX Subsection "evertical"
Sets or returns vertical error estimate (float, meters)
.PP
.Vb 1
\&  print $obj\->evertical, "\en";
.Ve
.SS "espeed"
.IX Subsection "espeed"
Sets or returns error estimate for speed (float, meters/sec, 95% confidence)
.PP
.Vb 1
\&  print $obj\->espeed, "\en";
.Ve
.SS "eheading"
.IX Subsection "eheading"
Sets or returns error estimate for course (float, degrees, 95% confidence)
.PP
.Vb 1
\&  print $obj\->eheading, "\en";
.Ve
.SS "eclimb"
.IX Subsection "eclimb"
Sets or returns Estimated error for climb/sink (float, meters/sec, 95% confidence)
.PP
.Vb 1
\&  print $obj\->eclimb, "\en";
.Ve
.SS "mode"
.IX Subsection "mode"
Sets or returns the \s-1NMEA\s0 mode (integer; undef=>no mode value yet seen, 1=>no fix, 2=>2D, 3=>3D)
.PP
.Vb 1
\&  print $obj\->mode, "\en";
.Ve
.SS "tag"
.IX Subsection "tag"
Sets or returns a tag identifying the last sentence received. For \s-1NMEA\s0 devices this is just the \s-1NMEA\s0 sentence name; the talker-ID portion may be useful for distinguishing among results produced by different \s-1NMEA\s0 talkers in the same wire. (string)
.PP
.Vb 1
\&  print $obj\->tag, "\en";
.Ve
.SH "METHODS (Value Added)"
.IX Header "METHODS (Value Added)"
.SS "fix"
.IX Subsection "fix"
Returns either 1 or 0 based upon if the \s-1GPS\s0 point is from a valid fix or not.
.PP
.Vb 1
\&  print $obj\->fix, "\en";
.Ve
.PP
At a minimum this method requires mode to be set.
.SS "datetime"
.IX Subsection "datetime"
Returns a DateTime object from time
.PP
.Vb 1
\&  my $dt=$point\->datetime;
.Ve
.PP
At a minimum this method requires time to be set.
.SS "latlon, latlong"
.IX Subsection "latlon, latlong"
Returns Latitude, Longitude as an array in array context and as a space joined string in scalar context
.PP
.Vb 2
\&  my @latlon=$point\->latlon;
\&  my $latlon=$point\->latlon;
.Ve
.PP
At a minimum this method requires lat and lon to be set.
.SS "setAltitude"
.IX Subsection "setAltitude"
Sets altitude from \s-1USGS\s0 web service and then returns the GPS::Point object.  This method is a wrapper around Geo::WebService::Elevation::USGS.
.PP
.Vb 3
\&  my $point=GPS::Point\->new(lat=>$lat, lon=>$lon)\->setAltitude;
\&  $point\->setAltitude;
\&  my $alt=$point\->alt;
.Ve
.PP
At a minimum this method requires lat and lon to be set and alt to be undef.
.SS "ecef"
.IX Subsection "ecef"
Returns \s-1ECEF\s0 coordinates. This method is a wrapper around Geo::ECEF.
.PP
.Vb 3
\&  my ($x,$y,$z) = $point\->ecef;
\&  my @xyz       = $point\->ecef;
\&  my $xyz_aref  = $point\->ecef; #if Geo::ECEF\->VERSION >= 0.08
.Ve
.PP
At a minimum this method requires lat and lon to be set. (alt of 0 is assumed by Geo::ECEF\->ecef).
.SS "GeoPoint"
.IX Subsection "GeoPoint"
Returns a Geo::Point Object in the \s-1WGS\-84\s0 projection.
.PP
.Vb 1
\&  my $GeoPointObject = $point\->GeoPoint;
.Ve
.PP
At a minimum this method requires lat and lon to be set.
.SS "distance"
.IX Subsection "distance"
Returns distance in meters between the object point and the argument point. The argument can be any valid argument of newMulti constructor.  This method is a wrapper around Geo::Inverse.
.PP
.Vb 2
\&  my ($faz, $baz, $dist) = $point\->distance($pt2); #Array context
\&  my $dist = $point\->distance($lat, $lon);  #if Geo::Inverse\->VERSION >=0.05
.Ve
.PP
At a minimum this method requires lat and lon to be set.
.SS "track"
.IX Subsection "track"
Returns a point object at the predicted location in time seconds assuming constant velocity. Using Geo::Forward calculation.
.PP
.Vb 2
\&  my $new_point=$point\->track($seconds); #default $point\->heading
\&  my $new_point=$point\->track($seconds => $heading);
.Ve
.PP
At a minimum this method requires lat and lon to be set. It might be very useful to have speed, heading and time set although they all default to zero.
.SS "forward"
.IX Subsection "forward"
Returns a point object at the distance and heading using Geo::Forward calculations.
.PP
.Vb 2
\&  my $point=$point\->forward($dist);             #default $point\->heading
\&  my $point=$point\->forward($dist => $heading); #meters => degrees
.Ve
.PP
At a minimum this method requires lat and lon to be set. It might be useful to have heading set although the default is zero.
.SS "buffer"
.IX Subsection "buffer"
Returns a list of GPS::Point objects equidistant from the current object location.
.PP
.Vb 2
\&  my @buffer=$point\->buffer($radius_meters, $sections); #returns (GPS::Point, GPS::Point, ...)
\&  my $buffer=$point\->buffer($radius_meters, $sections); #returns [GPS::Point, GPS::Point, ...]
.Ve
.SH "BUGS"
.IX Header "BUGS"
Please log on \s-1RT\s0 and send email to GPSD-DEV or GEO-PERL email lists.
.SH "SUPPORT"
.IX Header "SUPPORT"
DavisNetworks.com supports all Perl applications including this package.
.SH "AUTHOR"
.IX Header "AUTHOR"
.Vb 5
\&  Michael R. Davis
\&  CPAN ID: MRDVT
\&  DavisNetworks.com
\&  account=>perl,tld=>com,domain=>michaelrdavis
\&  http://www.davisnetworks.com/
.Ve
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
This program is free software licensed under the...
.PP
.Vb 1
\&  The BSD License
.Ve
.PP
The full text of the license can be found in the \s-1LICENSE\s0 file included with this module.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
Geo::Point, Net::GPSD, Net::GPSD::Point, Geo::ECEF, Geo::Functions, Geo::Forward, Geo::Inverse, Geo::Distance, Geo::Ellipsoids, Geo::WebService::Elevation::USGS, DateTime