NAME

       Geo::Gpx::Point - Class to store and edit GPX Waypoints

SYNOPSIS

         use Geo::Gpx::Point;

DESCRIPTION

       Geo::Gpx::Point provides a data structure for GPX points and provides accessor methods to read and edit
       point data.

   Constructor Method
       new( lat => $lat, lon => $lon [, ele => $ele, desc => $desc, X ] )
           Create  and  return  a  new  point  as per the fields provided, which can be any of "lat lon ele time
           magvar geoidheight name cmt desc src link sym type fix sat hdop vdop pdop ageofdgpsdata dgpsid". Most
           expect numberial values except: "name", "cmt", "desc", "src", "sym", "type", "fix" that  can  contain
           strings.

           "lat" and "lon" are required, all others keys are optional.

             %fields = ( lat => 47.0871, lon => 70.9318, ele => 808.000, name => 'MSA', desc => 'A nice view of the River at the top');
             $pt = Geo::Gpx::Point->new( %fields );

           The "link" field is expected to be structured as:

             link => { href => 'http://hexten.net/', text => 'Hexten', type => 'Blah' },

       flex_coordinates( $lat, $lon, %fields )
           Takes  latitude  and  longitude decimal values or strings and returns a "Geo::Gpx::Point" object. The
           latitude should always appear before the longitude and both can be in formatted  form  (i.e  Degrees,
           Minutes,  Seconds  or  "dms") and the constructor will attempt to convert them to decimals. Any other
           %fields are optional.

             $pt = Geo::Gpx::Point->flex_coordinates( '47.0871', '-70.9318', desc => 'Mont Ste-Anne' );

           If a string reference is passed as the first argument (instead of $lat  and  $lon),  the  constructor
           will  attempt  to  parse  it  as  coordinates  (decimal-form  only). For instance you can simply call
           "flex_coordinates( '47.0871 -70.9318' )" with or without a comma along with optional fields.

             $str_ref = \'47.0871 -70.9318';
             $pt = Geo::Gpx::Point->flex_coordinates($str_ref, desc => 'Mont Ste-Anne' );

       clone()
           Returns a deep copy of the "Geo::Gpx::Point".

             $clone = $ggp->clone;

   AUTOLOAD Methods
       field( $value )
           Methods with respect to fields of the object can be autoloaded.

           Possible fields consist of those listed and accepted by "new()", specifically: lat, lon,  ele,  time,
           magvar,   geoidheight,  name,  cmt,  desc,  src,  link,  sym,  type,  fix,  sat,  hdop,  vdop,  pdop,
           ageofdgpsdata, and dgpsid.

           Some fields may contain a value of 0. It is safer to check if a field is defined  with  "if  (defined
           $point->ele)" rather than "if ($point->ele)".

           Caution  should  be  used  if  setting  a  $value  as  no checks are performed to ensure the value is
           appropriate or in the proper format.

   Object Methods
       distance_to( $pt or lat => $lat, lon => $lon, [ %options ] )
           Returns the distance in meters from the "Geo::Gpx::Point" $pt or from  the  coordinates  provided  by
           $lat and $lon. The distance is calculated as the straight-line distance, ignoring any topography. $pt
           must be the first argument if specified.

           %options may be any of the following key/value pairs (all optional):

               "dec  =>  $decimals":  how  many digits to return after the decimal point. Defaults to 6 but this
           will change to 1 or 2 in the future.
               "km  => boole":     scale the return value to kilometers rather than meters (default is false).
               "rad => $radius":   the earth's radius in kilometers (see below).

           $radius should rarely be specified unless the user knows what they are  doing.  The  default  is  the
           global  average of 6371 kilometers and any value outside the 6357 to 6378 range will be ignored. This
           implies that a given value would affect the returned distance by at  most  0.16  percent  versus  the
           global average.

       to_geocalc()
           Returns a point as a Geo::Calc object. (Requires that the Geo::Calc module be installed.)

       to_tcx()
           Returns  a point as a basic Geo::TCX::Trackpoint object, i.e. a point with only Position information.
           (Requires that the Geo::TCX module be installed.)

       time_datetime ()
           Return a DateTime object corresponding to the time of the point. The "time_zone" of the  object  will
           be 'UTC'. Specify "time_zone => $tz" to set a different one.

       summ()
           For debugging purposes mostly. Summarizes the fields of point by printing to screen. Returns nothing.

       as_string()
           Returns a string with the coordinates e.g. "lat="47.0871" lon="-70.9318"".

   Overloaded Methods
       "as_string()" is called when using a "Geo::Gpx::Point" instance as a string.

EXAMPLES

       Coming soon.

AUTHOR

       Patrick Joly "<patjol@cpan.org>".

VERSION

       1.10

SEE ALSO

       perl(1).

perl v5.36.0                                       2023-11-25                               Geo::Gpx::Point(3pm)