GPS::Point(3pm)

✨ GPS::Point ✨

okay bestie, so this is GPS::Point, a page from the User Contributed Perl Documentation collection, and it's literally the moment your Perl code gets to have a whole object for a GPS point. it's giving "i have coordinates and feelings." 💖

---

💅 NAME 💅

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

like. an object. for a GPS point. slay. ✨

---

🌸 SYNOPSIS 🌸

here's the vibe, no notes:

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

look at all those named args. she's organized. she's got her life together. 🎀

---

🦋 DESCRIPTION 🦋

so this is a re-write of Net::GPSD::Point, and the whole goal was to be more re-usable. iconic behavior honestly.

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.

like if you need 2D or projection stuff, go talk to Geo::Point, she's the one for that. 💜

---

🌈 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

see how context changes everything? she's versatile. she contains multitudes. ✨

---

🙈 USAGE TODO 🙈

not done yet, bestie, but we're manifesting:

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

it's coming. we believe. 🫶

---

👑 CONSTRUCTORS 👑

⭐ new

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

just. make one. that's it. go off. 💅

⭐ newGPSD

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

Note: GPSD protocol 2 is soon to be defunct.

so like. she still works, but GPSD protocol 2 is on her way out, so don't get too attached. 😭

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

she accepts everything. she's flexible like that. main character energy fr fr.

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.

so yeah, lat/lon are decimal degrees always, and altitude is meters above the WGS-84 ellipsoid always. no cap. 💖

⭐ initialize, initializeGPSD, initializeMulti

that's them. that's the whole line. the trio. 💫

---

🌸 METHODS (Base) 🌸

these are the basic setters/getters, bestie. call with an arg to set, call with nothing to get. simple as. ✨

• 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) 🔥

okay this is where it gets good. the extras. the little treats. 🍓

💜 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.

like, she literally cannot tell you if it's a fix without mode. set your mode, bestie. 😤

💜 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.

context girlies know. 💅

💜 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.

she calls the USGS. she brings back your altitude. she returns herself so you can keep chaining. selfless. iconic. ✨

💜 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.

she's predicting the future. main character energy fr fr. 🔮

💜 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, ...]

a whole little circle of points around her. it's giving friendship bracelet. 🎀

---

💀 BUGS 💀

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

found a bug? tell the group chat. don't suffer in silence. 🙈

---

🫶 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/

thank you Michael, we appreciate you, king. 👑

---

📜 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

---

and that's the whole page, bestie!! 🦋 this doc is from perl v5.36.0, dated 2022-11-19 — so she's been serving coordinates since back in the day and she's still eating. no cap. periodt. 💅✨