/ 
GPS-Point-0.20
River stage one • 5 direct dependents • 6 total dependents
/ GPS::Point

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