Provided by: libgps-point-perl_0.20-5_all bug

NAME

       GPS::Point - Provides an object interface for a GPS point.

SYNOPSIS

         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
              );

DESCRIPTION

       This is a re-write of Net::GPSD::Point with the goal of being more re-usable.

       GPS::Point - Provides an object interface for a GPS fix (e.g. Position, Velocity and
       Time).

         Note: Please use Geo::Point, if you want 2D or projection support.

USAGE

         print scalar($point->latlon), "\n";       #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

USAGE TODO

         my $obj=GPS::Point->newNMEA($NMEA_lines); #e.g. GGA+GSA+RMC

CONSTRUCTORS

   new
         my $obj = GPS::Point->new();

   newGPSD
         my $obj=GPS::Point->newGPSD($GPSD_O_line);#e.g. GPSD,O=....

       Note: GPSD protocol 2 is soon to be defunct.

   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, $lon] (can be blessed) or a
       ($lat, $lon) pair.

         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=>'wgs84'));
         my $point=GPS::Point->newMulti({latitude=>$lat, longtude=>$lon});

       Note: Hash reference context supports the following keys lat, lon, alt, latitude,
       longitude, long, altitude, elevation, hae, elev.

       Note: Units are always decimal degrees for latitude and longitude and meters above the
       WGS-84 ellipsoid for altitude.

   initialize, initializeGPSD, initializeMulti

METHODS (Base)

   time
       Sets or returns seconds since the Unix epoch, UTC (float, seconds)

         print $obj->time, "\n";

   lat, latitude
       Sets or returns Latitude (float, degrees)

         print $obj->lat, "\n";

   lon, long, longitude
       Sets or returns Longitude (float, degrees)

         print $obj->lon, "\n";

   alt, altitude, hae, elevation
       Sets or returns Altitude (float, meters)

         print $obj->alt, "\n";

   speed
       Sets or returns speed (float, meters/sec)

         print $obj->speed, "\n";

   heading, bearing
       Sets or returns heading (float, degrees)

         print $obj->heading, "\n";

   climb
       Sets or returns vertical velocity (float, meters/sec)

         print $obj->climb, "\n";

   etime
       Sets or returns estimated timestamp error (float, seconds, 95% confidence)

         print $obj->etime, "\n";

   ehorizontal
       Sets or returns horizontal error estimate (float, meters)

         print $obj->ehorizontal, "\n";

   evertical
       Sets or returns vertical error estimate (float, meters)

         print $obj->evertical, "\n";

   espeed
       Sets or returns error estimate for speed (float, meters/sec, 95% confidence)

         print $obj->espeed, "\n";

   eheading
       Sets or returns error estimate for course (float, degrees, 95% confidence)

         print $obj->eheading, "\n";

   eclimb
       Sets or returns Estimated error for climb/sink (float, meters/sec, 95% confidence)

         print $obj->eclimb, "\n";

   mode
       Sets or returns the NMEA mode (integer; undef=>no mode value yet seen, 1=>no fix, 2=>2D,
       3=>3D)

         print $obj->mode, "\n";

   tag
       Sets or returns a tag identifying the last sentence received. For NMEA devices this is
       just the NMEA sentence name; the talker-ID portion may be useful for distinguishing among
       results produced by different NMEA talkers in the same wire. (string)

         print $obj->tag, "\n";

METHODS (Value Added)

   fix
       Returns either 1 or 0 based upon if the GPS point is from a valid fix or not.

         print $obj->fix, "\n";

       At a minimum this method requires mode to be set.

   datetime
       Returns a DateTime object from time

         my $dt=$point->datetime;

       At a minimum this method requires time to be set.

   latlon, latlong
       Returns Latitude, Longitude as an array in array context and as a space joined string in
       scalar context

         my @latlon=$point->latlon;
         my $latlon=$point->latlon;

       At a minimum this method requires lat and lon to be set.

   setAltitude
       Sets altitude from USGS web service and then returns the GPS::Point object.  This method
       is a wrapper around Geo::WebService::Elevation::USGS.

         my $point=GPS::Point->new(lat=>$lat, lon=>$lon)->setAltitude;
         $point->setAltitude;
         my $alt=$point->alt;

       At a minimum this method requires lat and lon to be set and alt to be undef.

   ecef
       Returns ECEF coordinates. This method is a wrapper around Geo::ECEF.

         my ($x,$y,$z) = $point->ecef;
         my @xyz       = $point->ecef;
         my $xyz_aref  = $point->ecef; #if Geo::ECEF->VERSION >= 0.08

       At a minimum this method requires lat and lon to be set. (alt of 0 is assumed by
       Geo::ECEF->ecef).

   GeoPoint
       Returns a Geo::Point Object in the WGS-84 projection.

         my $GeoPointObject = $point->GeoPoint;

       At a minimum this method requires lat and lon to be set.

   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.

         my ($faz, $baz, $dist) = $point->distance($pt2); #Array context
         my $dist = $point->distance($lat, $lon);  #if Geo::Inverse->VERSION >=0.05

       At a minimum this method requires lat and lon to be set.

   track
       Returns a point object at the predicted location in time seconds assuming constant
       velocity. Using Geo::Forward calculation.

         my $new_point=$point->track($seconds); #default $point->heading
         my $new_point=$point->track($seconds => $heading);

       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.

   forward
       Returns a point object at the distance and heading using Geo::Forward calculations.

         my $point=$point->forward($dist);             #default $point->heading
         my $point=$point->forward($dist => $heading); #meters => degrees

       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.

   buffer
       Returns a list of GPS::Point objects equidistant from the current object location.

         my @buffer=$point->buffer($radius_meters, $sections); #returns (GPS::Point, GPS::Point, ...)
         my $buffer=$point->buffer($radius_meters, $sections); #returns [GPS::Point, GPS::Point, ...]

BUGS

       Please log on RT and send email to GPSD-DEV or GEO-PERL email lists.

SUPPORT

       DavisNetworks.com supports all Perl applications including this package.

AUTHOR

         Michael R. Davis
         CPAN ID: MRDVT
         DavisNetworks.com
         account=>perl,tld=>com,domain=>michaelrdavis
         http://www.davisnetworks.com/

COPYRIGHT

       This program is free software licensed under the...

         The BSD License

       The full text of the license can be found in the LICENSE file included with this module.

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