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