--- name: "GPS::Point" section: "3pm" platform: "linux" package: "libgps-point-perl" version: "0.20-5" release: "Debian 13 (Trixie)" platforms: ["linux"] url: "https://new.carta.tech/GPS::Point" --- # GPS::Point(3pm) Provides an object interface for a 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